+ {/* Popular tabs */}
+
```
This function is important because it defines how Composio Tutorial: Production Tool and Authentication Infrastructure for AI Agents implements the patterns covered in this chapter.
@@ -220,11 +218,11 @@ This function is important because it defines how Composio Tutorial: Production
```mermaid
flowchart TD
- A[Feedback]
- B[FeedbackProps]
- C[fetchToolkits]
- D[fetchToolkitChangelog]
- E[fetchToolsForToolkit]
+ A[ClientIcon]
+ B[PopularTab]
+ C[ConnectFlow]
+ D[handleClick]
+ E[ConnectClientOption]
A --> B
B --> C
C --> D
diff --git a/tutorials/composio-tutorial/03-provider-integrations-and-framework-mapping.md b/tutorials/composio-tutorial/03-provider-integrations-and-framework-mapping.md
index 2081052c..b7768af4 100644
--- a/tutorials/composio-tutorial/03-provider-integrations-and-framework-mapping.md
+++ b/tutorials/composio-tutorial/03-provider-integrations-and-framework-mapping.md
@@ -48,183 +48,182 @@ You now have a framework-aware way to choose Composio provider integrations.
Next: [Chapter 4: Authentication and Connected Accounts](04-authentication-and-connected-accounts.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `docs/scripts/generate-toolkits.ts`
-The `Trigger` interface in [`docs/scripts/generate-toolkits.ts`](https://github.com/ComposioHQ/composio/blob/HEAD/docs/scripts/generate-toolkits.ts) handles a key part of this chapter's functionality:
+The `fetchToolkitChangelog` function in [`docs/scripts/generate-toolkits.ts`](https://github.com/ComposioHQ/composio/blob/HEAD/docs/scripts/generate-toolkits.ts) handles a key part of this chapter's functionality:
```ts
}
-interface Trigger {
- slug: string;
- name: string;
- description: string;
-}
-
-interface AuthConfigField {
- name: string;
- displayName: string;
- type: string;
- description: string;
- required: boolean;
- default?: string | null;
-}
-
-interface AuthConfigDetail {
- mode: string;
- name: string;
- fields: {
- auth_config_creation: {
- required: AuthConfigField[];
- optional: AuthConfigField[];
- };
- connected_account_initiation: {
- required: AuthConfigField[];
- optional: AuthConfigField[];
- };
- };
-}
-
+async function fetchToolkitChangelog(): Promise
> {
+ console.log('Fetching toolkit changelog...');
+
+ const response = await fetch(`${API_BASE}/toolkits/changelog`, {
+ headers: {
+ 'Content-Type': 'application/json',
+ 'x-api-key': API_KEY!,
+ },
+ });
+
+ if (!response.ok) {
+ console.warn(`Failed to fetch changelog: ${response.status}`);
+ return new Map();
+ }
+
+ const data = await response.json();
+ const versionMap = new Map();
+
+ // Response format: { items: [{ slug, name, display_name, versions: [{ version, changelog }] }] }
+ const items = data.items || [];
+ for (const entry of items) {
+ const slug = entry.slug?.toLowerCase();
+ const latestVersion = entry.versions?.[0]?.version;
+ if (slug && latestVersion) {
+ versionMap.set(slug, latestVersion);
+ }
+ }
+
+ console.log(`Found versions for ${versionMap.size} toolkits`);
+ return versionMap;
```
-This interface is important because it defines how Composio Tutorial: Production Tool and Authentication Infrastructure for AI Agents implements the patterns covered in this chapter.
+This function is important because it defines how Composio Tutorial: Production Tool and Authentication Infrastructure for AI Agents implements the patterns covered in this chapter.
### `docs/scripts/generate-toolkits.ts`
-The `AuthConfigField` interface in [`docs/scripts/generate-toolkits.ts`](https://github.com/ComposioHQ/composio/blob/HEAD/docs/scripts/generate-toolkits.ts) handles a key part of this chapter's functionality:
+The `fetchToolsForToolkit` function in [`docs/scripts/generate-toolkits.ts`](https://github.com/ComposioHQ/composio/blob/HEAD/docs/scripts/generate-toolkits.ts) handles a key part of this chapter's functionality:
```ts
}
-interface AuthConfigField {
- name: string;
- displayName: string;
- type: string;
- description: string;
- required: boolean;
- default?: string | null;
+async function fetchToolsForToolkit(slug: string): Promise {
+ const response = await fetch(`${API_BASE}/tools?toolkit_slug=${slug}&toolkit_versions=latest&limit=1000`, {
+ headers: {
+ 'Content-Type': 'application/json',
+ 'x-api-key': API_KEY!,
+ },
+ });
+
+ if (!response.ok) return [];
+
+ const data = await response.json();
+ const rawItems = data.items || data;
+ const items = Array.isArray(rawItems) ? rawItems : [];
+
+ return items.filter((raw: any) => raw && typeof raw === 'object').map((raw: any) => ({
+ slug: raw.slug || '',
+ name: raw.name || raw.display_name || raw.slug || '',
+ description: raw.description || '',
+ }));
}
-interface AuthConfigDetail {
- mode: string;
- name: string;
- fields: {
- auth_config_creation: {
- required: AuthConfigField[];
- optional: AuthConfigField[];
- };
- connected_account_initiation: {
- required: AuthConfigField[];
- optional: AuthConfigField[];
- };
- };
-}
+async function fetchTriggersForToolkit(slug: string): Promise {
+ const response = await fetch(`${API_BASE}/triggers_types?toolkit_slugs=${slug}&toolkit_versions=latest`, {
+ headers: {
+ 'Content-Type': 'application/json',
+ 'x-api-key': API_KEY!,
+ },
+ });
-interface Toolkit {
- slug: string;
- name: string;
- logo: string | null;
- description: string;
- category: string | null;
+ if (!response.ok) return [];
```
-This interface is important because it defines how Composio Tutorial: Production Tool and Authentication Infrastructure for AI Agents implements the patterns covered in this chapter.
+This function is important because it defines how Composio Tutorial: Production Tool and Authentication Infrastructure for AI Agents implements the patterns covered in this chapter.
### `docs/scripts/generate-toolkits.ts`
-The `AuthConfigDetail` interface in [`docs/scripts/generate-toolkits.ts`](https://github.com/ComposioHQ/composio/blob/HEAD/docs/scripts/generate-toolkits.ts) handles a key part of this chapter's functionality:
+The `fetchTriggersForToolkit` function in [`docs/scripts/generate-toolkits.ts`](https://github.com/ComposioHQ/composio/blob/HEAD/docs/scripts/generate-toolkits.ts) handles a key part of this chapter's functionality:
```ts
}
-interface AuthConfigDetail {
- mode: string;
- name: string;
- fields: {
- auth_config_creation: {
- required: AuthConfigField[];
- optional: AuthConfigField[];
- };
- connected_account_initiation: {
- required: AuthConfigField[];
- optional: AuthConfigField[];
- };
- };
+async function fetchTriggersForToolkit(slug: string): Promise {
+ const response = await fetch(`${API_BASE}/triggers_types?toolkit_slugs=${slug}&toolkit_versions=latest`, {
+ headers: {
+ 'Content-Type': 'application/json',
+ 'x-api-key': API_KEY!,
+ },
+ });
+
+ if (!response.ok) return [];
+
+ const data = await response.json();
+ const rawItems = data.items || data;
+ const items = Array.isArray(rawItems) ? rawItems : [];
+
+ return items.filter((raw: any) => raw && typeof raw === 'object').map((raw: any) => ({
+ slug: raw.slug || '',
+ name: raw.name || raw.display_name || raw.slug || '',
+ description: raw.description || '',
+ }));
}
-interface Toolkit {
- slug: string;
- name: string;
- logo: string | null;
- description: string;
- category: string | null;
- authSchemes: string[];
- composioManagedAuthSchemes?: string[];
- toolCount: number;
- triggerCount: number;
- version: string | null;
- tools: Tool[];
- triggers: Trigger[];
- authConfigDetails?: AuthConfigDetail[];
-}
+async function fetchAuthConfigDetails(slug: string): Promise {
+ const response = await fetch(`${API_BASE}/toolkits/${slug}`, {
+ headers: {
+ 'Content-Type': 'application/json',
+ 'x-api-key': API_KEY!,
+ },
+ });
+
+ if (!response.ok) return [];
```
-This interface is important because it defines how Composio Tutorial: Production Tool and Authentication Infrastructure for AI Agents implements the patterns covered in this chapter.
+This function is important because it defines how Composio Tutorial: Production Tool and Authentication Infrastructure for AI Agents implements the patterns covered in this chapter.
### `docs/scripts/generate-toolkits.ts`
-The `Toolkit` interface in [`docs/scripts/generate-toolkits.ts`](https://github.com/ComposioHQ/composio/blob/HEAD/docs/scripts/generate-toolkits.ts) handles a key part of this chapter's functionality:
+The `fetchAuthConfigDetails` function in [`docs/scripts/generate-toolkits.ts`](https://github.com/ComposioHQ/composio/blob/HEAD/docs/scripts/generate-toolkits.ts) handles a key part of this chapter's functionality:
```ts
-/**
- * Toolkit Generator Script
- *
- * Fetches all toolkits from Composio API and generates:
- * - /public/data/toolkits.json (full data with tools & triggers - for detail pages)
- * - /public/data/toolkits-list.json (light version without tools/triggers - for landing page)
- *
- * Run: bun run generate:toolkits
- */
-
-import { mkdir, writeFile } from 'fs/promises';
-import { join } from 'path';
-
-const API_BASE = process.env.COMPOSIO_API_BASE || 'https://backend.composio.dev/api/v3';
-const API_KEY = process.env.COMPOSIO_API_KEY;
-
-if (!API_KEY) {
- console.error('Error: COMPOSIO_API_KEY environment variable is required');
- process.exit(1);
-}
-
-const OUTPUT_DIR = join(process.cwd(), 'public/data');
-
-interface Tool {
- slug: string;
- name: string;
- description: string;
}
-interface Trigger {
- slug: string;
+async function fetchAuthConfigDetails(slug: string): Promise {
+ const response = await fetch(`${API_BASE}/toolkits/${slug}`, {
+ headers: {
+ 'Content-Type': 'application/json',
+ 'x-api-key': API_KEY!,
+ },
+ });
+
+ if (!response.ok) return [];
+
+ const data = await response.json();
+ const authConfigDetails = data.auth_config_details || [];
+
+ return authConfigDetails.map((raw: any) => ({
+ mode: raw.mode || '',
+ name: raw.name || raw.mode || '',
+ fields: {
+ auth_config_creation: {
+ required: (raw.fields?.auth_config_creation?.required || []).map((f: any) => ({
+ name: f.name || '',
+ displayName: f.displayName || f.name || '',
+ type: f.type || 'string',
+ description: f.description || '',
+ required: f.required ?? true,
+ default: f.default ?? null,
+ })),
+ optional: (raw.fields?.auth_config_creation?.optional || []).map((f: any) => ({
+ name: f.name || '',
+ displayName: f.displayName || f.name || '',
+ type: f.type || 'string',
```
-This interface is important because it defines how Composio Tutorial: Production Tool and Authentication Infrastructure for AI Agents implements the patterns covered in this chapter.
+This function is important because it defines how Composio Tutorial: Production Tool and Authentication Infrastructure for AI Agents implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[Trigger]
- B[AuthConfigField]
- C[AuthConfigDetail]
- D[Toolkit]
- E[ClientIcon]
+ A[fetchToolkitChangelog]
+ B[fetchToolsForToolkit]
+ C[fetchTriggersForToolkit]
+ D[fetchAuthConfigDetails]
+ E[transformToolkit]
A --> B
B --> C
C --> D
diff --git a/tutorials/composio-tutorial/04-authentication-and-connected-accounts.md b/tutorials/composio-tutorial/04-authentication-and-connected-accounts.md
index c1255055..5683b252 100644
--- a/tutorials/composio-tutorial/04-authentication-and-connected-accounts.md
+++ b/tutorials/composio-tutorial/04-authentication-and-connected-accounts.md
@@ -50,170 +50,167 @@ You now have a safer authentication foundation for multi-user production systems
Next: [Chapter 5: Tool Execution Modes and Modifiers](05-tool-execution-modes-and-modifiers.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `docs/components/connect-flow.tsx`
+### `docs/scripts/generate-toolkits.ts`
-The `ConnectContextValue` interface in [`docs/components/connect-flow.tsx`](https://github.com/ComposioHQ/composio/blob/HEAD/docs/components/connect-flow.tsx) handles a key part of this chapter's functionality:
+The `Toolkit` interface in [`docs/scripts/generate-toolkits.ts`](https://github.com/ComposioHQ/composio/blob/HEAD/docs/scripts/generate-toolkits.ts) handles a key part of this chapter's functionality:
-```tsx
-}
+```ts
+/**
+ * Toolkit Generator Script
+ *
+ * Fetches all toolkits from Composio API and generates:
+ * - /public/data/toolkits.json (full data with tools & triggers - for detail pages)
+ * - /public/data/toolkits-list.json (light version without tools/triggers - for landing page)
+ *
+ * Run: bun run generate:toolkits
+ */
-interface ConnectContextValue {
- selectedId: string;
- setSelectedId: (id: string) => void;
- registerClient: (data: ClientData) => void;
- clients: ClientData[];
-}
+import { mkdir, writeFile } from 'fs/promises';
+import { join } from 'path';
-const ConnectContext = createContext(null);
+const API_BASE = process.env.COMPOSIO_API_BASE || 'https://backend.composio.dev/api/v3';
+const API_KEY = process.env.COMPOSIO_API_KEY;
-function ClientIcon({ icon, iconDark, name, size = 16 }: { icon?: string; iconDark?: string; name: string; size?: number }) {
- if (!icon) return null;
+if (!API_KEY) {
+ console.error('Error: COMPOSIO_API_KEY environment variable is required');
+ process.exit(1);
+}
- if (iconDark) {
- return (
- <>
-
-
-
- );
- }
+const OUTPUT_DIR = join(process.cwd(), 'public/data');
- return ;
+interface Tool {
+ slug: string;
+ name: string;
+ description: string;
}
-function PopularTab({
- client,
- selected,
- onSelect,
-}: {
- client: ClientData;
+interface Trigger {
+ slug: string;
```
This interface is important because it defines how Composio Tutorial: Production Tool and Authentication Infrastructure for AI Agents implements the patterns covered in this chapter.
-### `docs/components/connect-flow.tsx`
+### `docs/components/feedback.tsx`
-The `ConnectFlowProps` interface in [`docs/components/connect-flow.tsx`](https://github.com/ComposioHQ/composio/blob/HEAD/docs/components/connect-flow.tsx) handles a key part of this chapter's functionality:
+The `Feedback` function in [`docs/components/feedback.tsx`](https://github.com/ComposioHQ/composio/blob/HEAD/docs/components/feedback.tsx) handles a key part of this chapter's functionality:
```tsx
-}
+type Sentiment = 'positive' | 'neutral' | 'negative' | null;
-interface ConnectFlowProps {
- children: ReactNode;
+interface FeedbackProps {
+ page: string;
}
-export function ConnectFlow({ children }: ConnectFlowProps) {
- const [clients, setClients] = useState([]);
- const [selectedId, setSelectedId] = useState('');
- const registeredIds = useRef>(new Set());
- const [dropdownOpen, setDropdownOpen] = useState(false);
- const dropdownRef = useRef(null);
-
- const registerClient = (data: ClientData) => {
- if (!registeredIds.current.has(data.id)) {
- registeredIds.current.add(data.id);
- setClients((prev) => {
- if (prev.some((c) => c.id === data.id)) return prev;
- return [...prev, data];
- });
- }
- };
-
- useEffect(() => {
- if (clients.length > 0 && !selectedId) {
- setSelectedId(clients[0].id);
- }
- }, [clients, selectedId]);
+export function Feedback({ page }: FeedbackProps) {
+ const [isOpen, setIsOpen] = useState(false);
+ const [sentiment, setSentiment] = useState(null);
+ const [message, setMessage] = useState('');
+ const [email, setEmail] = useState('');
+ const [state, setState] = useState<'idle' | 'loading' | 'success' | 'error'>('idle');
+ const closeTimeoutRef = useRef | null>(null);
- // Close dropdown on outside click
useEffect(() => {
- function handleClick(e: MouseEvent) {
+ return () => {
+ if (closeTimeoutRef.current) {
+ clearTimeout(closeTimeoutRef.current);
+ }
+ };
+ }, []);
+
+ const handleSubmit = async (e: React.FormEvent) => {
+ e.preventDefault();
+ if (!message.trim()) return;
+
+ setState('loading');
+
+ try {
+ const response = await fetch('/api/feedback', {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
```
-This interface is important because it defines how Composio Tutorial: Production Tool and Authentication Infrastructure for AI Agents implements the patterns covered in this chapter.
+This function is important because it defines how Composio Tutorial: Production Tool and Authentication Infrastructure for AI Agents implements the patterns covered in this chapter.
-### `docs/components/connect-flow.tsx`
+### `docs/components/feedback.tsx`
-The `ConnectClientOptionProps` interface in [`docs/components/connect-flow.tsx`](https://github.com/ComposioHQ/composio/blob/HEAD/docs/components/connect-flow.tsx) handles a key part of this chapter's functionality:
+The `FeedbackProps` interface in [`docs/components/feedback.tsx`](https://github.com/ComposioHQ/composio/blob/HEAD/docs/components/feedback.tsx) handles a key part of this chapter's functionality:
```tsx
-}
+type Sentiment = 'positive' | 'neutral' | 'negative' | null;
-interface ConnectClientOptionProps {
- id: string;
- name: string;
- description: string;
- icon?: string;
- iconDark?: string;
- category?: 'popular' | 'ide' | 'other';
- children: ReactNode;
+interface FeedbackProps {
+ page: string;
}
-export function ConnectClientOption({
- id,
- name,
- description,
- icon,
- iconDark,
- category = 'other',
- children,
-}: ConnectClientOptionProps) {
- const context = useContext(ConnectContext);
- const hasRegistered = useRef(false);
+export function Feedback({ page }: FeedbackProps) {
+ const [isOpen, setIsOpen] = useState(false);
+ const [sentiment, setSentiment] = useState(null);
+ const [message, setMessage] = useState('');
+ const [email, setEmail] = useState('');
+ const [state, setState] = useState<'idle' | 'loading' | 'success' | 'error'>('idle');
+ const closeTimeoutRef = useRef | null>(null);
useEffect(() => {
- if (context && !hasRegistered.current) {
- context.registerClient({ id, name, description, icon, iconDark, category });
- hasRegistered.current = true;
- }
- }, [context, id, name, description, icon, iconDark, category]);
-
- if (!context || context.selectedId !== id) {
+ return () => {
+ if (closeTimeoutRef.current) {
+ clearTimeout(closeTimeoutRef.current);
+ }
+ };
+ }, []);
+
+ const handleSubmit = async (e: React.FormEvent) => {
+ e.preventDefault();
+ if (!message.trim()) return;
+
+ setState('loading');
+
+ try {
+ const response = await fetch('/api/feedback', {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
```
This interface is important because it defines how Composio Tutorial: Production Tool and Authentication Infrastructure for AI Agents implements the patterns covered in this chapter.
-### `docs/components/custom-schema-ui.tsx`
+### `docs/lib/source.ts`
-The `useData` function in [`docs/components/custom-schema-ui.tsx`](https://github.com/ComposioHQ/composio/blob/HEAD/docs/components/custom-schema-ui.tsx) handles a key part of this chapter's functionality:
+The `getOpenapiPages` function in [`docs/lib/source.ts`](https://github.com/ComposioHQ/composio/blob/HEAD/docs/lib/source.ts) handles a key part of this chapter's functionality:
-```tsx
-const ResponseContext = createContext(false);
+```ts
+let _openapiPagesPromise: Promise | null = null;
-function useData() {
- const ctx = use(DataContext);
- if (!ctx) throw new Error('Missing DataContext');
- return ctx;
+async function getOpenapiPages() {
+ if (!_openapiPagesPromise) {
+ _openapiPagesPromise = openapiSource(openapi, {
+ groupBy: 'tag',
+ baseDir: 'api-reference',
+ });
+ }
+ return _openapiPagesPromise;
}
-function useIsResponse() {
- return use(ResponseContext);
+export async function getReferenceSource() {
+ if (!_referenceSource) {
+ const openapiPages = await getOpenapiPages();
+ _referenceSource = loader({
+ baseUrl: '/reference',
+ source: multiple({
+ mdx: reference.toFumadocsSource(),
+ openapi: openapiPages,
+ }),
+ plugins: [lucideIconsPlugin(), openapiPlugin()],
+ pageTree: {
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ transformers: [defaultOpenTransformer as any],
+ },
+ });
+ }
+ return _referenceSource;
}
-export function CustomSchemaUI({
- name,
- required = false,
- as = 'property',
- generated,
- isResponse = false,
-}: SchemaUIProps) {
- const schema = generated.refs[generated.$root];
- const isProperty = as === 'property' || !isExpandable(schema, generated.refs);
-
- return (
-
-
- {isProperty ? (
-
+// Synchronous reference source for cases where OpenAPI isn't needed
```
This function is important because it defines how Composio Tutorial: Production Tool and Authentication Infrastructure for AI Agents implements the patterns covered in this chapter.
@@ -223,11 +220,11 @@ This function is important because it defines how Composio Tutorial: Production
```mermaid
flowchart TD
- A[ConnectContextValue]
- B[ConnectFlowProps]
- C[ConnectClientOptionProps]
- D[useData]
- E[useIsResponse]
+ A[Toolkit]
+ B[Feedback]
+ C[FeedbackProps]
+ D[getOpenapiPages]
+ E[getReferenceSource]
A --> B
B --> C
C --> D
diff --git a/tutorials/composio-tutorial/05-tool-execution-modes-and-modifiers.md b/tutorials/composio-tutorial/05-tool-execution-modes-and-modifiers.md
index cbd23aa7..e59dba8b 100644
--- a/tutorials/composio-tutorial/05-tool-execution-modes-and-modifiers.md
+++ b/tutorials/composio-tutorial/05-tool-execution-modes-and-modifiers.md
@@ -48,184 +48,133 @@ You now have an execution and modifier model that can be adapted to both agentic
Next: [Chapter 6: MCP Server Patterns and Toolkit Control](06-mcp-server-patterns-and-toolkit-control.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `docs/components/custom-schema-ui.tsx`
-
-The `isExpandable` function in [`docs/components/custom-schema-ui.tsx`](https://github.com/ComposioHQ/composio/blob/HEAD/docs/components/custom-schema-ui.tsx) handles a key part of this chapter's functionality:
-
-```tsx
-}: SchemaUIProps) {
- const schema = generated.refs[generated.$root];
- const isProperty = as === 'property' || !isExpandable(schema, generated.refs);
-
- return (
-
-
- {isProperty ? (
-
- ) : (
-
- )}
-
-
- );
+### `docs/lib/source.ts`
+
+The `validateDateFormat` function in [`docs/lib/source.ts`](https://github.com/ComposioHQ/composio/blob/HEAD/docs/lib/source.ts) handles a key part of this chapter's functionality:
+
+```ts
+const DATE_REGEX = /^\d{4}-\d{2}-\d{2}$/;
+
+function validateDateFormat(dateStr: string): void {
+ if (!DATE_REGEX.test(dateStr)) {
+ throw new Error(
+ `Invalid date format: "${dateStr}". Expected YYYY-MM-DD (e.g., "2025-12-29")`
+ );
+ }
}
-function SchemaContent({
- $type,
- parentPath = '',
-}: {
- $type: string;
- parentPath?: string;
-}) {
- const { refs } = useData();
- const schema = refs[$type];
+export function dateToChangelogUrl(dateStr: string): string {
+ // Convert "2025-12-29" to "/docs/changelog/2025/12/29"
+ validateDateFormat(dateStr);
+ const [year, month, day] = dateStr.split('-');
+ return `/docs/changelog/${year}/${month}/${day}`;
+}
-```
+export function dateToSlug(dateStr: string): string[] {
+ // Convert "2025-12-29" to ["2025", "12", "29"]
+ validateDateFormat(dateStr);
+ const [year, month, day] = dateStr.split('-');
+ return [year, month, day];
+}
-This function is important because it defines how Composio Tutorial: Production Tool and Authentication Infrastructure for AI Agents implements the patterns covered in this chapter.
+export function slugToDate(slug: string[]): string | null {
+ // Convert ["2025", "12", "29"] to "2025-12-29"
+ if (slug.length !== 3) return null;
+ const [year, month, day] = slug;
+ return `${year}-${month}-${day}`;
+}
-### `docs/components/custom-schema-ui.tsx`
-
-The `getTypeDisplay` function in [`docs/components/custom-schema-ui.tsx`](https://github.com/ComposioHQ/composio/blob/HEAD/docs/components/custom-schema-ui.tsx) handles a key part of this chapter's functionality:
-
-```tsx
-
- const hasChildren = isExpandable(schema, refs);
- const typeDisplay = getTypeDisplay(schema);
-
- return (
-
- {/* Property header */}
-
-
- {name}
-
-
- {typeDisplay}
-
- {required && !isResponse && (
- Required
- )}
- {schema.deprecated && (
-
- Deprecated
-
- )}
-
-
- {/* Description */}
- {schema.description && (
-
- {schema.description}
-
- )}
-
- {/* Info tags */}
```
This function is important because it defines how Composio Tutorial: Production Tool and Authentication Infrastructure for AI Agents implements the patterns covered in this chapter.
-### `docs/components/custom-schema-ui.tsx`
-
-The `getChildCount` function in [`docs/components/custom-schema-ui.tsx`](https://github.com/ComposioHQ/composio/blob/HEAD/docs/components/custom-schema-ui.tsx) handles a key part of this chapter's functionality:
-
-```tsx
- const schema = refs[$type];
-
- const childCount = getChildCount(schema);
- const label = schema.type === 'array' ? 'item properties' : 'child attributes';
-
- return (
-
-
- {isOpen ? (
- <>
-
- Hide {label}
-
- ) : (
- <>
-
- Show {childCount > 0 ? `${childCount} ` : ''}{label}
-
- )}
-
-
-
-
-
-
-
- );
+### `docs/lib/source.ts`
+
+The `dateToChangelogUrl` function in [`docs/lib/source.ts`](https://github.com/ComposioHQ/composio/blob/HEAD/docs/lib/source.ts) handles a key part of this chapter's functionality:
+
+```ts
+}
+
+export function dateToChangelogUrl(dateStr: string): string {
+ // Convert "2025-12-29" to "/docs/changelog/2025/12/29"
+ validateDateFormat(dateStr);
+ const [year, month, day] = dateStr.split('-');
+ return `/docs/changelog/${year}/${month}/${day}`;
+}
+
+export function dateToSlug(dateStr: string): string[] {
+ // Convert "2025-12-29" to ["2025", "12", "29"]
+ validateDateFormat(dateStr);
+ const [year, month, day] = dateStr.split('-');
+ return [year, month, day];
+}
+
+export function slugToDate(slug: string[]): string | null {
+ // Convert ["2025", "12", "29"] to "2025-12-29"
+ if (slug.length !== 3) return null;
+ const [year, month, day] = slug;
+ return `${year}-${month}-${day}`;
}
-function isExpandable(
- schema: SchemaData,
- refs?: Record
,
```
This function is important because it defines how Composio Tutorial: Production Tool and Authentication Infrastructure for AI Agents implements the patterns covered in this chapter.
-### `docs/components/custom-schema-ui.tsx`
+### `docs/lib/source.ts`
-The `SchemaUIProps` interface in [`docs/components/custom-schema-ui.tsx`](https://github.com/ComposioHQ/composio/blob/HEAD/docs/components/custom-schema-ui.tsx) handles a key part of this chapter's functionality:
+The `dateToSlug` function in [`docs/lib/source.ts`](https://github.com/ComposioHQ/composio/blob/HEAD/docs/lib/source.ts) handles a key part of this chapter's functionality:
-```tsx
-import type { SchemaData, SchemaUIGeneratedData } from './schema-generator';
+```ts
+}
-interface SchemaUIProps {
- name: string;
- required?: boolean;
- as?: 'property' | 'body';
- generated: SchemaUIGeneratedData;
- isResponse?: boolean;
+export function dateToSlug(dateStr: string): string[] {
+ // Convert "2025-12-29" to ["2025", "12", "29"]
+ validateDateFormat(dateStr);
+ const [year, month, day] = dateStr.split('-');
+ return [year, month, day];
}
-const DataContext = createContext(null);
-const ResponseContext = createContext(false);
+export function slugToDate(slug: string[]): string | null {
+ // Convert ["2025", "12", "29"] to "2025-12-29"
+ if (slug.length !== 3) return null;
+ const [year, month, day] = slug;
+ return `${year}-${month}-${day}`;
+}
-function useData() {
- const ctx = use(DataContext);
- if (!ctx) throw new Error('Missing DataContext');
- return ctx;
+```
+
+This function is important because it defines how Composio Tutorial: Production Tool and Authentication Infrastructure for AI Agents implements the patterns covered in this chapter.
+
+### `docs/lib/source.ts`
+
+The `slugToDate` function in [`docs/lib/source.ts`](https://github.com/ComposioHQ/composio/blob/HEAD/docs/lib/source.ts) handles a key part of this chapter's functionality:
+
+```ts
}
-function useIsResponse() {
- return use(ResponseContext);
+export function slugToDate(slug: string[]): string | null {
+ // Convert ["2025", "12", "29"] to "2025-12-29"
+ if (slug.length !== 3) return null;
+ const [year, month, day] = slug;
+ return `${year}-${month}-${day}`;
}
-export function CustomSchemaUI({
- name,
- required = false,
- as = 'property',
- generated,
- isResponse = false,
-}: SchemaUIProps) {
- const schema = generated.refs[generated.$root];
- const isProperty = as === 'property' || !isExpandable(schema, generated.refs);
```
-This interface is important because it defines how Composio Tutorial: Production Tool and Authentication Infrastructure for AI Agents implements the patterns covered in this chapter.
+This function is important because it defines how Composio Tutorial: Production Tool and Authentication Infrastructure for AI Agents implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[isExpandable]
- B[getTypeDisplay]
- C[getChildCount]
- D[SchemaUIProps]
- E[name]
+ A[validateDateFormat]
+ B[dateToChangelogUrl]
+ C[dateToSlug]
+ D[slugToDate]
+ E[useData]
A --> B
B --> C
C --> D
diff --git a/tutorials/composio-tutorial/06-mcp-server-patterns-and-toolkit-control.md b/tutorials/composio-tutorial/06-mcp-server-patterns-and-toolkit-control.md
index be726a09..8e2d50b9 100644
--- a/tutorials/composio-tutorial/06-mcp-server-patterns-and-toolkit-control.md
+++ b/tutorials/composio-tutorial/06-mcp-server-patterns-and-toolkit-control.md
@@ -46,170 +46,168 @@ You now have a decision framework for MCP architecture choices in Composio deplo
Next: [Chapter 7: Triggers, Webhooks, and Event Automation](07-triggers-webhooks-and-event-automation.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `python/scripts/generate-docs.py`
-
-The `docs` class in [`python/scripts/generate-docs.py`](https://github.com/ComposioHQ/composio/blob/HEAD/python/scripts/generate-docs.py) handles a key part of this chapter's functionality:
-
-```py
-
-Generates MDX documentation from Python source code using griffe.
-Output is written to the docs content directory.
-
-Run: cd python && uv run --with griffe python scripts/generate-docs.py
-"""
-
-from __future__ import annotations
-
-import json
-import re
-import shutil
-from pathlib import Path
-from typing import Any
-
-try:
- import griffe
-except ImportError:
- print("Error: griffe not installed. Run: pip install griffe")
- raise SystemExit(1)
-
-# Paths
-SCRIPT_DIR = Path(__file__).parent
-PACKAGE_DIR = SCRIPT_DIR.parent
-OUTPUT_DIR = (
- PACKAGE_DIR.parent / "docs" / "content" / "reference" / "sdk-reference" / "python"
-)
-
-# GitHub base URL for source links
-GITHUB_BASE = "https://github.com/composiohq/composio/blob/next/python"
-
-# Decorators to document
+### `docs/components/custom-schema-ui.tsx`
+
+The `ExpandableContent` function in [`docs/components/custom-schema-ui.tsx`](https://github.com/ComposioHQ/composio/blob/HEAD/docs/components/custom-schema-ui.tsx) handles a key part of this chapter's functionality:
+
+```tsx
+ {item.name}
+ {isExpandable(refs[item.$type], refs) && (
+
+ )}
+
+ );
+ }
+
+ return null;
+}
+
+function SchemaProperty({
+ name,
+ $type,
+ required,
+ parentPath = '',
+ isRoot = false,
+}: {
+ name: string;
+ $type: string;
+ required: boolean;
+ parentPath?: string;
+ isRoot?: boolean;
+}) {
+ const { refs } = useData();
+ const isResponse = useIsResponse();
+ const schema = refs[$type];
+ const fullPath = parentPath ? `${parentPath}.${name}` : name;
+
+ const hasChildren = isExpandable(schema, refs);
```
-This class is important because it defines how Composio Tutorial: Production Tool and Authentication Infrastructure for AI Agents implements the patterns covered in this chapter.
-
-### `python/scripts/generate-docs.py`
-
-The `to_kebab_case` function in [`python/scripts/generate-docs.py`](https://github.com/ComposioHQ/composio/blob/HEAD/python/scripts/generate-docs.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def to_kebab_case(name: str) -> str:
- """Convert PascalCase to kebab-case."""
- s1 = re.sub("(.)([A-Z][a-z]+)", r"\1-\2", name)
- return re.sub("([a-z0-9])([A-Z])", r"\1-\2", s1).lower()
-
-
-def escape_yaml_string(s: str) -> str:
- """Escape a string for YAML frontmatter."""
- if any(c in s for c in [":", '"', "'", "\n", "#", "{", "}"]):
- return f'"{s.replace(chr(34), chr(92) + chr(34))}"'
- return s
+This function is important because it defines how Composio Tutorial: Production Tool and Authentication Infrastructure for AI Agents implements the patterns covered in this chapter.
+### `docs/components/custom-schema-ui.tsx`
+
+The `isExpandable` function in [`docs/components/custom-schema-ui.tsx`](https://github.com/ComposioHQ/composio/blob/HEAD/docs/components/custom-schema-ui.tsx) handles a key part of this chapter's functionality:
+
+```tsx
+}: SchemaUIProps) {
+ const schema = generated.refs[generated.$root];
+ const isProperty = as === 'property' || !isExpandable(schema, generated.refs);
+
+ return (
+
+
+ {isProperty ? (
+
+ ) : (
+
+ )}
+
+
+ );
+}
+
+function SchemaContent({
+ $type,
+ parentPath = '',
+}: {
+ $type: string;
+ parentPath?: string;
+}) {
+ const { refs } = useData();
+ const schema = refs[$type];
-def get_source_link(obj: griffe.Object) -> str | None:
- """Get GitHub source link for an object."""
- if not hasattr(obj, "filepath") or not obj.filepath:
- return None
- try:
- raw_filepath = obj.filepath
- # Handle case where filepath might be a list (griffe edge case)
- if isinstance(raw_filepath, list):
- resolved_path: Path | None = raw_filepath[0] if raw_filepath else None
- else:
- resolved_path = raw_filepath
- if not resolved_path:
- return None
- rel_path = resolved_path.relative_to(PACKAGE_DIR)
- except ValueError:
- return None
- line = obj.lineno if hasattr(obj, "lineno") and obj.lineno else 1
```
This function is important because it defines how Composio Tutorial: Production Tool and Authentication Infrastructure for AI Agents implements the patterns covered in this chapter.
-### `python/scripts/generate-docs.py`
-
-The `escape_yaml_string` function in [`python/scripts/generate-docs.py`](https://github.com/ComposioHQ/composio/blob/HEAD/python/scripts/generate-docs.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def escape_yaml_string(s: str) -> str:
- """Escape a string for YAML frontmatter."""
- if any(c in s for c in [":", '"', "'", "\n", "#", "{", "}"]):
- return f'"{s.replace(chr(34), chr(92) + chr(34))}"'
- return s
-
-
-def get_source_link(obj: griffe.Object) -> str | None:
- """Get GitHub source link for an object."""
- if not hasattr(obj, "filepath") or not obj.filepath:
- return None
- try:
- raw_filepath = obj.filepath
- # Handle case where filepath might be a list (griffe edge case)
- if isinstance(raw_filepath, list):
- resolved_path: Path | None = raw_filepath[0] if raw_filepath else None
- else:
- resolved_path = raw_filepath
- if not resolved_path:
- return None
- rel_path = resolved_path.relative_to(PACKAGE_DIR)
- except ValueError:
- return None
- line = obj.lineno if hasattr(obj, "lineno") and obj.lineno else 1
- return f"{GITHUB_BASE}/{rel_path}#L{line}"
-
-
-def format_type(annotation: Any) -> str:
- """Format a type annotation to readable string."""
- if annotation is None:
+### `docs/components/custom-schema-ui.tsx`
+
+The `getTypeDisplay` function in [`docs/components/custom-schema-ui.tsx`](https://github.com/ComposioHQ/composio/blob/HEAD/docs/components/custom-schema-ui.tsx) handles a key part of this chapter's functionality:
+
+```tsx
+
+ const hasChildren = isExpandable(schema, refs);
+ const typeDisplay = getTypeDisplay(schema);
+
+ return (
+
+ {/* Property header */}
+
+
+ {name}
+
+
+ {typeDisplay}
+
+ {required && !isResponse && (
+ Required
+ )}
+ {schema.deprecated && (
+
+ Deprecated
+
+ )}
+
+
+ {/* Description */}
+ {schema.description && (
+
+ {schema.description}
+
+ )}
+
+ {/* Info tags */}
```
This function is important because it defines how Composio Tutorial: Production Tool and Authentication Infrastructure for AI Agents implements the patterns covered in this chapter.
-### `python/scripts/generate-docs.py`
-
-The `get_source_link` function in [`python/scripts/generate-docs.py`](https://github.com/ComposioHQ/composio/blob/HEAD/python/scripts/generate-docs.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def get_source_link(obj: griffe.Object) -> str | None:
- """Get GitHub source link for an object."""
- if not hasattr(obj, "filepath") or not obj.filepath:
- return None
- try:
- raw_filepath = obj.filepath
- # Handle case where filepath might be a list (griffe edge case)
- if isinstance(raw_filepath, list):
- resolved_path: Path | None = raw_filepath[0] if raw_filepath else None
- else:
- resolved_path = raw_filepath
- if not resolved_path:
- return None
- rel_path = resolved_path.relative_to(PACKAGE_DIR)
- except ValueError:
- return None
- line = obj.lineno if hasattr(obj, "lineno") and obj.lineno else 1
- return f"{GITHUB_BASE}/{rel_path}#L{line}"
-
-
-def format_type(annotation: Any) -> str:
- """Format a type annotation to readable string."""
- if annotation is None:
- return "Any"
-
- type_str = str(annotation)
- # Clean up common prefixes
- type_str = type_str.replace("typing.", "").replace("typing_extensions.", "")
- type_str = type_str.replace("composio.client.types.", "")
- type_str = re.sub(r"\bt\.", "", type_str)
+### `docs/components/custom-schema-ui.tsx`
+
+The `getChildCount` function in [`docs/components/custom-schema-ui.tsx`](https://github.com/ComposioHQ/composio/blob/HEAD/docs/components/custom-schema-ui.tsx) handles a key part of this chapter's functionality:
+
+```tsx
+ const schema = refs[$type];
+
+ const childCount = getChildCount(schema);
+ const label = schema.type === 'array' ? 'item properties' : 'child attributes';
+
+ return (
+
+
+ {isOpen ? (
+ <>
+
+ Hide {label}
+
+ ) : (
+ <>
+
+ Show {childCount > 0 ? `${childCount} ` : ''}{label}
+
+ )}
+
+
+
+
+
+
+
+ );
+}
+
+function isExpandable(
+ schema: SchemaData,
+ refs?: Record
,
```
This function is important because it defines how Composio Tutorial: Production Tool and Authentication Infrastructure for AI Agents implements the patterns covered in this chapter.
@@ -219,11 +217,11 @@ This function is important because it defines how Composio Tutorial: Production
```mermaid
flowchart TD
- A[docs]
- B[to_kebab_case]
- C[escape_yaml_string]
- D[get_source_link]
- E[format_type]
+ A[ExpandableContent]
+ B[isExpandable]
+ C[getTypeDisplay]
+ D[getChildCount]
+ E[SchemaUIProps]
A --> B
B --> C
C --> D
diff --git a/tutorials/composio-tutorial/07-triggers-webhooks-and-event-automation.md b/tutorials/composio-tutorial/07-triggers-webhooks-and-event-automation.md
index f3c59272..47801182 100644
--- a/tutorials/composio-tutorial/07-triggers-webhooks-and-event-automation.md
+++ b/tutorials/composio-tutorial/07-triggers-webhooks-and-event-automation.md
@@ -50,184 +50,182 @@ You now have a practical event-automation blueprint for production-grade Composi
Next: [Chapter 8: Migration, Troubleshooting, and Production Ops](08-migration-troubleshooting-and-production-ops.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `docs/lib/source.ts`
-
-The `getOpenapiPages` function in [`docs/lib/source.ts`](https://github.com/ComposioHQ/composio/blob/HEAD/docs/lib/source.ts) handles a key part of this chapter's functionality:
-
-```ts
-let _openapiPagesPromise: Promise | null = null;
-
-async function getOpenapiPages() {
- if (!_openapiPagesPromise) {
- _openapiPagesPromise = openapiSource(openapi, {
- groupBy: 'tag',
- baseDir: 'api-reference',
- });
- }
- return _openapiPagesPromise;
-}
-
-export async function getReferenceSource() {
- if (!_referenceSource) {
- const openapiPages = await getOpenapiPages();
- _referenceSource = loader({
- baseUrl: '/reference',
- source: multiple({
- mdx: reference.toFumadocsSource(),
- openapi: openapiPages,
- }),
- plugins: [lucideIconsPlugin(), openapiPlugin()],
- pageTree: {
- // eslint-disable-next-line @typescript-eslint/no-explicit-any
- transformers: [defaultOpenTransformer as any],
- },
- });
- }
- return _referenceSource;
-}
-
-// Synchronous reference source for cases where OpenAPI isn't needed
+### `docs/components/schema-generator.tsx`
+
+The `generateInfoTags` function in [`docs/components/schema-generator.tsx`](https://github.com/ComposioHQ/composio/blob/HEAD/docs/components/schema-generator.tsx) handles a key part of this chapter's functionality:
+
+```tsx
+ ? ctx.renderMarkdown(schema.description)
+ : undefined,
+ infoTags: generateInfoTags(schema),
+ typeName: getTypeName(schema),
+ aliasName,
+ deprecated: schema.deprecated,
+ enumValues: schema.enum
+ ? schema.enum.map((v: unknown) => String(v))
+ : undefined,
+ };
+
+ // Handle oneOf/anyOf
+ if (schema.oneOf || schema.anyOf) {
+ const variants = schema.oneOf || schema.anyOf || [];
+ refs[id] = {
+ ...base,
+ type: 'or',
+ items: variants.map((variant: SimpleSchema) => ({
+ name: getTypeName(variant),
+ $type: processSchema(variant),
+ })),
+ };
+ return id;
+ }
+
+ // Handle allOf - merge into single object
+ if (schema.allOf) {
+ // Merge all schemas together
+ const merged: SimpleSchema = { type: 'object', properties: {}, required: [] };
+ for (const subSchema of schema.allOf) {
+ if (subSchema.properties) {
+ Object.assign(merged.properties, subSchema.properties);
```
This function is important because it defines how Composio Tutorial: Production Tool and Authentication Infrastructure for AI Agents implements the patterns covered in this chapter.
-### `docs/lib/source.ts`
+### `docs/components/schema-generator.tsx`
-The `getReferenceSource` function in [`docs/lib/source.ts`](https://github.com/ComposioHQ/composio/blob/HEAD/docs/lib/source.ts) handles a key part of this chapter's functionality:
+The `FieldBase` interface in [`docs/components/schema-generator.tsx`](https://github.com/ComposioHQ/composio/blob/HEAD/docs/components/schema-generator.tsx) handles a key part of this chapter's functionality:
-```ts
+```tsx
+
+// Types matching fumadocs-openapi internal structure
+interface FieldBase {
+ description?: ReactNode;
+ infoTags?: ReactNode[];
+ typeName: string;
+ aliasName: string;
+ deprecated?: boolean;
+ enumValues?: string[];
}
-export async function getReferenceSource() {
- if (!_referenceSource) {
- const openapiPages = await getOpenapiPages();
- _referenceSource = loader({
- baseUrl: '/reference',
- source: multiple({
- mdx: reference.toFumadocsSource(),
- openapi: openapiPages,
- }),
- plugins: [lucideIconsPlugin(), openapiPlugin()],
- pageTree: {
- // eslint-disable-next-line @typescript-eslint/no-explicit-any
- transformers: [defaultOpenTransformer as any],
- },
- });
- }
- return _referenceSource;
+export type SchemaData = FieldBase &
+ (
+ | { type: 'primitive' }
+ | {
+ type: 'object';
+ props: { name: string; $type: string; required: boolean }[];
+ }
+ | { type: 'array'; item: { $type: string } }
+ | { type: 'or'; items: { name: string; $type: string }[] }
+ | { type: 'and'; items: { name: string; $type: string }[] }
+ );
+
+export interface SchemaUIGeneratedData {
+ $root: string;
+ refs: Record;
}
-// Synchronous reference source for cases where OpenAPI isn't needed
-export const referenceSource = loader({
- baseUrl: '/reference',
- source: reference.toFumadocsSource(),
- plugins: [lucideIconsPlugin()],
-});
-
-export const cookbooksSource = loader({
- baseUrl: '/cookbooks',
- source: cookbooks.toFumadocsSource(),
- plugins: [lucideIconsPlugin()],
+// Simplified schema type (subset of OpenAPI schema)
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type SimpleSchema = any;
+
```
-This function is important because it defines how Composio Tutorial: Production Tool and Authentication Infrastructure for AI Agents implements the patterns covered in this chapter.
+This interface is important because it defines how Composio Tutorial: Production Tool and Authentication Infrastructure for AI Agents implements the patterns covered in this chapter.
-### `docs/lib/source.ts`
+### `docs/components/schema-generator.tsx`
-The `getOgImageUrl` function in [`docs/lib/source.ts`](https://github.com/ComposioHQ/composio/blob/HEAD/docs/lib/source.ts) handles a key part of this chapter's functionality:
+The `SchemaUIGeneratedData` interface in [`docs/components/schema-generator.tsx`](https://github.com/ComposioHQ/composio/blob/HEAD/docs/components/schema-generator.tsx) handles a key part of this chapter's functionality:
-```ts
- * Generate OG image URL for any page section
- */
-export function getOgImageUrl(_section: string, _slugs: string[], title?: string, _description?: string): string {
- const encodedTitle = encodeURIComponent(title ?? 'Composio Docs');
- return `https://og.composio.dev/api/og?title=${encodedTitle}`;
-}
+```tsx
+ );
-/**
- * Converts MDX content to clean markdown for AI agents.
- * Strips JSX components and converts them to plain text equivalents.
- */
-export function mdxToCleanMarkdown(content: string): string {
- let result = content;
+export interface SchemaUIGeneratedData {
+ $root: string;
+ refs: Record;
+}
- // Remove frontmatter
- result = result.replace(/^---[\s\S]*?---\n*/m, '');
+// Simplified schema type (subset of OpenAPI schema)
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type SimpleSchema = any;
- // Convert YouTube to link
- result = result.replace(
- //g,
- '[Video: $2](https://youtube.com/watch?v=$1)'
- );
+interface RenderContext {
+ renderMarkdown: (text: string) => ReactNode;
+ schema: {
+ getRawRef: (obj: object) => string | undefined;
+ };
+}
- // Convert Callout to blockquote - trim content to avoid empty lines
- result = result.replace(
- /]*title="([^"]*)"[^>]*>([\s\S]*?)<\/Callout>/g,
- (_, title, content) => `> **${title}**: ${content.trim()}`
- );
- result = result.replace(
- /]*>([\s\S]*?)<\/Callout>/g,
- (_, content) => `> ${content.trim()}`
- );
-```
+interface SchemaUIOptions {
+ root: SimpleSchema;
+ readOnly?: boolean;
+ writeOnly?: boolean;
+}
-This function is important because it defines how Composio Tutorial: Production Tool and Authentication Infrastructure for AI Agents implements the patterns covered in this chapter.
+export function generateSchemaData(
+ options: SchemaUIOptions,
+ ctx: RenderContext
+): SchemaUIGeneratedData {
+ const refs: Record = {};
+ let counter = 0;
+ const autoIds = new WeakMap();
-### `docs/lib/source.ts`
+```
-The `mdxToCleanMarkdown` function in [`docs/lib/source.ts`](https://github.com/ComposioHQ/composio/blob/HEAD/docs/lib/source.ts) handles a key part of this chapter's functionality:
+This interface is important because it defines how Composio Tutorial: Production Tool and Authentication Infrastructure for AI Agents implements the patterns covered in this chapter.
-```ts
- * Strips JSX components and converts them to plain text equivalents.
- */
-export function mdxToCleanMarkdown(content: string): string {
- let result = content;
+### `docs/components/schema-generator.tsx`
- // Remove frontmatter
- result = result.replace(/^---[\s\S]*?---\n*/m, '');
+The `RenderContext` interface in [`docs/components/schema-generator.tsx`](https://github.com/ComposioHQ/composio/blob/HEAD/docs/components/schema-generator.tsx) handles a key part of this chapter's functionality:
- // Convert YouTube to link
- result = result.replace(
- //g,
- '[Video: $2](https://youtube.com/watch?v=$1)'
- );
+```tsx
+type SimpleSchema = any;
- // Convert Callout to blockquote - trim content to avoid empty lines
- result = result.replace(
- /]*title="([^"]*)"[^>]*>([\s\S]*?)<\/Callout>/g,
- (_, title, content) => `> **${title}**: ${content.trim()}`
- );
- result = result.replace(
- /]*>([\s\S]*?)<\/Callout>/g,
- (_, content) => `> ${content.trim()}`
- );
+interface RenderContext {
+ renderMarkdown: (text: string) => ReactNode;
+ schema: {
+ getRawRef: (obj: object) => string | undefined;
+ };
+}
- // Remove Cards wrapper before processing individual Card tags
- // (prevents from being matched by ]*>/g, '');
+interface SchemaUIOptions {
+ root: SimpleSchema;
+ readOnly?: boolean;
+ writeOnly?: boolean;
+}
- // Convert Card - handle multiline and various attribute orders
- // Self-closing Cards with description attribute
- result = result.replace(
- //g,
+export function generateSchemaData(
+ options: SchemaUIOptions,
+ ctx: RenderContext
+): SchemaUIGeneratedData {
+ const refs: Record = {};
+ let counter = 0;
+ const autoIds = new WeakMap();
+
+ function getSchemaId(schema: SimpleSchema): string {
+ if (typeof schema === 'boolean') return String(schema);
+ if (typeof schema !== 'object' || schema === null) return `__${counter++}`;
+ const raw = ctx.schema.getRawRef(schema);
+ if (raw) return raw;
+ const prev = autoIds.get(schema);
+ if (prev) return prev;
+ const generated = `__${counter++}`;
+ autoIds.set(schema, generated);
```
-This function is important because it defines how Composio Tutorial: Production Tool and Authentication Infrastructure for AI Agents implements the patterns covered in this chapter.
+This interface is important because it defines how Composio Tutorial: Production Tool and Authentication Infrastructure for AI Agents implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[getOpenapiPages]
- B[getReferenceSource]
- C[getOgImageUrl]
- D[mdxToCleanMarkdown]
- E[stripTwoslashFromCodeBlocks]
+ A[generateInfoTags]
+ B[FieldBase]
+ C[SchemaUIGeneratedData]
+ D[RenderContext]
+ E[SchemaUIOptions]
A --> B
B --> C
C --> D
diff --git a/tutorials/composio-tutorial/08-migration-troubleshooting-and-production-ops.md b/tutorials/composio-tutorial/08-migration-troubleshooting-and-production-ops.md
index 24d32db8..542b6db1 100644
--- a/tutorials/composio-tutorial/08-migration-troubleshooting-and-production-ops.md
+++ b/tutorials/composio-tutorial/08-migration-troubleshooting-and-production-ops.md
@@ -44,147 +44,168 @@ The migration guide highlights key conceptual shifts (for example: ToolSets -> P
You now have a full lifecycle playbook for building, operating, and evolving Composio-backed agent integrations.
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `docs/lib/source.ts`
+### `python/scripts/generate-docs.py`
+
+The `docs` class in [`python/scripts/generate-docs.py`](https://github.com/ComposioHQ/composio/blob/HEAD/python/scripts/generate-docs.py) handles a key part of this chapter's functionality:
+
+```py
+
+Generates MDX documentation from Python source code using griffe.
+Output is written to the docs content directory.
+
+Run: cd python && uv run --with griffe python scripts/generate-docs.py
+"""
+
+from __future__ import annotations
-The `slugToDate` function in [`docs/lib/source.ts`](https://github.com/ComposioHQ/composio/blob/HEAD/docs/lib/source.ts) handles a key part of this chapter's functionality:
+import json
+import re
+import shutil
+from pathlib import Path
+from typing import Any
-```ts
-}
+try:
+ import griffe
+except ImportError:
+ print("Error: griffe not installed. Run: pip install griffe")
+ raise SystemExit(1)
-export function slugToDate(slug: string[]): string | null {
- // Convert ["2025", "12", "29"] to "2025-12-29"
- if (slug.length !== 3) return null;
- const [year, month, day] = slug;
- return `${year}-${month}-${day}`;
-}
+# Paths
+SCRIPT_DIR = Path(__file__).parent
+PACKAGE_DIR = SCRIPT_DIR.parent
+OUTPUT_DIR = (
+ PACKAGE_DIR.parent / "docs" / "content" / "reference" / "sdk-reference" / "python"
+)
+# GitHub base URL for source links
+GITHUB_BASE = "https://github.com/composiohq/composio/blob/next/python"
+
+# Decorators to document
```
-This function is important because it defines how Composio Tutorial: Production Tool and Authentication Infrastructure for AI Agents implements the patterns covered in this chapter.
+This class is important because it defines how Composio Tutorial: Production Tool and Authentication Infrastructure for AI Agents implements the patterns covered in this chapter.
+
+### `python/scripts/generate-docs.py`
+
+The `to_kebab_case` function in [`python/scripts/generate-docs.py`](https://github.com/ComposioHQ/composio/blob/HEAD/python/scripts/generate-docs.py) handles a key part of this chapter's functionality:
+
+```py
+
-### `docs/components/schema-generator.tsx`
-
-The `generateSchemaData` function in [`docs/components/schema-generator.tsx`](https://github.com/ComposioHQ/composio/blob/HEAD/docs/components/schema-generator.tsx) handles a key part of this chapter's functionality:
-
-```tsx
-}
-
-export function generateSchemaData(
- options: SchemaUIOptions,
- ctx: RenderContext
-): SchemaUIGeneratedData {
- const refs: Record = {};
- let counter = 0;
- const autoIds = new WeakMap();
-
- function getSchemaId(schema: SimpleSchema): string {
- if (typeof schema === 'boolean') return String(schema);
- if (typeof schema !== 'object' || schema === null) return `__${counter++}`;
- const raw = ctx.schema.getRawRef(schema);
- if (raw) return raw;
- const prev = autoIds.get(schema);
- if (prev) return prev;
- const generated = `__${counter++}`;
- autoIds.set(schema, generated);
- return generated;
- }
-
- function getTypeName(schema: SimpleSchema): string {
- if (!schema || typeof schema !== 'object') return 'any';
- if (schema.$ref) {
- const refName = schema.$ref.split('/').pop() || 'object';
- return refName;
- }
- if (schema.type === 'array' && schema.items) {
- return `${getTypeName(schema.items)}[]`;
- }
- if (schema.oneOf || schema.anyOf) {
+def to_kebab_case(name: str) -> str:
+ """Convert PascalCase to kebab-case."""
+ s1 = re.sub("(.)([A-Z][a-z]+)", r"\1-\2", name)
+ return re.sub("([a-z0-9])([A-Z])", r"\1-\2", s1).lower()
+
+
+def escape_yaml_string(s: str) -> str:
+ """Escape a string for YAML frontmatter."""
+ if any(c in s for c in [":", '"', "'", "\n", "#", "{", "}"]):
+ return f'"{s.replace(chr(34), chr(92) + chr(34))}"'
+ return s
+
+
+def get_source_link(obj: griffe.Object) -> str | None:
+ """Get GitHub source link for an object."""
+ if not hasattr(obj, "filepath") or not obj.filepath:
+ return None
+ try:
+ raw_filepath = obj.filepath
+ # Handle case where filepath might be a list (griffe edge case)
+ if isinstance(raw_filepath, list):
+ resolved_path: Path | None = raw_filepath[0] if raw_filepath else None
+ else:
+ resolved_path = raw_filepath
+ if not resolved_path:
+ return None
+ rel_path = resolved_path.relative_to(PACKAGE_DIR)
+ except ValueError:
+ return None
+ line = obj.lineno if hasattr(obj, "lineno") and obj.lineno else 1
```
This function is important because it defines how Composio Tutorial: Production Tool and Authentication Infrastructure for AI Agents implements the patterns covered in this chapter.
-### `docs/components/schema-generator.tsx`
-
-The `getSchemaId` function in [`docs/components/schema-generator.tsx`](https://github.com/ComposioHQ/composio/blob/HEAD/docs/components/schema-generator.tsx) handles a key part of this chapter's functionality:
-
-```tsx
- const autoIds = new WeakMap();
-
- function getSchemaId(schema: SimpleSchema): string {
- if (typeof schema === 'boolean') return String(schema);
- if (typeof schema !== 'object' || schema === null) return `__${counter++}`;
- const raw = ctx.schema.getRawRef(schema);
- if (raw) return raw;
- const prev = autoIds.get(schema);
- if (prev) return prev;
- const generated = `__${counter++}`;
- autoIds.set(schema, generated);
- return generated;
- }
-
- function getTypeName(schema: SimpleSchema): string {
- if (!schema || typeof schema !== 'object') return 'any';
- if (schema.$ref) {
- const refName = schema.$ref.split('/').pop() || 'object';
- return refName;
- }
- if (schema.type === 'array' && schema.items) {
- return `${getTypeName(schema.items)}[]`;
- }
- if (schema.oneOf || schema.anyOf) {
- const variants = schema.oneOf || schema.anyOf || [];
- return variants.map((v: SimpleSchema) => getTypeName(v)).join(' | ');
- }
- if (schema.enum) {
- return 'enum';
- }
- if (Array.isArray(schema.type)) {
- const isNullable = schema.type.includes('null');
+### `python/scripts/generate-docs.py`
+
+The `escape_yaml_string` function in [`python/scripts/generate-docs.py`](https://github.com/ComposioHQ/composio/blob/HEAD/python/scripts/generate-docs.py) handles a key part of this chapter's functionality:
+
+```py
+
+
+def escape_yaml_string(s: str) -> str:
+ """Escape a string for YAML frontmatter."""
+ if any(c in s for c in [":", '"', "'", "\n", "#", "{", "}"]):
+ return f'"{s.replace(chr(34), chr(92) + chr(34))}"'
+ return s
+
+
+def get_source_link(obj: griffe.Object) -> str | None:
+ """Get GitHub source link for an object."""
+ if not hasattr(obj, "filepath") or not obj.filepath:
+ return None
+ try:
+ raw_filepath = obj.filepath
+ # Handle case where filepath might be a list (griffe edge case)
+ if isinstance(raw_filepath, list):
+ resolved_path: Path | None = raw_filepath[0] if raw_filepath else None
+ else:
+ resolved_path = raw_filepath
+ if not resolved_path:
+ return None
+ rel_path = resolved_path.relative_to(PACKAGE_DIR)
+ except ValueError:
+ return None
+ line = obj.lineno if hasattr(obj, "lineno") and obj.lineno else 1
+ return f"{GITHUB_BASE}/{rel_path}#L{line}"
+
+
+def format_type(annotation: Any) -> str:
+ """Format a type annotation to readable string."""
+ if annotation is None:
```
This function is important because it defines how Composio Tutorial: Production Tool and Authentication Infrastructure for AI Agents implements the patterns covered in this chapter.
-### `docs/components/schema-generator.tsx`
-
-The `getTypeName` function in [`docs/components/schema-generator.tsx`](https://github.com/ComposioHQ/composio/blob/HEAD/docs/components/schema-generator.tsx) handles a key part of this chapter's functionality:
-
-```tsx
- }
-
- function getTypeName(schema: SimpleSchema): string {
- if (!schema || typeof schema !== 'object') return 'any';
- if (schema.$ref) {
- const refName = schema.$ref.split('/').pop() || 'object';
- return refName;
- }
- if (schema.type === 'array' && schema.items) {
- return `${getTypeName(schema.items)}[]`;
- }
- if (schema.oneOf || schema.anyOf) {
- const variants = schema.oneOf || schema.anyOf || [];
- return variants.map((v: SimpleSchema) => getTypeName(v)).join(' | ');
- }
- if (schema.enum) {
- return 'enum';
- }
- if (Array.isArray(schema.type)) {
- const isNullable = schema.type.includes('null');
- const types = schema.type.filter((t: string) => t !== 'null');
- const typeName = types.join(' | ') || 'any';
- return isNullable ? `nullable ${typeName}` : typeName;
- }
- return schema.type || 'any';
- }
-
- function isVisible(schema: SimpleSchema): boolean {
- if (!schema || typeof schema !== 'object') return true;
- if (schema.writeOnly) return options.writeOnly ?? false;
- if (schema.readOnly) return options.readOnly ?? false;
- return true;
+### `python/scripts/generate-docs.py`
+
+The `get_source_link` function in [`python/scripts/generate-docs.py`](https://github.com/ComposioHQ/composio/blob/HEAD/python/scripts/generate-docs.py) handles a key part of this chapter's functionality:
+
+```py
+
+
+def get_source_link(obj: griffe.Object) -> str | None:
+ """Get GitHub source link for an object."""
+ if not hasattr(obj, "filepath") or not obj.filepath:
+ return None
+ try:
+ raw_filepath = obj.filepath
+ # Handle case where filepath might be a list (griffe edge case)
+ if isinstance(raw_filepath, list):
+ resolved_path: Path | None = raw_filepath[0] if raw_filepath else None
+ else:
+ resolved_path = raw_filepath
+ if not resolved_path:
+ return None
+ rel_path = resolved_path.relative_to(PACKAGE_DIR)
+ except ValueError:
+ return None
+ line = obj.lineno if hasattr(obj, "lineno") and obj.lineno else 1
+ return f"{GITHUB_BASE}/{rel_path}#L{line}"
+
+
+def format_type(annotation: Any) -> str:
+ """Format a type annotation to readable string."""
+ if annotation is None:
+ return "Any"
+
+ type_str = str(annotation)
+ # Clean up common prefixes
+ type_str = type_str.replace("typing.", "").replace("typing_extensions.", "")
+ type_str = type_str.replace("composio.client.types.", "")
+ type_str = re.sub(r"\bt\.", "", type_str)
```
This function is important because it defines how Composio Tutorial: Production Tool and Authentication Infrastructure for AI Agents implements the patterns covered in this chapter.
@@ -194,11 +215,11 @@ This function is important because it defines how Composio Tutorial: Production
```mermaid
flowchart TD
- A[slugToDate]
- B[generateSchemaData]
- C[getSchemaId]
- D[getTypeName]
- E[isVisible]
+ A[docs]
+ B[to_kebab_case]
+ C[escape_yaml_string]
+ D[get_source_link]
+ E[format_type]
A --> B
B --> C
C --> D
diff --git a/tutorials/compound-engineering-plugin-tutorial/01-getting-started.md b/tutorials/compound-engineering-plugin-tutorial/01-getting-started.md
index 9d43fe4a..28dcea4c 100644
--- a/tutorials/compound-engineering-plugin-tutorial/01-getting-started.md
+++ b/tutorials/compound-engineering-plugin-tutorial/01-getting-started.md
@@ -46,8 +46,6 @@ You now have a working compound-engineering baseline in Claude Code.
Next: [Chapter 2: Compound Engineering Philosophy and Workflow Loop](02-compound-engineering-philosophy-and-workflow-loop.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `src/commands/install.ts`
@@ -55,9 +53,9 @@ Next: [Chapter 2: Compound Engineering Philosophy and Workflow Loop](02-compound
The `resolvePluginPath` function in [`src/commands/install.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/HEAD/src/commands/install.ts) handles a key part of this chapter's functionality:
```ts
- }
- const resolvedPlugin = await resolvePluginPath(String(args.plugin))
+ const branch = args.branch ? String(args.branch) : undefined
+ const resolvedPlugin = await resolvePluginPath(String(args.plugin), branch)
try {
const plugin = await loadClaudePlugin(resolvedPlugin.path)
@@ -175,12 +173,19 @@ This function is important because it defines how Compound Engineering Plugin Tu
### `src/commands/install.ts`
-The `resolveGitHubPluginPath` function in [`src/commands/install.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/HEAD/src/commands/install.ts) handles a key part of this chapter's functionality:
+The `resolveBundledPluginPath` function in [`src/commands/install.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/HEAD/src/commands/install.ts) handles a key part of this chapter's functionality:
```ts
+ // Skip bundled plugins when a branch is specified — the user wants a specific remote version
+ if (!branch) {
+ const bundledPluginPath = await resolveBundledPluginPath(input)
+ if (bundledPluginPath) {
+ return { path: bundledPluginPath }
+ }
+ }
- // Otherwise, always fetch the latest from GitHub
- return await resolveGitHubPluginPath(input)
+ // Otherwise, fetch from GitHub (optionally from a specific branch)
+ return await resolveGitHubPluginPath(input, branch)
}
function parseExtraTargets(value: unknown): string[] {
@@ -201,15 +206,8 @@ function resolveOutputRoot(value: unknown): string {
return path.join(os.homedir(), ".config", "opencode")
}
-async function resolveGitHubPluginPath(pluginName: string): Promise {
- const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "compound-plugin-"))
- const source = resolveGitHubSource()
- try {
- await cloneGitHubRepo(source, tempRoot)
- } catch (error) {
- await fs.rm(tempRoot, { recursive: true, force: true })
- throw error
- }
+async function resolveBundledPluginPath(pluginName: string): Promise {
+ const bundledRoot = fileURLToPath(new URL("../../plugins/", import.meta.url))
```
This function is important because it defines how Compound Engineering Plugin Tutorial: Compounding Agent Workflows Across Toolchains implements the patterns covered in this chapter.
@@ -222,8 +220,8 @@ flowchart TD
A[resolvePluginPath]
B[parseExtraTargets]
C[resolveOutputRoot]
- D[resolveGitHubPluginPath]
- E[resolveGitHubSource]
+ D[resolveBundledPluginPath]
+ E[resolveGitHubPluginPath]
A --> B
B --> C
C --> D
diff --git a/tutorials/compound-engineering-plugin-tutorial/02-compound-engineering-philosophy-and-workflow-loop.md b/tutorials/compound-engineering-plugin-tutorial/02-compound-engineering-philosophy-and-workflow-loop.md
index 8df0e9dd..0b85c226 100644
--- a/tutorials/compound-engineering-plugin-tutorial/02-compound-engineering-philosophy-and-workflow-loop.md
+++ b/tutorials/compound-engineering-plugin-tutorial/02-compound-engineering-philosophy-and-workflow-loop.md
@@ -50,12 +50,51 @@ You now understand how the workflow loop creates durable engineering leverage.
Next: [Chapter 3: Architecture of Agents, Commands, and Skills](03-architecture-of-agents-commands-and-skills.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `src/converters/claude-to-opencode.ts`
+The `renderHookStatements` function in [`src/converters/claude-to-opencode.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/HEAD/src/converters/claude-to-opencode.ts) handles a key part of this chapter's functionality:
+
+```ts
+ const statements: string[] = []
+ for (const matcher of matchers) {
+ statements.push(...renderHookStatements(matcher, options.useToolMatcher))
+ }
+ const rendered = statements.map((line) => ` ${line}`).join("\n")
+ const wrapped = options.requireError
+ ? ` if (input?.error) {\n${statements.map((line) => ` ${line}`).join("\n")}\n }`
+ : rendered
+
+ // Wrap tool.execute.before handlers in try-catch to prevent a failing hook
+ // from crashing parallel tool call batches (causes API 400 errors).
+ // See: https://github.com/EveryInc/compound-engineering-plugin/issues/85
+ const isPreToolUse = event === "tool.execute.before"
+ const note = options.note ? ` // ${options.note}\n` : ""
+ if (isPreToolUse) {
+ return ` "${event}": async (input) => {\n${note} try {\n ${wrapped}\n } catch (err) {\n console.error("[hook] ${event} error (non-fatal):", err)\n }\n }`
+ }
+ return ` "${event}": async (input) => {\n${note}${wrapped}\n }`
+}
+
+function renderHookStatements(
+ matcher: ClaudeHooks["hooks"][string][number],
+ useToolMatcher: boolean,
+): string[] {
+ if (!matcher.hooks || matcher.hooks.length === 0) return []
+ const tools = matcher.matcher
+ ? matcher.matcher
+ .split("|")
+ .map((tool) => tool.trim().toLowerCase())
+ .filter(Boolean)
+ : []
+
+```
+
+This function is important because it defines how Compound Engineering Plugin Tutorial: Compounding Agent Workflows Across Toolchains implements the patterns covered in this chapter.
+
+### `src/converters/claude-to-opencode.ts`
+
The `rewriteClaudePaths` function in [`src/converters/claude-to-opencode.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/HEAD/src/converters/claude-to-opencode.ts) handles a key part of this chapter's functionality:
```ts
@@ -79,7 +118,7 @@ function convertCommands(commands: ClaudeCommand[]): OpenCodeCommandFile[] {
description: command.description,
}
if (command.model && command.model !== "inherit") {
- frontmatter.model = normalizeModel(command.model)
+ frontmatter.model = normalizeModelWithProvider(command.model)
}
const content = formatFrontmatter(frontmatter, rewriteClaudePaths(command.body))
files.push({ name: command.name, content })
@@ -97,41 +136,41 @@ This function is important because it defines how Compound Engineering Plugin Tu
### `src/converters/claude-to-opencode.ts`
-The `normalizeModel` function in [`src/converters/claude-to-opencode.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/HEAD/src/converters/claude-to-opencode.ts) handles a key part of this chapter's functionality:
+The `transformSkillContentForOpenCode` function in [`src/converters/claude-to-opencode.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/HEAD/src/converters/claude-to-opencode.ts) handles a key part of this chapter's functionality:
```ts
+ * See #477.
+ */
+export function transformSkillContentForOpenCode(body: string): string {
+ let result = rewriteClaudePaths(body)
+ // Rewrite 3-segment FQ agent refs: plugin:category:agent-name -> agent-name.
+ // Boundary assertions prevent partial matching on 4+ segment names
+ // (e.g. `a:b:c:d` would otherwise produce `c:d` or `a:d`).
+ // The `/` in the lookbehind prevents rewriting slash commands like
+ // `/team:ops:deploy` — agent names are never preceded by `/`.
+ result = result.replace(
+ /(? = {
- description: command.description,
- }
- if (command.model && command.model !== "inherit") {
- frontmatter.model = normalizeModel(command.model)
- }
```
This function is important because it defines how Compound Engineering Plugin Tutorial: Compounding Agent Workflows Across Toolchains implements the patterns covered in this chapter.
@@ -177,57 +216,16 @@ const HOOK_EVENT_MAP: Record = {
This function is important because it defines how Compound Engineering Plugin Tutorial: Compounding Agent Workflows Across Toolchains implements the patterns covered in this chapter.
-### `src/converters/claude-to-opencode.ts`
-
-The `applyPermissions` function in [`src/converters/claude-to-opencode.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/HEAD/src/converters/claude-to-opencode.ts) handles a key part of this chapter's functionality:
-
-```ts
- }
-
- applyPermissions(config, plugin.commands, options.permissions)
-
- return {
- config,
- agents: agentFiles,
- commandFiles: cmdFiles,
- plugins,
- skillDirs: plugin.skills.map((skill) => ({ sourceDir: skill.sourceDir, name: skill.name })),
- }
-}
-
-function convertAgent(agent: ClaudeAgent, options: ClaudeToOpenCodeOptions) {
- const frontmatter: Record = {
- description: agent.description,
- mode: options.agentMode,
- }
-
- if (agent.model && agent.model !== "inherit") {
- frontmatter.model = normalizeModel(agent.model)
- }
-
- if (options.inferTemperature) {
- const temperature = inferTemperature(agent)
- if (temperature !== undefined) {
- frontmatter.temperature = temperature
- }
- }
-
- const content = formatFrontmatter(frontmatter, rewriteClaudePaths(agent.body))
-
-```
-
-This function is important because it defines how Compound Engineering Plugin Tutorial: Compounding Agent Workflows Across Toolchains implements the patterns covered in this chapter.
-
## How These Components Connect
```mermaid
flowchart TD
- A[rewriteClaudePaths]
- B[normalizeModel]
- C[inferTemperature]
- D[applyPermissions]
- E[normalizeTool]
+ A[renderHookStatements]
+ B[rewriteClaudePaths]
+ C[transformSkillContentForOpenCode]
+ D[inferTemperature]
+ E[applyPermissions]
A --> B
B --> C
C --> D
diff --git a/tutorials/compound-engineering-plugin-tutorial/03-architecture-of-agents-commands-and-skills.md b/tutorials/compound-engineering-plugin-tutorial/03-architecture-of-agents-commands-and-skills.md
index 2d7e28e6..613d90ee 100644
--- a/tutorials/compound-engineering-plugin-tutorial/03-architecture-of-agents-commands-and-skills.md
+++ b/tutorials/compound-engineering-plugin-tutorial/03-architecture-of-agents-commands-and-skills.md
@@ -50,8 +50,6 @@ You now have a clear architecture map for plugin capability selection.
Next: [Chapter 4: Multi-Provider Conversion and Config Sync](04-multi-provider-conversion-and-config-sync.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `src/converters/claude-to-codex.ts`
diff --git a/tutorials/compound-engineering-plugin-tutorial/04-multi-provider-conversion-and-config-sync.md b/tutorials/compound-engineering-plugin-tutorial/04-multi-provider-conversion-and-config-sync.md
index 2b66a992..844d313a 100644
--- a/tutorials/compound-engineering-plugin-tutorial/04-multi-provider-conversion-and-config-sync.md
+++ b/tutorials/compound-engineering-plugin-tutorial/04-multi-provider-conversion-and-config-sync.md
@@ -54,8 +54,6 @@ You now understand how to move compound workflows across different coding-agent
Next: [Chapter 5: MCP Integrations and Browser Automation](05-mcp-integrations-and-browser-automation.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `src/parsers/claude.ts`
@@ -99,100 +97,52 @@ async function loadMcpServers(
This function is important because it defines how Compound Engineering Plugin Tutorial: Compounding Agent Workflows Across Toolchains implements the patterns covered in this chapter.
-### `src/commands/convert.ts`
+### `src/release/metadata.ts`
-The `parseExtraTargets` function in [`src/commands/convert.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/HEAD/src/commands/convert.ts) handles a key part of this chapter's functionality:
+The `resolveExpectedVersion` function in [`src/release/metadata.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/HEAD/src/release/metadata.ts) handles a key part of this chapter's functionality:
```ts
- console.log(`Converted ${plugin.manifest.name} to ${targetName} at ${primaryOutputRoot}`)
-
- const extraTargets = parseExtraTargets(args.also)
- const allTargets = [targetName, ...extraTargets]
- for (const extra of extraTargets) {
- const handler = targets[extra]
- if (!handler) {
- console.warn(`Skipping unknown target: ${extra}`)
- continue
- }
- if (!handler.implemented) {
- console.warn(`Skipping ${extra}: not implemented yet.`)
- continue
- }
- const extraBundle = handler.convert(plugin, options)
- if (!extraBundle) {
- console.warn(`Skipping ${extra}: no output returned.`)
- continue
- }
- const extraRoot = resolveTargetOutputRoot({
- targetName: extra,
- outputRoot: path.join(outputRoot, extra),
- codexHome,
- piHome,
- openclawHome,
- qwenHome,
- pluginName: plugin.manifest.name,
- hasExplicitOutput,
- scope: handler.defaultScope,
- })
- await handler.write(extraRoot, extraBundle, handler.defaultScope)
- console.log(`Converted ${plugin.manifest.name} to ${extra} at ${extraRoot}`)
-```
-
-This function is important because it defines how Compound Engineering Plugin Tutorial: Compounding Agent Workflows Across Toolchains implements the patterns covered in this chapter.
-
-### `src/commands/convert.ts`
+ "AI-powered development tools that get smarter with every use. Make each unit of engineering work easier than the last."
-The `resolveOutputRoot` function in [`src/commands/convert.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/HEAD/src/commands/convert.ts) handles a key part of this chapter's functionality:
+function resolveExpectedVersion(
+ explicitVersion: string | undefined,
+ fallbackVersion: string,
+): string {
+ return explicitVersion ?? fallbackVersion
+}
-```ts
+export async function countMarkdownFiles(root: string): Promise {
+ const entries = await fs.readdir(root, { withFileTypes: true })
+ let total = 0
- const plugin = await loadClaudePlugin(String(args.source))
- const outputRoot = resolveOutputRoot(args.output)
- const hasExplicitOutput = Boolean(args.output && String(args.output).trim())
- const codexHome = resolveTargetHome(args.codexHome, path.join(os.homedir(), ".codex"))
- const piHome = resolveTargetHome(args.piHome, path.join(os.homedir(), ".pi", "agent"))
- const openclawHome = resolveTargetHome(args.openclawHome, path.join(os.homedir(), ".openclaw", "extensions"))
- const qwenHome = resolveTargetHome(args.qwenHome, path.join(os.homedir(), ".qwen", "extensions"))
-
- const options = {
- agentMode: String(args.agentMode) === "primary" ? "primary" : "subagent",
- inferTemperature: Boolean(args.inferTemperature),
- permissions: permissions as PermissionMode,
+ for (const entry of entries) {
+ const fullPath = path.join(root, entry.name)
+ if (entry.isDirectory()) {
+ total += await countMarkdownFiles(fullPath)
+ continue
}
+ if (entry.isFile() && entry.name.endsWith(".md")) {
+ total += 1
+ }
+ }
- if (targetName === "all") {
- const detected = await detectInstalledTools()
- const activeTargets = detected.filter((t) => t.detected)
-
- if (activeTargets.length === 0) {
- console.log("No AI coding tools detected. Install at least one tool first.")
- return
- }
+ return total
+}
- console.log(`Detected ${activeTargets.length} tool(s):`)
- for (const tool of detected) {
- console.log(` ${tool.detected ? "✓" : "✗"} ${tool.name} — ${tool.reason}`)
- }
+export async function countSkillDirectories(root: string): Promise {
+ const entries = await fs.readdir(root, { withFileTypes: true })
+ let total = 0
- for (const tool of activeTargets) {
- const handler = targets[tool.name]
- if (!handler || !handler.implemented) {
+ for (const entry of entries) {
```
This function is important because it defines how Compound Engineering Plugin Tutorial: Compounding Agent Workflows Across Toolchains implements the patterns covered in this chapter.
### `src/release/metadata.ts`
-The `resolveExpectedVersion` function in [`src/release/metadata.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/HEAD/src/release/metadata.ts) handles a key part of this chapter's functionality:
+The `countMarkdownFiles` function in [`src/release/metadata.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/HEAD/src/release/metadata.ts) handles a key part of this chapter's functionality:
```ts
- "AI-powered development tools that get smarter with every use. Make each unit of engineering work easier than the last."
-
-function resolveExpectedVersion(
- explicitVersion: string | undefined,
- fallbackVersion: string,
-): string {
- return explicitVersion ?? fallbackVersion
}
export async function countMarkdownFiles(root: string): Promise {
@@ -218,6 +168,54 @@ export async function countSkillDirectories(root: string): Promise {
let total = 0
for (const entry of entries) {
+ if (!entry.isDirectory()) continue
+ const skillPath = path.join(root, entry.name, "SKILL.md")
+ try {
+ await fs.access(skillPath)
+ total += 1
+ } catch {
+ // Ignore non-skill directories.
+```
+
+This function is important because it defines how Compound Engineering Plugin Tutorial: Compounding Agent Workflows Across Toolchains implements the patterns covered in this chapter.
+
+### `src/release/metadata.ts`
+
+The `countSkillDirectories` function in [`src/release/metadata.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/HEAD/src/release/metadata.ts) handles a key part of this chapter's functionality:
+
+```ts
+}
+
+export async function countSkillDirectories(root: string): Promise {
+ const entries = await fs.readdir(root, { withFileTypes: true })
+ let total = 0
+
+ for (const entry of entries) {
+ if (!entry.isDirectory()) continue
+ const skillPath = path.join(root, entry.name, "SKILL.md")
+ try {
+ await fs.access(skillPath)
+ total += 1
+ } catch {
+ // Ignore non-skill directories.
+ }
+ }
+
+ return total
+}
+
+export async function countMcpServers(pluginRoot: string): Promise {
+ const mcpPath = path.join(pluginRoot, ".mcp.json")
+ try {
+ const manifest = await readJson<{ mcpServers?: Record }>(mcpPath)
+ return Object.keys(manifest.mcpServers ?? {}).length
+ } catch (err: unknown) {
+ if ((err as NodeJS.ErrnoException).code === "ENOENT") return 0
+ throw err
+ }
+}
+
+export async function getCompoundEngineeringCounts(root: string): Promise {
```
This function is important because it defines how Compound Engineering Plugin Tutorial: Compounding Agent Workflows Across Toolchains implements the patterns covered in this chapter.
@@ -228,10 +226,10 @@ This function is important because it defines how Compound Engineering Plugin Tu
```mermaid
flowchart TD
A[resolveWithinRoot]
- B[parseExtraTargets]
- C[resolveOutputRoot]
- D[resolveExpectedVersion]
- E[countMarkdownFiles]
+ B[resolveExpectedVersion]
+ C[countMarkdownFiles]
+ D[countSkillDirectories]
+ E[countMcpServers]
A --> B
B --> C
C --> D
diff --git a/tutorials/compound-engineering-plugin-tutorial/05-mcp-integrations-and-browser-automation.md b/tutorials/compound-engineering-plugin-tutorial/05-mcp-integrations-and-browser-automation.md
index 512e1927..650bdc94 100644
--- a/tutorials/compound-engineering-plugin-tutorial/05-mcp-integrations-and-browser-automation.md
+++ b/tutorials/compound-engineering-plugin-tutorial/05-mcp-integrations-and-browser-automation.md
@@ -46,170 +46,168 @@ You now know how MCP and browser capabilities fit into compound engineering work
Next: [Chapter 6: Daily Operations and Quality Gates](06-daily-operations-and-quality-gates.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/converters/claude-to-windsurf.ts`
+### `src/release/components.ts`
-The `convertCommandToWorkflow` function in [`src/converters/claude-to-windsurf.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/HEAD/src/converters/claude-to-windsurf.ts) handles a key part of this chapter's functionality:
+The `resolveComponentWarnings` function in [`src/release/components.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/HEAD/src/release/components.ts) handles a key part of this chapter's functionality:
```ts
- const usedCommandNames = new Set()
- const commandWorkflows = plugin.commands.map((command) =>
- convertCommandToWorkflow(command, knownAgentNames, usedCommandNames),
- )
+}
- // Build MCP config
- const mcpConfig = buildMcpConfig(plugin.mcpServers)
+export function resolveComponentWarnings(
+ intent: ParsedReleaseIntent,
+ detectedComponents: ReleaseComponent[],
+): string[] {
+ const warnings: string[] = []
- // Warn about hooks
- if (plugin.hooks && Object.keys(plugin.hooks.hooks).length > 0) {
- console.warn(
- "Warning: Windsurf has no hooks equivalent. Hooks were skipped during conversion.",
- )
+ if (!intent.type) {
+ warnings.push("Title does not match the expected conventional format: (optional-scope): description")
+ return warnings
}
- return { agentSkills, commandWorkflows, skillDirs, mcpConfig }
-}
+ if (intent.scope) {
+ const normalized = intent.scope.trim().toLowerCase()
+ const expected = SCOPES_TO_COMPONENTS[normalized]
+ if (expected && detectedComponents.length > 0 && !detectedComponents.includes(expected)) {
+ warnings.push(
+ `Optional scope "${intent.scope}" does not match the detected component set: ${detectedComponents.join(", ")}`,
+ )
+ }
+ }
-function convertAgentToSkill(
- agent: ClaudeAgent,
- knownAgentNames: string[],
- usedNames: Set,
-): WindsurfGeneratedSkill {
- const name = uniqueName(normalizeName(agent.name), usedNames)
- const description = sanitizeDescription(
- agent.description ?? `Converted from Claude agent ${agent.name}`,
- )
+ if (detectedComponents.length === 0 && inferBumpFromIntent(intent) !== null) {
+ warnings.push("No releasable component files were detected for this change")
+ }
- let body = transformContentForWindsurf(agent.body.trim(), knownAgentNames)
- if (agent.capabilities && agent.capabilities.length > 0) {
- const capabilities = agent.capabilities.map((c) => `- ${c}`).join("\n")
- body = `## Capabilities\n${capabilities}\n\n${body}`.trim()
+ return warnings
+}
+
+export function applyOverride(
+ inferred: BumpLevel | null,
```
This function is important because it defines how Compound Engineering Plugin Tutorial: Compounding Agent Workflows Across Toolchains implements the patterns covered in this chapter.
-### `src/converters/claude-to-windsurf.ts`
+### `src/release/components.ts`
-The `transformContentForWindsurf` function in [`src/converters/claude-to-windsurf.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/HEAD/src/converters/claude-to-windsurf.ts) handles a key part of this chapter's functionality:
+The `applyOverride` function in [`src/release/components.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/HEAD/src/release/components.ts) handles a key part of this chapter's functionality:
```ts
- )
-
- let body = transformContentForWindsurf(agent.body.trim(), knownAgentNames)
- if (agent.capabilities && agent.capabilities.length > 0) {
- const capabilities = agent.capabilities.map((c) => `- ${c}`).join("\n")
- body = `## Capabilities\n${capabilities}\n\n${body}`.trim()
- }
- if (body.length === 0) {
- body = `Instructions converted from the ${agent.name} agent.`
- }
+}
- const content = formatFrontmatter({ name, description }, `# ${name}\n\n${body}`) + "\n"
- return { name, content }
+export function applyOverride(
+ inferred: BumpLevel | null,
+ override: BumpOverride,
+): BumpLevel | null {
+ if (override === "auto") return inferred
+ return override
}
-function convertCommandToWorkflow(
- command: ClaudeCommand,
- knownAgentNames: string[],
- usedNames: Set,
-): WindsurfWorkflow {
- const name = uniqueName(normalizeName(command.name), usedNames)
- const description = sanitizeDescription(
- command.description ?? `Converted from Claude command ${command.name}`,
- )
+export function bumpVersion(version: string, bump: BumpLevel | null): string | null {
+ if (!bump) return null
- let body = transformContentForWindsurf(command.body.trim(), knownAgentNames)
- if (command.argumentHint) {
- body = `> Arguments: ${command.argumentHint}\n\n${body}`
+ const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(version)
+ if (!match) {
+ throw new Error(`Unsupported version format: ${version}`)
}
- if (body.length === 0) {
- body = `Instructions converted from the ${command.name} command.`
+
+ const major = Number(match[1])
+ const minor = Number(match[2])
+ const patch = Number(match[3])
+
+ switch (bump) {
+ case "major":
+ return `${major + 1}.0.0`
+ case "minor":
+ return `${major}.${minor + 1}.0`
+ case "patch":
+ return `${major}.${minor}.${patch + 1}`
}
+}
+
```
This function is important because it defines how Compound Engineering Plugin Tutorial: Compounding Agent Workflows Across Toolchains implements the patterns covered in this chapter.
-### `src/converters/claude-to-windsurf.ts`
+### `src/release/components.ts`
-The `buildMcpConfig` function in [`src/converters/claude-to-windsurf.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/HEAD/src/converters/claude-to-windsurf.ts) handles a key part of this chapter's functionality:
+The `bumpVersion` function in [`src/release/components.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/HEAD/src/release/components.ts) handles a key part of this chapter's functionality:
```ts
+}
- // Build MCP config
- const mcpConfig = buildMcpConfig(plugin.mcpServers)
+export function bumpVersion(version: string, bump: BumpLevel | null): string | null {
+ if (!bump) return null
- // Warn about hooks
- if (plugin.hooks && Object.keys(plugin.hooks.hooks).length > 0) {
- console.warn(
- "Warning: Windsurf has no hooks equivalent. Hooks were skipped during conversion.",
- )
+ const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(version)
+ if (!match) {
+ throw new Error(`Unsupported version format: ${version}`)
}
- return { agentSkills, commandWorkflows, skillDirs, mcpConfig }
+ const major = Number(match[1])
+ const minor = Number(match[2])
+ const patch = Number(match[3])
+
+ switch (bump) {
+ case "major":
+ return `${major + 1}.0.0`
+ case "minor":
+ return `${major}.${minor + 1}.0`
+ case "patch":
+ return `${major}.${minor}.${patch + 1}`
+ }
}
-function convertAgentToSkill(
- agent: ClaudeAgent,
- knownAgentNames: string[],
- usedNames: Set,
-): WindsurfGeneratedSkill {
- const name = uniqueName(normalizeName(agent.name), usedNames)
- const description = sanitizeDescription(
- agent.description ?? `Converted from Claude agent ${agent.name}`,
- )
+export async function loadCurrentVersions(cwd = process.cwd()): Promise {
+ const root = await readJson(`${cwd}/package.json`)
+ const ce = await readJson(`${cwd}/plugins/compound-engineering/.claude-plugin/plugin.json`)
+ const codingTutor = await readJson(`${cwd}/plugins/coding-tutor/.claude-plugin/plugin.json`)
+ const marketplace = await readJson(`${cwd}/.claude-plugin/marketplace.json`)
+ const cursorMarketplace = await readJson(`${cwd}/.cursor-plugin/marketplace.json`)
- let body = transformContentForWindsurf(agent.body.trim(), knownAgentNames)
- if (agent.capabilities && agent.capabilities.length > 0) {
- const capabilities = agent.capabilities.map((c) => `- ${c}`).join("\n")
- body = `## Capabilities\n${capabilities}\n\n${body}`.trim()
- }
- if (body.length === 0) {
- body = `Instructions converted from the ${agent.name} agent.`
- }
+ return {
```
This function is important because it defines how Compound Engineering Plugin Tutorial: Compounding Agent Workflows Across Toolchains implements the patterns covered in this chapter.
-### `src/converters/claude-to-windsurf.ts`
+### `src/release/components.ts`
-The `normalizeName` function in [`src/converters/claude-to-windsurf.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/HEAD/src/converters/claude-to-windsurf.ts) handles a key part of this chapter's functionality:
+The `loadCurrentVersions` function in [`src/release/components.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/HEAD/src/release/components.ts) handles a key part of this chapter's functionality:
```ts
- _options: ClaudeToWindsurfOptions,
-): WindsurfBundle {
- const knownAgentNames = plugin.agents.map((a) => normalizeName(a.name))
-
- // Pass-through skills (collected first so agent skill names can deduplicate against them)
- const skillDirs = plugin.skills.map((skill) => ({
- name: skill.name,
- sourceDir: skill.sourceDir,
- }))
-
- // Convert agents to skills (seed usedNames with pass-through skill names)
- const usedSkillNames = new Set(skillDirs.map((s) => s.name))
- const agentSkills = plugin.agents.map((agent) =>
- convertAgentToSkill(agent, knownAgentNames, usedSkillNames),
- )
-
- // Convert commands to workflows
- const usedCommandNames = new Set()
- const commandWorkflows = plugin.commands.map((command) =>
- convertCommandToWorkflow(command, knownAgentNames, usedCommandNames),
- )
-
- // Build MCP config
- const mcpConfig = buildMcpConfig(plugin.mcpServers)
+}
- // Warn about hooks
- if (plugin.hooks && Object.keys(plugin.hooks.hooks).length > 0) {
- console.warn(
- "Warning: Windsurf has no hooks equivalent. Hooks were skipped during conversion.",
- )
+export async function loadCurrentVersions(cwd = process.cwd()): Promise {
+ const root = await readJson(`${cwd}/package.json`)
+ const ce = await readJson(`${cwd}/plugins/compound-engineering/.claude-plugin/plugin.json`)
+ const codingTutor = await readJson(`${cwd}/plugins/coding-tutor/.claude-plugin/plugin.json`)
+ const marketplace = await readJson(`${cwd}/.claude-plugin/marketplace.json`)
+ const cursorMarketplace = await readJson(`${cwd}/.cursor-plugin/marketplace.json`)
+
+ return {
+ cli: root.version,
+ "compound-engineering": ce.version,
+ "coding-tutor": codingTutor.version,
+ marketplace: marketplace.metadata.version,
+ "cursor-marketplace": cursorMarketplace.metadata.version,
}
+}
+export async function buildReleasePreview(options: {
+ title: string
+ files: string[]
+ overrides?: Partial>
+ cwd?: string
+}): Promise {
+ const intent = parseReleaseIntent(options.title)
+ const inferredBump = inferBumpFromIntent(intent)
+ const componentFilesMap = detectComponentsFromFiles(options.files)
+ const currentVersions = await loadCurrentVersions(options.cwd)
+
+ const detectedComponents = RELEASE_COMPONENTS.filter(
+ (component) => (componentFilesMap.get(component) ?? []).length > 0,
+ )
```
This function is important because it defines how Compound Engineering Plugin Tutorial: Compounding Agent Workflows Across Toolchains implements the patterns covered in this chapter.
@@ -219,11 +217,11 @@ This function is important because it defines how Compound Engineering Plugin Tu
```mermaid
flowchart TD
- A[convertCommandToWorkflow]
- B[transformContentForWindsurf]
- C[buildMcpConfig]
- D[normalizeName]
- E[sanitizeDescription]
+ A[resolveComponentWarnings]
+ B[applyOverride]
+ C[bumpVersion]
+ D[loadCurrentVersions]
+ E[buildReleasePreview]
A --> B
B --> C
C --> D
diff --git a/tutorials/compound-engineering-plugin-tutorial/06-daily-operations-and-quality-gates.md b/tutorials/compound-engineering-plugin-tutorial/06-daily-operations-and-quality-gates.md
index 51e00c2c..2bfa40f5 100644
--- a/tutorials/compound-engineering-plugin-tutorial/06-daily-operations-and-quality-gates.md
+++ b/tutorials/compound-engineering-plugin-tutorial/06-daily-operations-and-quality-gates.md
@@ -45,170 +45,145 @@ You now have a repeatable operations loop with built-in quality controls.
Next: [Chapter 7: Troubleshooting and Runtime Maintenance](07-troubleshooting-and-runtime-maintenance.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/converters/claude-to-pi.ts`
+### `src/sync/commands.ts`
-The `convertAgent` function in [`src/converters/claude-to-pi.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/HEAD/src/converters/claude-to-pi.ts) handles a key part of this chapter's functionality:
+The `syncQwenCommands` function in [`src/sync/commands.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/HEAD/src/sync/commands.ts) handles a key part of this chapter's functionality:
```ts
- .map((command) => convertPrompt(command, promptNames))
-
- const generatedSkills = plugin.agents.map((agent) => convertAgent(agent, usedSkillNames))
-
- const extensions = [
- {
- name: "compound-engineering-compat.ts",
- content: PI_COMPAT_EXTENSION_SOURCE,
- },
- ]
-
- return {
- prompts,
- skillDirs: plugin.skills.map((skill) => ({
- name: skill.name,
- sourceDir: skill.sourceDir,
- })),
- generatedSkills,
- extensions,
- mcporterConfig: plugin.mcpServers ? convertMcpToMcporter(plugin.mcpServers) : undefined,
- }
}
-function convertPrompt(command: ClaudeCommand, usedNames: Set) {
- const name = uniqueName(normalizeName(command.name), usedNames)
- const frontmatter: Record = {
- description: command.description,
- "argument-hint": command.argumentHint,
+export async function syncQwenCommands(
+ config: ClaudeHomeConfig,
+ outputRoot: string,
+): Promise {
+ if (!hasCommands(config)) return
+
+ const plugin = buildClaudeHomePlugin(config)
+ const bundle = convertClaudeToQwen(plugin, DEFAULT_QWEN_SYNC_OPTIONS)
+
+ for (const commandFile of bundle.commandFiles) {
+ const parts = commandFile.name.split(":")
+ if (parts.length > 1) {
+ const nestedDir = path.join(outputRoot, "commands", ...parts.slice(0, -1))
+ await writeText(path.join(nestedDir, `${parts[parts.length - 1]}.md`), commandFile.content + "\n")
+ continue
+ }
+
+ await writeText(path.join(outputRoot, "commands", `${commandFile.name}.md`), commandFile.content + "\n")
}
+}
+
+export function warnUnsupportedOpenClawCommands(config: ClaudeHomeConfig): void {
+ if (!hasCommands(config)) return
+
+ console.warn(
+ "Warning: OpenClaw personal command sync is skipped because this sync target currently has no documented user-level command surface.",
+ )
+}
- let body = transformContentForPi(command.body)
- body = appendCompatibilityNoteIfNeeded(body)
```
This function is important because it defines how Compound Engineering Plugin Tutorial: Compounding Agent Workflows Across Toolchains implements the patterns covered in this chapter.
-### `src/converters/claude-to-pi.ts`
+### `src/sync/commands.ts`
-The `transformContentForPi` function in [`src/converters/claude-to-pi.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/HEAD/src/converters/claude-to-pi.ts) handles a key part of this chapter's functionality:
+The `warnUnsupportedOpenClawCommands` function in [`src/sync/commands.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/HEAD/src/sync/commands.ts) handles a key part of this chapter's functionality:
```ts
- }
-
- let body = transformContentForPi(command.body)
- body = appendCompatibilityNoteIfNeeded(body)
-
- return {
- name,
- content: formatFrontmatter(frontmatter, body.trim()),
- }
}
-function convertAgent(agent: ClaudeAgent, usedNames: Set): PiGeneratedSkill {
- const name = uniqueName(normalizeName(agent.name), usedNames)
- const description = sanitizeDescription(
- agent.description ?? `Converted from Claude agent ${agent.name}`,
- )
-
- const frontmatter: Record = {
- name,
- description,
- }
+export function warnUnsupportedOpenClawCommands(config: ClaudeHomeConfig): void {
+ if (!hasCommands(config)) return
- const sections: string[] = []
- if (agent.capabilities && agent.capabilities.length > 0) {
- sections.push(`## Capabilities\n${agent.capabilities.map((capability) => `- ${capability}`).join("\n")}`)
- }
+ console.warn(
+ "Warning: OpenClaw personal command sync is skipped because this sync target currently has no documented user-level command surface.",
+ )
+}
- const body = [
- ...sections,
- agent.body.trim().length > 0
- ? agent.body.trim()
- : `Instructions converted from the ${agent.name} agent.`,
```
This function is important because it defines how Compound Engineering Plugin Tutorial: Compounding Agent Workflows Across Toolchains implements the patterns covered in this chapter.
-### `src/converters/claude-to-pi.ts`
+### `src/converters/claude-to-droid.ts`
-The `appendCompatibilityNoteIfNeeded` function in [`src/converters/claude-to-pi.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/HEAD/src/converters/claude-to-pi.ts) handles a key part of this chapter's functionality:
+The `convertClaudeToDroid` function in [`src/converters/claude-to-droid.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/HEAD/src/converters/claude-to-droid.ts) handles a key part of this chapter's functionality:
```ts
-
- let body = transformContentForPi(command.body)
- body = appendCompatibilityNoteIfNeeded(body)
-
- return {
- name,
- content: formatFrontmatter(frontmatter, body.trim()),
- }
+])
+
+export function convertClaudeToDroid(
+ plugin: ClaudePlugin,
+ _options: ClaudeToDroidOptions,
+): DroidBundle {
+ const commands = plugin.commands.map((command) => convertCommand(command))
+ const droids = plugin.agents.map((agent) => convertAgent(agent))
+ const skillDirs = plugin.skills.map((skill) => ({
+ name: skill.name,
+ sourceDir: skill.sourceDir,
+ }))
+
+ return { commands, droids, skillDirs }
}
-function convertAgent(agent: ClaudeAgent, usedNames: Set): PiGeneratedSkill {
- const name = uniqueName(normalizeName(agent.name), usedNames)
- const description = sanitizeDescription(
- agent.description ?? `Converted from Claude agent ${agent.name}`,
- )
-
+function convertCommand(command: ClaudeCommand): DroidCommandFile {
+ const name = flattenCommandName(command.name)
const frontmatter: Record = {
- name,
- description,
+ description: command.description,
}
-
- const sections: string[] = []
- if (agent.capabilities && agent.capabilities.length > 0) {
- sections.push(`## Capabilities\n${agent.capabilities.map((capability) => `- ${capability}`).join("\n")}`)
+ if (command.argumentHint) {
+ frontmatter["argument-hint"] = command.argumentHint
+ }
+ if (command.disableModelInvocation) {
+ frontmatter["disable-model-invocation"] = true
}
- const body = [
- ...sections,
- agent.body.trim().length > 0
- ? agent.body.trim()
- : `Instructions converted from the ${agent.name} agent.`,
- ].join("\n\n")
+ const body = transformContentForDroid(command.body.trim())
+ const content = formatFrontmatter(frontmatter, body)
+ return { name, content }
+}
```
This function is important because it defines how Compound Engineering Plugin Tutorial: Compounding Agent Workflows Across Toolchains implements the patterns covered in this chapter.
-### `src/converters/claude-to-pi.ts`
+### `src/converters/claude-to-droid.ts`
-The `convertMcpToMcporter` function in [`src/converters/claude-to-pi.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/HEAD/src/converters/claude-to-pi.ts) handles a key part of this chapter's functionality:
+The `convertCommand` function in [`src/converters/claude-to-droid.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/HEAD/src/converters/claude-to-droid.ts) handles a key part of this chapter's functionality:
```ts
- generatedSkills,
- extensions,
- mcporterConfig: plugin.mcpServers ? convertMcpToMcporter(plugin.mcpServers) : undefined,
- }
+ _options: ClaudeToDroidOptions,
+): DroidBundle {
+ const commands = plugin.commands.map((command) => convertCommand(command))
+ const droids = plugin.agents.map((agent) => convertAgent(agent))
+ const skillDirs = plugin.skills.map((skill) => ({
+ name: skill.name,
+ sourceDir: skill.sourceDir,
+ }))
+
+ return { commands, droids, skillDirs }
}
-function convertPrompt(command: ClaudeCommand, usedNames: Set) {
- const name = uniqueName(normalizeName(command.name), usedNames)
+function convertCommand(command: ClaudeCommand): DroidCommandFile {
+ const name = flattenCommandName(command.name)
const frontmatter: Record = {
description: command.description,
- "argument-hint": command.argumentHint,
}
-
- let body = transformContentForPi(command.body)
- body = appendCompatibilityNoteIfNeeded(body)
-
- return {
- name,
- content: formatFrontmatter(frontmatter, body.trim()),
+ if (command.argumentHint) {
+ frontmatter["argument-hint"] = command.argumentHint
+ }
+ if (command.disableModelInvocation) {
+ frontmatter["disable-model-invocation"] = true
}
-}
-function convertAgent(agent: ClaudeAgent, usedNames: Set): PiGeneratedSkill {
- const name = uniqueName(normalizeName(agent.name), usedNames)
- const description = sanitizeDescription(
- agent.description ?? `Converted from Claude agent ${agent.name}`,
- )
+ const body = transformContentForDroid(command.body.trim())
+ const content = formatFrontmatter(frontmatter, body)
+ return { name, content }
+}
+function convertAgent(agent: ClaudeAgent): DroidAgentFile {
+ const name = normalizeName(agent.name)
const frontmatter: Record = {
- name,
- description,
- }
```
This function is important because it defines how Compound Engineering Plugin Tutorial: Compounding Agent Workflows Across Toolchains implements the patterns covered in this chapter.
@@ -218,11 +193,11 @@ This function is important because it defines how Compound Engineering Plugin Tu
```mermaid
flowchart TD
- A[convertAgent]
- B[transformContentForPi]
- C[appendCompatibilityNoteIfNeeded]
- D[convertMcpToMcporter]
- E[normalizeName]
+ A[syncQwenCommands]
+ B[warnUnsupportedOpenClawCommands]
+ C[convertClaudeToDroid]
+ D[convertCommand]
+ E[convertAgent]
A --> B
B --> C
C --> D
diff --git a/tutorials/compound-engineering-plugin-tutorial/07-troubleshooting-and-runtime-maintenance.md b/tutorials/compound-engineering-plugin-tutorial/07-troubleshooting-and-runtime-maintenance.md
index d786ad59..b27b08ba 100644
--- a/tutorials/compound-engineering-plugin-tutorial/07-troubleshooting-and-runtime-maintenance.md
+++ b/tutorials/compound-engineering-plugin-tutorial/07-troubleshooting-and-runtime-maintenance.md
@@ -46,170 +46,168 @@ You now have a troubleshooting and maintenance playbook for compound workflows.
Next: [Chapter 8: Contribution Workflow and Versioning Discipline](08-contribution-workflow-and-versioning-discipline.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/converters/claude-to-gemini.ts`
+### `src/utils/files.ts`
-The `formatTomlString` function in [`src/converters/claude-to-gemini.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/HEAD/src/converters/claude-to-gemini.ts) handles a key part of this chapter's functionality:
+The `writeJsonSecure` function in [`src/utils/files.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/HEAD/src/utils/files.ts) handles a key part of this chapter's functionality:
```ts
-export function toToml(description: string, prompt: string): string {
- const lines: string[] = []
- lines.push(`description = ${formatTomlString(description)}`)
-
- // Use multi-line string for prompt
- const escapedPrompt = prompt.replace(/\\/g, "\\\\").replace(/"""/g, '\\"\\"\\"')
- lines.push(`prompt = """`)
- lines.push(escapedPrompt)
- lines.push(`"""`)
-
- return lines.join("\n")
-}
-function formatTomlString(value: string): string {
- return JSON.stringify(value)
+/** Write JSON with restrictive permissions (0o600) for files containing secrets */
+export async function writeJsonSecure(filePath: string, data: unknown): Promise {
+ const content = JSON.stringify(data, null, 2)
+ await ensureDir(path.dirname(filePath))
+ await fs.writeFile(filePath, content + "\n", { encoding: "utf8", mode: 0o600 })
+ await fs.chmod(filePath, 0o600)
}
-function normalizeName(value: string): string {
- const trimmed = value.trim()
- if (!trimmed) return "item"
- const normalized = trimmed
- .toLowerCase()
- .replace(/[\\/]+/g, "-")
- .replace(/[:\s]+/g, "-")
- .replace(/[^a-z0-9_-]+/g, "-")
- .replace(/-+/g, "-")
- .replace(/^-+|-+$/g, "")
- return normalized || "item"
+export async function walkFiles(root: string): Promise {
+ const entries = await fs.readdir(root, { withFileTypes: true })
+ const results: string[] = []
+ for (const entry of entries) {
+ const fullPath = path.join(root, entry.name)
+ if (entry.isDirectory()) {
+ const nested = await walkFiles(fullPath)
+ results.push(...nested)
+ } else if (entry.isFile()) {
+ results.push(fullPath)
+ }
+ }
+ return results
}
-function sanitizeDescription(value: string, maxLength = GEMINI_DESCRIPTION_MAX_LENGTH): string {
- const normalized = value.replace(/\s+/g, " ").trim()
+/**
+ * Sanitize a name for use as a filesystem path component.
+ * Replaces colons with hyphens so colon-namespaced names
+ * (e.g. "ce:brainstorm") become flat directory names ("ce-brainstorm")
+ * instead of failing on Windows where colons are illegal in filenames.
+ */
+export function sanitizePathName(name: string): string {
+ return name.replace(/:/g, "-")
```
This function is important because it defines how Compound Engineering Plugin Tutorial: Compounding Agent Workflows Across Toolchains implements the patterns covered in this chapter.
-### `src/converters/claude-to-gemini.ts`
+### `src/utils/files.ts`
-The `normalizeName` function in [`src/converters/claude-to-gemini.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/HEAD/src/converters/claude-to-gemini.ts) handles a key part of this chapter's functionality:
+The `walkFiles` function in [`src/utils/files.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/HEAD/src/utils/files.ts) handles a key part of this chapter's functionality:
```ts
- // Reserve skill names from pass-through skills
- for (const skill of skillDirs) {
- usedSkillNames.add(normalizeName(skill.name))
- }
-
- const generatedSkills = plugin.agents.map((agent) => convertAgentToSkill(agent, usedSkillNames))
-
- const commands = plugin.commands.map((command) => convertCommand(command, usedCommandNames))
-
- const mcpServers = convertMcpServers(plugin.mcpServers)
+}
- if (plugin.hooks && Object.keys(plugin.hooks.hooks).length > 0) {
- console.warn("Warning: Gemini CLI hooks use a different format (BeforeTool/AfterTool with matchers). Hooks were skipped during conversion.")
+export async function walkFiles(root: string): Promise {
+ const entries = await fs.readdir(root, { withFileTypes: true })
+ const results: string[] = []
+ for (const entry of entries) {
+ const fullPath = path.join(root, entry.name)
+ if (entry.isDirectory()) {
+ const nested = await walkFiles(fullPath)
+ results.push(...nested)
+ } else if (entry.isFile()) {
+ results.push(fullPath)
+ }
}
-
- return { generatedSkills, skillDirs, commands, mcpServers }
+ return results
}
-function convertAgentToSkill(agent: ClaudeAgent, usedNames: Set): GeminiSkill {
- const name = uniqueName(normalizeName(agent.name), usedNames)
- const description = sanitizeDescription(
- agent.description ?? `Use this skill for ${agent.name} tasks`,
- )
-
- const frontmatter: Record = { name, description }
+/**
+ * Sanitize a name for use as a filesystem path component.
+ * Replaces colons with hyphens so colon-namespaced names
+ * (e.g. "ce:brainstorm") become flat directory names ("ce-brainstorm")
+ * instead of failing on Windows where colons are illegal in filenames.
+ */
+export function sanitizePathName(name: string): string {
+ return name.replace(/:/g, "-")
+}
- let body = transformContentForGemini(agent.body.trim())
- if (agent.capabilities && agent.capabilities.length > 0) {
- const capabilities = agent.capabilities.map((c) => `- ${c}`).join("\n")
- body = `## Capabilities\n${capabilities}\n\n${body}`.trim()
- }
- if (body.length === 0) {
+/**
+ * Resolve a colon-separated command name into a filesystem path.
+ * e.g. resolveCommandPath("/commands", "ce:plan", ".md") -> "/commands/ce/plan.md"
+ * Creates intermediate directories as needed.
+ */
```
This function is important because it defines how Compound Engineering Plugin Tutorial: Compounding Agent Workflows Across Toolchains implements the patterns covered in this chapter.
-### `src/converters/claude-to-gemini.ts`
+### `src/utils/files.ts`
-The `sanitizeDescription` function in [`src/converters/claude-to-gemini.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/HEAD/src/converters/claude-to-gemini.ts) handles a key part of this chapter's functionality:
+The `sanitizePathName` function in [`src/utils/files.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/HEAD/src/utils/files.ts) handles a key part of this chapter's functionality:
```ts
-function convertAgentToSkill(agent: ClaudeAgent, usedNames: Set): GeminiSkill {
- const name = uniqueName(normalizeName(agent.name), usedNames)
- const description = sanitizeDescription(
- agent.description ?? `Use this skill for ${agent.name} tasks`,
- )
-
- const frontmatter: Record = { name, description }
-
- let body = transformContentForGemini(agent.body.trim())
- if (agent.capabilities && agent.capabilities.length > 0) {
- const capabilities = agent.capabilities.map((c) => `- ${c}`).join("\n")
- body = `## Capabilities\n${capabilities}\n\n${body}`.trim()
- }
- if (body.length === 0) {
- body = `Instructions converted from the ${agent.name} agent.`
- }
-
- const content = formatFrontmatter(frontmatter, body)
- return { name, content }
+ * instead of failing on Windows where colons are illegal in filenames.
+ */
+export function sanitizePathName(name: string): string {
+ return name.replace(/:/g, "-")
}
-function convertCommand(command: ClaudeCommand, usedNames: Set): GeminiCommand {
- // Preserve namespace structure: workflows:plan -> workflows/plan
- const commandPath = resolveCommandPath(command.name)
- const pathKey = commandPath.join("/")
- uniqueName(pathKey, usedNames) // Track for dedup
-
- const description = command.description ?? `Converted from Claude command ${command.name}`
- const transformedBody = transformContentForGemini(command.body.trim())
+/**
+ * Resolve a colon-separated command name into a filesystem path.
+ * e.g. resolveCommandPath("/commands", "ce:plan", ".md") -> "/commands/ce/plan.md"
+ * Creates intermediate directories as needed.
+ */
+export async function resolveCommandPath(dir: string, name: string, ext: string): Promise {
+ const parts = name.split(":")
+ if (parts.length > 1) {
+ const nestedDir = path.join(dir, ...parts.slice(0, -1))
+ await ensureDir(nestedDir)
+ return path.join(nestedDir, `${parts[parts.length - 1]}${ext}`)
+ }
+ return path.join(dir, `${name}${ext}`)
+}
- let prompt = transformedBody
- if (command.argumentHint) {
+export async function copyDir(sourceDir: string, targetDir: string): Promise {
+ await ensureDir(targetDir)
+ const entries = await fs.readdir(sourceDir, { withFileTypes: true })
+ for (const entry of entries) {
+ const sourcePath = path.join(sourceDir, entry.name)
+ const targetPath = path.join(targetDir, entry.name)
+ if (entry.isDirectory()) {
+ await copyDir(sourcePath, targetPath)
+ } else if (entry.isFile()) {
+ await ensureDir(path.dirname(targetPath))
+ await fs.copyFile(sourcePath, targetPath)
```
This function is important because it defines how Compound Engineering Plugin Tutorial: Compounding Agent Workflows Across Toolchains implements the patterns covered in this chapter.
-### `src/converters/claude-to-gemini.ts`
+### `src/utils/files.ts`
-The `uniqueName` function in [`src/converters/claude-to-gemini.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/HEAD/src/converters/claude-to-gemini.ts) handles a key part of this chapter's functionality:
+The `resolveCommandPath` function in [`src/utils/files.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/HEAD/src/utils/files.ts) handles a key part of this chapter's functionality:
```ts
-
-function convertAgentToSkill(agent: ClaudeAgent, usedNames: Set): GeminiSkill {
- const name = uniqueName(normalizeName(agent.name), usedNames)
- const description = sanitizeDescription(
- agent.description ?? `Use this skill for ${agent.name} tasks`,
- )
-
- const frontmatter: Record = { name, description }
-
- let body = transformContentForGemini(agent.body.trim())
- if (agent.capabilities && agent.capabilities.length > 0) {
- const capabilities = agent.capabilities.map((c) => `- ${c}`).join("\n")
- body = `## Capabilities\n${capabilities}\n\n${body}`.trim()
+/**
+ * Resolve a colon-separated command name into a filesystem path.
+ * e.g. resolveCommandPath("/commands", "ce:plan", ".md") -> "/commands/ce/plan.md"
+ * Creates intermediate directories as needed.
+ */
+export async function resolveCommandPath(dir: string, name: string, ext: string): Promise {
+ const parts = name.split(":")
+ if (parts.length > 1) {
+ const nestedDir = path.join(dir, ...parts.slice(0, -1))
+ await ensureDir(nestedDir)
+ return path.join(nestedDir, `${parts[parts.length - 1]}${ext}`)
}
- if (body.length === 0) {
- body = `Instructions converted from the ${agent.name} agent.`
- }
-
- const content = formatFrontmatter(frontmatter, body)
- return { name, content }
+ return path.join(dir, `${name}${ext}`)
}
-function convertCommand(command: ClaudeCommand, usedNames: Set): GeminiCommand {
- // Preserve namespace structure: workflows:plan -> workflows/plan
- const commandPath = resolveCommandPath(command.name)
- const pathKey = commandPath.join("/")
- uniqueName(pathKey, usedNames) // Track for dedup
-
- const description = command.description ?? `Converted from Claude command ${command.name}`
- const transformedBody = transformContentForGemini(command.body.trim())
+export async function copyDir(sourceDir: string, targetDir: string): Promise {
+ await ensureDir(targetDir)
+ const entries = await fs.readdir(sourceDir, { withFileTypes: true })
+ for (const entry of entries) {
+ const sourcePath = path.join(sourceDir, entry.name)
+ const targetPath = path.join(targetDir, entry.name)
+ if (entry.isDirectory()) {
+ await copyDir(sourcePath, targetPath)
+ } else if (entry.isFile()) {
+ await ensureDir(path.dirname(targetPath))
+ await fs.copyFile(sourcePath, targetPath)
+ }
+ }
+}
- let prompt = transformedBody
+/**
+ * Copy a skill directory, optionally transforming markdown content.
```
This function is important because it defines how Compound Engineering Plugin Tutorial: Compounding Agent Workflows Across Toolchains implements the patterns covered in this chapter.
@@ -219,11 +217,11 @@ This function is important because it defines how Compound Engineering Plugin Tu
```mermaid
flowchart TD
- A[formatTomlString]
- B[normalizeName]
- C[sanitizeDescription]
- D[uniqueName]
- E[convertClaudeToOpenClaw]
+ A[writeJsonSecure]
+ B[walkFiles]
+ C[sanitizePathName]
+ D[resolveCommandPath]
+ E[copyDir]
A --> B
B --> C
C --> D
diff --git a/tutorials/compound-engineering-plugin-tutorial/08-contribution-workflow-and-versioning-discipline.md b/tutorials/compound-engineering-plugin-tutorial/08-contribution-workflow-and-versioning-discipline.md
index 37706b58..8603848f 100644
--- a/tutorials/compound-engineering-plugin-tutorial/08-contribution-workflow-and-versioning-discipline.md
+++ b/tutorials/compound-engineering-plugin-tutorial/08-contribution-workflow-and-versioning-discipline.md
@@ -50,170 +50,168 @@ Next steps:
- publish compatibility test matrix across target runtimes
- ship one focused contribution with changelog and docs updates
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/sync/gemini.ts`
+### `src/converters/claude-to-openclaw.ts`
-The `syncToGemini` function in [`src/sync/gemini.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/HEAD/src/sync/gemini.ts) handles a key part of this chapter's functionality:
+The `loadSkills` function in [`src/converters/claude-to-openclaw.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/HEAD/src/converters/claude-to-openclaw.ts) handles a key part of this chapter's functionality:
```ts
-}
+const skills: Record = {};
-export async function syncToGemini(
- config: ClaudeHomeConfig,
- outputRoot: string,
-): Promise {
- await syncGeminiSkills(config.skills, outputRoot)
- await syncGeminiCommands(config, outputRoot)
-
- if (Object.keys(config.mcpServers).length > 0) {
- const settingsPath = path.join(outputRoot, "settings.json")
- const converted = convertMcpForGemini(config.mcpServers)
- await mergeJsonConfigAtKey({
- configPath: settingsPath,
- key: "mcpServers",
- incoming: converted,
- })
+async function loadSkills() {
+ const skillsDir = path.join(__dirname, "skills");
+ try {
+ const entries = await fs.readdir(skillsDir, { withFileTypes: true });
+ for (const entry of entries) {
+ if (!entry.isDirectory()) continue;
+ const skillPath = path.join(skillsDir, entry.name, "SKILL.md");
+ try {
+ const content = await fs.readFile(skillPath, "utf8");
+ // Strip frontmatter
+ const body = content.replace(/^---[\\s\\S]*?---\\n*/, "");
+ skills[entry.name.replace(/^cmd-/, "")] = body.trim();
+ } catch {
+ // Skill file not found, skip
+ }
+ }
+ } catch {
+ // Skills directory not found
}
}
-async function syncGeminiSkills(
- skills: ClaudeHomeConfig["skills"],
- outputRoot: string,
-): Promise {
- const skillsDir = path.join(outputRoot, "skills")
- const sharedSkillsDir = getGeminiSharedSkillsDir(outputRoot)
+export default async function register(api) {
+ await loadSkills();
- if (!sharedSkillsDir) {
- await syncSkills(skills, skillsDir)
- return
- }
+${commandRegistrations}
+}
+`
+}
+function rewritePaths(body: string): string {
```
This function is important because it defines how Compound Engineering Plugin Tutorial: Compounding Agent Workflows Across Toolchains implements the patterns covered in this chapter.
-### `src/sync/gemini.ts`
+### `src/converters/claude-to-openclaw.ts`
-The `syncGeminiSkills` function in [`src/sync/gemini.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/HEAD/src/sync/gemini.ts) handles a key part of this chapter's functionality:
+The `register` function in [`src/converters/claude-to-openclaw.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/HEAD/src/converters/claude-to-openclaw.ts) handles a key part of this chapter's functionality:
```ts
- outputRoot: string,
-): Promise {
- await syncGeminiSkills(config.skills, outputRoot)
- await syncGeminiCommands(config, outputRoot)
-
- if (Object.keys(config.mcpServers).length > 0) {
- const settingsPath = path.join(outputRoot, "settings.json")
- const converted = convertMcpForGemini(config.mcpServers)
- await mergeJsonConfigAtKey({
- configPath: settingsPath,
- key: "mcpServers",
- incoming: converted,
+ const safeDesc = JSON.stringify(cmd.description ?? "")
+ const safeNotFound = JSON.stringify(`Command ${cmd.name} not found. Check skills directory.`)
+ return ` api.registerCommand({
+ name: ${safeName},
+ description: ${safeDesc},
+ acceptsArgs: ${cmd.acceptsArgs},
+ requireAuth: false,
+ handler: (ctx) => ({
+ text: skills[${safeName}] ?? ${safeNotFound},
+ }),
+ });`
})
- }
-}
+ .join("\n\n")
-async function syncGeminiSkills(
- skills: ClaudeHomeConfig["skills"],
- outputRoot: string,
-): Promise {
- const skillsDir = path.join(outputRoot, "skills")
- const sharedSkillsDir = getGeminiSharedSkillsDir(outputRoot)
+ return `// Auto-generated OpenClaw plugin entry point
+// Converted from Claude Code plugin format by compound-plugin CLI
+import { promises as fs } from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
- if (!sharedSkillsDir) {
- await syncSkills(skills, skillsDir)
- return
- }
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
- const canonicalSharedSkillsDir = await canonicalizePath(sharedSkillsDir)
- const mirroredSkills: ClaudeHomeConfig["skills"] = []
- const directSkills: ClaudeHomeConfig["skills"] = []
+// Pre-load skill bodies for command responses
+const skills: Record = {};
+async function loadSkills() {
+ const skillsDir = path.join(__dirname, "skills");
+ try {
+ const entries = await fs.readdir(skillsDir, { withFileTypes: true });
+ for (const entry of entries) {
+ if (!entry.isDirectory()) continue;
+ const skillPath = path.join(skillsDir, entry.name, "SKILL.md");
```
This function is important because it defines how Compound Engineering Plugin Tutorial: Compounding Agent Workflows Across Toolchains implements the patterns covered in this chapter.
-### `src/sync/gemini.ts`
+### `src/converters/claude-to-openclaw.ts`
-The `getGeminiSharedSkillsDir` function in [`src/sync/gemini.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/HEAD/src/sync/gemini.ts) handles a key part of this chapter's functionality:
+The `rewritePaths` function in [`src/converters/claude-to-openclaw.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/HEAD/src/converters/claude-to-openclaw.ts) handles a key part of this chapter's functionality:
```ts
-): Promise {
- const skillsDir = path.join(outputRoot, "skills")
- const sharedSkillsDir = getGeminiSharedSkillsDir(outputRoot)
+ }
+
+ const body = rewritePaths(agent.body)
+ const content = formatFrontmatter(frontmatter, body)
- if (!sharedSkillsDir) {
- await syncSkills(skills, skillsDir)
- return
+ return {
+ name: agent.name,
+ content,
+ dir: `agent-${agent.name}`,
}
+}
- const canonicalSharedSkillsDir = await canonicalizePath(sharedSkillsDir)
- const mirroredSkills: ClaudeHomeConfig["skills"] = []
- const directSkills: ClaudeHomeConfig["skills"] = []
+function convertCommandToSkill(command: ClaudeCommand): OpenClawSkillFile {
+ const frontmatter: Record = {
+ name: `cmd-${command.name}`,
+ description: command.description,
+ }
- for (const skill of skills) {
- if (await isWithinDir(skill.sourceDir, canonicalSharedSkillsDir)) {
- mirroredSkills.push(skill)
- } else {
- directSkills.push(skill)
- }
+ if (command.model && command.model !== "inherit") {
+ frontmatter.model = normalizeModelWithProvider(command.model)
}
- await removeGeminiMirrorConflicts(mirroredSkills, skillsDir, canonicalSharedSkillsDir)
- await syncSkills(directSkills, skillsDir)
-}
+ const body = rewritePaths(command.body)
+ const content = formatFrontmatter(frontmatter, body)
-function getGeminiSharedSkillsDir(outputRoot: string): string | null {
- if (path.basename(outputRoot) !== ".gemini") return null
- return path.join(path.dirname(outputRoot), ".agents", "skills")
+ return {
+ name: command.name,
+ content,
+ dir: `cmd-${command.name}`,
+ }
}
-async function canonicalizePath(targetPath: string): Promise {
- try {
```
This function is important because it defines how Compound Engineering Plugin Tutorial: Compounding Agent Workflows Across Toolchains implements the patterns covered in this chapter.
-### `src/sync/gemini.ts`
+### `src/converters/claude-to-openclaw.ts`
-The `canonicalizePath` function in [`src/sync/gemini.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/HEAD/src/sync/gemini.ts) handles a key part of this chapter's functionality:
+The `formatDisplayName` function in [`src/converters/claude-to-openclaw.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/HEAD/src/converters/claude-to-openclaw.ts) handles a key part of this chapter's functionality:
```ts
- }
-
- const canonicalSharedSkillsDir = await canonicalizePath(sharedSkillsDir)
- const mirroredSkills: ClaudeHomeConfig["skills"] = []
- const directSkills: ClaudeHomeConfig["skills"] = []
-
- for (const skill of skills) {
- if (await isWithinDir(skill.sourceDir, canonicalSharedSkillsDir)) {
- mirroredSkills.push(skill)
- } else {
- directSkills.push(skill)
- }
- }
-
- await removeGeminiMirrorConflicts(mirroredSkills, skillsDir, canonicalSharedSkillsDir)
- await syncSkills(directSkills, skillsDir)
-}
-
-function getGeminiSharedSkillsDir(outputRoot: string): string | null {
- if (path.basename(outputRoot) !== ".gemini") return null
- return path.join(path.dirname(outputRoot), ".agents", "skills")
-}
-
-async function canonicalizePath(targetPath: string): Promise {
- try {
- return await fs.realpath(targetPath)
- } catch {
- return path.resolve(targetPath)
+ return {
+ id: plugin.manifest.name,
+ name: formatDisplayName(plugin.manifest.name),
+ kind: "tool",
+ configSchema: {
+ type: "object",
+ properties: {},
+ },
+ skills: skillDirs.map((dir) => `skills/${dir}`),
}
}
-async function isWithinDir(candidate: string, canonicalParentDir: string): Promise {
+function buildPackageJson(plugin: ClaudePlugin): Record {
+ return {
+ name: `openclaw-${plugin.manifest.name}`,
+ version: plugin.manifest.version,
+ type: "module",
+ private: true,
+ description: plugin.manifest.description,
+ main: "index.ts",
+ openclaw: {
+ extensions: [
+ {
+ id: plugin.manifest.name,
+ entry: "./index.ts",
+ },
+ ],
+ },
+ keywords: [
+ "openclaw",
+ "openclaw-plugin",
+ ...(plugin.manifest.keywords ?? []),
```
This function is important because it defines how Compound Engineering Plugin Tutorial: Compounding Agent Workflows Across Toolchains implements the patterns covered in this chapter.
@@ -223,11 +221,11 @@ This function is important because it defines how Compound Engineering Plugin Tu
```mermaid
flowchart TD
- A[syncToGemini]
- B[syncGeminiSkills]
- C[getGeminiSharedSkillsDir]
- D[canonicalizePath]
- E[isWithinDir]
+ A[loadSkills]
+ B[register]
+ C[rewritePaths]
+ D[formatDisplayName]
+ E[convertClaudeToQwen]
A --> B
B --> C
C --> D
diff --git a/tutorials/context7-tutorial/01-getting-started.md b/tutorials/context7-tutorial/01-getting-started.md
index 329a34b7..bd4a77d0 100644
--- a/tutorials/context7-tutorial/01-getting-started.md
+++ b/tutorials/context7-tutorial/01-getting-started.md
@@ -47,10 +47,52 @@ You now have Context7 running and reachable from your coding client.
Next: [Chapter 2: Architecture and Tooling Model](02-architecture-and-tooling-model.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
+### `package.json`
+
+The `package` module in [`package.json`](https://github.com/upstash/context7/blob/HEAD/package.json) handles a key part of this chapter's functionality:
+
+```json
+{
+ "name": "@upstash/context7",
+ "private": true,
+ "version": "1.0.0",
+ "description": "Context7 monorepo - Documentation tools and SDKs",
+ "workspaces": [
+ "packages/*"
+ ],
+ "scripts": {
+ "build": "pnpm -r run build",
+ "build:sdk": "pnpm --filter @upstash/context7-sdk build",
+ "build:mcp": "pnpm --filter @upstash/context7-mcp build",
+ "build:ai-sdk": "pnpm --filter @upstash/context7-tools-ai-sdk build",
+ "typecheck": "pnpm -r run typecheck",
+ "test": "pnpm -r run test",
+ "test:sdk": "pnpm --filter @upstash/context7-sdk test",
+ "test:tools-ai-sdk": "pnpm --filter @upstash/context7-tools-ai-sdk test",
+ "clean": "pnpm -r run clean && rm -rf node_modules",
+ "lint": "pnpm -r run lint",
+ "lint:check": "pnpm -r run lint:check",
+ "format": "pnpm -r run format",
+ "format:check": "pnpm -r run format:check",
+ "release": "pnpm build && changeset publish",
+ "release:snapshot": "changeset version --snapshot canary && pnpm build && changeset publish --tag canary --no-git-tag"
+ },
+ "repository": {
+ "type": "git",
+ "url": "git+https://github.com/upstash/context7.git"
+ },
+ "keywords": [
+ "modelcontextprotocol",
+ "mcp",
+ "context7",
+ "vibe-coding",
+ "developer tools",
+```
+
+This module is important because it defines how Context7 Tutorial: Live Documentation Context for Coding Agents implements the patterns covered in this chapter.
+
### `server.json`
The `server` module in [`server.json`](https://github.com/upstash/context7/blob/HEAD/server.json) handles a key part of this chapter's functionality:
@@ -95,102 +137,12 @@ The `server` module in [`server.json`](https://github.com/upstash/context7/blob/
This module is important because it defines how Context7 Tutorial: Live Documentation Context for Coding Agents implements the patterns covered in this chapter.
-### `docs/docs.json`
-
-The `docs` module in [`docs/docs.json`](https://github.com/upstash/context7/blob/HEAD/docs/docs.json) handles a key part of this chapter's functionality:
-
-```json
-{
- "$schema": "https://mintlify.com/docs.json",
- "theme": "mint",
- "name": "Context7 MCP",
- "description": "Up-to-date code docs for any prompt.",
- "colors": {
- "primary": "#10B981",
- "light": "#ECFDF5",
- "dark": "#064E3B"
- },
- "contextual": {
- "options": [
- "copy",
- "view",
- "chatgpt",
- "claude"
- ]
- },
- "navigation": {
- "groups": [
- {
- "group": "Overview",
- "pages": [
- "overview",
- "installation",
- "plans-pricing",
- "clients/cli",
- "adding-libraries",
- "api-guide",
- "skills",
- "tips"
- ]
- },
- {
- "group": "How To",
-```
-
-This module is important because it defines how Context7 Tutorial: Live Documentation Context for Coding Agents implements the patterns covered in this chapter.
-
-### `eslint.config.js`
-
-The `eslint.config` module in [`eslint.config.js`](https://github.com/upstash/context7/blob/HEAD/eslint.config.js) handles a key part of this chapter's functionality:
-
-```js
-import tseslint from "typescript-eslint";
-import eslintPluginPrettier from "eslint-plugin-prettier";
-
-export default tseslint.config({
- // Base ESLint configuration
- ignores: ["node_modules/**", "build/**", "dist/**", ".git/**", ".github/**"],
- languageOptions: {
- ecmaVersion: 2020,
- sourceType: "module",
- parser: tseslint.parser,
- parserOptions: {},
- globals: {
- // Add Node.js globals
- process: "readonly",
- require: "readonly",
- module: "writable",
- console: "readonly",
- },
- },
- // Settings for all files
- linterOptions: {
- reportUnusedDisableDirectives: true,
- },
- // Apply ESLint recommended rules
- extends: [tseslint.configs.recommended],
- plugins: {
- prettier: eslintPluginPrettier,
- },
- rules: {
- // TypeScript rules
- "@typescript-eslint/explicit-module-boundary-types": "off",
- "@typescript-eslint/no-unused-vars": ["error", { argsIgnorePattern: "^_" }],
- "@typescript-eslint/no-explicit-any": "warn",
- // Prettier integration
- "prettier/prettier": "error",
-```
-
-This module is important because it defines how Context7 Tutorial: Live Documentation Context for Coding Agents implements the patterns covered in this chapter.
-
## How These Components Connect
```mermaid
flowchart TD
- A[server]
- B[docs]
- C[eslint.config]
+ A[package]
+ B[server]
A --> B
- B --> C
```
diff --git a/tutorials/context7-tutorial/02-architecture-and-tooling-model.md b/tutorials/context7-tutorial/02-architecture-and-tooling-model.md
index 7ffb685b..d6025897 100644
--- a/tutorials/context7-tutorial/02-architecture-and-tooling-model.md
+++ b/tutorials/context7-tutorial/02-architecture-and-tooling-model.md
@@ -45,10 +45,52 @@ You now understand the mechanism that makes Context7 valuable in code generation
Next: [Chapter 3: Client Integrations and Setup Patterns](03-client-integrations-and-setup-patterns.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
+### `package.json`
+
+The `package` module in [`package.json`](https://github.com/upstash/context7/blob/HEAD/package.json) handles a key part of this chapter's functionality:
+
+```json
+{
+ "name": "@upstash/context7",
+ "private": true,
+ "version": "1.0.0",
+ "description": "Context7 monorepo - Documentation tools and SDKs",
+ "workspaces": [
+ "packages/*"
+ ],
+ "scripts": {
+ "build": "pnpm -r run build",
+ "build:sdk": "pnpm --filter @upstash/context7-sdk build",
+ "build:mcp": "pnpm --filter @upstash/context7-mcp build",
+ "build:ai-sdk": "pnpm --filter @upstash/context7-tools-ai-sdk build",
+ "typecheck": "pnpm -r run typecheck",
+ "test": "pnpm -r run test",
+ "test:sdk": "pnpm --filter @upstash/context7-sdk test",
+ "test:tools-ai-sdk": "pnpm --filter @upstash/context7-tools-ai-sdk test",
+ "clean": "pnpm -r run clean && rm -rf node_modules",
+ "lint": "pnpm -r run lint",
+ "lint:check": "pnpm -r run lint:check",
+ "format": "pnpm -r run format",
+ "format:check": "pnpm -r run format:check",
+ "release": "pnpm build && changeset publish",
+ "release:snapshot": "changeset version --snapshot canary && pnpm build && changeset publish --tag canary --no-git-tag"
+ },
+ "repository": {
+ "type": "git",
+ "url": "git+https://github.com/upstash/context7.git"
+ },
+ "keywords": [
+ "modelcontextprotocol",
+ "mcp",
+ "context7",
+ "vibe-coding",
+ "developer tools",
+```
+
+This module is important because it defines how Context7 Tutorial: Live Documentation Context for Coding Agents implements the patterns covered in this chapter.
+
### `server.json`
The `server` module in [`server.json`](https://github.com/upstash/context7/blob/HEAD/server.json) handles a key part of this chapter's functionality:
@@ -93,102 +135,12 @@ The `server` module in [`server.json`](https://github.com/upstash/context7/blob/
This module is important because it defines how Context7 Tutorial: Live Documentation Context for Coding Agents implements the patterns covered in this chapter.
-### `docs/docs.json`
-
-The `docs` module in [`docs/docs.json`](https://github.com/upstash/context7/blob/HEAD/docs/docs.json) handles a key part of this chapter's functionality:
-
-```json
-{
- "$schema": "https://mintlify.com/docs.json",
- "theme": "mint",
- "name": "Context7 MCP",
- "description": "Up-to-date code docs for any prompt.",
- "colors": {
- "primary": "#10B981",
- "light": "#ECFDF5",
- "dark": "#064E3B"
- },
- "contextual": {
- "options": [
- "copy",
- "view",
- "chatgpt",
- "claude"
- ]
- },
- "navigation": {
- "groups": [
- {
- "group": "Overview",
- "pages": [
- "overview",
- "installation",
- "plans-pricing",
- "clients/cli",
- "adding-libraries",
- "api-guide",
- "skills",
- "tips"
- ]
- },
- {
- "group": "How To",
-```
-
-This module is important because it defines how Context7 Tutorial: Live Documentation Context for Coding Agents implements the patterns covered in this chapter.
-
-### `eslint.config.js`
-
-The `eslint.config` module in [`eslint.config.js`](https://github.com/upstash/context7/blob/HEAD/eslint.config.js) handles a key part of this chapter's functionality:
-
-```js
-import tseslint from "typescript-eslint";
-import eslintPluginPrettier from "eslint-plugin-prettier";
-
-export default tseslint.config({
- // Base ESLint configuration
- ignores: ["node_modules/**", "build/**", "dist/**", ".git/**", ".github/**"],
- languageOptions: {
- ecmaVersion: 2020,
- sourceType: "module",
- parser: tseslint.parser,
- parserOptions: {},
- globals: {
- // Add Node.js globals
- process: "readonly",
- require: "readonly",
- module: "writable",
- console: "readonly",
- },
- },
- // Settings for all files
- linterOptions: {
- reportUnusedDisableDirectives: true,
- },
- // Apply ESLint recommended rules
- extends: [tseslint.configs.recommended],
- plugins: {
- prettier: eslintPluginPrettier,
- },
- rules: {
- // TypeScript rules
- "@typescript-eslint/explicit-module-boundary-types": "off",
- "@typescript-eslint/no-unused-vars": ["error", { argsIgnorePattern: "^_" }],
- "@typescript-eslint/no-explicit-any": "warn",
- // Prettier integration
- "prettier/prettier": "error",
-```
-
-This module is important because it defines how Context7 Tutorial: Live Documentation Context for Coding Agents implements the patterns covered in this chapter.
-
## How These Components Connect
```mermaid
flowchart TD
- A[server]
- B[docs]
- C[eslint.config]
+ A[package]
+ B[server]
A --> B
- B --> C
```
diff --git a/tutorials/context7-tutorial/03-client-integrations-and-setup-patterns.md b/tutorials/context7-tutorial/03-client-integrations-and-setup-patterns.md
index 1e9dd5d5..a2eea560 100644
--- a/tutorials/context7-tutorial/03-client-integrations-and-setup-patterns.md
+++ b/tutorials/context7-tutorial/03-client-integrations-and-setup-patterns.md
@@ -46,10 +46,52 @@ You now can deploy Context7 consistently across heterogeneous coding-agent clien
Next: [Chapter 4: Prompting Strategies and Rules](04-prompting-strategies-and-rules.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
+### `package.json`
+
+The `package` module in [`package.json`](https://github.com/upstash/context7/blob/HEAD/package.json) handles a key part of this chapter's functionality:
+
+```json
+{
+ "name": "@upstash/context7",
+ "private": true,
+ "version": "1.0.0",
+ "description": "Context7 monorepo - Documentation tools and SDKs",
+ "workspaces": [
+ "packages/*"
+ ],
+ "scripts": {
+ "build": "pnpm -r run build",
+ "build:sdk": "pnpm --filter @upstash/context7-sdk build",
+ "build:mcp": "pnpm --filter @upstash/context7-mcp build",
+ "build:ai-sdk": "pnpm --filter @upstash/context7-tools-ai-sdk build",
+ "typecheck": "pnpm -r run typecheck",
+ "test": "pnpm -r run test",
+ "test:sdk": "pnpm --filter @upstash/context7-sdk test",
+ "test:tools-ai-sdk": "pnpm --filter @upstash/context7-tools-ai-sdk test",
+ "clean": "pnpm -r run clean && rm -rf node_modules",
+ "lint": "pnpm -r run lint",
+ "lint:check": "pnpm -r run lint:check",
+ "format": "pnpm -r run format",
+ "format:check": "pnpm -r run format:check",
+ "release": "pnpm build && changeset publish",
+ "release:snapshot": "changeset version --snapshot canary && pnpm build && changeset publish --tag canary --no-git-tag"
+ },
+ "repository": {
+ "type": "git",
+ "url": "git+https://github.com/upstash/context7.git"
+ },
+ "keywords": [
+ "modelcontextprotocol",
+ "mcp",
+ "context7",
+ "vibe-coding",
+ "developer tools",
+```
+
+This module is important because it defines how Context7 Tutorial: Live Documentation Context for Coding Agents implements the patterns covered in this chapter.
+
### `server.json`
The `server` module in [`server.json`](https://github.com/upstash/context7/blob/HEAD/server.json) handles a key part of this chapter's functionality:
@@ -94,102 +136,12 @@ The `server` module in [`server.json`](https://github.com/upstash/context7/blob/
This module is important because it defines how Context7 Tutorial: Live Documentation Context for Coding Agents implements the patterns covered in this chapter.
-### `docs/docs.json`
-
-The `docs` module in [`docs/docs.json`](https://github.com/upstash/context7/blob/HEAD/docs/docs.json) handles a key part of this chapter's functionality:
-
-```json
-{
- "$schema": "https://mintlify.com/docs.json",
- "theme": "mint",
- "name": "Context7 MCP",
- "description": "Up-to-date code docs for any prompt.",
- "colors": {
- "primary": "#10B981",
- "light": "#ECFDF5",
- "dark": "#064E3B"
- },
- "contextual": {
- "options": [
- "copy",
- "view",
- "chatgpt",
- "claude"
- ]
- },
- "navigation": {
- "groups": [
- {
- "group": "Overview",
- "pages": [
- "overview",
- "installation",
- "plans-pricing",
- "clients/cli",
- "adding-libraries",
- "api-guide",
- "skills",
- "tips"
- ]
- },
- {
- "group": "How To",
-```
-
-This module is important because it defines how Context7 Tutorial: Live Documentation Context for Coding Agents implements the patterns covered in this chapter.
-
-### `eslint.config.js`
-
-The `eslint.config` module in [`eslint.config.js`](https://github.com/upstash/context7/blob/HEAD/eslint.config.js) handles a key part of this chapter's functionality:
-
-```js
-import tseslint from "typescript-eslint";
-import eslintPluginPrettier from "eslint-plugin-prettier";
-
-export default tseslint.config({
- // Base ESLint configuration
- ignores: ["node_modules/**", "build/**", "dist/**", ".git/**", ".github/**"],
- languageOptions: {
- ecmaVersion: 2020,
- sourceType: "module",
- parser: tseslint.parser,
- parserOptions: {},
- globals: {
- // Add Node.js globals
- process: "readonly",
- require: "readonly",
- module: "writable",
- console: "readonly",
- },
- },
- // Settings for all files
- linterOptions: {
- reportUnusedDisableDirectives: true,
- },
- // Apply ESLint recommended rules
- extends: [tseslint.configs.recommended],
- plugins: {
- prettier: eslintPluginPrettier,
- },
- rules: {
- // TypeScript rules
- "@typescript-eslint/explicit-module-boundary-types": "off",
- "@typescript-eslint/no-unused-vars": ["error", { argsIgnorePattern: "^_" }],
- "@typescript-eslint/no-explicit-any": "warn",
- // Prettier integration
- "prettier/prettier": "error",
-```
-
-This module is important because it defines how Context7 Tutorial: Live Documentation Context for Coding Agents implements the patterns covered in this chapter.
-
## How These Components Connect
```mermaid
flowchart TD
- A[server]
- B[docs]
- C[eslint.config]
+ A[package]
+ B[server]
A --> B
- B --> C
```
diff --git a/tutorials/context7-tutorial/04-prompting-strategies-and-rules.md b/tutorials/context7-tutorial/04-prompting-strategies-and-rules.md
index 76ebc479..908a8d7e 100644
--- a/tutorials/context7-tutorial/04-prompting-strategies-and-rules.md
+++ b/tutorials/context7-tutorial/04-prompting-strategies-and-rules.md
@@ -43,10 +43,52 @@ You now know how to structure prompts and rules so Context7 activates predictabl
Next: [Chapter 5: API Workflows and SDK Patterns](05-api-workflows-and-sdk-patterns.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
+### `package.json`
+
+The `package` module in [`package.json`](https://github.com/upstash/context7/blob/HEAD/package.json) handles a key part of this chapter's functionality:
+
+```json
+{
+ "name": "@upstash/context7",
+ "private": true,
+ "version": "1.0.0",
+ "description": "Context7 monorepo - Documentation tools and SDKs",
+ "workspaces": [
+ "packages/*"
+ ],
+ "scripts": {
+ "build": "pnpm -r run build",
+ "build:sdk": "pnpm --filter @upstash/context7-sdk build",
+ "build:mcp": "pnpm --filter @upstash/context7-mcp build",
+ "build:ai-sdk": "pnpm --filter @upstash/context7-tools-ai-sdk build",
+ "typecheck": "pnpm -r run typecheck",
+ "test": "pnpm -r run test",
+ "test:sdk": "pnpm --filter @upstash/context7-sdk test",
+ "test:tools-ai-sdk": "pnpm --filter @upstash/context7-tools-ai-sdk test",
+ "clean": "pnpm -r run clean && rm -rf node_modules",
+ "lint": "pnpm -r run lint",
+ "lint:check": "pnpm -r run lint:check",
+ "format": "pnpm -r run format",
+ "format:check": "pnpm -r run format:check",
+ "release": "pnpm build && changeset publish",
+ "release:snapshot": "changeset version --snapshot canary && pnpm build && changeset publish --tag canary --no-git-tag"
+ },
+ "repository": {
+ "type": "git",
+ "url": "git+https://github.com/upstash/context7.git"
+ },
+ "keywords": [
+ "modelcontextprotocol",
+ "mcp",
+ "context7",
+ "vibe-coding",
+ "developer tools",
+```
+
+This module is important because it defines how Context7 Tutorial: Live Documentation Context for Coding Agents implements the patterns covered in this chapter.
+
### `server.json`
The `server` module in [`server.json`](https://github.com/upstash/context7/blob/HEAD/server.json) handles a key part of this chapter's functionality:
@@ -91,102 +133,12 @@ The `server` module in [`server.json`](https://github.com/upstash/context7/blob/
This module is important because it defines how Context7 Tutorial: Live Documentation Context for Coding Agents implements the patterns covered in this chapter.
-### `docs/docs.json`
-
-The `docs` module in [`docs/docs.json`](https://github.com/upstash/context7/blob/HEAD/docs/docs.json) handles a key part of this chapter's functionality:
-
-```json
-{
- "$schema": "https://mintlify.com/docs.json",
- "theme": "mint",
- "name": "Context7 MCP",
- "description": "Up-to-date code docs for any prompt.",
- "colors": {
- "primary": "#10B981",
- "light": "#ECFDF5",
- "dark": "#064E3B"
- },
- "contextual": {
- "options": [
- "copy",
- "view",
- "chatgpt",
- "claude"
- ]
- },
- "navigation": {
- "groups": [
- {
- "group": "Overview",
- "pages": [
- "overview",
- "installation",
- "plans-pricing",
- "clients/cli",
- "adding-libraries",
- "api-guide",
- "skills",
- "tips"
- ]
- },
- {
- "group": "How To",
-```
-
-This module is important because it defines how Context7 Tutorial: Live Documentation Context for Coding Agents implements the patterns covered in this chapter.
-
-### `eslint.config.js`
-
-The `eslint.config` module in [`eslint.config.js`](https://github.com/upstash/context7/blob/HEAD/eslint.config.js) handles a key part of this chapter's functionality:
-
-```js
-import tseslint from "typescript-eslint";
-import eslintPluginPrettier from "eslint-plugin-prettier";
-
-export default tseslint.config({
- // Base ESLint configuration
- ignores: ["node_modules/**", "build/**", "dist/**", ".git/**", ".github/**"],
- languageOptions: {
- ecmaVersion: 2020,
- sourceType: "module",
- parser: tseslint.parser,
- parserOptions: {},
- globals: {
- // Add Node.js globals
- process: "readonly",
- require: "readonly",
- module: "writable",
- console: "readonly",
- },
- },
- // Settings for all files
- linterOptions: {
- reportUnusedDisableDirectives: true,
- },
- // Apply ESLint recommended rules
- extends: [tseslint.configs.recommended],
- plugins: {
- prettier: eslintPluginPrettier,
- },
- rules: {
- // TypeScript rules
- "@typescript-eslint/explicit-module-boundary-types": "off",
- "@typescript-eslint/no-unused-vars": ["error", { argsIgnorePattern: "^_" }],
- "@typescript-eslint/no-explicit-any": "warn",
- // Prettier integration
- "prettier/prettier": "error",
-```
-
-This module is important because it defines how Context7 Tutorial: Live Documentation Context for Coding Agents implements the patterns covered in this chapter.
-
## How These Components Connect
```mermaid
flowchart TD
- A[server]
- B[docs]
- C[eslint.config]
+ A[package]
+ B[server]
A --> B
- B --> C
```
diff --git a/tutorials/context7-tutorial/05-api-workflows-and-sdk-patterns.md b/tutorials/context7-tutorial/05-api-workflows-and-sdk-patterns.md
index 2fe6a063..5d5cee88 100644
--- a/tutorials/context7-tutorial/05-api-workflows-and-sdk-patterns.md
+++ b/tutorials/context7-tutorial/05-api-workflows-and-sdk-patterns.md
@@ -45,10 +45,52 @@ You now have a baseline for embedding Context7 docs retrieval in custom coding p
Next: [Chapter 6: Library Onboarding and Documentation Quality](06-library-onboarding-and-documentation-quality.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
+### `package.json`
+
+The `package` module in [`package.json`](https://github.com/upstash/context7/blob/HEAD/package.json) handles a key part of this chapter's functionality:
+
+```json
+{
+ "name": "@upstash/context7",
+ "private": true,
+ "version": "1.0.0",
+ "description": "Context7 monorepo - Documentation tools and SDKs",
+ "workspaces": [
+ "packages/*"
+ ],
+ "scripts": {
+ "build": "pnpm -r run build",
+ "build:sdk": "pnpm --filter @upstash/context7-sdk build",
+ "build:mcp": "pnpm --filter @upstash/context7-mcp build",
+ "build:ai-sdk": "pnpm --filter @upstash/context7-tools-ai-sdk build",
+ "typecheck": "pnpm -r run typecheck",
+ "test": "pnpm -r run test",
+ "test:sdk": "pnpm --filter @upstash/context7-sdk test",
+ "test:tools-ai-sdk": "pnpm --filter @upstash/context7-tools-ai-sdk test",
+ "clean": "pnpm -r run clean && rm -rf node_modules",
+ "lint": "pnpm -r run lint",
+ "lint:check": "pnpm -r run lint:check",
+ "format": "pnpm -r run format",
+ "format:check": "pnpm -r run format:check",
+ "release": "pnpm build && changeset publish",
+ "release:snapshot": "changeset version --snapshot canary && pnpm build && changeset publish --tag canary --no-git-tag"
+ },
+ "repository": {
+ "type": "git",
+ "url": "git+https://github.com/upstash/context7.git"
+ },
+ "keywords": [
+ "modelcontextprotocol",
+ "mcp",
+ "context7",
+ "vibe-coding",
+ "developer tools",
+```
+
+This module is important because it defines how Context7 Tutorial: Live Documentation Context for Coding Agents implements the patterns covered in this chapter.
+
### `server.json`
The `server` module in [`server.json`](https://github.com/upstash/context7/blob/HEAD/server.json) handles a key part of this chapter's functionality:
@@ -93,102 +135,12 @@ The `server` module in [`server.json`](https://github.com/upstash/context7/blob/
This module is important because it defines how Context7 Tutorial: Live Documentation Context for Coding Agents implements the patterns covered in this chapter.
-### `docs/docs.json`
-
-The `docs` module in [`docs/docs.json`](https://github.com/upstash/context7/blob/HEAD/docs/docs.json) handles a key part of this chapter's functionality:
-
-```json
-{
- "$schema": "https://mintlify.com/docs.json",
- "theme": "mint",
- "name": "Context7 MCP",
- "description": "Up-to-date code docs for any prompt.",
- "colors": {
- "primary": "#10B981",
- "light": "#ECFDF5",
- "dark": "#064E3B"
- },
- "contextual": {
- "options": [
- "copy",
- "view",
- "chatgpt",
- "claude"
- ]
- },
- "navigation": {
- "groups": [
- {
- "group": "Overview",
- "pages": [
- "overview",
- "installation",
- "plans-pricing",
- "clients/cli",
- "adding-libraries",
- "api-guide",
- "skills",
- "tips"
- ]
- },
- {
- "group": "How To",
-```
-
-This module is important because it defines how Context7 Tutorial: Live Documentation Context for Coding Agents implements the patterns covered in this chapter.
-
-### `eslint.config.js`
-
-The `eslint.config` module in [`eslint.config.js`](https://github.com/upstash/context7/blob/HEAD/eslint.config.js) handles a key part of this chapter's functionality:
-
-```js
-import tseslint from "typescript-eslint";
-import eslintPluginPrettier from "eslint-plugin-prettier";
-
-export default tseslint.config({
- // Base ESLint configuration
- ignores: ["node_modules/**", "build/**", "dist/**", ".git/**", ".github/**"],
- languageOptions: {
- ecmaVersion: 2020,
- sourceType: "module",
- parser: tseslint.parser,
- parserOptions: {},
- globals: {
- // Add Node.js globals
- process: "readonly",
- require: "readonly",
- module: "writable",
- console: "readonly",
- },
- },
- // Settings for all files
- linterOptions: {
- reportUnusedDisableDirectives: true,
- },
- // Apply ESLint recommended rules
- extends: [tseslint.configs.recommended],
- plugins: {
- prettier: eslintPluginPrettier,
- },
- rules: {
- // TypeScript rules
- "@typescript-eslint/explicit-module-boundary-types": "off",
- "@typescript-eslint/no-unused-vars": ["error", { argsIgnorePattern: "^_" }],
- "@typescript-eslint/no-explicit-any": "warn",
- // Prettier integration
- "prettier/prettier": "error",
-```
-
-This module is important because it defines how Context7 Tutorial: Live Documentation Context for Coding Agents implements the patterns covered in this chapter.
-
## How These Components Connect
```mermaid
flowchart TD
- A[server]
- B[docs]
- C[eslint.config]
+ A[package]
+ B[server]
A --> B
- B --> C
```
diff --git a/tutorials/context7-tutorial/06-library-onboarding-and-documentation-quality.md b/tutorials/context7-tutorial/06-library-onboarding-and-documentation-quality.md
index d949d59e..761cdeda 100644
--- a/tutorials/context7-tutorial/06-library-onboarding-and-documentation-quality.md
+++ b/tutorials/context7-tutorial/06-library-onboarding-and-documentation-quality.md
@@ -40,10 +40,52 @@ You now can improve Context7 retrieval quality from the library-owner side.
Next: [Chapter 7: Troubleshooting and Local Development](07-troubleshooting-and-local-development.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
+### `package.json`
+
+The `package` module in [`package.json`](https://github.com/upstash/context7/blob/HEAD/package.json) handles a key part of this chapter's functionality:
+
+```json
+{
+ "name": "@upstash/context7",
+ "private": true,
+ "version": "1.0.0",
+ "description": "Context7 monorepo - Documentation tools and SDKs",
+ "workspaces": [
+ "packages/*"
+ ],
+ "scripts": {
+ "build": "pnpm -r run build",
+ "build:sdk": "pnpm --filter @upstash/context7-sdk build",
+ "build:mcp": "pnpm --filter @upstash/context7-mcp build",
+ "build:ai-sdk": "pnpm --filter @upstash/context7-tools-ai-sdk build",
+ "typecheck": "pnpm -r run typecheck",
+ "test": "pnpm -r run test",
+ "test:sdk": "pnpm --filter @upstash/context7-sdk test",
+ "test:tools-ai-sdk": "pnpm --filter @upstash/context7-tools-ai-sdk test",
+ "clean": "pnpm -r run clean && rm -rf node_modules",
+ "lint": "pnpm -r run lint",
+ "lint:check": "pnpm -r run lint:check",
+ "format": "pnpm -r run format",
+ "format:check": "pnpm -r run format:check",
+ "release": "pnpm build && changeset publish",
+ "release:snapshot": "changeset version --snapshot canary && pnpm build && changeset publish --tag canary --no-git-tag"
+ },
+ "repository": {
+ "type": "git",
+ "url": "git+https://github.com/upstash/context7.git"
+ },
+ "keywords": [
+ "modelcontextprotocol",
+ "mcp",
+ "context7",
+ "vibe-coding",
+ "developer tools",
+```
+
+This module is important because it defines how Context7 Tutorial: Live Documentation Context for Coding Agents implements the patterns covered in this chapter.
+
### `server.json`
The `server` module in [`server.json`](https://github.com/upstash/context7/blob/HEAD/server.json) handles a key part of this chapter's functionality:
@@ -88,102 +130,12 @@ The `server` module in [`server.json`](https://github.com/upstash/context7/blob/
This module is important because it defines how Context7 Tutorial: Live Documentation Context for Coding Agents implements the patterns covered in this chapter.
-### `docs/docs.json`
-
-The `docs` module in [`docs/docs.json`](https://github.com/upstash/context7/blob/HEAD/docs/docs.json) handles a key part of this chapter's functionality:
-
-```json
-{
- "$schema": "https://mintlify.com/docs.json",
- "theme": "mint",
- "name": "Context7 MCP",
- "description": "Up-to-date code docs for any prompt.",
- "colors": {
- "primary": "#10B981",
- "light": "#ECFDF5",
- "dark": "#064E3B"
- },
- "contextual": {
- "options": [
- "copy",
- "view",
- "chatgpt",
- "claude"
- ]
- },
- "navigation": {
- "groups": [
- {
- "group": "Overview",
- "pages": [
- "overview",
- "installation",
- "plans-pricing",
- "clients/cli",
- "adding-libraries",
- "api-guide",
- "skills",
- "tips"
- ]
- },
- {
- "group": "How To",
-```
-
-This module is important because it defines how Context7 Tutorial: Live Documentation Context for Coding Agents implements the patterns covered in this chapter.
-
-### `eslint.config.js`
-
-The `eslint.config` module in [`eslint.config.js`](https://github.com/upstash/context7/blob/HEAD/eslint.config.js) handles a key part of this chapter's functionality:
-
-```js
-import tseslint from "typescript-eslint";
-import eslintPluginPrettier from "eslint-plugin-prettier";
-
-export default tseslint.config({
- // Base ESLint configuration
- ignores: ["node_modules/**", "build/**", "dist/**", ".git/**", ".github/**"],
- languageOptions: {
- ecmaVersion: 2020,
- sourceType: "module",
- parser: tseslint.parser,
- parserOptions: {},
- globals: {
- // Add Node.js globals
- process: "readonly",
- require: "readonly",
- module: "writable",
- console: "readonly",
- },
- },
- // Settings for all files
- linterOptions: {
- reportUnusedDisableDirectives: true,
- },
- // Apply ESLint recommended rules
- extends: [tseslint.configs.recommended],
- plugins: {
- prettier: eslintPluginPrettier,
- },
- rules: {
- // TypeScript rules
- "@typescript-eslint/explicit-module-boundary-types": "off",
- "@typescript-eslint/no-unused-vars": ["error", { argsIgnorePattern: "^_" }],
- "@typescript-eslint/no-explicit-any": "warn",
- // Prettier integration
- "prettier/prettier": "error",
-```
-
-This module is important because it defines how Context7 Tutorial: Live Documentation Context for Coding Agents implements the patterns covered in this chapter.
-
## How These Components Connect
```mermaid
flowchart TD
- A[server]
- B[docs]
- C[eslint.config]
+ A[package]
+ B[server]
A --> B
- B --> C
```
diff --git a/tutorials/context7-tutorial/07-troubleshooting-and-local-development.md b/tutorials/context7-tutorial/07-troubleshooting-and-local-development.md
index 410db959..3a20192b 100644
--- a/tutorials/context7-tutorial/07-troubleshooting-and-local-development.md
+++ b/tutorials/context7-tutorial/07-troubleshooting-and-local-development.md
@@ -49,10 +49,52 @@ You now can operate and debug Context7 reliably across local and hosted setups.
Next: [Chapter 8: Production Operations and Governance](08-production-operations-and-governance.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
+### `package.json`
+
+The `package` module in [`package.json`](https://github.com/upstash/context7/blob/HEAD/package.json) handles a key part of this chapter's functionality:
+
+```json
+{
+ "name": "@upstash/context7",
+ "private": true,
+ "version": "1.0.0",
+ "description": "Context7 monorepo - Documentation tools and SDKs",
+ "workspaces": [
+ "packages/*"
+ ],
+ "scripts": {
+ "build": "pnpm -r run build",
+ "build:sdk": "pnpm --filter @upstash/context7-sdk build",
+ "build:mcp": "pnpm --filter @upstash/context7-mcp build",
+ "build:ai-sdk": "pnpm --filter @upstash/context7-tools-ai-sdk build",
+ "typecheck": "pnpm -r run typecheck",
+ "test": "pnpm -r run test",
+ "test:sdk": "pnpm --filter @upstash/context7-sdk test",
+ "test:tools-ai-sdk": "pnpm --filter @upstash/context7-tools-ai-sdk test",
+ "clean": "pnpm -r run clean && rm -rf node_modules",
+ "lint": "pnpm -r run lint",
+ "lint:check": "pnpm -r run lint:check",
+ "format": "pnpm -r run format",
+ "format:check": "pnpm -r run format:check",
+ "release": "pnpm build && changeset publish",
+ "release:snapshot": "changeset version --snapshot canary && pnpm build && changeset publish --tag canary --no-git-tag"
+ },
+ "repository": {
+ "type": "git",
+ "url": "git+https://github.com/upstash/context7.git"
+ },
+ "keywords": [
+ "modelcontextprotocol",
+ "mcp",
+ "context7",
+ "vibe-coding",
+ "developer tools",
+```
+
+This module is important because it defines how Context7 Tutorial: Live Documentation Context for Coding Agents implements the patterns covered in this chapter.
+
### `server.json`
The `server` module in [`server.json`](https://github.com/upstash/context7/blob/HEAD/server.json) handles a key part of this chapter's functionality:
@@ -97,102 +139,12 @@ The `server` module in [`server.json`](https://github.com/upstash/context7/blob/
This module is important because it defines how Context7 Tutorial: Live Documentation Context for Coding Agents implements the patterns covered in this chapter.
-### `docs/docs.json`
-
-The `docs` module in [`docs/docs.json`](https://github.com/upstash/context7/blob/HEAD/docs/docs.json) handles a key part of this chapter's functionality:
-
-```json
-{
- "$schema": "https://mintlify.com/docs.json",
- "theme": "mint",
- "name": "Context7 MCP",
- "description": "Up-to-date code docs for any prompt.",
- "colors": {
- "primary": "#10B981",
- "light": "#ECFDF5",
- "dark": "#064E3B"
- },
- "contextual": {
- "options": [
- "copy",
- "view",
- "chatgpt",
- "claude"
- ]
- },
- "navigation": {
- "groups": [
- {
- "group": "Overview",
- "pages": [
- "overview",
- "installation",
- "plans-pricing",
- "clients/cli",
- "adding-libraries",
- "api-guide",
- "skills",
- "tips"
- ]
- },
- {
- "group": "How To",
-```
-
-This module is important because it defines how Context7 Tutorial: Live Documentation Context for Coding Agents implements the patterns covered in this chapter.
-
-### `eslint.config.js`
-
-The `eslint.config` module in [`eslint.config.js`](https://github.com/upstash/context7/blob/HEAD/eslint.config.js) handles a key part of this chapter's functionality:
-
-```js
-import tseslint from "typescript-eslint";
-import eslintPluginPrettier from "eslint-plugin-prettier";
-
-export default tseslint.config({
- // Base ESLint configuration
- ignores: ["node_modules/**", "build/**", "dist/**", ".git/**", ".github/**"],
- languageOptions: {
- ecmaVersion: 2020,
- sourceType: "module",
- parser: tseslint.parser,
- parserOptions: {},
- globals: {
- // Add Node.js globals
- process: "readonly",
- require: "readonly",
- module: "writable",
- console: "readonly",
- },
- },
- // Settings for all files
- linterOptions: {
- reportUnusedDisableDirectives: true,
- },
- // Apply ESLint recommended rules
- extends: [tseslint.configs.recommended],
- plugins: {
- prettier: eslintPluginPrettier,
- },
- rules: {
- // TypeScript rules
- "@typescript-eslint/explicit-module-boundary-types": "off",
- "@typescript-eslint/no-unused-vars": ["error", { argsIgnorePattern: "^_" }],
- "@typescript-eslint/no-explicit-any": "warn",
- // Prettier integration
- "prettier/prettier": "error",
-```
-
-This module is important because it defines how Context7 Tutorial: Live Documentation Context for Coding Agents implements the patterns covered in this chapter.
-
## How These Components Connect
```mermaid
flowchart TD
- A[server]
- B[docs]
- C[eslint.config]
+ A[package]
+ B[server]
A --> B
- B --> C
```
diff --git a/tutorials/context7-tutorial/08-production-operations-and-governance.md b/tutorials/context7-tutorial/08-production-operations-and-governance.md
index 4b3df6a1..3e91a09e 100644
--- a/tutorials/context7-tutorial/08-production-operations-and-governance.md
+++ b/tutorials/context7-tutorial/08-production-operations-and-governance.md
@@ -41,10 +41,52 @@ You now have a complete production rollout model for documentation-grounded codi
Continue with the [Cherry Studio Tutorial](../cherry-studio-tutorial/).
-## Depth Expansion Playbook
-
## Source Code Walkthrough
+### `package.json`
+
+The `package` module in [`package.json`](https://github.com/upstash/context7/blob/HEAD/package.json) handles a key part of this chapter's functionality:
+
+```json
+{
+ "name": "@upstash/context7",
+ "private": true,
+ "version": "1.0.0",
+ "description": "Context7 monorepo - Documentation tools and SDKs",
+ "workspaces": [
+ "packages/*"
+ ],
+ "scripts": {
+ "build": "pnpm -r run build",
+ "build:sdk": "pnpm --filter @upstash/context7-sdk build",
+ "build:mcp": "pnpm --filter @upstash/context7-mcp build",
+ "build:ai-sdk": "pnpm --filter @upstash/context7-tools-ai-sdk build",
+ "typecheck": "pnpm -r run typecheck",
+ "test": "pnpm -r run test",
+ "test:sdk": "pnpm --filter @upstash/context7-sdk test",
+ "test:tools-ai-sdk": "pnpm --filter @upstash/context7-tools-ai-sdk test",
+ "clean": "pnpm -r run clean && rm -rf node_modules",
+ "lint": "pnpm -r run lint",
+ "lint:check": "pnpm -r run lint:check",
+ "format": "pnpm -r run format",
+ "format:check": "pnpm -r run format:check",
+ "release": "pnpm build && changeset publish",
+ "release:snapshot": "changeset version --snapshot canary && pnpm build && changeset publish --tag canary --no-git-tag"
+ },
+ "repository": {
+ "type": "git",
+ "url": "git+https://github.com/upstash/context7.git"
+ },
+ "keywords": [
+ "modelcontextprotocol",
+ "mcp",
+ "context7",
+ "vibe-coding",
+ "developer tools",
+```
+
+This module is important because it defines how Context7 Tutorial: Live Documentation Context for Coding Agents implements the patterns covered in this chapter.
+
### `server.json`
The `server` module in [`server.json`](https://github.com/upstash/context7/blob/HEAD/server.json) handles a key part of this chapter's functionality:
@@ -89,102 +131,12 @@ The `server` module in [`server.json`](https://github.com/upstash/context7/blob/
This module is important because it defines how Context7 Tutorial: Live Documentation Context for Coding Agents implements the patterns covered in this chapter.
-### `docs/docs.json`
-
-The `docs` module in [`docs/docs.json`](https://github.com/upstash/context7/blob/HEAD/docs/docs.json) handles a key part of this chapter's functionality:
-
-```json
-{
- "$schema": "https://mintlify.com/docs.json",
- "theme": "mint",
- "name": "Context7 MCP",
- "description": "Up-to-date code docs for any prompt.",
- "colors": {
- "primary": "#10B981",
- "light": "#ECFDF5",
- "dark": "#064E3B"
- },
- "contextual": {
- "options": [
- "copy",
- "view",
- "chatgpt",
- "claude"
- ]
- },
- "navigation": {
- "groups": [
- {
- "group": "Overview",
- "pages": [
- "overview",
- "installation",
- "plans-pricing",
- "clients/cli",
- "adding-libraries",
- "api-guide",
- "skills",
- "tips"
- ]
- },
- {
- "group": "How To",
-```
-
-This module is important because it defines how Context7 Tutorial: Live Documentation Context for Coding Agents implements the patterns covered in this chapter.
-
-### `eslint.config.js`
-
-The `eslint.config` module in [`eslint.config.js`](https://github.com/upstash/context7/blob/HEAD/eslint.config.js) handles a key part of this chapter's functionality:
-
-```js
-import tseslint from "typescript-eslint";
-import eslintPluginPrettier from "eslint-plugin-prettier";
-
-export default tseslint.config({
- // Base ESLint configuration
- ignores: ["node_modules/**", "build/**", "dist/**", ".git/**", ".github/**"],
- languageOptions: {
- ecmaVersion: 2020,
- sourceType: "module",
- parser: tseslint.parser,
- parserOptions: {},
- globals: {
- // Add Node.js globals
- process: "readonly",
- require: "readonly",
- module: "writable",
- console: "readonly",
- },
- },
- // Settings for all files
- linterOptions: {
- reportUnusedDisableDirectives: true,
- },
- // Apply ESLint recommended rules
- extends: [tseslint.configs.recommended],
- plugins: {
- prettier: eslintPluginPrettier,
- },
- rules: {
- // TypeScript rules
- "@typescript-eslint/explicit-module-boundary-types": "off",
- "@typescript-eslint/no-unused-vars": ["error", { argsIgnorePattern: "^_" }],
- "@typescript-eslint/no-explicit-any": "warn",
- // Prettier integration
- "prettier/prettier": "error",
-```
-
-This module is important because it defines how Context7 Tutorial: Live Documentation Context for Coding Agents implements the patterns covered in this chapter.
-
## How These Components Connect
```mermaid
flowchart TD
- A[server]
- B[docs]
- C[eslint.config]
+ A[package]
+ B[server]
A --> B
- B --> C
```
diff --git a/tutorials/continue-tutorial/02-code-completion.md b/tutorials/continue-tutorial/02-code-completion.md
index cc986bd0..add52de5 100644
--- a/tutorials/continue-tutorial/02-code-completion.md
+++ b/tutorials/continue-tutorial/02-code-completion.md
@@ -837,9 +837,32 @@ Keep manual control for:
- **Performance-critical code** - Optimized implementations
- **Security-sensitive code** - Encryption, authentication
+## Code Completion Architecture
+
+```mermaid
+flowchart TD
+ A[Developer types in editor]
+ B[Continue detects completion trigger]
+ C[Context gathered: file content, cursor position, open files]
+ D[Context sent to configured LLM]
+ E[LLM generates completion suggestions]
+ F[Suggestions shown as ghost text]
+ G{Developer accepts?}
+ H[Completion inserted into editor]
+ I[Suggestion dismissed]
+ A --> B
+ B --> C
+ C --> D
+ D --> E
+ E --> F
+ F --> G
+ G -- Tab/accept --> H
+ G -- Esc/ignore --> I
+```
+
## What's Next?
-Fantastic! You've mastered Continue's intelligent code completion and generation capabilities. The suggestions you're seeing now are powered by sophisticated AI that understands your context, coding patterns, and project structure.
+You've mastered Continue's intelligent code completion and generation capabilities. The suggestions you're seeing now are powered by sophisticated AI that understands your context, coding patterns, and project structure.
In [Chapter 3: Refactoring & Optimization](03-refactoring-optimization.md), we'll explore how Continue can help you improve existing code - identifying performance bottlenecks, suggesting architectural improvements, and modernizing legacy code.
diff --git a/tutorials/continue-tutorial/03-refactoring-optimization.md b/tutorials/continue-tutorial/03-refactoring-optimization.md
index 0718982e..8b68e771 100644
--- a/tutorials/continue-tutorial/03-refactoring-optimization.md
+++ b/tutorials/continue-tutorial/03-refactoring-optimization.md
@@ -635,9 +635,32 @@ suite
.run();
```
+## Refactoring Workflow
+
+```mermaid
+flowchart TD
+ A[Developer selects code in editor]
+ B[Cmd+I opens inline edit with selection]
+ C[Developer describes refactoring goal]
+ D[Context sent to LLM: selected code + instructions]
+ E[LLM generates refactored version]
+ F[Diff shown in editor]
+ G{Accept or reject?}
+ H[Refactored code replaces original]
+ I[Original preserved]
+ A --> B
+ B --> C
+ C --> D
+ D --> E
+ E --> F
+ F --> G
+ G -- accept --> H
+ G -- reject --> I
+```
+
## What's Next?
-Excellent! You've learned how Continue can transform your code through intelligent refactoring and optimization. The ability to analyze existing code and suggest improvements is incredibly powerful for maintaining high-quality codebases.
+You've learned how Continue can transform your code through intelligent refactoring and optimization. The ability to analyze existing code and suggest improvements is incredibly powerful for maintaining high-quality codebases.
In [Chapter 4: Documentation & Comments](04-documentation-comments.md), we'll explore how Continue can help you create comprehensive documentation and improve code readability through intelligent commenting.
diff --git a/tutorials/continue-tutorial/04-documentation-comments.md b/tutorials/continue-tutorial/04-documentation-comments.md
index a784d64f..3fd2fa9d 100644
--- a/tutorials/continue-tutorial/04-documentation-comments.md
+++ b/tutorials/continue-tutorial/04-documentation-comments.md
@@ -712,9 +712,28 @@ def validate_documentation_quality(code_file):
- Include practical examples and use cases
- Provide navigation and cross-references
+## Documentation Generation Flow
+
+```mermaid
+flowchart TD
+ A[Developer selects function or class]
+ B[Invoke /doc slash command or Cmd+I]
+ C[Continue analyzes code structure and signature]
+ D[LLM generates docstring or comment block]
+ E[Documentation inserted above selection]
+ F[Developer reviews and edits as needed]
+ G[README generation: /doc for whole file]
+ A --> B
+ B --> C
+ C --> D
+ D --> E
+ E --> F
+ F --> G
+```
+
## What's Next?
-Excellent work on mastering Continue's documentation capabilities! You've learned how to generate comprehensive documentation that explains not just what code does, but why and how it works.
+You've mastered Continue's documentation capabilities! You've learned how to generate comprehensive documentation that explains not just what code does, but why and how it works.
In [Chapter 5: Debugging & Testing](05-debugging-testing.md), we'll explore how Continue can help you identify bugs, write better tests, and ensure code reliability through intelligent debugging and testing assistance.
diff --git a/tutorials/continue-tutorial/05-debugging-testing.md b/tutorials/continue-tutorial/05-debugging-testing.md
index cdf3bca7..039d93f1 100644
--- a/tutorials/continue-tutorial/05-debugging-testing.md
+++ b/tutorials/continue-tutorial/05-debugging-testing.md
@@ -674,9 +674,30 @@ describe('PasswordValidator', () => {
- Implement error tracking and alerting
- Use profiling tools for performance issues
+## Debugging and Testing Flow
+
+```mermaid
+flowchart TD
+ A[Error occurs or test fails]
+ B[Paste error stack trace into Continue chat]
+ C[LLM analyzes error context and codebase]
+ D[Root cause explanation provided]
+ E[Fix suggestion shown]
+ F[Developer applies fix]
+ G[Continue generates test for the fixed scenario]
+ H[Test run confirms fix]
+ A --> B
+ B --> C
+ C --> D
+ D --> E
+ E --> F
+ F --> G
+ G --> H
+```
+
## What's Next?
-Fantastic! You've mastered Continue's debugging and testing capabilities. The ability to generate comprehensive tests and provide intelligent debugging guidance is incredibly powerful for ensuring code quality and reliability.
+You've mastered Continue's debugging and testing capabilities. The ability to generate comprehensive tests and provide intelligent debugging guidance is incredibly powerful for ensuring code quality and reliability.
In [Chapter 6: Custom Models & Configuration](06-custom-models.md), we'll explore how to configure Continue with custom AI models and create personalized development environments.
diff --git a/tutorials/continue-tutorial/06-custom-models.md b/tutorials/continue-tutorial/06-custom-models.md
index 5efac32a..540460c6 100644
--- a/tutorials/continue-tutorial/06-custom-models.md
+++ b/tutorials/continue-tutorial/06-custom-models.md
@@ -765,9 +765,29 @@ class MultiModelOrchestrator {
}
```
+## Custom Model Configuration
+
+```mermaid
+flowchart TD
+ A[Edit config.json in ~/.continue/]
+ B[Add model entry: provider, model, apiKey]
+ C[Continue loads config on restart]
+ D{Provider type}
+ E[Cloud: Anthropic, OpenAI, Gemini API calls]
+ F[Local: Ollama or LM Studio endpoint]
+ G[Model available in chat and completion]
+ A --> B
+ B --> C
+ C --> D
+ D -- cloud --> E
+ D -- local --> F
+ E --> G
+ F --> G
+```
+
## What's Next?
-Excellent! You've learned how to customize Continue for your specific needs and preferences. The ability to configure custom models, create personalized prompts, and build custom tools makes Continue incredibly powerful for your unique development workflow.
+You've learned how to customize Continue for your specific needs and preferences. The ability to configure custom models, create personalized prompts, and build custom tools makes Continue incredibly powerful for your unique development workflow.
In [Chapter 7: Team Collaboration & Sharing](07-team-collaboration.md), we'll explore how to share your Continue configurations, collaborate with team members, and create shared development environments.
diff --git a/tutorials/continue-tutorial/07-team-collaboration.md b/tutorials/continue-tutorial/07-team-collaboration.md
index c5b6a7a6..472313ae 100644
--- a/tutorials/continue-tutorial/07-team-collaboration.md
+++ b/tutorials/continue-tutorial/07-team-collaboration.md
@@ -699,9 +699,28 @@ class TeamPerformanceDashboard {
}
```
+## Team Collaboration Architecture
+
+```mermaid
+flowchart TD
+ A[Team shares .continue/ config in repository]
+ B[config.json defines shared models and prompts]
+ C[Custom slash commands committed to .continue/prompts/]
+ D[Team members get consistent AI behavior]
+ E[New member clones repo and gets config automatically]
+ F[Team-specific context docs added to @codebase index]
+ G[Shared prompt library reduces duplicate work]
+ A --> B
+ B --> C
+ C --> D
+ D --> E
+ E --> F
+ F --> G
+```
+
## What's Next?
-Excellent! You've mastered the art of collaborative AI development with Continue. The ability to share configurations, workflows, and knowledge across teams creates a powerful collaborative environment that scales with your organization.
+You've mastered the art of collaborative AI development with Continue. The ability to share configurations, workflows, and knowledge across teams creates a powerful collaborative environment that scales with your organization.
In [Chapter 8: Advanced Enterprise Features](08-advanced-enterprise.md), we'll explore enterprise-grade features including security, compliance, audit trails, and advanced deployment strategies.
diff --git a/tutorials/continue-tutorial/08-advanced-enterprise.md b/tutorials/continue-tutorial/08-advanced-enterprise.md
index f7239bd1..e6b574a9 100644
--- a/tutorials/continue-tutorial/08-advanced-enterprise.md
+++ b/tutorials/continue-tutorial/08-advanced-enterprise.md
@@ -791,9 +791,28 @@ class CostOptimizationEngine {
}
```
+## Enterprise Architecture
+
+```mermaid
+flowchart TD
+ A[Enterprise Continue deployment]
+ B[Private LLM endpoint or gateway]
+ C[All AI requests routed through approved gateway]
+ D[Audit logs capture prompts and completions]
+ E[Data residency controls enforced]
+ F[SSO and permission policies applied]
+ G[Usage metrics and cost tracking per team]
+ A --> B
+ B --> C
+ C --> D
+ C --> E
+ C --> F
+ C --> G
+```
+
## What's Next?
-🎉 **Congratulations!** You've completed the comprehensive Continue tutorial and reached the pinnacle of enterprise-grade AI development capabilities. You've mastered everything from basic setup to advanced enterprise features including security, compliance, audit trails, multi-cloud deployment, and cost optimization.
+You've completed the comprehensive Continue tutorial and reached the pinnacle of enterprise-grade AI development capabilities. You've mastered everything from basic setup to advanced enterprise features including security, compliance, audit trails, multi-cloud deployment, and cost optimization.
## Your Continue Journey Summary
diff --git a/tutorials/copilotkit-tutorial/02-app-context.md b/tutorials/copilotkit-tutorial/02-app-context.md
index ef4a9193..060a629c 100644
--- a/tutorials/copilotkit-tutorial/02-app-context.md
+++ b/tutorials/copilotkit-tutorial/02-app-context.md
@@ -750,6 +750,24 @@ export function useVersionedCopilotReadable(data: any, description: string) {
}
```
+## App Context Flow
+
+```mermaid
+flowchart TD
+ A[React component has state]
+ B[useCopilotReadable registers state with AI]
+ C[User sends message to Copilot]
+ D[CopilotKit includes readable context in LLM prompt]
+ E[LLM responds with awareness of app state]
+ F[Context updates when state changes]
+ A --> B
+ B --> C
+ C --> D
+ D --> E
+ B --> F
+ F --> D
+```
+
## Summary
In this chapter, we've covered:
diff --git a/tutorials/copilotkit-tutorial/03-copilot-actions.md b/tutorials/copilotkit-tutorial/03-copilot-actions.md
index ae546fa4..f87267f2 100644
--- a/tutorials/copilotkit-tutorial/03-copilot-actions.md
+++ b/tutorials/copilotkit-tutorial/03-copilot-actions.md
@@ -897,6 +897,30 @@ export function useRobustCopilotAction(actionConfig: {
}
```
+## Copilot Actions Flow
+
+```mermaid
+flowchart TD
+ A[useCopilotAction registers action with name and parameters]
+ B[User asks AI to perform an action]
+ C[LLM decides to call the registered action]
+ D[CopilotKit invokes handler with parsed parameters]
+ E{renderAndWait or direct?}
+ F[UI confirmation component shown to user]
+ G[User approves or rejects]
+ H[Action handler executes]
+ I[App state updated]
+ A --> B
+ B --> C
+ C --> D
+ D --> E
+ E -- renderAndWait --> F
+ F --> G
+ G -- approve --> H
+ E -- direct --> H
+ H --> I
+```
+
## Summary
In this chapter, we've covered:
diff --git a/tutorials/copilotkit-tutorial/04-chat-components.md b/tutorials/copilotkit-tutorial/04-chat-components.md
index 25efb6ca..7b3acbdb 100644
--- a/tutorials/copilotkit-tutorial/04-chat-components.md
+++ b/tutorials/copilotkit-tutorial/04-chat-components.md
@@ -805,6 +805,29 @@ export function CustomChatUI() {
}
```
+## Chat Component Architecture
+
+```mermaid
+flowchart TD
+ A[CopilotKit provider wraps app]
+ B{Chat component choice}
+ C[CopilotSidebar: sliding panel overlay]
+ D[CopilotChat: embedded inline component]
+ E[CopilotPopup: floating chat button]
+ F[User sends message]
+ G[Message routed to configured LLM]
+ H[Response streamed to chat UI]
+ A --> B
+ B --> C
+ B --> D
+ B --> E
+ C --> F
+ D --> F
+ E --> F
+ F --> G
+ G --> H
+```
+
## Summary
In this chapter, we've covered:
diff --git a/tutorials/copilotkit-tutorial/05-generative-ui.md b/tutorials/copilotkit-tutorial/05-generative-ui.md
index 279b11d4..6c542cb5 100644
--- a/tutorials/copilotkit-tutorial/05-generative-ui.md
+++ b/tutorials/copilotkit-tutorial/05-generative-ui.md
@@ -707,6 +707,25 @@ export function InteractiveGenerator() {
}
```
+## Generative UI Flow
+
+```mermaid
+flowchart TD
+ A[User requests dynamic interface in chat]
+ B[LLM decides to render a UI component]
+ C[useCopilotAction with render function invoked]
+ D[React component rendered inline in chat]
+ E[User interacts with generated component]
+ F[Interaction result passed back to agent]
+ G[Agent continues conversation with result]
+ A --> B
+ B --> C
+ C --> D
+ D --> E
+ E --> F
+ F --> G
+```
+
## Summary
In this chapter, we've covered:
diff --git a/tutorials/copilotkit-tutorial/06-coagents.md b/tutorials/copilotkit-tutorial/06-coagents.md
index d83e827e..b083bc6f 100644
--- a/tutorials/copilotkit-tutorial/06-coagents.md
+++ b/tutorials/copilotkit-tutorial/06-coagents.md
@@ -782,6 +782,27 @@ export function MultiAgentCollaboration() {
}
```
+## CoAgents Architecture
+
+```mermaid
+flowchart TD
+ A[User sends message to CopilotKit]
+ B[Request forwarded to LangGraph agent backend]
+ C[Agent graph starts execution]
+ D[Agent node processes and calls tools]
+ E[Intermediate state streamed to frontend]
+ F[useCoAgent hook exposes state to React]
+ G[UI updates in real time with agent progress]
+ H[Final result returned]
+ A --> B
+ B --> C
+ C --> D
+ D --> E
+ E --> F
+ F --> G
+ D --> H
+```
+
## Summary
In this chapter, we've covered:
diff --git a/tutorials/copilotkit-tutorial/07-human-in-loop.md b/tutorials/copilotkit-tutorial/07-human-in-loop.md
index 243a74e9..c6ab4c4c 100644
--- a/tutorials/copilotkit-tutorial/07-human-in-loop.md
+++ b/tutorials/copilotkit-tutorial/07-human-in-loop.md
@@ -1080,6 +1080,27 @@ export function MultiLevelApproval() {
}
```
+## Human-in-the-Loop Flow
+
+```mermaid
+flowchart TD
+ A[Agent proposes action requiring approval]
+ B[Workflow interrupted at approval node]
+ C[useCopilotAction renderAndWait invoked]
+ D[Approval UI rendered in chat]
+ E{User decision}
+ F[Approval signal sent to backend]
+ G[Workflow resumes from interrupted state]
+ H[Action cancelled]
+ A --> B
+ B --> C
+ C --> D
+ D --> E
+ E -- approve --> F
+ F --> G
+ E -- reject --> H
+```
+
## Summary
In this chapter, we've covered:
diff --git a/tutorials/create-python-server-tutorial/01-getting-started-and-scaffolding-workflow.md b/tutorials/create-python-server-tutorial/01-getting-started-and-scaffolding-workflow.md
index 27814cba..40ad8b42 100644
--- a/tutorials/create-python-server-tutorial/01-getting-started-and-scaffolding-workflow.md
+++ b/tutorials/create-python-server-tutorial/01-getting-started-and-scaffolding-workflow.md
@@ -5,48 +5,91 @@ nav_order: 1
parent: Create Python Server Tutorial
---
-
# Chapter 1: Getting Started and Scaffolding Workflow
-Welcome to **Chapter 1: Getting Started and Scaffolding Workflow**. In this part of **Create Python Server Tutorial: Scaffold and Ship MCP Servers with uvx**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
-
+`create-python-server` is a `uvx`-based scaffolding tool that generates a complete, ready-to-run MCP server project in Python. This chapter covers prerequisites, the generation workflow, and the initial run sequence.
-This chapter covers initial project generation and first-run commands.
+> **Archive notice**: The `modelcontextprotocol/create-python-server` repository is archived. The scaffold it generates remains functional and the generated pattern (FastMCP or low-level Server API) is still the recommended approach, but the generator itself receives no further updates. See Chapter 8 for migration context.
## Learning Goals
-- scaffold a new MCP Python server via `uvx create-mcp-server`
-- understand prerequisites (`uv` tooling) and generated output
-- run the generated server locally with minimal setup
-- avoid onboarding drift across team environments
+- Scaffold a new MCP Python server via `uvx create-mcp-server`
+- Understand prerequisites: `uv` toolchain and minimum version check
+- Run the generated server locally with minimal setup
+- Avoid onboarding drift across team environments
+
+## Prerequisites
-## Quick Start
+The only system requirement is [`uv`](https://github.com/astral-sh/uv) at version 0.4.10 or higher. The generator checks this at startup and exits with a clear error if the version is insufficient.
```bash
-uvx create-mcp-server
+# Verify uv is installed at the right version
+uv --version # should be >= 0.4.10
+
+# Install or upgrade uv if needed
+curl -LsSf https://astral.sh/uv/install.sh | sh
```
-After generation, run `uv sync --dev --all-extras` and `uv run ` from the created project directory.
+`uvx` is bundled with `uv` — no separate install step is needed.
-## Source References
+## Scaffolding Workflow
-- [Create Python Server README](https://github.com/modelcontextprotocol/create-python-server/blob/main/README.md)
+```mermaid
+flowchart TD
+ A[Run: uvx create-mcp-server]
+ A --> B[Generator checks uv version]
+ B --> C{uv >= 0.4.10?}
+ C -- No --> FAIL[Exit with install instructions]
+ C -- Yes --> D[Prompt: project name\nproject description]
+ D --> E[uv init: create project\nwith pyproject.toml]
+ E --> F[Add mcp dependency to pyproject.toml]
+ F --> G[Copy Jinja2 templates:\nserver.py · __init__.py · README.md]
+ G --> H{Claude Desktop\ninstalled?}
+ H -- Yes --> CLAUDE[Update claude_desktop_config.json\nautomatically]
+ H -- No --> DONE[Done: project directory ready]
+ CLAUDE --> DONE
+```
-## Summary
+## Running the Generator
+
+```bash
+# Interactive mode — prompts for name and description
+uvx create-mcp-server
+
+# Example session:
+# Project name: my-notes-server
+# Project description: A simple MCP server for managing notes
+# Created project at: ./my-notes-server
+```
-You now have a reproducible baseline for generating MCP Python server projects.
+After generation, the project directory contains everything needed to run immediately:
-Next: [Chapter 2: Generated Project Structure and Conventions](02-generated-project-structure-and-conventions.md)
+```bash
+cd my-notes-server
+
+# Install dependencies (creates .venv, installs mcp and dependencies)
+uv sync --dev --all-extras
-## Source Code Walkthrough
+# Run the server in development mode via MCP Inspector
+npx @modelcontextprotocol/inspector uv --directory . run my-notes-server
-### `src/create_mcp_server/__init__.py`
+# Or run directly (stdio mode — for Claude Desktop integration)
+uv run my-notes-server
+```
-The `PyProject` class in [`src/create_mcp_server/__init__.py`](https://github.com/modelcontextprotocol/create-python-server/blob/HEAD/src/create_mcp_server/__init__.py) handles a key part of this chapter's functionality:
+## What the Generator Does Internally
-```py
+The generator entry point lives in `src/create_mcp_server/__main__.py` which calls `main()` from `__init__.py`. The main function:
+1. Checks `uv` version via `check_uv_version()` against `MIN_UV_VERSION = "0.4.10"`
+2. Prompts for project name and description using `click`
+3. Calls `uv init ` as a subprocess to initialize a standard Python project
+4. Modifies the generated `pyproject.toml` to add `mcp>=1.0.0` as a dependency
+5. Calls `copy_template()` to render Jinja2 templates into the project
+6. Optionally calls `update_claude_config()` to register the server with Claude Desktop
+```python
+# From src/create_mcp_server/__init__.py
class PyProject:
def __init__(self, path: Path):
self.data = toml.load(path)
@@ -59,32 +102,35 @@ class PyProject:
def first_binary(self) -> str | None:
scripts = self.data["project"].get("scripts", {})
return next(iter(scripts.keys()), None)
+```
+The `PyProject` class reads the generated `pyproject.toml` to extract the project name and entry-point binary name, which are then used as template variables when rendering `server.py.jinja2`.
-def check_uv_version(required_version: str) -> str | None:
- """Check if uv is installed and has minimum version"""
- try:
- result = subprocess.run(
- ["uv", "--version"], capture_output=True, text=True, check=True
- )
- version = result.stdout.strip()
- match = re.match(r"uv (\d+\.\d+\.\d+)", version)
- if match:
- version_num = match.group(1)
- if parse(version_num) >= parse(required_version):
- return version
- return None
- except subprocess.CalledProcessError:
- click.echo("❌ Error: Failed to check uv version.", err=True)
- sys.exit(1)
-```
+## First-Run Verification
-This class is important because it defines how Create Python Server Tutorial: Scaffold and Ship MCP Servers with uvx implements the patterns covered in this chapter.
+After running `uv sync` and launching the server via the Inspector, you should see:
+1. The Inspector browser UI at `localhost:5173`
+2. One tool registered: `add-note`
+3. Zero resources initially (resources are note-URI-based; empty at start)
+4. One prompt: `summarize-notes`
-## How These Components Connect
+```bash
+# Verify the generated binary runs without errors
+uv run my-notes-server --help # if --help is supported, or just check process exits cleanly
-```mermaid
-flowchart TD
- A[PyProject]
+# Inspect it interactively
+npx @modelcontextprotocol/inspector uv --directory /path/to/my-notes-server run my-notes-server
```
+
+## Source References
+
+- [Create Python Server README](https://github.com/modelcontextprotocol/create-python-server/blob/main/README.md)
+- [Generator Entry Point: `__main__.py`](https://github.com/modelcontextprotocol/create-python-server/blob/main/src/create_mcp_server/__main__.py)
+- [Generator Logic: `__init__.py`](https://github.com/modelcontextprotocol/create-python-server/blob/main/src/create_mcp_server/__init__.py)
+
+## Summary
+
+The `uvx create-mcp-server` command scaffolds a complete MCP server project in seconds. The generator verifies `uv` version, prompts for metadata, runs `uv init`, installs the `mcp` dependency, and renders templates from `src/create_mcp_server/template/`. The result is immediately runnable via `uv run ` and testable in the MCP Inspector.
+
+Next: [Chapter 2: Generated Project Structure and Conventions](02-generated-project-structure-and-conventions.md)
diff --git a/tutorials/create-python-server-tutorial/02-generated-project-structure-and-conventions.md b/tutorials/create-python-server-tutorial/02-generated-project-structure-and-conventions.md
index 18fecf23..1f30297e 100644
--- a/tutorials/create-python-server-tutorial/02-generated-project-structure-and-conventions.md
+++ b/tutorials/create-python-server-tutorial/02-generated-project-structure-and-conventions.md
@@ -5,87 +5,157 @@ nav_order: 2
parent: Create Python Server Tutorial
---
-
# Chapter 2: Generated Project Structure and Conventions
-Welcome to **Chapter 2: Generated Project Structure and Conventions**. In this part of **Create Python Server Tutorial: Scaffold and Ship MCP Servers with uvx**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
+This chapter maps every file generated by `create-mcp-server`, explains the naming conventions the generator enforces, and shows how each piece supports maintainable server development.
+## Learning Goals
-This chapter explains generated file layout and how each piece supports maintainable server development.
+- Navigate the scaffolded project structure at every path
+- Map template files to runtime behavior and MCP primitive registration
+- Understand naming and package conventions used by the generator
+- Keep customization changes isolated from generated boilerplate
-## Learning Goals
+## Generated Directory Layout
-- navigate scaffolded project structure (`README`, `pyproject.toml`, `src/*`)
-- map template files to runtime behavior
-- understand naming/package conventions used by the generator
-- keep customization changes isolated from generated boilerplate
+```
+my-notes-server/
+├── README.md # Rendered from README.md.jinja2
+├── pyproject.toml # uv project config + mcp dependency
+├── uv.lock # Locked dependency tree
+└── src/
+ └── my_notes_server/ # Package dir: project name, hyphens → underscores
+ ├── __init__.py # Rendered from __init__.py.jinja2 (entry point)
+ └── server.py # Rendered from server.py.jinja2 (MCP handlers)
+```
-## Structure Overview
+```mermaid
+graph TD
+ ROOT[my-notes-server/]
+ ROOT --> README[README.md\nUsage + integration guide]
+ ROOT --> PYPROJECT[pyproject.toml\nPackaging + dependencies]
+ ROOT --> LOCK[uv.lock\nReproducible dependency tree]
+ ROOT --> SRC[src/]
+ SRC --> PKG[my_notes_server/\nPython package]
+ PKG --> INIT[__init__.py\nMain entry point\ncalls asyncio.run on server.main]
+ PKG --> SERVER[server.py\nMCP handlers:\ntools · resources · prompts]
+```
-| Path | Purpose |
-|:-----|:--------|
-| `README.md` | usage and integration instructions |
-| `pyproject.toml` | packaging and dependency definition |
-| `src//server.py` | MCP primitives and handler logic |
+## File-by-File Breakdown
-## Source References
+### `pyproject.toml`
-- [Create Python Server README](https://github.com/modelcontextprotocol/create-python-server/blob/main/README.md)
-- [Template README](https://github.com/modelcontextprotocol/create-python-server/blob/main/src/create_mcp_server/template/README.md.jinja2)
+The generator modifies the `uv init`-generated `pyproject.toml` to add:
+- `mcp>=1.0.0` as a runtime dependency
+- A `[project.scripts]` entry pointing the binary name at `:main`
-## Summary
+```toml
+[project]
+name = "my-notes-server"
+version = "0.1.0"
+description = "A simple MCP server for managing notes"
+requires-python = ">=3.10"
+dependencies = ["mcp>=1.0.0"]
-You now have a structural map for generated MCP Python server projects.
+[project.scripts]
+my-notes-server = "my_notes_server:main"
-Next: [Chapter 3: Template Server Architecture: Resources, Prompts, and Tools](03-template-server-architecture-resources-prompts-and-tools.md)
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+```
+
+The `[project.scripts]` entry is what makes `uv run my-notes-server` and `uvx my-notes-server` work — it maps the binary name to the `main()` function in `__init__.py`.
-## Source Code Walkthrough
+### `src//__init__.py`
+
+Rendered from `__init__.py.jinja2`, this file provides the synchronous entry point:
+
+```python
+from . import server
+import asyncio
+
+def main():
+ asyncio.run(server.main())
+```
-### `src/create_mcp_server/__init__.py`
+The generator uses the `first_binary` property of the `PyProject` class to ensure the function name matches the scripts entry. This indirection keeps `server.py` purely async and testable in isolation.
-The `check_uv_version` function in [`src/create_mcp_server/__init__.py`](https://github.com/modelcontextprotocol/create-python-server/blob/HEAD/src/create_mcp_server/__init__.py) handles a key part of this chapter's functionality:
+### `src//server.py`
-```py
+The core implementation file, rendered from `server.py.jinja2`. This is where all MCP primitive handlers live. It is the primary file developers modify after scaffolding.
+### `README.md`
-def check_uv_version(required_version: str) -> str | None:
- """Check if uv is installed and has minimum version"""
- try:
- result = subprocess.run(
- ["uv", "--version"], capture_output=True, text=True, check=True
- )
- version = result.stdout.strip()
- match = re.match(r"uv (\d+\.\d+\.\d+)", version)
- if match:
- version_num = match.group(1)
- if parse(version_num) >= parse(required_version):
- return version
- return None
- except subprocess.CalledProcessError:
- click.echo("❌ Error: Failed to check uv version.", err=True)
- sys.exit(1)
- except FileNotFoundError:
- return None
+Rendered from `README.md.jinja2`, the README contains:
+- Installation instructions (`uv sync --dev --all-extras`)
+- Claude Desktop configuration snippet (pre-filled with the project name)
+- Development command (`npx @modelcontextprotocol/inspector ...`)
+- Build and publish instructions (`uv build`, `uv publish`)
+## Naming Conventions
-def ensure_uv_installed() -> None:
- """Ensure uv is installed at minimum version"""
- if check_uv_version(MIN_UV_VERSION) is None:
- click.echo(
- f"❌ Error: uv >= {MIN_UV_VERSION} is required but not installed.", err=True
- )
- click.echo("To install, visit: https://github.com/astral-sh/uv", err=True)
- sys.exit(1)
+The generator enforces Python package naming from the project name string:
+| Input | Converted to |
+|:------|:-------------|
+| `my-notes-server` | `my_notes_server` (package dir, hyphens → underscores) |
+| `my-notes-server` | `my-notes-server` (binary name in scripts, preserved) |
+| `my-notes-server` | `"my-notes-server"` (server name in `Server("...")` call) |
+```mermaid
+flowchart LR
+ INPUT[project name: my-notes-server]
+ INPUT -->|hyphens to underscores| PKG[package dir:\nsrc/my_notes_server/]
+ INPUT -->|preserved| BIN[binary:\nuv run my-notes-server]
+ INPUT -->|preserved| SNAME[Server name:\nServer\nmy-notes-server\n]
+```
+
+**Important**: The Jinja2 templates reference `{{server_name}}` for display name and `{{binary_name}}` for the entry point. These are substituted by `copy_template()` during generation and are not present in the final generated files.
+
+## Template Rendering
+
+The `copy_template()` function in `__init__.py` uses Jinja2 to render all three template files:
+
+```python
+template_vars = {
+ "binary_name": bin_name, # from pyproject.toml scripts
+ "server_name": name, # project name as entered
+ "server_version": version, # "0.1.0" default
+ "server_description": description,
+ "server_directory": str(path.resolve()),
+}
```
-This function is important because it defines how Create Python Server Tutorial: Scaffold and Ship MCP Servers with uvx implements the patterns covered in this chapter.
+Files rendered:
+| Template | Output Location | Key Variables Used |
+|:---------|:----------------|:-------------------|
+| `__init__.py.jinja2` | `src//__init__.py` | `binary_name` |
+| `server.py.jinja2` | `src//server.py` | `server_name`, `server_version` |
+| `README.md.jinja2` | `README.md` | `server_name`, `binary_name`, `server_directory` |
-## How These Components Connect
+## Post-Generation File Ownership
```mermaid
-flowchart TD
- A[check_uv_version]
+graph LR
+ GENERATED[Generated Files]
+ GENERATED --> STABLE[Stable — rarely change:\npyproject.toml · uv.lock\n__init__.py]
+ GENERATED --> MODIFY[Primary modification target:\nserver.py]
+ GENERATED --> DOCS[Keep updated:\nREADME.md]
```
+
+The convention is: treat `__init__.py` as scaffolding boilerplate (don't modify), and concentrate all MCP logic in `server.py`. When customizing heavily, split `server.py` into multiple modules and import them — but keep the `server.py` file as the handler registration hub.
+
+## Source References
+
+- [Template Server (`server.py.jinja2`)](https://github.com/modelcontextprotocol/create-python-server/blob/main/src/create_mcp_server/template/server.py.jinja2)
+- [Template Entry Point (`__init__.py.jinja2`)](https://github.com/modelcontextprotocol/create-python-server/blob/main/src/create_mcp_server/template/__init__.py.jinja2)
+- [Template README (`README.md.jinja2`)](https://github.com/modelcontextprotocol/create-python-server/blob/main/src/create_mcp_server/template/README.md.jinja2)
+- [Generator Logic (`__init__.py`)](https://github.com/modelcontextprotocol/create-python-server/blob/main/src/create_mcp_server/__init__.py)
+
+## Summary
+
+The generator produces a five-file project: `pyproject.toml`, `uv.lock`, `README.md`, `__init__.py` (entry point shim), and `server.py` (handler implementation). Naming follows Python package conventions (hyphens → underscores for directory, preserved for binary). All customization should focus on `server.py`; treat the rest as scaffolding until deliberate changes are needed.
+
+Next: [Chapter 3: Template Server Architecture: Resources, Prompts, and Tools](03-template-server-architecture-resources-prompts-and-tools.md)
diff --git a/tutorials/create-python-server-tutorial/03-template-server-architecture-resources-prompts-and-tools.md b/tutorials/create-python-server-tutorial/03-template-server-architecture-resources-prompts-and-tools.md
index 9a60e291..eb5dc739 100644
--- a/tutorials/create-python-server-tutorial/03-template-server-architecture-resources-prompts-and-tools.md
+++ b/tutorials/create-python-server-tutorial/03-template-server-architecture-resources-prompts-and-tools.md
@@ -5,85 +5,219 @@ nav_order: 3
parent: Create Python Server Tutorial
---
-
# Chapter 3: Template Server Architecture: Resources, Prompts, and Tools
-Welcome to **Chapter 3: Template Server Architecture: Resources, Prompts, and Tools**. In this part of **Create Python Server Tutorial: Scaffold and Ship MCP Servers with uvx**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
+This chapter dives into `server.py.jinja2` — the generated server template — and explains precisely how it models the three MCP primitives: resources (note URIs), prompts (summarize-notes template), and tools (add-note mutation).
+## Learning Goals
-This chapter dives into the generated server template and how it models core MCP primitives.
+- Inspect the generated handlers for resource, prompt, and tool endpoints
+- Understand state management patterns in the template code
+- Map primitive behavior to MCP protocol semantics
+- Identify extension points for domain-specific logic
-## Learning Goals
+## Template Overview
-- inspect generated handlers for resource, prompt, and tool endpoints
-- understand state management patterns in template code
-- map primitive behavior to MCP protocol semantics
-- identify extension points for domain-specific logic
+The generated `server.py` uses the **low-level `Server` API** from `mcp.server`. It does not use FastMCP decorators — this makes every handler and lifecycle step explicit and educational.
-## Template Highlights
+```mermaid
+graph TD
+ SERVER[Server\nmy-notes-server]
+ STATE[In-memory state:\nnotes: dict-str-str-]
+ SERVER --> LR[list_resources\nHandler]
+ SERVER --> RR[read_resource\nHandler]
+ SERVER --> LP[list_prompts\nHandler]
+ SERVER --> GP[get_prompt\nHandler]
+ SERVER --> LT[list_tools\nHandler]
+ SERVER --> CT[call_tool\nHandler]
+ CT -->|mutates| STATE
+ LR -->|reads| STATE
+ RR -->|reads| STATE
+ GP -->|reads| STATE
+```
-- `list_resources` and `read_resource` expose note-based URI resources.
-- `list_prompts` and `get_prompt` generate argument-aware prompt messages.
-- `list_tools` and `call_tool` demonstrate tool registration, validation, and state mutation.
+## State Model
-## Source References
+The template stores notes in a module-level dictionary:
-- [Template Server Implementation](https://github.com/modelcontextprotocol/create-python-server/blob/main/src/create_mcp_server/template/server.py.jinja2)
-- [Template README](https://github.com/modelcontextprotocol/create-python-server/blob/main/src/create_mcp_server/template/README.md.jinja2)
+```python
+notes: dict[str, str] = {}
+server = Server("{{server_name}}")
+```
-## Summary
+This in-memory model is intentional — it demonstrates stateful server behavior (tools mutate, resources reflect mutations) without external dependencies. In production servers, replace this dict with your actual data layer.
-You now have a concrete mental model for generated MCP primitive handlers.
+## Resources: `list_resources` and `read_resource`
-Next: [Chapter 4: Runtime, Dependencies, and uv Packaging](04-runtime-dependencies-and-uv-packaging.md)
+Resources expose the current notes as URI-addressed data. Each note is accessible at `note://internal/`.
-## Source Code Walkthrough
+```python
+@server.list_resources()
+async def handle_list_resources() -> list[types.Resource]:
+ return [
+ types.Resource(
+ uri=AnyUrl(f"note://internal/{name}"),
+ name=f"Note: {name}",
+ description=f"A simple note named {name}",
+ mimeType="text/plain",
+ )
+ for name in notes
+ ]
+
+@server.read_resource()
+async def handle_read_resource(uri: AnyUrl) -> str:
+ if uri.scheme != "note":
+ raise ValueError(f"Unsupported URI scheme: {uri.scheme}")
+ name = uri.path.lstrip("/") if uri.path else None
+ return notes[name]
+```
-### `src/create_mcp_server/__init__.py`
+Resource design patterns demonstrated here:
+- **Custom URI scheme** (`note://`): servers define their own URI namespaces
+- **Dynamic list**: `list_resources` reflects live state, not a static catalog
+- **Scheme validation**: `read_resource` rejects URIs with unexpected schemes explicitly
+- **MimeType declaration**: `"text/plain"` tells clients how to render the content
-The `ensure_uv_installed` function in [`src/create_mcp_server/__init__.py`](https://github.com/modelcontextprotocol/create-python-server/blob/HEAD/src/create_mcp_server/__init__.py) handles a key part of this chapter's functionality:
+```mermaid
+sequenceDiagram
+ participant Client
+ participant Server
-```py
+ Client->>Server: resources/list
+ Server-->>Client: [{uri: "note://internal/meeting", name: "Note: meeting", ...}]
+ Client->>Server: resources/read {uri: "note://internal/meeting"}
+ Server-->>Client: {contents: [{text: "Meeting notes content...", mimeType: "text/plain"}]}
+```
-def ensure_uv_installed() -> None:
- """Ensure uv is installed at minimum version"""
- if check_uv_version(MIN_UV_VERSION) is None:
- click.echo(
- f"❌ Error: uv >= {MIN_UV_VERSION} is required but not installed.", err=True
+## Prompts: `list_prompts` and `get_prompt`
+
+The template registers a single prompt `summarize-notes` that generates a message asking for a summary of all current notes.
+
+```python
+@server.list_prompts()
+async def handle_list_prompts() -> list[types.Prompt]:
+ return [
+ types.Prompt(
+ name="summarize-notes",
+ description="Creates a summary of all notes",
+ arguments=[
+ types.PromptArgument(
+ name="style",
+ description="Style of the summary (brief/detailed)",
+ required=False,
+ )
+ ],
)
- click.echo("To install, visit: https://github.com/astral-sh/uv", err=True)
- sys.exit(1)
-
+ ]
+
+@server.get_prompt()
+async def handle_get_prompt(name: str, arguments: dict[str, str] | None) -> types.GetPromptResult:
+ if name != "summarize-notes":
+ raise ValueError(f"Unknown prompt: {name}")
+ style = (arguments or {}).get("style", "brief")
+ detail_prompt = " Give extensive details." if style == "detailed" else ""
+ return types.GetPromptResult(
+ description="Summarize the current notes",
+ messages=[
+ types.PromptMessage(
+ role="user",
+ content=types.TextContent(
+ type="text",
+ text=f"Here are the current notes to summarize:{detail_prompt}\n\n"
+ + "\n".join(f"- {name}: {content}" for name, content in notes.items()),
+ ),
+ )
+ ],
+ )
+```
-def get_claude_config_path() -> Path | None:
- """Get the Claude config directory based on platform"""
- if sys.platform == "win32":
- path = Path(Path.home(), "AppData", "Roaming", "Claude")
- elif sys.platform == "darwin":
- path = Path(Path.home(), "Library", "Application Support", "Claude")
- else:
- return None
+Prompt design patterns demonstrated:
+- **Optional arguments with defaults**: `style` defaults to `"brief"` if not provided
+- **Dynamic content injection**: the prompt body includes live note content at render time
+- **Single `user` message**: the simplest prompt shape — one message asking the LLM to act
+
+## Tools: `list_tools` and `call_tool`
+
+The template exposes one tool, `add-note`, which creates or replaces a note entry and notifies clients of resource list changes.
+
+```python
+@server.list_tools()
+async def handle_list_tools() -> list[types.Tool]:
+ return [
+ types.Tool(
+ name="add-note",
+ description="Add a new note",
+ inputSchema={
+ "type": "object",
+ "properties": {
+ "name": {"type": "string"},
+ "content": {"type": "string"},
+ },
+ "required": ["name", "content"],
+ },
+ )
+ ]
+
+@server.call_tool()
+async def handle_call_tool(name: str, arguments: dict | None) -> list[...]:
+ if name != "add-note":
+ raise ValueError(f"Unknown tool: {name}")
+ note_name = arguments.get("name")
+ content = arguments.get("content")
+ notes[note_name] = content
+ # Notify clients that resource list changed
+ await server.request_context.session.send_resource_list_changed()
+ return [types.TextContent(type="text", text=f"Added note '{note_name}' with content: {content}")]
+```
- if path.exists():
- return path
- return None
+Tool design patterns demonstrated:
+- **JSON Schema input validation**: `required` array and typed `properties`
+- **State mutation with notification**: after modifying `notes`, the server sends `notifications/resources/list_changed` so connected clients can refresh
+- **Structured response**: returns a `TextContent` list, not a raw string
+```mermaid
+sequenceDiagram
+ participant LLM
+ participant Host
+ participant Server
+
+ LLM->>Host: call add-note {name: "meeting", content: "..."}
+ Host->>Server: tools/call {name: "add-note", arguments: {...}}
+ Server->>Server: notes["meeting"] = "..."
+ Server-->>Host: notifications/resources/list_changed
+ Server-->>Host: tools/call result: TextContent
+ Host-->>LLM: "Added note 'meeting' with content: ..."
+```
-def has_claude_app() -> bool:
- return get_claude_config_path() is not None
+## The `main()` Async Entry Point
+
+```python
+async def main():
+ async with mcp.server.stdio.stdio_server() as (read_stream, write_stream):
+ await server.run(
+ read_stream,
+ write_stream,
+ InitializationOptions(
+ server_name="{{server_name}}",
+ server_version="{{server_version}}",
+ capabilities=server.get_capabilities(
+ notification_options=NotificationOptions(),
+ experimental_capabilities={},
+ ),
+ ),
+ )
+```
+This wires the server to stdin/stdout via the `stdio_server()` context manager, which handles the byte-level framing. `InitializationOptions` carries the server's name, version, and capability advertisement to the client during the `initialize` handshake.
-def update_claude_config(project_name: str, project_path: Path) -> bool:
- """Add the project to the Claude config if possible"""
-```
+## Source References
-This function is important because it defines how Create Python Server Tutorial: Scaffold and Ship MCP Servers with uvx implements the patterns covered in this chapter.
+- [Template Server Implementation](https://github.com/modelcontextprotocol/create-python-server/blob/main/src/create_mcp_server/template/server.py.jinja2)
+- [Template README](https://github.com/modelcontextprotocol/create-python-server/blob/main/src/create_mcp_server/template/README.md.jinja2)
+## Summary
-## How These Components Connect
+The generated `server.py` is a complete, working demonstration of all three MCP primitives using the low-level `Server` API. Resources use a custom `note://` URI scheme and reflect live state. The `summarize-notes` prompt injects current note content at render time. The `add-note` tool mutates state and sends `resource_list_changed` notifications. Every handler is an extension point — replace the `notes` dict and the business logic inside each handler to build a domain-specific server.
-```mermaid
-flowchart TD
- A[ensure_uv_installed]
-```
+Next: [Chapter 4: Runtime, Dependencies, and uv Packaging](04-runtime-dependencies-and-uv-packaging.md)
diff --git a/tutorials/create-python-server-tutorial/04-runtime-dependencies-and-uv-packaging.md b/tutorials/create-python-server-tutorial/04-runtime-dependencies-and-uv-packaging.md
index 8129f10d..2538d501 100644
--- a/tutorials/create-python-server-tutorial/04-runtime-dependencies-and-uv-packaging.md
+++ b/tutorials/create-python-server-tutorial/04-runtime-dependencies-and-uv-packaging.md
@@ -5,85 +5,183 @@ nav_order: 4
parent: Create Python Server Tutorial
---
-
# Chapter 4: Runtime, Dependencies, and uv Packaging
-Welcome to **Chapter 4: Runtime, Dependencies, and uv Packaging**. In this part of **Create Python Server Tutorial: Scaffold and Ship MCP Servers with uvx**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
+This chapter covers the `uv`-based dependency and packaging model for generated MCP servers: how dependencies are declared, how lockfiles maintain reproducibility, and how to build and publish a server as a standalone Python package.
+## Learning Goals
-This chapter focuses on dependency/runtime controls for reliable local and publish workflows.
+- Manage dependencies with `uv` conventions in generated projects
+- Run generated servers in development and published modes
+- Keep lockfiles and build artifacts reproducible across environments
+- Avoid environment drift across contributors and CI systems
-## Learning Goals
+## The uv Packaging Model
-- manage dependencies with `uv` conventions
-- run generated servers in development and publish modes
-- keep lockfiles and build artifacts reproducible
-- avoid environment drift across contributors
+Generated MCP servers use `uv` as the complete Python toolchain — environment manager, package manager, and build tool. This eliminates the `pip + virtualenv + poetry + twine` fragmentation common in Python projects.
-## Packaging Flow
+```mermaid
+graph LR
+ UV[uv toolchain]
+ UV --> SYNC[uv sync\nCreate .venv, install deps from lock]
+ UV --> RUN[uv run server-name\nRun in managed .venv]
+ UV --> BUILD[uv build\nCreate wheel + sdist in dist/]
+ UV --> PUBLISH[uv publish\nUpload to PyPI or private registry]
+ UV --> ADD[uv add package\nAdd dep + update lock]
+```
-1. sync dependencies (`uv sync`)
-2. build artifacts (`uv build`)
-3. publish package (`uv publish`) with secure credential handling
+## `pyproject.toml` Structure
-## Source References
+The generated `pyproject.toml` uses the `hatchling` build backend (the default for `uv init`):
-- [Create Python Server README](https://github.com/modelcontextprotocol/create-python-server/blob/main/README.md)
-- [Template README - Building and Publishing](https://github.com/modelcontextprotocol/create-python-server/blob/main/src/create_mcp_server/template/README.md.jinja2#building-and-publishing)
+```toml
+[project]
+name = "my-notes-server"
+version = "0.1.0"
+description = "A simple MCP server for managing notes"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = ["mcp>=1.0.0"]
-## Summary
+[project.scripts]
+my-notes-server = "my_notes_server:main"
-You now have a consistent runtime and packaging model for generated MCP servers.
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+```
-Next: [Chapter 5: Local Integration: Claude Desktop and Inspector](05-local-integration-claude-desktop-and-inspector.md)
+Key constraints:
+- `requires-python = ">=3.10"` — the `mcp` SDK requires Python 3.10+ for union type syntax (`X | Y`)
+- `mcp>=1.0.0` — unpinned upper bound; updates get new SDK versions on `uv sync`
+- `[project.scripts]` entry enables `uvx my-notes-server` without explicit path management
-## Source Code Walkthrough
+## Development Workflow
-### `src/create_mcp_server/__init__.py`
+```mermaid
+flowchart TD
+ EDIT[Edit server.py]
+ EDIT --> SYNC[uv sync\ninstall or refresh deps]
+ SYNC --> TEST[Test with Inspector:\nnpx @modelcontextprotocol/inspector\nuv --directory . run my-notes-server]
+ TEST --> VERIFY[Verify tool calls\nresource list\nprompt rendering]
+ VERIFY --> EDIT
+```
-The `get_claude_config_path` function in [`src/create_mcp_server/__init__.py`](https://github.com/modelcontextprotocol/create-python-server/blob/HEAD/src/create_mcp_server/__init__.py) handles a key part of this chapter's functionality:
+```bash
+# Full development cycle
-```py
+# 1. Install / refresh dependencies
+uv sync --dev --all-extras
+# 2. Run server directly (stdio — useful for pipes)
+uv run my-notes-server
-def get_claude_config_path() -> Path | None:
- """Get the Claude config directory based on platform"""
- if sys.platform == "win32":
- path = Path(Path.home(), "AppData", "Roaming", "Claude")
- elif sys.platform == "darwin":
- path = Path(Path.home(), "Library", "Application Support", "Claude")
- else:
- return None
+# 3. Run in Inspector for interactive testing
+npx @modelcontextprotocol/inspector uv --directory /path/to/my-notes-server run my-notes-server
- if path.exists():
- return path
- return None
+# 4. Add a new dependency
+uv add requests
+uv add --dev pytest
+```
+## Lockfile Discipline
-def has_claude_app() -> bool:
- return get_claude_config_path() is not None
+`uv.lock` pins every transitive dependency to an exact version and hash. This is committed to source control to ensure every environment gets identical packages:
+```bash
+# After anyone adds/removes a dependency, commit the updated lock file
+git add uv.lock pyproject.toml
+git commit -m "deps: add requests for HTTP resource fetching"
+```
-def update_claude_config(project_name: str, project_path: Path) -> bool:
- """Add the project to the Claude config if possible"""
- config_dir = get_claude_config_path()
- if not config_dir:
- return False
+If a contributor runs `uv sync` without updating the lock, they get the locked versions — not the latest. To upgrade dependencies:
- config_file = config_dir / "claude_desktop_config.json"
- if not config_file.exists():
- return False
+```bash
+# Upgrade all dependencies within pyproject.toml constraints
+uv lock --upgrade
- try:
- config = json.loads(config_file.read_text())
+# Upgrade a specific package
+uv lock --upgrade-package mcp
```
-This function is important because it defines how Create Python Server Tutorial: Scaffold and Ship MCP Servers with uvx implements the patterns covered in this chapter.
+## Building for Distribution
+```bash
+# Build wheel and source distribution
+uv build
+# Output: dist/my_notes_server-0.1.0-py3-none-any.whl
+# dist/my_notes_server-0.1.0.tar.gz
+```
-## How These Components Connect
+The generated wheel includes only the `src/` package — no test files, no development artifacts. `hatchling` reads the `[build-system]` config to determine what to include.
```mermaid
-flowchart TD
- A[get_claude_config_path]
+flowchart LR
+ SRC[src/my_notes_server/\n__init__.py · server.py]
+ TOML[pyproject.toml]
+ SRC --> BUILD[uv build]
+ TOML --> BUILD
+ BUILD --> WHEEL[dist/my_notes_server-0.1.0.whl]
+ BUILD --> SDIST[dist/my_notes_server-0.1.0.tar.gz]
+ WHEEL --> INSTALL[pip install / uvx install]
+```
+
+## Publishing to PyPI
+
+```bash
+# Configure credentials (one-time)
+export UV_PUBLISH_TOKEN=pypi-...
+
+# Publish
+uv publish
+
+# Or publish with explicit credential flags
+uv publish --token $PYPI_TOKEN
```
+
+After publishing, any user can run your server with:
+```bash
+uvx my-notes-server
+```
+
+No Python installation steps required — `uvx` handles environment creation transparently.
+
+## Version Management
+
+Update the version in `pyproject.toml` before each release:
+
+```toml
+[project]
+version = "0.2.0"
+```
+
+Semantic versioning conventions for MCP servers:
+- **Patch** (0.1.x): bug fixes, no new tools/resources
+- **Minor** (0.x.0): new tools, resources, or prompts added
+- **Major** (x.0.0): breaking changes to tool signatures or removed primitives
+
+## Python Version Compatibility
+
+| Python Version | Status | Notes |
+|:--------------|:-------|:------|
+| 3.9 | Not supported | `mcp` requires union syntax (`X \| Y`) which needs 3.10+ |
+| 3.10 | Minimum | Full support |
+| 3.11 | Recommended | Better performance for async |
+| 3.12+ | Supported | No known issues |
+
+```bash
+# Pin Python version for the project (creates .python-version file)
+uv python pin 3.12
+```
+
+## Source References
+
+- [Create Python Server README](https://github.com/modelcontextprotocol/create-python-server/blob/main/README.md)
+- [Template README — Building and Publishing](https://github.com/modelcontextprotocol/create-python-server/blob/main/src/create_mcp_server/template/README.md.jinja2)
+- [pyproject.toml spec (PEP 517)](https://peps.python.org/pep-0517/)
+
+## Summary
+
+Generated MCP servers are standard Python packages managed entirely by `uv`. The `uv sync → uv run → uv build → uv publish` pipeline handles the full lifecycle without touching `pip` or `virtualenv` directly. Commit `uv.lock` to ensure reproducibility. Use semantic versioning to signal breaking changes in tool signatures to downstream clients.
+
+Next: [Chapter 5: Local Integration: Claude Desktop and Inspector](05-local-integration-claude-desktop-and-inspector.md)
diff --git a/tutorials/create-python-server-tutorial/05-local-integration-claude-desktop-and-inspector.md b/tutorials/create-python-server-tutorial/05-local-integration-claude-desktop-and-inspector.md
index 30f09baf..a1e61d9f 100644
--- a/tutorials/create-python-server-tutorial/05-local-integration-claude-desktop-and-inspector.md
+++ b/tutorials/create-python-server-tutorial/05-local-integration-claude-desktop-and-inspector.md
@@ -5,86 +5,186 @@ nav_order: 5
parent: Create Python Server Tutorial
---
-
# Chapter 5: Local Integration: Claude Desktop and Inspector
-Welcome to **Chapter 5: Local Integration: Claude Desktop and Inspector**. In this part of **Create Python Server Tutorial: Scaffold and Ship MCP Servers with uvx**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
+This chapter explains how to wire a generated MCP server into Claude Desktop and how to use the MCP Inspector for iterative development validation. The generator can perform Claude Desktop registration automatically, but understanding the manual process is essential for troubleshooting.
+## Learning Goals
-This chapter explains local integration and debugging workflows for generated servers.
+- Configure a generated server for Claude Desktop in both development and published modes
+- Use the MCP Inspector for stdio debugging and server validation
+- Test development versus published server command paths
+- Reduce time-to-diagnosis for integration failures
-## Learning Goals
+## Automatic Claude Desktop Registration
-- configure generated server commands for Claude Desktop
-- use Inspector workflows for stdio debugging and validation
-- test development vs published server command paths
-- reduce time-to-diagnosis for integration issues
+When the generator detects Claude Desktop is installed (by checking the config directory path), it automatically adds the server to `claude_desktop_config.json`:
-## Integration Modes
+```python
+# From src/create_mcp_server/__init__.py
+def get_claude_config_path() -> Path | None:
+ if sys.platform == "win32":
+ path = Path(Path.home(), "AppData", "Roaming", "Claude")
+ elif sys.platform == "darwin":
+ path = Path(Path.home(), "Library", "Application Support", "Claude")
+ else:
+ return None
+ return path if path.exists() else None
-| Mode | Command Pattern |
-|:-----|:----------------|
-| development | `uv --directory run ` |
-| published | `uvx ` |
+def update_claude_config(project_name: str, project_path: Path) -> bool:
+ config_dir = get_claude_config_path()
+ if not config_dir:
+ return False
+ config_file = config_dir / "claude_desktop_config.json"
+ if not config_file.exists():
+ return False
+ config = json.loads(config_file.read_text())
+ config.setdefault("mcpServers", {})[project_name] = {
+ "command": "uv",
+ "args": ["--directory", str(project_path), "run", project_name],
+ }
+ config_file.write_text(json.dumps(config, indent=2))
+ return True
+```
-## Source References
+The generator writes the **development mode** config (using `uv --directory`), not the published mode config.
-- [Template README - Claude Desktop Configuration](https://github.com/modelcontextprotocol/create-python-server/blob/main/src/create_mcp_server/template/README.md.jinja2#claude-desktop)
-- [Template README - Debugging](https://github.com/modelcontextprotocol/create-python-server/blob/main/src/create_mcp_server/template/README.md.jinja2#debugging)
+## Claude Desktop Configuration
-## Summary
+```mermaid
+graph TD
+ CONFIG[claude_desktop_config.json]
+ CONFIG --> DEV[Development mode:\nuv --directory path run server-name]
+ CONFIG --> PUB[Published mode:\nuvx server-name]
+
+ DEV -->|Pros| D1[Edit server.py and restart\nNo rebuild step needed]
+ DEV -->|Cons| D2[Requires uv installed\nPath must remain valid]
+ PUB -->|Pros| P1[Self-contained\nNo local path dependency]
+ PUB -->|Cons| P2[Must publish new version\nto test changes]
+```
-You now have a working local integration and debugging strategy for scaffolded servers.
+### Development Mode Config
+
+```json
+{
+ "mcpServers": {
+ "my-notes-server": {
+ "command": "uv",
+ "args": ["--directory", "/Users/you/projects/my-notes-server", "run", "my-notes-server"]
+ }
+ }
+}
+```
-Next: [Chapter 6: Customization and Extension Patterns](06-customization-and-extension-patterns.md)
+Use this during active development. Claude Desktop spawns `uv run my-notes-server` in the project directory — changes to `server.py` take effect on the next Claude Desktop restart.
-## Source Code Walkthrough
+### Published Mode Config
-### `src/create_mcp_server/__init__.py`
+```json
+{
+ "mcpServers": {
+ "my-notes-server": {
+ "command": "uvx",
+ "args": ["my-notes-server"]
+ }
+ }
+}
+```
-The `has_claude_app` function in [`src/create_mcp_server/__init__.py`](https://github.com/modelcontextprotocol/create-python-server/blob/HEAD/src/create_mcp_server/__init__.py) handles a key part of this chapter's functionality:
+Use this for stable deployed servers after publishing to PyPI. No local project directory required.
-```py
+### Config File Locations
+| Platform | Path |
+|:---------|:-----|
+| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
+| Linux | Not officially supported by Claude Desktop |
-def has_claude_app() -> bool:
- return get_claude_config_path() is not None
+## MCP Inspector Integration
+The Inspector is the primary development tool for iterating on server behavior without restarting Claude Desktop.
-def update_claude_config(project_name: str, project_path: Path) -> bool:
- """Add the project to the Claude config if possible"""
- config_dir = get_claude_config_path()
- if not config_dir:
- return False
+```mermaid
+flowchart LR
+ DEV[Developer edits server.py]
+ DEV --> INSPECTOR[npx @modelcontextprotocol/inspector\nuv --directory . run my-notes-server]
+ INSPECTOR --> UI[Browser UI: localhost:5173]
+ UI --> TOOLS[Tools tab:\ncall add-note]
+ UI --> RES[Resources tab:\nlist notes]
+ UI --> PROMPTS[Prompts tab:\ntest summarize-notes]
+ UI --> MSGS[Messages tab:\nraw JSON-RPC trace]
+```
- config_file = config_dir / "claude_desktop_config.json"
- if not config_file.exists():
- return False
+```bash
+# Run with Inspector (development path)
+npx @modelcontextprotocol/inspector uv --directory /path/to/my-notes-server run my-notes-server
+
+# Run with Inspector (published path, after uvx install)
+npx @modelcontextprotocol/inspector uvx my-notes-server
+```
+
+### Inspector Verification Checklist
+
+After launching the Inspector, verify:
+
+- [ ] **Tools tab**: `add-note` appears with `name` and `content` arguments
+- [ ] **Resources tab**: empty list initially; after calling `add-note`, notes appear as `note://internal/` URIs
+- [ ] **Prompts tab**: `summarize-notes` appears with optional `style` argument
+- [ ] **Messages tab**: `initialize` request shows correct server name and capabilities
+
+### Testing the Full Primitive Lifecycle
- try:
- config = json.loads(config_file.read_text())
- if "mcpServers" not in config:
- config["mcpServers"] = {}
-
- if project_name in config["mcpServers"]:
- click.echo(
- f"⚠️ Warning: {project_name} already exists in Claude.app configuration",
- err=True,
- )
- click.echo(f"Settings file location: {config_file}", err=True)
- return False
-
- config["mcpServers"][project_name] = {
- "command": "uv",
- "args": ["--directory", str(project_path), "run", project_name],
```
+1. Open Tools tab → Call "add-note" with name="test" content="hello world"
+ Expected: TextContent response "Added note 'test' with content: hello world"
-This function is important because it defines how Create Python Server Tutorial: Scaffold and Ship MCP Servers with uvx implements the patterns covered in this chapter.
+2. Open Resources tab → Click refresh (or observe automatic update notification)
+ Expected: "note://internal/test" appears in the list
+3. Click "note://internal/test" to read it
+ Expected: "hello world" content
+
+4. Open Prompts tab → Call "summarize-notes" with style="brief"
+ Expected: UserMessage containing "- test: hello world"
+
+5. Open Messages tab → Find the tools/call message pair
+ Expected: Valid JSON-RPC request and response with correct IDs
+```
-## How These Components Connect
+## Troubleshooting Claude Desktop Integration
```mermaid
flowchart TD
- A[has_claude_app]
+ ISSUE[Server not appearing in Claude Desktop]
+ ISSUE --> CHECK1[Check config JSON syntax\njq . ~/Library/.../claude_desktop_config.json]
+ CHECK1 -->|Invalid JSON| FIX1[Fix syntax error\ncommon: trailing comma]
+ CHECK1 -->|Valid| CHECK2[Check server process\nActivity Monitor / Task Manager]
+ CHECK2 -->|Process not running| CHECK3[Check MCP log file:\nmcp-server-my-notes-server.log]
+ CHECK3 --> FIX2[Read error in log:\npath wrong, uv not found, import error]
+ CHECK2 -->|Process running| CHECK4[Check tools list in conversation\nclick hammer icon]
```
+
+Log file locations:
+- macOS: `~/Library/Logs/Claude/mcp-server-.log`
+- Windows: `%APPDATA%\Claude\logs\mcp-server-.log`
+
+Common failure patterns:
+
+| Symptom | Cause | Fix |
+|:--------|:------|:----|
+| Server doesn't appear | Config JSON syntax error | Validate with `jq` |
+| "uv not found" in log | uv not in PATH for GUI app | Use full path to uv in config |
+| Import error in log | Missing `uv sync` | Run `uv sync` in project dir |
+| Tools appear but calls fail | Unhandled exception in handler | Add try/except to `call_tool` |
+
+## Source References
+
+- [Template README — Claude Desktop Configuration](https://github.com/modelcontextprotocol/create-python-server/blob/main/src/create_mcp_server/template/README.md.jinja2)
+- [Generator — Claude Config Update](https://github.com/modelcontextprotocol/create-python-server/blob/main/src/create_mcp_server/__init__.py)
+
+## Summary
+
+The generator auto-registers your server with Claude Desktop in development mode when possible. For manual configuration, choose the `uv --directory` pattern during development and `uvx` after publishing. Use the MCP Inspector as the primary iteration tool — it surfaces tool, resource, and prompt behavior interactively without restarting any host application. When Claude Desktop integration fails, check the config JSON syntax first, then the MCP log file.
+
+Next: [Chapter 6: Customization and Extension Patterns](06-customization-and-extension-patterns.md)
diff --git a/tutorials/create-python-server-tutorial/06-customization-and-extension-patterns.md b/tutorials/create-python-server-tutorial/06-customization-and-extension-patterns.md
index 83923a43..680aca1d 100644
--- a/tutorials/create-python-server-tutorial/06-customization-and-extension-patterns.md
+++ b/tutorials/create-python-server-tutorial/06-customization-and-extension-patterns.md
@@ -5,86 +5,213 @@ nav_order: 6
parent: Create Python Server Tutorial
---
-
# Chapter 6: Customization and Extension Patterns
-Welcome to **Chapter 6: Customization and Extension Patterns**. In this part of **Create Python Server Tutorial: Scaffold and Ship MCP Servers with uvx**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
-
-
-This chapter covers practical ways to evolve generated scaffolds into domain-specific services.
+This chapter covers practical strategies for extending the generated scaffold into a production-grade, domain-specific MCP server — replacing the in-memory notes store, adding new tools and resources, and maintaining protocol contracts as complexity grows.
## Learning Goals
-- extend default primitive handlers with domain logic safely
-- preserve protocol contracts while changing storage or workflows
-- keep template-origin code maintainable over time
-- avoid coupling business logic to scaffold assumptions
+- Extend default primitive handlers with domain logic without breaking protocol contracts
+- Preserve MCP semantics (tool error handling, resource URI conventions) during extension
+- Keep handler boundaries thin and protocol-focused
+- Avoid coupling business logic to scaffold assumptions
-## Extension Strategy
+## Extension Strategy Overview
-1. isolate domain logic in dedicated modules/services
-2. keep handler boundaries thin and protocol-focused
-3. add schema validation and error mapping early
-4. maintain behavior tests as templates diverge
-
-## Source References
+```mermaid
+flowchart TD
+ SCAFFOLD[Generated scaffold\nIn-memory notes dict]
+ SCAFFOLD --> STEP1[1. Replace data layer\nnotes dict → database/API client]
+ STEP1 --> STEP2[2. Expand primitives\nadd more tools, resources, prompts]
+ STEP2 --> STEP3[3. Extract domain logic\nserver.py imports domain modules]
+ STEP3 --> STEP4[4. Add validation and error handling\ntype checks, input sanitization]
+ STEP4 --> PROD[Production server]
+```
-- [Template Server Implementation](https://github.com/modelcontextprotocol/create-python-server/blob/main/src/create_mcp_server/template/server.py.jinja2)
-- [Create Python Server README](https://github.com/modelcontextprotocol/create-python-server/blob/main/README.md)
+## Step 1: Replace the Data Layer
-## Summary
+The `notes: dict[str, str]` state variable is the single seam to replace. Extract it into a repository abstraction:
-You now have an extension model for safely evolving generated MCP servers.
+```python
+# Before (template)
+notes: dict[str, str] = {}
-Next: [Chapter 7: Quality, Security, and Contribution Workflows](07-quality-security-and-contribution-workflows.md)
+@server.list_resources()
+async def handle_list_resources() -> list[types.Resource]:
+ return [types.Resource(uri=AnyUrl(f"note://internal/{name}"), ...) for name in notes]
+```
-## Source Code Walkthrough
+```python
+# After (database-backed)
+from myserver.db import NoteRepository
+
+repo = NoteRepository(connection_string=os.environ["DATABASE_URL"])
+
+@server.list_resources()
+async def handle_list_resources() -> list[types.Resource]:
+ notes = await repo.list_all()
+ return [
+ types.Resource(
+ uri=AnyUrl(f"note://internal/{note.id}"),
+ name=f"Note: {note.title}",
+ description=note.summary,
+ mimeType="text/plain",
+ )
+ for note in notes
+ ]
+```
-### `src/create_mcp_server/__init__.py`
+Keep the URI scheme consistent (`note://internal/`) so clients that have cached resource URIs continue to work.
+
+## Step 2: Add New Tools
+
+Extend `handle_list_tools` and `handle_call_tool` to support additional operations. Maintain the dispatch pattern:
+
+```python
+TOOLS = {
+ "add-note": {
+ "description": "Add a new note",
+ "inputSchema": {
+ "type": "object",
+ "properties": {
+ "name": {"type": "string"},
+ "content": {"type": "string"},
+ },
+ "required": ["name", "content"],
+ },
+ },
+ "delete-note": {
+ "description": "Delete a note by name",
+ "inputSchema": {
+ "type": "object",
+ "properties": {"name": {"type": "string"}},
+ "required": ["name"],
+ },
+ },
+ "search-notes": {
+ "description": "Search notes by keyword",
+ "inputSchema": {
+ "type": "object",
+ "properties": {
+ "query": {"type": "string"},
+ "limit": {"type": "integer", "default": 10},
+ },
+ "required": ["query"],
+ },
+ },
+}
+
+@server.list_tools()
+async def handle_list_tools() -> list[types.Tool]:
+ return [types.Tool(name=name, **spec) for name, spec in TOOLS.items()]
+
+@server.call_tool()
+async def handle_call_tool(name: str, arguments: dict | None) -> list[types.TextContent]:
+ args = arguments or {}
+ if name == "add-note":
+ return await _add_note(args)
+ elif name == "delete-note":
+ return await _delete_note(args)
+ elif name == "search-notes":
+ return await _search_notes(args)
+ else:
+ raise ValueError(f"Unknown tool: {name}")
+```
-The `update_claude_config` function in [`src/create_mcp_server/__init__.py`](https://github.com/modelcontextprotocol/create-python-server/blob/HEAD/src/create_mcp_server/__init__.py) handles a key part of this chapter's functionality:
+```mermaid
+graph TD
+ DISPATCH[handle_call_tool dispatcher]
+ DISPATCH --> ADD[_add_note\nnotes.add + send_resource_list_changed]
+ DISPATCH --> DEL[_delete_note\nnotes.delete + send_resource_list_changed]
+ DISPATCH --> SEARCH[_search_notes\nreturns matching note list]
+```
-```py
+## Step 3: Error Handling Patterns
+The template raises `ValueError` for unknown tools, which the MCP runtime converts to a protocol error response. For production, use structured error responses for known failure modes:
-def update_claude_config(project_name: str, project_path: Path) -> bool:
- """Add the project to the Claude config if possible"""
- config_dir = get_claude_config_path()
- if not config_dir:
- return False
+```python
+async def _add_note(args: dict) -> list[types.TextContent]:
+ name = args.get("name", "").strip()
+ content = args.get("content", "").strip()
- config_file = config_dir / "claude_desktop_config.json"
- if not config_file.exists():
- return False
+ if not name:
+ return [types.TextContent(type="text", text="Error: note name cannot be empty")]
+ if len(content) > 10_000:
+ return [types.TextContent(type="text", text="Error: note content exceeds 10,000 character limit")]
try:
- config = json.loads(config_file.read_text())
- if "mcpServers" not in config:
- config["mcpServers"] = {}
-
- if project_name in config["mcpServers"]:
- click.echo(
- f"⚠️ Warning: {project_name} already exists in Claude.app configuration",
- err=True,
- )
- click.echo(f"Settings file location: {config_file}", err=True)
- return False
-
- config["mcpServers"][project_name] = {
- "command": "uv",
- "args": ["--directory", str(project_path), "run", project_name],
- }
-
- config_file.write_text(json.dumps(config, indent=2))
- click.echo(f"✅ Added {project_name} to Claude.app configuration")
+ await repo.save(name, content)
+ await server.request_context.session.send_resource_list_changed()
+ return [types.TextContent(type="text", text=f"Added note '{name}'")]
+ except DatabaseError as e:
+ return [types.TextContent(type="text", text=f"Storage error: {e}")]
```
-This function is important because it defines how Create Python Server Tutorial: Scaffold and Ship MCP Servers with uvx implements the patterns covered in this chapter.
+Key rule: **never raise exceptions from `call_tool`** for expected error conditions (validation failures, not-found cases). Return a `TextContent` with an error message so the LLM can communicate the failure to the user. Only raise for truly unexpected programming errors.
+
+## Step 4: Module Structure for Complex Servers
+As `server.py` grows, extract domain logic into sibling modules:
-## How These Components Connect
+```
+src/my_notes_server/
+├── __init__.py # Entry point — do not modify
+├── server.py # Handler registration — keep thin
+├── db.py # NoteRepository + database models
+├── search.py # Full-text search logic
+├── validators.py # Input validation helpers
+└── notifications.py # Resource change notification helpers
+```
```mermaid
-flowchart TD
- A[update_claude_config]
+graph LR
+ SERVER[server.py\nHandler registration + dispatch]
+ SERVER --> DB[db.py\nNoteRepository]
+ SERVER --> SEARCH[search.py\nSearchIndex]
+ SERVER --> VALID[validators.py\nInputValidator]
+ DB --> NOTES_TABLE[notes table]
+ SEARCH --> INDEX[full-text index]
+```
+
+`server.py` should remain a thin dispatch layer. Business logic goes in the domain modules, making them independently testable without the MCP server running.
+
+## Step 5: Environment Configuration
+
+Use environment variables for all deployment-specific configuration:
+
+```python
+import os
+from pathlib import Path
+
+DATABASE_URL = os.environ.get("DATABASE_URL", "sqlite:///notes.db")
+MAX_NOTES = int(os.environ.get("MAX_NOTES", "1000"))
+LOG_LEVEL = os.environ.get("LOG_LEVEL", "WARNING")
+```
+
+Add these to the Claude Desktop config:
+```json
+{
+ "mcpServers": {
+ "my-notes-server": {
+ "command": "uv",
+ "args": ["--directory", "/path/to/server", "run", "my-notes-server"],
+ "env": {
+ "DATABASE_URL": "postgresql://localhost/notes",
+ "LOG_LEVEL": "INFO"
+ }
+ }
+ }
+}
```
+
+## Source References
+
+- [Template Server Implementation](https://github.com/modelcontextprotocol/create-python-server/blob/main/src/create_mcp_server/template/server.py.jinja2)
+- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
+
+## Summary
+
+Extend the scaffold by replacing the `notes` dict with a real data layer, expanding the tool dispatch table, and extracting domain logic into testable modules. Keep `server.py` as a thin registration and dispatch layer. Return structured `TextContent` errors for expected failure conditions rather than raising exceptions. Use environment variables for deployment-specific configuration passed via the Claude Desktop config.
+
+Next: [Chapter 7: Quality, Security, and Contribution Workflows](07-quality-security-and-contribution-workflows.md)
diff --git a/tutorials/create-python-server-tutorial/07-quality-security-and-contribution-workflows.md b/tutorials/create-python-server-tutorial/07-quality-security-and-contribution-workflows.md
index 252ac0f4..c30f13f4 100644
--- a/tutorials/create-python-server-tutorial/07-quality-security-and-contribution-workflows.md
+++ b/tutorials/create-python-server-tutorial/07-quality-security-and-contribution-workflows.md
@@ -5,79 +5,197 @@ nav_order: 7
parent: Create Python Server Tutorial
---
-
# Chapter 7: Quality, Security, and Contribution Workflows
-Welcome to **Chapter 7: Quality, Security, and Contribution Workflows**. In this part of **Create Python Server Tutorial: Scaffold and Ship MCP Servers with uvx**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
+This chapter outlines how to maintain quality and security in scaffold-derived MCP server projects, and how to contribute to the `create-python-server` tool itself (given its archived status).
+## Learning Goals
-This chapter outlines governance controls for scaffold-based MCP server projects.
+- Align contribution practices with repository standards for scaffold-based projects
+- Incorporate security reporting and review practices into generated server development
+- Define quality gates for generated and customized code
+- Standardize issue triage and pull request expectations
-## Learning Goals
+## Quality Gates for Generated Servers
-- align contribution practices with repository standards
-- incorporate security reporting and review practices
-- define quality gates for generated and customized code
-- standardize issue triage and pull request expectations
+Because generated servers start from a template, quality gates need to cover both the original scaffold and all customizations layered on top.
-## Source References
+```mermaid
+graph LR
+ QUALITY[Quality Pipeline]
+ QUALITY --> LINT[Ruff lint + format\nuv run ruff check .\nuv run ruff format --check .]
+ QUALITY --> TYPE[Type checking\nuv run mypy src/]
+ QUALITY --> TEST[Unit tests\nuv run pytest]
+ QUALITY --> INTEG[Integration tests\nMCP Inspector smoke tests]
+ QUALITY --> SEC[Security scan\nuv run bandit -r src/]
+```
-- [Contributing Guide](https://github.com/modelcontextprotocol/create-python-server/blob/main/CONTRIBUTING.md)
-- [Security Policy](https://github.com/modelcontextprotocol/create-python-server/blob/main/SECURITY.md)
+### Setting Up Testing
-## Summary
+The generator does not scaffold test files — add them immediately after generation:
-You now have a governance model for secure and maintainable scaffold-derived projects.
+```bash
+# Add test dependencies
+uv add --dev pytest pytest-asyncio
-Next: [Chapter 8: Archived Status, Migration, and Long-Term Operations](08-archived-status-migration-and-long-term-operations.md)
+# Create test structure
+mkdir tests
+touch tests/__init__.py
+touch tests/test_server.py
+```
-## Source Code Walkthrough
+```python
+# tests/test_server.py
+import pytest
+import asyncio
+from my_notes_server.server import handle_list_tools, handle_call_tool, notes
+
+@pytest.mark.asyncio
+async def test_list_tools_returns_add_note():
+ tools = await handle_list_tools()
+ assert any(t.name == "add-note" for t in tools)
+
+@pytest.mark.asyncio
+async def test_add_note_stores_and_returns():
+ notes.clear()
+ result = await handle_call_tool("add-note", {"name": "test", "content": "hello"})
+ assert notes["test"] == "hello"
+ assert "Added note 'test'" in result[0].text
+
+@pytest.mark.asyncio
+async def test_unknown_tool_raises():
+ with pytest.raises(ValueError, match="Unknown tool"):
+ await handle_call_tool("nonexistent-tool", {})
+```
-### `src/create_mcp_server/__init__.py`
+Note: testing handlers directly (without the MCP transport layer) requires carefully managing the global `notes` state between tests. Use `notes.clear()` in test setup or inject the state via a fixture.
+
+### CI Configuration
+
+The `create-python-server` repo itself uses GitHub Actions workflows for CI. For generated servers, a minimal CI config:
+
+```yaml
+# .github/workflows/ci.yml
+name: CI
+on: [push, pull_request]
+jobs:
+ test:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ - uses: astral-sh/setup-uv@v3
+ - run: uv sync --dev --all-extras
+ - run: uv run ruff check .
+ - run: uv run pytest
+```
-The `get_package_directory` function in [`src/create_mcp_server/__init__.py`](https://github.com/modelcontextprotocol/create-python-server/blob/HEAD/src/create_mcp_server/__init__.py) handles a key part of this chapter's functionality:
+## Security Practices
-```py
+### Input Validation
+The template does minimal validation (`if not arguments: raise ValueError`). Production servers need explicit validation for all tool inputs:
-def get_package_directory(path: Path) -> Path:
- """Find the package directory under src/"""
- src_dir = next((path / "src").glob("*/__init__.py"), None)
- if src_dir is None:
- click.echo("❌ Error: Could not find __init__.py in src directory", err=True)
- sys.exit(1)
- return src_dir.parent
+```python
+from typing import Any
+def validate_note_name(name: Any) -> str:
+ if not isinstance(name, str):
+ raise TypeError("name must be a string")
+ name = name.strip()
+ if not name:
+ raise ValueError("name cannot be empty")
+ if len(name) > 255:
+ raise ValueError("name exceeds 255 character limit")
+ # Prevent path traversal in URI construction
+ if "/" in name or ".." in name:
+ raise ValueError("name contains invalid characters")
+ return name
+```
-def copy_template(
- path: Path, name: str, description: str, version: str = "0.1.0"
-) -> None:
- """Copy template files into src/"""
- template_dir = Path(__file__).parent / "template"
+### Tool Side-Effect Disclosure
- target_dir = get_package_directory(path)
+Every tool that modifies state, makes network calls, or reads sensitive data should document this in its `description` field — the LLM reads these descriptions to decide when to invoke tools:
- from jinja2 import Environment, FileSystemLoader
+```python
+types.Tool(
+ name="delete-all-notes",
+ description="Permanently deletes ALL notes. This action cannot be undone.",
+ ...
+)
+```
- env = Environment(loader=FileSystemLoader(str(template_dir)))
+Clear side-effect descriptions allow LLM hosts with confirmation prompts to surface the right warnings to users.
- files = [
- ("__init__.py.jinja2", "__init__.py", target_dir),
- ("server.py.jinja2", "server.py", target_dir),
- ("README.md.jinja2", "README.md", path),
- ]
+### Secret Management
- pyproject = PyProject(path / "pyproject.toml")
- bin_name = pyproject.first_binary
+Never hardcode API keys or credentials in `server.py`. Use environment variables exclusively:
+```python
+import os
+
+API_KEY = os.environ.get("MY_SERVICE_API_KEY")
+if not API_KEY:
+ raise RuntimeError("MY_SERVICE_API_KEY environment variable is required")
```
-This function is important because it defines how Create Python Server Tutorial: Scaffold and Ship MCP Servers with uvx implements the patterns covered in this chapter.
+Log startup failures clearly so Claude Desktop's MCP log captures configuration errors.
+
+## Security Reporting
+The `create-python-server` repository includes a `SECURITY.md` that routes vulnerability reports through GitHub's private security advisory feature. For servers you build on the scaffold:
-## How These Components Connect
+1. Create your own `SECURITY.md` with your reporting contact
+2. Enable GitHub private security advisories in your repo settings
+3. Do not disclose MCP server vulnerabilities in public issues
```mermaid
flowchart TD
- A[get_package_directory]
+ VULN[Vulnerability discovered in generated server]
+ VULN --> SCOPE{Scope of vulnerability?}
+ SCOPE --> TEMPLATE[Template/scaffold issue]
+ SCOPE --> CUSTOM[Custom code issue]
+ SCOPE --> DEPENDENCY[Dependency issue]
+
+ TEMPLATE --> UPSTREAM[Report to modelcontextprotocol/create-python-server\nvia GitHub security advisories\nNote: repo is archived]
+ CUSTOM --> OWN[Report to your repo's\nsecurity contact]
+ DEPENDENCY --> DEP[Report to dependency maintainer\nupdate uv.lock immediately]
```
+
+## Contributing to `create-python-server`
+
+The repository is **archived** and does not accept new feature contributions. However:
+
+- **Critical security vulnerabilities**: still reported via GitHub security advisories
+- **Documentation corrections**: may be accepted as PRs at maintainer discretion
+- **Forks**: teams who depend on the scaffold and need changes should fork and maintain internally
+
+For the upstream `mcp` Python SDK (not archived), contributions follow the standard GitHub PR workflow in `modelcontextprotocol/python-sdk`.
+
+## Code Style Conventions
+
+Follow the conventions established in the source repo:
+
+```bash
+# Formatting (ruff is the recommended formatter)
+uv run ruff format .
+
+# Linting
+uv run ruff check .
+
+# Type annotations on all handler functions
+@server.call_tool()
+async def handle_call_tool(name: str, arguments: dict | None) -> list[types.TextContent]:
+ ...
+```
+
+## Source References
+
+- [Contributing Guide](https://github.com/modelcontextprotocol/create-python-server/blob/main/CONTRIBUTING.md)
+- [Security Policy](https://github.com/modelcontextprotocol/create-python-server/blob/main/SECURITY.md)
+- [GitHub Actions Workflows](https://github.com/modelcontextprotocol/create-python-server/tree/main/.github/workflows)
+
+## Summary
+
+Quality for scaffold-derived servers requires adding tests (the template ships none), setting up CI, and adding explicit input validation. Security practice centers on input validation, clear side-effect documentation in tool descriptions, and environment-variable-only secret management. The scaffold repo is archived so bug fixes and new features go to your internal fork; report security vulnerabilities via GitHub's private advisory feature regardless.
+
+Next: [Chapter 8: Archived Status, Migration, and Long-Term Operations](08-archived-status-migration-and-long-term-operations.md)
diff --git a/tutorials/create-python-server-tutorial/08-archived-status-migration-and-long-term-operations.md b/tutorials/create-python-server-tutorial/08-archived-status-migration-and-long-term-operations.md
index 18040508..a13f2540 100644
--- a/tutorials/create-python-server-tutorial/08-archived-status-migration-and-long-term-operations.md
+++ b/tutorials/create-python-server-tutorial/08-archived-status-migration-and-long-term-operations.md
@@ -5,89 +5,155 @@ nav_order: 8
parent: Create Python Server Tutorial
---
-
# Chapter 8: Archived Status, Migration, and Long-Term Operations
-Welcome to **Chapter 8: Archived Status, Migration, and Long-Term Operations**. In this part of **Create Python Server Tutorial: Scaffold and Ship MCP Servers with uvx**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
+This chapter covers the long-term maintenance picture for teams relying on the `create-python-server` scaffold: what the archive status means operationally, how to sustain generated servers over time, and when and how to migrate to actively maintained scaffolding alternatives.
+## Learning Goals
-This chapter covers long-term maintenance strategy for teams relying on archived scaffolding tooling.
+- Account for archived upstream status in risk planning and ownership models
+- Define patch strategy for internal usage of archived tooling
+- Plan migration toward actively maintained scaffolding paths
+- Preserve compatibility and quality during transitions
-## Learning Goals
+## Understanding the Archive Status
-- account for archived upstream status in risk planning
-- define ownership and patch strategy for internal usage
-- plan migration toward actively maintained scaffolding paths
-- preserve compatibility and quality during transitions
+`modelcontextprotocol/create-python-server` is archived: the repository is read-only, no new releases are published, and no pull requests are reviewed. The generator binary itself (`uvx create-mcp-server`) remains installable from PyPI for as long as the package is not yanked, but no functional updates will be made.
-## Migration Controls
+```mermaid
+graph LR
+ ARCHIVED[create-python-server\nArchived on GitHub\nPyPI package still available]
-| Control | Why It Matters |
-|:--------|:---------------|
-| internal ownership | ensures fixes can continue post-archive |
-| fork readiness | supports urgent patching/security updates |
-| compatibility tests | protects behavior through migration |
-| phased rollout | lowers disruption for dependent teams |
+ ARCHIVED --> RISK1[Risk: mcp SDK breaking change\nmay break generated template code]
+ ARCHIVED --> RISK2[Risk: uv CLI changes\nmay affect generator behavior]
+ ARCHIVED --> RISK3[Risk: security vulnerability\nin generator or template]
+ ARCHIVED --> RISK4[Risk: Python 3.13+ incompatibility]
-## Source References
+ ARCHIVED --> MITIGATION[Mitigation strategies\nsee below]
+```
-- [Create Python Server Repository](https://github.com/modelcontextprotocol/create-python-server)
-- [Create Python Server README](https://github.com/modelcontextprotocol/create-python-server/blob/main/README.md)
-- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
+## Risk Assessment
-## Summary
+| Risk | Likelihood | Impact | Mitigation |
+|:-----|:-----------|:-------|:-----------|
+| `mcp` SDK major version breaks generated code | Medium | High — servers stop running | Pin `mcp` version in `pyproject.toml` |
+| Template uses deprecated `mcp` API | High over time | Medium — gradual deprecation warnings | Migrate to FastMCP API manually |
+| Generator won't install due to dependency conflict | Low | Low — only affects new server generation | Fork generator or switch scaffolding tool |
+| Security issue in template | Low | Medium | Patch generated code directly |
-You now have a long-term operating model for scaffold-derived Python MCP services in archived-tool scenarios.
+## What "Archived" Means for Running Servers
-Return to the [Create Python Server Tutorial index](README.md).
+The archive status of the **generator** has minimal impact on already-generated servers:
-## Source Code Walkthrough
+- Generated servers are independent Python packages with their own `pyproject.toml`
+- They depend on `mcp>=1.0.0` from the Python SDK (actively maintained)
+- The generator's source code is no longer needed after the project is generated
-### `src/create_mcp_server/__init__.py`
+```mermaid
+flowchart LR
+ GENERATOR[create-python-server\nArchived generator]
+ GENERATED[my-notes-server\nGenerated server package]
+ MCPSDK[modelcontextprotocol/python-sdk\nActive SDK]
+
+ GENERATOR -->|one-time use| GENERATED
+ MCPSDK -->|runtime dependency| GENERATED
+ GENERATOR -. no longer needed .-> GENERATED
+```
-The `copy_template` function in [`src/create_mcp_server/__init__.py`](https://github.com/modelcontextprotocol/create-python-server/blob/HEAD/src/create_mcp_server/__init__.py) handles a key part of this chapter's functionality:
+The generated server's ongoing health depends on `modelcontextprotocol/python-sdk` (not archived), `uv` (not archived), and your own code quality.
-```py
+## Long-Term Operating Model
+### Pin the mcp SDK Version
-def copy_template(
- path: Path, name: str, description: str, version: str = "0.1.0"
-) -> None:
- """Copy template files into src/"""
- template_dir = Path(__file__).parent / "template"
+In the short term, pin the `mcp` version to avoid unexpected breakage from minor updates:
- target_dir = get_package_directory(path)
+```toml
+# pyproject.toml — conservative pinning
+dependencies = ["mcp>=1.2.0,<2.0.0"]
+```
- from jinja2 import Environment, FileSystemLoader
+Upgrade the version constraint deliberately after reviewing the SDK changelog.
- env = Environment(loader=FileSystemLoader(str(template_dir)))
+### Migrate to FastMCP API
- files = [
- ("__init__.py.jinja2", "__init__.py", target_dir),
- ("server.py.jinja2", "server.py", target_dir),
- ("README.md.jinja2", "README.md", path),
- ]
+The generated template uses the low-level `Server` API. The actively maintained Python SDK now encourages the `FastMCP` decorator pattern, which is more concise and receives more documentation attention:
- pyproject = PyProject(path / "pyproject.toml")
- bin_name = pyproject.first_binary
+```python
+# Generated (low-level Server API)
+server = Server("my-server")
- template_vars = {
- "binary_name": bin_name,
- "server_name": name,
- "server_version": version,
- "server_description": description,
- "server_directory": str(path.resolve()),
- }
+@server.list_tools()
+async def handle_list_tools() -> list[types.Tool]:
+ return [types.Tool(name="add-note", ...)]
- try:
+@server.call_tool()
+async def handle_call_tool(name: str, arguments: dict | None) -> list[...]:
+ ...
```
-This function is important because it defines how Create Python Server Tutorial: Scaffold and Ship MCP Servers with uvx implements the patterns covered in this chapter.
+```python
+# FastMCP API (recommended migration target)
+from mcp.server.fastmcp import FastMCP
+
+mcp = FastMCP("my-server")
+
+@mcp.tool()
+async def add_note(name: str, content: str) -> str:
+ """Add a new note."""
+ notes[name] = content
+ return f"Added note '{name}'"
+```
+FastMCP advantages:
+- Python type hints define input schema automatically (no manual JSON Schema)
+- Docstring becomes tool description
+- Fewer lines of boilerplate
+- Aligns with current MCP Python SDK documentation
-## How These Components Connect
+### Migration Checklist
```mermaid
flowchart TD
- A[copy_template]
+ ASSESS[Assess: how many servers\nuse create-python-server scaffold?]
+ ASSESS --> FEW[1-3 servers:\nMigrate individually\nto FastMCP]
+ ASSESS --> MANY[4+ servers:\nCreate internal scaffold template\nbased on FastMCP]
+ FEW --> REWRITE[Port handlers to FastMCP\nKeep test suite green throughout]
+ MANY --> TEMPLATE[Internal scaffolding tool\nor Cookiecutter template]
+ REWRITE --> VERIFY[Verify in Inspector\nVerify in Claude Desktop]
+ TEMPLATE --> STANDARDIZE[Standardize all new servers\non internal scaffold]
```
+
+### Migration Steps (Low-Level → FastMCP)
+
+1. Add `from mcp.server.fastmcp import FastMCP` to `server.py`
+2. Replace `Server("name")` with `mcp = FastMCP("name")`
+3. Convert each `@server.list_tools()` + `@server.call_tool()` pair into `@mcp.tool()` functions
+4. Convert `@server.list_resources()` + `@server.read_resource()` into `@mcp.resource()` functions
+5. Convert `@server.list_prompts()` + `@server.get_prompt()` into `@mcp.prompt()` functions
+6. Replace the `main()` async function with `mcp.run(transport="stdio")` (or remove and use `if __name__ == "__main__": mcp.run()`)
+7. Update `__init__.py` if needed to match new entry point
+8. Run the full test suite and verify with Inspector
+
+## Alternative Scaffolding Options
+
+If starting fresh today rather than migrating:
+
+| Option | Approach | Notes |
+|:-------|:---------|:------|
+| `FastMCP` directly | `uv init` + `uv add mcp` + write `FastMCP` server | Most direct, minimal boilerplate |
+| `mcp` CLI | `uvx create-mcp-server` (archived) | Still works, generates low-level API template |
+| Cookiecutter | Community templates | Search PyPI for `cookiecutter-mcp` patterns |
+| Internal scaffold | Fork of create-python-server with FastMCP template | For teams with many servers |
+
+## Source References
+
+- [Create Python Server Repository](https://github.com/modelcontextprotocol/create-python-server)
+- [MCP Python SDK (Active)](https://github.com/modelcontextprotocol/python-sdk)
+- [FastMCP Documentation](https://github.com/modelcontextprotocol/python-sdk/blob/main/README.md)
+
+## Summary
+
+The generator being archived does not threaten already-generated servers — those depend on the active Python SDK, not the generator. The primary operational risk is the low-level `Server` API drifting from the documentation and examples that increasingly target `FastMCP`. Migrate to `FastMCP` incrementally per server, verifying with the Inspector at each step. For new projects, start with `FastMCP` directly rather than going through the archived generator.
+
+Return to the [Create Python Server Tutorial index](README.md).
diff --git a/tutorials/crewai-tutorial/02-agent-roles.md b/tutorials/crewai-tutorial/02-agent-roles.md
index 45298875..9782b9a8 100644
--- a/tutorials/crewai-tutorial/02-agent-roles.md
+++ b/tutorials/crewai-tutorial/02-agent-roles.md
@@ -506,6 +506,25 @@ hybrid_roles = {
}
```
+## Agent Role Architecture
+
+```mermaid
+flowchart TD
+ A[Define Role Config]
+ B[Set role, goal, backstory]
+ C[Assign tools to agent]
+ D[Define expertise and specializations]
+ E[Agent registered in Crew]
+ F[Task routed to best-fit agent]
+ G[Agent executes using tools]
+ A --> B
+ B --> C
+ C --> D
+ D --> E
+ E --> F
+ F --> G
+```
+
## What We've Accomplished
✅ **Understood agent role frameworks** and specialization patterns
diff --git a/tutorials/crewai-tutorial/03-task-planning.md b/tutorials/crewai-tutorial/03-task-planning.md
index ade48de2..45215bc6 100644
--- a/tutorials/crewai-tutorial/03-task-planning.md
+++ b/tutorials/crewai-tutorial/03-task-planning.md
@@ -436,6 +436,27 @@ critical_path_pattern = {
}
```
+## Task Planning Architecture
+
+```mermaid
+flowchart TD
+ A[Complex objective received]
+ B[Break into sequential tasks]
+ C[Each Task gets description and expected_output]
+ D[Assign task to specialized agent]
+ E[Define task dependencies via context]
+ F[Crew executes tasks in order]
+ G[Output of each task feeds next task]
+ H[Final output synthesized]
+ A --> B
+ B --> C
+ C --> D
+ D --> E
+ E --> F
+ F --> G
+ G --> H
+```
+
## What We've Accomplished
✅ **Mastered task definition** with structured frameworks
diff --git a/tutorials/crewai-tutorial/04-tool-integration.md b/tutorials/crewai-tutorial/04-tool-integration.md
index 3a211456..f7929208 100644
--- a/tutorials/crewai-tutorial/04-tool-integration.md
+++ b/tutorials/crewai-tutorial/04-tool-integration.md
@@ -487,6 +487,25 @@ class ToolPerformanceMonitor:
return recommendations
```
+## Tool Integration Architecture
+
+```mermaid
+flowchart TD
+ A[Define tool with @tool decorator]
+ B[Tool registered in agent tools list]
+ C[Agent task requires external data or action]
+ D[Agent calls tool with parameters]
+ E[Tool executes and returns result]
+ F[Result added to agent context]
+ G[Agent continues task with new data]
+ A --> B
+ B --> C
+ C --> D
+ D --> E
+ E --> F
+ F --> G
+```
+
## What We've Accomplished
✅ **Understood tool integration** fundamentals and architecture
diff --git a/tutorials/crewai-tutorial/05-crew-communication.md b/tutorials/crewai-tutorial/05-crew-communication.md
index 59b32b35..46a0a57f 100644
--- a/tutorials/crewai-tutorial/05-crew-communication.md
+++ b/tutorials/crewai-tutorial/05-crew-communication.md
@@ -497,6 +497,25 @@ class CommunicationAnalytics:
return recommendations
```
+## Crew Communication Architecture
+
+```mermaid
+flowchart TD
+ A[Agent completes task]
+ B[Output stored as task result]
+ C[Next task receives output as context]
+ D[Hierarchical crew: manager agent delegates]
+ E[Manager reviews subtask results]
+ F[Manager synthesizes final response]
+ G[Sequential process: chain of outputs]
+ A --> B
+ B --> C
+ B --> D
+ D --> E
+ E --> F
+ C --> G
+```
+
## What We've Accomplished
✅ **Built communication architecture** for multi-agent systems
diff --git a/tutorials/crewai-tutorial/06-process-management.md b/tutorials/crewai-tutorial/06-process-management.md
index 2b6bc85b..859741e5 100644
--- a/tutorials/crewai-tutorial/06-process-management.md
+++ b/tutorials/crewai-tutorial/06-process-management.md
@@ -498,6 +498,28 @@ class ProcessController:
await self.monitor.record_scaling_event(process_id, scale_type, scale_factor)
```
+## Process Management Architecture
+
+```mermaid
+flowchart TD
+ A[Crew kickoff called]
+ B{Process type}
+ C[Sequential: tasks run one by one]
+ D[Hierarchical: manager delegates to agents]
+ E[Task A completes]
+ F[Output passed to Task B context]
+ G[Manager reviews all results]
+ H[Final synthesized output]
+ A --> B
+ B -- sequential --> C
+ B -- hierarchical --> D
+ C --> E
+ E --> F
+ F --> H
+ D --> G
+ G --> H
+```
+
## What We've Accomplished
✅ **Implemented sequential processing** for dependent tasks
diff --git a/tutorials/crewai-tutorial/07-advanced-patterns.md b/tutorials/crewai-tutorial/07-advanced-patterns.md
index 9b7f4e3c..27ea684a 100644
--- a/tutorials/crewai-tutorial/07-advanced-patterns.md
+++ b/tutorials/crewai-tutorial/07-advanced-patterns.md
@@ -515,6 +515,28 @@ class CrewScalingManager:
}
```
+## Advanced Multi-Crew Architecture
+
+```mermaid
+flowchart TD
+ A[Complex enterprise task]
+ B[Orchestrator crew receives task]
+ C[Specialized sub-crews spawned]
+ D[Research crew gathers data]
+ E[Analysis crew processes data]
+ F[Execution crew implements]
+ G[Results aggregated by orchestrator]
+ H[Final output delivered]
+ A --> B
+ B --> C
+ C --> D
+ C --> E
+ D --> F
+ E --> F
+ F --> G
+ G --> H
+```
+
## What We've Accomplished
✅ **Built federated crew systems** for distributed collaboration
diff --git a/tutorials/crewai-tutorial/08-production-deployment.md b/tutorials/crewai-tutorial/08-production-deployment.md
index a96b2885..0e60a282 100644
--- a/tutorials/crewai-tutorial/08-production-deployment.md
+++ b/tutorials/crewai-tutorial/08-production-deployment.md
@@ -538,6 +538,27 @@ class ProductionConfig:
return errors
```
+## Production Architecture
+
+```mermaid
+flowchart TD
+ A[Production crew deployment]
+ B[Environment variables and secrets configured]
+ C[Crew instantiated with production LLM settings]
+ D[Task submitted via API or queue]
+ E[Crew executes with monitoring]
+ F[Telemetry and logs emitted]
+ G[Result returned to caller]
+ H[Alerts triggered on failure]
+ A --> B
+ B --> C
+ C --> D
+ D --> E
+ E --> F
+ E --> G
+ F --> H
+```
+
## What We've Accomplished
✅ **Built production-ready crew infrastructure** with monitoring and scaling
diff --git a/tutorials/crush-tutorial/01-getting-started.md b/tutorials/crush-tutorial/01-getting-started.md
index 831707b2..80ab602b 100644
--- a/tutorials/crush-tutorial/01-getting-started.md
+++ b/tutorials/crush-tutorial/01-getting-started.md
@@ -63,10 +63,47 @@ You now have Crush installed and running with a valid provider path.
Next: [Chapter 2: Architecture and Session Model](02-architecture-and-session-model.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
+### `main.go`
+
+The `main` function in [`main.go`](https://github.com/charmbracelet/crush/blob/HEAD/main.go) handles a key part of this chapter's functionality:
+
+```go
+// Package main is the entry point for the Crush CLI.
+//
+// @title Crush API
+// @version 1.0
+// @description Crush is a terminal-based AI coding assistant. This API is served over a Unix socket (or Windows named pipe) and provides programmatic access to workspaces, sessions, agents, LSP, MCP, and more.
+// @contact.name Charm
+// @contact.url https://charm.sh
+// @license.name MIT
+// @license.url https://github.com/charmbracelet/crush/blob/main/LICENSE
+// @BasePath /v1
+package main
+
+import (
+ "log/slog"
+ "net/http"
+ _ "net/http/pprof"
+ "os"
+
+ "github.com/charmbracelet/crush/internal/cmd"
+ _ "github.com/joho/godotenv/autoload"
+)
+
+func main() {
+ if os.Getenv("CRUSH_PROFILE") != "" {
+ go func() {
+ slog.Info("Serving pprof at localhost:6060")
+ if httpErr := http.ListenAndServe("localhost:6060", nil); httpErr != nil {
+ slog.Error("Failed to pprof listen", "error", httpErr)
+ }
+ }()
+```
+
+This function is important because it defines how Crush Tutorial: Multi-Model Terminal Coding Agent with Strong Extensibility implements the patterns covered in this chapter.
+
### `schema.json`
The `options` interface in [`schema.json`](https://github.com/charmbracelet/crush/blob/HEAD/schema.json) handles a key part of this chapter's functionality:
@@ -108,40 +145,6 @@ The `options` interface in [`schema.json`](https://github.com/charmbracelet/crus
This interface is important because it defines how Crush Tutorial: Multi-Model Terminal Coding Agent with Strong Extensibility implements the patterns covered in this chapter.
-### `main.go`
-
-The `main` function in [`main.go`](https://github.com/charmbracelet/crush/blob/HEAD/main.go) handles a key part of this chapter's functionality:
-
-```go
-package main
-
-import (
- "log/slog"
- "net/http"
- _ "net/http/pprof"
- "os"
-
- "github.com/charmbracelet/crush/internal/cmd"
- _ "github.com/joho/godotenv/autoload"
-)
-
-func main() {
- if os.Getenv("CRUSH_PROFILE") != "" {
- go func() {
- slog.Info("Serving pprof at localhost:6060")
- if httpErr := http.ListenAndServe("localhost:6060", nil); httpErr != nil {
- slog.Error("Failed to pprof listen", "error", httpErr)
- }
- }()
- }
-
- cmd.Execute()
-}
-
-```
-
-This function is important because it defines how Crush Tutorial: Multi-Model Terminal Coding Agent with Strong Extensibility implements the patterns covered in this chapter.
-
### `internal/agent/agent.go`
The `NewSessionAgent` function in [`internal/agent/agent.go`](https://github.com/charmbracelet/crush/blob/HEAD/internal/agent/agent.go) handles a key part of this chapter's functionality:
@@ -229,8 +232,8 @@ This function is important because it defines how Crush Tutorial: Multi-Model Te
```mermaid
flowchart TD
- A[options]
- B[main]
+ A[main]
+ B[options]
C[NewSessionAgent]
D[Run]
E[Summarize]
diff --git a/tutorials/crush-tutorial/02-architecture-and-session-model.md b/tutorials/crush-tutorial/02-architecture-and-session-model.md
index fbf0ceca..9694dc79 100644
--- a/tutorials/crush-tutorial/02-architecture-and-session-model.md
+++ b/tutorials/crush-tutorial/02-architecture-and-session-model.md
@@ -56,170 +56,168 @@ You now understand how Crush organizes context and configuration across sessions
Next: [Chapter 3: Providers and Model Configuration](03-providers-and-model-configuration.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `internal/lsp/client.go`
+### `internal/config/config.go`
-The `HandlesFile` function in [`internal/lsp/client.go`](https://github.com/charmbracelet/crush/blob/HEAD/internal/lsp/client.go) handles a key part of this chapter's functionality:
+The `Limits` function in [`internal/config/config.go`](https://github.com/charmbracelet/crush/blob/HEAD/internal/config/config.go) handles a key part of this chapter's functionality:
```go
}
-// HandlesFile checks if this LSP client handles the given file based on its
-// extension and whether it's within the working directory.
-func (c *Client) HandlesFile(path string) bool {
- if c == nil {
- return false
- }
- if !fsext.HasPrefix(path, c.cwd) {
- slog.Debug("File outside workspace", "name", c.name, "file", path, "workDir", c.cwd)
- return false
- }
- return handlesFiletype(c.name, c.fileTypes, path)
+func (c Completions) Limits() (depth, items int) {
+ return ptrValOr(c.MaxDepth, 0), ptrValOr(c.MaxItems, 0)
}
-// OpenFile opens a file in the LSP server.
-func (c *Client) OpenFile(ctx context.Context, filepath string) error {
- if !c.HandlesFile(filepath) {
- return nil
- }
+type Permissions struct {
+ AllowedTools []string `json:"allowed_tools,omitempty" jsonschema:"description=List of tools that don't require permission prompts,example=bash,example=view"`
+}
- uri := string(protocol.URIFromPath(filepath))
+type TrailerStyle string
- if _, exists := c.openFiles.Get(uri); exists {
- return nil // Already open
- }
+const (
+ TrailerStyleNone TrailerStyle = "none"
+ TrailerStyleCoAuthoredBy TrailerStyle = "co-authored-by"
+ TrailerStyleAssistedBy TrailerStyle = "assisted-by"
+)
- // Skip files that do not exist or cannot be read
- content, err := os.ReadFile(filepath)
- if err != nil {
- return fmt.Errorf("error reading file: %w", err)
+type Attribution struct {
+ TrailerStyle TrailerStyle `json:"trailer_style,omitempty" jsonschema:"description=Style of attribution trailer to add to commits,enum=none,enum=co-authored-by,enum=assisted-by,default=assisted-by"`
+ CoAuthoredBy *bool `json:"co_authored_by,omitempty" jsonschema:"description=Deprecated: use trailer_style instead"`
+ GeneratedWith bool `json:"generated_with,omitempty" jsonschema:"description=Add Generated with Crush line to commit messages and issues and PRs,default=true"`
+}
+
+// JSONSchemaExtend marks the co_authored_by field as deprecated in the schema.
+func (Attribution) JSONSchemaExtend(schema *jsonschema.Schema) {
+ if schema.Properties != nil {
+ if prop, ok := schema.Properties.Get("co_authored_by"); ok {
+ prop.Deprecated = true
+ }
}
+}
```
This function is important because it defines how Crush Tutorial: Multi-Model Terminal Coding Agent with Strong Extensibility implements the patterns covered in this chapter.
-### `internal/lsp/client.go`
+### `internal/config/config.go`
-The `OpenFile` function in [`internal/lsp/client.go`](https://github.com/charmbracelet/crush/blob/HEAD/internal/lsp/client.go) handles a key part of this chapter's functionality:
+The `Sorted` function in [`internal/config/config.go`](https://github.com/charmbracelet/crush/blob/HEAD/internal/config/config.go) handles a key part of this chapter's functionality:
```go
+}
+
+func (m MCPs) Sorted() []MCP {
+ sorted := make([]MCP, 0, len(m))
+ for k, v := range m {
+ sorted = append(sorted, MCP{
+ Name: k,
+ MCP: v,
+ })
+ }
+ slices.SortFunc(sorted, func(a, b MCP) int {
+ return strings.Compare(a.Name, b.Name)
+ })
+ return sorted
+}
- // Files are currently opened by the LSP
- openFiles *csync.Map[string, *OpenFileInfo]
+type LSPs map[string]LSPConfig
- // Server state
- serverState atomic.Value
+type LSP struct {
+ Name string `json:"name"`
+ LSP LSPConfig `json:"lsp"`
}
-// New creates a new LSP client using the powernap implementation.
-func New(
- ctx context.Context,
- name string,
- cfg config.LSPConfig,
- resolver config.VariableResolver,
- cwd string,
- debug bool,
-) (*Client, error) {
- client := &Client{
- name: name,
- fileTypes: cfg.FileTypes,
- diagnostics: csync.NewVersionedMap[protocol.DocumentURI, []protocol.Diagnostic](),
- openFiles: csync.NewMap[string, *OpenFileInfo](),
- config: cfg,
- ctx: ctx,
- debug: debug,
- resolver: resolver,
- cwd: cwd,
+func (l LSPs) Sorted() []LSP {
+ sorted := make([]LSP, 0, len(l))
+ for k, v := range l {
+ sorted = append(sorted, LSP{
+ Name: k,
+ LSP: v,
+ })
}
- client.serverState.Store(StateStopped)
-
- if err := client.createPowernapClient(); err != nil {
- return nil, err
+ slices.SortFunc(sorted, func(a, b LSP) int {
```
This function is important because it defines how Crush Tutorial: Multi-Model Terminal Coding Agent with Strong Extensibility implements the patterns covered in this chapter.
-### `internal/lsp/client.go`
+### `internal/config/config.go`
-The `NotifyChange` function in [`internal/lsp/client.go`](https://github.com/charmbracelet/crush/blob/HEAD/internal/lsp/client.go) handles a key part of this chapter's functionality:
+The `Sorted` function in [`internal/config/config.go`](https://github.com/charmbracelet/crush/blob/HEAD/internal/config/config.go) handles a key part of this chapter's functionality:
```go
}
-// NotifyChange notifies the server about a file change.
-func (c *Client) NotifyChange(ctx context.Context, filepath string) error {
- if c == nil {
- return nil
- }
- uri := string(protocol.URIFromPath(filepath))
-
- content, err := os.ReadFile(filepath)
- if err != nil {
- return fmt.Errorf("error reading file: %w", err)
+func (m MCPs) Sorted() []MCP {
+ sorted := make([]MCP, 0, len(m))
+ for k, v := range m {
+ sorted = append(sorted, MCP{
+ Name: k,
+ MCP: v,
+ })
}
+ slices.SortFunc(sorted, func(a, b MCP) int {
+ return strings.Compare(a.Name, b.Name)
+ })
+ return sorted
+}
- fileInfo, isOpen := c.openFiles.Get(uri)
- if !isOpen {
- return fmt.Errorf("cannot notify change for unopened file: %s", filepath)
- }
+type LSPs map[string]LSPConfig
- // Increment version
- fileInfo.Version++
+type LSP struct {
+ Name string `json:"name"`
+ LSP LSPConfig `json:"lsp"`
+}
- // Create change event
- changes := []protocol.TextDocumentContentChangeEvent{
- {
- Value: protocol.TextDocumentContentChangeWholeDocument{
- Text: string(content),
- },
- },
+func (l LSPs) Sorted() []LSP {
+ sorted := make([]LSP, 0, len(l))
+ for k, v := range l {
+ sorted = append(sorted, LSP{
+ Name: k,
+ LSP: v,
+ })
}
-
- return c.client.NotifyDidChangeTextDocument(ctx, uri, int(fileInfo.Version), changes)
+ slices.SortFunc(sorted, func(a, b LSP) int {
```
This function is important because it defines how Crush Tutorial: Multi-Model Terminal Coding Agent with Strong Extensibility implements the patterns covered in this chapter.
-### `internal/lsp/client.go`
+### `internal/config/config.go`
-The `IsFileOpen` function in [`internal/lsp/client.go`](https://github.com/charmbracelet/crush/blob/HEAD/internal/lsp/client.go) handles a key part of this chapter's functionality:
+The `ResolvedEnv` function in [`internal/config/config.go`](https://github.com/charmbracelet/crush/blob/HEAD/internal/config/config.go) handles a key part of this chapter's functionality:
```go
}
-// IsFileOpen checks if a file is currently open.
-func (c *Client) IsFileOpen(filepath string) bool {
- uri := string(protocol.URIFromPath(filepath))
- _, exists := c.openFiles.Get(uri)
- return exists
+func (l LSPConfig) ResolvedEnv() []string {
+ return resolveEnvs(l.Env)
}
-// CloseAllFiles closes all currently open files.
-func (c *Client) CloseAllFiles(ctx context.Context) {
- for uri := range c.openFiles.Seq2() {
- if c.debug {
- slog.Debug("Closing file", "file", uri)
- }
- if err := c.client.NotifyDidCloseTextDocument(ctx, uri); err != nil {
- slog.Warn("Error closing file", "uri", uri, "error", err)
+func (m MCPConfig) ResolvedEnv() []string {
+ return resolveEnvs(m.Env)
+}
+
+func (m MCPConfig) ResolvedHeaders() map[string]string {
+ resolver := NewShellVariableResolver(env.New())
+ for e, v := range m.Headers {
+ var err error
+ m.Headers[e], err = resolver.ResolveValue(v)
+ if err != nil {
+ slog.Error("Error resolving header variable", "error", err, "variable", e, "value", v)
continue
}
- c.openFiles.Del(uri)
}
+ return m.Headers
}
-// GetFileDiagnostics returns diagnostics for a specific file.
-func (c *Client) GetFileDiagnostics(uri protocol.DocumentURI) []protocol.Diagnostic {
- diags, _ := c.diagnostics.Get(uri)
- return diags
-}
+type Agent struct {
+ ID string `json:"id,omitempty"`
+ Name string `json:"name,omitempty"`
+ Description string `json:"description,omitempty"`
+ // This is the id of the system prompt used by the agent
+ Disabled bool `json:"disabled,omitempty"`
+
+ Model SelectedModelType `json:"model" jsonschema:"required,description=The model type to use for this agent,enum=large,enum=small,default=large"`
-// GetDiagnostics returns all diagnostics for all files.
-func (c *Client) GetDiagnostics() map[protocol.DocumentURI][]protocol.Diagnostic {
- if c == nil {
```
This function is important because it defines how Crush Tutorial: Multi-Model Terminal Coding Agent with Strong Extensibility implements the patterns covered in this chapter.
@@ -229,11 +227,11 @@ This function is important because it defines how Crush Tutorial: Multi-Model Te
```mermaid
flowchart TD
- A[HandlesFile]
- B[OpenFile]
- C[NotifyChange]
- D[IsFileOpen]
- E[CloseAllFiles]
+ A[Limits]
+ B[Sorted]
+ C[Sorted]
+ D[ResolvedEnv]
+ E[ResolvedEnv]
A --> B
B --> C
C --> D
diff --git a/tutorials/crush-tutorial/03-providers-and-model-configuration.md b/tutorials/crush-tutorial/03-providers-and-model-configuration.md
index 4910862c..dc6c736b 100644
--- a/tutorials/crush-tutorial/03-providers-and-model-configuration.md
+++ b/tutorials/crush-tutorial/03-providers-and-model-configuration.md
@@ -62,170 +62,168 @@ You now have a predictable strategy for provider selection and model routing in
Next: [Chapter 4: Permissions and Tool Controls](04-permissions-and-tool-controls.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `internal/cmd/session.go`
+### `internal/app/app.go`
-The `runSessionShow` function in [`internal/cmd/session.go`](https://github.com/charmbracelet/crush/blob/HEAD/internal/cmd/session.go) handles a key part of this chapter's functionality:
+The `Config` function in [`internal/app/app.go`](https://github.com/charmbracelet/crush/blob/HEAD/internal/app/app.go) handles a key part of this chapter's functionality:
```go
- Long: "Show session details. Use --json for machine-readable output. ID can be a UUID, full hash, or hash prefix.",
- Args: cobra.ExactArgs(1),
- RunE: runSessionShow,
-}
+ LSPManager *lsp.Manager
-var sessionLastCmd = &cobra.Command{
- Use: "last",
- Short: "Show most recent session",
- Long: "Show the last updated session. Use --json for machine-readable output.",
- RunE: runSessionLast,
-}
+ config *config.ConfigStore
-var sessionDeleteCmd = &cobra.Command{
- Use: "delete ",
- Aliases: []string{"rm"},
- Short: "Delete a session",
- Long: "Delete a session by ID. Use --json for machine-readable output. ID can be a UUID, full hash, or hash prefix.",
- Args: cobra.ExactArgs(1),
- RunE: runSessionDelete,
-}
+ serviceEventsWG *sync.WaitGroup
+ eventsCtx context.Context
+ events chan tea.Msg
+ tuiWG *sync.WaitGroup
-var sessionRenameCmd = &cobra.Command{
- Use: "rename ",
- Short: "Rename a session",
- Long: "Rename a session by ID. Use --json for machine-readable output. ID can be a UUID, full hash, or hash prefix.",
- Args: cobra.MinimumNArgs(2),
- RunE: runSessionRename,
+ // global context and cleanup functions
+ globalCtx context.Context
+ cleanupFuncs []func(context.Context) error
+ agentNotifications *pubsub.Broker[notify.Notification]
}
-func init() {
- sessionListCmd.Flags().BoolVar(&sessionListJSON, "json", false, "output in JSON format")
- sessionShowCmd.Flags().BoolVar(&sessionShowJSON, "json", false, "output in JSON format")
+// New initializes a new application instance.
+func New(ctx context.Context, conn *sql.DB, store *config.ConfigStore) (*App, error) {
+ q := db.New(conn)
+ sessions := session.NewService(q, conn)
+ messages := message.NewService(q)
+ files := history.NewService(q, conn)
+ cfg := store.Config()
+ skipPermissionsRequests := store.Overrides().SkipPermissionRequests
+ var allowedTools []string
+ if cfg.Permissions != nil && cfg.Permissions.AllowedTools != nil {
+ allowedTools = cfg.Permissions.AllowedTools
+ }
+
+ app := &App{
+ Sessions: sessions,
+ Messages: messages,
+ History: files,
```
This function is important because it defines how Crush Tutorial: Multi-Model Terminal Coding Agent with Strong Extensibility implements the patterns covered in this chapter.
-### `internal/cmd/session.go`
+### `internal/app/app.go`
-The `runSessionDelete` function in [`internal/cmd/session.go`](https://github.com/charmbracelet/crush/blob/HEAD/internal/cmd/session.go) handles a key part of this chapter's functionality:
+The `Store` function in [`internal/app/app.go`](https://github.com/charmbracelet/crush/blob/HEAD/internal/app/app.go) handles a key part of this chapter's functionality:
```go
- Long: "Delete a session by ID. Use --json for machine-readable output. ID can be a UUID, full hash, or hash prefix.",
- Args: cobra.ExactArgs(1),
- RunE: runSessionDelete,
-}
+ LSPManager *lsp.Manager
-var sessionRenameCmd = &cobra.Command{
- Use: "rename <id> <title>",
- Short: "Rename a session",
- Long: "Rename a session by ID. Use --json for machine-readable output. ID can be a UUID, full hash, or hash prefix.",
- Args: cobra.MinimumNArgs(2),
- RunE: runSessionRename,
-}
+ config *config.ConfigStore
-func init() {
- sessionListCmd.Flags().BoolVar(&sessionListJSON, "json", false, "output in JSON format")
- sessionShowCmd.Flags().BoolVar(&sessionShowJSON, "json", false, "output in JSON format")
- sessionLastCmd.Flags().BoolVar(&sessionLastJSON, "json", false, "output in JSON format")
- sessionDeleteCmd.Flags().BoolVar(&sessionDeleteJSON, "json", false, "output in JSON format")
- sessionRenameCmd.Flags().BoolVar(&sessionRenameJSON, "json", false, "output in JSON format")
- sessionCmd.AddCommand(sessionListCmd)
- sessionCmd.AddCommand(sessionShowCmd)
- sessionCmd.AddCommand(sessionLastCmd)
- sessionCmd.AddCommand(sessionDeleteCmd)
- sessionCmd.AddCommand(sessionRenameCmd)
-}
+ serviceEventsWG *sync.WaitGroup
+ eventsCtx context.Context
+ events chan tea.Msg
+ tuiWG *sync.WaitGroup
-type sessionServices struct {
- sessions session.Service
- messages message.Service
+ // global context and cleanup functions
+ globalCtx context.Context
+ cleanupFuncs []func(context.Context) error
+ agentNotifications *pubsub.Broker[notify.Notification]
}
-func sessionSetup(cmd *cobra.Command) (context.Context, *sessionServices, func(), error) {
+// New initializes a new application instance.
+func New(ctx context.Context, conn *sql.DB, store *config.ConfigStore) (*App, error) {
+ q := db.New(conn)
+ sessions := session.NewService(q, conn)
+ messages := message.NewService(q)
+ files := history.NewService(q, conn)
+ cfg := store.Config()
+ skipPermissionsRequests := store.Overrides().SkipPermissionRequests
+ var allowedTools []string
+ if cfg.Permissions != nil && cfg.Permissions.AllowedTools != nil {
+ allowedTools = cfg.Permissions.AllowedTools
+ }
+
+ app := &App{
+ Sessions: sessions,
+ Messages: messages,
+ History: files,
```
This function is important because it defines how Crush Tutorial: Multi-Model Terminal Coding Agent with Strong Extensibility implements the patterns covered in this chapter.
-### `internal/cmd/session.go`
+### `internal/app/app.go`
-The `runSessionRename` function in [`internal/cmd/session.go`](https://github.com/charmbracelet/crush/blob/HEAD/internal/cmd/session.go) handles a key part of this chapter's functionality:
+The `Events` function in [`internal/app/app.go`](https://github.com/charmbracelet/crush/blob/HEAD/internal/app/app.go) handles a key part of this chapter's functionality:
```go
- Long: "Rename a session by ID. Use --json for machine-readable output. ID can be a UUID, full hash, or hash prefix.",
- Args: cobra.MinimumNArgs(2),
- RunE: runSessionRename,
-}
+ config *config.ConfigStore
-func init() {
- sessionListCmd.Flags().BoolVar(&sessionListJSON, "json", false, "output in JSON format")
- sessionShowCmd.Flags().BoolVar(&sessionShowJSON, "json", false, "output in JSON format")
- sessionLastCmd.Flags().BoolVar(&sessionLastJSON, "json", false, "output in JSON format")
- sessionDeleteCmd.Flags().BoolVar(&sessionDeleteJSON, "json", false, "output in JSON format")
- sessionRenameCmd.Flags().BoolVar(&sessionRenameJSON, "json", false, "output in JSON format")
- sessionCmd.AddCommand(sessionListCmd)
- sessionCmd.AddCommand(sessionShowCmd)
- sessionCmd.AddCommand(sessionLastCmd)
- sessionCmd.AddCommand(sessionDeleteCmd)
- sessionCmd.AddCommand(sessionRenameCmd)
-}
+ serviceEventsWG *sync.WaitGroup
+ eventsCtx context.Context
+ events chan tea.Msg
+ tuiWG *sync.WaitGroup
-type sessionServices struct {
- sessions session.Service
- messages message.Service
+ // global context and cleanup functions
+ globalCtx context.Context
+ cleanupFuncs []func(context.Context) error
+ agentNotifications *pubsub.Broker[notify.Notification]
}
-func sessionSetup(cmd *cobra.Command) (context.Context, *sessionServices, func(), error) {
- dataDir, _ := cmd.Flags().GetString("data-dir")
- ctx := cmd.Context()
-
- if dataDir == "" {
- cfg, err := config.Init("", "", false)
- if err != nil {
- return nil, nil, nil, fmt.Errorf("failed to initialize config: %w", err)
- }
+// New initializes a new application instance.
+func New(ctx context.Context, conn *sql.DB, store *config.ConfigStore) (*App, error) {
+ q := db.New(conn)
+ sessions := session.NewService(q, conn)
+ messages := message.NewService(q)
+ files := history.NewService(q, conn)
+ cfg := store.Config()
+ skipPermissionsRequests := store.Overrides().SkipPermissionRequests
+ var allowedTools []string
+ if cfg.Permissions != nil && cfg.Permissions.AllowedTools != nil {
+ allowedTools = cfg.Permissions.AllowedTools
+ }
+
+ app := &App{
+ Sessions: sessions,
+ Messages: messages,
+ History: files,
+ Permissions: permission.NewPermissionService(store.WorkingDir(), skipPermissionsRequests, allowedTools),
+ FileTracker: filetracker.NewService(q),
```
This function is important because it defines how Crush Tutorial: Multi-Model Terminal Coding Agent with Strong Extensibility implements the patterns covered in this chapter.
-### `internal/cmd/session.go`
+### `internal/app/app.go`
-The `runSessionLast` function in [`internal/cmd/session.go`](https://github.com/charmbracelet/crush/blob/HEAD/internal/cmd/session.go) handles a key part of this chapter's functionality:
+The `SendEvent` function in [`internal/app/app.go`](https://github.com/charmbracelet/crush/blob/HEAD/internal/app/app.go) handles a key part of this chapter's functionality:
```go
- Short: "Show most recent session",
- Long: "Show the last updated session. Use --json for machine-readable output.",
- RunE: runSessionLast,
}
-var sessionDeleteCmd = &cobra.Command{
- Use: "delete <id>",
- Aliases: []string{"rm"},
- Short: "Delete a session",
- Long: "Delete a session by ID. Use --json for machine-readable output. ID can be a UUID, full hash, or hash prefix.",
- Args: cobra.ExactArgs(1),
- RunE: runSessionDelete,
+// SendEvent pushes a message into the application's events channel.
+// It is non-blocking; the message is dropped if the channel is full.
+func (app *App) SendEvent(msg tea.Msg) {
+ select {
+ case app.events <- msg:
+ default:
+ }
}
-var sessionRenameCmd = &cobra.Command{
- Use: "rename <id> <title>",
- Short: "Rename a session",
- Long: "Rename a session by ID. Use --json for machine-readable output. ID can be a UUID, full hash, or hash prefix.",
- Args: cobra.MinimumNArgs(2),
- RunE: runSessionRename,
+// AgentNotifications returns the broker for agent notification events.
+func (app *App) AgentNotifications() *pubsub.Broker[notify.Notification] {
+ return app.agentNotifications
}
-func init() {
- sessionListCmd.Flags().BoolVar(&sessionListJSON, "json", false, "output in JSON format")
- sessionShowCmd.Flags().BoolVar(&sessionShowJSON, "json", false, "output in JSON format")
- sessionLastCmd.Flags().BoolVar(&sessionLastJSON, "json", false, "output in JSON format")
- sessionDeleteCmd.Flags().BoolVar(&sessionDeleteJSON, "json", false, "output in JSON format")
- sessionRenameCmd.Flags().BoolVar(&sessionRenameJSON, "json", false, "output in JSON format")
- sessionCmd.AddCommand(sessionListCmd)
- sessionCmd.AddCommand(sessionShowCmd)
- sessionCmd.AddCommand(sessionLastCmd)
- sessionCmd.AddCommand(sessionDeleteCmd)
+// resolveSession resolves which session to use for a non-interactive run
+// If continueSessionID is set, it looks up that session by ID
+// If useLast is set, it returns the most recently updated top-level session
+// Otherwise, it creates a new session
+func (app *App) resolveSession(ctx context.Context, continueSessionID string, useLast bool) (session.Session, error) {
+ switch {
+ case continueSessionID != "":
+ if app.Sessions.IsAgentToolSession(continueSessionID) {
+ return session.Session{}, fmt.Errorf("cannot continue an agent tool session: %s", continueSessionID)
+ }
+ sess, err := app.Sessions.Get(ctx, continueSessionID)
+ if err != nil {
+ return session.Session{}, fmt.Errorf("session not found: %s", continueSessionID)
+ }
+ if sess.ParentSessionID != "" {
+ return session.Session{}, fmt.Errorf("cannot continue a child session: %s", continueSessionID)
```
This function is important because it defines how Crush Tutorial: Multi-Model Terminal Coding Agent with Strong Extensibility implements the patterns covered in this chapter.
@@ -235,11 +233,11 @@ This function is important because it defines how Crush Tutorial: Multi-Model Te
```mermaid
flowchart TD
- A[runSessionShow]
- B[runSessionDelete]
- C[runSessionRename]
- D[runSessionLast]
- E[messagePtrs]
+ A[Config]
+ B[Store]
+ C[Events]
+ D[SendEvent]
+ E[AgentNotifications]
A --> B
B --> C
C --> D
diff --git a/tutorials/crush-tutorial/04-permissions-and-tool-controls.md b/tutorials/crush-tutorial/04-permissions-and-tool-controls.md
index e522f1d5..975fac85 100644
--- a/tutorials/crush-tutorial/04-permissions-and-tool-controls.md
+++ b/tutorials/crush-tutorial/04-permissions-and-tool-controls.md
@@ -48,170 +48,168 @@ You now have a practical control model for balancing Crush autonomy and safety.
Next: [Chapter 5: LSP and MCP Integration](05-lsp-and-mcp-integration.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `internal/config/config.go`
+### `internal/cmd/session.go`
-The `IsConfigured` function in [`internal/config/config.go`](https://github.com/charmbracelet/crush/blob/HEAD/internal/config/config.go) handles a key part of this chapter's functionality:
+The `runSessionRename` function in [`internal/cmd/session.go`](https://github.com/charmbracelet/crush/blob/HEAD/internal/cmd/session.go) handles a key part of this chapter's functionality:
```go
+ Long: "Rename a session by ID. Use --json for machine-readable output. ID can be a UUID, full hash, or hash prefix.",
+ Args: cobra.MinimumNArgs(2),
+ RunE: runSessionRename,
}
-// IsConfigured return true if at least one provider is configured
-func (c *Config) IsConfigured() bool {
- return len(c.EnabledProviders()) > 0
+func init() {
+ sessionListCmd.Flags().BoolVar(&sessionListJSON, "json", false, "output in JSON format")
+ sessionShowCmd.Flags().BoolVar(&sessionShowJSON, "json", false, "output in JSON format")
+ sessionLastCmd.Flags().BoolVar(&sessionLastJSON, "json", false, "output in JSON format")
+ sessionDeleteCmd.Flags().BoolVar(&sessionDeleteJSON, "json", false, "output in JSON format")
+ sessionRenameCmd.Flags().BoolVar(&sessionRenameJSON, "json", false, "output in JSON format")
+ sessionCmd.AddCommand(sessionListCmd)
+ sessionCmd.AddCommand(sessionShowCmd)
+ sessionCmd.AddCommand(sessionLastCmd)
+ sessionCmd.AddCommand(sessionDeleteCmd)
+ sessionCmd.AddCommand(sessionRenameCmd)
}
-func (c *Config) GetModel(provider, model string) *catwalk.Model {
- if providerConfig, ok := c.Providers.Get(provider); ok {
- for _, m := range providerConfig.Models {
- if m.ID == model {
- return &m
- }
- }
- }
- return nil
+type sessionServices struct {
+ sessions session.Service
+ messages message.Service
}
-func (c *Config) GetProviderForModel(modelType SelectedModelType) *ProviderConfig {
- model, ok := c.Models[modelType]
- if !ok {
- return nil
- }
- if providerConfig, ok := c.Providers.Get(model.Provider); ok {
- return &providerConfig
- }
- return nil
-}
+func sessionSetup(cmd *cobra.Command) (context.Context, *sessionServices, func(), error) {
+ dataDir, _ := cmd.Flags().GetString("data-dir")
+ ctx := cmd.Context()
-func (c *Config) GetModelByType(modelType SelectedModelType) *catwalk.Model {
- model, ok := c.Models[modelType]
- if !ok {
+ if dataDir == "" {
+ cfg, err := config.Init("", "", false)
+ if err != nil {
+ return nil, nil, nil, fmt.Errorf("failed to initialize config: %w", err)
+ }
```
This function is important because it defines how Crush Tutorial: Multi-Model Terminal Coding Agent with Strong Extensibility implements the patterns covered in this chapter.
-### `internal/config/config.go`
+### `internal/cmd/session.go`
-The `GetModel` function in [`internal/config/config.go`](https://github.com/charmbracelet/crush/blob/HEAD/internal/config/config.go) handles a key part of this chapter's functionality:
+The `runSessionLast` function in [`internal/cmd/session.go`](https://github.com/charmbracelet/crush/blob/HEAD/internal/cmd/session.go) handles a key part of this chapter's functionality:
```go
-}
-
-func (c *Config) GetModel(provider, model string) *catwalk.Model {
- if providerConfig, ok := c.Providers.Get(provider); ok {
- for _, m := range providerConfig.Models {
- if m.ID == model {
- return &m
- }
- }
- }
- return nil
-}
-
-func (c *Config) GetProviderForModel(modelType SelectedModelType) *ProviderConfig {
- model, ok := c.Models[modelType]
- if !ok {
- return nil
- }
- if providerConfig, ok := c.Providers.Get(model.Provider); ok {
- return &providerConfig
- }
- return nil
-}
-
-func (c *Config) GetModelByType(modelType SelectedModelType) *catwalk.Model {
- model, ok := c.Models[modelType]
- if !ok {
- return nil
- }
- return c.GetModel(model.Provider, model.Model)
-}
-
+ Short: "Show most recent session",
+ Long: "Show the last updated session. Use --json for machine-readable output.",
+ RunE: runSessionLast,
+}
+
+var sessionDeleteCmd = &cobra.Command{
+ Use: "delete <id>",
+ Aliases: []string{"rm"},
+ Short: "Delete a session",
+ Long: "Delete a session by ID. Use --json for machine-readable output. ID can be a UUID, full hash, or hash prefix.",
+ Args: cobra.ExactArgs(1),
+ RunE: runSessionDelete,
+}
+
+var sessionRenameCmd = &cobra.Command{
+ Use: "rename <id> <title>",
+ Short: "Rename a session",
+ Long: "Rename a session by ID. Use --json for machine-readable output. ID can be a UUID, full hash, or hash prefix.",
+ Args: cobra.MinimumNArgs(2),
+ RunE: runSessionRename,
+}
+
+func init() {
+ sessionListCmd.Flags().BoolVar(&sessionListJSON, "json", false, "output in JSON format")
+ sessionShowCmd.Flags().BoolVar(&sessionShowJSON, "json", false, "output in JSON format")
+ sessionLastCmd.Flags().BoolVar(&sessionLastJSON, "json", false, "output in JSON format")
+ sessionDeleteCmd.Flags().BoolVar(&sessionDeleteJSON, "json", false, "output in JSON format")
+ sessionRenameCmd.Flags().BoolVar(&sessionRenameJSON, "json", false, "output in JSON format")
+ sessionCmd.AddCommand(sessionListCmd)
+ sessionCmd.AddCommand(sessionShowCmd)
+ sessionCmd.AddCommand(sessionLastCmd)
+ sessionCmd.AddCommand(sessionDeleteCmd)
```
This function is important because it defines how Crush Tutorial: Multi-Model Terminal Coding Agent with Strong Extensibility implements the patterns covered in this chapter.
-### `internal/config/config.go`
+### `internal/cmd/session.go`
-The `GetProviderForModel` function in [`internal/config/config.go`](https://github.com/charmbracelet/crush/blob/HEAD/internal/config/config.go) handles a key part of this chapter's functionality:
+The `messagePtrs` function in [`internal/cmd/session.go`](https://github.com/charmbracelet/crush/blob/HEAD/internal/cmd/session.go) handles a key part of this chapter's functionality:
```go
-}
-
-func (c *Config) GetProviderForModel(modelType SelectedModelType) *ProviderConfig {
- model, ok := c.Models[modelType]
- if !ok {
- return nil
}
- if providerConfig, ok := c.Providers.Get(model.Provider); ok {
- return &providerConfig
+
+ msgPtrs := messagePtrs(msgs)
+ if sessionShowJSON {
+ return outputSessionJSON(cmd.OutOrStdout(), sess, msgPtrs)
}
- return nil
+ return outputSessionHuman(ctx, sess, msgPtrs)
}
-func (c *Config) GetModelByType(modelType SelectedModelType) *catwalk.Model {
- model, ok := c.Models[modelType]
- if !ok {
- return nil
+func runSessionDelete(cmd *cobra.Command, args []string) error {
+ event.SetNonInteractive(true)
+ event.SessionDeletedCommand(sessionDeleteJSON)
+
+ ctx, svc, cleanup, err := sessionSetup(cmd)
+ if err != nil {
+ return err
}
- return c.GetModel(model.Provider, model.Model)
-}
+ defer cleanup()
-func (c *Config) LargeModel() *catwalk.Model {
- model, ok := c.Models[SelectedModelTypeLarge]
- if !ok {
- return nil
+ sess, err := resolveSessionID(ctx, svc.sessions, args[0])
+ if err != nil {
+ return err
}
- return c.GetModel(model.Provider, model.Model)
-}
-func (c *Config) SmallModel() *catwalk.Model {
- model, ok := c.Models[SelectedModelTypeSmall]
- if !ok {
+ if err := svc.sessions.Delete(ctx, sess.ID); err != nil {
+ return fmt.Errorf("failed to delete session: %w", err)
+ }
+
+ out := cmd.OutOrStdout()
+ if sessionDeleteJSON {
+ enc := json.NewEncoder(out)
+ enc.SetEscapeHTML(false)
```
This function is important because it defines how Crush Tutorial: Multi-Model Terminal Coding Agent with Strong Extensibility implements the patterns covered in this chapter.
-### `internal/config/config.go`
+### `internal/cmd/session.go`
-The `GetModelByType` function in [`internal/config/config.go`](https://github.com/charmbracelet/crush/blob/HEAD/internal/config/config.go) handles a key part of this chapter's functionality:
+The `outputSessionJSON` function in [`internal/cmd/session.go`](https://github.com/charmbracelet/crush/blob/HEAD/internal/cmd/session.go) handles a key part of this chapter's functionality:
```go
-}
-
-func (c *Config) GetModelByType(modelType SelectedModelType) *catwalk.Model {
- model, ok := c.Models[modelType]
- if !ok {
- return nil
+ msgPtrs := messagePtrs(msgs)
+ if sessionShowJSON {
+ return outputSessionJSON(cmd.OutOrStdout(), sess, msgPtrs)
}
- return c.GetModel(model.Provider, model.Model)
+ return outputSessionHuman(ctx, sess, msgPtrs)
}
-func (c *Config) LargeModel() *catwalk.Model {
- model, ok := c.Models[SelectedModelTypeLarge]
- if !ok {
- return nil
+func runSessionDelete(cmd *cobra.Command, args []string) error {
+ event.SetNonInteractive(true)
+ event.SessionDeletedCommand(sessionDeleteJSON)
+
+ ctx, svc, cleanup, err := sessionSetup(cmd)
+ if err != nil {
+ return err
}
- return c.GetModel(model.Provider, model.Model)
-}
+ defer cleanup()
-func (c *Config) SmallModel() *catwalk.Model {
- model, ok := c.Models[SelectedModelTypeSmall]
- if !ok {
- return nil
+ sess, err := resolveSessionID(ctx, svc.sessions, args[0])
+ if err != nil {
+ return err
}
- return c.GetModel(model.Provider, model.Model)
-}
-const maxRecentModelsPerType = 5
+ if err := svc.sessions.Delete(ctx, sess.ID); err != nil {
+ return fmt.Errorf("failed to delete session: %w", err)
+ }
-func allToolNames() []string {
- return []string{
- "agent",
- "bash",
+ out := cmd.OutOrStdout()
+ if sessionDeleteJSON {
+ enc := json.NewEncoder(out)
+ enc.SetEscapeHTML(false)
+ return enc.Encode(sessionMutationResult{
+ ID: session.HashID(sess.ID),
```
This function is important because it defines how Crush Tutorial: Multi-Model Terminal Coding Agent with Strong Extensibility implements the patterns covered in this chapter.
@@ -221,11 +219,11 @@ This function is important because it defines how Crush Tutorial: Multi-Model Te
```mermaid
flowchart TD
- A[IsConfigured]
- B[GetModel]
- C[GetProviderForModel]
- D[GetModelByType]
- E[LargeModel]
+ A[runSessionRename]
+ B[runSessionLast]
+ C[messagePtrs]
+ D[outputSessionJSON]
+ E[outputSessionHuman]
A --> B
B --> C
C --> D
diff --git a/tutorials/crush-tutorial/05-lsp-and-mcp-integration.md b/tutorials/crush-tutorial/05-lsp-and-mcp-integration.md
index d6e43571..d1c7749a 100644
--- a/tutorials/crush-tutorial/05-lsp-and-mcp-integration.md
+++ b/tutorials/crush-tutorial/05-lsp-and-mcp-integration.md
@@ -67,170 +67,168 @@ You now know how to wire Crush into language tooling and MCP ecosystems safely.
Next: [Chapter 6: Skills, Commands, and Workflow Customization](06-skills-commands-and-workflow-customization.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `internal/agent/coordinator.go`
+### `internal/config/load.go`
-The `Model` function in [`internal/agent/coordinator.go`](https://github.com/charmbracelet/crush/blob/HEAD/internal/agent/coordinator.go) handles a key part of this chapter's functionality:
+The `ProjectSkillsDir` function in [`internal/config/load.go`](https://github.com/charmbracelet/crush/blob/HEAD/internal/config/load.go) handles a key part of this chapter's functionality:
```go
-var (
- errCoderAgentNotConfigured = errors.New("coder agent not configured")
- errModelProviderNotConfigured = errors.New("model provider not configured")
- errLargeModelNotSelected = errors.New("large model not selected")
- errSmallModelNotSelected = errors.New("small model not selected")
- errLargeModelProviderNotConfigured = errors.New("large model provider not configured")
- errSmallModelProviderNotConfigured = errors.New("small model provider not configured")
- errLargeModelNotFound = errors.New("large model not found in provider config")
- errSmallModelNotFound = errors.New("small model not found in provider config")
-)
-
-type Coordinator interface {
- // INFO: (kujtim) this is not used yet we will use this when we have multiple agents
- // SetMainAgent(string)
- Run(ctx context.Context, sessionID, prompt string, attachments ...message.Attachment) (*fantasy.AgentResult, error)
- Cancel(sessionID string)
- CancelAll()
- IsSessionBusy(sessionID string) bool
- IsBusy() bool
- QueuedPrompts(sessionID string) int
- QueuedPromptsList(sessionID string) []string
- ClearQueue(sessionID string)
- Summarize(context.Context, string) error
- Model() Model
- UpdateModels(ctx context.Context) error
+
+ // Project specific skills dirs.
+ c.Options.SkillsPaths = append(c.Options.SkillsPaths, ProjectSkillsDir(workingDir)...)
+
+ if str, ok := os.LookupEnv("CRUSH_DISABLE_PROVIDER_AUTO_UPDATE"); ok {
+ c.Options.DisableProviderAutoUpdate, _ = strconv.ParseBool(str)
+ }
+
+ if str, ok := os.LookupEnv("CRUSH_DISABLE_DEFAULT_PROVIDERS"); ok {
+ c.Options.DisableDefaultProviders, _ = strconv.ParseBool(str)
+ }
+
+ if c.Options.Attribution == nil {
+ c.Options.Attribution = &Attribution{
+ TrailerStyle: TrailerStyleAssistedBy,
+ GeneratedWith: true,
+ }
+ } else if c.Options.Attribution.TrailerStyle == "" {
+ // Migrate deprecated co_authored_by or apply default
+ if c.Options.Attribution.CoAuthoredBy != nil {
+ if *c.Options.Attribution.CoAuthoredBy {
+ c.Options.Attribution.TrailerStyle = TrailerStyleCoAuthoredBy
+ } else {
+ c.Options.Attribution.TrailerStyle = TrailerStyleNone
+ }
+ } else {
+ c.Options.Attribution.TrailerStyle = TrailerStyleAssistedBy
+ }
+ }
+ c.Options.InitializeAs = cmp.Or(c.Options.InitializeAs, defaultInitializeAs)
}
-type coordinator struct {
- cfg *config.ConfigStore
- sessions session.Service
- messages message.Service
- permissions permission.Service
```
This function is important because it defines how Crush Tutorial: Multi-Model Terminal Coding Agent with Strong Extensibility implements the patterns covered in this chapter.
-### `internal/agent/coordinator.go`
+### `internal/config/load.go`
-The `UpdateModels` function in [`internal/agent/coordinator.go`](https://github.com/charmbracelet/crush/blob/HEAD/internal/agent/coordinator.go) handles a key part of this chapter's functionality:
+The `isAppleTerminal` function in [`internal/config/load.go`](https://github.com/charmbracelet/crush/blob/HEAD/internal/config/load.go) handles a key part of this chapter's functionality:
```go
- Summarize(context.Context, string) error
- Model() Model
- UpdateModels(ctx context.Context) error
-}
-
-type coordinator struct {
- cfg *config.ConfigStore
- sessions session.Service
- messages message.Service
- permissions permission.Service
- history history.Service
- filetracker filetracker.Service
- lspManager *lsp.Manager
- notify pubsub.Publisher[notify.Notification]
-
- currentAgent SessionAgent
- agents map[string]SessionAgent
-
- readyWg errgroup.Group
-}
-
-func NewCoordinator(
- ctx context.Context,
- cfg *config.ConfigStore,
- sessions session.Service,
- messages message.Service,
- permissions permission.Service,
- history history.Service,
- filetracker filetracker.Service,
- lspManager *lsp.Manager,
- notify pubsub.Publisher[notify.Notification],
-) (Coordinator, error) {
+ }
+
+ if isAppleTerminal() {
+ slog.Warn("Detected Apple Terminal, enabling transparent mode")
+ assignIfNil(&cfg.Options.TUI.Transparent, true)
+ }
+
+ // Load known providers, this loads the config from catwalk
+ providers, err := Providers(cfg)
+ if err != nil {
+ return nil, err
+ }
+ store.knownProviders = providers
+
+ env := env.New()
+ // Configure providers
+ valueResolver := NewShellVariableResolver(env)
+ store.resolver = valueResolver
+ if err := cfg.configureProviders(store, env, valueResolver, store.knownProviders); err != nil {
+ return nil, fmt.Errorf("failed to configure providers: %w", err)
+ }
+
+ if !cfg.IsConfigured() {
+ slog.Warn("No providers configured")
+ return store, nil
+ }
+
+ if err := configureSelectedModels(store, store.knownProviders); err != nil {
+ return nil, fmt.Errorf("failed to configure selected models: %w", err)
+ }
+ store.SetupAgents()
+ return store, nil
```
This function is important because it defines how Crush Tutorial: Multi-Model Terminal Coding Agent with Strong Extensibility implements the patterns covered in this chapter.
-### `internal/agent/coordinator.go`
+### `internal/cmd/root.go`
-The `QueuedPrompts` function in [`internal/agent/coordinator.go`](https://github.com/charmbracelet/crush/blob/HEAD/internal/agent/coordinator.go) handles a key part of this chapter's functionality:
+The `init` function in [`internal/cmd/root.go`](https://github.com/charmbracelet/crush/blob/HEAD/internal/cmd/root.go) handles a key part of this chapter's functionality:
```go
- IsSessionBusy(sessionID string) bool
- IsBusy() bool
- QueuedPrompts(sessionID string) int
- QueuedPromptsList(sessionID string) []string
- ClearQueue(sessionID string)
- Summarize(context.Context, string) error
- Model() Model
- UpdateModels(ctx context.Context) error
-}
-
-type coordinator struct {
- cfg *config.ConfigStore
- sessions session.Service
- messages message.Service
- permissions permission.Service
- history history.Service
- filetracker filetracker.Service
- lspManager *lsp.Manager
- notify pubsub.Publisher[notify.Notification]
-
- currentAgent SessionAgent
- agents map[string]SessionAgent
-
- readyWg errgroup.Group
+var clientHost string
+
+func init() {
+ rootCmd.PersistentFlags().StringP("cwd", "c", "", "Current working directory")
+ rootCmd.PersistentFlags().StringP("data-dir", "D", "", "Custom crush data directory")
+ rootCmd.PersistentFlags().BoolP("debug", "d", false, "Debug")
+ rootCmd.PersistentFlags().StringVarP(&clientHost, "host", "H", server.DefaultHost(), "Connect to a specific crush server host (for advanced users)")
+ rootCmd.Flags().BoolP("help", "h", false, "Help")
+ rootCmd.Flags().BoolP("yolo", "y", false, "Automatically accept all permissions (dangerous mode)")
+ rootCmd.Flags().StringP("session", "s", "", "Continue a previous session by ID")
+ rootCmd.Flags().BoolP("continue", "C", false, "Continue the most recent session")
+ rootCmd.MarkFlagsMutuallyExclusive("session", "continue")
+
+ rootCmd.AddCommand(
+ runCmd,
+ dirsCmd,
+ projectsCmd,
+ updateProvidersCmd,
+ logsCmd,
+ schemaCmd,
+ loginCmd,
+ statsCmd,
+ sessionCmd,
+ )
}
-func NewCoordinator(
- ctx context.Context,
- cfg *config.ConfigStore,
- sessions session.Service,
- messages message.Service,
- permissions permission.Service,
+var rootCmd = &cobra.Command{
+ Use: "crush",
+ Short: "A terminal-first AI assistant for software development",
+ Long: "A glamorous, terminal-first AI assistant for software development and adjacent tasks",
+ Example: `
+# Run in interactive mode
```
This function is important because it defines how Crush Tutorial: Multi-Model Terminal Coding Agent with Strong Extensibility implements the patterns covered in this chapter.
-### `internal/agent/coordinator.go`
+### `internal/cmd/root.go`
-The `QueuedPromptsList` function in [`internal/agent/coordinator.go`](https://github.com/charmbracelet/crush/blob/HEAD/internal/agent/coordinator.go) handles a key part of this chapter's functionality:
+The `Execute` function in [`internal/cmd/root.go`](https://github.com/charmbracelet/crush/blob/HEAD/internal/cmd/root.go) handles a key part of this chapter's functionality:
```go
- IsBusy() bool
- QueuedPrompts(sessionID string) int
- QueuedPromptsList(sessionID string) []string
- ClearQueue(sessionID string)
- Summarize(context.Context, string) error
- Model() Model
- UpdateModels(ctx context.Context) error
-}
-
-type coordinator struct {
- cfg *config.ConfigStore
- sessions session.Service
- messages message.Service
- permissions permission.Service
- history history.Service
- filetracker filetracker.Service
- lspManager *lsp.Manager
- notify pubsub.Publisher[notify.Notification]
-
- currentAgent SessionAgent
- agents map[string]SessionAgent
-
- readyWg errgroup.Group
-}
-
-func NewCoordinator(
- ctx context.Context,
- cfg *config.ConfigStore,
- sessions session.Service,
- messages message.Service,
- permissions permission.Service,
- history history.Service,
+`
+
+func Execute() {
+ // FIXME: config.Load uses slog internally during provider resolution,
+ // but the file-based logger isn't set up until after config is loaded
+ // (because the log path depends on the data directory from config).
+ // This creates a window where slog calls in config.Load leak to
+ // stderr. We discard early logs here as a workaround. The proper
+ // fix is to remove slog calls from config.Load and have it return
+ // warnings/diagnostics instead of logging them as a side effect.
+ slog.SetDefault(slog.New(slog.DiscardHandler))
+
+ // NOTE: very hacky: we create a colorprofile writer with STDOUT, then make
+ // it forward to a bytes.Buffer, write the colored heartbit to it, and then
+ // finally prepend it in the version template.
+ // Unfortunately cobra doesn't give us a way to set a function to handle
+ // printing the version, and PreRunE runs after the version is already
+ // handled, so that doesn't work either.
+ // This is the only way I could find that works relatively well.
+ if term.IsTerminal(os.Stdout.Fd()) {
+ var b bytes.Buffer
+ w := colorprofile.NewWriter(os.Stdout, os.Environ())
+ w.Forward = &b
+ _, _ = w.WriteString(heartbit.String())
+ rootCmd.SetVersionTemplate(b.String() + "\n" + defaultVersionTemplate)
+ }
+ if err := fang.Execute(
+ context.Background(),
+ rootCmd,
+ fang.WithVersion(version.Version),
+ fang.WithNotifySignal(os.Interrupt),
+ ); err != nil {
```
This function is important because it defines how Crush Tutorial: Multi-Model Terminal Coding Agent with Strong Extensibility implements the patterns covered in this chapter.
@@ -240,11 +238,11 @@ This function is important because it defines how Crush Tutorial: Multi-Model Te
```mermaid
flowchart TD
- A[Model]
- B[UpdateModels]
- C[QueuedPrompts]
- D[QueuedPromptsList]
- E[Summarize]
+ A[ProjectSkillsDir]
+ B[isAppleTerminal]
+ C[init]
+ D[Execute]
+ E[supportsProgressBar]
A --> B
B --> C
C --> D
diff --git a/tutorials/crush-tutorial/06-skills-commands-and-workflow-customization.md b/tutorials/crush-tutorial/06-skills-commands-and-workflow-customization.md
index 4fc56107..fa50dece 100644
--- a/tutorials/crush-tutorial/06-skills-commands-and-workflow-customization.md
+++ b/tutorials/crush-tutorial/06-skills-commands-and-workflow-customization.md
@@ -57,170 +57,168 @@ You now have the building blocks for durable, reusable Crush workflows.
Next: [Chapter 7: Logs, Debugging, and Operations](07-logs-debugging-and-operations.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `internal/message/content.go`
+### `internal/workspace/client_workspace.go`
-The `AddImageURL` function in [`internal/message/content.go`](https://github.com/charmbracelet/crush/blob/HEAD/internal/message/content.go) handles a key part of this chapter's functionality:
+The `SetProviderAPIKey` function in [`internal/workspace/client_workspace.go`](https://github.com/charmbracelet/crush/blob/HEAD/internal/workspace/client_workspace.go) handles a key part of this chapter's functionality:
```go
}
-func (m *Message) AddImageURL(url, detail string) {
- m.Parts = append(m.Parts, ImageURLContent{URL: url, Detail: detail})
-}
-
-func (m *Message) AddBinary(mimeType string, data []byte) {
- m.Parts = append(m.Parts, BinaryContent{MIMEType: mimeType, Data: data})
-}
-
-func PromptWithTextAttachments(prompt string, attachments []Attachment) string {
- var sb strings.Builder
- sb.WriteString(prompt)
- addedAttachments := false
- for _, content := range attachments {
- if !content.IsText() {
- continue
- }
- if !addedAttachments {
- sb.WriteString("\n<system_info>The files below have been attached by the user, consider them in your response</system_info>\n")
- addedAttachments = true
- }
- if content.FilePath != "" {
- fmt.Fprintf(&sb, "<file path='%s'>\n", content.FilePath)
- } else {
- sb.WriteString("<file>\n")
- }
- sb.WriteString("\n")
- sb.Write(content.Content)
- sb.WriteString("\n</file>\n")
+func (w *ClientWorkspace) SetProviderAPIKey(scope config.Scope, providerID string, apiKey any) error {
+ err := w.client.SetProviderAPIKey(context.Background(), w.workspaceID(), scope, providerID, apiKey)
+ if err == nil {
+ w.refreshWorkspace()
+ }
+ return err
+}
+
+func (w *ClientWorkspace) SetConfigField(scope config.Scope, key string, value any) error {
+ err := w.client.SetConfigField(context.Background(), w.workspaceID(), scope, key, value)
+ if err == nil {
+ w.refreshWorkspace()
+ }
+ return err
+}
+
+func (w *ClientWorkspace) RemoveConfigField(scope config.Scope, key string) error {
+ err := w.client.RemoveConfigField(context.Background(), w.workspaceID(), scope, key)
+ if err == nil {
+ w.refreshWorkspace()
+ }
+ return err
+}
+
+func (w *ClientWorkspace) ImportCopilot() (*oauth.Token, bool) {
+ token, ok, err := w.client.ImportCopilot(context.Background(), w.workspaceID())
+ if err != nil {
+ return nil, false
}
- return sb.String()
+ if ok {
```
This function is important because it defines how Crush Tutorial: Multi-Model Terminal Coding Agent with Strong Extensibility implements the patterns covered in this chapter.
-### `internal/message/content.go`
+### `internal/workspace/client_workspace.go`
-The `AddBinary` function in [`internal/message/content.go`](https://github.com/charmbracelet/crush/blob/HEAD/internal/message/content.go) handles a key part of this chapter's functionality:
+The `SetConfigField` function in [`internal/workspace/client_workspace.go`](https://github.com/charmbracelet/crush/blob/HEAD/internal/workspace/client_workspace.go) handles a key part of this chapter's functionality:
```go
}
-func (m *Message) AddBinary(mimeType string, data []byte) {
- m.Parts = append(m.Parts, BinaryContent{MIMEType: mimeType, Data: data})
-}
-
-func PromptWithTextAttachments(prompt string, attachments []Attachment) string {
- var sb strings.Builder
- sb.WriteString(prompt)
- addedAttachments := false
- for _, content := range attachments {
- if !content.IsText() {
- continue
- }
- if !addedAttachments {
- sb.WriteString("\n<system_info>The files below have been attached by the user, consider them in your response</system_info>\n")
- addedAttachments = true
- }
- if content.FilePath != "" {
- fmt.Fprintf(&sb, "<file path='%s'>\n", content.FilePath)
- } else {
- sb.WriteString("<file>\n")
- }
- sb.WriteString("\n")
- sb.Write(content.Content)
- sb.WriteString("\n</file>\n")
+func (w *ClientWorkspace) SetConfigField(scope config.Scope, key string, value any) error {
+ err := w.client.SetConfigField(context.Background(), w.workspaceID(), scope, key, value)
+ if err == nil {
+ w.refreshWorkspace()
}
- return sb.String()
+ return err
}
-func (m *Message) ToAIMessage() []fantasy.Message {
- var messages []fantasy.Message
+func (w *ClientWorkspace) RemoveConfigField(scope config.Scope, key string) error {
+ err := w.client.RemoveConfigField(context.Background(), w.workspaceID(), scope, key)
+ if err == nil {
+ w.refreshWorkspace()
+ }
+ return err
+}
+
+func (w *ClientWorkspace) ImportCopilot() (*oauth.Token, bool) {
+ token, ok, err := w.client.ImportCopilot(context.Background(), w.workspaceID())
+ if err != nil {
+ return nil, false
+ }
+ if ok {
+ w.refreshWorkspace()
+ }
+ return token, ok
+}
+
+func (w *ClientWorkspace) RefreshOAuthToken(ctx context.Context, scope config.Scope, providerID string) error {
+ err := w.client.RefreshOAuthToken(ctx, w.workspaceID(), scope, providerID)
+ if err == nil {
```
This function is important because it defines how Crush Tutorial: Multi-Model Terminal Coding Agent with Strong Extensibility implements the patterns covered in this chapter.
-### `internal/message/content.go`
+### `internal/workspace/client_workspace.go`
-The `PromptWithTextAttachments` function in [`internal/message/content.go`](https://github.com/charmbracelet/crush/blob/HEAD/internal/message/content.go) handles a key part of this chapter's functionality:
+The `RemoveConfigField` function in [`internal/workspace/client_workspace.go`](https://github.com/charmbracelet/crush/blob/HEAD/internal/workspace/client_workspace.go) handles a key part of this chapter's functionality:
```go
}
-func PromptWithTextAttachments(prompt string, attachments []Attachment) string {
- var sb strings.Builder
- sb.WriteString(prompt)
- addedAttachments := false
- for _, content := range attachments {
- if !content.IsText() {
- continue
- }
- if !addedAttachments {
- sb.WriteString("\n<system_info>The files below have been attached by the user, consider them in your response</system_info>\n")
- addedAttachments = true
- }
- if content.FilePath != "" {
- fmt.Fprintf(&sb, "<file path='%s'>\n", content.FilePath)
- } else {
- sb.WriteString("<file>\n")
- }
- sb.WriteString("\n")
- sb.Write(content.Content)
- sb.WriteString("\n</file>\n")
+func (w *ClientWorkspace) RemoveConfigField(scope config.Scope, key string) error {
+ err := w.client.RemoveConfigField(context.Background(), w.workspaceID(), scope, key)
+ if err == nil {
+ w.refreshWorkspace()
}
- return sb.String()
+ return err
}
-func (m *Message) ToAIMessage() []fantasy.Message {
- var messages []fantasy.Message
- switch m.Role {
- case User:
- var parts []fantasy.MessagePart
- text := strings.TrimSpace(m.Content().Text)
+func (w *ClientWorkspace) ImportCopilot() (*oauth.Token, bool) {
+ token, ok, err := w.client.ImportCopilot(context.Background(), w.workspaceID())
+ if err != nil {
+ return nil, false
+ }
+ if ok {
+ w.refreshWorkspace()
+ }
+ return token, ok
+}
+
+func (w *ClientWorkspace) RefreshOAuthToken(ctx context.Context, scope config.Scope, providerID string) error {
+ err := w.client.RefreshOAuthToken(ctx, w.workspaceID(), scope, providerID)
+ if err == nil {
+ w.refreshWorkspace()
+ }
+ return err
+}
+
+// -- Project lifecycle --
+
+func (w *ClientWorkspace) ProjectNeedsInitialization() (bool, error) {
```
This function is important because it defines how Crush Tutorial: Multi-Model Terminal Coding Agent with Strong Extensibility implements the patterns covered in this chapter.
-### `internal/message/content.go`
+### `internal/workspace/client_workspace.go`
-The `ToAIMessage` function in [`internal/message/content.go`](https://github.com/charmbracelet/crush/blob/HEAD/internal/message/content.go) handles a key part of this chapter's functionality:
+The `ImportCopilot` function in [`internal/workspace/client_workspace.go`](https://github.com/charmbracelet/crush/blob/HEAD/internal/workspace/client_workspace.go) handles a key part of this chapter's functionality:
```go
}
-func (m *Message) ToAIMessage() []fantasy.Message {
- var messages []fantasy.Message
- switch m.Role {
- case User:
- var parts []fantasy.MessagePart
- text := strings.TrimSpace(m.Content().Text)
- var textAttachments []Attachment
- for _, content := range m.BinaryContent() {
- if !strings.HasPrefix(content.MIMEType, "text/") {
- continue
- }
- textAttachments = append(textAttachments, Attachment{
- FilePath: content.Path,
- MimeType: content.MIMEType,
- Content: content.Data,
- })
- }
- text = PromptWithTextAttachments(text, textAttachments)
- if text != "" {
- parts = append(parts, fantasy.TextPart{Text: text})
- }
- for _, content := range m.BinaryContent() {
- // skip text attachements
- if strings.HasPrefix(content.MIMEType, "text/") {
- continue
- }
- parts = append(parts, fantasy.FilePart{
- Filename: content.Path,
- Data: content.Data,
- MediaType: content.MIMEType,
+func (w *ClientWorkspace) ImportCopilot() (*oauth.Token, bool) {
+ token, ok, err := w.client.ImportCopilot(context.Background(), w.workspaceID())
+ if err != nil {
+ return nil, false
+ }
+ if ok {
+ w.refreshWorkspace()
+ }
+ return token, ok
+}
+
+func (w *ClientWorkspace) RefreshOAuthToken(ctx context.Context, scope config.Scope, providerID string) error {
+ err := w.client.RefreshOAuthToken(ctx, w.workspaceID(), scope, providerID)
+ if err == nil {
+ w.refreshWorkspace()
+ }
+ return err
+}
+
+// -- Project lifecycle --
+
+func (w *ClientWorkspace) ProjectNeedsInitialization() (bool, error) {
+ return w.client.ProjectNeedsInitialization(context.Background(), w.workspaceID())
+}
+
+func (w *ClientWorkspace) MarkProjectInitialized() error {
+ return w.client.MarkProjectInitialized(context.Background(), w.workspaceID())
+}
+
+func (w *ClientWorkspace) InitializePrompt() (string, error) {
```
This function is important because it defines how Crush Tutorial: Multi-Model Terminal Coding Agent with Strong Extensibility implements the patterns covered in this chapter.
@@ -230,11 +228,11 @@ This function is important because it defines how Crush Tutorial: Multi-Model Te
```mermaid
flowchart TD
- A[AddImageURL]
- B[AddBinary]
- C[PromptWithTextAttachments]
- D[ToAIMessage]
- E[NewManager]
+ A[SetProviderAPIKey]
+ B[SetConfigField]
+ C[RemoveConfigField]
+ D[ImportCopilot]
+ E[RefreshOAuthToken]
A --> B
B --> C
C --> D
diff --git a/tutorials/crush-tutorial/07-logs-debugging-and-operations.md b/tutorials/crush-tutorial/07-logs-debugging-and-operations.md
index 8caf6efa..c0429a58 100644
--- a/tutorials/crush-tutorial/07-logs-debugging-and-operations.md
+++ b/tutorials/crush-tutorial/07-logs-debugging-and-operations.md
@@ -49,170 +49,168 @@ You now have practical diagnostics and maintenance workflows for operating Crush
Next: [Chapter 8: Production Governance and Rollout](08-production-governance-and-rollout.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `internal/db/stats.sql.go`
+### `internal/server/config.go`
-The `GetTotalStats` function in [`internal/db/stats.sql.go`](https://github.com/charmbracelet/crush/blob/HEAD/internal/db/stats.sql.go) handles a key part of this chapter's functionality:
+The `handlePostWorkspaceConfigModel` function in [`internal/server/config.go`](https://github.com/charmbracelet/crush/blob/HEAD/internal/server/config.go) handles a key part of this chapter's functionality:
```go
}
-const getTotalStats = `-- name: GetTotalStats :one
-SELECT
- COUNT(*) as total_sessions,
- COALESCE(SUM(prompt_tokens), 0) as total_prompt_tokens,
- COALESCE(SUM(completion_tokens), 0) as total_completion_tokens,
- COALESCE(SUM(cost), 0) as total_cost,
- COALESCE(SUM(message_count), 0) as total_messages,
- COALESCE(AVG(prompt_tokens + completion_tokens), 0) as avg_tokens_per_session,
- COALESCE(AVG(message_count), 0) as avg_messages_per_session
-FROM sessions
-WHERE parent_session_id IS NULL
-`
-
-type GetTotalStatsRow struct {
- TotalSessions int64 `json:"total_sessions"`
- TotalPromptTokens interface{} `json:"total_prompt_tokens"`
- TotalCompletionTokens interface{} `json:"total_completion_tokens"`
- TotalCost interface{} `json:"total_cost"`
- TotalMessages interface{} `json:"total_messages"`
- AvgTokensPerSession interface{} `json:"avg_tokens_per_session"`
- AvgMessagesPerSession interface{} `json:"avg_messages_per_session"`
+// handlePostWorkspaceConfigModel updates the preferred model.
+//
+// @Summary Set the preferred model
+// @Tags config
+// @Accept json
+// @Param id path string true "Workspace ID"
+// @Param request body proto.ConfigModelRequest true "Config model request"
+// @Success 200
+// @Failure 400 {object} proto.Error
+// @Failure 404 {object} proto.Error
+// @Failure 500 {object} proto.Error
+// @Router /workspaces/{id}/config/model [post]
+func (c *controllerV1) handlePostWorkspaceConfigModel(w http.ResponseWriter, r *http.Request) {
+ id := r.PathValue("id")
+
+ var req proto.ConfigModelRequest
+ if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+ c.server.logError(r, "Failed to decode request", "error", err)
+ jsonError(w, http.StatusBadRequest, "failed to decode request")
+ return
+ }
+
+ if err := c.backend.UpdatePreferredModel(id, req.Scope, req.ModelType, req.Model); err != nil {
+ c.handleError(w, r, err)
+ return
+ }
+ w.WriteHeader(http.StatusOK)
}
-func (q *Queries) GetTotalStats(ctx context.Context) (GetTotalStatsRow, error) {
- row := q.queryRow(ctx, q.getTotalStatsStmt, getTotalStats)
- var i GetTotalStatsRow
- err := row.Scan(
- &i.TotalSessions,
- &i.TotalPromptTokens,
- &i.TotalCompletionTokens,
+// handlePostWorkspaceConfigCompact sets compact mode.
```
This function is important because it defines how Crush Tutorial: Multi-Model Terminal Coding Agent with Strong Extensibility implements the patterns covered in this chapter.
-### `internal/db/stats.sql.go`
+### `internal/server/config.go`
-The `GetUsageByDay` function in [`internal/db/stats.sql.go`](https://github.com/charmbracelet/crush/blob/HEAD/internal/db/stats.sql.go) handles a key part of this chapter's functionality:
+The `handlePostWorkspaceConfigCompact` function in [`internal/server/config.go`](https://github.com/charmbracelet/crush/blob/HEAD/internal/server/config.go) handles a key part of this chapter's functionality:
```go
}
-const getUsageByDay = `-- name: GetUsageByDay :many
-SELECT
- date(created_at, 'unixepoch') as day,
- SUM(prompt_tokens) as prompt_tokens,
- SUM(completion_tokens) as completion_tokens,
- SUM(cost) as cost,
- COUNT(*) as session_count
-FROM sessions
-WHERE parent_session_id IS NULL
-GROUP BY date(created_at, 'unixepoch')
-ORDER BY day DESC
-`
-
-type GetUsageByDayRow struct {
- Day interface{} `json:"day"`
- PromptTokens sql.NullFloat64 `json:"prompt_tokens"`
- CompletionTokens sql.NullFloat64 `json:"completion_tokens"`
- Cost sql.NullFloat64 `json:"cost"`
- SessionCount int64 `json:"session_count"`
-}
+// handlePostWorkspaceConfigCompact sets compact mode.
+//
+// @Summary Set compact mode
+// @Tags config
+// @Accept json
+// @Param id path string true "Workspace ID"
+// @Param request body proto.ConfigCompactRequest true "Config compact request"
+// @Success 200
+// @Failure 400 {object} proto.Error
+// @Failure 404 {object} proto.Error
+// @Failure 500 {object} proto.Error
+// @Router /workspaces/{id}/config/compact [post]
+func (c *controllerV1) handlePostWorkspaceConfigCompact(w http.ResponseWriter, r *http.Request) {
+ id := r.PathValue("id")
+
+ var req proto.ConfigCompactRequest
+ if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+ c.server.logError(r, "Failed to decode request", "error", err)
+ jsonError(w, http.StatusBadRequest, "failed to decode request")
+ return
+ }
-func (q *Queries) GetUsageByDay(ctx context.Context) ([]GetUsageByDayRow, error) {
- rows, err := q.query(ctx, q.getUsageByDayStmt, getUsageByDay)
- if err != nil {
- return nil, err
+ if err := c.backend.SetCompactMode(id, req.Scope, req.Enabled); err != nil {
+ c.handleError(w, r, err)
+ return
}
- defer rows.Close()
- items := []GetUsageByDayRow{}
- for rows.Next() {
- var i GetUsageByDayRow
+ w.WriteHeader(http.StatusOK)
+}
+
+// handlePostWorkspaceConfigProviderKey sets a provider API key.
```
This function is important because it defines how Crush Tutorial: Multi-Model Terminal Coding Agent with Strong Extensibility implements the patterns covered in this chapter.
-### `internal/db/stats.sql.go`
+### `internal/server/config.go`
-The `GetUsageByDayOfWeek` function in [`internal/db/stats.sql.go`](https://github.com/charmbracelet/crush/blob/HEAD/internal/db/stats.sql.go) handles a key part of this chapter's functionality:
+The `handlePostWorkspaceConfigProviderKey` function in [`internal/server/config.go`](https://github.com/charmbracelet/crush/blob/HEAD/internal/server/config.go) handles a key part of this chapter's functionality:
```go
}
-const getUsageByDayOfWeek = `-- name: GetUsageByDayOfWeek :many
-SELECT
- CAST(strftime('%w', created_at, 'unixepoch') AS INTEGER) as day_of_week,
- COUNT(*) as session_count,
- SUM(prompt_tokens) as prompt_tokens,
- SUM(completion_tokens) as completion_tokens
-FROM sessions
-WHERE parent_session_id IS NULL
-GROUP BY day_of_week
-ORDER BY day_of_week
-`
-
-type GetUsageByDayOfWeekRow struct {
- DayOfWeek int64 `json:"day_of_week"`
- SessionCount int64 `json:"session_count"`
- PromptTokens sql.NullFloat64 `json:"prompt_tokens"`
- CompletionTokens sql.NullFloat64 `json:"completion_tokens"`
-}
+// handlePostWorkspaceConfigProviderKey sets a provider API key.
+//
+// @Summary Set provider API key
+// @Tags config
+// @Accept json
+// @Param id path string true "Workspace ID"
+// @Param request body proto.ConfigProviderKeyRequest true "Config provider key request"
+// @Success 200
+// @Failure 400 {object} proto.Error
+// @Failure 404 {object} proto.Error
+// @Failure 500 {object} proto.Error
+// @Router /workspaces/{id}/config/provider-key [post]
+func (c *controllerV1) handlePostWorkspaceConfigProviderKey(w http.ResponseWriter, r *http.Request) {
+ id := r.PathValue("id")
+
+ var req proto.ConfigProviderKeyRequest
+ if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+ c.server.logError(r, "Failed to decode request", "error", err)
+ jsonError(w, http.StatusBadRequest, "failed to decode request")
+ return
+ }
-func (q *Queries) GetUsageByDayOfWeek(ctx context.Context) ([]GetUsageByDayOfWeekRow, error) {
- rows, err := q.query(ctx, q.getUsageByDayOfWeekStmt, getUsageByDayOfWeek)
- if err != nil {
- return nil, err
+ if err := c.backend.SetProviderAPIKey(id, req.Scope, req.ProviderID, req.APIKey); err != nil {
+ c.handleError(w, r, err)
+ return
}
- defer rows.Close()
- items := []GetUsageByDayOfWeekRow{}
- for rows.Next() {
- var i GetUsageByDayOfWeekRow
- if err := rows.Scan(
- &i.DayOfWeek,
+ w.WriteHeader(http.StatusOK)
+}
+
+// handlePostWorkspaceConfigImportCopilot imports Copilot credentials.
```
This function is important because it defines how Crush Tutorial: Multi-Model Terminal Coding Agent with Strong Extensibility implements the patterns covered in this chapter.
-### `internal/db/stats.sql.go`
+### `internal/server/config.go`
-The `GetUsageByHour` function in [`internal/db/stats.sql.go`](https://github.com/charmbracelet/crush/blob/HEAD/internal/db/stats.sql.go) handles a key part of this chapter's functionality:
+The `handlePostWorkspaceConfigImportCopilot` function in [`internal/server/config.go`](https://github.com/charmbracelet/crush/blob/HEAD/internal/server/config.go) handles a key part of this chapter's functionality:
```go
}
-const getUsageByHour = `-- name: GetUsageByHour :many
-SELECT
- CAST(strftime('%H', created_at, 'unixepoch') AS INTEGER) as hour,
- COUNT(*) as session_count
-FROM sessions
-WHERE parent_session_id IS NULL
-GROUP BY hour
-ORDER BY hour
-`
-
-type GetUsageByHourRow struct {
- Hour int64 `json:"hour"`
- SessionCount int64 `json:"session_count"`
-}
-
-func (q *Queries) GetUsageByHour(ctx context.Context) ([]GetUsageByHourRow, error) {
- rows, err := q.query(ctx, q.getUsageByHourStmt, getUsageByHour)
+// handlePostWorkspaceConfigImportCopilot imports Copilot credentials.
+//
+// @Summary Import Copilot credentials
+// @Tags config
+// @Produce json
+// @Param id path string true "Workspace ID"
+// @Success 200 {object} proto.ImportCopilotResponse
+// @Failure 404 {object} proto.Error
+// @Failure 500 {object} proto.Error
+// @Router /workspaces/{id}/config/import-copilot [post]
+func (c *controllerV1) handlePostWorkspaceConfigImportCopilot(w http.ResponseWriter, r *http.Request) {
+ id := r.PathValue("id")
+ token, ok, err := c.backend.ImportCopilot(id)
if err != nil {
- return nil, err
- }
- defer rows.Close()
- items := []GetUsageByHourRow{}
- for rows.Next() {
- var i GetUsageByHourRow
- if err := rows.Scan(&i.Hour, &i.SessionCount); err != nil {
- return nil, err
- }
- items = append(items, i)
+ c.handleError(w, r, err)
+ return
}
- if err := rows.Close(); err != nil {
+ jsonEncode(w, proto.ImportCopilotResponse{Token: token, Success: ok})
+}
+
+// handlePostWorkspaceConfigRefreshOAuth refreshes an OAuth token for a provider.
+//
+// @Summary Refresh OAuth token
+// @Tags config
+// @Accept json
+// @Param id path string true "Workspace ID"
+// @Param request body proto.ConfigRefreshOAuthRequest true "Refresh OAuth request"
+// @Success 200
+// @Failure 400 {object} proto.Error
+// @Failure 404 {object} proto.Error
```
This function is important because it defines how Crush Tutorial: Multi-Model Terminal Coding Agent with Strong Extensibility implements the patterns covered in this chapter.
@@ -222,11 +220,11 @@ This function is important because it defines how Crush Tutorial: Multi-Model Te
```mermaid
flowchart TD
- A[GetTotalStats]
- B[GetUsageByDay]
- C[GetUsageByDayOfWeek]
- D[GetUsageByHour]
- E[GetUsageByModel]
+ A[handlePostWorkspaceConfigModel]
+ B[handlePostWorkspaceConfigCompact]
+ C[handlePostWorkspaceConfigProviderKey]
+ D[handlePostWorkspaceConfigImportCopilot]
+ E[handlePostWorkspaceConfigRefreshOAuth]
A --> B
B --> C
C --> D
diff --git a/tutorials/crush-tutorial/08-production-governance-and-rollout.md b/tutorials/crush-tutorial/08-production-governance-and-rollout.md
index 2a115d6c..1c4e85f1 100644
--- a/tutorials/crush-tutorial/08-production-governance-and-rollout.md
+++ b/tutorials/crush-tutorial/08-production-governance-and-rollout.md
@@ -50,169 +50,168 @@ You now have an end-to-end framework for adopting Crush as a governed coding-age
Compare terminal-first practices in the [Goose Tutorial](../goose-tutorial/).
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `internal/session/session.go`
+### `internal/workspace/app_workspace.go`
-The `marshalTodos` function in [`internal/session/session.go`](https://github.com/charmbracelet/crush/blob/HEAD/internal/session/session.go) handles a key part of this chapter's functionality:
+The `PermissionGrant` function in [`internal/workspace/app_workspace.go`](https://github.com/charmbracelet/crush/blob/HEAD/internal/workspace/app_workspace.go) handles a key part of this chapter's functionality:
```go
+// -- Permissions --
+
+func (w *AppWorkspace) PermissionGrant(perm permission.PermissionRequest) {
+ w.app.Permissions.Grant(perm)
+}
+
+func (w *AppWorkspace) PermissionGrantPersistent(perm permission.PermissionRequest) {
+ w.app.Permissions.GrantPersistent(perm)
+}
+
+func (w *AppWorkspace) PermissionDeny(perm permission.PermissionRequest) {
+ w.app.Permissions.Deny(perm)
+}
+
+func (w *AppWorkspace) PermissionSkipRequests() bool {
+ return w.app.Permissions.SkipRequests()
+}
+
+func (w *AppWorkspace) PermissionSetSkipRequests(skip bool) {
+ w.app.Permissions.SetSkipRequests(skip)
+}
+
+// -- FileTracker --
+
+func (w *AppWorkspace) FileTrackerRecordRead(ctx context.Context, sessionID, path string) {
+ w.app.FileTracker.RecordRead(ctx, sessionID, path)
+}
+
+func (w *AppWorkspace) FileTrackerLastReadTime(ctx context.Context, sessionID, path string) time.Time {
+ return w.app.FileTracker.LastReadTime(ctx, sessionID, path)
+}
-func (s *service) Save(ctx context.Context, session Session) (Session, error) {
- todosJSON, err := marshalTodos(session.Todos)
- if err != nil {
- return Session{}, err
- }
-
- dbSession, err := s.q.UpdateSession(ctx, db.UpdateSessionParams{
- ID: session.ID,
- Title: session.Title,
- PromptTokens: session.PromptTokens,
- CompletionTokens: session.CompletionTokens,
- SummaryMessageID: sql.NullString{
- String: session.SummaryMessageID,
- Valid: session.SummaryMessageID != "",
- },
- Cost: session.Cost,
- Todos: sql.NullString{
- String: todosJSON,
- Valid: todosJSON != "",
- },
- })
- if err != nil {
- return Session{}, err
- }
- session = s.fromDBItem(dbSession)
- s.Publish(pubsub.UpdatedEvent, session)
- return session, nil
-}
-
-// UpdateTitleAndUsage updates only the title and usage fields atomically.
-// This is safer than fetching, modifying, and saving the entire session.
```
This function is important because it defines how Crush Tutorial: Multi-Model Terminal Coding Agent with Strong Extensibility implements the patterns covered in this chapter.
-### `internal/session/session.go`
+### `internal/workspace/app_workspace.go`
-The `unmarshalTodos` function in [`internal/session/session.go`](https://github.com/charmbracelet/crush/blob/HEAD/internal/session/session.go) handles a key part of this chapter's functionality:
+The `PermissionGrantPersistent` function in [`internal/workspace/app_workspace.go`](https://github.com/charmbracelet/crush/blob/HEAD/internal/workspace/app_workspace.go) handles a key part of this chapter's functionality:
```go
+}
+
+func (w *AppWorkspace) PermissionGrantPersistent(perm permission.PermissionRequest) {
+ w.app.Permissions.GrantPersistent(perm)
+}
+
+func (w *AppWorkspace) PermissionDeny(perm permission.PermissionRequest) {
+ w.app.Permissions.Deny(perm)
+}
+
+func (w *AppWorkspace) PermissionSkipRequests() bool {
+ return w.app.Permissions.SkipRequests()
+}
+
+func (w *AppWorkspace) PermissionSetSkipRequests(skip bool) {
+ w.app.Permissions.SetSkipRequests(skip)
+}
+
+// -- FileTracker --
-func (s service) fromDBItem(item db.Session) Session {
- todos, err := unmarshalTodos(item.Todos.String)
- if err != nil {
- slog.Error("Failed to unmarshal todos", "session_id", item.ID, "error", err)
- }
- return Session{
- ID: item.ID,
- ParentSessionID: item.ParentSessionID.String,
- Title: item.Title,
- MessageCount: item.MessageCount,
- PromptTokens: item.PromptTokens,
- CompletionTokens: item.CompletionTokens,
- SummaryMessageID: item.SummaryMessageID.String,
- Cost: item.Cost,
- Todos: todos,
- CreatedAt: item.CreatedAt,
- UpdatedAt: item.UpdatedAt,
- }
-}
-
-func marshalTodos(todos []Todo) (string, error) {
- if len(todos) == 0 {
- return "", nil
- }
- data, err := json.Marshal(todos)
- if err != nil {
- return "", err
- }
- return string(data), nil
+func (w *AppWorkspace) FileTrackerRecordRead(ctx context.Context, sessionID, path string) {
+ w.app.FileTracker.RecordRead(ctx, sessionID, path)
+}
+
+func (w *AppWorkspace) FileTrackerLastReadTime(ctx context.Context, sessionID, path string) time.Time {
+ return w.app.FileTracker.LastReadTime(ctx, sessionID, path)
+}
+
+func (w *AppWorkspace) FileTrackerListReadFiles(ctx context.Context, sessionID string) ([]string, error) {
+ return w.app.FileTracker.ListReadFiles(ctx, sessionID)
}
```
This function is important because it defines how Crush Tutorial: Multi-Model Terminal Coding Agent with Strong Extensibility implements the patterns covered in this chapter.
-### `internal/session/session.go`
+### `internal/workspace/app_workspace.go`
-The `NewService` function in [`internal/session/session.go`](https://github.com/charmbracelet/crush/blob/HEAD/internal/session/session.go) handles a key part of this chapter's functionality:
+The `PermissionDeny` function in [`internal/workspace/app_workspace.go`](https://github.com/charmbracelet/crush/blob/HEAD/internal/workspace/app_workspace.go) handles a key part of this chapter's functionality:
```go
}
-func NewService(q *db.Queries, conn *sql.DB) Service {
- broker := pubsub.NewBroker[Session]()
- return &service{
- Broker: broker,
- db: conn,
- q: q,
- }
+func (w *AppWorkspace) PermissionDeny(perm permission.PermissionRequest) {
+ w.app.Permissions.Deny(perm)
}
-// CreateAgentToolSessionID creates a session ID for agent tool sessions using the format "messageID$$toolCallID"
-func (s *service) CreateAgentToolSessionID(messageID, toolCallID string) string {
- return fmt.Sprintf("%s$$%s", messageID, toolCallID)
+func (w *AppWorkspace) PermissionSkipRequests() bool {
+ return w.app.Permissions.SkipRequests()
}
-// ParseAgentToolSessionID parses an agent tool session ID into its components
-func (s *service) ParseAgentToolSessionID(sessionID string) (messageID string, toolCallID string, ok bool) {
- parts := strings.Split(sessionID, "$$")
- if len(parts) != 2 {
- return "", "", false
- }
- return parts[0], parts[1], true
+func (w *AppWorkspace) PermissionSetSkipRequests(skip bool) {
+ w.app.Permissions.SetSkipRequests(skip)
+}
+
+// -- FileTracker --
+
+func (w *AppWorkspace) FileTrackerRecordRead(ctx context.Context, sessionID, path string) {
+ w.app.FileTracker.RecordRead(ctx, sessionID, path)
}
-// IsAgentToolSession checks if a session ID follows the agent tool session format
-func (s *service) IsAgentToolSession(sessionID string) bool {
- _, _, ok := s.ParseAgentToolSessionID(sessionID)
- return ok
+func (w *AppWorkspace) FileTrackerLastReadTime(ctx context.Context, sessionID, path string) time.Time {
+ return w.app.FileTracker.LastReadTime(ctx, sessionID, path)
}
+func (w *AppWorkspace) FileTrackerListReadFiles(ctx context.Context, sessionID string) ([]string, error) {
+ return w.app.FileTracker.ListReadFiles(ctx, sessionID)
+}
+
+// -- History --
+
+func (w *AppWorkspace) ListSessionHistory(ctx context.Context, sessionID string) ([]history.File, error) {
+ return w.app.History.ListBySession(ctx, sessionID)
```
This function is important because it defines how Crush Tutorial: Multi-Model Terminal Coding Agent with Strong Extensibility implements the patterns covered in this chapter.
-### `internal/session/session.go`
+### `internal/workspace/app_workspace.go`
-The `CreateAgentToolSessionID` function in [`internal/session/session.go`](https://github.com/charmbracelet/crush/blob/HEAD/internal/session/session.go) handles a key part of this chapter's functionality:
+The `PermissionSkipRequests` function in [`internal/workspace/app_workspace.go`](https://github.com/charmbracelet/crush/blob/HEAD/internal/workspace/app_workspace.go) handles a key part of this chapter's functionality:
```go
+}
+
+func (w *AppWorkspace) PermissionSkipRequests() bool {
+ return w.app.Permissions.SkipRequests()
+}
+
+func (w *AppWorkspace) PermissionSetSkipRequests(skip bool) {
+ w.app.Permissions.SetSkipRequests(skip)
+}
+
+// -- FileTracker --
+
+func (w *AppWorkspace) FileTrackerRecordRead(ctx context.Context, sessionID, path string) {
+ w.app.FileTracker.RecordRead(ctx, sessionID, path)
+}
+
+func (w *AppWorkspace) FileTrackerLastReadTime(ctx context.Context, sessionID, path string) time.Time {
+ return w.app.FileTracker.LastReadTime(ctx, sessionID, path)
+}
+
+func (w *AppWorkspace) FileTrackerListReadFiles(ctx context.Context, sessionID string) ([]string, error) {
+ return w.app.FileTracker.ListReadFiles(ctx, sessionID)
+}
+
+// -- History --
+
+func (w *AppWorkspace) ListSessionHistory(ctx context.Context, sessionID string) ([]history.File, error) {
+ return w.app.History.ListBySession(ctx, sessionID)
+}
+
+// -- LSP --
- // Agent tool session management
- CreateAgentToolSessionID(messageID, toolCallID string) string
- ParseAgentToolSessionID(sessionID string) (messageID string, toolCallID string, ok bool)
- IsAgentToolSession(sessionID string) bool
-}
-
-type service struct {
- *pubsub.Broker[Session]
- db *sql.DB
- q *db.Queries
-}
-
-func (s *service) Create(ctx context.Context, title string) (Session, error) {
- dbSession, err := s.q.CreateSession(ctx, db.CreateSessionParams{
- ID: uuid.New().String(),
- Title: title,
- })
- if err != nil {
- return Session{}, err
- }
- session := s.fromDBItem(dbSession)
- s.Publish(pubsub.CreatedEvent, session)
- event.SessionCreated()
- return session, nil
-}
-
-func (s *service) CreateTaskSession(ctx context.Context, toolCallID, parentSessionID, title string) (Session, error) {
- dbSession, err := s.q.CreateSession(ctx, db.CreateSessionParams{
- ID: toolCallID,
- ParentSessionID: sql.NullString{String: parentSessionID, Valid: true},
- Title: title,
```
This function is important because it defines how Crush Tutorial: Multi-Model Terminal Coding Agent with Strong Extensibility implements the patterns covered in this chapter.
@@ -222,11 +221,11 @@ This function is important because it defines how Crush Tutorial: Multi-Model Te
```mermaid
flowchart TD
- A[marshalTodos]
- B[unmarshalTodos]
- C[NewService]
- D[CreateAgentToolSessionID]
- E[ParseAgentToolSessionID]
+ A[PermissionGrant]
+ B[PermissionGrantPersistent]
+ C[PermissionDeny]
+ D[PermissionSkipRequests]
+ E[PermissionSetSkipRequests]
A --> B
B --> C
C --> D
diff --git a/tutorials/daytona-tutorial/01-getting-started.md b/tutorials/daytona-tutorial/01-getting-started.md
index 19d78c06..b108e522 100644
--- a/tutorials/daytona-tutorial/01-getting-started.md
+++ b/tutorials/daytona-tutorial/01-getting-started.md
@@ -41,186 +41,15 @@ You now have a working Daytona baseline with authenticated access and first code
Next: [Chapter 2: Sandbox Lifecycle, Resources, and Regions](02-sandbox-lifecycle-resources-and-regions.md)
-## Depth Expansion Playbook
-
-## Source Code Walkthrough
-
-### `libs/api-client-go/api_snapshots.go`
-
-The `XDaytonaOrganizationID` function in [`libs/api-client-go/api_snapshots.go`](https://github.com/daytonaio/daytona/blob/HEAD/libs/api-client-go/api_snapshots.go) handles a key part of this chapter's functionality:
-
-```go
-
-// Use with JWT to specify the organization ID
-func (r SnapshotsAPIActivateSnapshotRequest) XDaytonaOrganizationID(xDaytonaOrganizationID string) SnapshotsAPIActivateSnapshotRequest {
- r.xDaytonaOrganizationID = &xDaytonaOrganizationID
- return r
-}
-
-func (r SnapshotsAPIActivateSnapshotRequest) Execute() (*SnapshotDto, *http.Response, error) {
- return r.ApiService.ActivateSnapshotExecute(r)
-}
-
-/*
-ActivateSnapshot Activate a snapshot
-
- @param ctx context.Context - for authentication, logging, cancellation, deadlines, tracing, etc. Passed from http.Request or context.Background().
- @param id Snapshot ID
- @return SnapshotsAPIActivateSnapshotRequest
-*/
-func (a *SnapshotsAPIService) ActivateSnapshot(ctx context.Context, id string) SnapshotsAPIActivateSnapshotRequest {
- return SnapshotsAPIActivateSnapshotRequest{
- ApiService: a,
- ctx: ctx,
- id: id,
- }
-}
-
-// Execute executes the request
-// @return SnapshotDto
-func (a *SnapshotsAPIService) ActivateSnapshotExecute(r SnapshotsAPIActivateSnapshotRequest) (*SnapshotDto, *http.Response, error) {
- var (
- localVarHTTPMethod = http.MethodPost
- localVarPostBody interface{}
-```
-
-This function is important because it defines how Daytona Tutorial: Secure Sandbox Infrastructure for AI-Generated Code implements the patterns covered in this chapter.
-
-### `libs/api-client-go/api_snapshots.go`
-
-The `Execute` function in [`libs/api-client-go/api_snapshots.go`](https://github.com/daytonaio/daytona/blob/HEAD/libs/api-client-go/api_snapshots.go) handles a key part of this chapter's functionality:
-
-```go
- ActivateSnapshot(ctx context.Context, id string) SnapshotsAPIActivateSnapshotRequest
-
- // ActivateSnapshotExecute executes the request
- // @return SnapshotDto
- ActivateSnapshotExecute(r SnapshotsAPIActivateSnapshotRequest) (*SnapshotDto, *http.Response, error)
-
- /*
- CanCleanupImage Check if an image can be cleaned up
-
- @param ctx context.Context - for authentication, logging, cancellation, deadlines, tracing, etc. Passed from http.Request or context.Background().
- @return SnapshotsAPICanCleanupImageRequest
- */
- CanCleanupImage(ctx context.Context) SnapshotsAPICanCleanupImageRequest
-
- // CanCleanupImageExecute executes the request
- // @return bool
- CanCleanupImageExecute(r SnapshotsAPICanCleanupImageRequest) (bool, *http.Response, error)
-
- /*
- CreateSnapshot Create a new snapshot
-
- @param ctx context.Context - for authentication, logging, cancellation, deadlines, tracing, etc. Passed from http.Request or context.Background().
- @return SnapshotsAPICreateSnapshotRequest
- */
- CreateSnapshot(ctx context.Context) SnapshotsAPICreateSnapshotRequest
-
- // CreateSnapshotExecute executes the request
- // @return SnapshotDto
- CreateSnapshotExecute(r SnapshotsAPICreateSnapshotRequest) (*SnapshotDto, *http.Response, error)
-
- /*
- DeactivateSnapshot Deactivate a snapshot
-```
-
-This function is important because it defines how Daytona Tutorial: Secure Sandbox Infrastructure for AI-Generated Code implements the patterns covered in this chapter.
-
-### `libs/api-client-go/api_snapshots.go`
-
-The `ActivateSnapshot` function in [`libs/api-client-go/api_snapshots.go`](https://github.com/daytonaio/daytona/blob/HEAD/libs/api-client-go/api_snapshots.go) handles a key part of this chapter's functionality:
-
-```go
-
- /*
- ActivateSnapshot Activate a snapshot
-
- @param ctx context.Context - for authentication, logging, cancellation, deadlines, tracing, etc. Passed from http.Request or context.Background().
- @param id Snapshot ID
- @return SnapshotsAPIActivateSnapshotRequest
- */
- ActivateSnapshot(ctx context.Context, id string) SnapshotsAPIActivateSnapshotRequest
-
- // ActivateSnapshotExecute executes the request
- // @return SnapshotDto
- ActivateSnapshotExecute(r SnapshotsAPIActivateSnapshotRequest) (*SnapshotDto, *http.Response, error)
-
- /*
- CanCleanupImage Check if an image can be cleaned up
-
- @param ctx context.Context - for authentication, logging, cancellation, deadlines, tracing, etc. Passed from http.Request or context.Background().
- @return SnapshotsAPICanCleanupImageRequest
- */
- CanCleanupImage(ctx context.Context) SnapshotsAPICanCleanupImageRequest
-
- // CanCleanupImageExecute executes the request
- // @return bool
- CanCleanupImageExecute(r SnapshotsAPICanCleanupImageRequest) (bool, *http.Response, error)
-
- /*
- CreateSnapshot Create a new snapshot
-
- @param ctx context.Context - for authentication, logging, cancellation, deadlines, tracing, etc. Passed from http.Request or context.Background().
- @return SnapshotsAPICreateSnapshotRequest
- */
-```
-
-This function is important because it defines how Daytona Tutorial: Secure Sandbox Infrastructure for AI-Generated Code implements the patterns covered in this chapter.
-
-### `libs/api-client-go/api_snapshots.go`
-
-The `ActivateSnapshotExecute` function in [`libs/api-client-go/api_snapshots.go`](https://github.com/daytonaio/daytona/blob/HEAD/libs/api-client-go/api_snapshots.go) handles a key part of this chapter's functionality:
-
-```go
- ActivateSnapshot(ctx context.Context, id string) SnapshotsAPIActivateSnapshotRequest
-
- // ActivateSnapshotExecute executes the request
- // @return SnapshotDto
- ActivateSnapshotExecute(r SnapshotsAPIActivateSnapshotRequest) (*SnapshotDto, *http.Response, error)
-
- /*
- CanCleanupImage Check if an image can be cleaned up
-
- @param ctx context.Context - for authentication, logging, cancellation, deadlines, tracing, etc. Passed from http.Request or context.Background().
- @return SnapshotsAPICanCleanupImageRequest
- */
- CanCleanupImage(ctx context.Context) SnapshotsAPICanCleanupImageRequest
-
- // CanCleanupImageExecute executes the request
- // @return bool
- CanCleanupImageExecute(r SnapshotsAPICanCleanupImageRequest) (bool, *http.Response, error)
-
- /*
- CreateSnapshot Create a new snapshot
-
- @param ctx context.Context - for authentication, logging, cancellation, deadlines, tracing, etc. Passed from http.Request or context.Background().
- @return SnapshotsAPICreateSnapshotRequest
- */
- CreateSnapshot(ctx context.Context) SnapshotsAPICreateSnapshotRequest
-
- // CreateSnapshotExecute executes the request
- // @return SnapshotDto
- CreateSnapshotExecute(r SnapshotsAPICreateSnapshotRequest) (*SnapshotDto, *http.Response, error)
-
- /*
- DeactivateSnapshot Deactivate a snapshot
-```
-
-This function is important because it defines how Daytona Tutorial: Secure Sandbox Infrastructure for AI-Generated Code implements the patterns covered in this chapter.
-
-
## How These Components Connect
```mermaid
flowchart TD
- A[XDaytonaOrganizationID]
- B[Execute]
- C[ActivateSnapshot]
- D[ActivateSnapshotExecute]
- E[ImageName]
- A --> B
- B --> C
- C --> D
- D --> E
+ A[Developer / AI Agent] --> B[Daytona CLI or SDK]
+ B --> C{Authentication}
+ C -->|API Key| D[Daytona API]
+ D --> E[Create Sandbox]
+ E --> F[Running Container]
+ F --> G[Execute Code]
+ G --> H[Return Output]
```
diff --git a/tutorials/daytona-tutorial/02-sandbox-lifecycle-resources-and-regions.md b/tutorials/daytona-tutorial/02-sandbox-lifecycle-resources-and-regions.md
index 0a4eaa89..c6dea8b0 100644
--- a/tutorials/daytona-tutorial/02-sandbox-lifecycle-resources-and-regions.md
+++ b/tutorials/daytona-tutorial/02-sandbox-lifecycle-resources-and-regions.md
@@ -37,186 +37,16 @@ You now understand how to shape sandbox lifecycle and resource policy around rea
Next: [Chapter 3: Process and Code Execution Patterns](03-process-and-code-execution-patterns.md)
-## Depth Expansion Playbook
-
-## Source Code Walkthrough
-
-### `libs/api-client-go/api_runners.go`
-
-The `XDaytonaOrganizationID` function in [`libs/api-client-go/api_runners.go`](https://github.com/daytonaio/daytona/blob/HEAD/libs/api-client-go/api_runners.go) handles a key part of this chapter's functionality:
-
-```go
-
-// Use with JWT to specify the organization ID
-func (r RunnersAPICreateRunnerRequest) XDaytonaOrganizationID(xDaytonaOrganizationID string) RunnersAPICreateRunnerRequest {
- r.xDaytonaOrganizationID = &xDaytonaOrganizationID
- return r
-}
-
-func (r RunnersAPICreateRunnerRequest) Execute() (*CreateRunnerResponse, *http.Response, error) {
- return r.ApiService.CreateRunnerExecute(r)
-}
-
-/*
-CreateRunner Create runner
-
- @param ctx context.Context - for authentication, logging, cancellation, deadlines, tracing, etc. Passed from http.Request or context.Background().
- @return RunnersAPICreateRunnerRequest
-*/
-func (a *RunnersAPIService) CreateRunner(ctx context.Context) RunnersAPICreateRunnerRequest {
- return RunnersAPICreateRunnerRequest{
- ApiService: a,
- ctx: ctx,
- }
-}
-
-// Execute executes the request
-// @return CreateRunnerResponse
-func (a *RunnersAPIService) CreateRunnerExecute(r RunnersAPICreateRunnerRequest) (*CreateRunnerResponse, *http.Response, error) {
- var (
- localVarHTTPMethod = http.MethodPost
- localVarPostBody interface{}
- formFiles []formFile
- localVarReturnValue *CreateRunnerResponse
-```
-
-This function is important because it defines how Daytona Tutorial: Secure Sandbox Infrastructure for AI-Generated Code implements the patterns covered in this chapter.
-
-### `libs/api-client-go/api_runners.go`
-
-The `Execute` function in [`libs/api-client-go/api_runners.go`](https://github.com/daytonaio/daytona/blob/HEAD/libs/api-client-go/api_runners.go) handles a key part of this chapter's functionality:
-
-```go
- CreateRunner(ctx context.Context) RunnersAPICreateRunnerRequest
-
- // CreateRunnerExecute executes the request
- // @return CreateRunnerResponse
- CreateRunnerExecute(r RunnersAPICreateRunnerRequest) (*CreateRunnerResponse, *http.Response, error)
-
- /*
- DeleteRunner Delete runner
-
- @param ctx context.Context - for authentication, logging, cancellation, deadlines, tracing, etc. Passed from http.Request or context.Background().
- @param id Runner ID
- @return RunnersAPIDeleteRunnerRequest
- */
- DeleteRunner(ctx context.Context, id string) RunnersAPIDeleteRunnerRequest
-
- // DeleteRunnerExecute executes the request
- DeleteRunnerExecute(r RunnersAPIDeleteRunnerRequest) (*http.Response, error)
-
- /*
- GetInfoForAuthenticatedRunner Get info for authenticated runner
-
- @param ctx context.Context - for authentication, logging, cancellation, deadlines, tracing, etc. Passed from http.Request or context.Background().
- @return RunnersAPIGetInfoForAuthenticatedRunnerRequest
- */
- GetInfoForAuthenticatedRunner(ctx context.Context) RunnersAPIGetInfoForAuthenticatedRunnerRequest
-
- // GetInfoForAuthenticatedRunnerExecute executes the request
- // @return RunnerFull
- GetInfoForAuthenticatedRunnerExecute(r RunnersAPIGetInfoForAuthenticatedRunnerRequest) (*RunnerFull, *http.Response, error)
-
- /*
- GetRunnerById Get runner by ID
-```
-
-This function is important because it defines how Daytona Tutorial: Secure Sandbox Infrastructure for AI-Generated Code implements the patterns covered in this chapter.
-
-### `libs/api-client-go/api_runners.go`
-
-The `CreateRunner` function in [`libs/api-client-go/api_runners.go`](https://github.com/daytonaio/daytona/blob/HEAD/libs/api-client-go/api_runners.go) handles a key part of this chapter's functionality:
-
-```go
-
- /*
- CreateRunner Create runner
-
- @param ctx context.Context - for authentication, logging, cancellation, deadlines, tracing, etc. Passed from http.Request or context.Background().
- @return RunnersAPICreateRunnerRequest
- */
- CreateRunner(ctx context.Context) RunnersAPICreateRunnerRequest
-
- // CreateRunnerExecute executes the request
- // @return CreateRunnerResponse
- CreateRunnerExecute(r RunnersAPICreateRunnerRequest) (*CreateRunnerResponse, *http.Response, error)
-
- /*
- DeleteRunner Delete runner
-
- @param ctx context.Context - for authentication, logging, cancellation, deadlines, tracing, etc. Passed from http.Request or context.Background().
- @param id Runner ID
- @return RunnersAPIDeleteRunnerRequest
- */
- DeleteRunner(ctx context.Context, id string) RunnersAPIDeleteRunnerRequest
-
- // DeleteRunnerExecute executes the request
- DeleteRunnerExecute(r RunnersAPIDeleteRunnerRequest) (*http.Response, error)
-
- /*
- GetInfoForAuthenticatedRunner Get info for authenticated runner
-
- @param ctx context.Context - for authentication, logging, cancellation, deadlines, tracing, etc. Passed from http.Request or context.Background().
- @return RunnersAPIGetInfoForAuthenticatedRunnerRequest
- */
- GetInfoForAuthenticatedRunner(ctx context.Context) RunnersAPIGetInfoForAuthenticatedRunnerRequest
-```
-
-This function is important because it defines how Daytona Tutorial: Secure Sandbox Infrastructure for AI-Generated Code implements the patterns covered in this chapter.
-
-### `libs/api-client-go/api_runners.go`
-
-The `CreateRunnerExecute` function in [`libs/api-client-go/api_runners.go`](https://github.com/daytonaio/daytona/blob/HEAD/libs/api-client-go/api_runners.go) handles a key part of this chapter's functionality:
-
-```go
- CreateRunner(ctx context.Context) RunnersAPICreateRunnerRequest
-
- // CreateRunnerExecute executes the request
- // @return CreateRunnerResponse
- CreateRunnerExecute(r RunnersAPICreateRunnerRequest) (*CreateRunnerResponse, *http.Response, error)
-
- /*
- DeleteRunner Delete runner
-
- @param ctx context.Context - for authentication, logging, cancellation, deadlines, tracing, etc. Passed from http.Request or context.Background().
- @param id Runner ID
- @return RunnersAPIDeleteRunnerRequest
- */
- DeleteRunner(ctx context.Context, id string) RunnersAPIDeleteRunnerRequest
-
- // DeleteRunnerExecute executes the request
- DeleteRunnerExecute(r RunnersAPIDeleteRunnerRequest) (*http.Response, error)
-
- /*
- GetInfoForAuthenticatedRunner Get info for authenticated runner
-
- @param ctx context.Context - for authentication, logging, cancellation, deadlines, tracing, etc. Passed from http.Request or context.Background().
- @return RunnersAPIGetInfoForAuthenticatedRunnerRequest
- */
- GetInfoForAuthenticatedRunner(ctx context.Context) RunnersAPIGetInfoForAuthenticatedRunnerRequest
-
- // GetInfoForAuthenticatedRunnerExecute executes the request
- // @return RunnerFull
- GetInfoForAuthenticatedRunnerExecute(r RunnersAPIGetInfoForAuthenticatedRunnerRequest) (*RunnerFull, *http.Response, error)
-
- /*
- GetRunnerById Get runner by ID
-```
-
-This function is important because it defines how Daytona Tutorial: Secure Sandbox Infrastructure for AI-Generated Code implements the patterns covered in this chapter.
-
-
## How These Components Connect
```mermaid
flowchart TD
- A[XDaytonaOrganizationID]
- B[Execute]
- C[CreateRunner]
- D[CreateRunnerExecute]
- E[XDaytonaOrganizationID]
- A --> B
- B --> C
- C --> D
- D --> E
+ A[Sandbox Created] --> B{State}
+ B -->|Active| C[running]
+ B -->|Idle| D[stopped]
+ B -->|Done| E[archived/deleted]
+ C --> F[Consumes CPU/RAM quota]
+ D --> G[Minimal quota use]
+ H[Snapshot] --> A
+ I[Region selection] --> A
```
diff --git a/tutorials/daytona-tutorial/03-process-and-code-execution-patterns.md b/tutorials/daytona-tutorial/03-process-and-code-execution-patterns.md
index e50726fd..a54b8894 100644
--- a/tutorials/daytona-tutorial/03-process-and-code-execution-patterns.md
+++ b/tutorials/daytona-tutorial/03-process-and-code-execution-patterns.md
@@ -37,186 +37,15 @@ You now have an execution model that balances speed, isolation, and observabilit
Next: [Chapter 4: File, Git, and Preview Workflows](04-file-git-and-preview-workflows.md)
-## Depth Expansion Playbook
-
-## Source Code Walkthrough
-
-### `libs/api-client-go/model_workspace.go`
-
-The `GetNameOk` function in [`libs/api-client-go/model_workspace.go`](https://github.com/daytonaio/daytona/blob/HEAD/libs/api-client-go/model_workspace.go) handles a key part of this chapter's functionality:
-
-```go
-}
-
-// GetNameOk returns a tuple with the Name field value
-// and a boolean to check if the value has been set.
-func (o *Workspace) GetNameOk() (*string, bool) {
- if o == nil {
- return nil, false
- }
- return &o.Name, true
-}
-
-// SetName sets field value
-func (o *Workspace) SetName(v string) {
- o.Name = v
-}
-
-// GetSnapshot returns the Snapshot field value if set, zero value otherwise.
-func (o *Workspace) GetSnapshot() string {
- if o == nil || IsNil(o.Snapshot) {
- var ret string
- return ret
- }
- return *o.Snapshot
-}
-
-// GetSnapshotOk returns a tuple with the Snapshot field value if set, nil otherwise
-// and a boolean to check if the value has been set.
-func (o *Workspace) GetSnapshotOk() (*string, bool) {
- if o == nil || IsNil(o.Snapshot) {
- return nil, false
- }
- return o.Snapshot, true
-```
-
-This function is important because it defines how Daytona Tutorial: Secure Sandbox Infrastructure for AI-Generated Code implements the patterns covered in this chapter.
-
-### `libs/api-client-go/model_workspace.go`
-
-The `SetName` function in [`libs/api-client-go/model_workspace.go`](https://github.com/daytonaio/daytona/blob/HEAD/libs/api-client-go/model_workspace.go) handles a key part of this chapter's functionality:
-
-```go
-}
-
-// SetName sets field value
-func (o *Workspace) SetName(v string) {
- o.Name = v
-}
-
-// GetSnapshot returns the Snapshot field value if set, zero value otherwise.
-func (o *Workspace) GetSnapshot() string {
- if o == nil || IsNil(o.Snapshot) {
- var ret string
- return ret
- }
- return *o.Snapshot
-}
-
-// GetSnapshotOk returns a tuple with the Snapshot field value if set, nil otherwise
-// and a boolean to check if the value has been set.
-func (o *Workspace) GetSnapshotOk() (*string, bool) {
- if o == nil || IsNil(o.Snapshot) {
- return nil, false
- }
- return o.Snapshot, true
-}
-
-// HasSnapshot returns a boolean if a field has been set.
-func (o *Workspace) HasSnapshot() bool {
- if o != nil && !IsNil(o.Snapshot) {
- return true
- }
-
- return false
-```
-
-This function is important because it defines how Daytona Tutorial: Secure Sandbox Infrastructure for AI-Generated Code implements the patterns covered in this chapter.
-
-### `libs/api-client-go/model_workspace.go`
-
-The `GetSnapshot` function in [`libs/api-client-go/model_workspace.go`](https://github.com/daytonaio/daytona/blob/HEAD/libs/api-client-go/model_workspace.go) handles a key part of this chapter's functionality:
-
-```go
-}
-
-// GetSnapshot returns the Snapshot field value if set, zero value otherwise.
-func (o *Workspace) GetSnapshot() string {
- if o == nil || IsNil(o.Snapshot) {
- var ret string
- return ret
- }
- return *o.Snapshot
-}
-
-// GetSnapshotOk returns a tuple with the Snapshot field value if set, nil otherwise
-// and a boolean to check if the value has been set.
-func (o *Workspace) GetSnapshotOk() (*string, bool) {
- if o == nil || IsNil(o.Snapshot) {
- return nil, false
- }
- return o.Snapshot, true
-}
-
-// HasSnapshot returns a boolean if a field has been set.
-func (o *Workspace) HasSnapshot() bool {
- if o != nil && !IsNil(o.Snapshot) {
- return true
- }
-
- return false
-}
-
-// SetSnapshot gets a reference to the given string and assigns it to the Snapshot field.
-func (o *Workspace) SetSnapshot(v string) {
- o.Snapshot = &v
-```
-
-This function is important because it defines how Daytona Tutorial: Secure Sandbox Infrastructure for AI-Generated Code implements the patterns covered in this chapter.
-
-### `libs/api-client-go/model_workspace.go`
-
-The `GetSnapshotOk` function in [`libs/api-client-go/model_workspace.go`](https://github.com/daytonaio/daytona/blob/HEAD/libs/api-client-go/model_workspace.go) handles a key part of this chapter's functionality:
-
-```go
-}
-
-// GetSnapshotOk returns a tuple with the Snapshot field value if set, nil otherwise
-// and a boolean to check if the value has been set.
-func (o *Workspace) GetSnapshotOk() (*string, bool) {
- if o == nil || IsNil(o.Snapshot) {
- return nil, false
- }
- return o.Snapshot, true
-}
-
-// HasSnapshot returns a boolean if a field has been set.
-func (o *Workspace) HasSnapshot() bool {
- if o != nil && !IsNil(o.Snapshot) {
- return true
- }
-
- return false
-}
-
-// SetSnapshot gets a reference to the given string and assigns it to the Snapshot field.
-func (o *Workspace) SetSnapshot(v string) {
- o.Snapshot = &v
-}
-
-// GetUser returns the User field value
-func (o *Workspace) GetUser() string {
- if o == nil {
- var ret string
- return ret
- }
-
-```
-
-This function is important because it defines how Daytona Tutorial: Secure Sandbox Infrastructure for AI-Generated Code implements the patterns covered in this chapter.
-
-
## How These Components Connect
```mermaid
flowchart TD
- A[GetNameOk]
- B[SetName]
- C[GetSnapshot]
- D[GetSnapshotOk]
- E[HasSnapshot]
- A --> B
- B --> C
- C --> D
- D --> E
+ A[SDK / CLI Call] --> B[Daytona Toolbox API]
+ B --> C{Execution type}
+ C -->|code_run| D[Language runtime in sandbox]
+ C -->|execute_command| E[Shell in sandbox]
+ D --> F[stdout / stderr / exit code]
+ E --> F
+ F --> G[Returned to caller]
```
diff --git a/tutorials/daytona-tutorial/04-file-git-and-preview-workflows.md b/tutorials/daytona-tutorial/04-file-git-and-preview-workflows.md
index e1bef4ad..0618266a 100644
--- a/tutorials/daytona-tutorial/04-file-git-and-preview-workflows.md
+++ b/tutorials/daytona-tutorial/04-file-git-and-preview-workflows.md
@@ -37,186 +37,15 @@ You can now run a full code-to-preview loop inside Daytona with cleaner automati
Next: [Chapter 5: MCP Agent Integration and Tooling](05-mcp-agent-integration-and-tooling.md)
-## Depth Expansion Playbook
-
-## Source Code Walkthrough
-
-### `libs/api-client-go/model_workspace.go`
-
-The `HasErrorReason` function in [`libs/api-client-go/model_workspace.go`](https://github.com/daytonaio/daytona/blob/HEAD/libs/api-client-go/model_workspace.go) handles a key part of this chapter's functionality:
-
-```go
-}
-
-// HasErrorReason returns a boolean if a field has been set.
-func (o *Workspace) HasErrorReason() bool {
- if o != nil && !IsNil(o.ErrorReason) {
- return true
- }
-
- return false
-}
-
-// SetErrorReason gets a reference to the given string and assigns it to the ErrorReason field.
-func (o *Workspace) SetErrorReason(v string) {
- o.ErrorReason = &v
-}
-
-// GetRecoverable returns the Recoverable field value if set, zero value otherwise.
-func (o *Workspace) GetRecoverable() bool {
- if o == nil || IsNil(o.Recoverable) {
- var ret bool
- return ret
- }
- return *o.Recoverable
-}
-
-// GetRecoverableOk returns a tuple with the Recoverable field value if set, nil otherwise
-// and a boolean to check if the value has been set.
-func (o *Workspace) GetRecoverableOk() (*bool, bool) {
- if o == nil || IsNil(o.Recoverable) {
- return nil, false
- }
- return o.Recoverable, true
-```
-
-This function is important because it defines how Daytona Tutorial: Secure Sandbox Infrastructure for AI-Generated Code implements the patterns covered in this chapter.
-
-### `libs/api-client-go/model_workspace.go`
-
-The `SetErrorReason` function in [`libs/api-client-go/model_workspace.go`](https://github.com/daytonaio/daytona/blob/HEAD/libs/api-client-go/model_workspace.go) handles a key part of this chapter's functionality:
-
-```go
-}
-
-// SetErrorReason gets a reference to the given string and assigns it to the ErrorReason field.
-func (o *Workspace) SetErrorReason(v string) {
- o.ErrorReason = &v
-}
-
-// GetRecoverable returns the Recoverable field value if set, zero value otherwise.
-func (o *Workspace) GetRecoverable() bool {
- if o == nil || IsNil(o.Recoverable) {
- var ret bool
- return ret
- }
- return *o.Recoverable
-}
-
-// GetRecoverableOk returns a tuple with the Recoverable field value if set, nil otherwise
-// and a boolean to check if the value has been set.
-func (o *Workspace) GetRecoverableOk() (*bool, bool) {
- if o == nil || IsNil(o.Recoverable) {
- return nil, false
- }
- return o.Recoverable, true
-}
-
-// HasRecoverable returns a boolean if a field has been set.
-func (o *Workspace) HasRecoverable() bool {
- if o != nil && !IsNil(o.Recoverable) {
- return true
- }
-
- return false
-```
-
-This function is important because it defines how Daytona Tutorial: Secure Sandbox Infrastructure for AI-Generated Code implements the patterns covered in this chapter.
-
-### `libs/api-client-go/model_workspace.go`
-
-The `GetRecoverable` function in [`libs/api-client-go/model_workspace.go`](https://github.com/daytonaio/daytona/blob/HEAD/libs/api-client-go/model_workspace.go) handles a key part of this chapter's functionality:
-
-```go
-}
-
-// GetRecoverable returns the Recoverable field value if set, zero value otherwise.
-func (o *Workspace) GetRecoverable() bool {
- if o == nil || IsNil(o.Recoverable) {
- var ret bool
- return ret
- }
- return *o.Recoverable
-}
-
-// GetRecoverableOk returns a tuple with the Recoverable field value if set, nil otherwise
-// and a boolean to check if the value has been set.
-func (o *Workspace) GetRecoverableOk() (*bool, bool) {
- if o == nil || IsNil(o.Recoverable) {
- return nil, false
- }
- return o.Recoverable, true
-}
-
-// HasRecoverable returns a boolean if a field has been set.
-func (o *Workspace) HasRecoverable() bool {
- if o != nil && !IsNil(o.Recoverable) {
- return true
- }
-
- return false
-}
-
-// SetRecoverable gets a reference to the given bool and assigns it to the Recoverable field.
-func (o *Workspace) SetRecoverable(v bool) {
- o.Recoverable = &v
-```
-
-This function is important because it defines how Daytona Tutorial: Secure Sandbox Infrastructure for AI-Generated Code implements the patterns covered in this chapter.
-
-### `libs/api-client-go/model_workspace.go`
-
-The `GetRecoverableOk` function in [`libs/api-client-go/model_workspace.go`](https://github.com/daytonaio/daytona/blob/HEAD/libs/api-client-go/model_workspace.go) handles a key part of this chapter's functionality:
-
-```go
-}
-
-// GetRecoverableOk returns a tuple with the Recoverable field value if set, nil otherwise
-// and a boolean to check if the value has been set.
-func (o *Workspace) GetRecoverableOk() (*bool, bool) {
- if o == nil || IsNil(o.Recoverable) {
- return nil, false
- }
- return o.Recoverable, true
-}
-
-// HasRecoverable returns a boolean if a field has been set.
-func (o *Workspace) HasRecoverable() bool {
- if o != nil && !IsNil(o.Recoverable) {
- return true
- }
-
- return false
-}
-
-// SetRecoverable gets a reference to the given bool and assigns it to the Recoverable field.
-func (o *Workspace) SetRecoverable(v bool) {
- o.Recoverable = &v
-}
-
-// GetBackupState returns the BackupState field value if set, zero value otherwise.
-func (o *Workspace) GetBackupState() string {
- if o == nil || IsNil(o.BackupState) {
- var ret string
- return ret
- }
- return *o.BackupState
-```
-
-This function is important because it defines how Daytona Tutorial: Secure Sandbox Infrastructure for AI-Generated Code implements the patterns covered in this chapter.
-
-
## How These Components Connect
```mermaid
flowchart TD
- A[HasErrorReason]
- B[SetErrorReason]
- C[GetRecoverable]
- D[GetRecoverableOk]
- E[HasRecoverable]
- A --> B
- B --> C
- C --> D
- D --> E
+ A[SDK call] --> B{Operation}
+ B -->|file upload/download| C[Sandbox filesystem]
+ B -->|git clone/commit/push| D[Git operations in sandbox]
+ B -->|preview link| E[Port-forwarded URL]
+ C --> F[Persistent file state]
+ D --> G[Source control synced]
+ E --> H[Browser-accessible preview]
```
diff --git a/tutorials/daytona-tutorial/05-mcp-agent-integration-and-tooling.md b/tutorials/daytona-tutorial/05-mcp-agent-integration-and-tooling.md
index c909f08e..2faee731 100644
--- a/tutorials/daytona-tutorial/05-mcp-agent-integration-and-tooling.md
+++ b/tutorials/daytona-tutorial/05-mcp-agent-integration-and-tooling.md
@@ -36,186 +36,14 @@ You can now connect Daytona capabilities directly into MCP-compatible coding-age
Next: [Chapter 6: Configuration, API, and Deployment Models](06-configuration-api-and-deployment-models.md)
-## Depth Expansion Playbook
-
-## Source Code Walkthrough
-
-### `libs/api-client-go/model_workspace.go`
-
-The `GetRunnerId` function in [`libs/api-client-go/model_workspace.go`](https://github.com/daytonaio/daytona/blob/HEAD/libs/api-client-go/model_workspace.go) handles a key part of this chapter's functionality:
-
-```go
-}
-
-// GetRunnerId returns the RunnerId field value if set, zero value otherwise.
-func (o *Workspace) GetRunnerId() string {
- if o == nil || IsNil(o.RunnerId) {
- var ret string
- return ret
- }
- return *o.RunnerId
-}
-
-// GetRunnerIdOk returns a tuple with the RunnerId field value if set, nil otherwise
-// and a boolean to check if the value has been set.
-func (o *Workspace) GetRunnerIdOk() (*string, bool) {
- if o == nil || IsNil(o.RunnerId) {
- return nil, false
- }
- return o.RunnerId, true
-}
-
-// HasRunnerId returns a boolean if a field has been set.
-func (o *Workspace) HasRunnerId() bool {
- if o != nil && !IsNil(o.RunnerId) {
- return true
- }
-
- return false
-}
-
-// SetRunnerId gets a reference to the given string and assigns it to the RunnerId field.
-func (o *Workspace) SetRunnerId(v string) {
- o.RunnerId = &v
-```
-
-This function is important because it defines how Daytona Tutorial: Secure Sandbox Infrastructure for AI-Generated Code implements the patterns covered in this chapter.
-
-### `libs/api-client-go/model_workspace.go`
-
-The `GetRunnerIdOk` function in [`libs/api-client-go/model_workspace.go`](https://github.com/daytonaio/daytona/blob/HEAD/libs/api-client-go/model_workspace.go) handles a key part of this chapter's functionality:
-
-```go
-}
-
-// GetRunnerIdOk returns a tuple with the RunnerId field value if set, nil otherwise
-// and a boolean to check if the value has been set.
-func (o *Workspace) GetRunnerIdOk() (*string, bool) {
- if o == nil || IsNil(o.RunnerId) {
- return nil, false
- }
- return o.RunnerId, true
-}
-
-// HasRunnerId returns a boolean if a field has been set.
-func (o *Workspace) HasRunnerId() bool {
- if o != nil && !IsNil(o.RunnerId) {
- return true
- }
-
- return false
-}
-
-// SetRunnerId gets a reference to the given string and assigns it to the RunnerId field.
-func (o *Workspace) SetRunnerId(v string) {
- o.RunnerId = &v
-}
-
-// GetToolboxProxyUrl returns the ToolboxProxyUrl field value
-func (o *Workspace) GetToolboxProxyUrl() string {
- if o == nil {
- var ret string
- return ret
- }
-
-```
-
-This function is important because it defines how Daytona Tutorial: Secure Sandbox Infrastructure for AI-Generated Code implements the patterns covered in this chapter.
-
-### `libs/api-client-go/model_workspace.go`
-
-The `HasRunnerId` function in [`libs/api-client-go/model_workspace.go`](https://github.com/daytonaio/daytona/blob/HEAD/libs/api-client-go/model_workspace.go) handles a key part of this chapter's functionality:
-
-```go
-}
-
-// HasRunnerId returns a boolean if a field has been set.
-func (o *Workspace) HasRunnerId() bool {
- if o != nil && !IsNil(o.RunnerId) {
- return true
- }
-
- return false
-}
-
-// SetRunnerId gets a reference to the given string and assigns it to the RunnerId field.
-func (o *Workspace) SetRunnerId(v string) {
- o.RunnerId = &v
-}
-
-// GetToolboxProxyUrl returns the ToolboxProxyUrl field value
-func (o *Workspace) GetToolboxProxyUrl() string {
- if o == nil {
- var ret string
- return ret
- }
-
- return o.ToolboxProxyUrl
-}
-
-// GetToolboxProxyUrlOk returns a tuple with the ToolboxProxyUrl field value
-// and a boolean to check if the value has been set.
-func (o *Workspace) GetToolboxProxyUrlOk() (*string, bool) {
- if o == nil {
- return nil, false
- }
-```
-
-This function is important because it defines how Daytona Tutorial: Secure Sandbox Infrastructure for AI-Generated Code implements the patterns covered in this chapter.
-
-### `libs/api-client-go/model_workspace.go`
-
-The `SetRunnerId` function in [`libs/api-client-go/model_workspace.go`](https://github.com/daytonaio/daytona/blob/HEAD/libs/api-client-go/model_workspace.go) handles a key part of this chapter's functionality:
-
-```go
-}
-
-// SetRunnerId gets a reference to the given string and assigns it to the RunnerId field.
-func (o *Workspace) SetRunnerId(v string) {
- o.RunnerId = &v
-}
-
-// GetToolboxProxyUrl returns the ToolboxProxyUrl field value
-func (o *Workspace) GetToolboxProxyUrl() string {
- if o == nil {
- var ret string
- return ret
- }
-
- return o.ToolboxProxyUrl
-}
-
-// GetToolboxProxyUrlOk returns a tuple with the ToolboxProxyUrl field value
-// and a boolean to check if the value has been set.
-func (o *Workspace) GetToolboxProxyUrlOk() (*string, bool) {
- if o == nil {
- return nil, false
- }
- return &o.ToolboxProxyUrl, true
-}
-
-// SetToolboxProxyUrl sets field value
-func (o *Workspace) SetToolboxProxyUrl(v string) {
- o.ToolboxProxyUrl = v
-}
-
-// GetImage returns the Image field value if set, zero value otherwise.
-```
-
-This function is important because it defines how Daytona Tutorial: Secure Sandbox Infrastructure for AI-Generated Code implements the patterns covered in this chapter.
-
-
## How These Components Connect
```mermaid
flowchart TD
- A[GetRunnerId]
- B[GetRunnerIdOk]
- C[HasRunnerId]
- D[SetRunnerId]
- E[GetToolboxProxyUrl]
- A --> B
- B --> C
- C --> D
- D --> E
+ A[AI Coding Agent] -->|MCP protocol| B[Daytona MCP Server]
+ B --> C[daytona CLI subprocess]
+ C --> D[Daytona API]
+ D --> E[Sandbox operations]
+ E -->|create/exec/file ops| F[Isolated sandbox]
+ F --> G[Results back to agent]
```
diff --git a/tutorials/daytona-tutorial/06-configuration-api-and-deployment-models.md b/tutorials/daytona-tutorial/06-configuration-api-and-deployment-models.md
index a26db267..b2a9ed53 100644
--- a/tutorials/daytona-tutorial/06-configuration-api-and-deployment-models.md
+++ b/tutorials/daytona-tutorial/06-configuration-api-and-deployment-models.md
@@ -36,186 +36,16 @@ You now have a clearer contract for environment setup and deployment mode select
Next: [Chapter 7: Limits, Network Controls, and Security](07-limits-network-controls-and-security.md)
-## Depth Expansion Playbook
-
-## Source Code Walkthrough
-
-### `libs/toolbox-api-client-go/api_git.go`
-
-The `CommitChangesExecute` function in [`libs/toolbox-api-client-go/api_git.go`](https://github.com/daytonaio/daytona/blob/HEAD/libs/toolbox-api-client-go/api_git.go) handles a key part of this chapter's functionality:
-
-```go
- CommitChanges(ctx context.Context) GitAPICommitChangesRequest
-
- // CommitChangesExecute executes the request
- // @return GitCommitResponse
- CommitChangesExecute(r GitAPICommitChangesRequest) (*GitCommitResponse, *http.Response, error)
-
- /*
- CreateBranch Create a new branch
-
- Create a new branch in the Git repository
-
- @param ctx context.Context - for authentication, logging, cancellation, deadlines, tracing, etc. Passed from http.Request or context.Background().
- @return GitAPICreateBranchRequest
- */
- CreateBranch(ctx context.Context) GitAPICreateBranchRequest
-
- // CreateBranchExecute executes the request
- CreateBranchExecute(r GitAPICreateBranchRequest) (*http.Response, error)
-
- /*
- DeleteBranch Delete a branch
-
- Delete a branch from the Git repository
-
- @param ctx context.Context - for authentication, logging, cancellation, deadlines, tracing, etc. Passed from http.Request or context.Background().
- @return GitAPIDeleteBranchRequest
- */
- DeleteBranch(ctx context.Context) GitAPIDeleteBranchRequest
-
- // DeleteBranchExecute executes the request
- DeleteBranchExecute(r GitAPIDeleteBranchRequest) (*http.Response, error)
-
-```
-
-This function is important because it defines how Daytona Tutorial: Secure Sandbox Infrastructure for AI-Generated Code implements the patterns covered in this chapter.
-
-### `libs/toolbox-api-client-go/api_git.go`
-
-The `Request` function in [`libs/toolbox-api-client-go/api_git.go`](https://github.com/daytonaio/daytona/blob/HEAD/libs/toolbox-api-client-go/api_git.go) handles a key part of this chapter's functionality:
-
-```go
- Add files to the Git staging area
-
- @param ctx context.Context - for authentication, logging, cancellation, deadlines, tracing, etc. Passed from http.Request or context.Background().
- @return GitAPIAddFilesRequest
- */
- AddFiles(ctx context.Context) GitAPIAddFilesRequest
-
- // AddFilesExecute executes the request
- AddFilesExecute(r GitAPIAddFilesRequest) (*http.Response, error)
-
- /*
- CheckoutBranch Checkout branch or commit
-
- Switch to a different branch or commit in the Git repository
-
- @param ctx context.Context - for authentication, logging, cancellation, deadlines, tracing, etc. Passed from http.Request or context.Background().
- @return GitAPICheckoutBranchRequest
- */
- CheckoutBranch(ctx context.Context) GitAPICheckoutBranchRequest
-
- // CheckoutBranchExecute executes the request
- CheckoutBranchExecute(r GitAPICheckoutBranchRequest) (*http.Response, error)
-
- /*
- CloneRepository Clone a Git repository
-
- Clone a Git repository to the specified path
-
- @param ctx context.Context - for authentication, logging, cancellation, deadlines, tracing, etc. Passed from http.Request or context.Background().
- @return GitAPICloneRepositoryRequest
- */
- CloneRepository(ctx context.Context) GitAPICloneRepositoryRequest
-```
-
-This function is important because it defines how Daytona Tutorial: Secure Sandbox Infrastructure for AI-Generated Code implements the patterns covered in this chapter.
-
-### `libs/toolbox-api-client-go/api_git.go`
-
-The `Execute` function in [`libs/toolbox-api-client-go/api_git.go`](https://github.com/daytonaio/daytona/blob/HEAD/libs/toolbox-api-client-go/api_git.go) handles a key part of this chapter's functionality:
-
-```go
- AddFiles(ctx context.Context) GitAPIAddFilesRequest
-
- // AddFilesExecute executes the request
- AddFilesExecute(r GitAPIAddFilesRequest) (*http.Response, error)
-
- /*
- CheckoutBranch Checkout branch or commit
-
- Switch to a different branch or commit in the Git repository
-
- @param ctx context.Context - for authentication, logging, cancellation, deadlines, tracing, etc. Passed from http.Request or context.Background().
- @return GitAPICheckoutBranchRequest
- */
- CheckoutBranch(ctx context.Context) GitAPICheckoutBranchRequest
-
- // CheckoutBranchExecute executes the request
- CheckoutBranchExecute(r GitAPICheckoutBranchRequest) (*http.Response, error)
-
- /*
- CloneRepository Clone a Git repository
-
- Clone a Git repository to the specified path
-
- @param ctx context.Context - for authentication, logging, cancellation, deadlines, tracing, etc. Passed from http.Request or context.Background().
- @return GitAPICloneRepositoryRequest
- */
- CloneRepository(ctx context.Context) GitAPICloneRepositoryRequest
-
- // CloneRepositoryExecute executes the request
- CloneRepositoryExecute(r GitAPICloneRepositoryRequest) (*http.Response, error)
-
- /*
-```
-
-This function is important because it defines how Daytona Tutorial: Secure Sandbox Infrastructure for AI-Generated Code implements the patterns covered in this chapter.
-
-### `libs/toolbox-api-client-go/api_git.go`
-
-The `CreateBranch` function in [`libs/toolbox-api-client-go/api_git.go`](https://github.com/daytonaio/daytona/blob/HEAD/libs/toolbox-api-client-go/api_git.go) handles a key part of this chapter's functionality:
-
-```go
-
- /*
- CreateBranch Create a new branch
-
- Create a new branch in the Git repository
-
- @param ctx context.Context - for authentication, logging, cancellation, deadlines, tracing, etc. Passed from http.Request or context.Background().
- @return GitAPICreateBranchRequest
- */
- CreateBranch(ctx context.Context) GitAPICreateBranchRequest
-
- // CreateBranchExecute executes the request
- CreateBranchExecute(r GitAPICreateBranchRequest) (*http.Response, error)
-
- /*
- DeleteBranch Delete a branch
-
- Delete a branch from the Git repository
-
- @param ctx context.Context - for authentication, logging, cancellation, deadlines, tracing, etc. Passed from http.Request or context.Background().
- @return GitAPIDeleteBranchRequest
- */
- DeleteBranch(ctx context.Context) GitAPIDeleteBranchRequest
-
- // DeleteBranchExecute executes the request
- DeleteBranchExecute(r GitAPIDeleteBranchRequest) (*http.Response, error)
-
- /*
- GetCommitHistory Get commit history
-
- Get the commit history of the Git repository
-
-```
-
-This function is important because it defines how Daytona Tutorial: Secure Sandbox Infrastructure for AI-Generated Code implements the patterns covered in this chapter.
-
-
## How These Components Connect
```mermaid
flowchart TD
- A[CommitChangesExecute]
- B[Request]
- C[Execute]
- D[CreateBranch]
- E[CreateBranchExecute]
- A --> B
- B --> C
+ A{Deployment model} -->|Cloud SaaS| B[Daytona Cloud]
+ A -->|Self-hosted| C[OSS Daytona server]
+ B --> D[REST API]
C --> D
- D --> E
+ D --> E[SDK / CLI]
+ E --> F[Sandbox workloads]
+ G[Environment variables] --> E
+ H[API key auth] --> D
```
diff --git a/tutorials/daytona-tutorial/07-limits-network-controls-and-security.md b/tutorials/daytona-tutorial/07-limits-network-controls-and-security.md
index 478eb215..ce627dbe 100644
--- a/tutorials/daytona-tutorial/07-limits-network-controls-and-security.md
+++ b/tutorials/daytona-tutorial/07-limits-network-controls-and-security.md
@@ -36,186 +36,16 @@ You now have a policy framework for scaling usage while constraining abuse and b
Next: [Chapter 8: Production Operations and Contribution](08-production-operations-and-contribution.md)
-## Depth Expansion Playbook
-
-## Source Code Walkthrough
-
-### `libs/api-client-go/model_runner_full.go`
-
-The `GetMemoryOk` function in [`libs/api-client-go/model_runner_full.go`](https://github.com/daytonaio/daytona/blob/HEAD/libs/api-client-go/model_runner_full.go) handles a key part of this chapter's functionality:
-
-```go
-}
-
-// GetMemoryOk returns a tuple with the Memory field value
-// and a boolean to check if the value has been set.
-func (o *RunnerFull) GetMemoryOk() (*float32, bool) {
- if o == nil {
- return nil, false
- }
- return &o.Memory, true
-}
-
-// SetMemory sets field value
-func (o *RunnerFull) SetMemory(v float32) {
- o.Memory = v
-}
-
-// GetDisk returns the Disk field value
-func (o *RunnerFull) GetDisk() float32 {
- if o == nil {
- var ret float32
- return ret
- }
-
- return o.Disk
-}
-
-// GetDiskOk returns a tuple with the Disk field value
-// and a boolean to check if the value has been set.
-func (o *RunnerFull) GetDiskOk() (*float32, bool) {
- if o == nil {
- return nil, false
- }
-```
-
-This function is important because it defines how Daytona Tutorial: Secure Sandbox Infrastructure for AI-Generated Code implements the patterns covered in this chapter.
-
-### `libs/api-client-go/model_runner_full.go`
-
-The `SetMemory` function in [`libs/api-client-go/model_runner_full.go`](https://github.com/daytonaio/daytona/blob/HEAD/libs/api-client-go/model_runner_full.go) handles a key part of this chapter's functionality:
-
-```go
-}
-
-// SetMemory sets field value
-func (o *RunnerFull) SetMemory(v float32) {
- o.Memory = v
-}
-
-// GetDisk returns the Disk field value
-func (o *RunnerFull) GetDisk() float32 {
- if o == nil {
- var ret float32
- return ret
- }
-
- return o.Disk
-}
-
-// GetDiskOk returns a tuple with the Disk field value
-// and a boolean to check if the value has been set.
-func (o *RunnerFull) GetDiskOk() (*float32, bool) {
- if o == nil {
- return nil, false
- }
- return &o.Disk, true
-}
-
-// SetDisk sets field value
-func (o *RunnerFull) SetDisk(v float32) {
- o.Disk = v
-}
-
-// GetGpu returns the Gpu field value if set, zero value otherwise.
-```
-
-This function is important because it defines how Daytona Tutorial: Secure Sandbox Infrastructure for AI-Generated Code implements the patterns covered in this chapter.
-
-### `libs/api-client-go/model_runner_full.go`
-
-The `GetDisk` function in [`libs/api-client-go/model_runner_full.go`](https://github.com/daytonaio/daytona/blob/HEAD/libs/api-client-go/model_runner_full.go) handles a key part of this chapter's functionality:
-
-```go
-}
-
-// GetDisk returns the Disk field value
-func (o *RunnerFull) GetDisk() float32 {
- if o == nil {
- var ret float32
- return ret
- }
-
- return o.Disk
-}
-
-// GetDiskOk returns a tuple with the Disk field value
-// and a boolean to check if the value has been set.
-func (o *RunnerFull) GetDiskOk() (*float32, bool) {
- if o == nil {
- return nil, false
- }
- return &o.Disk, true
-}
-
-// SetDisk sets field value
-func (o *RunnerFull) SetDisk(v float32) {
- o.Disk = v
-}
-
-// GetGpu returns the Gpu field value if set, zero value otherwise.
-func (o *RunnerFull) GetGpu() float32 {
- if o == nil || IsNil(o.Gpu) {
- var ret float32
- return ret
- }
-```
-
-This function is important because it defines how Daytona Tutorial: Secure Sandbox Infrastructure for AI-Generated Code implements the patterns covered in this chapter.
-
-### `libs/api-client-go/model_runner_full.go`
-
-The `GetDiskOk` function in [`libs/api-client-go/model_runner_full.go`](https://github.com/daytonaio/daytona/blob/HEAD/libs/api-client-go/model_runner_full.go) handles a key part of this chapter's functionality:
-
-```go
-}
-
-// GetDiskOk returns a tuple with the Disk field value
-// and a boolean to check if the value has been set.
-func (o *RunnerFull) GetDiskOk() (*float32, bool) {
- if o == nil {
- return nil, false
- }
- return &o.Disk, true
-}
-
-// SetDisk sets field value
-func (o *RunnerFull) SetDisk(v float32) {
- o.Disk = v
-}
-
-// GetGpu returns the Gpu field value if set, zero value otherwise.
-func (o *RunnerFull) GetGpu() float32 {
- if o == nil || IsNil(o.Gpu) {
- var ret float32
- return ret
- }
- return *o.Gpu
-}
-
-// GetGpuOk returns a tuple with the Gpu field value if set, nil otherwise
-// and a boolean to check if the value has been set.
-func (o *RunnerFull) GetGpuOk() (*float32, bool) {
- if o == nil || IsNil(o.Gpu) {
- return nil, false
- }
- return o.Gpu, true
-```
-
-This function is important because it defines how Daytona Tutorial: Secure Sandbox Infrastructure for AI-Generated Code implements the patterns covered in this chapter.
-
-
## How These Components Connect
```mermaid
flowchart TD
- A[GetMemoryOk]
- B[SetMemory]
- C[GetDisk]
- D[GetDiskOk]
- E[SetDisk]
- A --> B
- B --> C
- C --> D
- D --> E
+ A[Organization quota] --> B{Limit type}
+ B -->|CPU/RAM| C[Resource cap per sandbox]
+ B -->|Concurrent sandboxes| D[Max running count]
+ B -->|Network firewall| E[Egress allowlist / blocklist]
+ C --> F[Sandbox enforces limits]
+ D --> F
+ E --> F
+ F --> G[Isolated execution]
```
diff --git a/tutorials/daytona-tutorial/08-production-operations-and-contribution.md b/tutorials/daytona-tutorial/08-production-operations-and-contribution.md
index 22e1331a..3fa2b142 100644
--- a/tutorials/daytona-tutorial/08-production-operations-and-contribution.md
+++ b/tutorials/daytona-tutorial/08-production-operations-and-contribution.md
@@ -38,186 +38,16 @@ This chapter finalizes operational practices for long-lived Daytona adoption.
You now have an end-to-end blueprint for using Daytona as secure execution infrastructure for agentic coding workflows.
-## Depth Expansion Playbook
-
-## Source Code Walkthrough
-
-### `libs/api-client-go/model_runner_full.go`
-
-The `HasAvailabilityScore` function in [`libs/api-client-go/model_runner_full.go`](https://github.com/daytonaio/daytona/blob/HEAD/libs/api-client-go/model_runner_full.go) handles a key part of this chapter's functionality:
-
-```go
-}
-
-// HasAvailabilityScore returns a boolean if a field has been set.
-func (o *RunnerFull) HasAvailabilityScore() bool {
- if o != nil && !IsNil(o.AvailabilityScore) {
- return true
- }
-
- return false
-}
-
-// SetAvailabilityScore gets a reference to the given float32 and assigns it to the AvailabilityScore field.
-func (o *RunnerFull) SetAvailabilityScore(v float32) {
- o.AvailabilityScore = &v
-}
-
-// GetRegion returns the Region field value
-func (o *RunnerFull) GetRegion() string {
- if o == nil {
- var ret string
- return ret
- }
-
- return o.Region
-}
-
-// GetRegionOk returns a tuple with the Region field value
-// and a boolean to check if the value has been set.
-func (o *RunnerFull) GetRegionOk() (*string, bool) {
- if o == nil {
- return nil, false
- }
-```
-
-This function is important because it defines how Daytona Tutorial: Secure Sandbox Infrastructure for AI-Generated Code implements the patterns covered in this chapter.
-
-### `libs/api-client-go/model_runner_full.go`
-
-The `SetAvailabilityScore` function in [`libs/api-client-go/model_runner_full.go`](https://github.com/daytonaio/daytona/blob/HEAD/libs/api-client-go/model_runner_full.go) handles a key part of this chapter's functionality:
-
-```go
-}
-
-// SetAvailabilityScore gets a reference to the given float32 and assigns it to the AvailabilityScore field.
-func (o *RunnerFull) SetAvailabilityScore(v float32) {
- o.AvailabilityScore = &v
-}
-
-// GetRegion returns the Region field value
-func (o *RunnerFull) GetRegion() string {
- if o == nil {
- var ret string
- return ret
- }
-
- return o.Region
-}
-
-// GetRegionOk returns a tuple with the Region field value
-// and a boolean to check if the value has been set.
-func (o *RunnerFull) GetRegionOk() (*string, bool) {
- if o == nil {
- return nil, false
- }
- return &o.Region, true
-}
-
-// SetRegion sets field value
-func (o *RunnerFull) SetRegion(v string) {
- o.Region = v
-}
-
-// GetName returns the Name field value
-```
-
-This function is important because it defines how Daytona Tutorial: Secure Sandbox Infrastructure for AI-Generated Code implements the patterns covered in this chapter.
-
-### `libs/api-client-go/model_runner_full.go`
-
-The `GetRegion` function in [`libs/api-client-go/model_runner_full.go`](https://github.com/daytonaio/daytona/blob/HEAD/libs/api-client-go/model_runner_full.go) handles a key part of this chapter's functionality:
-
-```go
-}
-
-// GetRegion returns the Region field value
-func (o *RunnerFull) GetRegion() string {
- if o == nil {
- var ret string
- return ret
- }
-
- return o.Region
-}
-
-// GetRegionOk returns a tuple with the Region field value
-// and a boolean to check if the value has been set.
-func (o *RunnerFull) GetRegionOk() (*string, bool) {
- if o == nil {
- return nil, false
- }
- return &o.Region, true
-}
-
-// SetRegion sets field value
-func (o *RunnerFull) SetRegion(v string) {
- o.Region = v
-}
-
-// GetName returns the Name field value
-func (o *RunnerFull) GetName() string {
- if o == nil {
- var ret string
- return ret
- }
-```
-
-This function is important because it defines how Daytona Tutorial: Secure Sandbox Infrastructure for AI-Generated Code implements the patterns covered in this chapter.
-
-### `libs/api-client-go/model_runner_full.go`
-
-The `GetRegionOk` function in [`libs/api-client-go/model_runner_full.go`](https://github.com/daytonaio/daytona/blob/HEAD/libs/api-client-go/model_runner_full.go) handles a key part of this chapter's functionality:
-
-```go
-}
-
-// GetRegionOk returns a tuple with the Region field value
-// and a boolean to check if the value has been set.
-func (o *RunnerFull) GetRegionOk() (*string, bool) {
- if o == nil {
- return nil, false
- }
- return &o.Region, true
-}
-
-// SetRegion sets field value
-func (o *RunnerFull) SetRegion(v string) {
- o.Region = v
-}
-
-// GetName returns the Name field value
-func (o *RunnerFull) GetName() string {
- if o == nil {
- var ret string
- return ret
- }
-
- return o.Name
-}
-
-// GetNameOk returns a tuple with the Name field value
-// and a boolean to check if the value has been set.
-func (o *RunnerFull) GetNameOk() (*string, bool) {
- if o == nil {
- return nil, false
- }
-```
-
-This function is important because it defines how Daytona Tutorial: Secure Sandbox Infrastructure for AI-Generated Code implements the patterns covered in this chapter.
-
-
## How These Components Connect
```mermaid
flowchart TD
- A[HasAvailabilityScore]
- B[SetAvailabilityScore]
- C[GetRegion]
- D[GetRegionOk]
- E[SetRegion]
- A --> B
- B --> C
- C --> D
- D --> E
+ A[Production workload] --> B[Daytona sandbox pool]
+ B --> C{Health checks}
+ C -->|Pass| D[Serve agent requests]
+ C -->|Fail| E[Restart / recreate sandbox]
+ D --> F[Emit metrics & logs]
+ F --> G[Observability stack]
+ H[Contributing] --> I[Fork → PR → CI]
+ I --> J[Merged to daytonaio/daytona]
```
diff --git a/tutorials/deer-flow-tutorial/01-getting-started.md b/tutorials/deer-flow-tutorial/01-getting-started.md
index b01fa15b..5c642baf 100644
--- a/tutorials/deer-flow-tutorial/01-getting-started.md
+++ b/tutorials/deer-flow-tutorial/01-getting-started.md
@@ -1,671 +1,365 @@
---
layout: default
-title: "Chapter 1: Getting Started with Deer Flow"
-parent: "Deer Flow Tutorial"
+title: "Chapter 1: Getting Started with DeerFlow"
+parent: "DeerFlow Tutorial"
nav_order: 1
+format_version: v2
+why: "DeerFlow is a non-trivial system with three services, a Docker sandbox, and an LLM config layer. Getting all pieces wired correctly before exploring architecture saves hours of debugging."
+mental_model: "Think of the setup as configuring an AI agent runtime — not a web app. You are wiring an LLM provider, an optional web-search API key, and a sandboxed Python execution environment together, then launching three coordinated services behind Nginx."
+learning_outcomes:
+ - Clone and configure DeerFlow with any OpenAI-compatible LLM
+ - Understand the three-service architecture before writing a single line of code
+ - Submit your first deep research query and read the streaming response
+ - Verify your setup with make doctor and understand what each health check tests
+snapshot:
+ repo: bytedance/deer-flow
+ stars: ~53.5k
+ last_checked: 2026-04-12
+chapter_map:
+ - "01 (this): Installation, config, first query"
+ - "02: LangGraph state machine internals"
+ - "03: Research pipeline deep dive"
+ - "04: RAG and search tools"
+ - "05: Frontend and API design"
+ - "06: Skills and extensions"
+ - "07: Podcast and multi-modal outputs"
+ - "08: Production deployment"
+sources:
+ - https://github.com/bytedance/deer-flow
+ - https://github.com/bytedance/deer-flow/blob/main/backend/docs/SETUP.md
+ - https://github.com/bytedance/deer-flow/blob/main/backend/docs/CONFIGURATION.md
---
-# Chapter 1: Getting Started with Deer Flow
+# Chapter 1: Getting Started with DeerFlow
-Welcome to Deer Flow! This chapter will guide you through installing and setting up Deer Flow, understanding its core concepts, and creating your first distributed workflow.
+## What Problem Does This Solve?
+
+Most teams assume DeerFlow is something it is not. The repository name sounds like a workflow scheduler. The old documentation described it as a distributed task execution platform. Neither description is accurate.
+
+DeerFlow is an **open-source super agent harness** — a runtime that orchestrates a lead LLM agent to conduct deep research, write and execute code, spawn parallel sub-agents, load modular skills, and deliver structured outputs (reports, podcasts, slides) via a chat interface. It was created by ByteDance and is conceptually similar to Google's Gemini Deep Research product, but open-source and extensible.
-## 🎯 What You'll Learn
+The practical problem it solves: when you need an AI assistant that can autonomously browse the web from multiple angles, write and run Python to analyze data, synthesize a structured report with citations, and optionally produce audio or slide outputs — all from a single chat message — DeerFlow provides the production-ready runtime to do it.
-- Deer Flow installation and setup
-- Core concepts (workflows, tasks, dependencies)
-- Basic workflow creation and execution
-- Web interface and API usage
-- First distributed workflow walkthrough
+This chapter gets you from zero to your first research output in under 30 minutes.
-## 🏗️ Deer Flow Architecture
+## How it Works Under the Hood
-Deer Flow consists of several key components working together to orchestrate distributed workflows:
+Before touching any configuration, it helps to understand the three-service architecture you are about to start.
```mermaid
-graph TB
- subgraph "Control Plane"
- A[Workflow Manager]
- B[Task Scheduler]
- C[Dependency Resolver]
- D[State Manager]
+graph LR
+ subgraph "Your Browser / IM Client"
+ A[Chat UI :2026]
end
- subgraph "Execution Plane"
- E[Worker Nodes]
- F[Task Executors]
- G[Resource Pool]
- H[Load Balancer]
+ subgraph "Nginx Proxy :2026"
+ B[Entry Point]
end
- subgraph "Data Plane"
- I[Workflow Store]
- J[Task Queue]
- K[Result Store]
- L[Metrics Store]
+ subgraph "Three Core Services"
+ C[LangGraph Server :2024<br/>Agent runtime, SSE streaming,<br/>thread state management]
+ D[Gateway API :8001<br/>FastAPI REST endpoints<br/>models, skills, MCP, uploads]
+ E[Next.js Frontend :3000<br/>Chat interface, streaming<br/>message rendering]
end
- subgraph "Integration Layer"
- M[REST API]
- N[Web UI]
- O[CLI Tools]
- P[SDK Libraries]
+ subgraph "Execution Backend"
+ F[LocalSandboxProvider<br/>dev mode]
+ G[AioSandboxProvider<br/>Docker containers prod]
end
A --> B
B --> C
- C --> D
- D --> E
- E --> F
- F --> G
- G --> H
- A --> I
- A --> J
- A --> K
- A --> L
- A --> M
- A --> N
- A --> O
- A --> P
+ B --> D
+ B --> E
+ C --> F
+ C --> G
```
-### Core Components
+Every user message flows through Nginx to the LangGraph server. The LangGraph server runs the compiled `lead_agent` graph, which invokes the LLM, dispatches tools, streams tokens back to the frontend via SSE, and persists state via an async checkpointer.
-1. **Workflow Manager**: Orchestrates workflow execution
-2. **Task Scheduler**: Assigns tasks to workers
-3. **Worker Nodes**: Execute tasks in parallel
-4. **State Manager**: Tracks workflow and task states
-5. **Result Store**: Persists task outputs and results
+The Gateway API handles everything that is not agent execution: listing available models, managing MCP server configuration, serving generated artifacts, handling file uploads, and managing memory records.
-## 🚀 Installation Methods
+## Prerequisites
-### Method 1: Docker Compose (Recommended)
+| Requirement | Minimum | Recommended |
+|:--|:--|:--|
+| CPU | 4 cores | 8 cores |
+| RAM | 8 GB | 16 GB |
+| Disk | 20 GB | 40 GB |
+| Docker | 24+ | latest |
+| Python | 3.12+ | 3.12+ |
+| Node.js | 22+ | 22+ |
-```bash
-# Clone the repository
-git clone https://github.com/bytedance/deer-flow.git
-cd deer-flow
-
-# Start all services
-docker-compose up -d
-
-# Check service status
-docker-compose ps
-
-# View logs
-docker-compose logs -f deer-flow-server
-```
+You also need at least one LLM provider API key. DeerFlow works with any OpenAI-compatible endpoint including:
+- OpenAI (`gpt-4o`, `o1`, `o3`)
+- Anthropic Claude (via OpenAI-compatible proxy or direct LangChain integration)
+- DeepSeek
+- Novita AI
+- vLLM self-hosted endpoints
+- OpenRouter (routing to Gemini, Llama, etc.)
-**What this starts:**
-- Deer Flow server (port 8080)
-- Redis for task queuing
-- PostgreSQL for data storage
-- Web interface
+## Installation
-### Method 2: Manual Installation
+### Step 1: Clone the Repository
```bash
-# Install system dependencies
-sudo apt update
-sudo apt install python3.10 python3.10-venv postgresql redis-server
-
-# Clone and setup
git clone https://github.com/bytedance/deer-flow.git
cd deer-flow
-
-# Create virtual environment
-python3 -m venv venv
-source venv/bin/activate
-
-# Install dependencies
-pip install -r requirements.txt
-
-# Setup database
-sudo -u postgres createdb deerflow
-sudo -u postgres psql -c "CREATE USER deerflow WITH PASSWORD 'deerflow123';"
-sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE deerflow TO deerflow;"
-
-# Start Redis
-sudo systemctl start redis-server
-
-# Start the server
-python run_server.py
```
-### Method 3: Kubernetes Deployment
+### Step 2: Run the Interactive Setup Wizard
-```yaml
-# kubernetes/deployment.yaml
-apiVersion: apps/v1
-kind: Deployment
-metadata:
- name: deer-flow
-spec:
- replicas: 3
- selector:
- matchLabels:
- app: deer-flow
- template:
- metadata:
- labels:
- app: deer-flow
- spec:
- containers:
- - name: deer-flow
- image: bytedance/deer-flow:latest
- ports:
- - containerPort: 8080
- env:
- - name: DATABASE_URL
- value: "postgresql://deerflow:deerflow123@postgres:5432/deerflow"
- - name: REDIS_URL
- value: "redis://redis:6379"
- resources:
- limits:
- cpu: "1000m"
- memory: "1Gi"
- requests:
- cpu: "500m"
- memory: "512Mi"
-```
-
-## ⚙️ Configuration
-
-### Environment Variables
+The wizard creates `config.yaml` and `.env` from your answers:
```bash
-# Database configuration
-export DATABASE_URL="postgresql://deerflow:deerflow123@localhost:5432/deerflow"
+make setup
+```
-# Redis configuration
-export REDIS_URL="redis://localhost:6379"
+The wizard prompts for:
+1. LLM provider and model selection
+2. API key (saved to `.env`, referenced as `$OPENAI_API_KEY` in `config.yaml`)
+3. Web search provider (DuckDuckGo — free, no key; Tavily — better quality, requires key)
+4. Sandbox execution mode (local for dev, Docker for production)
-# Server configuration
-export SERVER_HOST="0.0.0.0"
-export SERVER_PORT="8080"
+After `make setup`, verify the generated files:
-# Worker configuration
-export WORKER_CONCURRENCY="4"
-export WORKER_PREFETCH="2"
+```bash
+# config.yaml should exist at the project root (NOT in backend/)
+ls -la config.yaml
-# Logging
-export LOG_LEVEL="INFO"
-export LOG_FILE="/var/log/deer-flow.log"
+# .env should contain your API key
+cat .env
```
-### Configuration File
+### Step 3: Validate with the Doctor Script
-```yaml
-# config.yaml
-server:
- host: "0.0.0.0"
- port: 8080
- workers: 4
-
-database:
- url: "postgresql://deerflow:deerflow123@localhost:5432/deerflow"
- pool_size: 10
- max_overflow: 20
-
-redis:
- url: "redis://localhost:6379"
- db: 0
-
-worker:
- concurrency: 4
- prefetch: 2
- heartbeat: 30
-
-logging:
- level: "INFO"
- file: "/var/log/deer-flow.log"
- format: "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
-
-monitoring:
- enabled: true
- metrics_port: 9090
+```bash
+make doctor
```
-## 🌐 Accessing Deer Flow
-
-Once installed, access Deer Flow through:
+The doctor script checks:
+- `config.yaml` loads without parse errors
+- The selected LLM model is reachable (test API call)
+- Web search tool (if configured) is responsive
+- Docker is available if sandbox mode is set to Docker
-```bash
-# Web interface
-open http://localhost:8080
+### Step 4: Choose Your Startup Mode
-# API endpoints
-curl http://localhost:8080/api/health
+**Docker (recommended for production and first-time setup):**
-# CLI tools
-deer-flow --help
-```
-
-### Default Credentials
-- **Web UI**: No authentication required (configure as needed)
-- **API**: No authentication by default (add middleware for production)
-
-## 🏃♂️ Your First Workflow
-
-### Creating a Simple Workflow
-
-```json
-// simple_workflow.json
-{
- "name": "hello_world",
- "description": "A simple hello world workflow",
- "version": "1.0",
- "tasks": [
- {
- "id": "hello_task",
- "name": "Hello Task",
- "type": "shell",
- "command": "echo 'Hello, Deer Flow!'",
- "timeout": 30
- }
- ]
-}
+```bash
+make docker-init # Pull images, create network, initialize volumes
+make docker-start # Start all three services + Nginx
```
-### Submitting the Workflow
+**Local development (faster iteration, no Docker for services):**
```bash
-# Via API
-curl -X POST http://localhost:8080/api/workflows \
- -H "Content-Type: application/json" \
- -d @simple_workflow.json
-
-# Via CLI
-deer-flow workflow submit simple_workflow.json
-
-# Via Python SDK
-from deerflow import WorkflowClient
-
-client = WorkflowClient("http://localhost:8080")
-workflow_id = client.submit_workflow("simple_workflow.json")
-print(f"Workflow submitted: {workflow_id}")
+make install # pip install + npm install
+make dev # Concurrently starts LangGraph server, Gateway, and Next.js
```
-### Monitoring Execution
+Both modes expose the UI at `http://localhost:2026`.
-```bash
-# Check workflow status
-curl http://localhost:8080/api/workflows/{workflow_id}/status
+## Configuration Deep Dive
-# View task logs
-curl http://localhost:8080/api/workflows/{workflow_id}/tasks/{task_id}/logs
+The `config.yaml` file controls every significant behavior of DeerFlow. Understanding its structure is essential for customization.
-# Get workflow results
-curl http://localhost:8080/api/workflows/{workflow_id}/result
+```yaml
+# config.yaml — canonical location: project root (deer-flow/config.yaml)
+config_version: 3
+
+models:
+ # Each entry defines an LLM available to the agent
+ - name: gpt-4o
+ display_name: GPT-4o
+ use: langchain_openai:ChatOpenAI
+ model: gpt-4o
+ api_key: $OPENAI_API_KEY
+ max_tokens: 16384
+ supports_thinking: false
+ supports_vision: true
+
+ # Example: OpenRouter routing to Gemini
+ - name: gemini-flash
+ display_name: Gemini 2.5 Flash
+ use: langchain_openai:ChatOpenAI
+ model: google/gemini-2.5-flash-preview
+ base_url: https://openrouter.ai/api/v1
+ api_key: $OPENROUTER_API_KEY
+
+tools:
+ # Web search configuration
+ - name: web_search
+ group: web
+ use: deerflow.community.ddg_search:web_search_tool
+ max_results: 5
+
+ # File operations
+ - name: read_file
+ group: file:read
+ use: deerflow.tools.file:read_file_tool
+
+ - name: bash
+ group: bash
+ use: deerflow.tools.bash:bash_tool
+
+sandbox:
+ # For development: direct host execution
+ use: deerflow.sandbox.local:LocalSandboxProvider
+ allow_host_bash: true
+
+ # For production: Docker-isolated execution
+ # use: deerflow.community.aio_sandbox:AioSandboxProvider
+ # auto_start: true
+ # port: 8080
+
+skills:
+ path: ../skills # Host path to skills directory
+ container_path: /mnt/skills
```
-## 📊 Understanding Workflow States
+The configuration path is resolved in this priority order:
+1. `DEER_FLOW_CONFIG_PATH` environment variable
+2. `backend/config.yaml`
+3. `deer-flow/config.yaml` (project root — the standard location)
-### Workflow States
+### Environment Variables
-```
-Workflow States
-├── PENDING - Workflow submitted, waiting to start
-├── RUNNING - Workflow is currently executing
-├── COMPLETED - All tasks completed successfully
-├── FAILED - One or more tasks failed
-├── CANCELLED - Workflow was cancelled
-└── TIMEOUT - Workflow exceeded time limit
+```bash
+# .env (git-ignored, do not commit)
+OPENAI_API_KEY=sk-...
+TAVILY_API_KEY=tvly-... # optional, better search quality
+ANTHROPIC_API_KEY=sk-ant-... # if using Claude directly
+LANGCHAIN_API_KEY=ls__... # optional, for LangSmith tracing
+LANGCHAIN_TRACING_V2=true # enable LangSmith
```
-### Task States
+## Your First Research Query
-```
-Task States
-├── PENDING - Task waiting to be scheduled
-├── SCHEDULED - Task assigned to a worker
-├── RUNNING - Task is currently executing
-├── COMPLETED - Task completed successfully
-├── FAILED - Task execution failed
-├── RETRY - Task failed, will retry
-├── CANCELLED - Task was cancelled
-└── TIMEOUT - Task exceeded time limit
-```
+With DeerFlow running at `http://localhost:2026`, open the chat interface and type:
-## 🔧 Workflow Definition
-
-### Basic Task Types
-
-```json
-{
- "tasks": [
- {
- "id": "shell_task",
- "name": "Shell Command",
- "type": "shell",
- "command": "echo 'Hello World'",
- "working_directory": "/tmp",
- "environment": {
- "MY_VAR": "my_value"
- },
- "timeout": 30
- },
- {
- "id": "http_task",
- "name": "HTTP Request",
- "type": "http",
- "method": "GET",
- "url": "https://api.example.com/data",
- "headers": {
- "Authorization": "Bearer token"
- },
- "timeout": 60
- },
- {
- "id": "python_task",
- "name": "Python Function",
- "type": "python",
- "module": "my_module",
- "function": "my_function",
- "args": ["arg1", "arg2"],
- "kwargs": {"key": "value"}
- }
- ]
-}
```
-
-### Workflow Metadata
-
-```json
-{
- "name": "data_processing_pipeline",
- "description": "Process and analyze data files",
- "version": "1.0.0",
- "author": "Data Team",
- "tags": ["data", "processing", "analytics"],
- "timeout": 3600,
- "retry_policy": {
- "max_attempts": 3,
- "backoff": "exponential",
- "initial_delay": 1
- },
- "notifications": {
- "on_success": ["email@company.com"],
- "on_failure": ["alerts@company.com"]
- }
-}
+What are the key architectural differences between LangGraph and AutoGen for building multi-agent systems? Include recent benchmarks and community adoption data.
```
-## 🔄 Task Dependencies
-
-### Simple Dependencies
-
-```json
-{
- "tasks": [
- {
- "id": "extract_data",
- "name": "Extract Data",
- "type": "shell",
- "command": "python extract.py"
- },
- {
- "id": "transform_data",
- "name": "Transform Data",
- "type": "shell",
- "command": "python transform.py",
- "depends_on": ["extract_data"]
- },
- {
- "id": "load_data",
- "name": "Load Data",
- "type": "shell",
- "command": "python load.py",
- "depends_on": ["transform_data"]
- }
- ]
-}
-```
+What you will observe:
-### Complex Dependencies
-
-```json
-{
- "tasks": [
- {
- "id": "task_a",
- "name": "Task A",
- "type": "shell",
- "command": "echo 'Task A'"
- },
- {
- "id": "task_b",
- "name": "Task B",
- "type": "shell",
- "command": "echo 'Task B'",
- "depends_on": ["task_a"]
- },
- {
- "id": "task_c",
- "name": "Task C",
- "type": "shell",
- "command": "echo 'Task C'",
- "depends_on": ["task_a"]
- },
- {
- "id": "task_d",
- "name": "Task D",
- "type": "shell",
- "command": "echo 'Task D'",
- "depends_on": ["task_b", "task_c"]
- }
- ]
-}
-```
-
-## 📊 Monitoring Workflows
-
-### Web Dashboard
+1. **Thinking phase** — The lead agent parses the question, identifies sub-topics, and may ask a clarifying question via `ask_clarification` if the request is ambiguous
+2. **Research phase** — Multiple web searches fire in sequence (or in parallel via sub-agents), each fetching and reading full page content
+3. **Synthesis phase** — The agent accumulates search results in its context window
+4. **Report phase** — A structured markdown report streams to the UI with inline citations in the format `[citation:Title](URL)`
-The Deer Flow web interface provides:
+The entire interaction is a single LangGraph thread, persisted in the checkpointer. You can resume it later or branch into a new query.
-- **Workflow Overview**: List of all workflows with status
-- **Task Details**: Individual task execution details
-- **Real-time Logs**: Live streaming of task logs
-- **Performance Metrics**: Execution times and success rates
-- **Dependency Graph**: Visual representation of task relationships
-
-### API Monitoring
-
-```bash
-# Get workflow statistics
-curl http://localhost:8080/api/workflows/stats
+```mermaid
+sequenceDiagram
+ participant U as User
+ participant UI as Next.js :3000
+ participant LG as LangGraph Server :2024
+ participant LLM as LLM Provider
+ participant WS as Web Search Tool
+ participant SB as Sandbox
+
+ U->>UI: Submit research query
+ UI->>LG: POST /threads/{id}/runs (SSE)
+ LG->>LLM: Lead agent invoke (system prompt + query)
+ LLM-->>LG: Tool call: web_search("LangGraph architecture")
+ LG->>WS: Execute search
+ WS-->>LG: Search results JSON
+ LG->>LLM: Continue with results
+ LLM-->>LG: Tool call: web_search("AutoGen benchmarks 2025")
+ LG->>WS: Execute search
+ WS-->>LG: Search results JSON
+ LG->>LLM: Continue with all results
+ LLM-->>LG: Final report (streaming tokens)
+ LG-->>UI: SSE token stream
+ UI-->>U: Rendered markdown report
+```
-# List running workflows
-curl http://localhost:8080/api/workflows?status=running
+## Understanding Thread State
-# Get task execution history
-curl http://localhost:8080/api/tasks/history
+Every conversation is a **thread**. DeerFlow extends LangGraph's `AgentState` with `ThreadState`:
-# Monitor system health
-curl http://localhost:8080/api/health
+```python
+# backend/packages/harness/deerflow/agents/thread_state.py
+class ThreadState(AgentState):
+ sandbox: SandboxState | None # Docker container ID for this thread
+ thread_data: ThreadDataState | None # Workspace/uploads/outputs paths
+ title: str | None # Auto-generated conversation title
+ artifacts: list[str] # Paths of generated outputs (reports, MP3s, slides)
+ todos: list | None # Task list (plan mode)
+ uploaded_files: list[dict] | None # Files attached by the user
+ viewed_images: dict[str, ViewedImageData] # Images the agent has processed
```
-## 🔧 Troubleshooting
+This state is checkpointed asynchronously after every step, meaning you can pause a long research run and resume it exactly where it left off.
-### Common Issues
+## Troubleshooting Common Setup Issues
-#### Connection Problems
-```bash
-# Check if services are running
-docker-compose ps
+### "config.yaml not found"
-# Verify API connectivity
-curl http://localhost:8080/api/health
+The backend looks for `config.yaml` in the project root (`deer-flow/`), not in `backend/`. The most common mistake is placing it in `backend/config.yaml`. Either move it or set:
-# Check logs
-docker-compose logs deer-flow-server
-```
-
-#### Database Issues
```bash
-# Check database connectivity
-docker-compose exec postgres psql -U deerflow -d deerflow -c "SELECT 1"
-
-# Reset database
-docker-compose down -v
-docker-compose up -d
+export DEER_FLOW_CONFIG_PATH=/absolute/path/to/deer-flow/config.yaml
```
-#### Worker Issues
-```bash
-# Check worker status
-curl http://localhost:8080/api/workers
+### LLM Model Not Responding
-# Restart workers
-docker-compose restart deer-flow-worker
+Run `make doctor` — it tests the model connection. If it fails, verify:
+- The API key in `.env` is correct and not expired
+- The `base_url` in `config.yaml` matches the provider's endpoint
+- The model name matches exactly (case-sensitive)
-# Scale workers
-docker-compose up -d --scale deer-flow-worker=3
-```
+### Docker Sandbox Startup Timeout
-### Performance Issues
+The AioSandbox container image is ~500 MB. Pull it explicitly before the first run:
```bash
-# Check resource usage
-docker stats
-
-# Monitor queue length
-curl http://localhost:8080/api/queue/stats
-
-# Adjust worker concurrency
-export WORKER_CONCURRENCY=8
-docker-compose restart deer-flow-worker
+make setup-sandbox
```
-## 🎯 Key Concepts
-
-### Workflows
-- **Definition**: JSON specification of tasks and dependencies
-- **Execution**: Orchestrated by the workflow manager
-- **State**: Tracked throughout lifecycle
-- **Results**: Stored and accessible via API
-
-### Tasks
-- **Types**: Shell, HTTP, Python, custom
-- **Dependencies**: Define execution order
-- **Retries**: Automatic retry on failure
-- **Timeouts**: Prevent hanging tasks
+### Port 2026 Already in Use
-### Workers
-- **Scaling**: Horizontal scaling for performance
-- **Isolation**: Each worker runs in separate container
-- **Monitoring**: Health checks and metrics
-- **Resource**: CPU and memory allocation
+```bash
+# Find the process using the port
+lsof -i :2026
+# Stop DeerFlow services
+make docker-stop
+# Or kill the specific process and restart
+```
-## 📊 Performance Metrics
+### Frontend Shows "Cannot connect to agent"
-### Key Metrics to Monitor
+The frontend at `:3000` proxies agent requests through Nginx at `:2026` to the LangGraph server at `:2024`. If the LangGraph server is not running, no agent calls will succeed. Check:
-```python
-# Workflow metrics
-workflow_metrics = {
- 'total_workflows': 0,
- 'running_workflows': 0,
- 'completed_workflows': 0,
- 'failed_workflows': 0,
- 'average_execution_time': 0.0
-}
-
-# Task metrics
-task_metrics = {
- 'total_tasks': 0,
- 'running_tasks': 0,
- 'completed_tasks': 0,
- 'failed_tasks': 0,
- 'retry_rate': 0.0
-}
-
-# System metrics
-system_metrics = {
- 'cpu_usage': 0.0,
- 'memory_usage': 0.0,
- 'queue_length': 0,
- 'worker_count': 0
-}
+```bash
+make docker-logs # Docker mode
+# or
+ps aux | grep langgraph # Local mode
```
-## 🏆 Achievement Unlocked!
-
-Congratulations! 🎉 You've successfully:
+## Key Concepts Recap
-- ✅ Installed Deer Flow using Docker
-- ✅ Configured the system components
-- ✅ Created and executed your first workflow
-- ✅ Explored the web interface and API
-- ✅ Understood workflow and task states
-- ✅ Set up basic monitoring
+| Concept | What It Actually Is |
+|:--|:--|
+| "Workflow" | A LangGraph thread — a sequence of LLM invocations + tool calls |
+| "Task" | A sub-agent invocation spawned via `task_tool` |
+| "Worker" | A Docker sandbox container executing Python/bash code |
+| "State" | The LangGraph `ThreadState` persisted by the checkpointer |
+| "Skill" | A Markdown file loaded into the agent's context to guide behavior |
+| "Config" | `config.yaml` at project root — LLM providers, tools, sandbox mode |
-## 🚀 What's Next?
+## What's Next?
-Ready to create more complex workflows? Let's explore [Chapter 2: Workflow Basics](02-workflow-basics.md) to learn about task types, dependencies, and advanced workflow patterns.
+With DeerFlow running and your first research query completed, Chapter 2 dives into the LangGraph state machine that powers everything: how the `lead_agent` graph is compiled, how the 14-stage middleware pipeline wraps every invocation, and how async checkpointing enables long-running multi-turn research sessions.
---
-**Practice what you've learned:**
-1. Experiment with different installation methods
-2. Create workflows with multiple task types
-3. Set up dependencies between tasks
-4. Monitor workflow execution in the web UI
-5. Explore the API endpoints for automation
-
-*What's the first distributed workflow you want to build?* 🔀
-
-## What Problem Does This Solve?
-
-Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for `Task`, `deer`, `flow` so behavior stays predictable as complexity grows.
-
-In practical terms, this chapter helps you avoid three common failures:
-
-- coupling core logic too tightly to one implementation path
-- missing the handoff boundaries between setup, execution, and validation
-- shipping changes without clear rollback or observability strategy
-
-After working through this chapter, you should be able to reason about `Chapter 1: Getting Started with Deer Flow` as an operating subsystem inside **Deer Flow Tutorial: Distributed Workflow Orchestration Platform**, with explicit contracts for inputs, state transitions, and outputs.
-
-Use the implementation notes around `name`, `localhost`, `http` as your checklist when adapting these patterns to your own repository.
-
-## How it Works Under the Hood
-
-Under the hood, `Chapter 1: Getting Started with Deer Flow` usually follows a repeatable control path:
-
-1. **Context bootstrap**: initialize runtime config and prerequisites for `Task`.
-2. **Input normalization**: shape incoming data so `deer` receives stable contracts.
-3. **Core execution**: run the main logic branch and propagate intermediate state through `flow`.
-4. **Policy and safety checks**: enforce limits, auth scopes, and failure boundaries.
-5. **Output composition**: return canonical result payloads for downstream consumers.
-6. **Operational telemetry**: emit logs/metrics needed for debugging and performance tuning.
-
-When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
-
-## Source Walkthrough
-
-Use the following upstream sources to verify implementation details while reading this chapter:
-
-- [Official Documentation](https://github.com/bytedance/deer-flow/tree/main/docs)
- Why it matters: authoritative reference on `Official Documentation` (github.com).
-- [GitHub Repository](https://github.com/bytedance/deer-flow)
- Why it matters: authoritative reference on `GitHub Repository` (github.com).
-- [API Reference](https://github.com/bytedance/deer-flow/blob/main/docs/API.md)
- Why it matters: authoritative reference on `API Reference` (github.com).
-- [Community & Issues](https://github.com/bytedance/deer-flow/issues)
- Why it matters: authoritative reference on `Community & Issues` (github.com).
-- [Workflow Examples](https://github.com/bytedance/deer-flow/tree/main/examples)
- Why it matters: authoritative reference on `Workflow Examples` (github.com).
-- [AI Codebase Knowledge Builder](https://github.com/johnxie/awesome-code-docs)
- Why it matters: authoritative reference on `AI Codebase Knowledge Builder` (github.com).
-
-Suggested trace strategy:
-- search upstream code for `Task` and `deer` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
-
## Chapter Connections
- [Tutorial Index](README.md)
-- [Next Chapter: Chapter 2: Workflow Basics](02-workflow-basics.md)
+- [Next Chapter: Chapter 2: LangGraph Architecture and Agent Orchestration](02-langgraph-architecture.md)
- [Main Catalog](../../README.md#-tutorial-catalog)
- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
diff --git a/tutorials/deer-flow-tutorial/02-langgraph-architecture.md b/tutorials/deer-flow-tutorial/02-langgraph-architecture.md
new file mode 100644
index 00000000..1ad03d16
--- /dev/null
+++ b/tutorials/deer-flow-tutorial/02-langgraph-architecture.md
@@ -0,0 +1,345 @@
+---
+layout: default
+title: "Chapter 2: LangGraph Architecture and Agent Orchestration"
+parent: "DeerFlow Tutorial"
+nav_order: 2
+format_version: v2
+why: "DeerFlow's control flow is entirely driven by a LangGraph state machine. Understanding how the graph is compiled, how the middleware chain wraps invocations, and how state is checkpointed is the foundation for debugging, extending, and scaling the system."
+mental_model: "The lead_agent is a compiled LangGraph graph with a single node that loops: call LLM → dispatch tool calls → update state → repeat until the LLM returns a final message. The 14-stage middleware pipeline wraps this loop, injecting infrastructure concerns (sandbox, memory, summarization, vision) without polluting the core LLM call."
+learning_outcomes:
+ - Explain how LangGraph's StateGraph compiles into the lead_agent runtime
+ - Trace the 14-stage middleware pipeline in execution order
+ - Understand how ThreadState is extended and checkpointed
+ - Understand how sub-agents are spawned via task_tool with concurrency limits
+snapshot:
+ repo: bytedance/deer-flow
+ stars: ~53.5k
+ last_checked: 2026-04-12
+chapter_map:
+ - "01: Installation and first query"
+ - "02 (this): LangGraph state machine internals"
+ - "03: Research pipeline deep dive"
+ - "04: RAG and search tools"
+ - "05: Frontend and API design"
+ - "06: Skills and extensions"
+ - "07: Podcast and multi-modal outputs"
+ - "08: Production deployment"
+sources:
+ - https://github.com/bytedance/deer-flow/blob/main/backend/packages/harness/deerflow/agents/lead_agent/agent.py
+ - https://github.com/bytedance/deer-flow/blob/main/backend/packages/harness/deerflow/agents/factory.py
+ - https://github.com/bytedance/deer-flow/blob/main/backend/packages/harness/deerflow/agents/thread_state.py
+ - https://github.com/bytedance/deer-flow/blob/main/backend/langgraph.json
+ - https://github.com/bytedance/deer-flow/blob/main/backend/docs/ARCHITECTURE.md
+---
+
+# Chapter 2: LangGraph Architecture and Agent Orchestration
+
+## What Problem Does This Solve?
+
+Agentic systems that use raw LLM loops fail in production. Without a proper state machine, you lose the ability to:
+- Resume a long-running research session after a crash or timeout
+- Inject infrastructure concerns (sandbox setup, memory loading, context summarization) without tangling them with LLM call logic
+- Enforce safety constraints (loop detection, sub-agent concurrency limits) at a consistent layer
+- Support human-in-the-loop interrupts (clarification requests) that pause execution and wait for user input
+
+DeerFlow solves these problems by building on LangGraph as its state machine runtime. Every agent invocation is a step in a compiled graph with explicit state, explicit transitions, and an async checkpointer that snapshots state after every node execution. The 14-stage middleware pipeline handles infrastructure concerns in a clean, ordered chain that is composable and testable independently of the LLM.
+
+## How it Works Under the Hood
+
+### The LangGraph Graph Definition
+
+DeerFlow registers a single graph called `lead_agent` in `backend/langgraph.json`:
+
+```json
+{
+ "python_version": "3.12",
+ "graphs": {
+ "lead_agent": "deerflow.agents:make_lead_agent"
+ },
+ "dependencies": ["."],
+ "env": ".env"
+}
+```
+
+The `make_lead_agent()` factory function constructs the full agent graph:
+
+```python
+# backend/packages/harness/deerflow/agents/lead_agent/agent.py
+def make_lead_agent(config: RunnableConfig | None = None):
+ """
+ Entry point registered in langgraph.json.
+ Creates the compiled StateGraph that is the lead_agent runtime.
+ """
+ agent = create_deerflow_agent(
+ model=resolve_model(config), # From config.yaml models list
+ tools=build_tools(config), # web_search, bash, file ops, MCP tools
+ system_prompt=load_soul_prompt(),
+ features=AgentFeatures(
+ subagent=True, # Enable task_tool for sub-agents
+ memory=True, # Enable cross-session memory
+ sandbox=True, # Enable code execution sandbox
+ vision=True, # Enable image processing
+ plan_mode=False, # Todo-list mode (off by default)
+ ),
+ checkpointer=make_checkpointer(), # Async SQLite or Postgres checkpointer
+ )
+ return agent
+```
+
+### The Agent Factory
+
+The `create_deerflow_agent()` factory in `agents/factory.py` is the core assembly point. It accepts a model, tools, and either a `features` flags object or a custom `middleware` list:
+
+```python
+# backend/packages/harness/deerflow/agents/factory.py
+def create_deerflow_agent(
+ model: BaseChatModel,
+ tools: list[BaseTool] | None = None,
+ system_prompt: str | None = None,
+ middleware: list[Middleware] | None = None,
+ features: AgentFeatures | None = None,
+ plan_mode: bool = False,
+ state_schema: type = ThreadState,
+ checkpointer: BaseCheckpointSaver | None = None,
+ name: str = "lead_agent",
+) -> CompiledGraph:
+ """
+ The factory assembly is config-free. Some injected runtime components
+ (e.g., task_tool for subagent) may still read global config at invocation time.
+ """
+ resolved_middleware = middleware or build_middleware_chain(features, plan_mode)
+ agent = create_agent(
+ model=model,
+ tools=tools or [],
+ system_prompt=system_prompt,
+ middleware=resolved_middleware,
+ state_schema=state_schema,
+ )
+ return agent.compile(checkpointer=checkpointer, name=name)
+```
+
+Note the key design principle stated in the source: **"The factory assembly itself reads no config files."** Configuration is injected at construction time, not read at invocation time. This makes the factory fully testable in isolation.
+
+### The Full State Machine Flow
+
+```mermaid
+stateDiagram-v2
+ [*] --> ThreadInit: User submits message
+ ThreadInit --> MiddlewareChain: Thread state loaded from checkpointer
+
+ state MiddlewareChain {
+ [*] --> ThreadDataMiddleware
+ ThreadDataMiddleware --> UploadsMiddleware
+ UploadsMiddleware --> SandboxMiddleware
+ SandboxMiddleware --> SummarizationMiddleware
+ SummarizationMiddleware --> TitleMiddleware
+ TitleMiddleware --> TodoListMiddleware
+ TodoListMiddleware --> ViewImageMiddleware
+ ViewImageMiddleware --> ClarificationMiddleware
+ }
+
+ MiddlewareChain --> LLMInvoke: Processed state
+ LLMInvoke --> ToolDispatch: LLM returns tool calls
+ ToolDispatch --> ToolExecution: Route to correct tool handler
+ ToolExecution --> StateUpdate: Tool results accumulated
+ StateUpdate --> LLMInvoke: Continue loop (not done)
+ StateUpdate --> FinalResponse: LLM returns no tool calls
+ FinalResponse --> Checkpointer: Persist final state
+ Checkpointer --> [*]: Stream final tokens to client
+
+ LLMInvoke --> ClarificationInterrupt: ask_clarification tool call
+ ClarificationInterrupt --> [*]: Halt, wait for user response
+```
+
+### The 14-Stage Middleware Pipeline
+
+Every agent invocation passes through an ordered chain of middlewares. Order matters — later middlewares can rely on earlier ones having executed:
+
+```mermaid
+graph TD
+ A[Incoming State] --> B[1. ThreadDataMiddleware<br/>Initialize workspace paths for this thread]
+ B --> C[2. UploadsMiddleware<br/>Process attached files, convert to Markdown]
+ C --> D[3. SandboxMiddleware<br/>Acquire Docker container or local executor]
+ D --> E[4. SummarizationMiddleware<br/>Compress old context when token limit approaches]
+ E --> F[5. TitleMiddleware<br/>Auto-generate conversation title after first response]
+ F --> G[6. TodoListMiddleware<br/>Track task checklist in plan mode]
+ G --> H[7. TokenUsageMiddleware<br/>Track and expose token consumption]
+ H --> I[8. MemoryMiddleware<br/>Queue facts for cross-session memory updater]
+ I --> J[9. ViewImageMiddleware<br/>Enable vision: convert image paths to base64]
+ J --> K[10. DeferredToolFilterMiddleware<br/>Remove tools not yet available to this model]
+ K --> L[11. SubagentLimitMiddleware<br/>Throttle concurrent task_tool calls to max N]
+ L --> M[12. LoopDetectionMiddleware<br/>Detect and break infinite tool-call loops]
+ M --> N[13. DanglingToolCallMiddleware<br/>Handle malformed/incomplete tool call responses]
+ N --> O[14. ClarificationMiddleware<br/>Intercept ask_clarification — MUST BE LAST]
+ O --> P[LLM Invocation]
+```
+
+**Why ClarificationMiddleware must be last:** It intercepts `ask_clarification` tool calls and halts execution by returning a `Command(goto=END)`. Running it last ensures it captures edge cases that only appear after the full middleware chain processes the state.
+
+### ThreadState: The State Schema
+
+DeerFlow extends LangGraph's `AgentState` with agent-specific fields:
+
+```python
+# backend/packages/harness/deerflow/agents/thread_state.py
+from langgraph.prebuilt import AgentState
+from typing import Annotated
+
+class SandboxState(TypedDict):
+ sandbox_id: str | None # Docker container ID
+
+class ThreadDataState(TypedDict):
+ workspace_path: str | None # /mnt/user-data/workspace/{thread_id}/
+ uploads_path: str | None # /mnt/user-data/uploads/{thread_id}/
+ outputs_path: str | None # /mnt/user-data/outputs/{thread_id}/
+
+class ViewedImageData(TypedDict):
+ base64: str
+ mime_type: str
+
+class ThreadState(AgentState):
+ sandbox: SandboxState | None
+ thread_data: ThreadDataState | None
+ title: str | None
+ artifacts: Annotated[list[str], merge_artifacts] # Custom reducer: append-only
+ todos: list | None
+ uploaded_files: list[dict] | None
+ viewed_images: Annotated[dict[str, ViewedImageData], merge_viewed_images]
+```
+
+The `artifacts` and `viewed_images` fields use custom **reducers** — functions that merge partial state updates. When a node returns a partial state update, LangGraph uses the reducer to merge it into the full state rather than overwriting it.
+
+### Async Checkpointing
+
+State is persisted asynchronously after every node execution:
+
+```python
+# backend/packages/harness/deerflow/agents/checkpointer/async_provider.py
+def make_checkpointer() -> BaseCheckpointSaver:
+ """
+ Factory function registered in langgraph.json.
+ Returns an async-capable checkpointer.
+ Development: SQLite-backed
+ Production: Postgres-backed via LangGraph Platform
+ """
+ ...
+```
+
+This enables:
+- **Resumability**: Stop a 30-minute research run and resume it exactly where it left off
+- **Branching**: Fork a thread at any checkpoint to explore an alternative direction
+- **Human-in-the-loop**: Halt at `ClarificationMiddleware`, wait for user response, resume
+- **Parallelism**: Multiple concurrent threads without state interference
+
+### Sub-Agent Orchestration via task_tool
+
+When the `subagent` feature flag is enabled, the lead agent gains access to `task_tool`. The agent calls this tool to spawn a sub-agent with isolated context and tools:
+
+```python
+# Conceptual model of task_tool behavior
+async def task_tool(
+ instruction: str, # What the sub-agent should do
+ tools: list[str], # Which tool groups to give the sub-agent
+ context: str | None, # Relevant context to inject
+) -> str:
+ """
+ Creates a new DeerFlow agent instance with minimal context,
+ executes the instruction, and returns the result as a string.
+
+ SubagentLimitMiddleware throttles concurrent calls to max N (default: 3).
+ """
+ sub_agent = create_deerflow_agent(
+ model=resolve_model(),
+ tools=resolve_tools(tools),
+ # Sub-agents do not spawn further sub-agents
+ features=AgentFeatures(subagent=False),
+ )
+ result = await sub_agent.ainvoke({"messages": [HumanMessage(instruction)]})
+ return result["messages"][-1].content
+```
+
+The lead agent's system prompt enforces a hard constraint: *"maximum [N] `task` calls per response."* If a research task requires more parallelism, the agent batches them across multiple response turns automatically.
+
+```mermaid
+graph TB
+ subgraph "Lead Agent Turn 1 - 3 concurrent sub-agents"
+ A[Lead Agent] -->|task: research angle A| B[Sub-Agent 1<br/>web_search + read]
+ A -->|task: research angle B| C[Sub-Agent 2<br/>web_search + read]
+ A -->|task: code analysis| D[Sub-Agent 3<br/>bash + file ops]
+ end
+
+ subgraph "Lead Agent Turn 2 - more if needed"
+ E[Lead Agent] -->|task: research angle C| F[Sub-Agent 4]
+ E -->|task: data processing| G[Sub-Agent 5]
+ end
+
+ B --> H[Aggregate in Lead Context]
+ C --> H
+ D --> H
+ F --> H
+ G --> H
+ H --> I[Synthesize Final Report]
+```
+
+### Model Resolution and Capability Validation
+
+The agent resolves which model to use through a three-level fallback chain:
+
+1. **Requested model** — specified in the API call (`X-Model` header or request body)
+2. **Agent config model** — from `workspace/agents/{agent_name}/config.yaml`
+3. **Global default** — first model in `config.yaml`'s `models` list
+
+After resolution, the factory validates that the model supports any required features:
+
+```python
+# Capability flags validated before agent compilation
+supports_thinking: bool # enables extended reasoning / thinking tokens
+supports_vision: bool # enables image inputs
+supports_reasoning_effort: bool # advanced reasoning control
+```
+
+If the selected model does not support `supports_vision` but the `ViewImageMiddleware` is in the chain, the factory either raises an error or degrades gracefully depending on the `allow_degradation` configuration.
+
+### Loop Detection
+
+`LoopDetectionMiddleware` watches the message history for repeated tool call patterns. If the agent calls the same tool with the same arguments above a configurable threshold, the middleware injects a system message:
+
+```python
+# Conceptual behavior of LoopDetectionMiddleware
+if repeated_tool_call_count > LOOP_THRESHOLD:
+ state["messages"].append(SystemMessage(
+ content=(
+ "You appear to be repeating the same tool call. "
+ "Stop and synthesize your findings with what you have so far."
+ )
+ ))
+```
+
+This prevents the most common failure mode in production LLM agent systems: infinite loops on ambiguous or unchanged tool results.
+
+## Key Architecture Principles
+
+| Principle | Implementation |
+|:--|:--|
+| State-machine-first | LangGraph StateGraph with explicit node/edge definitions |
+| Config-free factory | `create_deerflow_agent()` accepts injected dependencies only |
+| Middleware separation | Infrastructure concerns in 14-stage chain, not in LLM prompt |
+| Async by default | All I/O (tools, sandbox, checkpointer) is async |
+| Thread isolation | Per-thread workspace paths, sandbox containers, and state |
+| Safe by default | Loop detection, sub-agent limits, clarification halting |
+
+## Summary
+
+DeerFlow's LangGraph architecture provides a compiled `StateGraph` with explicit `ThreadState`, an async checkpointer, and a 14-stage middleware pipeline that cleanly separates infrastructure from LLM logic. Sub-agents are spawned via `task_tool` with concurrency limits enforced at the middleware layer. The config-free factory pattern makes the system composable and testable.
+
+In the next chapter, we trace a complete research query through the pipeline from submission to final report, including how web search results accumulate, how context is summarized to stay within token limits, and how citations are tracked.
+
+---
+
+## Chapter Connections
+
+- [Tutorial Index](README.md)
+- [Previous Chapter: Chapter 1: Getting Started](01-getting-started.md)
+- [Next Chapter: Chapter 3: Research Agent Pipeline](03-research-agent-pipeline.md)
+- [Main Catalog](../../README.md#-tutorial-catalog)
+- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
diff --git a/tutorials/deer-flow-tutorial/02-workflow-basics.md b/tutorials/deer-flow-tutorial/02-workflow-basics.md
deleted file mode 100644
index 6a5816cb..00000000
--- a/tutorials/deer-flow-tutorial/02-workflow-basics.md
+++ /dev/null
@@ -1,525 +0,0 @@
----
-layout: default
-title: "Chapter 2: Workflow Basics"
-parent: "Deer Flow Tutorial"
-nav_order: 2
----
-
-# Chapter 2: Workflow Basics
-
-Welcome to **Chapter 2: Workflow Basics**. In this part of **Deer Flow Tutorial: Distributed Workflow Orchestration Platform**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
-
-
-> Learn to create and manage basic workflows with Deer Flow's workflow definition system.
-
-## Overview
-
-Workflows are the core abstraction in Deer Flow. They define a series of tasks, their relationships, and execution parameters. This chapter covers fundamental workflow concepts and creation patterns.
-
-## Workflow Structure
-
-### Anatomy of a Workflow
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│ Deer Flow Workflow │
-├─────────────────────────────────────────────────────────────────┤
-│ │
-│ ┌─────────────────────────────────────────────────────────┐ │
-│ │ Workflow Metadata │ │
-│ │ - Name, ID, Description │ │
-│ │ - Version, Tags, Labels │ │
-│ │ - Schedule, Triggers │ │
-│ └─────────────────────────────────────────────────────────┘ │
-│ │ │
-│ ▼ │
-│ ┌─────────────────────────────────────────────────────────┐ │
-│ │ Task Definitions │ │
-│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
-│ │ │ Task A │──▶│ Task B │──▶│ Task C │ │ │
-│ │ └─────────┘ └─────────┘ └─────────┘ │ │
-│ │ │ │ │ │
-│ │ └────────────┬───────────────┘ │ │
-│ │ ▼ │ │
-│ │ ┌─────────┐ │ │
-│ │ │ Task D │ │ │
-│ │ └─────────┘ │ │
-│ └─────────────────────────────────────────────────────────┘ │
-│ │ │
-│ ▼ │
-│ ┌─────────────────────────────────────────────────────────┐ │
-│ │ Execution Configuration │ │
-│ │ - Retry policies, Timeouts │ │
-│ │ - Resource requirements │ │
-│ │ - Notifications, Callbacks │ │
-│ └─────────────────────────────────────────────────────────┘ │
-│ │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-### Workflow Definition Format
-
-```json
-{
- "name": "data_pipeline",
- "version": "1.0.0",
- "description": "Daily data processing pipeline",
- "metadata": {
- "owner": "data-team",
- "tags": ["etl", "daily"]
- },
- "tasks": [
- {
- "id": "extract",
- "type": "python",
- "config": {
- "script": "extract_data.py"
- }
- },
- {
- "id": "transform",
- "type": "python",
- "depends_on": ["extract"],
- "config": {
- "script": "transform_data.py"
- }
- },
- {
- "id": "load",
- "type": "python",
- "depends_on": ["transform"],
- "config": {
- "script": "load_data.py"
- }
- }
- ],
- "schedule": "0 2 * * *"
-}
-```
-
-## Creating Workflows
-
-### Using the CLI
-
-```bash
-# Create workflow from file
-deerflow create -f workflow.json
-
-# Create workflow with inline definition
-deerflow create --name "my_workflow" \
- --task "step1:shell:echo Hello" \
- --task "step2:shell:echo World" \
- --depends "step2:step1"
-
-# List workflows
-deerflow list
-
-# Get workflow details
-deerflow get my_workflow
-
-# Delete workflow
-deerflow delete my_workflow
-```
-
-### Using the Python SDK
-
-```python
-from deerflow import Workflow, Task, ShellTask, PythonTask
-
-# Create workflow
-workflow = Workflow(
- name="data_pipeline",
- description="Daily data processing"
-)
-
-# Add tasks
-extract = ShellTask(
- id="extract",
- command="python extract.py"
-)
-
-transform = PythonTask(
- id="transform",
- script="transform.py",
- depends_on=["extract"]
-)
-
-load = PythonTask(
- id="load",
- script="load.py",
- depends_on=["transform"]
-)
-
-workflow.add_tasks([extract, transform, load])
-
-# Register workflow
-workflow.register()
-```
-
-### Using the REST API
-
-```bash
-# Create workflow via API
-curl -X POST http://localhost:8080/api/workflows \
- -H "Content-Type: application/json" \
- -d '{
- "name": "api_workflow",
- "tasks": [
- {"id": "task1", "type": "shell", "command": "echo Hello"}
- ]
- }'
-
-# Get workflow
-curl http://localhost:8080/api/workflows/api_workflow
-
-# Update workflow
-curl -X PUT http://localhost:8080/api/workflows/api_workflow \
- -H "Content-Type: application/json" \
- -d @updated_workflow.json
-```
-
-## Task Types
-
-### Shell Tasks
-
-```json
-{
- "id": "shell_task",
- "type": "shell",
- "config": {
- "command": "python script.py",
- "working_dir": "/app/scripts",
- "env": {
- "ENV_VAR": "value"
- },
- "timeout": 3600
- }
-}
-```
-
-### Python Tasks
-
-```json
-{
- "id": "python_task",
- "type": "python",
- "config": {
- "script": "process_data.py",
- "function": "main",
- "args": ["arg1", "arg2"],
- "kwargs": {"key": "value"},
- "requirements": ["pandas", "numpy"]
- }
-}
-```
-
-### HTTP Tasks
-
-```json
-{
- "id": "api_call",
- "type": "http",
- "config": {
- "method": "POST",
- "url": "https://api.example.com/webhook",
- "headers": {
- "Authorization": "Bearer ${API_TOKEN}"
- },
- "body": {
- "data": "${task.previous.output}"
- },
- "timeout": 30,
- "retry": {
- "max_attempts": 3,
- "backoff": "exponential"
- }
- }
-}
-```
-
-### Docker Tasks
-
-```json
-{
- "id": "docker_task",
- "type": "docker",
- "config": {
- "image": "python:3.11",
- "command": ["python", "script.py"],
- "volumes": [
- "/data:/app/data"
- ],
- "environment": {
- "ENV": "production"
- },
- "resources": {
- "memory": "2Gi",
- "cpu": "1"
- }
- }
-}
-```
-
-## Workflow Execution
-
-### Running Workflows
-
-```bash
-# Run workflow immediately
-deerflow run my_workflow
-
-# Run with parameters
-deerflow run my_workflow --param date=2024-01-15 --param env=prod
-
-# Run specific tasks only
-deerflow run my_workflow --task transform --task load
-
-# Dry run (validate without executing)
-deerflow run my_workflow --dry-run
-```
-
-### Execution States
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│ Workflow Execution States │
-├─────────────────────────────────────────────────────────────────┤
-│ │
-│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
-│ │ PENDING │──▶│ RUNNING │──▶│ SUCCESS │ │ │ │
-│ └─────────┘ └────┬────┘ └─────────┘ │ │ │
-│ │ │ SKIPPED │ │
-│ ▼ │ │ │
-│ ┌─────────┐ └─────────┘ │
-│ │ FAILED │ │
-│ └────┬────┘ │
-│ │ │
-│ ▼ │
-│ ┌─────────┐ ┌─────────┐ │
-│ │ RETRY │──▶│ SUCCESS │ │
-│ └─────────┘ │ /FAILED │ │
-│ └─────────┘ │
-│ │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-### Monitoring Execution
-
-```bash
-# Watch execution in real-time
-deerflow watch execution_id
-
-# Get execution status
-deerflow status execution_id
-
-# Get execution logs
-deerflow logs execution_id
-deerflow logs execution_id --task transform
-
-# List recent executions
-deerflow executions --workflow my_workflow --limit 10
-```
-
-## Input and Output
-
-### Task Parameters
-
-```json
-{
- "id": "parameterized_task",
- "type": "python",
- "config": {
- "script": "process.py",
- "args": [
- "${params.date}",
- "${params.environment}"
- ]
- }
-}
-```
-
-### Passing Data Between Tasks
-
-```json
-{
- "tasks": [
- {
- "id": "fetch_data",
- "type": "python",
- "config": {
- "script": "fetch.py"
- },
- "outputs": ["data_path", "record_count"]
- },
- {
- "id": "process_data",
- "type": "python",
- "depends_on": ["fetch_data"],
- "config": {
- "script": "process.py",
- "args": [
- "${tasks.fetch_data.outputs.data_path}"
- ]
- }
- }
- ]
-}
-```
-
-### Using Python SDK for Data Flow
-
-```python
-from deerflow import Workflow, PythonTask, Output
-
-workflow = Workflow(name="data_flow_example")
-
-@workflow.task(id="producer")
-def produce_data():
- data = {"records": 100, "file": "/tmp/data.csv"}
- return Output(data)
-
-@workflow.task(id="consumer", depends_on=["producer"])
-def consume_data(producer_output):
- print(f"Processing {producer_output['records']} records")
- print(f"File: {producer_output['file']}")
-```
-
-## Scheduling
-
-### Cron Schedules
-
-```json
-{
- "name": "scheduled_workflow",
- "schedule": {
- "type": "cron",
- "expression": "0 2 * * *",
- "timezone": "UTC"
- },
- "tasks": [...]
-}
-```
-
-### Interval Schedules
-
-```json
-{
- "name": "interval_workflow",
- "schedule": {
- "type": "interval",
- "every": "1h",
- "start_time": "2024-01-01T00:00:00Z"
- },
- "tasks": [...]
-}
-```
-
-### Event Triggers
-
-```json
-{
- "name": "event_triggered",
- "triggers": [
- {
- "type": "webhook",
- "path": "/trigger/my_workflow"
- },
- {
- "type": "file",
- "path": "/data/incoming/*.csv",
- "event": "created"
- },
- {
- "type": "queue",
- "queue": "workflow-triggers",
- "filter": {"type": "process_request"}
- }
- ],
- "tasks": [...]
-}
-```
-
-## Summary
-
-In this chapter, you've learned:
-
-- **Workflow Structure**: Metadata, tasks, and execution configuration
-- **Creating Workflows**: CLI, SDK, and API methods
-- **Task Types**: Shell, Python, HTTP, and Docker tasks
-- **Execution**: Running, monitoring, and managing workflows
-- **Data Flow**: Parameters and task outputs
-- **Scheduling**: Cron, interval, and event triggers
-
-## Key Takeaways
-
-1. **JSON Definitions**: Workflows are declaratively defined
-2. **Multiple Task Types**: Choose the right task type for each job
-3. **Flexible Execution**: Run immediately or schedule
-4. **Data Passing**: Tasks can share outputs
-5. **Event-Driven**: Trigger workflows from various sources
-
-## Next Steps
-
-Ready to explore different task types in depth? Let's dive into Chapter 3.
-
----
-
-**Ready for Chapter 3?** [Task Management](03-task-management.md)
-
-*Generated for [Awesome Code Docs](https://github.com/johnxie/awesome-code-docs)*
-
-## What Problem Does This Solve?
-
-Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for `workflow`, `deerflow`, `python` so behavior stays predictable as complexity grows.
-
-In practical terms, this chapter helps you avoid three common failures:
-
-- coupling core logic too tightly to one implementation path
-- missing the handoff boundaries between setup, execution, and validation
-- shipping changes without clear rollback or observability strategy
-
-After working through this chapter, you should be able to reason about `Chapter 2: Workflow Basics` as an operating subsystem inside **Deer Flow Tutorial: Distributed Workflow Orchestration Platform**, with explicit contracts for inputs, state transitions, and outputs.
-
-Use the implementation notes around `script`, `config`, `tasks` as your checklist when adapting these patterns to your own repository.
-
-## How it Works Under the Hood
-
-Under the hood, `Chapter 2: Workflow Basics` usually follows a repeatable control path:
-
-1. **Context bootstrap**: initialize runtime config and prerequisites for `workflow`.
-2. **Input normalization**: shape incoming data so `deerflow` receives stable contracts.
-3. **Core execution**: run the main logic branch and propagate intermediate state through `python`.
-4. **Policy and safety checks**: enforce limits, auth scopes, and failure boundaries.
-5. **Output composition**: return canonical result payloads for downstream consumers.
-6. **Operational telemetry**: emit logs/metrics needed for debugging and performance tuning.
-
-When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
-
-## Source Walkthrough
-
-Use the following upstream sources to verify implementation details while reading this chapter:
-
-- [Official Documentation](https://github.com/bytedance/deer-flow/tree/main/docs)
- Why it matters: authoritative reference on `Official Documentation` (github.com).
-- [GitHub Repository](https://github.com/bytedance/deer-flow)
- Why it matters: authoritative reference on `GitHub Repository` (github.com).
-- [API Reference](https://github.com/bytedance/deer-flow/blob/main/docs/API.md)
- Why it matters: authoritative reference on `API Reference` (github.com).
-- [Community & Issues](https://github.com/bytedance/deer-flow/issues)
- Why it matters: authoritative reference on `Community & Issues` (github.com).
-- [Workflow Examples](https://github.com/bytedance/deer-flow/tree/main/examples)
- Why it matters: authoritative reference on `Workflow Examples` (github.com).
-- [AI Codebase Knowledge Builder](https://github.com/johnxie/awesome-code-docs)
- Why it matters: authoritative reference on `AI Codebase Knowledge Builder` (github.com).
-
-Suggested trace strategy:
-- search upstream code for `workflow` and `deerflow` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
-
-## Chapter Connections
-
-- [Tutorial Index](README.md)
-- [Previous Chapter: Chapter 1: Getting Started with Deer Flow](01-getting-started.md)
-- [Next Chapter: Chapter 3: Task Management](03-task-management.md)
-- [Main Catalog](../../README.md#-tutorial-catalog)
-- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
diff --git a/tutorials/deer-flow-tutorial/03-research-agent-pipeline.md b/tutorials/deer-flow-tutorial/03-research-agent-pipeline.md
new file mode 100644
index 00000000..e0161a1a
--- /dev/null
+++ b/tutorials/deer-flow-tutorial/03-research-agent-pipeline.md
@@ -0,0 +1,366 @@
+---
+layout: default
+title: "Chapter 3: Research Agent Pipeline"
+parent: "DeerFlow Tutorial"
+nav_order: 3
+format_version: v2
+why: "Understanding the research pipeline — how DeerFlow decomposes a query, issues multi-angle searches, accumulates evidence, and synthesizes a cited report — is what separates effective use of the system from naive prompt-and-hope interactions."
+mental_model: "The research pipeline is a CLARIFY → PLAN → ACT sequence enforced by the system prompt and ClarificationMiddleware. The agent does not search once and write; it searches iteratively from multiple angles, reading full pages, until it has enough evidence to cover 3-5 research dimensions before synthesizing."
+learning_outcomes:
+ - Trace a deep research query from user input to final report
+ - Understand the four-phase deep research methodology built into the skill
+ - Understand how the system prompt enforces CLARIFY → PLAN → ACT
+ - Understand how citations are tracked and formatted inline
+ - Configure research depth via sub-agent parallelism and search tool selection
+snapshot:
+ repo: bytedance/deer-flow
+ stars: ~53.5k
+ last_checked: 2026-04-12
+chapter_map:
+ - "01: Installation and first query"
+ - "02: LangGraph state machine internals"
+ - "03 (this): Research pipeline deep dive"
+ - "04: RAG and search tools"
+ - "05: Frontend and API design"
+ - "06: Skills and extensions"
+ - "07: Podcast and multi-modal outputs"
+ - "08: Production deployment"
+sources:
+ - https://github.com/bytedance/deer-flow/blob/main/backend/packages/harness/deerflow/agents/lead_agent/prompt.py
+ - https://github.com/bytedance/deer-flow/blob/main/skills/public/deep-research/SKILL.md
+ - https://github.com/bytedance/deer-flow/blob/main/backend/docs/plan_mode_usage.md
+---
+
+# Chapter 3: Research Agent Pipeline
+
+## What Problem Does This Solve?
+
+A naive research agent searches once, reads one page, and writes an answer. This produces shallow, often inaccurate outputs that miss context, conflicting evidence, and recent developments.
+
+DeerFlow's research pipeline solves this by enforcing a structured multi-phase methodology. The Deep Research skill provides a four-phase protocol: broad exploration, deep targeted searching, diversity validation (at least 3-5 angles), and a synthesis check before writing. The system prompt enforces a mandatory `CLARIFY → PLAN → ACT` sequence so the agent never starts work on an ambiguous request. Citations are tracked inline throughout the process using a standard format.
+
+The result is research outputs that cite real sources, cover multiple perspectives, and are reproducible by a human reviewer following the same search trail.
+
+## How it Works Under the Hood
+
+### The System Prompt Architecture
+
+The lead agent's behavior is primarily controlled by its system prompt, loaded at startup from `prompt.py` and a configurable `SOUL.md` file:
+
+```python
+# backend/packages/harness/deerflow/agents/lead_agent/prompt.py
+# Key excerpts from the actual system prompt structure:
+
+SYSTEM_PROMPT = """
+You are an open-source super agent configured with a specific personality.
+
+## Core Operational Protocol
+
+**MANDATORY PRIORITY SEQUENCE: CLARIFY → PLAN → ACT**
+
+1. CLARIFY: When any of the following is true, call ask_clarification immediately:
+ - The request contains missing information required to proceed
+ - Requirements are ambiguous or could be interpreted multiple ways
+ - The approach has multiple valid paths requiring user preference
+ - The operation is risky or irreversible
+
+ NEVER start work and clarify mid-execution. Clarify first, then act.
+
+2. PLAN: Think concisely and strategically before taking action.
+ Identify what is clear, what is ambiguous, and what is missing.
+
+3. ACT: Execute with the tools available, following loaded skills.
+
+## Citation Requirements
+When using external sources, include inline citations immediately after claims:
+Format: [citation:Title](URL)
+
+Include a Sources section at the end listing all references.
+
+## File Management
+- Working directory: /mnt/user-data/workspace/
+- Final deliverables: /mnt/user-data/outputs/
+- Use relative paths within generated scripts
+
+## Skill Loading
+You have access to skills that provide optimized workflows for specific tasks.
+Read the SKILL.md file when a query matches a skill's use case.
+Load referenced skill resources progressively — only when needed.
+"""
+```
+
+The SOUL.md component is loaded from `skills/public/bootstrap/templates/SOUL.template.md` and provides the agent's "personality" — communication style, values, and behavioral norms.
+
+### The Deep Research Skill
+
+The `deep-research` skill (`skills/public/deep-research/SKILL.md`) is the core methodology the agent loads when conducting research. It defines a four-phase protocol:
+
+```mermaid
+graph LR
+ A[Phase 1<br/>Broad Exploration<br/>Survey landscape<br/>identify subtopics] --> B[Phase 2<br/>Deep Dive<br/>Targeted searches<br/>per dimension<br/>read full pages]
+ B --> C[Phase 3<br/>Diversity Validation<br/>Facts, examples,<br/>expert opinions,<br/>trends, criticism]
+ C --> D[Phase 4<br/>Synthesis Check<br/>Verify 3-5 angles<br/>covered before writing]
+ D --> E[Output<br/>Structured report<br/>with inline citations]
+```
+
+Key principles enforced by the skill:
+- **Never generate content based solely on general knowledge.** Research quality directly affects output quality.
+- **Search with temporal awareness.** Use the current date in queries where recency matters.
+- **Fetch full sources.** Do not rely on search snippets — use `web_fetch` to read complete pages.
+- **Success criteria**: Can address key facts, 2-3 concrete examples, expert perspectives, current trends, limitations, and topical relevance.
+
+### Full Research Query Trace
+
+Here is the complete execution path for a research query:
+
+```mermaid
+sequenceDiagram
+ participant U as User
+ participant UI as Next.js Chat
+ participant LG as LangGraph Lead Agent
+ participant LLM as LLM
+ participant DDG as DuckDuckGo / Tavily
+ participant WF as web_fetch tool
+ participant SA as Sub-Agent (if enabled)
+ participant CP as Checkpointer
+
+ U->>UI: "What are the trade-offs between LangGraph and CrewAI?"
+ UI->>LG: POST /threads/{id}/runs (SSE stream)
+ LG->>CP: Load thread state (empty for new thread)
+ LG->>LG: Run 14-stage middleware pipeline
+ LG->>LLM: System prompt + user message
+
+ Note over LLM: Phase 1: Broad Exploration
+ LLM-->>LG: tool_call: web_search("LangGraph architecture overview")
+ LG->>DDG: Execute search
+ DDG-->>LG: 5 result snippets
+ LG->>LLM: Search results
+
+ LLM-->>LG: tool_call: web_search("CrewAI architecture 2025")
+ LG->>DDG: Execute search
+ DDG-->>LG: 5 result snippets
+ LG->>LLM: Search results
+
+ Note over LLM: Phase 2: Deep Dive
+ LLM-->>LG: tool_call: web_fetch("https://langchain.com/langgraph")
+ LG->>WF: Fetch full page
+ WF-->>LG: Full page Markdown (~10k tokens)
+ LG->>LLM: Full page content
+
+ LLM-->>LG: tool_call: web_fetch("https://crewai.com/docs/...")
+ LG->>WF: Fetch full page
+ WF-->>LG: Full page content
+
+ Note over LLM: Phase 3: Diversity Validation
+ LLM-->>LG: tool_call: web_search("LangGraph vs CrewAI performance benchmarks")
+ LG->>DDG: Execute search
+ DDG-->>LG: Results
+
+ Note over LLM: Phase 4: Synthesis
+ LLM-->>LG: Final report (streaming tokens)
+ LG-->>UI: SSE stream of report tokens
+ LG->>CP: Checkpoint final state
+ UI-->>U: Rendered report with citations
+```
+
+### Sub-Agent Parallelism in Research
+
+When sub-agents are enabled and the query is complex, the lead agent decomposes research across concurrent sub-agents:
+
+```python
+# Lead agent's research decomposition strategy (conceptual)
+# The agent generates these task_tool calls in a single response
+
+tasks = [
+ task_tool(
+ instruction="Research LangGraph architecture and state management approach. "
+ "Read at least 3 full sources. Return a structured summary with citations.",
+ tools=["web", "file:read"],
+ ),
+ task_tool(
+ instruction="Research CrewAI architecture, agent roles, and orchestration model. "
+ "Read at least 3 full sources. Return a structured summary with citations.",
+ tools=["web", "file:read"],
+ ),
+ task_tool(
+ instruction="Find recent benchmarks comparing LangGraph and CrewAI: performance, "
+ "developer adoption, GitHub stars, community size. Return data with sources.",
+ tools=["web", "file:read"],
+ ),
+]
+
+# SubagentLimitMiddleware allows max 3 concurrent (default)
+# Results arrive async and are aggregated in lead agent context
+results = await asyncio.gather(*tasks)
+```
+
+### Citation Tracking
+
+The system prompt enforces a strict citation format. Every claim derived from a web source must have an inline citation immediately following it:
+
+```markdown
+LangGraph uses a compiled StateGraph model where control flow is explicit
+[citation:LangGraph Documentation](https://python.langchain.com/docs/langgraph),
+while CrewAI uses a role-based crew model where agents are assigned tasks
+[citation:CrewAI Docs](https://crewai.com/docs/core-concepts).
+
+## Sources
+
+1. [LangGraph Documentation](https://python.langchain.com/docs/langgraph)
+2. [CrewAI Core Concepts](https://crewai.com/docs/core-concepts)
+3. [Agent Framework Comparison 2025](https://example.com/comparison)
+```
+
+This format is enforced at the system prompt level, not by any post-processing code. If the LLM omits a citation, the format is not applied automatically — it is a soft constraint.
+
+### Context Management and Summarization
+
+Long research sessions accumulate large message histories. `SummarizationMiddleware` prevents context overflow:
+
+```python
+# Conceptual behavior of SummarizationMiddleware
+class SummarizationMiddleware:
+ """
+ When token count approaches model's context limit,
+ compress the older portion of the conversation:
+ - Keep the system prompt
+ - Keep the last N messages verbatim
+ - Summarize everything in between
+ - Replace the compressed portion with a summary message
+ """
+ TOKEN_THRESHOLD = 0.8 # Trigger at 80% of model's context window
+
+ async def before_invoke(self, state: ThreadState) -> ThreadState:
+ token_count = count_tokens(state["messages"])
+ if token_count > self.TOKEN_THRESHOLD * self.model_context_limit:
+ summary = await self.summarize_middle_messages(state["messages"])
+ state["messages"] = compress_with_summary(state["messages"], summary)
+ return state
+```
+
+The summarization model can be configured separately from the research model — a cheaper, faster model can handle compression while a more capable model handles research.
+
+### Plan Mode for Explicit Task Tracking
+
+When `plan_mode=True` is set (either globally or per agent), the `TodoListMiddleware` activates. The agent maintains an explicit task list in the thread state:
+
+```mermaid
+graph LR
+ A[User: research request] --> B[Lead Agent creates todo list]
+ B --> C[Todo: research angle A - pending]
+ B --> D[Todo: research angle B - pending]
+ B --> E[Todo: compile report - pending]
+ C --> F[Searches executed]
+ F --> G[Todo: research angle A - done]
+ D --> H[More searches]
+ H --> I[Todo: research angle B - done]
+ G --> J[Report synthesis]
+ I --> J
+ J --> K[Todo: compile report - done]
+```
+
+Todo state is stored in `ThreadState.todos` and rendered in the frontend as a visible progress tracker. This is especially useful for long-running research tasks where the user wants to see progress without reading the full agent output stream.
+
+### Clarification Flow
+
+Before starting any research, the agent may invoke `ask_clarification` if the query is ambiguous. This is intercepted by `ClarificationMiddleware`:
+
+```python
+# ClarificationMiddleware behavior (from source)
+# 1. Detect ask_clarification tool call in LLM response
+# 2. Format the question with type-specific emoji
+# 3. Return Command(goto=END) to halt execution
+# 4. Add a ToolMessage with the formatted question to message history
+# 5. User sees the question in chat UI
+# 6. User responds; new HumanMessage triggers a new run
+# 7. Agent continues from halted state with user's answer
+
+# Example of what the agent sees vs. what the user sees:
+
+# Agent calls:
+ask_clarification(
+ question="What is the target audience for this comparison?",
+ context="Understanding the audience helps tailor the technical depth.",
+ options=["Developers evaluating frameworks", "Managers making build-vs-buy decisions", "Researchers studying multi-agent systems"],
+ type="choice",
+)
+
+# User sees in chat:
+"""
+❓ What is the target audience for this comparison?
+
+Context: Understanding the audience helps tailor the technical depth.
+
+Options:
+1. Developers evaluating frameworks
+2. Managers making build-vs-buy decisions
+3. Researchers studying multi-agent systems
+"""
+```
+
+## Configuring Research Quality
+
+### Choosing the Right Search Provider
+
+| Provider | Quality | Speed | Cost | Config |
+|:--|:--|:--|:--|:--|
+| DuckDuckGo | Good | Fast | Free | `deerflow.community.ddg_search` |
+| Tavily | Excellent | Moderate | Paid | `deerflow.community.tavily` |
+| Exa | Excellent | Fast | Paid | `deerflow.community.exa` |
+| Firecrawl | Best for full-page | Slow | Paid | `deerflow.community.firecrawl` |
+
+```yaml
+# config.yaml — selecting Tavily for higher quality research
+tools:
+ - name: web_search
+ group: web
+ use: deerflow.community.tavily:web_search_tool
+ api_key: $TAVILY_API_KEY
+ max_results: 10
+```
+
+### Tuning Sub-Agent Parallelism
+
+```yaml
+# workspace/agents/lead_agent/config.yaml (per-agent config)
+subagent:
+ enabled: true
+ max_concurrent: 5 # Default: 3. More parallelism = faster research but higher cost
+```
+
+### Research-Specific Model Configuration
+
+For deep research tasks, reasoning models produce significantly better synthesis:
+
+```yaml
+models:
+ - name: o3-mini
+ display_name: o3-mini (Research)
+ use: langchain_openai:ChatOpenAI
+ model: o3-mini
+ api_key: $OPENAI_API_KEY
+ supports_thinking: true
+ supports_reasoning_effort: true
+ when_thinking_enabled:
+ extra_body:
+ reasoning_effort: high
+```
+
+## Summary
+
+The DeerFlow research pipeline is a structured, multi-phase protocol enforced at three levels:
+1. **System prompt** — `CLARIFY → PLAN → ACT` sequence with citation requirements
+2. **Deep Research skill** — four-phase methodology (explore, dive, diversify, synthesize)
+3. **Middleware chain** — `SummarizationMiddleware` for context management, `ClarificationMiddleware` for human-in-the-loop
+
+The pipeline produces cited, multi-angle research reports that are qualitatively different from single-shot LLM answers.
+
+---
+
+## Chapter Connections
+
+- [Tutorial Index](README.md)
+- [Previous Chapter: Chapter 2: LangGraph Architecture](02-langgraph-architecture.md)
+- [Next Chapter: Chapter 4: RAG, Search, and Knowledge Synthesis](04-rag-search-knowledge.md)
+- [Main Catalog](../../README.md#-tutorial-catalog)
+- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
diff --git a/tutorials/deer-flow-tutorial/03-task-management.md b/tutorials/deer-flow-tutorial/03-task-management.md
deleted file mode 100644
index e28018f6..00000000
--- a/tutorials/deer-flow-tutorial/03-task-management.md
+++ /dev/null
@@ -1,559 +0,0 @@
----
-layout: default
-title: "Chapter 3: Task Management"
-parent: "Deer Flow Tutorial"
-nav_order: 3
----
-
-# Chapter 3: Task Management
-
-Welcome to **Chapter 3: Task Management**. In this part of **Deer Flow Tutorial: Distributed Workflow Orchestration Platform**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
-
-
-> Deep dive into task types, execution modes, and configuration options in Deer Flow.
-
-## Overview
-
-Tasks are the fundamental execution units in Deer Flow. Understanding the various task types and their configuration options is essential for building effective workflows.
-
-## Task Architecture
-
-### Task Lifecycle
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│ Task Lifecycle │
-├─────────────────────────────────────────────────────────────────┤
-│ │
-│ ┌─────────┐ ┌──────────┐ ┌─────────┐ ┌──────────┐ │
-│ │ CREATED │──▶│ SCHEDULED│──▶│ QUEUED │──▶│ ASSIGNED │ │
-│ └─────────┘ └──────────┘ └─────────┘ └──────────┘ │
-│ │ │
-│ ▼ │
-│ ┌─────────┐ │
-│ │ RUNNING │ │
-│ └────┬────┘ │
-│ ┌────────────────────────┼────────┐ │
-│ ▼ ▼ ▼ │
-│ ┌─────────┐ ┌─────────┐ ┌─────┐ │
-│ │ SUCCESS │ │ FAILED │ │KILLED│ │
-│ └─────────┘ └────┬────┘ └─────┘ │
-│ │ │
-│ ▼ │
-│ ┌─────────┐ │
-│ │ RETRY │ │
-│ └─────────┘ │
-│ │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-### Task Components
-
-```python
-from deerflow import Task
-
-class TaskDefinition:
- # Identity
- id: str # Unique task identifier
- name: str # Human-readable name
- type: str # Task type (shell, python, http, etc.)
-
- # Dependencies
- depends_on: List[str] # Tasks that must complete first
- condition: str # Conditional execution expression
-
- # Configuration
- config: Dict # Task-type specific configuration
- timeout: int # Maximum execution time
- retries: int # Retry attempts on failure
-
- # Resources
- resources: Dict # CPU, memory, etc.
- labels: Dict # Metadata labels
-```
-
-## Built-in Task Types
-
-### Shell Task
-
-```python
-from deerflow import ShellTask
-
-task = ShellTask(
- id="run_script",
- command="python process.py --input ${input_file}",
- working_dir="/app/scripts",
- env={
- "PYTHONPATH": "/app/lib",
- "DEBUG": "true"
- },
- shell="/bin/bash",
- timeout=3600
-)
-```
-
-```json
-{
- "id": "shell_example",
- "type": "shell",
- "config": {
- "command": "python process.py",
- "working_dir": "/app",
- "env": {
- "ENV": "production"
- },
- "capture_output": true,
- "timeout": 3600
- }
-}
-```
-
-### Python Task
-
-```python
-from deerflow import PythonTask
-
-# Script-based
-task = PythonTask(
- id="process_data",
- script="/app/scripts/process.py",
- function="main",
- args=["arg1", "arg2"],
- kwargs={"verbose": True},
- python_version="3.11",
- requirements=["pandas>=2.0", "numpy"]
-)
-
-# Inline function
-@workflow.python_task(id="inline_task")
-def process_records(input_data):
- import pandas as pd
- df = pd.DataFrame(input_data)
- return df.to_dict()
-```
-
-### HTTP Task
-
-```python
-from deerflow import HTTPTask
-
-task = HTTPTask(
- id="call_api",
- method="POST",
- url="https://api.example.com/process",
- headers={
- "Content-Type": "application/json",
- "Authorization": "Bearer ${secrets.API_TOKEN}"
- },
- body={
- "data": "${tasks.previous.output}",
- "timestamp": "${now()}"
- },
- timeout=30,
- retry=RetryConfig(max_attempts=3, backoff="exponential")
-)
-```
-
-### Docker Task
-
-```python
-from deerflow import DockerTask
-
-task = DockerTask(
- id="containerized_job",
- image="myregistry/processor:latest",
- command=["python", "main.py"],
- volumes=[
- "/data:/app/data:ro",
- "/output:/app/output:rw"
- ],
- environment={
- "CONFIG_PATH": "/app/config.yaml"
- },
- resources={
- "memory": "4Gi",
- "cpu": "2",
- "gpu": "1"
- },
- pull_policy="IfNotPresent"
-)
-```
-
-### Kubernetes Task
-
-```python
-from deerflow import KubernetesTask
-
-task = KubernetesTask(
- id="k8s_job",
- namespace="workflows",
- pod_spec={
- "containers": [{
- "name": "worker",
- "image": "processor:latest",
- "resources": {
- "requests": {"memory": "1Gi", "cpu": "500m"},
- "limits": {"memory": "2Gi", "cpu": "1"}
- }
- }],
- "restartPolicy": "Never"
- },
- service_account="workflow-runner"
-)
-```
-
-### SQL Task
-
-```python
-from deerflow import SQLTask
-
-task = SQLTask(
- id="run_query",
- connection="postgres://user:pass@host:5432/db",
- query="""
- INSERT INTO results (date, count, total)
- SELECT
- CURRENT_DATE,
- COUNT(*),
- SUM(amount)
- FROM transactions
- WHERE date = '${params.date}'
- """,
- fetch_results=True
-)
-```
-
-### Spark Task
-
-```python
-from deerflow import SparkTask
-
-task = SparkTask(
- id="spark_etl",
- application="/app/jobs/etl_job.py",
- master="spark://spark-master:7077",
- deploy_mode="cluster",
- executor_memory="4g",
- executor_cores=2,
- num_executors=10,
- spark_conf={
- "spark.sql.shuffle.partitions": "200"
- },
- args=["--date", "${params.date}"]
-)
-```
-
-## Custom Task Types
-
-### Creating Custom Tasks
-
-```python
-from deerflow import TaskType, register_task_type
-
-@register_task_type("my_custom")
-class MyCustomTask(TaskType):
- """Custom task type for specific operations."""
-
- def __init__(self, config: dict):
- self.config = config
-
- def validate(self) -> bool:
- """Validate task configuration."""
- required = ["operation", "target"]
- return all(k in self.config for k in required)
-
- async def execute(self, context: TaskContext) -> TaskResult:
- """Execute the task."""
- operation = self.config["operation"]
- target = self.config["target"]
-
- # Perform custom logic
- result = await self._perform_operation(operation, target)
-
- return TaskResult(
- status="success",
- output=result
- )
-
- async def _perform_operation(self, op, target):
- # Implementation
- pass
-```
-
-### Using Custom Tasks
-
-```json
-{
- "id": "custom_operation",
- "type": "my_custom",
- "config": {
- "operation": "sync",
- "target": "s3://bucket/path"
- }
-}
-```
-
-## Task Configuration
-
-### Timeouts and Retries
-
-```json
-{
- "id": "resilient_task",
- "type": "http",
- "config": {
- "url": "https://api.example.com/endpoint"
- },
- "timeout": 300,
- "retry": {
- "max_attempts": 5,
- "initial_delay": 1,
- "max_delay": 60,
- "backoff": "exponential",
- "retry_on": ["timeout", "5xx"]
- }
-}
-```
-
-### Resource Allocation
-
-```json
-{
- "id": "resource_intensive",
- "type": "docker",
- "config": {
- "image": "ml-model:latest"
- },
- "resources": {
- "cpu": "4",
- "memory": "16Gi",
- "gpu": {
- "count": 2,
- "type": "nvidia-tesla-v100"
- },
- "storage": {
- "size": "100Gi",
- "type": "ssd"
- }
- },
- "node_selector": {
- "node-type": "compute-optimized"
- }
-}
-```
-
-### Environment and Secrets
-
-```json
-{
- "id": "secure_task",
- "type": "python",
- "config": {
- "script": "secure_process.py"
- },
- "env": {
- "LOG_LEVEL": "INFO",
- "CONFIG_PATH": "/etc/config"
- },
- "secrets": {
- "DB_PASSWORD": {
- "source": "vault",
- "path": "secret/data/db",
- "key": "password"
- },
- "API_KEY": {
- "source": "kubernetes",
- "name": "api-secrets",
- "key": "api-key"
- }
- }
-}
-```
-
-## Task Execution Modes
-
-### Sequential Execution
-
-```json
-{
- "tasks": [
- {"id": "step1", "type": "shell", "command": "echo Step 1"},
- {"id": "step2", "type": "shell", "command": "echo Step 2", "depends_on": ["step1"]},
- {"id": "step3", "type": "shell", "command": "echo Step 3", "depends_on": ["step2"]}
- ]
-}
-```
-
-### Parallel Execution
-
-```json
-{
- "tasks": [
- {"id": "fetch_a", "type": "http", "config": {"url": "https://api.a.com"}},
- {"id": "fetch_b", "type": "http", "config": {"url": "https://api.b.com"}},
- {"id": "fetch_c", "type": "http", "config": {"url": "https://api.c.com"}},
- {
- "id": "combine",
- "type": "python",
- "depends_on": ["fetch_a", "fetch_b", "fetch_c"]
- }
- ]
-}
-```
-
-### Dynamic Task Generation
-
-```python
-from deerflow import Workflow, DynamicTaskGroup
-
-workflow = Workflow(name="dynamic_example")
-
-@workflow.dynamic_tasks(id="process_files")
-def generate_tasks(context):
- """Generate tasks based on runtime data."""
- files = context.params.get("files", [])
-
- tasks = []
- for i, file in enumerate(files):
- tasks.append({
- "id": f"process_{i}",
- "type": "python",
- "config": {
- "script": "process_file.py",
- "args": [file]
- }
- })
-
- return tasks
-```
-
-## Task Monitoring
-
-### Logging
-
-```python
-from deerflow import TaskLogger
-
-@workflow.task(id="logged_task")
-def process_with_logging(context):
- logger = TaskLogger(context)
-
- logger.info("Starting processing")
- logger.debug(f"Parameters: {context.params}")
-
- try:
- result = do_work()
- logger.info(f"Completed with result: {result}")
- return result
- except Exception as e:
- logger.error(f"Failed: {e}")
- raise
-```
-
-### Metrics
-
-```python
-from deerflow import TaskMetrics
-
-@workflow.task(id="metrics_task")
-def process_with_metrics(context):
- metrics = TaskMetrics(context)
-
- with metrics.timer("processing_time"):
- records = fetch_records()
-
- metrics.gauge("records_fetched", len(records))
-
- processed = 0
- for record in records:
- process(record)
- processed += 1
- metrics.counter("records_processed")
-
- return {"processed": processed}
-```
-
-## Summary
-
-In this chapter, you've learned:
-
-- **Task Architecture**: Lifecycle and components
-- **Built-in Types**: Shell, Python, HTTP, Docker, K8s, SQL, Spark
-- **Custom Tasks**: Creating your own task types
-- **Configuration**: Timeouts, retries, resources, secrets
-- **Execution Modes**: Sequential, parallel, dynamic
-- **Monitoring**: Logging and metrics
-
-## Key Takeaways
-
-1. **Choose Right Type**: Match task type to the job
-2. **Configure Resources**: Allocate appropriate resources
-3. **Handle Failures**: Use retries and timeouts
-4. **Secure Secrets**: Use proper secret management
-5. **Monitor Everything**: Log and metric all tasks
-
-## Next Steps
-
-Ready to learn about complex task dependencies? Let's explore Chapter 4.
-
----
-
-**Ready for Chapter 4?** [Dependencies](04-dependencies.md)
-
-*Generated for [Awesome Code Docs](https://github.com/johnxie/awesome-code-docs)*
-
-## What Problem Does This Solve?
-
-Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for `config`, `task`, `deerflow` so behavior stays predictable as complexity grows.
-
-In practical terms, this chapter helps you avoid three common failures:
-
-- coupling core logic too tightly to one implementation path
-- missing the handoff boundaries between setup, execution, and validation
-- shipping changes without clear rollback or observability strategy
-
-After working through this chapter, you should be able to reason about `Chapter 3: Task Management` as an operating subsystem inside **Deer Flow Tutorial: Distributed Workflow Orchestration Platform**, with explicit contracts for inputs, state transitions, and outputs.
-
-Use the implementation notes around `self`, `context`, `python` as your checklist when adapting these patterns to your own repository.
-
-## How it Works Under the Hood
-
-Under the hood, `Chapter 3: Task Management` usually follows a repeatable control path:
-
-1. **Context bootstrap**: initialize runtime config and prerequisites for `config`.
-2. **Input normalization**: shape incoming data so `task` receives stable contracts.
-3. **Core execution**: run the main logic branch and propagate intermediate state through `deerflow`.
-4. **Policy and safety checks**: enforce limits, auth scopes, and failure boundaries.
-5. **Output composition**: return canonical result payloads for downstream consumers.
-6. **Operational telemetry**: emit logs/metrics needed for debugging and performance tuning.
-
-When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
-
-## Source Walkthrough
-
-Use the following upstream sources to verify implementation details while reading this chapter:
-
-- [Official Documentation](https://github.com/bytedance/deer-flow/tree/main/docs)
- Why it matters: authoritative reference on `Official Documentation` (github.com).
-- [GitHub Repository](https://github.com/bytedance/deer-flow)
- Why it matters: authoritative reference on `GitHub Repository` (github.com).
-- [API Reference](https://github.com/bytedance/deer-flow/blob/main/docs/API.md)
- Why it matters: authoritative reference on `API Reference` (github.com).
-- [Community & Issues](https://github.com/bytedance/deer-flow/issues)
- Why it matters: authoritative reference on `Community & Issues` (github.com).
-- [Workflow Examples](https://github.com/bytedance/deer-flow/tree/main/examples)
- Why it matters: authoritative reference on `Workflow Examples` (github.com).
-- [AI Codebase Knowledge Builder](https://github.com/johnxie/awesome-code-docs)
- Why it matters: authoritative reference on `AI Codebase Knowledge Builder` (github.com).
-
-Suggested trace strategy:
-- search upstream code for `config` and `task` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
-
-## Chapter Connections
-
-- [Tutorial Index](README.md)
-- [Previous Chapter: Chapter 2: Workflow Basics](02-workflow-basics.md)
-- [Next Chapter: Chapter 4: Dependencies](04-dependencies.md)
-- [Main Catalog](../../README.md#-tutorial-catalog)
-- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
diff --git a/tutorials/deer-flow-tutorial/04-dependencies.md b/tutorials/deer-flow-tutorial/04-dependencies.md
deleted file mode 100644
index a7bb9448..00000000
--- a/tutorials/deer-flow-tutorial/04-dependencies.md
+++ /dev/null
@@ -1,509 +0,0 @@
----
-layout: default
-title: "Chapter 4: Dependencies"
-parent: "Deer Flow Tutorial"
-nav_order: 4
----
-
-# Chapter 4: Dependencies
-
-Welcome to **Chapter 4: Dependencies**. In this part of **Deer Flow Tutorial: Distributed Workflow Orchestration Platform**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
-
-
-> Master complex dependency relationships, conditional execution, and data flow between tasks.
-
-## Overview
-
-Dependencies define the execution order and relationships between tasks. Deer Flow supports various dependency patterns from simple chains to complex DAGs with conditional branching.
-
-## Dependency Types
-
-### Direct Dependencies
-
-```json
-{
- "tasks": [
- {
- "id": "task_a",
- "type": "shell",
- "command": "echo A"
- },
- {
- "id": "task_b",
- "type": "shell",
- "command": "echo B",
- "depends_on": ["task_a"]
- },
- {
- "id": "task_c",
- "type": "shell",
- "command": "echo C",
- "depends_on": ["task_b"]
- }
- ]
-}
-```
-
-```
-task_a ──▶ task_b ──▶ task_c
-```
-
-### Fan-Out Pattern
-
-```json
-{
- "tasks": [
- {
- "id": "source",
- "type": "python",
- "config": {"script": "fetch_data.py"}
- },
- {
- "id": "process_a",
- "depends_on": ["source"],
- "type": "python",
- "config": {"script": "process_a.py"}
- },
- {
- "id": "process_b",
- "depends_on": ["source"],
- "type": "python",
- "config": {"script": "process_b.py"}
- },
- {
- "id": "process_c",
- "depends_on": ["source"],
- "type": "python",
- "config": {"script": "process_c.py"}
- }
- ]
-}
-```
-
-```
- ┌──▶ process_a
- │
-source ───────┼──▶ process_b
- │
- └──▶ process_c
-```
-
-### Fan-In Pattern
-
-```json
-{
- "tasks": [
- {"id": "fetch_users", "type": "http", "config": {"url": "..."}},
- {"id": "fetch_orders", "type": "http", "config": {"url": "..."}},
- {"id": "fetch_products", "type": "http", "config": {"url": "..."}},
- {
- "id": "aggregate",
- "type": "python",
- "depends_on": ["fetch_users", "fetch_orders", "fetch_products"],
- "config": {"script": "aggregate.py"}
- }
- ]
-}
-```
-
-```
-fetch_users ────┐
- │
-fetch_orders ───┼──▶ aggregate
- │
-fetch_products ─┘
-```
-
-### Diamond Pattern
-
-```json
-{
- "tasks": [
- {"id": "start", "type": "shell", "command": "echo Start"},
- {"id": "path_a", "depends_on": ["start"], "type": "shell", "command": "echo A"},
- {"id": "path_b", "depends_on": ["start"], "type": "shell", "command": "echo B"},
- {
- "id": "finish",
- "depends_on": ["path_a", "path_b"],
- "type": "shell",
- "command": "echo Finish"
- }
- ]
-}
-```
-
-```
- ┌──▶ path_a ──┐
- │ │
-start ──┤ ├──▶ finish
- │ │
- └──▶ path_b ──┘
-```
-
-## Conditional Execution
-
-### Basic Conditions
-
-```json
-{
- "id": "conditional_task",
- "type": "python",
- "depends_on": ["check_condition"],
- "condition": "${tasks.check_condition.output.should_run == true}",
- "config": {
- "script": "process.py"
- }
-}
-```
-
-### Branch Patterns
-
-```python
-from deerflow import Workflow, BranchTask
-
-workflow = Workflow(name="branching_example")
-
-@workflow.task(id="check_type")
-def check_data_type(context):
- data = context.params.get("data")
- if data.get("type") == "json":
- return {"branch": "json"}
- elif data.get("type") == "csv":
- return {"branch": "csv"}
- else:
- return {"branch": "default"}
-
-@workflow.task(id="process_json", condition="check_type.output.branch == 'json'")
-def process_json(context):
- # Process JSON data
- pass
-
-@workflow.task(id="process_csv", condition="check_type.output.branch == 'csv'")
-def process_csv(context):
- # Process CSV data
- pass
-
-@workflow.task(id="process_default", condition="check_type.output.branch == 'default'")
-def process_default(context):
- # Default processing
- pass
-```
-
-### Conditional Expressions
-
-```json
-{
- "tasks": [
- {
- "id": "load_data",
- "type": "python",
- "config": {"script": "load.py"},
- "outputs": ["record_count", "has_errors"]
- },
- {
- "id": "process_normal",
- "depends_on": ["load_data"],
- "condition": "${tasks.load_data.outputs.record_count > 0 && !tasks.load_data.outputs.has_errors}",
- "type": "python",
- "config": {"script": "process.py"}
- },
- {
- "id": "handle_errors",
- "depends_on": ["load_data"],
- "condition": "${tasks.load_data.outputs.has_errors}",
- "type": "python",
- "config": {"script": "error_handler.py"}
- },
- {
- "id": "skip_empty",
- "depends_on": ["load_data"],
- "condition": "${tasks.load_data.outputs.record_count == 0}",
- "type": "shell",
- "command": "echo 'No records to process'"
- }
- ]
-}
-```
-
-## Data Flow
-
-### Passing Outputs
-
-```python
-from deerflow import Workflow, Output
-
-workflow = Workflow(name="data_flow_example")
-
-@workflow.task(id="producer")
-def produce_data():
- data = {
- "records": [1, 2, 3, 4, 5],
- "metadata": {"source": "api", "timestamp": "2024-01-15"}
- }
- return Output(
- data=data,
- artifacts={"data_file": "/tmp/data.json"}
- )
-
-@workflow.task(id="consumer", depends_on=["producer"])
-def consume_data(producer):
- records = producer.data["records"]
- data_file = producer.artifacts["data_file"]
- # Process the data
- return Output(data={"processed_count": len(records)})
-```
-
-### XCom-Style Communication
-
-```json
-{
- "tasks": [
- {
- "id": "extract",
- "type": "python",
- "config": {
- "script": "extract.py"
- },
- "publish": {
- "key": "extracted_data",
- "value": "${output.data}"
- }
- },
- {
- "id": "transform",
- "depends_on": ["extract"],
- "type": "python",
- "config": {
- "script": "transform.py",
- "args": ["${xcom.extracted_data}"]
- }
- }
- ]
-}
-```
-
-### File-Based Data Passing
-
-```json
-{
- "tasks": [
- {
- "id": "generate",
- "type": "python",
- "config": {
- "script": "generate.py"
- },
- "artifacts": {
- "output": "/workflow/data/output.parquet"
- }
- },
- {
- "id": "analyze",
- "depends_on": ["generate"],
- "type": "python",
- "config": {
- "script": "analyze.py",
- "args": ["${tasks.generate.artifacts.output}"]
- }
- }
- ]
-}
-```
-
-## Advanced Dependency Patterns
-
-### Optional Dependencies
-
-```json
-{
- "id": "flexible_task",
- "type": "python",
- "dependencies": [
- {
- "task": "required_task",
- "type": "required"
- },
- {
- "task": "optional_task",
- "type": "optional"
- }
- ],
- "config": {
- "script": "process.py"
- }
-}
-```
-
-### Trigger Rules
-
-```json
-{
- "tasks": [
- {"id": "task_a", "type": "shell", "command": "..."},
- {"id": "task_b", "type": "shell", "command": "..."},
- {"id": "task_c", "type": "shell", "command": "..."},
- {
- "id": "final_task",
- "depends_on": ["task_a", "task_b", "task_c"],
- "trigger_rule": "one_success",
- "type": "shell",
- "command": "echo Done"
- }
- ]
-}
-```
-
-Trigger rules:
-- `all_success` - All dependencies succeeded (default)
-- `all_done` - All dependencies completed (success or fail)
-- `one_success` - At least one succeeded
-- `one_failed` - At least one failed
-- `none_failed` - No failures (includes skipped)
-
-### Cross-Workflow Dependencies
-
-```python
-from deerflow import Workflow, ExternalTaskSensor
-
-workflow = Workflow(name="downstream")
-
-# Wait for external workflow to complete
-sensor = ExternalTaskSensor(
- id="wait_for_upstream",
- external_workflow="upstream_workflow",
- external_task="final_task",
- execution_date="{{ execution_date }}",
- timeout=3600,
- poke_interval=60
-)
-
-workflow.add_task(sensor)
-
-@workflow.task(id="process", depends_on=["wait_for_upstream"])
-def process_downstream():
- # Process after upstream completes
- pass
-```
-
-## Dependency Visualization
-
-### Generating DAG Diagrams
-
-```bash
-# Generate visual representation
-deerflow visualize my_workflow --format png --output workflow.png
-
-# Interactive HTML view
-deerflow visualize my_workflow --format html --output workflow.html
-
-# Mermaid diagram
-deerflow visualize my_workflow --format mermaid
-```
-
-### Validating Dependencies
-
-```bash
-# Check for cycles and issues
-deerflow validate my_workflow
-
-# Detailed dependency report
-deerflow dependencies my_workflow --verbose
-```
-
-### Execution Order Preview
-
-```bash
-# Show execution order
-deerflow order my_workflow
-
-# Output:
-# Level 0: task_a (parallel with task_b)
-# Level 0: task_b (parallel with task_a)
-# Level 1: task_c (after task_a)
-# Level 1: task_d (after task_b)
-# Level 2: task_e (after task_c, task_d)
-```
-
-## Summary
-
-In this chapter, you've learned:
-
-- **Dependency Types**: Direct, fan-out, fan-in, diamond
-- **Conditional Execution**: Branches and expressions
-- **Data Flow**: Outputs, XCom, artifacts
-- **Advanced Patterns**: Optional deps, trigger rules, cross-workflow
-- **Visualization**: DAG diagrams and validation
-
-## Key Takeaways
-
-1. **DAG Structure**: Dependencies form directed acyclic graphs
-2. **Parallel When Possible**: Independent tasks run in parallel
-3. **Conditions Enable Branching**: Dynamic workflow paths
-4. **Data Passes Cleanly**: Use outputs and artifacts
-5. **Validate Dependencies**: Check for cycles and issues
-
-## Next Steps
-
-Ready to learn about error handling and fault tolerance? Let's explore Chapter 5.
-
----
-
-**Ready for Chapter 5?** [Error Handling](05-error-handling.md)
-
-*Generated for [Awesome Code Docs](https://github.com/johnxie/awesome-code-docs)*
-
-## What Problem Does This Solve?
-
-Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for `depends_on`, `config`, `workflow` so behavior stays predictable as complexity grows.
-
-In practical terms, this chapter helps you avoid three common failures:
-
-- coupling core logic too tightly to one implementation path
-- missing the handoff boundaries between setup, execution, and validation
-- shipping changes without clear rollback or observability strategy
-
-After working through this chapter, you should be able to reason about `Chapter 4: Dependencies` as an operating subsystem inside **Deer Flow Tutorial: Distributed Workflow Orchestration Platform**, with explicit contracts for inputs, state transitions, and outputs.
-
-Use the implementation notes around `tasks`, `python`, `script` as your checklist when adapting these patterns to your own repository.
-
-## How it Works Under the Hood
-
-Under the hood, `Chapter 4: Dependencies` usually follows a repeatable control path:
-
-1. **Context bootstrap**: initialize runtime config and prerequisites for `depends_on`.
-2. **Input normalization**: shape incoming data so `config` receives stable contracts.
-3. **Core execution**: run the main logic branch and propagate intermediate state through `workflow`.
-4. **Policy and safety checks**: enforce limits, auth scopes, and failure boundaries.
-5. **Output composition**: return canonical result payloads for downstream consumers.
-6. **Operational telemetry**: emit logs/metrics needed for debugging and performance tuning.
-
-When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
-
-## Source Walkthrough
-
-Use the following upstream sources to verify implementation details while reading this chapter:
-
-- [Official Documentation](https://github.com/bytedance/deer-flow/tree/main/docs)
- Why it matters: authoritative reference on `Official Documentation` (github.com).
-- [GitHub Repository](https://github.com/bytedance/deer-flow)
- Why it matters: authoritative reference on `GitHub Repository` (github.com).
-- [API Reference](https://github.com/bytedance/deer-flow/blob/main/docs/API.md)
- Why it matters: authoritative reference on `API Reference` (github.com).
-- [Community & Issues](https://github.com/bytedance/deer-flow/issues)
- Why it matters: authoritative reference on `Community & Issues` (github.com).
-- [Workflow Examples](https://github.com/bytedance/deer-flow/tree/main/examples)
- Why it matters: authoritative reference on `Workflow Examples` (github.com).
-- [AI Codebase Knowledge Builder](https://github.com/johnxie/awesome-code-docs)
- Why it matters: authoritative reference on `AI Codebase Knowledge Builder` (github.com).
-
-Suggested trace strategy:
-- search upstream code for `depends_on` and `config` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
-
-## Chapter Connections
-
-- [Tutorial Index](README.md)
-- [Previous Chapter: Chapter 3: Task Management](03-task-management.md)
-- [Next Chapter: Chapter 5: Error Handling](05-error-handling.md)
-- [Main Catalog](../../README.md#-tutorial-catalog)
-- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
diff --git a/tutorials/deer-flow-tutorial/04-rag-search-knowledge.md b/tutorials/deer-flow-tutorial/04-rag-search-knowledge.md
new file mode 100644
index 00000000..7d18ffb7
--- /dev/null
+++ b/tutorials/deer-flow-tutorial/04-rag-search-knowledge.md
@@ -0,0 +1,356 @@
+---
+layout: default
+title: "Chapter 4: RAG, Search, and Knowledge Synthesis"
+parent: "DeerFlow Tutorial"
+nav_order: 4
+format_version: v2
+why: "The quality of DeerFlow's research outputs is entirely dependent on which search and retrieval tools are configured and how they are composed. Understanding each tool's strengths, configuration, and failure modes lets you tune research quality for your specific use case."
+mental_model: "DeerFlow's knowledge acquisition is a two-layer system: a search layer (DuckDuckGo / Tavily / Exa) that returns snippets and URLs, and a retrieval layer (web_fetch / Firecrawl) that fetches full page content. The agent orchestrates both layers — first identifying relevant sources, then reading them in full — producing inline citations along the way."
+learning_outcomes:
+ - Understand the difference between web_search and web_fetch in DeerFlow's tool chain
+ - Configure Tavily, DuckDuckGo, Exa, and Firecrawl for different research scenarios
+ - Understand how image search works and when vision tools activate
+ - Understand the sandbox-based Python REPL and how it enables data analysis
+ - Configure MCP servers to add custom knowledge sources
+snapshot:
+ repo: bytedance/deer-flow
+ stars: ~53.5k
+ last_checked: 2026-04-12
+chapter_map:
+ - "01: Installation and first query"
+ - "02: LangGraph state machine internals"
+ - "03: Research pipeline deep dive"
+ - "04 (this): RAG and search tools"
+ - "05: Frontend and API design"
+ - "06: Skills and extensions"
+ - "07: Podcast and multi-modal outputs"
+ - "08: Production deployment"
+sources:
+ - https://github.com/bytedance/deer-flow/blob/main/backend/packages/harness/deerflow/community/ddg_search/tools.py
+ - https://github.com/bytedance/deer-flow/blob/main/backend/packages/harness/deerflow/community/exa/tools.py
+ - https://github.com/bytedance/deer-flow/blob/main/backend/packages/harness/deerflow/community/firecrawl/tools.py
+ - https://github.com/bytedance/deer-flow/blob/main/backend/packages/harness/deerflow/community/image_search/tools.py
+ - https://github.com/bytedance/deer-flow/blob/main/backend/docs/MCP_SERVER.md
+---
+
+# Chapter 4: RAG, Search, and Knowledge Synthesis
+
+## What Problem Does This Solve?
+
+Traditional RAG systems retrieve from a pre-indexed corpus: you embed documents, store them in a vector database, and retrieve by cosine similarity. This is powerful for organization-internal knowledge, but fails for open-web research because the corpus is stale the moment it is indexed.
+
+DeerFlow takes a different approach: **live web retrieval with LLM-driven navigation**. The agent does not query a pre-indexed corpus. It issues real-time web searches, navigates to the most relevant pages, reads full content, and synthesizes answers with inline citations — all driven by the LLM's judgment about which sources are worth reading in full.
+
+This gives DeerFlow access to current information, niche sources, and multi-modal content (images, data files), but requires careful tool selection to balance quality, cost, and latency.
+
+## How it Works Under the Hood
+
+### The Two-Layer Retrieval Model
+
+```mermaid
+graph LR
+ subgraph "Layer 1: Discovery (web_search)"
+ A[DuckDuckGo<br/>Free, good baseline]
+ B[Tavily<br/>AI-optimized, paid]
+ C[Exa<br/>Semantic search, paid]
+ end
+
+ subgraph "Layer 2: Retrieval (web_fetch / Firecrawl)"
+ D[web_fetch<br/>Built-in HTTP fetcher<br/>converts HTML to Markdown]
+ E[Firecrawl<br/>JS rendering, PDF support<br/>paid, high quality]
+ end
+
+ subgraph "Agent Decision"
+ F[LLM decides:<br/>which sources to fetch in full]
+ end
+
+ A --> F
+ B --> F
+ C --> F
+ F --> D
+ F --> E
+```
+
+The agent always starts with a search tool to get a set of candidate URLs with snippets. It then decides which URLs are worth fetching in full based on the snippet quality, source authority, and relevance to the research question.
+
+### DuckDuckGo Search Tool
+
+The DuckDuckGo tool is implemented in `deerflow/community/ddg_search/tools.py` using the `duckduckgo-search` Python library:
+
+```python
+# backend/packages/harness/deerflow/community/ddg_search/tools.py
+from duckduckgo_search import DDGS
+from langchain_core.tools import tool
+
+def _search_text(query: str, max_results: int = 5, region: str = "wt-wt") -> list[dict]:
+ """Core search function using DDGS library."""
+ with DDGS() as ddgs:
+ results = list(ddgs.text(
+ query,
+ region=region,
+ safesearch="moderate",
+ max_results=max_results,
+ ))
+ return results
+
+@tool
+def web_search_tool(query: str, max_results: int | None = None) -> str:
+ """
+ Search the web using DuckDuckGo.
+ Returns JSON with query, result_count, and normalized results.
+ Each result: {title, url, content}
+ """
+ results = _search_text(query, max_results=max_results or get_config_max_results())
+ # Normalize field names across DuckDuckGo response variations
+ normalized = [
+ {
+ "title": r.get("title", ""),
+ "url": r.get("href") or r.get("link", ""),
+ "content": r.get("body") or r.get("snippet", ""),
+ }
+ for r in results
+ ]
+ return json.dumps({
+ "query": query,
+ "result_count": len(normalized),
+ "results": normalized,
+ })
+```
+
+Configuration in `config.yaml`:
+
+```yaml
+tools:
+ - name: web_search
+ group: web
+ use: deerflow.community.ddg_search:web_search_tool
+ max_results: 5 # Override the default result count
+```
+
+**Trade-offs:**
+- Free, no API key required
+- Moderate quality — good for general research
+- Rate limiting can occur with rapid parallel sub-agent searches
+- No semantic ranking or recency filtering
+
+### Tavily Search Tool
+
+Tavily is an AI-native search API optimized for LLM agents, returning cleaner, more relevant results:
+
+```yaml
+tools:
+ - name: web_search
+ group: web
+ use: deerflow.community.tavily:web_search_tool
+ api_key: $TAVILY_API_KEY
+ max_results: 10
+```
+
+Tavily provides:
+- AI-filtered results with relevance scoring
+- Automatic content extraction (no separate `web_fetch` needed for basic use)
+- Recency filtering support
+- Much lower noise than DuckDuckGo for technical queries
+
+Cost: ~$0.01–$0.05 per search depending on plan.
+
+### Exa Search Tool
+
+Exa uses semantic (embedding-based) search rather than keyword matching:
+
+```yaml
+tools:
+ - name: web_search
+ group: web
+ use: deerflow.community.exa:web_search_tool
+ api_key: $EXA_API_KEY
+ max_results: 10
+```
+
+Exa is particularly effective for:
+- Academic and research paper discovery
+- Finding similar documents to a reference
+- Queries where exact keywords are unknown
+
+### Firecrawl: Full-Page Web Retrieval
+
+For pages that require JavaScript rendering, PDF extraction, or structured data extraction, Firecrawl provides a managed scraping service:
+
+```yaml
+tools:
+ - name: web_fetch
+ group: web
+ use: deerflow.community.firecrawl:web_fetch_tool
+ api_key: $FIRECRAWL_API_KEY
+```
+
+Firecrawl converts any URL to clean Markdown, handling:
+- Single-page applications (React, Vue, Angular)
+- PDF documents
+- Paywalled content (where legally accessible)
+- JavaScript-rendered tables and charts
+
+### Image Search Tool
+
+DeerFlow includes an image search capability in `deerflow/community/image_search/tools.py`:
+
+```python
+# Image search returns URLs of relevant images
+# When ViewImageMiddleware is active and the model supports vision,
+# the agent can fetch and "view" images inline
+
+@tool
+def image_search_tool(query: str, max_results: int = 5) -> str:
+ """
+ Search for images relevant to the query.
+ Returns JSON with image URLs, titles, and sources.
+ """
+ ...
+```
+
+When the agent calls `image_search_tool` and follows up with a `view_image` tool call, `ViewImageMiddleware` intercepts the `view_image` call, fetches the image, converts it to base64, and injects it into the message state as a multimodal message — provided the configured model supports vision.
+
+### The Sandbox: Python REPL for Data Analysis
+
+Beyond web search, DeerFlow's sandbox enables the agent to write and execute Python code for data analysis tasks. This is not a toy REPL — it is a full execution environment with file system access:
+
+```mermaid
+graph LR
+ A[Agent decides to analyze data] --> B[Writes Python script to workspace]
+ B --> C[Calls bash tool: python script.py]
+ C --> D{Sandbox type}
+ D -->|LocalSandboxProvider| E[Executes on host machine]
+ D -->|AioSandboxProvider| F[Executes in Docker container]
+ E --> G[Stdout/stderr returned to agent]
+ F --> G
+ G --> A
+```
+
+The agent's workspace is at `/mnt/user-data/workspace/{thread_id}/`, and final outputs (charts, processed data, reports) are written to `/mnt/user-data/outputs/{thread_id}/`.
+
+Example: agent-generated data analysis code
+
+```python
+# An agent might generate and execute this script during a research task:
+
+import json
+import matplotlib.pyplot as plt
+
+# Data from web search results
+frameworks = ["LangGraph", "CrewAI", "AutoGen", "Swarm"]
+github_stars = [8200, 24000, 31000, 3100]
+
+fig, ax = plt.subplots(figsize=(10, 6))
+bars = ax.bar(frameworks, github_stars, color=["#2196F3", "#4CAF50", "#FF9800", "#9C27B0"])
+ax.set_xlabel("Framework")
+ax.set_ylabel("GitHub Stars")
+ax.set_title("Multi-Agent Framework GitHub Stars (April 2026)")
+
+for bar, stars in zip(bars, github_stars):
+ ax.text(bar.get_x() + bar.get_width()/2., bar.get_height() + 200,
+ f"{stars:,}", ha="center", va="bottom")
+
+plt.tight_layout()
+plt.savefig("/mnt/user-data/outputs/framework_comparison.png", dpi=150)
+print("Chart saved to outputs/framework_comparison.png")
+```
+
+The generated PNG is tracked in `ThreadState.artifacts` and served by the Gateway API for display in the frontend.
+
+### MCP Servers: Extending the Knowledge Layer
+
+Model Context Protocol (MCP) servers allow DeerFlow to connect to arbitrary knowledge sources — databases, private APIs, internal documentation systems:
+
+```json
+// backend/extensions_config.json
+{
+ "mcpServers": {
+ "filesystem": {
+ "command": "npx",
+ "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/docs"],
+ "enabled": true
+ },
+ "postgres": {
+ "command": "npx",
+ "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://..."],
+ "enabled": true
+ },
+ "github": {
+ "command": "npx",
+ "args": ["-y", "@modelcontextprotocol/server-github"],
+ "env": {
+ "GITHUB_PERSONAL_ACCESS_TOKEN": "$GITHUB_TOKEN"
+ },
+ "enabled": true
+ }
+ }
+}
+```
+
+MCP tools are **automatically discovered** at startup — no code changes required. The Gateway API handles OAuth for HTTP-based MCP servers. Once enabled, these tools appear to the agent as regular tools alongside `web_search` and `bash`.
+
+### Tool Groups and Capability Control
+
+Tools are organized into groups that control which capabilities are available:
+
+```python
+# Tool groups defined in config.yaml
+TOOL_GROUPS = {
+ "web": ["web_search", "web_fetch", "image_search"],
+ "file:read": ["read_file", "ls"],
+ "file:write": ["write_file", "str_replace"],
+ "bash": ["bash"],
+}
+```
+
+Sub-agents receive a restricted tool list based on their task:
+- A "web research" sub-agent gets `["web", "file:read"]`
+- A "code analysis" sub-agent gets `["bash", "file:read", "file:write"]`
+- A "data processing" sub-agent gets `["bash", "file:read", "file:write"]`
+
+This prevents sub-agents from doing things outside their intended scope.
+
+### Configuring Search for Different Research Scenarios
+
+| Scenario | Recommended Config |
+|:--|:--|
+| General web research | DuckDuckGo (free) + web_fetch |
+| High-quality competitive intelligence | Tavily (paid) + Firecrawl |
+| Academic paper discovery | Exa (paid) + web_fetch |
+| Internal documentation RAG | MCP filesystem server |
+| Database querying | MCP postgres server |
+| GitHub repository analysis | MCP github server + bash |
+| Data analysis + visualization | bash + file ops (sandbox) |
+
+### Knowledge Synthesis Process
+
+After gathering evidence from multiple sources, the agent synthesizes a structured output:
+
+```mermaid
+graph TB
+ A[Web search results<br/>10-30 snippets] --> D[Context window accumulation]
+ B[Full page fetches<br/>5-10 pages × 5-20k tokens] --> D
+ C[Code execution results<br/>analysis outputs] --> D
+ D --> E[SummarizationMiddleware<br/>compresses if token limit approaches]
+ E --> F[LLM synthesis<br/>structured report with sections]
+ F --> G[Inline citations added<br/>citation:Title URL format]
+ G --> H[Sources section appended]
+ H --> I[Final report streamed to user]
+ I --> J[Artifacts tracked in ThreadState]
+```
+
+## Summary
+
+DeerFlow's knowledge acquisition system is a two-layer live retrieval architecture: a search layer (DuckDuckGo/Tavily/Exa) for source discovery and a retrieval layer (web_fetch/Firecrawl) for full-page reading. The sandbox Python REPL adds data analysis capabilities. MCP servers extend the system to private knowledge sources.
+
+The agent orchestrates all of these tools via LLM judgment — choosing which searches to run, which pages to read in full, and which scripts to execute based on the research question and the evidence gathered so far.
+
+---
+
+## Chapter Connections
+
+- [Tutorial Index](README.md)
+- [Previous Chapter: Chapter 3: Research Agent Pipeline](03-research-agent-pipeline.md)
+- [Next Chapter: Chapter 5: Frontend, Backend, and API Design](05-frontend-backend-api.md)
+- [Main Catalog](../../README.md#-tutorial-catalog)
+- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
diff --git a/tutorials/deer-flow-tutorial/05-error-handling.md b/tutorials/deer-flow-tutorial/05-error-handling.md
deleted file mode 100644
index 6f3f91e3..00000000
--- a/tutorials/deer-flow-tutorial/05-error-handling.md
+++ /dev/null
@@ -1,561 +0,0 @@
----
-layout: default
-title: "Chapter 5: Error Handling"
-parent: "Deer Flow Tutorial"
-nav_order: 5
----
-
-# Chapter 5: Error Handling
-
-Welcome to **Chapter 5: Error Handling**. In this part of **Deer Flow Tutorial: Distributed Workflow Orchestration Platform**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
-
-
-> Implement fault-tolerant workflows with retries, fallbacks, and recovery mechanisms.
-
-## Overview
-
-Production workflows must handle failures gracefully. Deer Flow provides comprehensive error handling mechanisms including retries, fallbacks, timeouts, and alerting to ensure workflow reliability.
-
-## Retry Mechanisms
-
-### Basic Retry Configuration
-
-```json
-{
- "id": "retryable_task",
- "type": "http",
- "config": {
- "url": "https://api.example.com/data"
- },
- "retry": {
- "max_attempts": 3,
- "delay": 5
- }
-}
-```
-
-### Exponential Backoff
-
-```json
-{
- "id": "backoff_task",
- "type": "http",
- "config": {
- "url": "https://api.example.com/data"
- },
- "retry": {
- "max_attempts": 5,
- "initial_delay": 1,
- "max_delay": 60,
- "backoff": "exponential",
- "multiplier": 2
- }
-}
-```
-
-```
-Attempt 1: immediate
-Attempt 2: wait 1s
-Attempt 3: wait 2s
-Attempt 4: wait 4s
-Attempt 5: wait 8s (capped at max_delay)
-```
-
-### Retry Conditions
-
-```json
-{
- "id": "conditional_retry",
- "type": "http",
- "config": {
- "url": "https://api.example.com/data"
- },
- "retry": {
- "max_attempts": 3,
- "retry_on": {
- "exceptions": ["TimeoutError", "ConnectionError"],
- "status_codes": [429, 500, 502, 503, 504],
- "conditions": ["${output.retry_requested == true}"]
- },
- "no_retry_on": {
- "exceptions": ["AuthenticationError"],
- "status_codes": [400, 401, 403, 404]
- }
- }
-}
-```
-
-### Python Retry Decorator
-
-```python
-from deerflow import Workflow, retry
-
-workflow = Workflow(name="retry_example")
-
-@workflow.task(id="flaky_operation")
-@retry(
- max_attempts=3,
- backoff="exponential",
- retry_on=[TimeoutError, ConnectionError]
-)
-def flaky_operation(context):
- # This will be retried on failure
- response = make_api_call()
- return response
-```
-
-## Timeout Management
-
-### Task Timeouts
-
-```json
-{
- "id": "bounded_task",
- "type": "python",
- "config": {
- "script": "long_running.py"
- },
- "timeout": {
- "execution": 3600,
- "idle": 300,
- "queue": 600
- }
-}
-```
-
-- **execution**: Maximum total execution time
-- **idle**: Maximum time without output
-- **queue**: Maximum time waiting in queue
-
-### Workflow Timeouts
-
-```json
-{
- "name": "timed_workflow",
- "timeout": 7200,
- "tasks": [
- {"id": "task1", "timeout": 1800, "...": "..."},
- {"id": "task2", "timeout": 1800, "...": "..."},
- {"id": "task3", "timeout": 1800, "...": "..."}
- ]
-}
-```
-
-### Handling Timeouts
-
-```python
-from deerflow import Workflow, TimeoutError
-
-@workflow.task(id="timeout_aware")
-def process_with_timeout(context):
- try:
- result = long_operation()
- return result
- except TimeoutError:
- # Save partial progress
- save_checkpoint(context.checkpoint_path)
- raise
-```
-
-## Fallback Strategies
-
-### Task-Level Fallbacks
-
-```json
-{
- "id": "primary_task",
- "type": "http",
- "config": {
- "url": "https://primary-api.com/data"
- },
- "fallback": {
- "task": {
- "type": "http",
- "config": {
- "url": "https://backup-api.com/data"
- }
- }
- }
-}
-```
-
-### Cascading Fallbacks
-
-```json
-{
- "id": "resilient_fetch",
- "type": "http",
- "config": {"url": "https://api1.example.com"},
- "fallbacks": [
- {
- "type": "http",
- "config": {"url": "https://api2.example.com"}
- },
- {
- "type": "http",
- "config": {"url": "https://api3.example.com"}
- },
- {
- "type": "python",
- "config": {
- "script": "load_cached_data.py"
- }
- }
- ]
-}
-```
-
-### Default Values
-
-```python
-from deerflow import Workflow, fallback_value
-
-@workflow.task(id="with_default")
-@fallback_value({"status": "unknown", "data": []})
-def fetch_data(context):
- # If this fails, return the default value
- return fetch_from_api()
-```
-
-## Error Callbacks
-
-### On Failure Handlers
-
-```json
-{
- "id": "monitored_task",
- "type": "python",
- "config": {"script": "process.py"},
- "on_failure": {
- "tasks": [
- {
- "id": "send_alert",
- "type": "http",
- "config": {
- "method": "POST",
- "url": "https://alerts.example.com/webhook",
- "body": {
- "message": "Task ${task.id} failed",
- "error": "${task.error}",
- "workflow": "${workflow.name}"
- }
- }
- },
- {
- "id": "cleanup",
- "type": "shell",
- "command": "rm -rf /tmp/task_${task.id}/*"
- }
- ]
- }
-}
-```
-
-### Workflow-Level Handlers
-
-```json
-{
- "name": "monitored_workflow",
- "on_failure": {
- "notify": {
- "type": "slack",
- "channel": "#alerts",
- "message": "Workflow ${workflow.name} failed: ${workflow.error}"
- },
- "cleanup": {
- "type": "shell",
- "command": "cleanup.sh ${execution.id}"
- }
- },
- "on_success": {
- "notify": {
- "type": "slack",
- "channel": "#success",
- "message": "Workflow ${workflow.name} completed successfully"
- }
- },
- "tasks": [...]
-}
-```
-
-### Python Callbacks
-
-```python
-from deerflow import Workflow, on_failure, on_success
-
-workflow = Workflow(name="callback_example")
-
-@workflow.on_failure
-def handle_workflow_failure(context, error):
- send_alert(
- channel="#alerts",
- message=f"Workflow failed: {error}",
- execution_id=context.execution_id
- )
- cleanup_resources(context)
-
-@workflow.on_success
-def handle_workflow_success(context):
- update_dashboard(context.execution_id, status="success")
-
-@workflow.task(id="risky_task")
-@on_failure(lambda ctx, err: log_failure(ctx, err))
-def risky_task(context):
- # Task implementation
- pass
-```
-
-## Circuit Breaker Pattern
-
-### Implementation
-
-```python
-from deerflow import Workflow, CircuitBreaker
-
-workflow = Workflow(name="circuit_breaker_example")
-
-# Configure circuit breaker
-breaker = CircuitBreaker(
- failure_threshold=5, # Open after 5 failures
- reset_timeout=60, # Try again after 60s
- half_open_requests=3 # Test with 3 requests
-)
-
-@workflow.task(id="protected_call")
-@breaker.protect
-def call_external_service(context):
- response = requests.get("https://unreliable-api.com")
- return response.json()
-```
-
-### Circuit States
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│ Circuit Breaker States │
-├─────────────────────────────────────────────────────────────────┤
-│ │
-│ ┌─────────┐ failures >= threshold ┌─────────┐ │
-│ │ CLOSED │ ───────────────────────────▶│ OPEN │ │
-│ │(normal) │ │ (fail │ │
-│ └────┬────┘ │ fast) │ │
-│ │ └────┬────┘ │
-│ │ success │ │
-│ │ │ timeout │
-│ │ ▼ │
-│ │ ┌────────────────┐ │
-│ │ │ HALF-OPEN │ │
-│ │ │ (test requests)│ │
-│ │ └────────┬───────┘ │
-│ │ │ │
-│ │ success ──────────┘ │
-│ │ │ │
-│ └───────────────────────────────────────┘ │
-│ │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-## Dead Letter Queue
-
-### Configuration
-
-```json
-{
- "name": "dlq_workflow",
- "dead_letter_queue": {
- "enabled": true,
- "queue": "workflow-dlq",
- "retention": "7d",
- "include_context": true
- },
- "tasks": [...]
-}
-```
-
-### Processing Failed Tasks
-
-```python
-from deerflow import DLQProcessor
-
-processor = DLQProcessor(queue="workflow-dlq")
-
-# List failed tasks
-failed = processor.list(
- workflow="my_workflow",
- since="2024-01-01"
-)
-
-# Retry a specific failure
-processor.retry(failure_id="abc123")
-
-# Retry all failures for a workflow
-processor.retry_all(workflow="my_workflow")
-
-# Purge old failures
-processor.purge(older_than="7d")
-```
-
-## Recovery and Checkpoints
-
-### Checkpoint System
-
-```python
-from deerflow import Workflow, checkpoint
-
-workflow = Workflow(name="checkpoint_example")
-
-@workflow.task(id="long_process")
-@checkpoint(interval=100) # Checkpoint every 100 items
-def process_large_dataset(context):
- dataset = load_dataset()
-
- # Resume from checkpoint if exists
- start_idx = context.checkpoint.get("last_index", 0)
-
- for i, item in enumerate(dataset[start_idx:], start=start_idx):
- process_item(item)
-
- # Save checkpoint periodically
- if i % 100 == 0:
- context.save_checkpoint({"last_index": i})
-
- return {"processed": len(dataset)}
-```
-
-### Workflow Resume
-
-```bash
-# Resume failed workflow from last checkpoint
-deerflow resume execution_id
-
-# Resume from specific task
-deerflow resume execution_id --from-task task_id
-
-# Resume with modified parameters
-deerflow resume execution_id --param key=new_value
-```
-
-## Alerting and Notifications
-
-### Alert Configuration
-
-```yaml
-# config/alerts.yaml
-alerts:
- channels:
- slack:
- webhook_url: https://hooks.slack.com/...
- default_channel: "#workflow-alerts"
-
- email:
- smtp_host: smtp.example.com
- from_address: alerts@example.com
- recipients:
- - team@example.com
-
- pagerduty:
- api_key: ${PAGERDUTY_KEY}
- service_id: P123ABC
-
- rules:
- - name: critical_failure
- condition: "workflow.status == 'failed' && workflow.tags.critical"
- channels: [slack, pagerduty]
- severity: critical
-
- - name: task_timeout
- condition: "task.status == 'timeout'"
- channels: [slack]
- severity: warning
-
- - name: retry_exhausted
- condition: "task.retries_exhausted"
- channels: [email]
- severity: high
-```
-
-## Summary
-
-In this chapter, you've learned:
-
-- **Retries**: Basic, exponential backoff, conditional
-- **Timeouts**: Task and workflow level
-- **Fallbacks**: Task fallbacks and defaults
-- **Callbacks**: Failure and success handlers
-- **Circuit Breaker**: Protect against cascading failures
-- **Recovery**: Checkpoints and workflow resume
-- **Alerting**: Notifications for failures
-
-## Key Takeaways
-
-1. **Retry Intelligently**: Use backoff and conditions
-2. **Set Timeouts**: Prevent infinite waits
-3. **Plan Fallbacks**: Have alternatives ready
-4. **Checkpoint Progress**: Enable partial recovery
-5. **Alert Early**: Catch failures before impact
-
-## Next Steps
-
-Ready to scale your workflows? Let's explore distributed execution in Chapter 6.
-
----
-
-**Ready for Chapter 6?** [Scaling](06-scaling.md)
-
-*Generated for [Awesome Code Docs](https://github.com/johnxie/awesome-code-docs)*
-
-## What Problem Does This Solve?
-
-Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for `workflow`, `task`, `context` so behavior stays predictable as complexity grows.
-
-In practical terms, this chapter helps you avoid three common failures:
-
-- coupling core logic too tightly to one implementation path
-- missing the handoff boundaries between setup, execution, and validation
-- shipping changes without clear rollback or observability strategy
-
-After working through this chapter, you should be able to reason about `Chapter 5: Error Handling` as an operating subsystem inside **Deer Flow Tutorial: Distributed Workflow Orchestration Platform**, with explicit contracts for inputs, state transitions, and outputs.
-
-Use the implementation notes around `config`, `Workflow`, `name` as your checklist when adapting these patterns to your own repository.
-
-## How it Works Under the Hood
-
-Under the hood, `Chapter 5: Error Handling` usually follows a repeatable control path:
-
-1. **Context bootstrap**: initialize runtime config and prerequisites for `workflow`.
-2. **Input normalization**: shape incoming data so `task` receives stable contracts.
-3. **Core execution**: run the main logic branch and propagate intermediate state through `context`.
-4. **Policy and safety checks**: enforce limits, auth scopes, and failure boundaries.
-5. **Output composition**: return canonical result payloads for downstream consumers.
-6. **Operational telemetry**: emit logs/metrics needed for debugging and performance tuning.
-
-When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
-
-## Source Walkthrough
-
-Use the following upstream sources to verify implementation details while reading this chapter:
-
-- [Official Documentation](https://github.com/bytedance/deer-flow/tree/main/docs)
- Why it matters: authoritative reference on `Official Documentation` (github.com).
-- [GitHub Repository](https://github.com/bytedance/deer-flow)
- Why it matters: authoritative reference on `GitHub Repository` (github.com).
-- [API Reference](https://github.com/bytedance/deer-flow/blob/main/docs/API.md)
- Why it matters: authoritative reference on `API Reference` (github.com).
-- [Community & Issues](https://github.com/bytedance/deer-flow/issues)
- Why it matters: authoritative reference on `Community & Issues` (github.com).
-- [Workflow Examples](https://github.com/bytedance/deer-flow/tree/main/examples)
- Why it matters: authoritative reference on `Workflow Examples` (github.com).
-- [AI Codebase Knowledge Builder](https://github.com/johnxie/awesome-code-docs)
- Why it matters: authoritative reference on `AI Codebase Knowledge Builder` (github.com).
-
-Suggested trace strategy:
-- search upstream code for `workflow` and `task` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
-
-## Chapter Connections
-
-- [Tutorial Index](README.md)
-- [Previous Chapter: Chapter 4: Dependencies](04-dependencies.md)
-- [Next Chapter: Chapter 6: Scaling](06-scaling.md)
-- [Main Catalog](../../README.md#-tutorial-catalog)
-- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
diff --git a/tutorials/deer-flow-tutorial/05-frontend-backend-api.md b/tutorials/deer-flow-tutorial/05-frontend-backend-api.md
new file mode 100644
index 00000000..71767a93
--- /dev/null
+++ b/tutorials/deer-flow-tutorial/05-frontend-backend-api.md
@@ -0,0 +1,426 @@
+---
+layout: default
+title: "Chapter 5: Frontend, Backend, and API Design"
+parent: "DeerFlow Tutorial"
+nav_order: 5
+format_version: v2
+why: "DeerFlow is a three-service system (LangGraph server, Gateway API, Next.js frontend) behind an Nginx proxy. Understanding each service's responsibilities, how they communicate, and how the streaming API works lets you integrate DeerFlow into existing products, build custom frontends, or expose it to IM channels."
+mental_model: "The Gateway API handles everything except agent execution. The LangGraph server handles agent execution and streaming. The frontend is a chat interface that connects to both. Nginx is the single entry point that routes between them."
+learning_outcomes:
+ - Understand the responsibility boundary between LangGraph server and Gateway API
+ - Understand how SSE streaming works from LangGraph to the Next.js frontend
+ - Use the Gateway API endpoints to manage threads, artifacts, skills, and models
+ - Understand the IM channel integration pattern (Telegram, Slack, Feishu)
+ - Configure DeerFlow for programmatic access via the embedded DeerFlowClient
+snapshot:
+ repo: bytedance/deer-flow
+ stars: ~53.5k
+ last_checked: 2026-04-12
+chapter_map:
+ - "01: Installation and first query"
+ - "02: LangGraph state machine internals"
+ - "03: Research pipeline deep dive"
+ - "04: RAG and search tools"
+ - "05 (this): Frontend and API design"
+ - "06: Skills and extensions"
+ - "07: Podcast and multi-modal outputs"
+ - "08: Production deployment"
+sources:
+ - https://github.com/bytedance/deer-flow/blob/main/backend/docs/ARCHITECTURE.md
+ - https://github.com/bytedance/deer-flow/blob/main/backend/app/gateway/routers/
+ - https://github.com/bytedance/deer-flow/blob/main/backend/docs/STREAMING.md
+ - https://github.com/bytedance/deer-flow/blob/main/backend/app/channels/
+ - https://github.com/bytedance/deer-flow/blob/main/backend/packages/harness/deerflow/client.py
+---
+
+# Chapter 5: Frontend, Backend, and API Design
+
+## What Problem Does This Solve?
+
+A multi-agent system that only works through its own bundled UI is limited. Production deployments need programmatic access (to trigger research runs from external systems), IM integrations (to accept tasks from Slack or Telegram), and artifact serving (to download generated reports and podcasts). DeerFlow's architecture cleanly separates these concerns across three services with well-defined boundaries.
+
+Understanding where each piece lives lets you:
+- Build a custom frontend or integrate into an existing product
+- Trigger research from CI/CD pipelines or scheduled jobs
+- Deploy IM bots that dispatch research tasks autonomously
+- Download artifacts without navigating the UI
+
+## How it Works Under the Hood
+
+### Three-Service Architecture
+
+```mermaid
+graph TB
+ subgraph "Entry Point"
+ N[Nginx :2026<br/>Unified entry point<br/>Routes by path prefix]
+ end
+
+ subgraph "Service 1: LangGraph Server :2024"
+ LG1[Agent Runtime<br/>make_lead_agent graph]
+ LG2[Thread State Management<br/>AsyncCheckpointer]
+ LG3[SSE Streaming<br/>Token-by-token output]
+ LG4[LangGraph Platform API<br/>/threads, /runs endpoints]
+ end
+
+ subgraph "Service 2: Gateway API :8001 (FastAPI)"
+ GW1[Models: list available LLMs]
+ GW2[MCP: configure/reload servers]
+ GW3[Skills: list/install/remove]
+ GW4[Uploads: file validation + storage]
+ GW5[Artifacts: serve generated files]
+ GW6[Memory: CRUD for cross-session memory]
+ GW7[Suggestions: prompt suggestions]
+ GW8[Threads: cleanup thread data]
+ end
+
+ subgraph "Service 3: Next.js Frontend :3000"
+ FE1[Chat interface]
+ FE2[SSE stream consumer]
+ FE3[Artifact viewer]
+ FE4[Thread history]
+ end
+
+ subgraph "IM Channels"
+ IM1[Telegram Bot]
+ IM2[Slack App]
+ IM3[Feishu / Lark Bot]
+ IM4[WeChat / WeCom]
+ end
+
+ N --> LG1
+ N --> GW1
+ N --> FE1
+ IM1 --> LG1
+ IM2 --> LG1
+ IM3 --> LG1
+ IM4 --> LG1
+```
+
+**Routing rules in Nginx:**
+- `/api/...` (LangGraph paths: `/threads`, `/runs`, `/assistants`) → LangGraph server `:2024`
+- `/gateway/...` → Gateway API `:8001`
+- Everything else → Next.js frontend `:3000`
+
+### LangGraph Server: The Agent Runtime
+
+The LangGraph server is the `langgraph-cli dev` process running the compiled `lead_agent` graph. It exposes the standard LangGraph Platform API:
+
+| Endpoint | Method | Description |
+|:--|:--|:--|
+| `/assistants` | GET | List registered graphs (returns `lead_agent`) |
+| `/threads` | POST | Create a new conversation thread |
+| `/threads/{thread_id}` | GET | Get thread metadata |
+| `/threads/{thread_id}/runs` | POST | Submit a message and get SSE stream |
+| `/threads/{thread_id}/runs/{run_id}` | GET | Get run status |
+| `/threads/{thread_id}/state` | GET | Inspect full `ThreadState` at latest checkpoint |
+| `/threads/{thread_id}/history` | GET | Get all checkpointed states |
+
+**Starting a research run programmatically:**
+
+```python
+import httpx
+import json
+
+async def run_research(query: str, thread_id: str | None = None) -> str:
+ """Submit a research query to DeerFlow and collect the full response."""
+
+ base_url = "http://localhost:2026"
+
+ async with httpx.AsyncClient() as client:
+ # Create thread if not provided
+ if thread_id is None:
+ thread_resp = await client.post(f"{base_url}/threads")
+ thread_id = thread_resp.json()["thread_id"]
+
+ # Submit run and stream response
+ full_content = ""
+
+ async with client.stream(
+ "POST",
+ f"{base_url}/threads/{thread_id}/runs",
+ json={
+ "assistant_id": "lead_agent",
+ "input": {
+ "messages": [{"role": "user", "content": query}]
+ },
+ "stream_mode": ["messages"],
+ },
+ headers={"Accept": "text/event-stream"},
+ ) as response:
+ async for line in response.aiter_lines():
+ if line.startswith("data: "):
+ data = json.loads(line[6:])
+ # Extract token from SSE event
+ if data.get("type") == "message_chunk":
+ full_content += data.get("content", "")
+
+ return full_content
+
+
+# Usage:
+import asyncio
+result = asyncio.run(run_research("What are the key differences between RAG and fine-tuning?"))
+print(result)
+```
+
+### SSE Streaming: How Tokens Flow to the Frontend
+
+DeerFlow uses Server-Sent Events (SSE) for real-time streaming. The frontend establishes a long-lived HTTP connection and receives events as the agent processes:
+
+```mermaid
+sequenceDiagram
+ participant FE as Next.js Frontend
+ participant LG as LangGraph Server
+
+ FE->>LG: POST /threads/{id}/runs<br/>Accept: text/event-stream
+ Note over LG: Agent starts executing
+ LG-->>FE: data: {"type":"run_created","run_id":"..."}
+ LG-->>FE: data: {"type":"message_chunk","content":"Based "}
+ LG-->>FE: data: {"type":"message_chunk","content":"on my "}
+ LG-->>FE: data: {"type":"tool_call_start","tool":"web_search"}
+ LG-->>FE: data: {"type":"tool_result","tool":"web_search","content":"..."}
+ LG-->>FE: data: {"type":"message_chunk","content":"research, "}
+ LG-->>FE: data: {"type":"message_chunk","content":"I found..."}
+ LG-->>FE: data: {"type":"run_complete","artifacts":["report.md"]}
+ FE->>FE: Render complete message with citations
+```
+
+The frontend (`frontend/src/core/api/`) handles SSE connection management, reconnection on drop, and rendering of different event types (tool calls shown as expandable cards, message chunks rendered as streaming markdown).
+
+### Gateway API: The Support Layer
+
+The Gateway API is a FastAPI application at `:8001` that handles everything except agent execution:
+
+```python
+# backend/app/gateway/app.py (route registration)
+from app.gateway.routers import (
+ agents, # Agent config management
+ models, # List available LLM models from config.yaml
+ mcp, # MCP server config and reload
+ skills, # Skill listing, installation, removal
+ uploads, # File upload with validation
+ artifacts, # Serve generated outputs (reports, MP3s, slides)
+ memory, # Cross-session memory CRUD
+ threads, # Thread cleanup (removes filesystem artifacts)
+ suggestions, # Prompt autocomplete suggestions
+)
+
+app = FastAPI(title="DeerFlow Gateway API")
+app.include_router(models.router, prefix="/gateway/models")
+app.include_router(mcp.router, prefix="/gateway/mcp")
+app.include_router(skills.router, prefix="/gateway/skills")
+app.include_router(uploads.router, prefix="/gateway/uploads")
+app.include_router(artifacts.router, prefix="/gateway/artifacts")
+app.include_router(memory.router, prefix="/gateway/memory")
+app.include_router(threads.router, prefix="/gateway/threads")
+```
+
+**Key Gateway API endpoints:**
+
+```bash
+# List available models (from config.yaml)
+GET /gateway/models
+# Response: [{"name": "gpt-4o", "display_name": "GPT-4o", "supports_vision": true}, ...]
+
+# List installed skills
+GET /gateway/skills
+# Response: [{"name": "deep-research", "description": "..."}, ...]
+
+# Download a generated artifact (e.g., research report, podcast MP3)
+GET /gateway/artifacts/{thread_id}/{filename}
+# Response: Binary file with appropriate Content-Type header
+
+# Upload a file for the agent to process
+POST /gateway/uploads
+# Multipart form: file attachment
+# Response: {"file_id": "...", "filename": "...", "markdown_content": "..."}
+
+# List MCP server configurations
+GET /gateway/mcp
+# Response: [{"name": "github", "enabled": true, "tools": [...]}, ...]
+
+# Reload MCP configuration after editing extensions_config.json
+POST /gateway/mcp/reload
+```
+
+### File Upload Flow
+
+Uploaded files flow through a multi-step pipeline before reaching the agent:
+
+```mermaid
+graph LR
+ A[User uploads file] --> B[Gateway validates<br/>file type and size]
+ B --> C[Store in<br/>uploads_path/thread_id/]
+ C --> D{File type?}
+ D -->|PDF / DOCX| E[Convert to Markdown<br/>text extraction]
+ D -->|Image| F[Keep as binary<br/>ViewImageMiddleware handles it]
+ D -->|CSV / JSON| G[Keep as-is<br/>Agent reads directly]
+ E --> H[Store .md alongside original]
+ F --> H
+ G --> H
+ H --> I[ThreadState.uploaded_files<br/>populated with metadata]
+ I --> J[Agent can read via read_file tool<br/>or view via view_image tool]
+```
+
+### Security: Artifact Serving and XSS Prevention
+
+Generated artifacts (HTML reports, for example) could contain attacker-controlled content if rendered inline. DeerFlow's Gateway API forces downloads rather than inline rendering:
+
+```python
+# backend/app/gateway/routers/artifacts.py
+@router.get("/{thread_id}/{filename}")
+async def get_artifact(thread_id: str, filename: str):
+ """
+ Serve generated artifacts.
+ Security: always force download (Content-Disposition: attachment)
+ to prevent XSS from agent-generated HTML content.
+ """
+ file_path = Paths.get_outputs_path(thread_id) / filename
+ if not file_path.exists():
+ raise HTTPException(status_code=404)
+
+ return FileResponse(
+ path=file_path,
+ headers={"Content-Disposition": f'attachment; filename="{filename}"'},
+ )
+```
+
+### IM Channel Integration
+
+DeerFlow supports connecting to IM platforms, allowing users to interact with the agent via messaging apps:
+
+```python
+# backend/app/channels/
+# Each channel implements BaseChannel with standardized message handling
+
+class TelegramChannel(BaseChannel):
+ """Polls Telegram Bot API for updates, dispatches to lead_agent."""
+
+ async def handle_message(self, update: TelegramUpdate):
+ # Create or retrieve thread for this Telegram user
+ thread_id = self.store.get_thread_id(update.from_user.id)
+
+ # Submit to LangGraph
+ result = await self.agent_client.run(
+ thread_id=thread_id,
+ message=update.message.text,
+ attachments=update.message.documents,
+ )
+
+ # Send response back to Telegram
+ await self.bot.send_message(
+ chat_id=update.chat_id,
+ text=result.content,
+ )
+
+ # If artifacts were generated, send as files
+ for artifact in result.artifacts:
+ await self.bot.send_document(
+ chat_id=update.chat_id,
+ document=open(artifact, "rb"),
+ )
+```
+
+Supported channels: Telegram, Slack, Feishu/Lark, WeChat, WeCom, Discord.
+
+Each channel is configured in the environment:
+
+```bash
+# .env
+TELEGRAM_BOT_TOKEN=...
+SLACK_BOT_TOKEN=...
+SLACK_SIGNING_SECRET=...
+FEISHU_APP_ID=...
+FEISHU_APP_SECRET=...
+```
+
+### The Embedded DeerFlowClient
+
+For programmatic access without spinning up the full HTTP stack, DeerFlow provides an embedded client that runs the agent in-process:
+
+```python
+# backend/packages/harness/deerflow/client.py
+from deerflow.client import DeerFlowClient
+
+# Initialize client (reads config.yaml automatically)
+client = DeerFlowClient()
+
+# Run a research query in-process
+result = await client.run(
+ thread_id="my-thread-123",
+ message="Research the current state of open-source LLM fine-tuning frameworks",
+)
+
+print(result.content)
+for artifact in result.artifacts:
+ print(f"Artifact: {artifact}")
+```
+
+The embedded client bypasses HTTP entirely — useful for:
+- Integration tests that need to verify research output quality
+- Batch research pipelines run as Python scripts
+- Claude Code integration (the `claude-to-deerflow` skill uses this)
+
+### Thread Data Management
+
+Thread data spans both services. When a thread is deleted, both must be cleaned up:
+
+```python
+# Thread cleanup requires coordination:
+# 1. LangGraph server removes thread state (messages, checkpoints)
+# 2. Gateway API removes filesystem artifacts
+
+async def delete_thread(thread_id: str):
+ # Delete LangGraph state
+ await langgraph_client.delete_thread(thread_id)
+
+ # Delete filesystem data
+ Paths.delete_thread_dir(thread_id)
+ # This removes:
+ # - /mnt/user-data/workspace/{thread_id}/
+ # - /mnt/user-data/uploads/{thread_id}/
+ # - /mnt/user-data/outputs/{thread_id}/
+```
+
+## Configuration for API Access
+
+### Enabling Authentication
+
+DeerFlow defaults to no authentication. For production or network-exposed deployments, add authentication at the Nginx layer:
+
+```nginx
+# nginx.conf - basic API key authentication
+location /threads {
+ auth_request /auth;
+ proxy_pass http://langgraph:2024;
+}
+
+location /auth {
+ internal;
+ proxy_pass http://auth-service:8080/verify;
+ proxy_pass_request_body off;
+ proxy_set_header X-API-Key $http_x_api_key;
+}
+```
+
+Or use the `better-auth` integration already in the frontend:
+
+```typescript
+// frontend/src/server/better-auth/config.ts
+// DeerFlow ships with a better-auth server for basic user authentication
+// Configure providers in this file
+```
+
+## Summary
+
+DeerFlow's three-service architecture cleanly separates agent execution (LangGraph server), support operations (Gateway API), and user interface (Next.js). The SSE streaming model enables real-time token delivery. The Gateway API handles file uploads, artifact serving, MCP configuration, and memory management. IM channel integrations connect the agent to messaging platforms. The embedded `DeerFlowClient` enables programmatic access without HTTP overhead.
+
+---
+
+## Chapter Connections
+
+- [Tutorial Index](README.md)
+- [Previous Chapter: Chapter 4: RAG, Search, and Knowledge Synthesis](04-rag-search-knowledge.md)
+- [Next Chapter: Chapter 6: Customization and Extension](06-customization-extension.md)
+- [Main Catalog](../../README.md#-tutorial-catalog)
+- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
diff --git a/tutorials/deer-flow-tutorial/06-customization-extension.md b/tutorials/deer-flow-tutorial/06-customization-extension.md
new file mode 100644
index 00000000..5594b5e2
--- /dev/null
+++ b/tutorials/deer-flow-tutorial/06-customization-extension.md
@@ -0,0 +1,417 @@
+---
+layout: default
+title: "Chapter 6: Customization and Extension"
+parent: "DeerFlow Tutorial"
+nav_order: 6
+format_version: v2
+why: "DeerFlow's core value proposition is extensibility. The skills system, MCP integrations, custom tools, and agent config overrides allow teams to adapt the system to specific domains without forking the main codebase."
+mental_model: "Think of DeerFlow as a skeleton agent runtime with three extension points: skills (Markdown workflows that guide the LLM), tools (Python functions or MCP servers that give the agent new capabilities), and agent configs (YAML overrides for model, features, and skill availability per deployment). These three levers let you configure a general-purpose agent into a domain-specific assistant."
+learning_outcomes:
+ - Create a custom skill in the SKILL.md format and test it
+ - Add a custom Python tool and register it in config.yaml
+ - Connect an MCP server for private knowledge source access
+ - Configure per-agent model and feature overrides
+ - Use the skill-creator skill to auto-generate new skill templates
+snapshot:
+ repo: bytedance/deer-flow
+ stars: ~53.5k
+ last_checked: 2026-04-12
+chapter_map:
+ - "01: Installation and first query"
+ - "02: LangGraph state machine internals"
+ - "03: Research pipeline deep dive"
+ - "04: RAG and search tools"
+ - "05: Frontend and API design"
+ - "06 (this): Skills and extensions"
+ - "07: Podcast and multi-modal outputs"
+ - "08: Production deployment"
+sources:
+ - https://github.com/bytedance/deer-flow/tree/main/skills/public
+ - https://github.com/bytedance/deer-flow/blob/main/skills/public/skill-creator/SKILL.md
+ - https://github.com/bytedance/deer-flow/blob/main/backend/docs/CONFIGURATION.md
+ - https://github.com/bytedance/deer-flow/blob/main/backend/docs/MCP_SERVER.md
+---
+
+# Chapter 6: Customization and Extension
+
+## What Problem Does This Solve?
+
+A general-purpose research agent is useful, but a domain-specific agent is valuable. A legal research assistant needs to know how to structure case law citations. A financial analyst agent needs to know how to pull earnings data. A DevOps agent needs to know how to interact with cloud APIs. None of these behaviors can be hardcoded into a single system.
+
+DeerFlow solves this through three composable extension mechanisms:
+1. **Skills** — Markdown-based workflow guides that load into the agent's context on demand
+2. **Tools** — Python functions (or MCP servers) that give the agent new capabilities
+3. **Agent configs** — Per-deployment YAML files that override model, features, and skill availability
+
+## How it Works Under the Hood
+
+### The Skills System
+
+Skills are Markdown files (`SKILL.md`) stored in the `skills/` directory. When the agent receives a query that matches a skill's use case, it reads the SKILL.md file and follows its methodology.
+
+```mermaid
+graph TB
+ A[User query] --> B[Lead agent receives query]
+ B --> C{Query matches a skill?}
+ C -->|No match| D[Use default research approach]
+ C -->|Match detected| E[Read SKILL.md file]
+ E --> F{References listed?}
+ F -->|Yes| G[Load reference files progressively<br/>as task requires them]
+ F -->|No| H[Follow SKILL.md instructions]
+ G --> H
+ H --> I[Execute task with skill guidance]
+ I --> J[Produce skill-specified output format]
+```
+
+Skills are loaded **progressively** — the agent reads the top-level SKILL.md first, then loads sub-resources (templates, reference guides, scripts) only when the task requires them. This avoids bloating the context with irrelevant detail.
+
+### Anatomy of a SKILL.md
+
+Every skill follows a standard structure:
+
+```markdown
+# [Skill Name]
+
+## When to Use This Skill
+[Describe the trigger conditions — when should the agent load this skill?]
+
+## What This Skill Produces
+[Describe the expected output format and quality bar]
+
+## Resources
+[List reference files that may be loaded progressively]
+- references/guide.md — [when to load this]
+- templates/output.md — [when to load this]
+- scripts/execute.py — [when to load this]
+
+## Workflow
+
+### Phase 1: [Phase Name]
+[Step-by-step instructions]
+
+### Phase 2: [Phase Name]
+[Step-by-step instructions]
+
+## Output Format
+[Exact format specification for the final output]
+
+## Quality Checklist
+- [ ] [Quality criterion 1]
+- [ ] [Quality criterion 2]
+```
+
+### Creating a Custom Skill
+
+Let's create a skill for legal case law research:
+
+```bash
+# 1. Create the skill directory
+mkdir -p skills/private/legal-research/references
+mkdir -p skills/private/legal-research/templates
+
+# 2. Create the SKILL.md
+```
+
+```markdown
+# skills/private/legal-research/SKILL.md
+
+# Legal Case Law Research
+
+## When to Use This Skill
+Load this skill when the user asks about:
+- Legal cases, court decisions, or precedents
+- Statutory interpretation
+- Regulatory compliance questions
+- Contract law or IP law research
+
+## What This Skill Produces
+A structured legal research memo with:
+- Summary of relevant cases and holdings
+- Key legal principles extracted
+- Circuit splits or conflicting authorities noted
+- Practical implications section
+- Full citations in Bluebook format
+
+## Resources
+- references/citation-format.md — load when formatting citations
+- templates/memo-template.md — load when writing the final memo
+
+## Workflow
+
+### Phase 1: Issue Identification
+Identify the precise legal question. Use ask_clarification if the jurisdiction,
+applicable law (state/federal), or specific legal issue is unclear.
+
+### Phase 2: Primary Research
+Search for: "[legal issue] case law [jurisdiction]"
+Search for: "[statute or regulation] interpretation"
+Fetch full text of key cases from Google Scholar or court websites.
+
+### Phase 3: Secondary Sources
+Search for law review articles and treatises to identify leading cases.
+Use: "[legal issue] law review article [jurisdiction]"
+
+### Phase 4: Synthesis
+Apply IRAC structure: Issue, Rule, Application, Conclusion.
+Cite every case with full Bluebook citation.
+
+## Quality Checklist
+- [ ] At least 3 primary cases cited
+- [ ] Circuit/jurisdiction consistency verified
+- [ ] Bluebook format applied
+- [ ] Practical implications addressed
+```
+
+```bash
+# 3. Point config.yaml to your skills directory
+```
+
+```yaml
+# config.yaml
+skills:
+ path: ../skills # Includes both skills/public/ and skills/private/
+ container_path: /mnt/skills
+```
+
+The skill is immediately available — no restart required. The agent will discover it on the next invocation when the query matches the "When to Use" criteria.
+
+### Using the skill-creator Skill
+
+DeerFlow ships a meta-skill for creating new skills:
+
+```
+# In the DeerFlow chat interface:
+"Use the skill-creator skill to help me create a new skill for financial earnings analysis"
+```
+
+The `skill-creator` skill (`skills/public/skill-creator/SKILL.md`) guides the agent through:
+1. Analyzing the task domain and required workflow
+2. Identifying what tools and references the skill needs
+3. Drafting the SKILL.md structure
+4. Running eval benchmarks to validate the skill quality
+5. Packaging the skill for distribution
+
+The skill-creator includes evaluation infrastructure (`scripts/run_eval.py`, `scripts/aggregate_benchmark.py`) for quantitatively measuring skill quality against test cases.
+
+### Available Public Skills
+
+DeerFlow ships with a rich library of production-ready skills:
+
+| Skill | Description |
+|:--|:--|
+| `deep-research` | Four-phase web research methodology |
+| `podcast-generation` | Convert research to MP3 dialogue |
+| `ppt-generation` | Research to PowerPoint slides |
+| `chart-visualization` | Generate 25+ chart types from data |
+| `data-analysis` | Statistical analysis with Python |
+| `academic-paper-review` | Structured paper critique |
+| `systematic-literature-review` | Multi-paper synthesis with citations |
+| `github-deep-research` | Deep analysis of GitHub repositories |
+| `consulting-analysis` | McKinsey-style structured analysis |
+| `code-documentation` | Auto-generate code documentation |
+| `newsletter-generation` | Curated content newsletter production |
+| `image-generation` | AI image generation integration |
+| `video-generation` | Video generation integration |
+| `web-design-guidelines` | UI/UX design assistance |
+| `skill-creator` | Meta-skill for creating new skills |
+| `find-skills` | Discover and install skills from registry |
+
+### Adding a Custom Python Tool
+
+For capabilities that require code execution beyond the sandbox (API integrations, specialized data processing), create a custom Python tool:
+
+```python
+# tools/my_tools/legal_database.py
+from langchain_core.tools import tool
+import requests
+
+@tool
+def search_legal_cases(
+ query: str,
+ jurisdiction: str = "federal",
+ date_range: str = "2020-2026",
+ max_results: int = 10,
+) -> str:
+ """
+ Search a legal case database for relevant decisions.
+
+ Args:
+ query: Legal issue or case name to search for
+ jurisdiction: "federal", "state:CA", "state:NY", etc.
+ date_range: Date range in "YYYY-YYYY" format
+ max_results: Maximum number of cases to return
+
+ Returns:
+ JSON string with case list, holdings, and citations
+ """
+ # Integration with CourtListener, Westlaw, or internal legal DB
+ response = requests.get(
+ "https://www.courtlistener.com/api/rest/v4/search/",
+ params={
+ "q": query,
+ "type": "o", # Opinions
+ "order_by": "score desc",
+ },
+ headers={"Authorization": f"Token {get_courtlistener_token()}"},
+ )
+ cases = response.json()["results"]
+ return format_case_results(cases[:max_results])
+```
+
+Register the tool in `config.yaml`:
+
+```yaml
+tools:
+ - name: search_legal_cases
+ group: web # Add to the "web" group so legal research agents get it
+ use: tools.my_tools.legal_database:search_legal_cases
+ # No max_results here — the tool has its own default
+```
+
+### Custom Middleware
+
+For advanced customization, inject custom middleware into the agent factory:
+
+```python
+# custom/audit_middleware.py
+from deerflow.agents.middlewares import BaseMiddleware
+from deerflow.agents.thread_state import ThreadState
+
+class AuditLogMiddleware(BaseMiddleware):
+ """Log all tool calls to an external audit system."""
+
+ async def before_tool_call(
+ self,
+ tool_name: str,
+ tool_input: dict,
+ state: ThreadState,
+ ) -> None:
+ await audit_log.record(
+ thread_id=state["thread_data"]["workspace_path"],
+ tool=tool_name,
+ input=tool_input,
+ timestamp=datetime.utcnow(),
+ )
+
+ async def after_tool_call(
+ self,
+ tool_name: str,
+ tool_output: str,
+ state: ThreadState,
+ ) -> None:
+ await audit_log.record(
+ thread_id=state["thread_data"]["workspace_path"],
+ tool=tool_name,
+ output_length=len(tool_output),
+ timestamp=datetime.utcnow(),
+ )
+```
+
+```python
+# custom/agent_factory.py
+from deerflow.agents.factory import create_deerflow_agent
+from custom.audit_middleware import AuditLogMiddleware
+
+def make_audited_agent(config=None):
+ """Lead agent with audit logging middleware injected."""
+ base_middleware = build_default_middleware_chain()
+ custom_middleware = [AuditLogMiddleware()] + base_middleware
+
+ return create_deerflow_agent(
+ model=resolve_model(config),
+ tools=build_tools(config),
+ middleware=custom_middleware, # Use custom chain instead of features flags
+ checkpointer=make_checkpointer(),
+ )
+```
+
+### Per-Agent Configuration Overrides
+
+DeerFlow supports per-agent configuration files that override the global config:
+
+```yaml
+# workspace/agents/lead_agent/config.yaml
+model_name: o3-mini # Override default model for this agent
+subagent:
+ enabled: true
+ max_concurrent: 5
+
+# Restrict which skills this agent can load:
+skills:
+ - deep-research
+ - chart-visualization
+ - data-analysis
+# null = all skills available
+# [] = no skills
+# ["skill-name"] = specific skills only
+```
+
+This enables multi-tenant deployments where different user groups get different agent capabilities:
+
+```mermaid
+graph LR
+ A[Research Analyst Role] --> B[lead_agent config A<br/>skills: deep-research, consulting-analysis<br/>model: o3-mini]
+ C[Data Engineer Role] --> D[lead_agent config B<br/>skills: data-analysis, chart-visualization<br/>model: gpt-4o<br/>tools: +postgres MCP]
+ E[Content Team Role] --> F[lead_agent config C<br/>skills: podcast-generation, newsletter-generation<br/>model: gpt-4o-mini]
+```
+
+### MCP Server Extensions
+
+MCP servers are the most powerful extension point for adding private data sources:
+
+```json
+// backend/extensions_config.json
+{
+ "mcpServers": {
+ "internal-docs": {
+ "command": "npx",
+ "args": ["-y", "@modelcontextprotocol/server-filesystem", "/mnt/company-docs"],
+ "enabled": true
+ },
+ "analytics-db": {
+ "command": "python",
+ "args": ["-m", "my_company.mcp_server"],
+ "env": {
+ "DB_CONNECTION": "$ANALYTICS_DB_URL"
+ },
+ "enabled": true
+ },
+ "jira": {
+ "type": "http",
+ "url": "https://mcp.atlassian.com",
+ "oauth": {
+ "type": "client_credentials",
+ "token_endpoint": "https://auth.atlassian.com/oauth/token",
+ "client_id": "$JIRA_CLIENT_ID",
+ "client_secret": "$JIRA_CLIENT_SECRET"
+ },
+ "enabled": true
+ }
+ }
+}
+```
+
+After editing `extensions_config.json`, trigger a reload without restart:
+
+```bash
+curl -X POST http://localhost:2026/gateway/mcp/reload
+```
+
+## Summary
+
+DeerFlow's extension model centers on three composable mechanisms:
+1. **Skills** (SKILL.md files) — domain-specific workflow guides that load into agent context on demand
+2. **Tools** (Python functions or MCP servers) — new capabilities injected at construction time
+3. **Agent configs** — per-deployment YAML overrides for model, features, and skill availability
+
+The skill-creator meta-skill enables teams to build, evaluate, and package new skills without modifying core code. The MCP server integration provides a standardized protocol for connecting any data source with OAuth support.
+
+---
+
+## Chapter Connections
+
+- [Tutorial Index](README.md)
+- [Previous Chapter: Chapter 5: Frontend, Backend, and API Design](05-frontend-backend-api.md)
+- [Next Chapter: Chapter 7: Podcast and Multi-Modal Output](07-podcast-multimodal.md)
+- [Main Catalog](../../README.md#-tutorial-catalog)
+- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
diff --git a/tutorials/deer-flow-tutorial/06-scaling.md b/tutorials/deer-flow-tutorial/06-scaling.md
deleted file mode 100644
index 5fbd4367..00000000
--- a/tutorials/deer-flow-tutorial/06-scaling.md
+++ /dev/null
@@ -1,571 +0,0 @@
----
-layout: default
-title: "Chapter 6: Scaling"
-parent: "Deer Flow Tutorial"
-nav_order: 6
----
-
-# Chapter 6: Scaling
-
-Welcome to **Chapter 6: Scaling**. In this part of **Deer Flow Tutorial: Distributed Workflow Orchestration Platform**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
-
-
-> Scale Deer Flow across distributed systems with horizontal scaling, load balancing, and resource management.
-
-## Overview
-
-As workflow complexity and volume grow, Deer Flow must scale to meet demand. This chapter covers distributed architecture, horizontal scaling, resource management, and performance optimization.
-
-## Distributed Architecture
-
-### System Components
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│ Deer Flow Distributed Architecture │
-├─────────────────────────────────────────────────────────────────┤
-│ │
-│ ┌─────────────────────────────────────────────────────────┐ │
-│ │ API Gateway │ │
-│ │ (Load Balanced Entry Point) │ │
-│ └───────────────────────┬─────────────────────────────────┘ │
-│ │ │
-│ ┌───────────────────────┼─────────────────────────────────┐ │
-│ │ Scheduler Cluster (Active-Passive) │ │
-│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
-│ │ │Scheduler│ │Scheduler│ │Scheduler│ │ │
-│ │ │(Active) │ │(Standby)│ │(Standby)│ │ │
-│ │ └─────────┘ └─────────┘ └─────────┘ │ │
-│ └───────────────────────┬─────────────────────────────────┘ │
-│ │ │
-│ ┌───────────────────────┼─────────────────────────────────┐ │
-│ │ Message Queue │ │
-│ │ (Kafka / RabbitMQ / Redis) │ │
-│ └───────────────────────┬─────────────────────────────────┘ │
-│ │ │
-│ ┌───────────────────────┼─────────────────────────────────┐ │
-│ │ Worker Pool (Auto-Scaling) │ │
-│ │ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ │ │
-│ │ │Worker│ │Worker│ │Worker│ │Worker│ │Worker│ │Worker│ │ │
-│ │ │ 1 │ │ 2 │ │ 3 │ │ N │ │ N+1 │ │ ... │ │ │
-│ │ └──────┘ └──────┘ └──────┘ └──────┘ └──────┘ └──────┘ │ │
-│ └─────────────────────────────────────────────────────────┘ │
-│ │
-│ ┌─────────────────────────────────────────────────────────┐ │
-│ │ Storage Layer │ │
-│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
-│ │ │PostgreSQL│ │ S3 │ │ Redis │ │ │
-│ │ │(Metadata)│ │(Artifacts)│ │ (Cache) │ │ │
-│ │ └──────────┘ └──────────┘ └──────────┘ │ │
-│ └─────────────────────────────────────────────────────────┘ │
-│ │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-### Kubernetes Deployment
-
-```yaml
-# k8s/scheduler-deployment.yaml
-apiVersion: apps/v1
-kind: Deployment
-metadata:
- name: deerflow-scheduler
-spec:
- replicas: 3
- selector:
- matchLabels:
- app: deerflow-scheduler
- template:
- metadata:
- labels:
- app: deerflow-scheduler
- spec:
- containers:
- - name: scheduler
- image: deerflow/scheduler:latest
- env:
- - name: REDIS_URL
- value: redis://redis:6379
- - name: DATABASE_URL
- valueFrom:
- secretKeyRef:
- name: deerflow-secrets
- key: database-url
- resources:
- requests:
- memory: "512Mi"
- cpu: "500m"
- limits:
- memory: "1Gi"
- cpu: "1"
- livenessProbe:
- httpGet:
- path: /health
- port: 8080
- initialDelaySeconds: 30
----
-# k8s/worker-deployment.yaml
-apiVersion: apps/v1
-kind: Deployment
-metadata:
- name: deerflow-worker
-spec:
- replicas: 5
- selector:
- matchLabels:
- app: deerflow-worker
- template:
- metadata:
- labels:
- app: deerflow-worker
- spec:
- containers:
- - name: worker
- image: deerflow/worker:latest
- env:
- - name: QUEUE_URL
- value: amqp://rabbitmq:5672
- - name: WORKER_CONCURRENCY
- value: "4"
- resources:
- requests:
- memory: "1Gi"
- cpu: "1"
- limits:
- memory: "4Gi"
- cpu: "2"
-```
-
-## Horizontal Scaling
-
-### Worker Auto-Scaling
-
-```yaml
-# k8s/worker-hpa.yaml
-apiVersion: autoscaling/v2
-kind: HorizontalPodAutoscaler
-metadata:
- name: deerflow-worker-hpa
-spec:
- scaleTargetRef:
- apiVersion: apps/v1
- kind: Deployment
- name: deerflow-worker
- minReplicas: 3
- maxReplicas: 50
- metrics:
- - type: External
- external:
- metric:
- name: rabbitmq_queue_messages
- selector:
- matchLabels:
- queue: deerflow-tasks
- target:
- type: AverageValue
- averageValue: "10"
- - type: Resource
- resource:
- name: cpu
- target:
- type: Utilization
- averageUtilization: 70
-```
-
-### Queue-Based Scaling
-
-```python
-from deerflow.scaling import QueueBasedScaler
-
-scaler = QueueBasedScaler(
- queue="deerflow-tasks",
- min_workers=3,
- max_workers=100,
- scale_up_threshold=50, # Queue depth to trigger scale up
- scale_down_threshold=5, # Queue depth to trigger scale down
- scale_up_step=5, # Workers to add
- scale_down_step=2, # Workers to remove
- cooldown_period=300 # Seconds between scaling actions
-)
-
-scaler.start()
-```
-
-### Workflow-Specific Pools
-
-```yaml
-# config/worker-pools.yaml
-worker_pools:
- default:
- min_workers: 5
- max_workers: 20
- task_types: ["*"]
-
- cpu_intensive:
- min_workers: 2
- max_workers: 10
- task_types: ["python", "spark"]
- resources:
- cpu: 4
- memory: 8Gi
-
- io_bound:
- min_workers: 10
- max_workers: 50
- task_types: ["http", "sql"]
- resources:
- cpu: 1
- memory: 2Gi
-
- gpu:
- min_workers: 1
- max_workers: 5
- task_types: ["ml_inference", "training"]
- resources:
- cpu: 4
- memory: 16Gi
- gpu: 1
-```
-
-## Load Balancing
-
-### Task Distribution Strategies
-
-```python
-from deerflow.routing import TaskRouter
-
-router = TaskRouter()
-
-# Round-robin (default)
-router.strategy = "round_robin"
-
-# Least connections
-router.strategy = "least_connections"
-
-# Weighted routing
-router.strategy = "weighted"
-router.weights = {
- "worker-pool-1": 3,
- "worker-pool-2": 2,
- "worker-pool-3": 1
-}
-
-# Consistent hashing (for stateful tasks)
-router.strategy = "consistent_hash"
-router.hash_key = "workflow_id"
-```
-
-### Priority Queues
-
-```yaml
-# config/queues.yaml
-queues:
- critical:
- priority: 1
- max_workers: 20
- timeout: 60
-
- high:
- priority: 2
- max_workers: 15
- timeout: 300
-
- normal:
- priority: 3
- max_workers: 10
- timeout: 1800
-
- low:
- priority: 4
- max_workers: 5
- timeout: 7200
-```
-
-### Task Routing
-
-```json
-{
- "id": "priority_task",
- "type": "python",
- "config": {"script": "critical_job.py"},
- "routing": {
- "queue": "critical",
- "priority": 1,
- "worker_pool": "cpu_intensive"
- }
-}
-```
-
-## Resource Management
-
-### Resource Quotas
-
-```yaml
-# config/quotas.yaml
-quotas:
- organization:
- max_concurrent_workflows: 100
- max_concurrent_tasks: 1000
- cpu_limit: 500
- memory_limit: 2Ti
-
- teams:
- data-engineering:
- max_concurrent_workflows: 50
- max_concurrent_tasks: 500
- cpu_limit: 200
- memory_limit: 800Gi
-
- ml-team:
- max_concurrent_workflows: 20
- max_concurrent_tasks: 100
- cpu_limit: 100
- memory_limit: 500Gi
- gpu_limit: 10
-```
-
-### Dynamic Resource Allocation
-
-```python
-from deerflow import Workflow, ResourceRequest
-
-@workflow.task(id="adaptive_task")
-def process_data(context):
- data_size = get_data_size()
-
- # Request resources based on data size
- if data_size > 1_000_000:
- context.request_resources(
- cpu=4,
- memory="16Gi"
- )
- elif data_size > 100_000:
- context.request_resources(
- cpu=2,
- memory="8Gi"
- )
-
- # Process with allocated resources
- return process(data)
-```
-
-### Spot/Preemptible Instances
-
-```yaml
-# k8s/spot-workers.yaml
-apiVersion: apps/v1
-kind: Deployment
-metadata:
- name: deerflow-worker-spot
-spec:
- replicas: 10
- template:
- spec:
- nodeSelector:
- node-type: spot
- tolerations:
- - key: "spot"
- operator: "Equal"
- value: "true"
- effect: "NoSchedule"
- containers:
- - name: worker
- image: deerflow/worker:latest
- env:
- - name: WORKER_TYPE
- value: "preemptible"
- - name: CHECKPOINT_INTERVAL
- value: "60" # Frequent checkpoints for preemptible
-```
-
-## Performance Optimization
-
-### Caching
-
-```python
-from deerflow import Workflow, cache
-
-workflow = Workflow(name="cached_workflow")
-
-@workflow.task(id="expensive_computation")
-@cache(
- ttl=3600,
- key="${params.date}:${params.region}",
- backend="redis"
-)
-def expensive_computation(context):
- # This result will be cached
- return compute_expensive_result()
-```
-
-### Batch Processing
-
-```python
-from deerflow import Workflow, batch
-
-workflow = Workflow(name="batch_workflow")
-
-@workflow.task(id="batch_process")
-@batch(size=100, parallel=10)
-def process_items(items, context):
- """Process items in batches of 100, 10 batches in parallel."""
- results = []
- for item in items:
- results.append(process_single(item))
- return results
-```
-
-### Connection Pooling
-
-```yaml
-# config/connections.yaml
-connections:
- database:
- pool_size: 20
- max_overflow: 10
- pool_timeout: 30
- pool_recycle: 3600
-
- http:
- pool_connections: 100
- pool_maxsize: 100
- max_retries: 3
-
- redis:
- max_connections: 50
-```
-
-## Multi-Region Deployment
-
-### Geographic Distribution
-
-```yaml
-# config/regions.yaml
-regions:
- us-east:
- primary: true
- scheduler: true
- workers: 20
- endpoints:
- api: https://us-east.deerflow.example.com
- queue: amqp://mq-us-east.internal
-
- us-west:
- primary: false
- scheduler: false
- workers: 15
- endpoints:
- api: https://us-west.deerflow.example.com
- queue: amqp://mq-us-west.internal
-
- eu-west:
- primary: false
- scheduler: true # DR scheduler
- workers: 10
- endpoints:
- api: https://eu-west.deerflow.example.com
- queue: amqp://mq-eu-west.internal
-
-replication:
- enabled: true
- mode: async
- lag_threshold: 30s
-```
-
-### Workflow Affinity
-
-```json
-{
- "name": "regional_workflow",
- "affinity": {
- "region": "us-east",
- "fallback_regions": ["us-west", "eu-west"]
- },
- "tasks": [...]
-}
-```
-
-## Summary
-
-In this chapter, you've learned:
-
-- **Distributed Architecture**: Components and deployment
-- **Horizontal Scaling**: Auto-scaling workers
-- **Load Balancing**: Task distribution strategies
-- **Resource Management**: Quotas and dynamic allocation
-- **Performance**: Caching, batching, pooling
-- **Multi-Region**: Geographic distribution
-
-## Key Takeaways
-
-1. **Scale Workers**: Auto-scale based on queue depth
-2. **Use Pools**: Different pools for different workloads
-3. **Set Quotas**: Prevent resource exhaustion
-4. **Cache Results**: Avoid redundant computation
-5. **Plan for Regions**: Consider latency and disaster recovery
-
-## Next Steps
-
-Ready to monitor and observe your workflows? Let's explore Chapter 7.
-
----
-
-**Ready for Chapter 7?** [Monitoring](07-monitoring.md)
-
-*Generated for [Awesome Code Docs](https://github.com/johnxie/awesome-code-docs)*
-
-## What Problem Does This Solve?
-
-Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for `deerflow`, `name`, `worker` so behavior stays predictable as complexity grows.
-
-In practical terms, this chapter helps you avoid three common failures:
-
-- coupling core logic too tightly to one implementation path
-- missing the handoff boundaries between setup, execution, and validation
-- shipping changes without clear rollback or observability strategy
-
-After working through this chapter, you should be able to reason about `Chapter 6: Scaling` as an operating subsystem inside **Deer Flow Tutorial: Distributed Workflow Orchestration Platform**, with explicit contracts for inputs, state transitions, and outputs.
-
-Use the implementation notes around `scheduler`, `yaml`, `memory` as your checklist when adapting these patterns to your own repository.
-
-## How it Works Under the Hood
-
-Under the hood, `Chapter 6: Scaling` usually follows a repeatable control path:
-
-1. **Context bootstrap**: initialize runtime config and prerequisites for `deerflow`.
-2. **Input normalization**: shape incoming data so `name` receives stable contracts.
-3. **Core execution**: run the main logic branch and propagate intermediate state through `worker`.
-4. **Policy and safety checks**: enforce limits, auth scopes, and failure boundaries.
-5. **Output composition**: return canonical result payloads for downstream consumers.
-6. **Operational telemetry**: emit logs/metrics needed for debugging and performance tuning.
-
-When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
-
-## Source Walkthrough
-
-Use the following upstream sources to verify implementation details while reading this chapter:
-
-- [Official Documentation](https://github.com/bytedance/deer-flow/tree/main/docs)
- Why it matters: authoritative reference on `Official Documentation` (github.com).
-- [GitHub Repository](https://github.com/bytedance/deer-flow)
- Why it matters: authoritative reference on `GitHub Repository` (github.com).
-- [API Reference](https://github.com/bytedance/deer-flow/blob/main/docs/API.md)
- Why it matters: authoritative reference on `API Reference` (github.com).
-- [Community & Issues](https://github.com/bytedance/deer-flow/issues)
- Why it matters: authoritative reference on `Community & Issues` (github.com).
-- [Workflow Examples](https://github.com/bytedance/deer-flow/tree/main/examples)
- Why it matters: authoritative reference on `Workflow Examples` (github.com).
-- [AI Codebase Knowledge Builder](https://github.com/johnxie/awesome-code-docs)
- Why it matters: authoritative reference on `AI Codebase Knowledge Builder` (github.com).
-
-Suggested trace strategy:
-- search upstream code for `deerflow` and `name` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
-
-## Chapter Connections
-
-- [Tutorial Index](README.md)
-- [Previous Chapter: Chapter 5: Error Handling](05-error-handling.md)
-- [Next Chapter: Chapter 7: Monitoring](07-monitoring.md)
-- [Main Catalog](../../README.md#-tutorial-catalog)
-- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
diff --git a/tutorials/deer-flow-tutorial/07-monitoring.md b/tutorials/deer-flow-tutorial/07-monitoring.md
deleted file mode 100644
index af13d25b..00000000
--- a/tutorials/deer-flow-tutorial/07-monitoring.md
+++ /dev/null
@@ -1,590 +0,0 @@
----
-layout: default
-title: "Chapter 7: Monitoring"
-parent: "Deer Flow Tutorial"
-nav_order: 7
----
-
-# Chapter 7: Monitoring
-
-Welcome to **Chapter 7: Monitoring**. In this part of **Deer Flow Tutorial: Distributed Workflow Orchestration Platform**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
-
-
-> Implement comprehensive monitoring and observability for Deer Flow workflows.
-
-## Overview
-
-Effective monitoring is crucial for maintaining reliable workflows. This chapter covers metrics collection, logging, tracing, alerting, and dashboard creation for Deer Flow.
-
-## Metrics Collection
-
-### Built-in Metrics
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│ Deer Flow Metrics │
-├─────────────────────────────────────────────────────────────────┤
-│ │
-│ Workflow Metrics: │
-│ • deerflow_workflows_total{status} │
-│ • deerflow_workflow_duration_seconds{workflow} │
-│ • deerflow_workflows_active │
-│ │
-│ Task Metrics: │
-│ • deerflow_tasks_total{type, status} │
-│ • deerflow_task_duration_seconds{type} │
-│ • deerflow_task_retries_total{type} │
-│ • deerflow_tasks_queued │
-│ │
-│ Worker Metrics: │
-│ • deerflow_workers_active │
-│ • deerflow_worker_utilization{worker} │
-│ • deerflow_worker_tasks_processed{worker} │
-│ │
-│ System Metrics: │
-│ • deerflow_queue_depth{queue} │
-│ • deerflow_scheduler_lag_seconds │
-│ • deerflow_api_requests_total{endpoint, status} │
-│ │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-### Prometheus Integration
-
-```yaml
-# config/metrics.yaml
-metrics:
- enabled: true
- port: 9090
- path: /metrics
-
- prometheus:
- scrape_interval: 15s
- labels:
- environment: production
- service: deerflow
-
- custom_metrics:
- - name: data_processed_bytes
- type: counter
- description: "Total bytes processed"
- labels: [workflow, task]
-
- - name: processing_latency
- type: histogram
- description: "Processing latency distribution"
- buckets: [0.1, 0.5, 1, 5, 10, 30, 60]
-```
-
-### Custom Metrics
-
-```python
-from deerflow import Workflow
-from deerflow.metrics import Counter, Histogram, Gauge
-
-# Define custom metrics
-records_processed = Counter(
- 'deerflow_records_processed_total',
- 'Total records processed',
- ['workflow', 'task', 'status']
-)
-
-processing_time = Histogram(
- 'deerflow_processing_time_seconds',
- 'Time to process records',
- ['workflow', 'task'],
- buckets=[0.1, 0.5, 1, 5, 10, 30]
-)
-
-active_connections = Gauge(
- 'deerflow_active_connections',
- 'Number of active database connections',
- ['database']
-)
-
-workflow = Workflow(name="instrumented_workflow")
-
-@workflow.task(id="process_records")
-def process_records(context):
- with processing_time.labels(
- workflow=context.workflow.name,
- task=context.task.id
- ).time():
- records = fetch_records()
-
- for record in records:
- try:
- process(record)
- records_processed.labels(
- workflow=context.workflow.name,
- task=context.task.id,
- status="success"
- ).inc()
- except Exception:
- records_processed.labels(
- workflow=context.workflow.name,
- task=context.task.id,
- status="error"
- ).inc()
-```
-
-## Logging
-
-### Structured Logging
-
-```python
-from deerflow.logging import get_logger
-
-logger = get_logger(__name__)
-
-@workflow.task(id="logged_task")
-def logged_task(context):
- logger.info(
- "Starting task processing",
- extra={
- "workflow_id": context.workflow.id,
- "task_id": context.task.id,
- "execution_id": context.execution.id,
- "params": context.params
- }
- )
-
- try:
- result = process_data()
- logger.info(
- "Task completed successfully",
- extra={
- "result_count": len(result),
- "duration_ms": context.elapsed_ms
- }
- )
- return result
- except Exception as e:
- logger.error(
- "Task failed",
- extra={"error": str(e)},
- exc_info=True
- )
- raise
-```
-
-### Log Configuration
-
-```yaml
-# config/logging.yaml
-logging:
- level: INFO
- format: json
-
- handlers:
- console:
- enabled: true
- level: INFO
-
- file:
- enabled: true
- path: /var/log/deerflow/app.log
- rotation: daily
- retention: 30d
-
- elasticsearch:
- enabled: true
- hosts:
- - http://elasticsearch:9200
- index: deerflow-logs-{date}
-
- filters:
- - name: sensitive_data
- action: redact
- patterns:
- - "password"
- - "api_key"
- - "secret"
-```
-
-### Log Aggregation
-
-```yaml
-# fluent-bit/config.yaml
-[INPUT]
- Name tail
- Path /var/log/deerflow/*.log
- Parser json
- Tag deerflow.*
-
-[FILTER]
- Name modify
- Match deerflow.*
- Add cluster ${CLUSTER_NAME}
- Add environment ${ENVIRONMENT}
-
-[OUTPUT]
- Name es
- Match deerflow.*
- Host elasticsearch
- Port 9200
- Index deerflow-logs
- Type _doc
-```
-
-## Distributed Tracing
-
-### OpenTelemetry Integration
-
-```python
-from opentelemetry import trace
-from opentelemetry.sdk.trace import TracerProvider
-from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
-from deerflow.tracing import DeerFlowInstrumentor
-
-# Configure tracing
-trace.set_tracer_provider(TracerProvider())
-otlp_exporter = OTLPSpanExporter(endpoint="http://jaeger:4317")
-trace.get_tracer_provider().add_span_processor(
- BatchSpanProcessor(otlp_exporter)
-)
-
-# Instrument Deer Flow
-DeerFlowInstrumentor().instrument()
-
-# Custom spans
-tracer = trace.get_tracer(__name__)
-
-@workflow.task(id="traced_task")
-def traced_task(context):
- with tracer.start_as_current_span("process_batch") as span:
- span.set_attribute("batch_size", 100)
-
- for i in range(100):
- with tracer.start_as_current_span(f"process_item_{i}"):
- process_item(i)
-
- span.set_attribute("items_processed", 100)
-```
-
-### Trace Context Propagation
-
-```python
-from deerflow.tracing import inject_context, extract_context
-
-@workflow.task(id="upstream")
-def upstream_task(context):
- # Inject trace context for downstream
- headers = {}
- inject_context(headers)
-
- # Pass to external service
- response = requests.post(
- "https://api.example.com/process",
- headers=headers,
- json={"data": "..."}
- )
- return response.json()
-
-@workflow.task(id="downstream")
-def downstream_task(context):
- # Extract context from upstream
- parent_context = extract_context(context.input.headers)
-
- with tracer.start_as_current_span("downstream", context=parent_context):
- # Continue trace
- pass
-```
-
-## Dashboards
-
-### Grafana Dashboard
-
-```json
-{
- "dashboard": {
- "title": "Deer Flow Overview",
- "panels": [
- {
- "title": "Workflow Executions",
- "type": "timeseries",
- "targets": [
- {
- "expr": "sum(rate(deerflow_workflows_total[5m])) by (status)",
- "legendFormat": "{{status}}"
- }
- ]
- },
- {
- "title": "Task Queue Depth",
- "type": "gauge",
- "targets": [
- {
- "expr": "deerflow_tasks_queued",
- "legendFormat": "Queued Tasks"
- }
- ]
- },
- {
- "title": "Worker Utilization",
- "type": "heatmap",
- "targets": [
- {
- "expr": "deerflow_worker_utilization",
- "legendFormat": "{{worker}}"
- }
- ]
- },
- {
- "title": "P95 Task Duration",
- "type": "stat",
- "targets": [
- {
- "expr": "histogram_quantile(0.95, rate(deerflow_task_duration_seconds_bucket[5m]))"
- }
- ]
- }
- ]
- }
-}
-```
-
-### Key Metrics Dashboard
-
-```yaml
-# Dashboard panels
-panels:
- - name: Workflow Success Rate
- query: |
- sum(rate(deerflow_workflows_total{status="success"}[1h]))
- /
- sum(rate(deerflow_workflows_total[1h])) * 100
- thresholds:
- critical: 95
- warning: 99
-
- - name: Average Task Duration
- query: |
- avg(rate(deerflow_task_duration_seconds_sum[5m])
- /
- rate(deerflow_task_duration_seconds_count[5m]))
-
- - name: Queue Wait Time
- query: |
- histogram_quantile(0.95,
- rate(deerflow_task_queue_time_seconds_bucket[5m]))
-
- - name: Error Rate
- query: |
- sum(rate(deerflow_tasks_total{status="failed"}[5m]))
- /
- sum(rate(deerflow_tasks_total[5m])) * 100
-```
-
-## Alerting
-
-### Alert Rules
-
-```yaml
-# prometheus/alerts.yaml
-groups:
- - name: deerflow
- rules:
- - alert: HighWorkflowFailureRate
- expr: |
- sum(rate(deerflow_workflows_total{status="failed"}[5m]))
- /
- sum(rate(deerflow_workflows_total[5m])) > 0.1
- for: 5m
- labels:
- severity: critical
- annotations:
- summary: "High workflow failure rate"
- description: "Failure rate is {{ $value | humanizePercentage }}"
-
- - alert: TaskQueueBacklog
- expr: deerflow_tasks_queued > 1000
- for: 10m
- labels:
- severity: warning
- annotations:
- summary: "Task queue backlog"
- description: "{{ $value }} tasks in queue"
-
- - alert: WorkerPoolExhausted
- expr: deerflow_workers_active / deerflow_workers_total > 0.95
- for: 5m
- labels:
- severity: warning
- annotations:
- summary: "Worker pool near capacity"
-
- - alert: SchedulerLag
- expr: deerflow_scheduler_lag_seconds > 60
- for: 5m
- labels:
- severity: critical
- annotations:
- summary: "Scheduler lag detected"
- description: "Lag is {{ $value }} seconds"
-```
-
-### Notification Channels
-
-```yaml
-# config/notifications.yaml
-notifications:
- channels:
- slack:
- webhook: https://hooks.slack.com/services/...
- channel: "#deerflow-alerts"
- templates:
- critical: |
- :rotating_light: *CRITICAL ALERT*
- *Alert:* {{ .AlertName }}
- *Description:* {{ .Description }}
- *Value:* {{ .Value }}
-
- pagerduty:
- service_key: ${PAGERDUTY_KEY}
- severity_mapping:
- critical: critical
- warning: warning
- info: info
-
- email:
- smtp_host: smtp.example.com
- from: alerts@example.com
- to:
- - oncall@example.com
-
- routing:
- - match:
- severity: critical
- channels: [pagerduty, slack]
-
- - match:
- severity: warning
- channels: [slack]
-
- - match:
- severity: info
- channels: [email]
-```
-
-## Health Checks
-
-### Endpoint Configuration
-
-```python
-from deerflow.health import HealthCheck, health_check
-
-app = HealthCheck()
-
-@health_check("database")
-async def check_database():
- async with get_db_connection() as conn:
- await conn.execute("SELECT 1")
- return {"status": "healthy", "latency_ms": 5}
-
-@health_check("queue")
-async def check_queue():
- depth = await get_queue_depth()
- return {
- "status": "healthy" if depth < 10000 else "degraded",
- "queue_depth": depth
- }
-
-@health_check("scheduler")
-async def check_scheduler():
- lag = await get_scheduler_lag()
- return {
- "status": "healthy" if lag < 30 else "unhealthy",
- "lag_seconds": lag
- }
-
-# Endpoints
-# GET /health - Overall health
-# GET /health/live - Liveness (is the process running)
-# GET /health/ready - Readiness (can accept traffic)
-```
-
-## Summary
-
-In this chapter, you've learned:
-
-- **Metrics Collection**: Prometheus integration and custom metrics
-- **Logging**: Structured logging and aggregation
-- **Tracing**: Distributed tracing with OpenTelemetry
-- **Dashboards**: Grafana dashboard creation
-- **Alerting**: Alert rules and notifications
-- **Health Checks**: Liveness and readiness probes
-
-## Key Takeaways
-
-1. **Instrument Everything**: Metrics for all operations
-2. **Structured Logs**: JSON for easy querying
-3. **Distributed Tracing**: Follow requests across services
-4. **Meaningful Dashboards**: Focus on key indicators
-5. **Actionable Alerts**: Alert on symptoms, not noise
-
-## Next Steps
-
-Ready to explore advanced orchestration patterns? Let's dive into Chapter 8.
-
----
-
-**Ready for Chapter 8?** [Advanced Patterns](08-advanced-patterns.md)
-
-*Generated for [Awesome Code Docs](https://github.com/johnxie/awesome-code-docs)*
-
-## What Problem Does This Solve?
-
-Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for `context`, `workflow`, `deerflow` so behavior stays predictable as complexity grows.
-
-In practical terms, this chapter helps you avoid three common failures:
-
-- coupling core logic too tightly to one implementation path
-- missing the handoff boundaries between setup, execution, and validation
-- shipping changes without clear rollback or observability strategy
-
-After working through this chapter, you should be able to reason about `Chapter 7: Monitoring` as an operating subsystem inside **Deer Flow Tutorial: Distributed Workflow Orchestration Platform**, with explicit contracts for inputs, state transitions, and outputs.
-
-Use the implementation notes around `task`, `status`, `rate` as your checklist when adapting these patterns to your own repository.
-
-## How it Works Under the Hood
-
-Under the hood, `Chapter 7: Monitoring` usually follows a repeatable control path:
-
-1. **Context bootstrap**: initialize runtime config and prerequisites for `context`.
-2. **Input normalization**: shape incoming data so `workflow` receives stable contracts.
-3. **Core execution**: run the main logic branch and propagate intermediate state through `deerflow`.
-4. **Policy and safety checks**: enforce limits, auth scopes, and failure boundaries.
-5. **Output composition**: return canonical result payloads for downstream consumers.
-6. **Operational telemetry**: emit logs/metrics needed for debugging and performance tuning.
-
-When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
-
-## Source Walkthrough
-
-Use the following upstream sources to verify implementation details while reading this chapter:
-
-- [Official Documentation](https://github.com/bytedance/deer-flow/tree/main/docs)
- Why it matters: authoritative reference on `Official Documentation` (github.com).
-- [GitHub Repository](https://github.com/bytedance/deer-flow)
- Why it matters: authoritative reference on `GitHub Repository` (github.com).
-- [API Reference](https://github.com/bytedance/deer-flow/blob/main/docs/API.md)
- Why it matters: authoritative reference on `API Reference` (github.com).
-- [Community & Issues](https://github.com/bytedance/deer-flow/issues)
- Why it matters: authoritative reference on `Community & Issues` (github.com).
-- [Workflow Examples](https://github.com/bytedance/deer-flow/tree/main/examples)
- Why it matters: authoritative reference on `Workflow Examples` (github.com).
-- [AI Codebase Knowledge Builder](https://github.com/johnxie/awesome-code-docs)
- Why it matters: authoritative reference on `AI Codebase Knowledge Builder` (github.com).
-
-Suggested trace strategy:
-- search upstream code for `context` and `workflow` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
-
-## Chapter Connections
-
-- [Tutorial Index](README.md)
-- [Previous Chapter: Chapter 6: Scaling](06-scaling.md)
-- [Next Chapter: Chapter 8: Advanced Patterns](08-advanced-patterns.md)
-- [Main Catalog](../../README.md#-tutorial-catalog)
-- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
diff --git a/tutorials/deer-flow-tutorial/07-podcast-multimodal.md b/tutorials/deer-flow-tutorial/07-podcast-multimodal.md
new file mode 100644
index 00000000..2ef75c6f
--- /dev/null
+++ b/tutorials/deer-flow-tutorial/07-podcast-multimodal.md
@@ -0,0 +1,398 @@
+---
+layout: default
+title: "Chapter 7: Podcast and Multi-Modal Output"
+parent: "DeerFlow Tutorial"
+nav_order: 7
+format_version: v2
+why: "DeerFlow can produce more than text reports. Understanding the podcast, PowerPoint, chart, and image generation pipelines lets you deliver research outputs in formats suited to different audiences — audio summaries for busy executives, slides for presentations, charts for data-heavy analysis."
+mental_model: "Every output format is a skill. The agent reads the skill's SKILL.md, follows its workflow, generates an intermediate artifact (a JSON script, a data file, a chart spec), runs a Python script in the sandbox to convert it to the final format (MP3, PPTX, PNG), and stores it in the outputs directory. The Gateway API serves the artifact for download."
+learning_outcomes:
+ - Understand the podcast generation workflow from research to MP3 audio
+ - Generate PowerPoint presentations from research using the ppt-generation skill
+ - Use the chart-visualization skill to produce charts from data
+ - Understand how image and video generation skills integrate with external APIs
+ - Configure Volcengine TTS credentials for podcast output
+snapshot:
+ repo: bytedance/deer-flow
+ stars: ~53.5k
+ last_checked: 2026-04-12
+chapter_map:
+ - "01: Installation and first query"
+ - "02: LangGraph state machine internals"
+ - "03: Research pipeline deep dive"
+ - "04: RAG and search tools"
+ - "05: Frontend and API design"
+ - "06: Skills and extensions"
+ - "07 (this): Podcast and multi-modal outputs"
+ - "08: Production deployment"
+sources:
+ - https://github.com/bytedance/deer-flow/blob/main/skills/public/podcast-generation/SKILL.md
+ - https://github.com/bytedance/deer-flow/blob/main/skills/public/podcast-generation/scripts/generate.py
+ - https://github.com/bytedance/deer-flow/blob/main/skills/public/ppt-generation/SKILL.md
+ - https://github.com/bytedance/deer-flow/blob/main/skills/public/chart-visualization/SKILL.md
+ - https://github.com/bytedance/deer-flow/blob/main/skills/public/image-generation/SKILL.md
+---
+
+# Chapter 7: Podcast and Multi-Modal Output
+
+## What Problem Does This Solve?
+
+A 10-page research report is not always the right format. Executives want audio summaries they can consume during a commute. Teams want slide decks for presentations. Data analysis needs charts, not prose descriptions of numbers. DeerFlow's multi-modal output system converts research into whichever format the audience needs, using the same underlying agent and research pipeline.
+
+The key insight: every output format is implemented as a **skill**. The agent researches the topic, then uses the appropriate skill's workflow to transform the research into the target format — running Python scripts in the sandbox to handle the actual conversion (TTS API calls, PPTX generation, chart rendering).
+
+## How it Works Under the Hood
+
+### The General Multi-Modal Output Architecture
+
+```mermaid
+graph TB
+ A[User: generate podcast about X] --> B[Agent loads podcast-generation skill]
+ B --> C[Research Phase<br/>web_search + web_fetch]
+ C --> D[Script Generation<br/>Agent writes JSON dialogue script]
+ D --> E[bash: python generate.py<br/>--script-file script.json<br/>--output-file podcast.mp3]
+ E --> F{External API call}
+ F --> G[Volcengine TTS API<br/>converts dialogue to audio]
+ G --> H[MP3 saved to outputs/]
+ H --> I[ThreadState.artifacts updated]
+ I --> J[Frontend shows download link]
+ J --> K[GET /gateway/artifacts/{thread_id}/podcast.mp3]
+```
+
+### Podcast Generation
+
+The podcast generation skill (`skills/public/podcast-generation/SKILL.md`) converts any research content into a two-host conversational MP3:
+
+**Step 1: Trigger the skill**
+
+```
+# In the DeerFlow chat:
+"Research the current state of quantum computing and generate a podcast about it"
+# or, if research was already done:
+"Generate a podcast from my previous research on quantum computing"
+```
+
+**Step 2: Script creation**
+
+The agent generates a JSON dialogue script following the skill's specification:
+
+```json
+// Example: /mnt/user-data/workspace/{thread_id}/podcast_script.json
+{
+ "title": "Quantum Computing: Where We Are Today",
+ "locale": "en",
+ "lines": [
+ {
+ "speaker": "female",
+ "line": "Hello Deer! Today we're diving into quantum computing — and there's a lot happening right now."
+ },
+ {
+ "speaker": "male",
+ "line": "That's right. We've seen some major milestones this year. Google's Willow chip, for instance, claimed to solve a problem in 5 minutes that would take classical computers 10 septillion years."
+ },
+ {
+ "speaker": "female",
+ "line": "Septillion — that's a one followed by 24 zeros, for anyone keeping track at home. But let's back up. What does a quantum computer actually do differently?"
+ },
+ {
+ "speaker": "male",
+ "line": "Classical computers use bits — zeros and ones. Quantum computers use qubits, which can exist in a superposition of zero and one simultaneously."
+ }
+ ]
+}
+```
+
+**Content guidelines enforced by the skill:**
+- Target 40-60 lines (~10 minutes of audio)
+- Natural, conversational language — "like two friends chatting"
+- Greetings include "Hello Deer"
+- No technical jargon, formulas, or code
+- Short, speakable sentences
+
+**Step 3: Audio generation**
+
+The agent runs the generation script:
+
+```bash
+# Executed via bash tool in the sandbox
+python /mnt/skills/podcast-generation/scripts/generate.py \
+ --script-file /mnt/user-data/workspace/{thread_id}/podcast_script.json \
+ --output-file /mnt/user-data/outputs/{thread_id}/quantum_computing_podcast.mp3 \
+ --transcript-file /mnt/user-data/outputs/{thread_id}/podcast_transcript.md
+```
+
+```python
+# skills/public/podcast-generation/scripts/generate.py
+import json
+import argparse
+from volcengine.tts import TTS # Volcengine Text-to-Speech SDK
+
+def generate_podcast(script_file: str, output_file: str, transcript_file: str | None):
+ with open(script_file) as f:
+ script = json.load(f)
+
+ tts = TTS(
+ app_id=os.environ["VOLCENGINE_TTS_APP_ID"],
+ access_token=os.environ["VOLCENGINE_TTS_ACCESS_TOKEN"],
+ cluster=os.environ["VOLCENGINE_TTS_CLUSTER"],
+ )
+
+ audio_segments = []
+ transcript_lines = []
+
+ for line in script["lines"]:
+ # Select voice based on speaker
+ voice_id = "en_female_1" if line["speaker"] == "female" else "en_male_1"
+
+ # Generate audio for this line
+ audio = tts.synthesize(
+ text=line["line"],
+ voice_type=voice_id,
+ encoding="mp3",
+ )
+ audio_segments.append(audio)
+ transcript_lines.append(f"**{line['speaker'].title()}:** {line['line']}\n")
+
+ # Concatenate all audio segments
+ combine_audio(audio_segments, output_file)
+
+ # Write transcript
+ if transcript_file:
+ with open(transcript_file, "w") as f:
+ f.write(f"# {script['title']}\n\n")
+ f.writelines(transcript_lines)
+
+ print(f"Podcast saved: {output_file}")
+ print(f"Duration: ~{len(script['lines']) * 15 // 60} minutes")
+
+if __name__ == "__main__":
+ parser = argparse.ArgumentParser()
+ parser.add_argument("--script-file", required=True)
+ parser.add_argument("--output-file", required=True)
+ parser.add_argument("--transcript-file")
+ args = parser.parse_args()
+ generate_podcast(args.script_file, args.output_file, args.transcript_file)
+```
+
+**Required credentials:**
+
+```bash
+# .env
+VOLCENGINE_TTS_APP_ID=...
+VOLCENGINE_TTS_ACCESS_TOKEN=...
+VOLCENGINE_TTS_CLUSTER=...
+```
+
+These are Volcengine (ByteDance's cloud platform) credentials. Without them, the generate.py script will fail at the TTS API call. For non-Volcengine deployments, modify `generate.py` to use ElevenLabs, OpenAI TTS, or any other TTS provider.
+
+### PowerPoint Generation
+
+The `ppt-generation` skill converts research into PPTX slides:
+
+```
+# Trigger:
+"Create a PowerPoint presentation about AI agent frameworks for my team presentation"
+```
+
+The skill uses Python-PPTX or a similar library to generate slides:
+
+```python
+# skills/public/ppt-generation/scripts/generate.py (conceptual)
+from pptx import Presentation
+from pptx.util import Inches, Pt
+import json
+
+def generate_presentation(content_file: str, output_file: str):
+ """
+ Convert structured research content to PPTX.
+ Content file is a JSON with slides, each having title, bullets, and notes.
+ """
+ with open(content_file) as f:
+ content = json.load(f)
+
+ prs = Presentation()
+
+ for slide_data in content["slides"]:
+ if slide_data["type"] == "title":
+ layout = prs.slide_layouts[0]
+ slide = prs.slides.add_slide(layout)
+ slide.shapes.title.text = slide_data["title"]
+ slide.placeholders[1].text = slide_data.get("subtitle", "")
+ else:
+ layout = prs.slide_layouts[1]
+ slide = prs.slides.add_slide(layout)
+ slide.shapes.title.text = slide_data["title"]
+ body = slide.placeholders[1]
+ tf = body.text_frame
+ for bullet in slide_data.get("bullets", []):
+ p = tf.add_paragraph()
+ p.text = bullet
+ p.level = 0
+
+ prs.save(output_file)
+ print(f"Presentation saved: {output_file}")
+```
+
+### Chart Visualization
+
+The `chart-visualization` skill supports 25+ chart types:
+
+```
+# Trigger:
+"Create a bar chart comparing GitHub stars of popular AI agent frameworks"
+```
+
+```javascript
+// skills/public/chart-visualization/scripts/generate.js
+// Uses AntV G2 or similar charting library for high-quality output
+
+const { Chart } = require('@antv/g2');
+const fs = require('fs');
+const data = JSON.parse(fs.readFileSync(process.argv[2]));
+
+// Chart spec from agent:
+const spec = {
+ type: 'interval',
+ data: data,
+ encode: {
+ x: 'framework',
+ y: 'stars',
+ color: 'framework',
+ },
+ style: { fill: 'gradient' },
+};
+
+// Render to PNG
+const chart = new Chart({ width: 800, height: 500 });
+chart.options(spec);
+chart.render();
+chart.exportPNG(process.argv[3]);
+```
+
+Supported chart types include: bar, column, line, area, scatter, histogram, pie, donut, radar, heatmap, treemap, sankey, network graph, org chart, flow diagram, fishbone diagram, mind map, district map, and more.
+
+### Image Generation
+
+The `image-generation` skill integrates with external image generation APIs:
+
+```
+# Trigger:
+"Generate an illustration of a neural network with multiple layers for my presentation"
+```
+
+```python
+# skills/public/image-generation/scripts/generate.py
+import openai
+import requests
+
+def generate_image(prompt: str, output_file: str, size: str = "1024x1024"):
+ """Generate an image using OpenAI DALL-E 3 or similar."""
+ client = openai.OpenAI()
+
+ response = client.images.generate(
+ model="dall-e-3",
+ prompt=prompt,
+ size=size,
+ quality="standard",
+ n=1,
+ )
+
+ image_url = response.data[0].url
+ image_data = requests.get(image_url).content
+
+ with open(output_file, "wb") as f:
+ f.write(image_data)
+
+ print(f"Image saved: {output_file}")
+ print(f"Revised prompt: {response.data[0].revised_prompt}")
+```
+
+### Video Generation
+
+The `video-generation` skill integrates with video generation APIs (Sora, Runway, or equivalent):
+
+```python
+# skills/public/video-generation/scripts/generate.py
+# Calls external video generation API with a text prompt
+# Polls for completion and downloads the final video file
+```
+
+### The Outputs Directory and Artifact Tracking
+
+All generated artifacts (MP3s, PDFs, PNGs, PPTX files) are stored in:
+
+```
+/mnt/user-data/outputs/{thread_id}/
+├── research_report.md
+├── podcast_script.json
+├── quantum_computing_podcast.mp3
+├── podcast_transcript.md
+├── framework_comparison.png
+└── ai_frameworks_presentation.pptx
+```
+
+The agent updates `ThreadState.artifacts` with the paths of generated files using the `merge_artifacts` reducer. The frontend detects artifact entries and shows download links.
+
+```python
+# How artifacts are tracked (ThreadState reducer)
+def merge_artifacts(existing: list[str], new: list[str]) -> list[str]:
+ """Append-only reducer: new artifacts are added, existing are not removed."""
+ return existing + [a for a in new if a not in existing]
+```
+
+### Multi-Modal Output Selection Guide
+
+```mermaid
+graph TB
+ A[Research complete] --> B{Who is the audience?}
+ B -->|Technical team| C[Markdown report with citations<br/>Default output]
+ B -->|Executive / busy reader| D[Podcast MP3<br/>podcast-generation skill]
+ B -->|Board / clients| E[PowerPoint slides<br/>ppt-generation skill]
+ B -->|Data-heavy findings| F[Charts + brief report<br/>chart-visualization skill]
+ B -->|All of the above| G[Multi-format bundle<br/>Combine multiple skills in one session]
+```
+
+### Template-Based Output Customization
+
+Skills include templates that control output style and structure:
+
+```markdown
+# skills/public/podcast-generation/templates/tech-explainer.md
+# Tech Explainer Template
+
+## Format
+- Duration: 8-12 minutes
+- Tone: Educational but accessible
+- Structure:
+ 1. Hook: surprising fact or question (30 seconds)
+ 2. Background: what the technology is (2 minutes)
+ 3. How it works: simplified explanation (3 minutes)
+ 4. Why it matters: real-world impact (2 minutes)
+ 5. Future outlook (1 minute)
+ 6. Call to action: where to learn more (30 seconds)
+
+## Language Guidelines
+- Explain all technical terms when first used
+- Use analogies liberally
+- Avoid passive voice
+```
+
+Specify a template in your request:
+
+```
+"Generate a podcast about reinforcement learning using the tech-explainer format"
+```
+
+## Summary
+
+DeerFlow's multi-modal output system is built on the skills framework. Each output format has a skill (podcast-generation, ppt-generation, chart-visualization, image-generation, video-generation) that guides the agent through research → script/spec generation → sandbox execution → artifact storage. The podcast skill uses Volcengine TTS for audio generation. All artifacts are tracked in `ThreadState.artifacts` and served via the Gateway API.
+
+---
+
+## Chapter Connections
+
+- [Tutorial Index](README.md)
+- [Previous Chapter: Chapter 6: Customization and Extension](06-customization-extension.md)
+- [Next Chapter: Chapter 8: Production Deployment and Advanced Patterns](08-production-deployment.md)
+- [Main Catalog](../../README.md#-tutorial-catalog)
+- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
diff --git a/tutorials/deer-flow-tutorial/08-advanced-patterns.md b/tutorials/deer-flow-tutorial/08-advanced-patterns.md
deleted file mode 100644
index 966da0d6..00000000
--- a/tutorials/deer-flow-tutorial/08-advanced-patterns.md
+++ /dev/null
@@ -1,542 +0,0 @@
----
-layout: default
-title: "Chapter 8: Advanced Patterns"
-parent: "Deer Flow Tutorial"
-nav_order: 8
----
-
-# Chapter 8: Advanced Patterns
-
-Welcome to **Chapter 8: Advanced Patterns**. In this part of **Deer Flow Tutorial: Distributed Workflow Orchestration Platform**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
-
-
-> Master sophisticated orchestration patterns for complex workflow scenarios.
-
-## Overview
-
-This chapter covers advanced workflow patterns including dynamic workflows, event-driven architectures, sub-workflows, and complex orchestration scenarios that solve real-world distributed system challenges.
-
-## Dynamic Workflows
-
-### Runtime Task Generation
-
-```python
-from deerflow import Workflow, DynamicTasks
-
-workflow = Workflow(name="dynamic_etl")
-
-@workflow.task(id="discover_sources")
-def discover_sources(context):
- """Discover data sources at runtime."""
- sources = list_s3_buckets(prefix="data-")
- return {"sources": sources}
-
-@workflow.dynamic_tasks(id="process_sources", depends_on=["discover_sources"])
-def generate_processing_tasks(context):
- """Generate a task for each discovered source."""
- sources = context.tasks["discover_sources"].output["sources"]
-
- tasks = []
- for source in sources:
- tasks.append({
- "id": f"process_{source['name']}",
- "type": "python",
- "config": {
- "script": "process_source.py",
- "args": [source["uri"]]
- }
- })
-
- return tasks
-
-@workflow.task(id="aggregate", depends_on=["process_sources"])
-def aggregate_results(context):
- """Aggregate results from all dynamic tasks."""
- results = []
- for task_id, output in context.dynamic_outputs["process_sources"].items():
- results.append(output)
- return {"total_records": sum(r["count"] for r in results)}
-```
-
-### Parameterized Workflow Templates
-
-```python
-from deerflow import WorkflowTemplate
-
-template = WorkflowTemplate(
- name="data_pipeline_template",
- parameters={
- "source_type": {"type": "string", "enum": ["s3", "gcs", "azure"]},
- "destination": {"type": "string"},
- "parallelism": {"type": "integer", "default": 5}
- }
-)
-
-@template.task(id="extract")
-def extract(context):
- source_type = context.params["source_type"]
- # Extract based on source type
- pass
-
-@template.task(id="transform", depends_on=["extract"])
-def transform(context):
- pass
-
-@template.task(id="load", depends_on=["transform"])
-def load(context):
- destination = context.params["destination"]
- pass
-
-# Instantiate for different configurations
-s3_pipeline = template.instantiate(
- name="s3_to_warehouse",
- parameters={"source_type": "s3", "destination": "snowflake"}
-)
-
-gcs_pipeline = template.instantiate(
- name="gcs_to_warehouse",
- parameters={"source_type": "gcs", "destination": "bigquery"}
-)
-```
-
-## Sub-Workflows
-
-### Nested Workflows
-
-```python
-from deerflow import Workflow, SubWorkflow
-
-# Define reusable sub-workflow
-validation_workflow = Workflow(name="data_validation")
-
-@validation_workflow.task(id="schema_check")
-def check_schema(context):
- return validate_schema(context.input)
-
-@validation_workflow.task(id="quality_check", depends_on=["schema_check"])
-def check_quality(context):
- return validate_quality(context.input)
-
-# Main workflow using sub-workflow
-main_workflow = Workflow(name="etl_with_validation")
-
-@main_workflow.task(id="extract")
-def extract(context):
- return fetch_data()
-
-@main_workflow.sub_workflow(
- id="validate",
- workflow=validation_workflow,
- depends_on=["extract"]
-)
-
-@main_workflow.task(id="transform", depends_on=["validate"])
-def transform(context):
- validated_data = context.tasks["validate"].output
- return transform_data(validated_data)
-```
-
-### Workflow Composition
-
-```python
-from deerflow import compose_workflows
-
-# Compose multiple workflows
-composed = compose_workflows(
- name="full_pipeline",
- workflows=[
- {"workflow": "extraction_workflow", "alias": "extract"},
- {"workflow": "transformation_workflow", "alias": "transform", "depends_on": ["extract"]},
- {"workflow": "loading_workflow", "alias": "load", "depends_on": ["transform"]}
- ],
- connections={
- "transform.input": "extract.output",
- "load.input": "transform.output"
- }
-)
-```
-
-## Event-Driven Patterns
-
-### Event Triggers
-
-```python
-from deerflow import Workflow, EventTrigger
-from deerflow.events import S3Event, KafkaEvent, WebhookEvent
-
-workflow = Workflow(name="event_driven_pipeline")
-
-# S3 event trigger
-workflow.add_trigger(
- S3Event(
- bucket="data-lake",
- prefix="incoming/",
- events=["s3:ObjectCreated:*"],
- filter={"suffix": ".parquet"}
- )
-)
-
-# Kafka event trigger
-workflow.add_trigger(
- KafkaEvent(
- topic="data-events",
- consumer_group="deerflow",
- filter=lambda msg: msg["type"] == "new_data"
- )
-)
-
-# Webhook trigger
-workflow.add_trigger(
- WebhookEvent(
- path="/trigger/pipeline",
- method="POST",
- auth="api_key"
- )
-)
-
-@workflow.task(id="process_event")
-def process_event(context):
- event = context.trigger_event
- if event.type == "s3":
- return process_s3_file(event.bucket, event.key)
- elif event.type == "kafka":
- return process_kafka_message(event.message)
-```
-
-### Event Sourcing Pattern
-
-```python
-from deerflow import Workflow, EventStore
-
-event_store = EventStore(backend="kafka", topic="workflow-events")
-
-workflow = Workflow(name="event_sourced_order")
-
-@workflow.task(id="create_order")
-def create_order(context):
- order = {"id": uuid4(), "items": context.params["items"]}
-
- # Publish event
- event_store.publish({
- "type": "OrderCreated",
- "payload": order,
- "timestamp": datetime.utcnow()
- })
-
- return order
-
-@workflow.task(id="process_payment", depends_on=["create_order"])
-def process_payment(context):
- order = context.tasks["create_order"].output
-
- result = charge_payment(order)
-
- event_store.publish({
- "type": "PaymentProcessed",
- "payload": {"order_id": order["id"], "status": result["status"]},
- "timestamp": datetime.utcnow()
- })
-
- return result
-```
-
-## Saga Pattern
-
-### Distributed Transactions
-
-```python
-from deerflow import Workflow, Saga, CompensatingAction
-
-workflow = Workflow(name="order_saga")
-
-@workflow.saga
-class OrderSaga(Saga):
- @step(order=1)
- def reserve_inventory(self, context):
- return inventory_service.reserve(context.params["items"])
-
- @step(order=1, compensate="release_inventory")
- def release_inventory(self, context, reservation):
- inventory_service.release(reservation["id"])
-
- @step(order=2)
- def charge_payment(self, context):
- return payment_service.charge(
- context.params["customer_id"],
- context.params["amount"]
- )
-
- @step(order=2, compensate="refund_payment")
- def refund_payment(self, context, payment):
- payment_service.refund(payment["id"])
-
- @step(order=3)
- def create_shipment(self, context):
- return shipping_service.create_shipment(
- context.params["address"],
- context.tasks["reserve_inventory"].output["items"]
- )
-
- @step(order=3, compensate="cancel_shipment")
- def cancel_shipment(self, context, shipment):
- shipping_service.cancel(shipment["id"])
-```
-
-### Choreography vs Orchestration
-
-```python
-# Orchestration (centralized control)
-orchestrated_workflow = Workflow(name="orchestrated_order")
-
-@orchestrated_workflow.task(id="coordinator")
-async def coordinate_order(context):
- # Central coordinator manages all steps
- inventory = await call_inventory_service(context.params)
- payment = await call_payment_service(context.params)
- shipping = await call_shipping_service(context.params)
- return {"inventory": inventory, "payment": payment, "shipping": shipping}
-
-# Choreography (event-driven, decentralized)
-choreographed_workflow = Workflow(name="choreographed_order")
-
-@choreographed_workflow.task(id="start_order")
-def start_order(context):
- publish_event("OrderStarted", context.params)
-
-@choreographed_workflow.event_handler("InventoryReserved")
-def on_inventory_reserved(event):
- publish_event("PaymentRequested", event.data)
-
-@choreographed_workflow.event_handler("PaymentCompleted")
-def on_payment_completed(event):
- publish_event("ShipmentRequested", event.data)
-```
-
-## MapReduce Pattern
-
-```python
-from deerflow import Workflow, MapReduce
-
-workflow = Workflow(name="distributed_analysis")
-
-@workflow.map_reduce(
- id="analyze_logs",
- partitions=100,
- reduce_parallelism=10
-)
-class LogAnalysis(MapReduce):
- def partition(self, context):
- """Partition input data."""
- log_files = list_log_files(context.params["date"])
- return [{"file": f} for f in log_files]
-
- def map(self, partition, context):
- """Process each partition."""
- file_path = partition["file"]
- counts = {}
-
- for line in read_log_file(file_path):
- error_type = extract_error_type(line)
- if error_type:
- counts[error_type] = counts.get(error_type, 0) + 1
-
- return counts
-
- def reduce(self, results, context):
- """Combine all results."""
- combined = {}
- for result in results:
- for error_type, count in result.items():
- combined[error_type] = combined.get(error_type, 0) + count
-
- return {
- "total_errors": sum(combined.values()),
- "by_type": combined
- }
-```
-
-## Pipeline Patterns
-
-### Fan-Out / Fan-In
-
-```python
-from deerflow import Workflow, parallel, gather
-
-workflow = Workflow(name="parallel_processing")
-
-@workflow.task(id="split")
-def split_data(context):
- data = load_large_dataset()
- chunks = split_into_chunks(data, num_chunks=10)
- return {"chunks": chunks}
-
-@workflow.parallel_tasks(id="process_chunks", depends_on=["split"])
-def process_chunk(chunk, context):
- """This runs in parallel for each chunk."""
- return process_data(chunk)
-
-@workflow.task(id="merge", depends_on=["process_chunks"])
-def merge_results(context):
- """Gather and merge all parallel results."""
- results = context.parallel_results["process_chunks"]
- return merge_datasets(results)
-```
-
-### Pipeline with Backpressure
-
-```python
-from deerflow import Workflow, Pipeline, Backpressure
-
-workflow = Workflow(name="streaming_pipeline")
-
-@workflow.pipeline(
- backpressure=Backpressure(
- max_buffer_size=1000,
- strategy="block" # block, drop, or sample
- )
-)
-class DataPipeline(Pipeline):
- @stage(parallelism=5)
- def extract(self, item):
- return fetch_record(item)
-
- @stage(parallelism=10)
- def transform(self, record):
- return transform_record(record)
-
- @stage(parallelism=3, batch_size=100)
- def load(self, batch):
- return bulk_insert(batch)
-```
-
-## State Machine Workflows
-
-```python
-from deerflow import Workflow, StateMachine, State, Transition
-
-workflow = Workflow(name="order_state_machine")
-
-@workflow.state_machine
-class OrderStateMachine(StateMachine):
- # Define states
- pending = State(initial=True)
- confirmed = State()
- processing = State()
- shipped = State()
- delivered = State(final=True)
- cancelled = State(final=True)
-
- # Define transitions
- confirm = Transition(source=pending, target=confirmed)
- start_processing = Transition(source=confirmed, target=processing)
- ship = Transition(source=processing, target=shipped)
- deliver = Transition(source=shipped, target=delivered)
- cancel = Transition(source=[pending, confirmed], target=cancelled)
-
- # Transition handlers
- @on_transition(confirm)
- def on_confirm(self, context):
- send_confirmation_email(context.order)
-
- @on_transition(ship)
- def on_ship(self, context):
- notify_customer(context.order, "shipped")
-
- @on_transition(cancel)
- def on_cancel(self, context):
- refund_payment(context.order)
-```
-
-## Summary
-
-In this chapter, you've learned:
-
-- **Dynamic Workflows**: Runtime task generation
-- **Sub-Workflows**: Nested and composed workflows
-- **Event-Driven**: Triggers and event sourcing
-- **Saga Pattern**: Distributed transactions
-- **MapReduce**: Parallel data processing
-- **State Machines**: Complex state transitions
-
-## Key Takeaways
-
-1. **Dynamic for Flexibility**: Generate tasks at runtime
-2. **Compose for Reuse**: Build complex from simple workflows
-3. **Events for Decoupling**: Loose coupling between components
-4. **Sagas for Consistency**: Handle distributed transactions
-5. **Patterns for Scale**: MapReduce for big data
-
-## Tutorial Complete
-
-Congratulations! You've completed the Deer Flow tutorial. You now have the knowledge to:
-
-- Design and implement complex distributed workflows
-- Handle failures with retries, fallbacks, and sagas
-- Scale workflows across clusters
-- Monitor and observe workflow execution
-- Apply advanced orchestration patterns
-
-## Further Resources
-
-- [Deer Flow Documentation](https://github.com/bytedance/deer-flow/tree/main/docs)
-- [GitHub Repository](https://github.com/bytedance/deer-flow)
-- [Example Workflows](https://github.com/bytedance/deer-flow/tree/main/examples)
-
----
-
-*Generated for [Awesome Code Docs](https://github.com/johnxie/awesome-code-docs)*
-
-## What Problem Does This Solve?
-
-Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for `context`, `workflow`, `Workflow` so behavior stays predictable as complexity grows.
-
-In practical terms, this chapter helps you avoid three common failures:
-
-- coupling core logic too tightly to one implementation path
-- missing the handoff boundaries between setup, execution, and validation
-- shipping changes without clear rollback or observability strategy
-
-After working through this chapter, you should be able to reason about `Chapter 8: Advanced Patterns` as an operating subsystem inside **Deer Flow Tutorial: Distributed Workflow Orchestration Platform**, with explicit contracts for inputs, state transitions, and outputs.
-
-Use the implementation notes around `name`, `task`, `order` as your checklist when adapting these patterns to your own repository.
-
-## How it Works Under the Hood
-
-Under the hood, `Chapter 8: Advanced Patterns` usually follows a repeatable control path:
-
-1. **Context bootstrap**: initialize runtime config and prerequisites for `context`.
-2. **Input normalization**: shape incoming data so `workflow` receives stable contracts.
-3. **Core execution**: run the main logic branch and propagate intermediate state through `Workflow`.
-4. **Policy and safety checks**: enforce limits, auth scopes, and failure boundaries.
-5. **Output composition**: return canonical result payloads for downstream consumers.
-6. **Operational telemetry**: emit logs/metrics needed for debugging and performance tuning.
-
-When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
-
-## Source Walkthrough
-
-Use the following upstream sources to verify implementation details while reading this chapter:
-
-- [Official Documentation](https://github.com/bytedance/deer-flow/tree/main/docs)
- Why it matters: authoritative reference on `Official Documentation` (github.com).
-- [GitHub Repository](https://github.com/bytedance/deer-flow)
- Why it matters: authoritative reference on `GitHub Repository` (github.com).
-- [API Reference](https://github.com/bytedance/deer-flow/blob/main/docs/API.md)
- Why it matters: authoritative reference on `API Reference` (github.com).
-- [Community & Issues](https://github.com/bytedance/deer-flow/issues)
- Why it matters: authoritative reference on `Community & Issues` (github.com).
-- [Workflow Examples](https://github.com/bytedance/deer-flow/tree/main/examples)
- Why it matters: authoritative reference on `Workflow Examples` (github.com).
-- [AI Codebase Knowledge Builder](https://github.com/johnxie/awesome-code-docs)
- Why it matters: authoritative reference on `AI Codebase Knowledge Builder` (github.com).
-
-Suggested trace strategy:
-- search upstream code for `context` and `workflow` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
-
-## Chapter Connections
-
-- [Tutorial Index](README.md)
-- [Previous Chapter: Chapter 7: Monitoring](07-monitoring.md)
-- [Main Catalog](../../README.md#-tutorial-catalog)
-- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
diff --git a/tutorials/deer-flow-tutorial/08-production-deployment.md b/tutorials/deer-flow-tutorial/08-production-deployment.md
new file mode 100644
index 00000000..b8e4462c
--- /dev/null
+++ b/tutorials/deer-flow-tutorial/08-production-deployment.md
@@ -0,0 +1,576 @@
+---
+layout: default
+title: "Chapter 8: Production Deployment and Advanced Patterns"
+parent: "DeerFlow Tutorial"
+nav_order: 8
+format_version: v2
+why: "Running DeerFlow in production requires careful attention to sandbox security, checkpointer persistence, observability, resource sizing, and authentication. The default dev configuration is insecure and not suitable for multi-user deployments."
+mental_model: "A production DeerFlow deployment is: Nginx (entry point) + LangGraph Platform (agent runtime with Postgres checkpointer) + FastAPI Gateway (support services) + Next.js (UI) + Docker sandbox containers (isolated code execution). Each component has specific production requirements that differ from the development defaults."
+learning_outcomes:
+ - Deploy DeerFlow with Docker Compose in a production-hardened configuration
+ - Configure Postgres checkpointer for persistent thread state across restarts
+ - Enable LangSmith or Langfuse observability for all LLM calls
+ - Secure the deployment with authentication and network isolation
+ - Configure resource sizing for different workload profiles
+ - Implement health checks and understand recovery patterns
+snapshot:
+ repo: bytedance/deer-flow
+ stars: ~53.5k
+ last_checked: 2026-04-12
+chapter_map:
+ - "01: Installation and first query"
+ - "02: LangGraph state machine internals"
+ - "03: Research pipeline deep dive"
+ - "04: RAG and search tools"
+ - "05: Frontend and API design"
+ - "06: Skills and extensions"
+ - "07: Podcast and multi-modal outputs"
+ - "08 (this): Production deployment"
+sources:
+ - https://github.com/bytedance/deer-flow/blob/main/backend/docs/ARCHITECTURE.md
+ - https://github.com/bytedance/deer-flow/blob/main/backend/docs/SETUP.md
+ - https://github.com/bytedance/deer-flow/blob/main/backend/Dockerfile
+ - https://github.com/bytedance/deer-flow/.env.example
+ - https://github.com/bytedance/deer-flow/blob/main/Makefile
+---
+
+# Chapter 8: Production Deployment and Advanced Patterns
+
+## What Problem Does This Solve?
+
+The `make dev` local setup is designed for a single developer with direct host access. Production deployments face different requirements:
+- **Multi-user access**: multiple users submitting research tasks concurrently
+- **State persistence**: thread history and memory must survive service restarts
+- **Security**: untrusted user inputs must not escape the sandbox; the API must require authentication
+- **Observability**: you need to know when agent runs fail, which LLM calls are expensive, and where latency is concentrated
+- **Resource control**: long-running research jobs must not starve other users
+- **Reliability**: the system must recover from sandbox container crashes, LLM API rate limits, and network failures
+
+This chapter covers each of these production concerns with concrete configuration examples.
+
+## How it Works Under the Hood
+
+### Production Architecture
+
+```mermaid
+graph TB
+ subgraph "Load Balancer / Auth"
+ LB[HTTPS Load Balancer<br/>TLS termination<br/>Authentication gateway]
+ end
+
+ subgraph "Application Layer"
+ N[Nginx :2026<br/>Internal routing]
+ LG[LangGraph Server :2024<br/>AioSandboxProvider<br/>Postgres checkpointer]
+ GW[Gateway API :8001<br/>FastAPI]
+ FE[Next.js :3000]
+ end
+
+ subgraph "Sandbox Layer"
+ SB1[Docker Sandbox<br/>Thread 1]
+ SB2[Docker Sandbox<br/>Thread 2]
+ SBN[Docker Sandbox<br/>Thread N]
+ end
+
+ subgraph "Persistence Layer"
+ PG[PostgreSQL<br/>Thread state + checkpoints]
+ FS[Shared Filesystem / S3<br/>Artifacts, uploads, outputs]
+ end
+
+ subgraph "Observability"
+ LS[LangSmith / Langfuse<br/>LLM call tracing]
+ LOG[Centralized Logging<br/>stdout → aggregator]
+ end
+
+ LB --> N
+ N --> LG
+ N --> GW
+ N --> FE
+ LG --> SB1
+ LG --> SB2
+ LG --> SBN
+ LG --> PG
+ GW --> PG
+ LG --> FS
+ GW --> FS
+ LG --> LS
+```
+
+### Deployment Sizing
+
+ByteDance documents three deployment profiles:
+
+| Profile | CPU | RAM | Disk | Use Case |
+|:--|:--|:--|:--|:--|
+| Local eval | 4 vCPU | 8 GB | 20 GB SSD | Single developer testing |
+| Docker dev | 4 vCPU | 8 GB | 25 GB SSD | Team dev environment |
+| Production server | 8–16 vCPU | 16–32 GB | 40+ GB SSD | Multi-user production |
+
+The large RAM requirement comes from:
+- LangGraph server keeping active thread states in memory
+- Docker sandbox containers (each uses ~256 MB–1 GB)
+- LLM context windows being processed (long research contexts can use GB of memory during inference)
+
+### Production Docker Compose
+
+A production-ready Docker Compose configuration:
+
+```yaml
+# docker-compose.prod.yml
+version: "3.9"
+
+services:
+ nginx:
+ image: nginx:1.25-alpine
+ ports:
+ - "2026:2026"
+ volumes:
+ - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro
+ depends_on:
+ - langgraph
+ - gateway
+ - frontend
+ restart: unless-stopped
+
+ langgraph:
+ build:
+ context: ./backend
+ dockerfile: Dockerfile
+ environment:
+ - LANGGRAPH_POSTGRES_URI=postgresql://deerflow:${DB_PASSWORD}@postgres:5432/deerflow
+ - DEER_FLOW_CONFIG_PATH=/app/config.yaml
+ - LANGCHAIN_TRACING_V2=true
+ - LANGCHAIN_API_KEY=${LANGSMITH_API_KEY}
+ - LANGCHAIN_PROJECT=deer-flow-production
+ volumes:
+ - ./config.yaml:/app/config.yaml:ro
+ - user_data:/mnt/user-data
+ - ./skills:/mnt/skills:ro
+ depends_on:
+ postgres:
+ condition: service_healthy
+ restart: unless-stopped
+ deploy:
+ resources:
+ limits:
+ cpus: "8"
+ memory: 16G
+
+ gateway:
+ build:
+ context: ./backend
+ dockerfile: Dockerfile
+ target: gateway
+ environment:
+ - DEER_FLOW_CONFIG_PATH=/app/config.yaml
+ volumes:
+ - ./config.yaml:/app/config.yaml:ro
+ - user_data:/mnt/user-data
+ - ./extensions_config.json:/app/extensions_config.json
+ restart: unless-stopped
+
+ frontend:
+ build:
+ context: ./frontend
+ dockerfile: Dockerfile
+ environment:
+ - NEXT_PUBLIC_API_URL=http://nginx:2026
+ restart: unless-stopped
+
+ postgres:
+ image: postgres:16-alpine
+ environment:
+ POSTGRES_DB: deerflow
+ POSTGRES_USER: deerflow
+ POSTGRES_PASSWORD: ${DB_PASSWORD}
+ volumes:
+ - postgres_data:/var/lib/postgresql/data
+ healthcheck:
+ test: ["CMD-SHELL", "pg_isready -U deerflow"]
+ interval: 10s
+ timeout: 5s
+ retries: 5
+ restart: unless-stopped
+
+ sandbox:
+ image: bytedance/deer-flow-sandbox:latest
+ volumes:
+ - user_data:/mnt/user-data
+ deploy:
+ replicas: 4 # Pre-warm 4 sandbox containers
+ resources:
+ limits:
+ cpus: "2"
+ memory: 2G
+
+volumes:
+ postgres_data:
+ user_data:
+```
+
+### Postgres Checkpointer
+
+The development setup uses SQLite for checkpointing. Production must use Postgres for:
+- Persistence across service restarts
+- Concurrent access from multiple LangGraph server instances
+- Efficient state queries for thread history
+
+```python
+# backend/packages/harness/deerflow/agents/checkpointer/async_provider.py
+import os
+from langgraph.checkpoint.postgres.aio import AsyncPostgresSaver
+
+def make_checkpointer():
+ postgres_uri = os.environ.get("LANGGRAPH_POSTGRES_URI")
+
+ if postgres_uri:
+ # Production: use Postgres
+ return AsyncPostgresSaver.from_conn_string(postgres_uri)
+ else:
+ # Development: fall back to SQLite
+ from langgraph.checkpoint.sqlite.aio import AsyncSqliteSaver
+ return AsyncSqliteSaver.from_conn_string("./checkpoints.db")
+```
+
+### Gateway Mode: Eliminating LangGraph Platform Dependency
+
+DeerFlow's "gateway mode" embeds the agent runtime inside the FastAPI Gateway API, reducing the process count from 4 to 3 and removing the LangGraph Platform server:
+
+```python
+# backend/app/gateway/app.py (gateway mode)
+# In gateway mode, the FastAPI app hosts the agent runtime directly
+
+from deerflow.agents import make_lead_agent
+from langgraph.checkpoint.postgres.aio import AsyncPostgresSaver
+
+app = FastAPI(title="DeerFlow Gateway + Agent Runtime")
+
+@app.on_event("startup")
+async def startup():
+ checkpointer = AsyncPostgresSaver.from_conn_string(settings.POSTGRES_URI)
+ app.state.agent = make_lead_agent()
+
+@app.post("/threads/{thread_id}/runs")
+async def run_agent(thread_id: str, request: RunRequest):
+ """SSE streaming endpoint for agent execution."""
+ async def generate():
+ async for event in app.state.agent.astream_events(
+ request.input,
+ config={"configurable": {"thread_id": thread_id}},
+ version="v2",
+ ):
+ yield f"data: {json.dumps(event)}\n\n"
+
+ return StreamingResponse(generate(), media_type="text/event-stream")
+```
+
+Enable gateway mode in the environment:
+
+```bash
+DEERFLOW_GATEWAY_MODE=true
+```
+
+Gateway mode is marked experimental but is the recommended approach for deployments that want to avoid the LangGraph Platform licensing and process overhead.
+
+### LangSmith Observability
+
+LangSmith provides per-call tracing for all LLM invocations and tool calls:
+
+```bash
+# .env
+LANGCHAIN_TRACING_V2=true
+LANGCHAIN_API_KEY=ls__...
+LANGCHAIN_PROJECT=deer-flow-production
+LANGCHAIN_ENDPOINT=https://api.smith.langchain.com # default
+```
+
+With tracing enabled, every research run creates a trace with:
+- Full message history at each step
+- Tool call inputs and outputs
+- Token counts and costs per LLM call
+- Latency at each node
+- Error stacks for failed runs
+
+```mermaid
+graph LR
+ A[LangGraph Agent Run] --> B[LangSmith Trace]
+ B --> C[Run overview<br/>total tokens, cost, latency]
+ B --> D[Per-step spans<br/>each LLM call + tool call]
+ B --> E[Input/output at each step]
+ B --> F[Error details if failed]
+```
+
+### Langfuse: Open-Source Alternative
+
+For teams that cannot send data to LangSmith (data residency requirements), Langfuse is an open-source observability alternative:
+
+```bash
+# .env
+LANGFUSE_HOST=https://cloud.langfuse.com # or self-hosted
+LANGFUSE_PUBLIC_KEY=pk-lf-...
+LANGFUSE_SECRET_KEY=sk-lf-...
+```
+
+```python
+# backend/packages/harness/deerflow/agents/lead_agent/agent.py
+# Langfuse integration (conceptual — actual config is via env vars)
+from langfuse.callback import CallbackHandler
+
+langfuse_handler = CallbackHandler()
+
+# Injected into agent config:
+config = {
+ "callbacks": [langfuse_handler],
+ "configurable": {"thread_id": thread_id},
+}
+```
+
+### Security Hardening
+
+**1. Sandbox isolation** — always use `AioSandboxProvider` (Docker) in production:
+
+```yaml
+# config.yaml
+sandbox:
+ use: deerflow.community.aio_sandbox:AioSandboxProvider
+ allow_host_bash: false # NEVER true in production
+ auto_start: true
+ container_prefix: deer-flow-sandbox
+```
+
+The sandbox provides:
+- Filesystem isolation (agent code cannot reach host files outside `/mnt/user-data`)
+- Network isolation (configurable — default allows outbound for web search)
+- Resource limits per container (CPU and memory caps)
+
+**2. Authentication** — DeerFlow defaults to no auth. Add authentication at Nginx:
+
+```nginx
+# nginx.conf (production auth example using OAuth2 Proxy)
+location / {
+ auth_request /oauth2/auth;
+ error_page 401 = /oauth2/sign_in;
+ proxy_pass http://frontend:3000;
+}
+
+location /oauth2/ {
+ proxy_pass http://oauth2-proxy:4180;
+}
+```
+
+Or use the built-in `better-auth` integration in the frontend:
+
+```typescript
+// frontend/src/server/better-auth/config.ts
+import { betterAuth } from "better-auth";
+import { prismaAdapter } from "better-auth/adapters/prisma";
+
+export const auth = betterAuth({
+ database: prismaAdapter(prisma, { provider: "postgresql" }),
+ socialProviders: {
+ github: {
+ clientId: process.env.GITHUB_CLIENT_ID!,
+ clientSecret: process.env.GITHUB_CLIENT_SECRET!,
+ },
+ google: {
+ clientId: process.env.GOOGLE_CLIENT_ID!,
+ clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
+ },
+ },
+});
+```
+
+**3. Network exposure** — DeerFlow's documentation states:
+
+> "DeerFlow is designed for local trusted deployments. Untrusted network exposure requires IP allowlists, authentication gateways, and network isolation to prevent unauthorized agent invocation and potential abuse."
+
+Never expose the LangGraph server port (`:2024`) or Gateway API port (`:8001`) directly to the internet. Route all traffic through Nginx or a load balancer with authentication.
+
+### Health Checks and Monitoring
+
+Configure health checks for each service:
+
+```yaml
+# docker-compose.prod.yml health checks
+services:
+ langgraph:
+ healthcheck:
+ test: ["CMD", "curl", "-f", "http://localhost:2024/health"]
+ interval: 30s
+ timeout: 10s
+ retries: 3
+ start_period: 60s
+
+ gateway:
+ healthcheck:
+ test: ["CMD", "curl", "-f", "http://localhost:8001/health"]
+ interval: 30s
+ timeout: 5s
+ retries: 3
+```
+
+The `make doctor` script can also be run as a scheduled health check:
+
+```bash
+# Cron: run doctor every 5 minutes, alert if it fails
+*/5 * * * * cd /opt/deer-flow && make doctor >> /var/log/deerflow-health.log 2>&1
+```
+
+### Recovery Patterns
+
+**LLM API Rate Limits:**
+
+DeerFlow's `LLMErrorHandlingMiddleware` handles rate limit responses from LLM providers with exponential backoff. No additional configuration is needed, but you should monitor LangSmith/Langfuse for runs that are slow due to rate limit retries.
+
+**Sandbox Container Crashes:**
+
+If a Docker sandbox container crashes mid-execution:
+1. `SandboxMiddleware` detects the missing container ID in `ThreadState.sandbox`
+2. A new container is provisioned for the thread on the next invocation
+3. The agent resumes from the last checkpoint (previous messages are intact)
+4. Files in the workspace directory persist (they are on the shared volume, not inside the container)
+
+**LangGraph Server Restart:**
+
+With Postgres checkpointer:
+- All thread states are persisted and immediately available after restart
+- In-flight runs at the time of restart are marked as failed
+- Users can resubmit their last message to resume from the last saved checkpoint
+
+**Disk Full:**
+
+Generated artifacts (MP3s, PDFs, slides) accumulate on the shared volume. Implement periodic cleanup:
+
+```python
+# scripts/cleanup_old_threads.py
+import os
+import shutil
+from datetime import datetime, timedelta
+from pathlib import Path
+
+OUTPUTS_DIR = Path("/mnt/user-data/outputs")
+RETENTION_DAYS = 30
+
+def cleanup_old_outputs():
+ cutoff = datetime.now() - timedelta(days=RETENTION_DAYS)
+
+ for thread_dir in OUTPUTS_DIR.iterdir():
+ if thread_dir.is_dir():
+ mtime = datetime.fromtimestamp(thread_dir.stat().st_mtime)
+ if mtime < cutoff:
+ shutil.rmtree(thread_dir)
+ print(f"Deleted: {thread_dir}")
+
+if __name__ == "__main__":
+ cleanup_old_outputs()
+```
+
+### Advanced Pattern: Agent Guardrails
+
+For deployments where you need to restrict what the agent can do (e.g., corporate environments):
+
+```python
+# backend/docs/GUARDRAILS.md describes this pattern
+
+# Guardrails are implemented as middleware that intercepts tool calls
+class ContentGuardrailMiddleware(BaseMiddleware):
+ """Block tool calls to specific domains or with specific patterns."""
+
+ BLOCKED_DOMAINS = {"competitor.com", "internal.company.com"}
+
+ async def before_tool_call(
+ self,
+ tool_name: str,
+ tool_input: dict,
+ state: ThreadState,
+ ) -> dict | None:
+ """Return None to allow, return error dict to block."""
+
+ if tool_name in ("web_search", "web_fetch"):
+ url = tool_input.get("url", "")
+ query = tool_input.get("query", "")
+
+ for domain in self.BLOCKED_DOMAINS:
+ if domain in url or domain in query:
+ return {"error": f"Access to {domain} is restricted by policy."}
+
+ return None # Allow the tool call
+```
+
+### Cost Management
+
+LLM API costs scale with:
+- Number of concurrent users
+- Research depth (sub-agent count and search iterations)
+- Model selection (o3 vs. gpt-4o-mini cost ratio can be 100x)
+
+Production cost controls:
+
+```yaml
+# config.yaml — cost-efficient defaults with premium model available
+models:
+ - name: gpt-4o-mini
+ display_name: GPT-4o Mini (Default)
+ use: langchain_openai:ChatOpenAI
+ model: gpt-4o-mini
+ api_key: $OPENAI_API_KEY
+
+ - name: o3-mini
+ display_name: o3 Mini (Deep Research)
+ use: langchain_openai:ChatOpenAI
+ model: o3-mini
+ api_key: $OPENAI_API_KEY
+ supports_thinking: true
+```
+
+```yaml
+# Per-agent config: limit sub-agent parallelism to control costs
+# workspace/agents/lead_agent/config.yaml
+subagent:
+ max_concurrent: 2 # Reduce from default 3 to limit parallel LLM calls
+```
+
+## Summary
+
+Production DeerFlow deployment requires:
+1. **Postgres checkpointer** for persistent thread state
+2. **AioSandboxProvider** (Docker) for isolated code execution
+3. **Authentication** at Nginx or via better-auth
+4. **LangSmith or Langfuse** for observability
+5. **Shared filesystem volume** for artifacts persistence across service restarts
+6. **Resource sizing** based on concurrent user count and research depth
+7. **Periodic cleanup** for accumulated artifacts
+8. **Network isolation** preventing direct exposure of internal service ports
+
+The gateway mode (experimental) simplifies the architecture by embedding the agent runtime in the FastAPI server, reducing the process count and removing the LangGraph Platform dependency.
+
+---
+
+## Tutorial Complete
+
+You have now covered the full DeerFlow system:
+
+- **Chapter 1**: Installation, configuration, and first research query
+- **Chapter 2**: LangGraph state machine, 14-stage middleware pipeline, async checkpointing
+- **Chapter 3**: Research pipeline — CLARIFY → PLAN → ACT, deep research skill, citations
+- **Chapter 4**: RAG and search tools — DuckDuckGo, Tavily, Exa, Firecrawl, sandbox REPL, MCP
+- **Chapter 5**: Three-service architecture, SSE streaming, Gateway API, IM channels
+- **Chapter 6**: Skills system, custom tools, MCP servers, per-agent config overrides
+- **Chapter 7**: Podcast generation, PowerPoint, charts, image and video generation
+- **Chapter 8**: Production deployment, Postgres checkpointer, security, observability, cost management
+
+## Further Resources
+
+- [DeerFlow GitHub Repository](https://github.com/bytedance/deer-flow)
+- [Architecture Documentation](https://github.com/bytedance/deer-flow/blob/main/backend/docs/ARCHITECTURE.md)
+- [Configuration Reference](https://github.com/bytedance/deer-flow/blob/main/backend/docs/CONFIGURATION.md)
+- [Skills Library](https://github.com/bytedance/deer-flow/tree/main/skills/public)
+- [Contributing Guide](https://github.com/bytedance/deer-flow/blob/main/CONTRIBUTING.md)
+
+---
+
+## Chapter Connections
+
+- [Tutorial Index](README.md)
+- [Previous Chapter: Chapter 7: Podcast and Multi-Modal Output](07-podcast-multimodal.md)
+- [Main Catalog](../../README.md#-tutorial-catalog)
+- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
diff --git a/tutorials/deer-flow-tutorial/README.md b/tutorials/deer-flow-tutorial/README.md
index ee48c35f..75259260 100644
--- a/tutorials/deer-flow-tutorial/README.md
+++ b/tutorials/deer-flow-tutorial/README.md
@@ -1,255 +1,252 @@
---
layout: default
-title: "Deer Flow Tutorial"
+title: "DeerFlow Tutorial"
nav_order: 36
has_children: true
format_version: v2
+source_repo: https://github.com/bytedance/deer-flow
+categories:
+ - ai-agents
+ - multi-agent-systems
+ - langgraph
+ - research-automation
+related_tutorials:
+ - langgraph-tutorial
+ - langchain-tutorial
+ - dspy-tutorial
+ - fabric-tutorial
+last_updated: 2026-04-12
---
-# Deer Flow Tutorial: Distributed Workflow Orchestration Platform
+# DeerFlow Tutorial: Open-Source Super Agent Harness
-> Orchestrate complex distributed workflows with Deer Flow's powerful task coordination and execution platform.
+> DeerFlow is a LangGraph-powered multi-agent runtime by ByteDance that orchestrates a lead agent, specialized sub-agents, persistent memory, sandboxed code execution, and a modular skills system to tackle complex, long-horizon research and automation tasks.
[](https://github.com/bytedance/deer-flow)
[](https://opensource.org/licenses/MIT)
-[](https://github.com/bytedance/deer-flow)
-
-
-<div align="center">
- <img src="https://raw.githubusercontent.com/bytedance/deer-flow/main/docs/images/logo.png" alt="Deer Flow Logo" width="200"/>
-</div>
+[](https://github.com/bytedance/deer-flow)
---
## Why This Track Matters
-Deer Flow is increasingly relevant for developers working with modern AI/ML infrastructure. Orchestrate complex distributed workflows with Deer Flow's powerful task coordination and execution platform, and this track helps you understand the architecture, key patterns, and production considerations.
+DeerFlow represents the state of the art in open-source agentic systems. It is not an ETL scheduler, a workflow DAG engine, or a data pipeline tool. It is a **super agent harness** — a runtime that orchestrates a lead LLM agent that spawns specialized sub-agents, loads Markdown-based skills on demand, executes code inside Docker sandboxes, persists cross-session memory, and streams results back to a Next.js chat interface.
+
+Understanding DeerFlow means understanding how production-grade, long-horizon agent systems are actually built: LangGraph state machines, middleware-chain architecture, MCP tool discovery, and skills-as-code patterns. These patterns show up across the emerging agent ecosystem.
This track focuses on:
-- understanding getting started with deer flow
-- understanding workflow basics
-- understanding task management
-- understanding dependencies
+- Understanding how LangGraph drives the agent state machine
+- Understanding how the lead agent orchestrates sub-agents through the `task_tool`
+- Understanding the middleware pipeline that wraps every agent invocation
+- Understanding the skills system for extending agent capabilities
+- Understanding RAG-style tool use (web search, code execution, file operations)
+- Understanding the podcast and multi-modal output pipeline
+- Understanding production deployment with Docker and LangGraph Platform
-## 🎯 What is Deer Flow?
+## What is DeerFlow?
-**Deer Flow** is a distributed workflow orchestration platform designed for coordinating complex tasks across multiple systems and services. It provides a robust framework for building, executing, and monitoring distributed workflows with support for parallelism, fault tolerance, and dynamic scaling.
+**DeerFlow** is an open-source super agent harness that orchestrates sub-agents, memory, and sandboxes to accomplish almost any complex, multi-step task. It evolved from ByteDance's internal deep research tooling (inspired by Google's Gemini Deep Research product) into a general-purpose agent runtime.
+
+The system centers on a **lead agent** that decomposes requests, loads relevant skills, spawns parallel sub-agents for long tasks, executes code in isolated Docker containers, searches the web, and synthesizes outputs into structured reports, presentations, podcasts, or other artifacts.
### Key Features
-- 🔀 **Workflow Orchestration** - Complex task coordination and execution
-- 📊 **Distributed Processing** - Scale across multiple nodes and clusters
-- 🛡️ **Fault Tolerance** - Automatic retry and recovery mechanisms
-- 📈 **Dynamic Scaling** - Auto-scale based on workload demands
-- 🎯 **Task Dependencies** - Define complex dependency relationships
-- 📊 **Monitoring & Observability** - Comprehensive workflow monitoring
-- 🔌 **Extensible Architecture** - Custom task types and integrations
-- ⏱️ **Scheduling** - Time-based and event-driven execution
+
+- **Multi-Agent Orchestration** — Lead agent spawns up to N concurrent sub-agents via `task_tool`, each with isolated context and tools
+- **LangGraph State Machine** — Agent control flow is a compiled LangGraph graph (`lead_agent`) with async checkpointing
+- **14-Stage Middleware Pipeline** — Every agent invocation passes through an ordered chain: sandbox setup, file uploads, summarization, titling, memory, vision, loop detection, clarification, and more
+- **Skills Framework** — Modular Markdown-based workflows (deep-research, podcast-generation, chart-visualization, ppt-generation, etc.) load progressively on demand
+- **Persistent Memory** — Cross-session memory layer learns user preferences and accumulated knowledge via a memory queue and updater
+- **Sandbox Execution** — `LocalSandboxProvider` (direct) or `AioSandboxProvider` (Docker-isolated) for Python/bash execution
+- **MCP Tool Discovery** — External tools (GitHub, filesystem, databases, browser) auto-discovered from `extensions_config.json`
+- **Multi-Modal Outputs** — Research reports, PowerPoint slides, chart visualizations, podcasts (MP3 via Volcengine TTS), and video generation
+- **IM Channel Support** — Telegram, Slack, Feishu/Lark, WeChat, WeCom integrations
+- **Streaming Responses** — Server-Sent Events (SSE) from LangGraph to Next.js frontend
+- **Observability** — LangSmith and Langfuse tracing for all LLM calls and agent runs
## Current Snapshot (auto-updated)
- repository: [`bytedance/deer-flow`](https://github.com/bytedance/deer-flow)
-- stars: about **58.4k**
+- stars: about **53.5k**
+- tech stack: Python 3.12+, LangGraph, LangChain, FastAPI, Next.js 22+, Docker
## Mental Model
```mermaid
graph TB
subgraph "User Interface"
- A[Web Dashboard]
- B[REST API]
- C[CLI Tools]
- D[SDK Libraries]
+ A[Next.js Chat UI :3000]
+ B[IM Channels<br/>Telegram/Slack/Feishu]
end
- subgraph "Orchestration Engine"
- E[Workflow Scheduler]
- F[Task Coordinator]
- G[Dependency Resolver]
- H[Execution Engine]
+ subgraph "Entry Point"
+ C[Nginx :2026]
end
- subgraph "Execution Layer"
- I[Worker Nodes]
- J[Task Executors]
- K[Resource Manager]
- L[Load Balancer]
+ subgraph "Agent Runtime - LangGraph Server :2024"
+ D[lead_agent Graph<br/>make_lead_agent]
+ E[14-Stage Middleware Pipeline]
+ F[Lead Agent LLM]
+ G[task_tool → Sub-agents]
+ H[Skills Loader<br/>SKILL.md files]
+ end
+
+ subgraph "Gateway API - FastAPI :8001"
+ I[Models / MCP / Skills]
+ J[Threads / Artifacts]
+ K[Memory / Uploads]
end
- subgraph "Storage Layer"
- M[Workflow Definitions]
- N[Execution History]
- O[Task State]
- P[Metrics & Logs]
+ subgraph "Tool Layer"
+ L[Web Search<br/>DDG / Tavily / Exa]
+ M[Bash + File Ops]
+ N[MCP Servers<br/>GitHub / DB / Browser]
+ O[ask_clarification]
end
- subgraph "Integration Layer"
- Q[Message Queues]
- R[Databases]
- S[External APIs]
- T[Cloud Services]
+ subgraph "Execution Layer"
+ P[LocalSandboxProvider<br/>dev]
+ Q[AioSandboxProvider<br/>Docker prod]
end
- A --> E
- B --> E
- C --> E
+ subgraph "Memory & Storage"
+ R[Persistent Memory<br/>cross-session]
+ S[LangGraph Checkpointer<br/>thread state]
+ T[Outputs<br/>reports / MP3 / slides]
+ end
+
+ A --> C
+ B --> C
+ C --> D
+ C --> I
D --> E
E --> F
F --> G
- G --> H
- H --> I
- I --> J
- J --> K
- K --> L
- H --> M
- H --> N
- H --> O
- H --> P
- F --> Q
+ F --> H
+ F --> L
+ F --> M
+ F --> N
+ F --> O
+ G --> P
+ G --> Q
+ M --> P
+ M --> Q
F --> R
- F --> S
+ D --> S
F --> T
```
-## 📋 Tutorial Chapters
+## Tutorial Chapters
| Chapter | Topic | Time | Difficulty |
|:--------|:------|:-----|:-----------|
-| **[01-getting-started](01-getting-started.md)** | Installation & Setup | 20 min | 🟢 Beginner |
-| **[02-workflow-basics](02-workflow-basics.md)** | Basic Workflow Creation | 30 min | 🟢 Beginner |
-| **[03-task-management](03-task-management.md)** | Task Types & Execution | 35 min | 🟡 Intermediate |
-| **[04-dependencies](04-dependencies.md)** | Complex Dependencies | 40 min | 🟡 Intermediate |
-| **[05-error-handling](05-error-handling.md)** | Fault Tolerance & Recovery | 35 min | 🟡 Intermediate |
-| **[06-scaling](06-scaling.md)** | Distributed Execution | 45 min | 🔴 Expert |
-| **[07-monitoring](07-monitoring.md)** | Monitoring & Observability | 30 min | 🔴 Expert |
-| **[08-advanced-patterns](08-advanced-patterns.md)** | Advanced Orchestration Patterns | 50 min | 🔴 Expert |
+| **[01-getting-started](01-getting-started.md)** | Installation & First Research Query | 25 min | Beginner |
+| **[02-langgraph-architecture](02-langgraph-architecture.md)** | LangGraph Architecture and Agent Orchestration | 40 min | Intermediate |
+| **[03-research-agent-pipeline](03-research-agent-pipeline.md)** | Research Agent Pipeline | 35 min | Intermediate |
+| **[04-rag-search-knowledge](04-rag-search-knowledge.md)** | RAG, Search, and Knowledge Synthesis | 35 min | Intermediate |
+| **[05-frontend-backend-api](05-frontend-backend-api.md)** | Frontend, Backend, and API Design | 35 min | Intermediate |
+| **[06-customization-extension](06-customization-extension.md)** | Customization and Extension | 40 min | Advanced |
+| **[07-podcast-multimodal](07-podcast-multimodal.md)** | Podcast and Multi-Modal Output | 30 min | Advanced |
+| **[08-production-deployment](08-production-deployment.md)** | Production Deployment and Advanced Patterns | 45 min | Advanced |
## What You Will Learn
-By the end of this tutorial, you'll be able to:
+By the end of this tutorial, you will be able to:
-- ✅ Install and configure Deer Flow platform
-- ✅ Design and implement complex workflows
-- ✅ Manage task dependencies and execution order
-- ✅ Implement fault-tolerant workflow patterns
-- ✅ Scale workflows across distributed systems
-- ✅ Monitor workflow performance and health
-- ✅ Integrate with external systems and APIs
-- ✅ Optimize workflow performance and reliability
-- ✅ Debug and troubleshoot workflow issues
+- Install and configure DeerFlow with any OpenAI-compatible LLM
+- Understand how LangGraph compiles the lead agent graph with async checkpointing
+- Trace a research query through the 14-stage middleware pipeline
+- Extend DeerFlow with custom skills, MCP servers, and custom tools
+- Understand how sub-agents are spawned via `task_tool` with concurrency limits
+- Configure web search providers (DuckDuckGo, Tavily, Exa, Firecrawl)
+- Use the sandbox system for safe Python and bash execution
+- Generate podcasts, slides, and charts from research outputs
+- Deploy DeerFlow with Docker Compose in a production-ready configuration
+- Integrate IM channels (Telegram, Slack, Feishu) for autonomous agent access
-## 🛠️ Prerequisites
+## Prerequisites
### System Requirements
-- **CPU**: 2+ cores recommended
-- **RAM**: 4GB+ recommended
-- **Storage**: 10GB+ for workflow data
-- **OS**: Linux, macOS, Windows
+
+- **CPU**: 4+ cores recommended (8+ for sub-agent workloads)
+- **RAM**: 8 GB minimum, 16 GB recommended
+- **Storage**: 25 GB for Docker images and sandbox containers
+- **OS**: Linux, macOS, Windows (via WSL2)
### Software Prerequisites
-- Docker & Docker Compose
-- Python 3.8+
-- Node.js 16+ (for web interface)
-- Redis or compatible message queue
+
+- Docker Desktop (for sandbox and recommended dev mode)
+- Python 3.12+ (for local development)
+- Node.js 22+ (for frontend)
+- An API key for at least one OpenAI-compatible LLM provider
+- (Optional) Tavily or DuckDuckGo API key for web search
### Knowledge Prerequisites
-- Basic programming concepts
-- Understanding of distributed systems
-- Familiarity with workflow concepts
-## 🚀 Quick Start
+- Familiarity with Python async programming
+- Basic understanding of LLM APIs and tool-use patterns
+- Comfort with Docker and Docker Compose
-### Docker Deployment
+## Quick Start
```bash
-# Clone repository
+# Clone the repository
git clone https://github.com/bytedance/deer-flow.git
cd deer-flow
-# Start with Docker Compose
-docker-compose up -d
+# Run the interactive setup wizard (configures config.yaml and .env)
+make setup
-# Access web interface
-open http://localhost:8080
+# Start with Docker (recommended)
+make docker-init
+make docker-start
-# Submit first workflow
-curl -X POST http://localhost:8080/api/workflows \
- -H "Content-Type: application/json" \
- -d @examples/simple_workflow.json
+# Access the chat interface
+open http://localhost:2026
```
-### Basic Usage
+For local development without Docker:
```bash
-# Create a simple workflow
-cat > my_workflow.json << EOF
-{
- "name": "hello_world",
- "tasks": [
- {
- "id": "task1",
- "type": "shell",
- "command": "echo 'Hello, Deer Flow!'"
- }
- ]
-}
-EOF
-
-# Submit workflow
-curl -X POST http://localhost:8080/api/workflows \
- -H "Content-Type: application/json" \
- -d @my_workflow.json
+make install # Install Python + Node dependencies
+make dev # Start all services (LangGraph server + Gateway + frontend)
```
-## 🎨 What Makes This Tutorial Special?
+## Use Cases
-### 🏆 **Production-Ready Focus**
-- Enterprise-grade workflow orchestration
-- Fault tolerance and reliability patterns
-- Scalability and performance optimization
+### Deep Research & Knowledge Synthesis
+- Multi-source web research with automatic citation tracking
+- Academic paper review and systematic literature analysis
+- Competitive intelligence and market research reports
-### 🔧 **Practical Implementation**
-- Real-world workflow examples
-- Integration patterns and best practices
-- Troubleshooting and debugging techniques
+### Code & Data Analysis
+- Data analysis pipelines with Python REPL execution
+- GitHub repository deep dives
+- Chart and visualization generation from datasets
-### 📊 **Distributed Systems**
-- Multi-node deployment strategies
-- Load balancing and resource management
-- High availability configurations
+### Content Production
+- Long-form reports with structured sections
+- PowerPoint presentation generation
+- Podcast audio generation (MP3) with two-host dialogue
+- Newsletter creation
-### 🌟 **Extensible Design**
-- Custom task types and integrations
-- Plugin architecture for extensions
-- API-driven workflow management
+### Automation via IM Channels
+- Trigger research tasks from Slack/Telegram messages
+- Deliver results back to channels automatically
+- Schedule recurring research workflows
-## 💡 Use Cases
+## What Makes DeerFlow Different from Airflow / Prefect / Temporal
-### Data Processing Pipelines
-- ETL (Extract, Transform, Load) workflows
-- Data validation and quality checks
-- Batch processing and analytics
-- Real-time data streaming
+DeerFlow is **not** a workflow DAG orchestrator. It does not define tasks as JSON configurations, does not have worker nodes, does not have a task queue, and does not use `depends_on` dependency declarations. Every comparison to Airflow or Celery in the old tutorial was wrong.
-### Business Process Automation
-- Order processing and fulfillment
-- Customer onboarding workflows
-- Approval and review processes
-- Notification and communication flows
+DeerFlow is a **conversational agent runtime** where:
+- Control flow is determined by the LLM's tool calls, not a static DAG
+- "Tasks" are sub-agent invocations generated dynamically at runtime
+- State is a LangGraph `ThreadState` persisted via a checkpointer
+- "Workers" are Docker sandbox containers that execute agent-generated code
+- The user interacts through a chat interface, not a workflow submission API
-### DevOps & CI/CD
-- Deployment pipelines
-- Infrastructure provisioning
-- Automated testing and validation
-- Rollback and recovery procedures
-
-### AI/ML Workflows
-- Model training pipelines
-- Data preprocessing workflows
-- Model deployment and serving
-- A/B testing and experimentation
-
-## 🤝 Contributing
+## Contributing
Found an issue or want to improve this tutorial? Contributions are welcome!
@@ -258,22 +255,33 @@ Found an issue or want to improve this tutorial? Contributions are welcome!
3. Make your changes
4. Submit a pull request
-## 📚 Additional Resources
+## Additional Resources
-- [Official Documentation](https://github.com/bytedance/deer-flow/tree/main/docs)
-- [GitHub Repository](https://github.com/bytedance/deer-flow)
-- [API Reference](https://github.com/bytedance/deer-flow/blob/main/docs/API.md)
-- [Community & Issues](https://github.com/bytedance/deer-flow/issues)
-- [Workflow Examples](https://github.com/bytedance/deer-flow/tree/main/examples)
+- [DeerFlow GitHub Repository](https://github.com/bytedance/deer-flow)
+- [Backend Architecture Docs](https://github.com/bytedance/deer-flow/blob/main/backend/docs/ARCHITECTURE.md)
+- [Configuration Reference](https://github.com/bytedance/deer-flow/blob/main/backend/docs/CONFIGURATION.md)
+- [MCP Server Integration](https://github.com/bytedance/deer-flow/blob/main/backend/docs/MCP_SERVER.md)
+- [Skills Directory](https://github.com/bytedance/deer-flow/tree/main/skills/public)
-## 🙏 Acknowledgments
+## Navigation & Backlinks
-Special thanks to the ByteDance team for creating this powerful distributed workflow orchestration platform!
+- [Start Here: Chapter 1: Getting Started](01-getting-started.md)
+- [Back to Main Catalog](../../README.md#-tutorial-catalog)
+- [Browse A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
+- [Search by Intent](../../discoverability/query-hub.md)
----
+*Generated by [AI Codebase Knowledge Builder](https://github.com/johnxie/awesome-code-docs)*
-**Ready to orchestrate distributed workflows?** Let's dive into [Chapter 1: Getting Started](01-getting-started.md)! 🚀
+## Chapter Guide
+1. [Chapter 1: Getting Started](01-getting-started.md)
+2. [Chapter 2: LangGraph Architecture and Agent Orchestration](02-langgraph-architecture.md)
+3. [Chapter 3: Research Agent Pipeline](03-research-agent-pipeline.md)
+4. [Chapter 4: RAG, Search, and Knowledge Synthesis](04-rag-search-knowledge.md)
+5. [Chapter 5: Frontend, Backend, and API Design](05-frontend-backend-api.md)
+6. [Chapter 6: Customization and Extension](06-customization-extension.md)
+7. [Chapter 7: Podcast and Multi-Modal Output](07-podcast-multimodal.md)
+8. [Chapter 8: Production Deployment and Advanced Patterns](08-production-deployment.md)
## Related Tutorials
@@ -282,32 +290,11 @@ Special thanks to the ByteDance team for creating this powerful distributed work
- [DSPy Tutorial](../dspy-tutorial/)
- [Fabric Tutorial](../fabric-tutorial/)
- [Instructor Tutorial](../instructor-tutorial/)
-## Navigation & Backlinks
-
-- [Start Here: Chapter 1: Getting Started with Deer Flow](01-getting-started.md)
-- [Back to Main Catalog](../../README.md#-tutorial-catalog)
-- [Browse A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
-- [Search by Intent](../../discoverability/query-hub.md)
-- [Explore Category Hubs](../../README.md#category-hubs)
-
-*Generated by [AI Codebase Knowledge Builder](https://github.com/johnxie/awesome-code-docs)*
-
-## Chapter Guide
-
-1. [Chapter 1: Getting Started with Deer Flow](01-getting-started.md)
-2. [Chapter 2: Workflow Basics](02-workflow-basics.md)
-3. [Chapter 3: Task Management](03-task-management.md)
-4. [Chapter 4: Dependencies](04-dependencies.md)
-5. [Chapter 5: Error Handling](05-error-handling.md)
-6. [Chapter 6: Scaling](06-scaling.md)
-7. [Chapter 7: Monitoring](07-monitoring.md)
-8. [Chapter 8: Advanced Patterns](08-advanced-patterns.md)
## Source References
-- [Official Documentation](https://github.com/bytedance/deer-flow/tree/main/docs)
- [GitHub Repository](https://github.com/bytedance/deer-flow)
-- [API Reference](https://github.com/bytedance/deer-flow/blob/main/docs/API.md)
-- [Community & Issues](https://github.com/bytedance/deer-flow/issues)
-- [Workflow Examples](https://github.com/bytedance/deer-flow/tree/main/examples)
+- [Architecture Documentation](https://github.com/bytedance/deer-flow/blob/main/backend/docs/ARCHITECTURE.md)
+- [Configuration Documentation](https://github.com/bytedance/deer-flow/blob/main/backend/docs/CONFIGURATION.md)
+- [Skills Reference](https://github.com/bytedance/deer-flow/tree/main/skills/public)
- [AI Codebase Knowledge Builder](https://github.com/johnxie/awesome-code-docs)
diff --git a/tutorials/devika-tutorial/01-getting-started.md b/tutorials/devika-tutorial/01-getting-started.md
index 14eda9b4..c326529a 100644
--- a/tutorials/devika-tutorial/01-getting-started.md
+++ b/tutorials/devika-tutorial/01-getting-started.md
@@ -39,186 +39,16 @@ You now have a working Devika installation and have executed your first autonomo
Next: [Chapter 2: Architecture and Agent Pipeline](02-architecture-and-agent-pipeline.md)
-## Depth Expansion Playbook
-
-## Source Code Walkthrough
-
-### `devika.py`
-
-The `test_connect` function in [`devika.py`](https://github.com/stitionai/devika/blob/HEAD/devika.py) handles a key part of this chapter's functionality:
-
-```py
-# initial socket
-@socketio.on('socket_connect')
-def test_connect(data):
- print("Socket connected :: ", data)
- emit_agent("socket_response", {"data": "Server Connected"})
-
-
-@app.route("/api/data", methods=["GET"])
-@route_logger(logger)
-def data():
- project = manager.get_project_list()
- models = LLM().list_models()
- search_engines = ["Bing", "Google", "DuckDuckGo"]
- return jsonify({"projects": project, "models": models, "search_engines": search_engines})
-
-
-@app.route("/api/messages", methods=["POST"])
-def get_messages():
- data = request.json
- project_name = data.get("project_name")
- messages = manager.get_messages(project_name)
- return jsonify({"messages": messages})
-
-
-# Main socket
-@socketio.on('user-message')
-def handle_message(data):
- logger.info(f"User message: {data}")
- message = data.get('message')
- base_model = data.get('base_model')
- project_name = data.get('project_name')
- search_engine = data.get('search_engine').lower()
-```
-
-This function is important because it defines how Devika Tutorial: Open-Source Autonomous AI Software Engineer implements the patterns covered in this chapter.
-
-### `devika.py`
-
-The `data` function in [`devika.py`](https://github.com/stitionai/devika/blob/HEAD/devika.py) handles a key part of this chapter's functionality:
-
-```py
-# initial socket
-@socketio.on('socket_connect')
-def test_connect(data):
- print("Socket connected :: ", data)
- emit_agent("socket_response", {"data": "Server Connected"})
-
-
-@app.route("/api/data", methods=["GET"])
-@route_logger(logger)
-def data():
- project = manager.get_project_list()
- models = LLM().list_models()
- search_engines = ["Bing", "Google", "DuckDuckGo"]
- return jsonify({"projects": project, "models": models, "search_engines": search_engines})
-
-
-@app.route("/api/messages", methods=["POST"])
-def get_messages():
- data = request.json
- project_name = data.get("project_name")
- messages = manager.get_messages(project_name)
- return jsonify({"messages": messages})
-
-
-# Main socket
-@socketio.on('user-message')
-def handle_message(data):
- logger.info(f"User message: {data}")
- message = data.get('message')
- base_model = data.get('base_model')
- project_name = data.get('project_name')
- search_engine = data.get('search_engine').lower()
-```
-
-This function is important because it defines how Devika Tutorial: Open-Source Autonomous AI Software Engineer implements the patterns covered in this chapter.
-
-### `devika.py`
-
-The `get_messages` function in [`devika.py`](https://github.com/stitionai/devika/blob/HEAD/devika.py) handles a key part of this chapter's functionality:
-
-```py
-
-@app.route("/api/messages", methods=["POST"])
-def get_messages():
- data = request.json
- project_name = data.get("project_name")
- messages = manager.get_messages(project_name)
- return jsonify({"messages": messages})
-
-
-# Main socket
-@socketio.on('user-message')
-def handle_message(data):
- logger.info(f"User message: {data}")
- message = data.get('message')
- base_model = data.get('base_model')
- project_name = data.get('project_name')
- search_engine = data.get('search_engine').lower()
-
- agent = Agent(base_model=base_model, search_engine=search_engine)
-
- state = AgentState.get_latest_state(project_name)
- if not state:
- thread = Thread(target=lambda: agent.execute(message, project_name))
- thread.start()
- else:
- if AgentState.is_agent_completed(project_name):
- thread = Thread(target=lambda: agent.subsequent_execute(message, project_name))
- thread.start()
- else:
- emit_agent("info", {"type": "warning", "message": "previous agent doesn't completed it's task."})
- last_state = AgentState.get_latest_state(project_name)
- if last_state["agent_is_active"] or not last_state["completed"]:
-```
-
-This function is important because it defines how Devika Tutorial: Open-Source Autonomous AI Software Engineer implements the patterns covered in this chapter.
-
-### `devika.py`
-
-The `handle_message` function in [`devika.py`](https://github.com/stitionai/devika/blob/HEAD/devika.py) handles a key part of this chapter's functionality:
-
-```py
-# Main socket
-@socketio.on('user-message')
-def handle_message(data):
- logger.info(f"User message: {data}")
- message = data.get('message')
- base_model = data.get('base_model')
- project_name = data.get('project_name')
- search_engine = data.get('search_engine').lower()
-
- agent = Agent(base_model=base_model, search_engine=search_engine)
-
- state = AgentState.get_latest_state(project_name)
- if not state:
- thread = Thread(target=lambda: agent.execute(message, project_name))
- thread.start()
- else:
- if AgentState.is_agent_completed(project_name):
- thread = Thread(target=lambda: agent.subsequent_execute(message, project_name))
- thread.start()
- else:
- emit_agent("info", {"type": "warning", "message": "previous agent doesn't completed it's task."})
- last_state = AgentState.get_latest_state(project_name)
- if last_state["agent_is_active"] or not last_state["completed"]:
- thread = Thread(target=lambda: agent.execute(message, project_name))
- thread.start()
- else:
- thread = Thread(target=lambda: agent.subsequent_execute(message, project_name))
- thread.start()
-
-@app.route("/api/is-agent-active", methods=["POST"])
-@route_logger(logger)
-def is_agent_active():
-```
-
-This function is important because it defines how Devika Tutorial: Open-Source Autonomous AI Software Engineer implements the patterns covered in this chapter.
-
-
## How These Components Connect
```mermaid
flowchart TD
- A[test_connect]
- B[data]
- C[get_messages]
- D[handle_message]
- E[is_agent_active]
- A --> B
- B --> C
- C --> D
- D --> E
+ A[Install Devika] --> B[Configure .env with API keys]
+ B --> C[Start backend: python devika.py]
+ B --> D[Start frontend: bun run dev]
+ C --> E[Flask server on :1337]
+ D --> F[React UI on :3000]
+ F --> G[Browser: open Devika UI]
+ G --> H[Create project, enter task]
+ H --> I[Agent pipeline starts]
```
diff --git a/tutorials/devika-tutorial/02-architecture-and-agent-pipeline.md b/tutorials/devika-tutorial/02-architecture-and-agent-pipeline.md
index 6769d4e0..898a3c7d 100644
--- a/tutorials/devika-tutorial/02-architecture-and-agent-pipeline.md
+++ b/tutorials/devika-tutorial/02-architecture-and-agent-pipeline.md
@@ -39,186 +39,18 @@ You now understand how Devika's multi-agent architecture decomposes a high-level
Next: [Chapter 3: LLM Provider Configuration](03-llm-provider-configuration.md)
-## Depth Expansion Playbook
-
-## Source Code Walkthrough
-
-### `devika.py`
-
-The `browser_snapshot` function in [`devika.py`](https://github.com/stitionai/devika/blob/HEAD/devika.py) handles a key part of this chapter's functionality:
-
-```py
-@app.route("/api/get-browser-snapshot", methods=["GET"])
-@route_logger(logger)
-def browser_snapshot():
- snapshot_path = request.args.get("snapshot_path")
- return send_file(snapshot_path, as_attachment=True)
-
-
-@app.route("/api/get-browser-session", methods=["GET"])
-@route_logger(logger)
-def get_browser_session():
- project_name = request.args.get("project_name")
- agent_state = AgentState.get_latest_state(project_name)
- if not agent_state:
- return jsonify({"session": None})
- else:
- browser_session = agent_state["browser_session"]
- return jsonify({"session": browser_session})
-
-
-@app.route("/api/get-terminal-session", methods=["GET"])
-@route_logger(logger)
-def get_terminal_session():
- project_name = request.args.get("project_name")
- agent_state = AgentState.get_latest_state(project_name)
- if not agent_state:
- return jsonify({"terminal_state": None})
- else:
- terminal_state = agent_state["terminal_session"]
- return jsonify({"terminal_state": terminal_state})
-
-
-@app.route("/api/run-code", methods=["POST"])
-```
-
-This function is important because it defines how Devika Tutorial: Open-Source Autonomous AI Software Engineer implements the patterns covered in this chapter.
-
-### `devika.py`
-
-The `get_browser_session` function in [`devika.py`](https://github.com/stitionai/devika/blob/HEAD/devika.py) handles a key part of this chapter's functionality:
-
-```py
-@app.route("/api/get-browser-session", methods=["GET"])
-@route_logger(logger)
-def get_browser_session():
- project_name = request.args.get("project_name")
- agent_state = AgentState.get_latest_state(project_name)
- if not agent_state:
- return jsonify({"session": None})
- else:
- browser_session = agent_state["browser_session"]
- return jsonify({"session": browser_session})
-
-
-@app.route("/api/get-terminal-session", methods=["GET"])
-@route_logger(logger)
-def get_terminal_session():
- project_name = request.args.get("project_name")
- agent_state = AgentState.get_latest_state(project_name)
- if not agent_state:
- return jsonify({"terminal_state": None})
- else:
- terminal_state = agent_state["terminal_session"]
- return jsonify({"terminal_state": terminal_state})
-
-
-@app.route("/api/run-code", methods=["POST"])
-@route_logger(logger)
-def run_code():
- data = request.json
- project_name = data.get("project_name")
- code = data.get("code")
- # TODO: Implement code execution logic
- return jsonify({"message": "Code execution started"})
-```
-
-This function is important because it defines how Devika Tutorial: Open-Source Autonomous AI Software Engineer implements the patterns covered in this chapter.
-
-### `devika.py`
-
-The `get_terminal_session` function in [`devika.py`](https://github.com/stitionai/devika/blob/HEAD/devika.py) handles a key part of this chapter's functionality:
-
-```py
-@app.route("/api/get-terminal-session", methods=["GET"])
-@route_logger(logger)
-def get_terminal_session():
- project_name = request.args.get("project_name")
- agent_state = AgentState.get_latest_state(project_name)
- if not agent_state:
- return jsonify({"terminal_state": None})
- else:
- terminal_state = agent_state["terminal_session"]
- return jsonify({"terminal_state": terminal_state})
-
-
-@app.route("/api/run-code", methods=["POST"])
-@route_logger(logger)
-def run_code():
- data = request.json
- project_name = data.get("project_name")
- code = data.get("code")
- # TODO: Implement code execution logic
- return jsonify({"message": "Code execution started"})
-
-
-@app.route("/api/calculate-tokens", methods=["POST"])
-@route_logger(logger)
-def calculate_tokens():
- data = request.json
- prompt = data.get("prompt")
- tokens = len(TIKTOKEN_ENC.encode(prompt))
- return jsonify({"token_usage": tokens})
-
-
-@app.route("/api/token-usage", methods=["GET"])
-```
-
-This function is important because it defines how Devika Tutorial: Open-Source Autonomous AI Software Engineer implements the patterns covered in this chapter.
-
-### `devika.py`
-
-The `run_code` function in [`devika.py`](https://github.com/stitionai/devika/blob/HEAD/devika.py) handles a key part of this chapter's functionality:
-
-```py
-@app.route("/api/run-code", methods=["POST"])
-@route_logger(logger)
-def run_code():
- data = request.json
- project_name = data.get("project_name")
- code = data.get("code")
- # TODO: Implement code execution logic
- return jsonify({"message": "Code execution started"})
-
-
-@app.route("/api/calculate-tokens", methods=["POST"])
-@route_logger(logger)
-def calculate_tokens():
- data = request.json
- prompt = data.get("prompt")
- tokens = len(TIKTOKEN_ENC.encode(prompt))
- return jsonify({"token_usage": tokens})
-
-
-@app.route("/api/token-usage", methods=["GET"])
-@route_logger(logger)
-def token_usage():
- project_name = request.args.get("project_name")
- token_count = AgentState.get_latest_token_usage(project_name)
- return jsonify({"token_usage": token_count})
-
-
-@app.route("/api/logs", methods=["GET"])
-def real_time_logs():
- log_file = logger.read_log_file()
- return jsonify({"logs": log_file})
-
-```
-
-This function is important because it defines how Devika Tutorial: Open-Source Autonomous AI Software Engineer implements the patterns covered in this chapter.
-
-
## How These Components Connect
```mermaid
flowchart TD
- A[browser_snapshot]
- B[get_browser_session]
- C[get_terminal_session]
- D[run_code]
- E[calculate_tokens]
- A --> B
- B --> C
- C --> D
- D --> E
+ A[User task input] --> B[Planner Agent]
+ B --> C[Break into subtasks]
+ C --> D[Researcher Agent]
+ D --> E[Web search & browse]
+ E --> F[Coder Agent]
+ F --> G[Generate code]
+ G --> H[Action Agent]
+ H --> I[Write files, run code]
+ I --> J[Internal Monologue]
+ J --> K[Agent state update]
```
diff --git a/tutorials/devika-tutorial/03-llm-provider-configuration.md b/tutorials/devika-tutorial/03-llm-provider-configuration.md
index 566c8ace..86f5701e 100644
--- a/tutorials/devika-tutorial/03-llm-provider-configuration.md
+++ b/tutorials/devika-tutorial/03-llm-provider-configuration.md
@@ -39,140 +39,18 @@ You now know how to configure any of Devika's supported LLM providers, select th
Next: [Chapter 4: Task Planning and Code Generation](04-task-planning-and-code-generation.md)
-## Depth Expansion Playbook
-
-## Source Code Walkthrough
-
-### `devika.py`
-
-The `real_time_logs` function in [`devika.py`](https://github.com/stitionai/devika/blob/HEAD/devika.py) handles a key part of this chapter's functionality:
-
-```py
-
-@app.route("/api/logs", methods=["GET"])
-def real_time_logs():
- log_file = logger.read_log_file()
- return jsonify({"logs": log_file})
-
-
-@app.route("/api/settings", methods=["POST"])
-@route_logger(logger)
-def set_settings():
- data = request.json
- config.update_config(data)
- return jsonify({"message": "Settings updated"})
-
-
-@app.route("/api/settings", methods=["GET"])
-@route_logger(logger)
-def get_settings():
- configs = config.get_config()
- return jsonify({"settings": configs})
-
-
-@app.route("/api/status", methods=["GET"])
-@route_logger(logger)
-def status():
- return jsonify({"status": "server is running!"})
-
-if __name__ == "__main__":
- logger.info("Devika is up and running!")
- socketio.run(app, debug=False, port=1337, host="0.0.0.0")
-
-```
-
-This function is important because it defines how Devika Tutorial: Open-Source Autonomous AI Software Engineer implements the patterns covered in this chapter.
-
-### `devika.py`
-
-The `set_settings` function in [`devika.py`](https://github.com/stitionai/devika/blob/HEAD/devika.py) handles a key part of this chapter's functionality:
-
-```py
-@app.route("/api/settings", methods=["POST"])
-@route_logger(logger)
-def set_settings():
- data = request.json
- config.update_config(data)
- return jsonify({"message": "Settings updated"})
-
-
-@app.route("/api/settings", methods=["GET"])
-@route_logger(logger)
-def get_settings():
- configs = config.get_config()
- return jsonify({"settings": configs})
-
-
-@app.route("/api/status", methods=["GET"])
-@route_logger(logger)
-def status():
- return jsonify({"status": "server is running!"})
-
-if __name__ == "__main__":
- logger.info("Devika is up and running!")
- socketio.run(app, debug=False, port=1337, host="0.0.0.0")
-
-```
-
-This function is important because it defines how Devika Tutorial: Open-Source Autonomous AI Software Engineer implements the patterns covered in this chapter.
-
-### `devika.py`
-
-The `get_settings` function in [`devika.py`](https://github.com/stitionai/devika/blob/HEAD/devika.py) handles a key part of this chapter's functionality:
-
-```py
-@app.route("/api/settings", methods=["GET"])
-@route_logger(logger)
-def get_settings():
- configs = config.get_config()
- return jsonify({"settings": configs})
-
-
-@app.route("/api/status", methods=["GET"])
-@route_logger(logger)
-def status():
- return jsonify({"status": "server is running!"})
-
-if __name__ == "__main__":
- logger.info("Devika is up and running!")
- socketio.run(app, debug=False, port=1337, host="0.0.0.0")
-
-```
-
-This function is important because it defines how Devika Tutorial: Open-Source Autonomous AI Software Engineer implements the patterns covered in this chapter.
-
-### `devika.py`
-
-The `status` function in [`devika.py`](https://github.com/stitionai/devika/blob/HEAD/devika.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-@app.route("/api/status", methods=["GET"])
-@route_logger(logger)
-def status():
- return jsonify({"status": "server is running!"})
-
-if __name__ == "__main__":
- logger.info("Devika is up and running!")
- socketio.run(app, debug=False, port=1337, host="0.0.0.0")
-
-```
-
-This function is important because it defines how Devika Tutorial: Open-Source Autonomous AI Software Engineer implements the patterns covered in this chapter.
-
-
## How These Components Connect
```mermaid
flowchart TD
- A[real_time_logs]
- B[set_settings]
- C[get_settings]
- D[status]
- E[Config]
- A --> B
- B --> C
- C --> D
- D --> E
+ A[config.yaml] --> B{Provider selection}
+ B -->|Claude| C[ANTHROPIC_API_KEY]
+ B -->|GPT-4| D[OPENAI_API_KEY]
+ B -->|Gemini| E[GEMINI_API_KEY]
+ B -->|Ollama| F[Local endpoint]
+ C --> G[LLM abstraction layer]
+ D --> G
+ E --> G
+ F --> G
+ G --> H[Agent pipeline]
```
diff --git a/tutorials/devika-tutorial/04-task-planning-and-code-generation.md b/tutorials/devika-tutorial/04-task-planning-and-code-generation.md
index b8fb3626..a9346e2b 100644
--- a/tutorials/devika-tutorial/04-task-planning-and-code-generation.md
+++ b/tutorials/devika-tutorial/04-task-planning-and-code-generation.md
@@ -39,186 +39,17 @@ You now understand how Devika converts a natural language task into a structured
Next: [Chapter 5: Web Research and Browser Integration](05-web-research-and-browser-integration.md)
-## Depth Expansion Playbook
-
-## Source Code Walkthrough
-
-### `src/state.py`
-
-The `AgentState` class in [`src/state.py`](https://github.com/stitionai/devika/blob/HEAD/src/state.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-class AgentStateModel(SQLModel, table=True):
- __tablename__ = "agent_state"
-
- id: Optional[int] = Field(default=None, primary_key=True)
- project: str
- state_stack_json: str
-
-
-class AgentState:
- def __init__(self):
- config = Config()
- sqlite_path = config.get_sqlite_db()
- self.engine = create_engine(f"sqlite:///{sqlite_path}")
- SQLModel.metadata.create_all(self.engine)
-
- def new_state(self):
- timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
-
- return {
- "internal_monologue": '',
- "browser_session": {
- "url": None,
- "screenshot": None
- },
- "terminal_session": {
- "command": None,
- "output": None,
- "title": None
- },
- "step": int(),
-```
-
-This class is important because it defines how Devika Tutorial: Open-Source Autonomous AI Software Engineer implements the patterns covered in this chapter.
-
-### `src/project.py`
-
-The `Projects` class in [`src/project.py`](https://github.com/stitionai/devika/blob/HEAD/src/project.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-class Projects(SQLModel, table=True):
- id: Optional[int] = Field(default=None, primary_key=True)
- project: str
- message_stack_json: str
-
-
-class ProjectManager:
- def __init__(self):
- config = Config()
- sqlite_path = config.get_sqlite_db()
- self.project_path = config.get_projects_dir()
- self.engine = create_engine(f"sqlite:///{sqlite_path}")
- SQLModel.metadata.create_all(self.engine)
-
- def new_message(self):
- timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
-
- return {
- "from_devika": True,
- "message": None,
- "timestamp": timestamp
- }
-
- def create_project(self, project: str):
- with Session(self.engine) as session:
- project_state = Projects(project=project, message_stack_json=json.dumps([]))
- session.add(project_state)
- session.commit()
-
- def delete_project(self, project: str):
-```
-
-This class is important because it defines how Devika Tutorial: Open-Source Autonomous AI Software Engineer implements the patterns covered in this chapter.
-
-### `src/project.py`
-
-The `ProjectManager` class in [`src/project.py`](https://github.com/stitionai/devika/blob/HEAD/src/project.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-class ProjectManager:
- def __init__(self):
- config = Config()
- sqlite_path = config.get_sqlite_db()
- self.project_path = config.get_projects_dir()
- self.engine = create_engine(f"sqlite:///{sqlite_path}")
- SQLModel.metadata.create_all(self.engine)
-
- def new_message(self):
- timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
-
- return {
- "from_devika": True,
- "message": None,
- "timestamp": timestamp
- }
-
- def create_project(self, project: str):
- with Session(self.engine) as session:
- project_state = Projects(project=project, message_stack_json=json.dumps([]))
- session.add(project_state)
- session.commit()
-
- def delete_project(self, project: str):
- with Session(self.engine) as session:
- project_state = session.query(Projects).filter(Projects.project == project).first()
- if project_state:
- session.delete(project_state)
- session.commit()
-
-```
-
-This class is important because it defines how Devika Tutorial: Open-Source Autonomous AI Software Engineer implements the patterns covered in this chapter.
-
-### `src/logger.py`
-
-The `Logger` class in [`src/logger.py`](https://github.com/stitionai/devika/blob/HEAD/src/logger.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-class Logger:
- def __init__(self, filename="devika_agent.log"):
- config = Config()
- logs_dir = config.get_logs_dir()
- self.logger = LogInit(pathName=logs_dir + "/" + filename, console=True, colors=True, encoding="utf-8")
-
- def read_log_file(self) -> str:
- with open(self.logger.pathName, "r") as file:
- return file.read()
-
- def info(self, message: str):
- self.logger.info(message)
- self.logger.flush()
-
- def error(self, message: str):
- self.logger.error(message)
- self.logger.flush()
-
- def warning(self, message: str):
- self.logger.warning(message)
- self.logger.flush()
-
- def debug(self, message: str):
- self.logger.debug(message)
- self.logger.flush()
-
- def exception(self, message: str):
- self.logger.exception(message)
- self.logger.flush()
-
-```
-
-This class is important because it defines how Devika Tutorial: Open-Source Autonomous AI Software Engineer implements the patterns covered in this chapter.
-
-
## How These Components Connect
```mermaid
flowchart TD
- A[AgentState]
- B[Projects]
- C[ProjectManager]
- D[Logger]
- E[route_logger]
- A --> B
- B --> C
- C --> D
- D --> E
+ A[User task] --> B[Planner agent]
+ B --> C[Structured plan with steps]
+ C --> D[Coder agent per step]
+ D --> E[LLM generates code]
+ E --> F[Code written to project workspace]
+ F --> G[Action agent runs code]
+ G --> H{Success?}
+ H -->|Yes| I[Advance to next step]
+ H -->|No| J[Debug / retry cycle]
```
diff --git a/tutorials/devika-tutorial/05-web-research-and-browser-integration.md b/tutorials/devika-tutorial/05-web-research-and-browser-integration.md
index bf8bae83..f370bd3b 100644
--- a/tutorials/devika-tutorial/05-web-research-and-browser-integration.md
+++ b/tutorials/devika-tutorial/05-web-research-and-browser-integration.md
@@ -39,166 +39,18 @@ You now understand how Devika's browser automation layer fetches, extracts, and
Next: [Chapter 6: Project Management and Workspaces](06-project-management-and-workspaces.md)
-## Depth Expansion Playbook
-
-## Source Code Walkthrough
-
-### `src/socket_instance.py`
-
-The `emit_agent` function in [`src/socket_instance.py`](https://github.com/stitionai/devika/blob/HEAD/src/socket_instance.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def emit_agent(channel, content, log=True):
- try:
- socketio.emit(channel, content)
- if log:
- logger.info(f"SOCKET {channel} MESSAGE: {content}")
- return True
- except Exception as e:
- logger.error(f"SOCKET {channel} ERROR: {str(e)}")
- return False
-
-```
-
-This function is important because it defines how Devika Tutorial: Open-Source Autonomous AI Software Engineer implements the patterns covered in this chapter.
-
-### `src/agents/agent.py`
-
-The `Agent` class in [`src/agents/agent.py`](https://github.com/stitionai/devika/blob/HEAD/src/agents/agent.py) handles a key part of this chapter's functionality:
-
-```py
-
-from src.project import ProjectManager
-from src.state import AgentState
-from src.logger import Logger
-
-from src.bert.sentence import SentenceBert
-from src.memory import KnowledgeBase
-from src.browser.search import BingSearch, GoogleSearch, DuckDuckGoSearch
-from src.browser import Browser
-from src.browser import start_interaction
-from src.filesystem import ReadCode
-from src.services import Netlify
-from src.documenter.pdf import PDF
-
-import json
-import time
-import platform
-import tiktoken
-import asyncio
-
-from src.socket_instance import emit_agent
-
-
-class Agent:
- def __init__(self, base_model: str, search_engine: str, browser: Browser = None):
- if not base_model:
- raise ValueError("base_model is required")
-
- self.logger = Logger()
-
- """
- Accumulate contextual keywords from chained prompts of all preparation agents
-```
-
-This class is important because it defines how Devika Tutorial: Open-Source Autonomous AI Software Engineer implements the patterns covered in this chapter.
-
-### `src/browser/interaction.py`
-
-The `Crawler` class in [`src/browser/interaction.py`](https://github.com/stitionai/devika/blob/HEAD/src/browser/interaction.py) handles a key part of this chapter's functionality:
-
-```py
-black_listed_elements = set(["html", "head", "title", "meta", "iframe", "body", "script", "style", "path", "svg", "br", "::marker",])
-
-class Crawler:
- def __init__(self):
- self.browser = (
- sync_playwright()
- .start()
- .chromium.launch(
- headless=True,
- )
- )
-
- self.page = self.browser.new_page()
- self.page.set_viewport_size({"width": 1280, "height": 1080})
-
- def screenshot(self, project_name):
- screenshots_save_path = Config().get_screenshots_dir()
-
- page_metadata = self.page.evaluate("() => { return { url: document.location.href, title: document.title } }")
- page_url = page_metadata['url']
- random_filename = os.urandom(20).hex()
- filename_to_save = f"{random_filename}.png"
- path_to_save = os.path.join(screenshots_save_path, filename_to_save)
-
- self.page.emulate_media(media="screen")
- self.page.screenshot(path=path_to_save)
-
- new_state = AgentState().new_state()
- new_state["internal_monologue"] = "Browsing the web right now..."
- new_state["browser_session"]["url"] = page_url
- new_state["browser_session"]["screenshot"] = path_to_save
- AgentState().add_to_current_state(project_name, new_state)
-```
-
-This class is important because it defines how Devika Tutorial: Open-Source Autonomous AI Software Engineer implements the patterns covered in this chapter.
-
-### `src/browser/interaction.py`
-
-The `start_interaction` function in [`src/browser/interaction.py`](https://github.com/stitionai/devika/blob/HEAD/src/browser/interaction.py) handles a key part of this chapter's functionality:
-
-```py
- return elements_of_interest
-
-def start_interaction(model_id, objective, project_name):
- _crawler = Crawler()
-
- def print_help():
- print(
- "(g) to visit url\n(u) scroll up\n(d) scroll down\n(c) to click\n(t) to type\n" +
- "(h) to view commands again\n(r/enter) to run suggested command\n(o) change objective"
- )
-
- def get_gpt_command(objective, url, previous_command, browser_content):
- prompt = prompt_template
- prompt = prompt.replace("$objective", objective)
- prompt = prompt.replace("$url", url[:100])
- prompt = prompt.replace("$previous_command", previous_command)
- prompt = prompt.replace("$browser_content", browser_content[:4500])
- response = LLM(model_id=model_id).inference(prompt)
- return response
-
- def run_cmd(cmd):
- cmd = cmd.split("\n")[0]
-
- if cmd.startswith("SCROLL UP"):
- _crawler.scroll("up")
- elif cmd.startswith("SCROLL DOWN"):
- _crawler.scroll("down")
- elif cmd.startswith("CLICK"):
- commasplit = cmd.split(",")
- id = commasplit[0].split(" ")[1]
- _crawler.click(id)
- elif cmd.startswith("TYPE"):
-```
-
-This function is important because it defines how Devika Tutorial: Open-Source Autonomous AI Software Engineer implements the patterns covered in this chapter.
-
-
## How These Components Connect
```mermaid
flowchart TD
- A[emit_agent]
- B[Agent]
- C[Crawler]
- D[start_interaction]
- E[InvalidResponseError]
- A --> B
- B --> C
- C --> D
- D --> E
+ A[Researcher agent] --> B{Search engine}
+ B -->|Bing| C[BingSearch API]
+ B -->|Google| D[SerpAPI]
+ B -->|DuckDuckGo| E[DuckDuckGo scraper]
+ C --> F[URL list]
+ D --> F
+ E --> F
+ F --> G[Playwright browser]
+ G --> H[Page content extraction]
+ H --> I[Summarized context for Coder]
```
diff --git a/tutorials/devika-tutorial/06-project-management-and-workspaces.md b/tutorials/devika-tutorial/06-project-management-and-workspaces.md
index 5b755ccc..9c89ebb2 100644
--- a/tutorials/devika-tutorial/06-project-management-and-workspaces.md
+++ b/tutorials/devika-tutorial/06-project-management-and-workspaces.md
@@ -39,186 +39,15 @@ You now know how to create and manage Devika projects, navigate the workspace fi
Next: [Chapter 7: Debugging and Troubleshooting](07-debugging-and-troubleshooting.md)
-## Depth Expansion Playbook
-
-## Source Code Walkthrough
-
-### `src/services/utils.py`
-
-The `validate_responses` function in [`src/services/utils.py`](https://github.com/stitionai/devika/blob/HEAD/src/services/utils.py) handles a key part of this chapter's functionality:
-
-```py
- pass
-
-def validate_responses(func):
- @wraps(func)
- def wrapper(*args, **kwargs):
- args = list(args)
- response = args[1]
- response = response.strip()
-
- try:
- response = json.loads(response)
- print("first", type(response))
- args[1] = response
- return func(*args, **kwargs)
-
- except json.JSONDecodeError:
- pass
-
- try:
- response = response.split("```")[1]
- if response:
- response = json.loads(response.strip())
- print("second", type(response))
- args[1] = response
- return func(*args, **kwargs)
-
- except (IndexError, json.JSONDecodeError):
- pass
-
- try:
- start_index = response.find('{')
- end_index = response.rfind('}')
-```
-
-This function is important because it defines how Devika Tutorial: Open-Source Autonomous AI Software Engineer implements the patterns covered in this chapter.
-
-### `src/browser/search.py`
-
-The `BingSearch` class in [`src/browser/search.py`](https://github.com/stitionai/devika/blob/HEAD/src/browser/search.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-class BingSearch:
- def __init__(self):
- self.config = Config()
- self.bing_api_key = self.config.get_bing_api_key()
- self.bing_api_endpoint = self.config.get_bing_api_endpoint()
- self.query_result = None
-
- def search(self, query):
- headers = {"Ocp-Apim-Subscription-Key": self.bing_api_key}
- params = {"q": query, "mkt": "en-US"}
-
- try:
- response = requests.get(self.bing_api_endpoint, headers=headers, params=params)
- response.raise_for_status()
- self.query_result = response.json()
- return self.query_result
- except Exception as error:
- return error
-
- def get_first_link(self):
- return self.query_result["webPages"]["value"][0]["url"]
-
-
-class GoogleSearch:
- def __init__(self):
- self.config = Config()
- self.google_search_api_key = self.config.get_google_search_api_key()
- self.google_search_engine_ID = self.config.get_google_search_engine_id()
- self.google_search_api_endpoint = self.config.get_google_search_api_endpoint()
- self.query_result = None
-```
-
-This class is important because it defines how Devika Tutorial: Open-Source Autonomous AI Software Engineer implements the patterns covered in this chapter.
-
-### `src/browser/search.py`
-
-The `GoogleSearch` class in [`src/browser/search.py`](https://github.com/stitionai/devika/blob/HEAD/src/browser/search.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-class GoogleSearch:
- def __init__(self):
- self.config = Config()
- self.google_search_api_key = self.config.get_google_search_api_key()
- self.google_search_engine_ID = self.config.get_google_search_engine_id()
- self.google_search_api_endpoint = self.config.get_google_search_api_endpoint()
- self.query_result = None
-
- def search(self, query):
- params = {
- "key": self.google_search_api_key,
- "cx": self.google_search_engine_ID,
- "q": query
- }
- try:
- print("Searching in Google...")
- response = requests.get(self.google_search_api_endpoint, params=params)
- # response.raise_for_status()
- self.query_result = response.json()
- except Exception as error:
- return error
-
- def get_first_link(self):
- item = ""
- try:
- if 'items' in self.query_result:
- item = self.query_result['items'][0]['link']
- return item
- except Exception as error:
- print(error)
-```
-
-This class is important because it defines how Devika Tutorial: Open-Source Autonomous AI Software Engineer implements the patterns covered in this chapter.
-
-### `src/browser/search.py`
-
-The `DuckDuckGoSearch` class in [`src/browser/search.py`](https://github.com/stitionai/devika/blob/HEAD/src/browser/search.py) handles a key part of this chapter's functionality:
-
-```py
- return ""
-
-# class DuckDuckGoSearch:
-# def __init__(self):
-# self.query_result = None
-#
-# def search(self, query):
-# from duckduckgo_search import DDGS
-# try:
-# self.query_result = DDGS().text(query, max_results=5, region="us")
-# print(self.query_result)
-#
-# except Exception as err:
-# print(err)
-#
-# def get_first_link(self):
-# if self.query_result:
-# return self.query_result[0]["href"]
-# else:
-# return None
-#
-
-
-class DuckDuckGoSearch:
- """DuckDuckGo search engine class.
- methods are inherited from the duckduckgo_search package.
- do not change the methods.
-
- currently, the package is not working with our current setup.
- """
- def __init__(self):
- from curl_cffi import requests as curl_requests
-```
-
-This class is important because it defines how Devika Tutorial: Open-Source Autonomous AI Software Engineer implements the patterns covered in this chapter.
-
-
## How These Components Connect
```mermaid
flowchart TD
- A[validate_responses]
- B[BingSearch]
- C[GoogleSearch]
- D[DuckDuckGoSearch]
- E[DuckDuckGoSearch]
- A --> B
- B --> C
- C --> D
- D --> E
+ A[Devika project] --> B[Project workspace directory]
+ B --> C[Generated files]
+ B --> D[Agent state SQLite]
+ D --> E[Message stack per project]
+ E --> F[Resume session]
+ B --> G[Download as ZIP]
+ B --> H[Delete project]
```
diff --git a/tutorials/devika-tutorial/07-debugging-and-troubleshooting.md b/tutorials/devika-tutorial/07-debugging-and-troubleshooting.md
index a026cd9a..a78628a5 100644
--- a/tutorials/devika-tutorial/07-debugging-and-troubleshooting.md
+++ b/tutorials/devika-tutorial/07-debugging-and-troubleshooting.md
@@ -39,175 +39,17 @@ You now have a systematic debugging playbook for Devika that covers log interpre
Next: [Chapter 8: Production Operations and Governance](08-production-operations-and-governance.md)
-## Depth Expansion Playbook
-
-## Source Code Walkthrough
-
-### `src/memory/knowledge_base.py`
-
-The `KnowledgeBase` class in [`src/memory/knowledge_base.py`](https://github.com/stitionai/devika/blob/HEAD/src/memory/knowledge_base.py) handles a key part of this chapter's functionality:
-
-```py
- contents: str
-
-class KnowledgeBase:
- def __init__(self):
- config = Config()
- sqlite_path = config.get_sqlite_db()
- self.engine = create_engine(f"sqlite:///{sqlite_path}")
- SQLModel.metadata.create_all(self.engine)
-
- def add_knowledge(self, tag: str, contents: str):
- knowledge = Knowledge(tag=tag, contents=contents)
- with Session(self.engine) as session:
- session.add(knowledge)
- session.commit()
-
- def get_knowledge(self, tag: str) -> str:
- with Session(self.engine) as session:
- knowledge = session.query(Knowledge).filter(Knowledge.tag == tag).first()
- if knowledge:
- return knowledge.contents
- return None
-```
-
-This class is important because it defines how Devika Tutorial: Open-Source Autonomous AI Software Engineer implements the patterns covered in this chapter.
-
-### `src/llm/llm.py`
-
-The `LLM` class in [`src/llm/llm.py`](https://github.com/stitionai/devika/blob/HEAD/src/llm/llm.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-class LLM:
- def __init__(self, model_id: str = None):
- self.model_id = model_id
- self.log_prompts = config.get_logging_prompts()
- self.timeout_inference = config.get_timeout_inference()
- self.models = {
- "CLAUDE": [
- ("Claude 3 Opus", "claude-3-opus-20240229"),
- ("Claude 3 Sonnet", "claude-3-sonnet-20240229"),
- ("Claude 3 Haiku", "claude-3-haiku-20240307"),
- ],
- "OPENAI": [
- ("GPT-4o-mini", "gpt-4o-mini"),
- ("GPT-4o", "gpt-4o"),
- ("GPT-4 Turbo", "gpt-4-turbo"),
- ("GPT-3.5 Turbo", "gpt-3.5-turbo-0125"),
- ],
- "GOOGLE": [
- ("Gemini 1.0 Pro", "gemini-pro"),
- ("Gemini 1.5 Flash", "gemini-1.5-flash"),
- ("Gemini 1.5 Pro", "gemini-1.5-pro"),
- ],
- "MISTRAL": [
- ("Mistral 7b", "open-mistral-7b"),
- ("Mistral 8x7b", "open-mixtral-8x7b"),
- ("Mistral Medium", "mistral-medium-latest"),
- ("Mistral Small", "mistral-small-latest"),
- ("Mistral Large", "mistral-large-latest"),
- ],
- "GROQ": [
-```
-
-This class is important because it defines how Devika Tutorial: Open-Source Autonomous AI Software Engineer implements the patterns covered in this chapter.
-
-### `src/llm/llm.py`
-
-The `is` interface in [`src/llm/llm.py`](https://github.com/stitionai/devika/blob/HEAD/src/llm/llm.py) handles a key part of this chapter's functionality:
-
-```py
-
-import tiktoken
-from typing import List, Tuple
-
-from src.socket_instance import emit_agent
-from .ollama_client import Ollama
-from .claude_client import Claude
-from .openai_client import OpenAi
-from .gemini_client import Gemini
-from .mistral_client import MistralAi
-from .groq_client import Groq
-from .lm_studio_client import LMStudio
-
-from src.state import AgentState
-
-from src.config import Config
-from src.logger import Logger
-
-TIKTOKEN_ENC = tiktoken.get_encoding("cl100k_base")
-
-ollama = Ollama()
-logger = Logger()
-agentState = AgentState()
-config = Config()
-
-
-class LLM:
- def __init__(self, model_id: str = None):
- self.model_id = model_id
- self.log_prompts = config.get_logging_prompts()
- self.timeout_inference = config.get_timeout_inference()
- self.models = {
-```
-
-This interface is important because it defines how Devika Tutorial: Open-Source Autonomous AI Software Engineer implements the patterns covered in this chapter.
-
-### `src/browser/browser.py`
-
-The `Browser` class in [`src/browser/browser.py`](https://github.com/stitionai/devika/blob/HEAD/src/browser/browser.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-class Browser:
- def __init__(self):
- self.playwright = None
- self.browser = None
- self.page = None
- self.agent = AgentState()
-
- async def start(self):
- self.playwright = await async_playwright().start()
- self.browser = await self.playwright.chromium.launch(headless=True)
- self.page = await self.browser.new_page()
- return self
-
- # def new_page(self):
- # return self.browser.new_page()
-
- async def go_to(self, url):
- try:
- await self.page.goto(url, timeout=20000)
-
- except TimeoutError as e:
- print(f"TimeoutError: {e} when trying to navigate to {url}")
- return False
- return True
-
- async def screenshot(self, project_name):
- screenshots_save_path = Config().get_screenshots_dir()
-
- page_metadata = await self.page.evaluate("() => { return { url: document.location.href, title: document.title } }")
- page_url = page_metadata['url']
-```
-
-This class is important because it defines how Devika Tutorial: Open-Source Autonomous AI Software Engineer implements the patterns covered in this chapter.
-
-
## How These Components Connect
```mermaid
flowchart TD
- A[KnowledgeBase]
- B[LLM]
- C[is]
- D[Browser]
- E[ReadCode]
- A --> B
- B --> C
- C --> D
- D --> E
+ A[Agent error] --> B{Error type}
+ B -->|LLM parse error| C[validate_responses retry]
+ B -->|Browser timeout| D[Retry with backoff]
+ B -->|API rate limit| E[Wait and retry]
+ C --> F[Corrected response]
+ D --> F
+ E --> F
+ F --> G[Agent continues pipeline]
+ G --> H[State logged to DB]
```
diff --git a/tutorials/devika-tutorial/08-production-operations-and-governance.md b/tutorials/devika-tutorial/08-production-operations-and-governance.md
index f213c1ad..4a8deaf6 100644
--- a/tutorials/devika-tutorial/08-production-operations-and-governance.md
+++ b/tutorials/devika-tutorial/08-production-operations-and-governance.md
@@ -39,151 +39,15 @@ You now have a complete production governance framework for Devika covering secu
Return to: [Tutorial Index](README.md)
-## Depth Expansion Playbook
-
-## Source Code Walkthrough
-
-### `src/apis/project.py`
-
-The `create_project` function in [`src/apis/project.py`](https://github.com/stitionai/devika/blob/HEAD/src/apis/project.py) handles a key part of this chapter's functionality:
-
-```py
-@project_bp.route("/api/create-project", methods=["POST"])
-@route_logger(logger)
-def create_project():
- data = request.json
- project_name = data.get("project_name")
- manager.create_project(secure_filename(project_name))
- return jsonify({"message": "Project created"})
-
-
-@project_bp.route("/api/delete-project", methods=["POST"])
-@route_logger(logger)
-def delete_project():
- data = request.json
- project_name = secure_filename(data.get("project_name"))
- manager.delete_project(project_name)
- AgentState().delete_state(project_name)
- return jsonify({"message": "Project deleted"})
-
-
-@project_bp.route("/api/download-project", methods=["GET"])
-@route_logger(logger)
-def download_project():
- project_name = secure_filename(request.args.get("project_name"))
- manager.project_to_zip(project_name)
- project_path = manager.get_zip_path(project_name)
- return send_file(project_path, as_attachment=False)
-
-
-@project_bp.route("/api/download-project-pdf", methods=["GET"])
-@route_logger(logger)
-def download_project_pdf():
- project_name = secure_filename(request.args.get("project_name"))
-```
-
-This function is important because it defines how Devika Tutorial: Open-Source Autonomous AI Software Engineer implements the patterns covered in this chapter.
-
-### `src/apis/project.py`
-
-The `delete_project` function in [`src/apis/project.py`](https://github.com/stitionai/devika/blob/HEAD/src/apis/project.py) handles a key part of this chapter's functionality:
-
-```py
-@project_bp.route("/api/delete-project", methods=["POST"])
-@route_logger(logger)
-def delete_project():
- data = request.json
- project_name = secure_filename(data.get("project_name"))
- manager.delete_project(project_name)
- AgentState().delete_state(project_name)
- return jsonify({"message": "Project deleted"})
-
-
-@project_bp.route("/api/download-project", methods=["GET"])
-@route_logger(logger)
-def download_project():
- project_name = secure_filename(request.args.get("project_name"))
- manager.project_to_zip(project_name)
- project_path = manager.get_zip_path(project_name)
- return send_file(project_path, as_attachment=False)
-
-
-@project_bp.route("/api/download-project-pdf", methods=["GET"])
-@route_logger(logger)
-def download_project_pdf():
- project_name = secure_filename(request.args.get("project_name"))
- pdf_dir = Config().get_pdfs_dir()
- pdf_path = os.path.join(pdf_dir, f"{project_name}.pdf")
-
- response = make_response(send_file(pdf_path))
- response.headers['Content-Type'] = 'project_bplication/pdf'
- return response
-
-```
-
-This function is important because it defines how Devika Tutorial: Open-Source Autonomous AI Software Engineer implements the patterns covered in this chapter.
-
-### `src/apis/project.py`
-
-The `download_project` function in [`src/apis/project.py`](https://github.com/stitionai/devika/blob/HEAD/src/apis/project.py) handles a key part of this chapter's functionality:
-
-```py
-@project_bp.route("/api/download-project", methods=["GET"])
-@route_logger(logger)
-def download_project():
- project_name = secure_filename(request.args.get("project_name"))
- manager.project_to_zip(project_name)
- project_path = manager.get_zip_path(project_name)
- return send_file(project_path, as_attachment=False)
-
-
-@project_bp.route("/api/download-project-pdf", methods=["GET"])
-@route_logger(logger)
-def download_project_pdf():
- project_name = secure_filename(request.args.get("project_name"))
- pdf_dir = Config().get_pdfs_dir()
- pdf_path = os.path.join(pdf_dir, f"{project_name}.pdf")
-
- response = make_response(send_file(pdf_path))
- response.headers['Content-Type'] = 'project_bplication/pdf'
- return response
-
-```
-
-This function is important because it defines how Devika Tutorial: Open-Source Autonomous AI Software Engineer implements the patterns covered in this chapter.
-
-### `src/apis/project.py`
-
-The `download_project_pdf` function in [`src/apis/project.py`](https://github.com/stitionai/devika/blob/HEAD/src/apis/project.py) handles a key part of this chapter's functionality:
-
-```py
-@project_bp.route("/api/download-project-pdf", methods=["GET"])
-@route_logger(logger)
-def download_project_pdf():
- project_name = secure_filename(request.args.get("project_name"))
- pdf_dir = Config().get_pdfs_dir()
- pdf_path = os.path.join(pdf_dir, f"{project_name}.pdf")
-
- response = make_response(send_file(pdf_path))
- response.headers['Content-Type'] = 'project_bplication/pdf'
- return response
-
-```
-
-This function is important because it defines how Devika Tutorial: Open-Source Autonomous AI Software Engineer implements the patterns covered in this chapter.
-
-
## How These Components Connect
```mermaid
flowchart TD
- A[create_project]
- B[delete_project]
- C[download_project]
- D[download_project_pdf]
- E[Gemini]
- A --> B
- B --> C
- C --> D
- D --> E
+ A[Devika instance] --> B[Reverse proxy / auth]
+ B --> C[Rate limiting per user]
+ C --> D[Task queue]
+ D --> E[Agent pipeline execution]
+ E --> F[Cost tracking via token counts]
+ F --> G[Audit log]
+ G --> H[Team review cadence]
```
diff --git a/tutorials/dify-tutorial/01-system-overview.md b/tutorials/dify-tutorial/01-system-overview.md
index 2cf8ba9d..afb34ab3 100644
--- a/tutorials/dify-tutorial/01-system-overview.md
+++ b/tutorials/dify-tutorial/01-system-overview.md
@@ -6,6 +6,7 @@ has_children: false
parent: "Dify Platform Deep Dive"
---
+
# Chapter 1: Dify System Overview
Welcome to **Chapter 1: Dify System Overview**. In this part of **Dify Platform: Deep Dive Tutorial**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
@@ -299,288 +300,19 @@ Suggested trace strategy:
- [Main Catalog](../../README.md#-tutorial-catalog)
- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
-## Depth Expansion Playbook
-
-<!-- depth-expansion-v2 -->
-
-This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
-
-### Strategic Context
-
-- tutorial: **Dify Platform: Deep Dive Tutorial**
-- tutorial slug: **dify-tutorial**
-- chapter focus: **Chapter 1: Dify System Overview**
-- system context: **Dify Platform Deep Dive**
-- objective: move from surface-level usage to repeatable engineering operation
-
-### Architecture Decomposition
-
-1. Define the runtime boundary for `Chapter 1: Dify System Overview`.
-2. Separate control-plane decisions from data-plane execution.
-3. Capture input contracts, transformation points, and output contracts.
-4. Trace state transitions across request lifecycle stages.
-5. Identify extension hooks and policy interception points.
-6. Map ownership boundaries for team and automation workflows.
-7. Specify rollback and recovery paths for unsafe changes.
-8. Track observability signals for correctness, latency, and cost.
-
-### Operator Decision Matrix
-
-| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
-|:--------------|:--------------|:------------------|:---------|
-| Runtime mode | managed defaults | explicit policy config | speed vs control |
-| State handling | local ephemeral | durable persisted state | simplicity vs auditability |
-| Tool integration | direct API use | mediated adapter layer | velocity vs governance |
-| Rollout method | manual change | staged + canary rollout | effort vs safety |
-| Incident response | best effort logs | runbooks + SLO alerts | cost vs reliability |
-
-### Failure Modes and Countermeasures
-
-| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
-|:-------------|:-------------|:-------------------|:---------------|
-| stale context | inconsistent outputs | missing refresh window | enforce context TTL and refresh hooks |
-| policy drift | unexpected execution | ad hoc overrides | centralize policy profiles |
-| auth mismatch | 401/403 bursts | credential sprawl | rotation schedule + scope minimization |
-| schema breakage | parser/validation errors | unmanaged upstream changes | contract tests per release |
-| retry storms | queue congestion | no backoff controls | jittered backoff + circuit breakers |
-| silent regressions | quality drop without alerts | weak baseline metrics | eval harness with thresholds |
-
-### Implementation Runbook
-
-1. Establish a reproducible baseline environment.
-2. Capture chapter-specific success criteria before changes.
-3. Implement minimal viable path with explicit interfaces.
-4. Add observability before expanding feature scope.
-5. Run deterministic tests for happy-path behavior.
-6. Inject failure scenarios for negative-path validation.
-7. Compare output quality against baseline snapshots.
-8. Promote through staged environments with rollback gates.
-9. Record operational lessons in release notes.
-
-### Quality Gate Checklist
-
-- [ ] chapter-level assumptions are explicit and testable
-- [ ] API/tool boundaries are documented with input/output examples
-- [ ] failure handling includes retry, timeout, and fallback policy
-- [ ] security controls include auth scopes and secret rotation plans
-- [ ] observability includes logs, metrics, traces, and alert thresholds
-- [ ] deployment guidance includes canary and rollback paths
-- [ ] docs include links to upstream sources and related tracks
-- [ ] post-release verification confirms expected behavior under load
-
-### Source Alignment
+## How These Components Connect
-- [Dify](https://github.com/langgenius/dify)
-- [AI Codebase Knowledge Builder](https://github.com/The-Pocket/Tutorial-Codebase-Knowledge)
-
-### Cross-Tutorial Connection Map
-
-- Related tutorials are listed in this tutorial index.
-
-### Advanced Practice Exercises
-
-1. Build a minimal end-to-end implementation for `Chapter 1: Dify System Overview`.
-2. Add instrumentation and measure baseline latency and error rate.
-3. Introduce one controlled failure and confirm graceful recovery.
-4. Add policy constraints and verify they are enforced consistently.
-5. Run a staged rollout and document rollback decision criteria.
-
-### Review Questions
-
-1. Which execution boundary matters most for this chapter and why?
-2. What signal detects regressions earliest in your environment?
-3. What tradeoff did you make between delivery speed and governance?
-4. How would you recover from the highest-impact failure mode?
-5. What must be automated before scaling to team-wide adoption?
-
-### Scenario Playbook 1: Chapter 1: Dify System Overview
-
-- tutorial context: **Dify Platform: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 2: Chapter 1: Dify System Overview
-
-- tutorial context: **Dify Platform: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 3: Chapter 1: Dify System Overview
-
-- tutorial context: **Dify Platform: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 4: Chapter 1: Dify System Overview
-
-- tutorial context: **Dify Platform: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 5: Chapter 1: Dify System Overview
-
-- tutorial context: **Dify Platform: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 6: Chapter 1: Dify System Overview
-
-- tutorial context: **Dify Platform: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 7: Chapter 1: Dify System Overview
-
-- tutorial context: **Dify Platform: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 8: Chapter 1: Dify System Overview
-
-- tutorial context: **Dify Platform: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 9: Chapter 1: Dify System Overview
-
-- tutorial context: **Dify Platform: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 10: Chapter 1: Dify System Overview
-
-- tutorial context: **Dify Platform: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 11: Chapter 1: Dify System Overview
-
-- tutorial context: **Dify Platform: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 12: Chapter 1: Dify System Overview
-
-- tutorial context: **Dify Platform: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 13: Chapter 1: Dify System Overview
-
-- tutorial context: **Dify Platform: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 14: Chapter 1: Dify System Overview
-
-- tutorial context: **Dify Platform: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 15: Chapter 1: Dify System Overview
-
-- tutorial context: **Dify Platform: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 16: Chapter 1: Dify System Overview
-
-- tutorial context: **Dify Platform: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
+```mermaid
+flowchart TD
+ A[User/Developer] --> B[Dify Studio UI]
+ B --> C{Build mode}
+ C -->|Chatbot| D[Conversation app]
+ C -->|Workflow| E[DAG-based pipeline]
+ C -->|Agent| F[ReAct / tool-calling agent]
+ D --> G[Dify API backend]
+ E --> G
+ F --> G
+ G --> H[LLM provider]
+ G --> I[Vector store]
+ G --> J[External tools]
+```
diff --git a/tutorials/dify-tutorial/02-core-architecture.md b/tutorials/dify-tutorial/02-core-architecture.md
index cdae1a10..82d2c28b 100644
--- a/tutorials/dify-tutorial/02-core-architecture.md
+++ b/tutorials/dify-tutorial/02-core-architecture.md
@@ -6,6 +6,7 @@ has_children: false
parent: "Dify Platform Deep Dive"
---
+
# Chapter 2: Core Architecture
Welcome to **Chapter 2: Core Architecture**. In this part of **Dify Platform: Deep Dive Tutorial**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
@@ -476,108 +477,19 @@ Suggested trace strategy:
- [Main Catalog](../../README.md#-tutorial-catalog)
- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
-## Depth Expansion Playbook
-
-<!-- depth-expansion-v2 -->
-
-This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
-
-### Strategic Context
-
-- tutorial: **Dify Platform: Deep Dive Tutorial**
-- tutorial slug: **dify-tutorial**
-- chapter focus: **Chapter 2: Core Architecture**
-- system context: **Dify Platform Deep Dive**
-- objective: move from surface-level usage to repeatable engineering operation
-
-### Architecture Decomposition
-
-1. Define the runtime boundary for `Chapter 2: Core Architecture`.
-2. Separate control-plane decisions from data-plane execution.
-3. Capture input contracts, transformation points, and output contracts.
-4. Trace state transitions across request lifecycle stages.
-5. Identify extension hooks and policy interception points.
-6. Map ownership boundaries for team and automation workflows.
-7. Specify rollback and recovery paths for unsafe changes.
-8. Track observability signals for correctness, latency, and cost.
-
-### Operator Decision Matrix
-
-| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
-|:--------------|:--------------|:------------------|:---------|
-| Runtime mode | managed defaults | explicit policy config | speed vs control |
-| State handling | local ephemeral | durable persisted state | simplicity vs auditability |
-| Tool integration | direct API use | mediated adapter layer | velocity vs governance |
-| Rollout method | manual change | staged + canary rollout | effort vs safety |
-| Incident response | best effort logs | runbooks + SLO alerts | cost vs reliability |
-
-### Failure Modes and Countermeasures
-
-| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
-|:-------------|:-------------|:-------------------|:---------------|
-| stale context | inconsistent outputs | missing refresh window | enforce context TTL and refresh hooks |
-| policy drift | unexpected execution | ad hoc overrides | centralize policy profiles |
-| auth mismatch | 401/403 bursts | credential sprawl | rotation schedule + scope minimization |
-| schema breakage | parser/validation errors | unmanaged upstream changes | contract tests per release |
-| retry storms | queue congestion | no backoff controls | jittered backoff + circuit breakers |
-| silent regressions | quality drop without alerts | weak baseline metrics | eval harness with thresholds |
-
-### Implementation Runbook
-
-1. Establish a reproducible baseline environment.
-2. Capture chapter-specific success criteria before changes.
-3. Implement minimal viable path with explicit interfaces.
-4. Add observability before expanding feature scope.
-5. Run deterministic tests for happy-path behavior.
-6. Inject failure scenarios for negative-path validation.
-7. Compare output quality against baseline snapshots.
-8. Promote through staged environments with rollback gates.
-9. Record operational lessons in release notes.
-
-### Quality Gate Checklist
-
-- [ ] chapter-level assumptions are explicit and testable
-- [ ] API/tool boundaries are documented with input/output examples
-- [ ] failure handling includes retry, timeout, and fallback policy
-- [ ] security controls include auth scopes and secret rotation plans
-- [ ] observability includes logs, metrics, traces, and alert thresholds
-- [ ] deployment guidance includes canary and rollback paths
-- [ ] docs include links to upstream sources and related tracks
-- [ ] post-release verification confirms expected behavior under load
-
-### Source Alignment
-
-- [Dify](https://github.com/langgenius/dify)
-- [AI Codebase Knowledge Builder](https://github.com/The-Pocket/Tutorial-Codebase-Knowledge)
-
-### Cross-Tutorial Connection Map
-
-- Related tutorials are listed in this tutorial index.
-
-### Advanced Practice Exercises
+## How These Components Connect
-1. Build a minimal end-to-end implementation for `Chapter 2: Core Architecture`.
-2. Add instrumentation and measure baseline latency and error rate.
-3. Introduce one controlled failure and confirm graceful recovery.
-4. Add policy constraints and verify they are enforced consistently.
-5. Run a staged rollout and document rollback decision criteria.
-
-### Review Questions
-
-1. Which execution boundary matters most for this chapter and why?
-2. What signal detects regressions earliest in your environment?
-3. What tradeoff did you make between delivery speed and governance?
-4. How would you recover from the highest-impact failure mode?
-5. What must be automated before scaling to team-wide adoption?
-
-### Scenario Playbook 1: Chapter 2: Core Architecture
-
-- tutorial context: **Dify Platform: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
+```mermaid
+flowchart TD
+ A[Dify platform] --> B[API service: Flask/Python]
+ A --> C[Web frontend: Next.js]
+ B --> D[Workflow engine]
+ B --> E[RAG pipeline]
+ B --> F[Agent framework]
+ D --> G[Node runner]
+ E --> H[Document processor + vector DB]
+ F --> I[Tool registry]
+ G --> J[LLM calls via provider abstraction]
+ H --> J
+ I --> J
+```
diff --git a/tutorials/dify-tutorial/08-operations-playbook.md b/tutorials/dify-tutorial/08-operations-playbook.md
index 76916f49..1ff1455e 100644
--- a/tutorials/dify-tutorial/08-operations-playbook.md
+++ b/tutorials/dify-tutorial/08-operations-playbook.md
@@ -6,6 +6,7 @@ has_children: false
parent: "Dify Platform Deep Dive"
---
+
# Chapter 8: Operations Playbook
Welcome to **Chapter 8: Operations Playbook**. In this part of **Dify Platform: Deep Dive Tutorial**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
@@ -85,504 +86,17 @@ Suggested trace strategy:
- [Main Catalog](../../README.md#-tutorial-catalog)
- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
-## Depth Expansion Playbook
-
-<!-- depth-expansion-v2 -->
-
-This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
-
-### Strategic Context
-
-- tutorial: **Dify Platform: Deep Dive Tutorial**
-- tutorial slug: **dify-tutorial**
-- chapter focus: **Chapter 8: Operations Playbook**
-- system context: **Dify Platform Deep Dive**
-- objective: move from surface-level usage to repeatable engineering operation
-
-### Architecture Decomposition
-
-1. Define the runtime boundary for `Chapter 8: Operations Playbook`.
-2. Separate control-plane decisions from data-plane execution.
-3. Capture input contracts, transformation points, and output contracts.
-4. Trace state transitions across request lifecycle stages.
-5. Identify extension hooks and policy interception points.
-6. Map ownership boundaries for team and automation workflows.
-7. Specify rollback and recovery paths for unsafe changes.
-8. Track observability signals for correctness, latency, and cost.
-
-### Operator Decision Matrix
-
-| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
-|:--------------|:--------------|:------------------|:---------|
-| Runtime mode | managed defaults | explicit policy config | speed vs control |
-| State handling | local ephemeral | durable persisted state | simplicity vs auditability |
-| Tool integration | direct API use | mediated adapter layer | velocity vs governance |
-| Rollout method | manual change | staged + canary rollout | effort vs safety |
-| Incident response | best effort logs | runbooks + SLO alerts | cost vs reliability |
-
-### Failure Modes and Countermeasures
-
-| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
-|:-------------|:-------------|:-------------------|:---------------|
-| stale context | inconsistent outputs | missing refresh window | enforce context TTL and refresh hooks |
-| policy drift | unexpected execution | ad hoc overrides | centralize policy profiles |
-| auth mismatch | 401/403 bursts | credential sprawl | rotation schedule + scope minimization |
-| schema breakage | parser/validation errors | unmanaged upstream changes | contract tests per release |
-| retry storms | queue congestion | no backoff controls | jittered backoff + circuit breakers |
-| silent regressions | quality drop without alerts | weak baseline metrics | eval harness with thresholds |
-
-### Implementation Runbook
-
-1. Establish a reproducible baseline environment.
-2. Capture chapter-specific success criteria before changes.
-3. Implement minimal viable path with explicit interfaces.
-4. Add observability before expanding feature scope.
-5. Run deterministic tests for happy-path behavior.
-6. Inject failure scenarios for negative-path validation.
-7. Compare output quality against baseline snapshots.
-8. Promote through staged environments with rollback gates.
-9. Record operational lessons in release notes.
-
-### Quality Gate Checklist
-
-- [ ] chapter-level assumptions are explicit and testable
-- [ ] API/tool boundaries are documented with input/output examples
-- [ ] failure handling includes retry, timeout, and fallback policy
-- [ ] security controls include auth scopes and secret rotation plans
-- [ ] observability includes logs, metrics, traces, and alert thresholds
-- [ ] deployment guidance includes canary and rollback paths
-- [ ] docs include links to upstream sources and related tracks
-- [ ] post-release verification confirms expected behavior under load
-
-### Source Alignment
-
-- [Dify](https://github.com/langgenius/dify)
-- [AI Codebase Knowledge Builder](https://github.com/The-Pocket/Tutorial-Codebase-Knowledge)
-
-### Cross-Tutorial Connection Map
-
-- Related tutorials are listed in this tutorial index.
-
-### Advanced Practice Exercises
-
-1. Build a minimal end-to-end implementation for `Chapter 8: Operations Playbook`.
-2. Add instrumentation and measure baseline latency and error rate.
-3. Introduce one controlled failure and confirm graceful recovery.
-4. Add policy constraints and verify they are enforced consistently.
-5. Run a staged rollout and document rollback decision criteria.
-
-### Review Questions
-
-1. Which execution boundary matters most for this chapter and why?
-2. What signal detects regressions earliest in your environment?
-3. What tradeoff did you make between delivery speed and governance?
-4. How would you recover from the highest-impact failure mode?
-5. What must be automated before scaling to team-wide adoption?
-
-### Scenario Playbook 1: Chapter 8: Operations Playbook
-
-- tutorial context: **Dify Platform: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 2: Chapter 8: Operations Playbook
-
-- tutorial context: **Dify Platform: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 3: Chapter 8: Operations Playbook
-
-- tutorial context: **Dify Platform: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 4: Chapter 8: Operations Playbook
-
-- tutorial context: **Dify Platform: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 5: Chapter 8: Operations Playbook
-
-- tutorial context: **Dify Platform: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 6: Chapter 8: Operations Playbook
-
-- tutorial context: **Dify Platform: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 7: Chapter 8: Operations Playbook
-
-- tutorial context: **Dify Platform: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 8: Chapter 8: Operations Playbook
-
-- tutorial context: **Dify Platform: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 9: Chapter 8: Operations Playbook
-
-- tutorial context: **Dify Platform: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 10: Chapter 8: Operations Playbook
-
-- tutorial context: **Dify Platform: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 11: Chapter 8: Operations Playbook
-
-- tutorial context: **Dify Platform: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 12: Chapter 8: Operations Playbook
-
-- tutorial context: **Dify Platform: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 13: Chapter 8: Operations Playbook
-
-- tutorial context: **Dify Platform: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 14: Chapter 8: Operations Playbook
-
-- tutorial context: **Dify Platform: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 15: Chapter 8: Operations Playbook
-
-- tutorial context: **Dify Platform: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 16: Chapter 8: Operations Playbook
-
-- tutorial context: **Dify Platform: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 17: Chapter 8: Operations Playbook
-
-- tutorial context: **Dify Platform: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 18: Chapter 8: Operations Playbook
-
-- tutorial context: **Dify Platform: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 19: Chapter 8: Operations Playbook
-
-- tutorial context: **Dify Platform: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 20: Chapter 8: Operations Playbook
-
-- tutorial context: **Dify Platform: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 21: Chapter 8: Operations Playbook
-
-- tutorial context: **Dify Platform: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 22: Chapter 8: Operations Playbook
-
-- tutorial context: **Dify Platform: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 23: Chapter 8: Operations Playbook
-
-- tutorial context: **Dify Platform: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 24: Chapter 8: Operations Playbook
-
-- tutorial context: **Dify Platform: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 25: Chapter 8: Operations Playbook
-
-- tutorial context: **Dify Platform: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 26: Chapter 8: Operations Playbook
-
-- tutorial context: **Dify Platform: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 27: Chapter 8: Operations Playbook
-
-- tutorial context: **Dify Platform: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 28: Chapter 8: Operations Playbook
-
-- tutorial context: **Dify Platform: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 29: Chapter 8: Operations Playbook
-
-- tutorial context: **Dify Platform: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 30: Chapter 8: Operations Playbook
-
-- tutorial context: **Dify Platform: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 31: Chapter 8: Operations Playbook
-
-- tutorial context: **Dify Platform: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 32: Chapter 8: Operations Playbook
-
-- tutorial context: **Dify Platform: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 33: Chapter 8: Operations Playbook
-
-- tutorial context: **Dify Platform: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 34: Chapter 8: Operations Playbook
-
-- tutorial context: **Dify Platform: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
+## How These Components Connect
+
+```mermaid
+flowchart TD
+ A[Dify production instance] --> B[Health endpoint /health]
+ B --> C{Status}
+ C -->|OK| D[Serve traffic]
+ C -->|Degraded| E[Alert on-call]
+ D --> F[Celery worker queue]
+ F --> G[Async workflow execution]
+ G --> H[Results stored in DB]
+ E --> I[Runbook: restart service]
+ I --> B
+```
diff --git a/tutorials/dspy-tutorial/01-getting-started.md b/tutorials/dspy-tutorial/01-getting-started.md
index 45ff104a..d245cbf8 100644
--- a/tutorials/dspy-tutorial/01-getting-started.md
+++ b/tutorials/dspy-tutorial/01-getting-started.md
@@ -22,14 +22,14 @@ DSPy introduces a paradigm shift in how we work with language models. Instead of
### Installing DSPy
```bash
-# Install DSPy via pip
-pip install dspy-ai
+# Install DSPy via pip (package renamed from dspy-ai to dspy in v2)
+pip install dspy
# For development and latest features
pip install git+https://github.com/stanfordnlp/dspy.git
-# Optional: Install with specific ML frameworks
-pip install dspy-ai[all] # Includes torch, transformers, etc.
+# Optional: Install with all retrieval integrations
+pip install dspy[all]
```
### Setting up API Keys
@@ -64,18 +64,18 @@ In DSPy, language models are abstracted as simple callable objects:
```python
import dspy
-# OpenAI GPT models
-gpt3 = dspy.OpenAI(model="gpt-3.5-turbo")
-gpt4 = dspy.OpenAI(model="gpt-4", max_tokens=300)
+# DSPy 2.x uses dspy.LM with provider/model strings
+gpt4 = dspy.LM("openai/gpt-4o")
+gpt4_mini = dspy.LM("openai/gpt-4o-mini", max_tokens=300)
# Anthropic Claude
-claude = dspy.Claude(model="claude-3-sonnet-20240229")
+claude = dspy.LM("anthropic/claude-3-5-sonnet-20241022")
# Local models via Ollama
-ollama = dspy.OllamaLocal(model="llama2")
+ollama = dspy.LM("ollama_chat/llama3.2", api_base="http://localhost:11434")
# Configure DSPy to use a specific LM
-dspy.settings.configure(lm=gpt4)
+dspy.configure(lm=gpt4)
```
### Retrieval Models (RMs)
@@ -83,24 +83,19 @@ dspy.settings.configure(lm=gpt4)
For retrieval-augmented generation, DSPy supports various retrieval systems:
```python
-# ColBERTv2 (neural retrieval)
-rm_colbert = dspy.ColBERTv2(url="http://20.102.90.50:2017/wiki17_abstracts")
-
-# Pinecone vector database
-rm_pinecone = dspy.Pinecone(
- index="my-index",
- api_key="your-pinecone-key",
- dimension=768
-)
+# In DSPy 2.x, retrieval is handled inline via dspy.Retrieve or RAG modules
+# ColBERTv2 (via dspy.ColBERTv2Retriever)
+retriever = dspy.ColBERTv2(url="http://20.102.90.50:2017/wiki17_abstracts")
-# Weaviate
-rm_weaviate = dspy.Weaviate(
- url="http://localhost:8080",
- class_name="Document"
-)
+# Use retriever inside a module
+class RAGModule(dspy.Module):
+ def __init__(self):
+ self.retrieve = dspy.Retrieve(k=5) # uses default retriever
+ self.generate = dspy.ChainOfThought("context, question -> answer")
-# Configure retrieval model
-dspy.settings.configure(rm=rm_colbert)
+ def forward(self, question):
+ context = self.retrieve(question).passages
+ return self.generate(context=context, question=question)
```
## Your First DSPy Program
@@ -113,8 +108,8 @@ The simplest DSPy program uses the `Predict` module:
import dspy
# Configure DSPy (do this once at the start)
-lm = dspy.OpenAI(model="gpt-3.5-turbo")
-dspy.settings.configure(lm=lm)
+lm = dspy.LM("openai/gpt-4o-mini")
+dspy.configure(lm=lm)
# Define a signature (input/output specification)
class BasicQA(dspy.Signature):
@@ -283,38 +278,28 @@ print(f"Accuracy: {results['accuracy']}")
### Custom Language Model Configuration
```python
-# Advanced OpenAI configuration
-lm_advanced = dspy.OpenAI(
- model="gpt-4",
+# Advanced LM configuration in DSPy 2.x
+lm_advanced = dspy.LM(
+ "openai/gpt-4o",
api_key="your-key",
api_base="https://api.openai.com/v1", # Custom endpoint
max_tokens=1000,
temperature=0.7,
- top_p=0.9,
- frequency_penalty=0.0,
- presence_penalty=0.0,
- model_type="chat" # or "text" for completion models
)
-# Using multiple LMs with automatic fallback
-lm_fallback = dspy.OpenAI(
- model=["gpt-4", "gpt-3.5-turbo"], # Try GPT-4 first, fallback to 3.5
- api_key="your-key"
-)
+# Using a fallback LM
+lm_fallback = dspy.LM("openai/gpt-4o-mini", api_key="your-key")
```
### Caching and Performance
```python
-# Enable caching for development
-dspy.settings.configure(
- lm=lm,
- cache=True, # Cache LM responses
- cache_dir="./dspy_cache"
-)
+# Enable caching for development (DSPy 2.x uses dspy.configure)
+dspy.configure(lm=lm)
# Disable caching for fresh results
-dspy.settings.configure(lm=lm, cache=False)
+lm_no_cache = dspy.LM("openai/gpt-4o-mini", cache=False)
+dspy.configure(lm=lm_no_cache)
```
### Debugging and Logging
@@ -327,10 +312,10 @@ logging.basicConfig(level=logging.INFO)
dspy_logger = logging.getLogger("dspy")
dspy_logger.setLevel(logging.DEBUG)
-# View intermediate steps
-with dspy.settings.trace():
+# View intermediate steps (DSPy 2.x)
+with dspy.context(lm=lm):
result = program(question="What is DSPy?")
- print("Trace:", dspy.settings.trace) # Shows intermediate LM calls
+ print("History:", lm.history[-1]) # Shows last LM call details
```
## Common Patterns and Best Practices
@@ -385,9 +370,9 @@ for q, a in zip(questions, answers):
class DSPyConfig:
def __init__(self):
self.lm_configs = {
- "development": dspy.OpenAI(model="gpt-3.5-turbo", temperature=0.7),
- "production": dspy.OpenAI(model="gpt-4", temperature=0.1),
- "experimental": dspy.Claude(model="claude-3-sonnet-20240229")
+ "development": dspy.LM("openai/gpt-4o-mini", temperature=0.7),
+ "production": dspy.LM("openai/gpt-4o", temperature=0.1),
+ "experimental": dspy.LM("anthropic/claude-3-5-sonnet-20241022"),
}
self.current_config = "development"
@@ -396,7 +381,7 @@ class DSPyConfig:
"""Switch configurations"""
if config_name in self.lm_configs:
lm = self.lm_configs[config_name]
- dspy.settings.configure(lm=lm)
+ dspy.configure(lm=lm)
self.current_config = config_name
print(f"Switched to {config_name} configuration")
else:
@@ -449,6 +434,18 @@ After working through this chapter, you should be able to reason about `Chapter
Use the implementation notes around `program`, `What`, `model` as your checklist when adapting these patterns to your own repository.
+## DSPy Execution Flow
+
+```mermaid
+flowchart TD
+ A[Define task with Signature] --> B[Write DSPy Module]
+ B --> C[Provide training examples]
+ C --> D[Run optimizer / teleprompter]
+ D --> E[Optimized prompt + module]
+ E --> F[Deploy to production]
+ F --> G[LLM executes with optimized instructions]
+```
+
## How it Works Under the Hood
Under the hood, `Chapter 1: Getting Started with DSPy` usually follows a repeatable control path:
diff --git a/tutorials/dspy-tutorial/02-signatures.md b/tutorials/dspy-tutorial/02-signatures.md
index a6094e7c..6ccb2ccc 100644
--- a/tutorials/dspy-tutorial/02-signatures.md
+++ b/tutorials/dspy-tutorial/02-signatures.md
@@ -547,6 +547,19 @@ After working through this chapter, you should be able to reason about `Chapter
Use the implementation notes around `InputField`, `answer`, `Signature` as your checklist when adapting these patterns to your own repository.
+## Signature Contract
+
+```mermaid
+flowchart TD
+ A[dspy.Signature subclass] --> B[InputField declarations]
+ A --> C[OutputField declarations]
+ B --> D[Field descriptions guide LLM]
+ C --> D
+ D --> E[Module uses Signature]
+ E --> F[LLM call with structured I/O]
+ F --> G[Parsed Prediction object]
+```
+
## How it Works Under the Hood
Under the hood, `Chapter 2: Signatures - Defining LM Input/Output Behavior` usually follows a repeatable control path:
diff --git a/tutorials/dspy-tutorial/03-modules.md b/tutorials/dspy-tutorial/03-modules.md
index dd0d7d88..810232db 100644
--- a/tutorials/dspy-tutorial/03-modules.md
+++ b/tutorials/dspy-tutorial/03-modules.md
@@ -118,7 +118,7 @@ Retrieves relevant passages from a knowledge base:
```python
# Configure retrieval model
rm = dspy.ColBERTv2(url="http://20.102.90.50:2017/wiki17_abstracts")
-dspy.settings.configure(rm=rm)
+dspy.configure(rm=rm)
# Basic retrieval
retrieve_module = dspy.Retrieve(k=3) # Get top 3 passages
@@ -755,6 +755,19 @@ After working through this chapter, you should be able to reason about `Chapter
Use the implementation notes around `result`, `answer`, `desc` as your checklist when adapting these patterns to your own repository.
+## Module Architecture
+
+```mermaid
+flowchart TD
+ A[dspy.Module subclass] --> B[Declare predictors in __init__]
+ B --> C[dspy.Predict with Signature]
+ B --> D[dspy.ChainOfThought]
+ B --> E[dspy.ReAct]
+ A --> F[Implement forward method]
+ F --> G[Call predictors with inputs]
+ G --> H[Return Prediction]
+```
+
## How it Works Under the Hood
Under the hood, `Chapter 3: Modules - Reusable DSPy Components` usually follows a repeatable control path:
diff --git a/tutorials/dspy-tutorial/04-rag.md b/tutorials/dspy-tutorial/04-rag.md
index 30bd4cc6..7a9c7acc 100644
--- a/tutorials/dspy-tutorial/04-rag.md
+++ b/tutorials/dspy-tutorial/04-rag.md
@@ -26,7 +26,7 @@ import dspy
# Configure DSPy with retrieval model
rm = dspy.ColBERTv2(url="http://20.102.90.50:2017/wiki17_abstracts")
-dspy.settings.configure(rm=rm)
+dspy.configure(rm=rm)
class BasicRAG(dspy.Module):
def __init__(self, num_passages=3):
@@ -424,7 +424,7 @@ class PineconeRAG(dspy.Module):
dimension=dimension
)
- dspy.settings.configure(rm=self.rm)
+ dspy.configure(rm=self.rm)
self.retrieve = dspy.Retrieve(k=3)
self.generate = dspy.Predict(RAGSignature)
@@ -696,6 +696,20 @@ After working through this chapter, you should be able to reason about `Chapter
Use the implementation notes around `answer`, `passages`, `context` as your checklist when adapting these patterns to your own repository.
+## RAG Pipeline in DSPy
+
+```mermaid
+flowchart TD
+ A[User question] --> B[Retrieve step]
+ B --> C[Retriever: ColBERT / embeddings]
+ C --> D[Top-k passages]
+ D --> E[Generate step]
+ E --> F[dspy.ChainOfThought]
+ F --> G[LLM reads question + context]
+ G --> H[Answer]
+ B --> I[DSPy optimizer tunes retrieval + generation]
+```
+
## How it Works Under the Hood
Under the hood, `Chapter 4: Retrieval-Augmented Generation (RAG) with DSPy` usually follows a repeatable control path:
diff --git a/tutorials/dspy-tutorial/05-optimization.md b/tutorials/dspy-tutorial/05-optimization.md
index 43056c17..1e7f1351 100644
--- a/tutorials/dspy-tutorial/05-optimization.md
+++ b/tutorials/dspy-tutorial/05-optimization.md
@@ -25,8 +25,8 @@ The true power of DSPy lies in its optimization capabilities. Unlike traditional
import dspy
# Configure DSPy
-lm = dspy.OpenAI(model="gpt-3.5-turbo")
-dspy.settings.configure(lm=lm)
+lm = dspy.LM("openai/gpt-4o-mini")
+dspy.configure(lm=lm)
# Define a simple program
class BasicQA(dspy.Signature):
@@ -669,6 +669,24 @@ After working through this chapter, you should be able to reason about `Chapter
Use the implementation notes around `print`, `program`, `score` as your checklist when adapting these patterns to your own repository.
+## DSPy Optimization Loop
+
+```mermaid
+flowchart TD
+ A[Training examples] --> B[Optimizer / Teleprompter]
+ B --> C{Optimizer type}
+ C -->|BootstrapFewShot| D[Select few-shot demos]
+ C -->|MIPRO| E[Propose and score instructions]
+ C -->|BootstrapFinetune| F[Fine-tune weights]
+ D --> G[Optimized module]
+ E --> G
+ F --> G
+ G --> H[Evaluate on dev set]
+ H --> I{Metric improves?}
+ I -->|Yes| J[Save optimized program]
+ I -->|No| B
+```
+
## How it Works Under the Hood
Under the hood, `Chapter 5: Automatic Optimization - DSPy's Superpower` usually follows a repeatable control path:
diff --git a/tutorials/dspy-tutorial/06-advanced-patterns.md b/tutorials/dspy-tutorial/06-advanced-patterns.md
index 61ac31f0..b66f7eb4 100644
--- a/tutorials/dspy-tutorial/06-advanced-patterns.md
+++ b/tutorials/dspy-tutorial/06-advanced-patterns.md
@@ -810,6 +810,20 @@ After working through this chapter, you should be able to reason about `Chapter
Use the implementation notes around `problem`, `task`, `OutputField` as your checklist when adapting these patterns to your own repository.
+## Advanced DSPy Patterns
+
+```mermaid
+flowchart TD
+ A[Complex task] --> B{Pattern}
+ B -->|Multi-hop| C[Chain multiple retrieval + reasoning steps]
+ B -->|Tool use| D[dspy.ReAct with tool signatures]
+ B -->|Multi-agent| E[Specialized sub-modules per role]
+ C --> F[Final answer]
+ D --> F
+ E --> F
+ F --> G[Each module independently optimizable]
+```
+
## How it Works Under the Hood
Under the hood, `Chapter 6: Advanced Patterns - Multi-Hop Reasoning and Tool Integration` usually follows a repeatable control path:
diff --git a/tutorials/dspy-tutorial/07-evaluation.md b/tutorials/dspy-tutorial/07-evaluation.md
index 91b0884a..a8a3286a 100644
--- a/tutorials/dspy-tutorial/07-evaluation.md
+++ b/tutorials/dspy-tutorial/07-evaluation.md
@@ -25,8 +25,8 @@ Evaluation is crucial for DSPy programs. Unlike traditional ML where you train o
import dspy
# Configure DSPy
-lm = dspy.OpenAI(model="gpt-3.5-turbo")
-dspy.settings.configure(lm=lm)
+lm = dspy.LM("openai/gpt-3.5-turbo")
+dspy.configure(lm=lm)
# Create a simple program to evaluate
class BasicQA(dspy.Signature):
@@ -737,6 +737,20 @@ After working through this chapter, you should be able to reason about `Chapter
Use the implementation notes around `program`, `testset`, `example` as your checklist when adapting these patterns to your own repository.
+## DSPy Evaluation Framework
+
+```mermaid
+flowchart TD
+ A[Dev/test dataset] --> B[dspy.Evaluate]
+ B --> C[Run module on each example]
+ C --> D[Apply metric function]
+ D --> E[Score per example]
+ E --> F[Aggregate score]
+ F --> G{Sufficient?}
+ G -->|No| H[Re-optimize or tune]
+ G -->|Yes| I[Deploy program]
+```
+
## How it Works Under the Hood
Under the hood, `Chapter 7: Evaluation & Metrics - Systematic Assessment of DSPy Programs` usually follows a repeatable control path:
diff --git a/tutorials/dspy-tutorial/08-production.md b/tutorials/dspy-tutorial/08-production.md
index 42d04f1e..d84a76eb 100644
--- a/tutorials/dspy-tutorial/08-production.md
+++ b/tutorials/dspy-tutorial/08-production.md
@@ -51,12 +51,12 @@ class CostOptimizedDSPy:
self.model_configs = model_configs
self.models = {}
- # Initialize models
+ # Initialize models (DSPy 2.x uses dspy.LM with provider/model strings)
for name, config in model_configs.items():
if name.startswith("gpt"):
- self.models[name] = dspy.OpenAI(model=config["model"])
+ self.models[name] = dspy.LM(f"openai/{config['model']}")
elif name.startswith("claude"):
- self.models[name] = dspy.Claude(model=config["model"])
+ self.models[name] = dspy.LM(f"anthropic/{config['model']}")
def select_model(self, task_complexity, budget_constraint=None):
"""Select optimal model based on requirements"""
@@ -116,7 +116,7 @@ class ModelRouter:
try:
# Configure DSPy with current model
model = self.get_model(model_name)
- dspy.settings.configure(lm=model)
+ dspy.configure(lm=model)
# Execute program
result = await program_func(*args, **kwargs)
@@ -681,12 +681,12 @@ class GracefulDegradationSystem:
# Modify execution based on degradation level
if current_level == "minimal":
# Use simplest possible execution
- dspy.settings.configure(lm=cost_optimizer.get_model("gpt-3.5-turbo"))
+ dspy.configure(lm=cost_optimizer.get_model("gpt-3.5-turbo"))
kwargs["max_tokens"] = 50 # Limit response length
elif current_level == "degraded":
# Use medium-quality execution
- dspy.settings.configure(lm=cost_optimizer.get_model("claude-3-haiku"))
+ dspy.configure(lm=cost_optimizer.get_model("claude-3-haiku"))
kwargs["max_tokens"] = 100
# Execute with current configuration
@@ -897,6 +897,21 @@ After working through this chapter, you should be able to reason about `Chapter
Use the implementation notes around `model`, `kwargs`, `cache` as your checklist when adapting these patterns to your own repository.
+## Production Deployment
+
+```mermaid
+flowchart TD
+ A[Optimized DSPy program] --> B[Save with program.save]
+ B --> C[Load in production: program.load]
+ C --> D[Configure production LM]
+ D --> E[dspy.configure with caching]
+ E --> F[Serve requests]
+ F --> G[Monitor: latency, cost, accuracy]
+ G --> H{Drift detected?}
+ H -->|Yes| I[Re-optimize with new data]
+ H -->|No| F
+```
+
## How it Works Under the Hood
Under the hood, `Chapter 8: Production Deployment - Scaling DSPy Systems` usually follows a repeatable control path:
diff --git a/tutorials/dspy-tutorial/README.md b/tutorials/dspy-tutorial/README.md
index cebbfe80..9dd3e904 100644
--- a/tutorials/dspy-tutorial/README.md
+++ b/tutorials/dspy-tutorial/README.md
@@ -161,8 +161,8 @@ optimized_program = mipro_optimizer.compile(program, trainset=trainset)
## Quick Start
```bash
-# Install DSPy
-pip install dspy-ai
+# Install DSPy (package renamed to 'dspy' in v2)
+pip install dspy
# Set up OpenAI API key
export OPENAI_API_KEY="your-api-key"
@@ -171,9 +171,9 @@ export OPENAI_API_KEY="your-api-key"
```python
import dspy
-# Configure LM
-lm = dspy.OpenAI(model='gpt-3.5-turbo', api_key='your-key')
-dspy.settings.configure(lm=lm)
+# Configure LM (DSPy 2.x API)
+lm = dspy.LM("openai/gpt-4o-mini")
+dspy.configure(lm=lm)
# Define signature
class BasicQA(dspy.Signature):
@@ -193,10 +193,9 @@ print(result.answer) # "Paris"
```python
import dspy
-# Configure DSPy
-lm = dspy.OpenAI(model='gpt-4')
-rm = dspy.ColBERTv2(url='http://20.102.90.50:2017/wiki17_abstracts')
-dspy.settings.configure(lm=lm, rm=rm)
+# Configure DSPy (2.x API)
+lm = dspy.LM("openai/gpt-4o")
+dspy.configure(lm=lm)
# Define RAG signature
class GenerateAnswer(dspy.Signature):
diff --git a/tutorials/dyad-tutorial/01-getting-started.md b/tutorials/dyad-tutorial/01-getting-started.md
index 7b694a8d..d71d9b77 100644
--- a/tutorials/dyad-tutorial/01-getting-started.md
+++ b/tutorials/dyad-tutorial/01-getting-started.md
@@ -5,6 +5,7 @@ parent: "Dyad Tutorial"
nav_order: 1
---
+
# Chapter 1: Getting Started with Dyad
Welcome to Dyad! If you've ever dreamed of building applications using just natural language, you're in the right place. Dyad opens up the exciting world of AI-powered app development, where you can describe what you want to build and watch the code come to life.
@@ -142,496 +143,17 @@ Congratulations on creating your first AI-generated app! In the next chapter, we
## Depth Expansion Playbook
-<!-- depth-expansion-v2 -->
-
-This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
-
-### Strategic Context
-
-- tutorial: **Dyad Tutorial: Local-First AI App Building**
-- tutorial slug: **dyad-tutorial**
-- chapter focus: **Chapter 1: Getting Started with Dyad**
-- system context: **Dyad Tutorial**
-- objective: move from surface-level usage to repeatable engineering operation
-
-### Architecture Decomposition
-
-1. Define the runtime boundary for `Chapter 1: Getting Started with Dyad`.
-2. Separate control-plane decisions from data-plane execution.
-3. Capture input contracts, transformation points, and output contracts.
-4. Trace state transitions across request lifecycle stages.
-5. Identify extension hooks and policy interception points.
-6. Map ownership boundaries for team and automation workflows.
-7. Specify rollback and recovery paths for unsafe changes.
-8. Track observability signals for correctness, latency, and cost.
-
-### Operator Decision Matrix
-
-| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
-|:--------------|:--------------|:------------------|:---------|
-| Runtime mode | managed defaults | explicit policy config | speed vs control |
-| State handling | local ephemeral | durable persisted state | simplicity vs auditability |
-| Tool integration | direct API use | mediated adapter layer | velocity vs governance |
-| Rollout method | manual change | staged + canary rollout | effort vs safety |
-| Incident response | best effort logs | runbooks + SLO alerts | cost vs reliability |
-
-### Failure Modes and Countermeasures
-
-| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
-|:-------------|:-------------|:-------------------|:---------------|
-| stale context | inconsistent outputs | missing refresh window | enforce context TTL and refresh hooks |
-| policy drift | unexpected execution | ad hoc overrides | centralize policy profiles |
-| auth mismatch | 401/403 bursts | credential sprawl | rotation schedule + scope minimization |
-| schema breakage | parser/validation errors | unmanaged upstream changes | contract tests per release |
-| retry storms | queue congestion | no backoff controls | jittered backoff + circuit breakers |
-| silent regressions | quality drop without alerts | weak baseline metrics | eval harness with thresholds |
-
-### Implementation Runbook
-
-1. Establish a reproducible baseline environment.
-2. Capture chapter-specific success criteria before changes.
-3. Implement minimal viable path with explicit interfaces.
-4. Add observability before expanding feature scope.
-5. Run deterministic tests for happy-path behavior.
-6. Inject failure scenarios for negative-path validation.
-7. Compare output quality against baseline snapshots.
-8. Promote through staged environments with rollback gates.
-9. Record operational lessons in release notes.
-
-### Quality Gate Checklist
-
-- [ ] chapter-level assumptions are explicit and testable
-- [ ] API/tool boundaries are documented with input/output examples
-- [ ] failure handling includes retry, timeout, and fallback policy
-- [ ] security controls include auth scopes and secret rotation plans
-- [ ] observability includes logs, metrics, traces, and alert thresholds
-- [ ] deployment guidance includes canary and rollback paths
-- [ ] docs include links to upstream sources and related tracks
-- [ ] post-release verification confirms expected behavior under load
-
-### Source Alignment
-
-- [Dyad README](https://github.com/dyad-sh/dyad/blob/main/README.md)
-- [Dyad Releases](https://github.com/dyad-sh/dyad/releases)
-- [Dyad Repository](https://github.com/dyad-sh/dyad)
-
-### Cross-Tutorial Connection Map
-
-- [bolt.diy Tutorial](../bolt-diy-tutorial/)
-- [Vercel AI SDK Tutorial](../vercel-ai-tutorial/)
-- [Cline Tutorial](../cline-tutorial/)
-- [Roo Code Tutorial](../roo-code-tutorial/)
-- [Chapter 1: Getting Started](01-getting-started.md)
-
-### Advanced Practice Exercises
-
-1. Build a minimal end-to-end implementation for `Chapter 1: Getting Started with Dyad`.
-2. Add instrumentation and measure baseline latency and error rate.
-3. Introduce one controlled failure and confirm graceful recovery.
-4. Add policy constraints and verify they are enforced consistently.
-5. Run a staged rollout and document rollback decision criteria.
-
-### Review Questions
-
-1. Which execution boundary matters most for this chapter and why?
-2. What signal detects regressions earliest in your environment?
-3. What tradeoff did you make between delivery speed and governance?
-4. How would you recover from the highest-impact failure mode?
-5. What must be automated before scaling to team-wide adoption?
-
-### Scenario Playbook 1: Chapter 1: Getting Started with Dyad
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 2: Chapter 1: Getting Started with Dyad
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 3: Chapter 1: Getting Started with Dyad
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 4: Chapter 1: Getting Started with Dyad
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 5: Chapter 1: Getting Started with Dyad
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 6: Chapter 1: Getting Started with Dyad
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 7: Chapter 1: Getting Started with Dyad
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 8: Chapter 1: Getting Started with Dyad
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 9: Chapter 1: Getting Started with Dyad
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 10: Chapter 1: Getting Started with Dyad
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 11: Chapter 1: Getting Started with Dyad
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 12: Chapter 1: Getting Started with Dyad
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 13: Chapter 1: Getting Started with Dyad
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 14: Chapter 1: Getting Started with Dyad
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 15: Chapter 1: Getting Started with Dyad
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 16: Chapter 1: Getting Started with Dyad
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 17: Chapter 1: Getting Started with Dyad
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 18: Chapter 1: Getting Started with Dyad
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 19: Chapter 1: Getting Started with Dyad
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 20: Chapter 1: Getting Started with Dyad
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 21: Chapter 1: Getting Started with Dyad
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 22: Chapter 1: Getting Started with Dyad
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 23: Chapter 1: Getting Started with Dyad
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 24: Chapter 1: Getting Started with Dyad
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 25: Chapter 1: Getting Started with Dyad
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 26: Chapter 1: Getting Started with Dyad
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 27: Chapter 1: Getting Started with Dyad
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 28: Chapter 1: Getting Started with Dyad
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 29: Chapter 1: Getting Started with Dyad
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-## What Problem Does This Solve?
-
-Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for `dyad`, `Create`, `tasks` so behavior stays predictable as complexity grows.
-
-In practical terms, this chapter helps you avoid three common failures:
-
-- coupling core logic too tightly to one implementation path
-- missing the handoff boundaries between setup, execution, and validation
-- shipping changes without clear rollback or observability strategy
-
-After working through this chapter, you should be able to reason about `Chapter 1: Getting Started with Dyad` as an operating subsystem inside **Dyad Tutorial: Local-First AI App Building**, with explicit contracts for inputs, state transitions, and outputs.
-
-Use the implementation notes around `Clone`, `Dyad`, `repository` as your checklist when adapting these patterns to your own repository.
-
-## How it Works Under the Hood
-
-Under the hood, `Chapter 1: Getting Started with Dyad` usually follows a repeatable control path:
-
-1. **Context bootstrap**: initialize runtime config and prerequisites for `dyad`.
-2. **Input normalization**: shape incoming data so `Create` receives stable contracts.
-3. **Core execution**: run the main logic branch and propagate intermediate state through `tasks`.
-4. **Policy and safety checks**: enforce limits, auth scopes, and failure boundaries.
-5. **Output composition**: return canonical result payloads for downstream consumers.
-6. **Operational telemetry**: emit logs/metrics needed for debugging and performance tuning.
-
-When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
-
-## Source Walkthrough
-
-Use the following upstream sources to verify implementation details while reading this chapter:
-
-- [Dyad README](https://github.com/dyad-sh/dyad/blob/main/README.md)
- Why it matters: authoritative reference on `Dyad README` (github.com).
-- [Dyad Releases](https://github.com/dyad-sh/dyad/releases)
- Why it matters: authoritative reference on `Dyad Releases` (github.com).
-- [Dyad Repository](https://github.com/dyad-sh/dyad)
- Why it matters: authoritative reference on `Dyad Repository` (github.com).
-
-Suggested trace strategy:
-- search upstream code for `dyad` and `Create` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
-
-## Chapter Connections
-
-- [Tutorial Index](README.md)
-- [Next Chapter: Chapter 2: Natural Language App Building](02-natural-language-building.md)
-- [Main Catalog](../../README.md#-tutorial-catalog)
-- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
+## How These Components Connect
+
+```mermaid
+flowchart TD
+ A[Install Dyad: download .dmg or .exe] --> B[Launch Dyad desktop app]
+ B --> C[Configure LLM provider API key]
+ C --> D[Open or create project]
+ D --> E[Enter natural language prompt]
+ E --> F[Dyad generates code changes]
+ F --> G[Review diff in editor]
+ G --> H{Accept?}
+ H -->|Yes| I[Changes applied to files]
+ H -->|No| J[Reject / modify prompt]
+```
diff --git a/tutorials/dyad-tutorial/02-natural-language-building.md b/tutorials/dyad-tutorial/02-natural-language-building.md
index 6a272c00..352641f7 100644
--- a/tutorials/dyad-tutorial/02-natural-language-building.md
+++ b/tutorials/dyad-tutorial/02-natural-language-building.md
@@ -5,6 +5,7 @@ parent: "Dyad Tutorial"
nav_order: 2
---
+
# Chapter 2: Natural Language App Building
Welcome to **Chapter 2: Natural Language App Building**. In this part of **Dyad Tutorial: Local-First AI App Building**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
@@ -203,437 +204,15 @@ You've learned the fundamentals of natural language app building with Dyad. In t
## Depth Expansion Playbook
-<!-- depth-expansion-v2 -->
-
-This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
-
-### Strategic Context
-
-- tutorial: **Dyad Tutorial: Local-First AI App Building**
-- tutorial slug: **dyad-tutorial**
-- chapter focus: **Chapter 2: Natural Language App Building**
-- system context: **Dyad Tutorial**
-- objective: move from surface-level usage to repeatable engineering operation
-
-### Architecture Decomposition
-
-1. Define the runtime boundary for `Chapter 2: Natural Language App Building`.
-2. Separate control-plane decisions from data-plane execution.
-3. Capture input contracts, transformation points, and output contracts.
-4. Trace state transitions across request lifecycle stages.
-5. Identify extension hooks and policy interception points.
-6. Map ownership boundaries for team and automation workflows.
-7. Specify rollback and recovery paths for unsafe changes.
-8. Track observability signals for correctness, latency, and cost.
-
-### Operator Decision Matrix
-
-| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
-|:--------------|:--------------|:------------------|:---------|
-| Runtime mode | managed defaults | explicit policy config | speed vs control |
-| State handling | local ephemeral | durable persisted state | simplicity vs auditability |
-| Tool integration | direct API use | mediated adapter layer | velocity vs governance |
-| Rollout method | manual change | staged + canary rollout | effort vs safety |
-| Incident response | best effort logs | runbooks + SLO alerts | cost vs reliability |
-
-### Failure Modes and Countermeasures
-
-| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
-|:-------------|:-------------|:-------------------|:---------------|
-| stale context | inconsistent outputs | missing refresh window | enforce context TTL and refresh hooks |
-| policy drift | unexpected execution | ad hoc overrides | centralize policy profiles |
-| auth mismatch | 401/403 bursts | credential sprawl | rotation schedule + scope minimization |
-| schema breakage | parser/validation errors | unmanaged upstream changes | contract tests per release |
-| retry storms | queue congestion | no backoff controls | jittered backoff + circuit breakers |
-| silent regressions | quality drop without alerts | weak baseline metrics | eval harness with thresholds |
-
-### Implementation Runbook
-
-1. Establish a reproducible baseline environment.
-2. Capture chapter-specific success criteria before changes.
-3. Implement minimal viable path with explicit interfaces.
-4. Add observability before expanding feature scope.
-5. Run deterministic tests for happy-path behavior.
-6. Inject failure scenarios for negative-path validation.
-7. Compare output quality against baseline snapshots.
-8. Promote through staged environments with rollback gates.
-9. Record operational lessons in release notes.
-
-### Quality Gate Checklist
-
-- [ ] chapter-level assumptions are explicit and testable
-- [ ] API/tool boundaries are documented with input/output examples
-- [ ] failure handling includes retry, timeout, and fallback policy
-- [ ] security controls include auth scopes and secret rotation plans
-- [ ] observability includes logs, metrics, traces, and alert thresholds
-- [ ] deployment guidance includes canary and rollback paths
-- [ ] docs include links to upstream sources and related tracks
-- [ ] post-release verification confirms expected behavior under load
-
-### Source Alignment
-
-- [Dyad README](https://github.com/dyad-sh/dyad/blob/main/README.md)
-- [Dyad Releases](https://github.com/dyad-sh/dyad/releases)
-- [Dyad Repository](https://github.com/dyad-sh/dyad)
-
-### Cross-Tutorial Connection Map
-
-- [bolt.diy Tutorial](../bolt-diy-tutorial/)
-- [Vercel AI SDK Tutorial](../vercel-ai-tutorial/)
-- [Cline Tutorial](../cline-tutorial/)
-- [Roo Code Tutorial](../roo-code-tutorial/)
-- [Chapter 1: Getting Started](01-getting-started.md)
-
-### Advanced Practice Exercises
-
-1. Build a minimal end-to-end implementation for `Chapter 2: Natural Language App Building`.
-2. Add instrumentation and measure baseline latency and error rate.
-3. Introduce one controlled failure and confirm graceful recovery.
-4. Add policy constraints and verify they are enforced consistently.
-5. Run a staged rollout and document rollback decision criteria.
-
-### Review Questions
-
-1. Which execution boundary matters most for this chapter and why?
-2. What signal detects regressions earliest in your environment?
-3. What tradeoff did you make between delivery speed and governance?
-4. How would you recover from the highest-impact failure mode?
-5. What must be automated before scaling to team-wide adoption?
-
-### Scenario Playbook 1: Chapter 2: Natural Language App Building
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 2: Chapter 2: Natural Language App Building
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 3: Chapter 2: Natural Language App Building
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 4: Chapter 2: Natural Language App Building
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 5: Chapter 2: Natural Language App Building
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 6: Chapter 2: Natural Language App Building
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 7: Chapter 2: Natural Language App Building
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 8: Chapter 2: Natural Language App Building
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 9: Chapter 2: Natural Language App Building
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 10: Chapter 2: Natural Language App Building
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 11: Chapter 2: Natural Language App Building
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 12: Chapter 2: Natural Language App Building
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 13: Chapter 2: Natural Language App Building
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 14: Chapter 2: Natural Language App Building
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 15: Chapter 2: Natural Language App Building
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 16: Chapter 2: Natural Language App Building
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 17: Chapter 2: Natural Language App Building
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 18: Chapter 2: Natural Language App Building
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 19: Chapter 2: Natural Language App Building
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 20: Chapter 2: Natural Language App Building
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 21: Chapter 2: Natural Language App Building
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 22: Chapter 2: Natural Language App Building
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 23: Chapter 2: Natural Language App Building
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 24: Chapter 2: Natural Language App Building
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-## What Problem Does This Solve?
-
-Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for `Create`, `Build`, `management` so behavior stays predictable as complexity grows.
-
-In practical terms, this chapter helps you avoid three common failures:
-
-- coupling core logic too tightly to one implementation path
-- missing the handoff boundaries between setup, execution, and validation
-- shipping changes without clear rollback or observability strategy
-
-After working through this chapter, you should be able to reason about `Chapter 2: Natural Language App Building` as an operating subsystem inside **Dyad Tutorial: Local-First AI App Building**, with explicit contracts for inputs, state transitions, and outputs.
-
-Use the implementation notes around `User`, `users`, `categories` as your checklist when adapting these patterns to your own repository.
-
-## How it Works Under the Hood
-
-Under the hood, `Chapter 2: Natural Language App Building` usually follows a repeatable control path:
-
-1. **Context bootstrap**: initialize runtime config and prerequisites for `Create`.
-2. **Input normalization**: shape incoming data so `Build` receives stable contracts.
-3. **Core execution**: run the main logic branch and propagate intermediate state through `management`.
-4. **Policy and safety checks**: enforce limits, auth scopes, and failure boundaries.
-5. **Output composition**: return canonical result payloads for downstream consumers.
-6. **Operational telemetry**: emit logs/metrics needed for debugging and performance tuning.
-
-When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
-
-## Source Walkthrough
-
-Use the following upstream sources to verify implementation details while reading this chapter:
-
-- [Dyad README](https://github.com/dyad-sh/dyad/blob/main/README.md)
- Why it matters: authoritative reference on `Dyad README` (github.com).
-- [Dyad Releases](https://github.com/dyad-sh/dyad/releases)
- Why it matters: authoritative reference on `Dyad Releases` (github.com).
-- [Dyad Repository](https://github.com/dyad-sh/dyad)
- Why it matters: authoritative reference on `Dyad Repository` (github.com).
-
-Suggested trace strategy:
-- search upstream code for `Create` and `Build` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
-
-## Chapter Connections
-
-- [Tutorial Index](README.md)
-- [Previous Chapter: Chapter 1: Getting Started with Dyad](01-getting-started.md)
-- [Next Chapter: Chapter 3: Component Integration](03-component-integration.md)
-- [Main Catalog](../../README.md#-tutorial-catalog)
-- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
+## How These Components Connect
+
+```mermaid
+flowchart TD
+ A[User prompt in Dyad] --> B[LLM processes request]
+ B --> C[Structured code diff]
+ C --> D[Dyad applies virtual filesystem changes]
+ D --> E[Preview in embedded browser]
+ E --> F{Looks good?}
+ F -->|Yes| G[Commit changes to disk]
+ F -->|No| H[Refine prompt or revert]
+```
diff --git a/tutorials/dyad-tutorial/03-component-integration.md b/tutorials/dyad-tutorial/03-component-integration.md
index e0b08ae5..27643001 100644
--- a/tutorials/dyad-tutorial/03-component-integration.md
+++ b/tutorials/dyad-tutorial/03-component-integration.md
@@ -5,6 +5,7 @@ parent: "Dyad Tutorial"
nav_order: 3
---
+
# Chapter 3: Component Integration
Welcome to **Chapter 3: Component Integration**. In this part of **Dyad Tutorial: Local-First AI App Building**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
@@ -152,485 +153,14 @@ You've learned how to integrate components into your Dyad applications. In the n
## Depth Expansion Playbook
-<!-- depth-expansion-v2 -->
-
-This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
-
-### Strategic Context
-
-- tutorial: **Dyad Tutorial: Local-First AI App Building**
-- tutorial slug: **dyad-tutorial**
-- chapter focus: **Chapter 3: Component Integration**
-- system context: **Dyad Tutorial**
-- objective: move from surface-level usage to repeatable engineering operation
-
-### Architecture Decomposition
-
-1. Define the runtime boundary for `Chapter 3: Component Integration`.
-2. Separate control-plane decisions from data-plane execution.
-3. Capture input contracts, transformation points, and output contracts.
-4. Trace state transitions across request lifecycle stages.
-5. Identify extension hooks and policy interception points.
-6. Map ownership boundaries for team and automation workflows.
-7. Specify rollback and recovery paths for unsafe changes.
-8. Track observability signals for correctness, latency, and cost.
-
-### Operator Decision Matrix
-
-| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
-|:--------------|:--------------|:------------------|:---------|
-| Runtime mode | managed defaults | explicit policy config | speed vs control |
-| State handling | local ephemeral | durable persisted state | simplicity vs auditability |
-| Tool integration | direct API use | mediated adapter layer | velocity vs governance |
-| Rollout method | manual change | staged + canary rollout | effort vs safety |
-| Incident response | best effort logs | runbooks + SLO alerts | cost vs reliability |
-
-### Failure Modes and Countermeasures
-
-| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
-|:-------------|:-------------|:-------------------|:---------------|
-| stale context | inconsistent outputs | missing refresh window | enforce context TTL and refresh hooks |
-| policy drift | unexpected execution | ad hoc overrides | centralize policy profiles |
-| auth mismatch | 401/403 bursts | credential sprawl | rotation schedule + scope minimization |
-| schema breakage | parser/validation errors | unmanaged upstream changes | contract tests per release |
-| retry storms | queue congestion | no backoff controls | jittered backoff + circuit breakers |
-| silent regressions | quality drop without alerts | weak baseline metrics | eval harness with thresholds |
-
-### Implementation Runbook
-
-1. Establish a reproducible baseline environment.
-2. Capture chapter-specific success criteria before changes.
-3. Implement minimal viable path with explicit interfaces.
-4. Add observability before expanding feature scope.
-5. Run deterministic tests for happy-path behavior.
-6. Inject failure scenarios for negative-path validation.
-7. Compare output quality against baseline snapshots.
-8. Promote through staged environments with rollback gates.
-9. Record operational lessons in release notes.
-
-### Quality Gate Checklist
-
-- [ ] chapter-level assumptions are explicit and testable
-- [ ] API/tool boundaries are documented with input/output examples
-- [ ] failure handling includes retry, timeout, and fallback policy
-- [ ] security controls include auth scopes and secret rotation plans
-- [ ] observability includes logs, metrics, traces, and alert thresholds
-- [ ] deployment guidance includes canary and rollback paths
-- [ ] docs include links to upstream sources and related tracks
-- [ ] post-release verification confirms expected behavior under load
-
-### Source Alignment
-
-- [Dyad README](https://github.com/dyad-sh/dyad/blob/main/README.md)
-- [Dyad Releases](https://github.com/dyad-sh/dyad/releases)
-- [Dyad Repository](https://github.com/dyad-sh/dyad)
-
-### Cross-Tutorial Connection Map
-
-- [bolt.diy Tutorial](../bolt-diy-tutorial/)
-- [Vercel AI SDK Tutorial](../vercel-ai-tutorial/)
-- [Cline Tutorial](../cline-tutorial/)
-- [Roo Code Tutorial](../roo-code-tutorial/)
-- [Chapter 1: Getting Started](01-getting-started.md)
-
-### Advanced Practice Exercises
-
-1. Build a minimal end-to-end implementation for `Chapter 3: Component Integration`.
-2. Add instrumentation and measure baseline latency and error rate.
-3. Introduce one controlled failure and confirm graceful recovery.
-4. Add policy constraints and verify they are enforced consistently.
-5. Run a staged rollout and document rollback decision criteria.
-
-### Review Questions
-
-1. Which execution boundary matters most for this chapter and why?
-2. What signal detects regressions earliest in your environment?
-3. What tradeoff did you make between delivery speed and governance?
-4. How would you recover from the highest-impact failure mode?
-5. What must be automated before scaling to team-wide adoption?
-
-### Scenario Playbook 1: Chapter 3: Component Integration
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 2: Chapter 3: Component Integration
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 3: Chapter 3: Component Integration
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 4: Chapter 3: Component Integration
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 5: Chapter 3: Component Integration
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 6: Chapter 3: Component Integration
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 7: Chapter 3: Component Integration
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 8: Chapter 3: Component Integration
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 9: Chapter 3: Component Integration
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 10: Chapter 3: Component Integration
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 11: Chapter 3: Component Integration
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 12: Chapter 3: Component Integration
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 13: Chapter 3: Component Integration
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 14: Chapter 3: Component Integration
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 15: Chapter 3: Component Integration
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 16: Chapter 3: Component Integration
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 17: Chapter 3: Component Integration
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 18: Chapter 3: Component Integration
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 19: Chapter 3: Component Integration
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 20: Chapter 3: Component Integration
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 21: Chapter 3: Component Integration
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 22: Chapter 3: Component Integration
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 23: Chapter 3: Component Integration
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 24: Chapter 3: Component Integration
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 25: Chapter 3: Component Integration
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 26: Chapter 3: Component Integration
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 27: Chapter 3: Component Integration
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 28: Chapter 3: Component Integration
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-## What Problem Does This Solve?
-
-Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for `components`, `table`, `component` so behavior stays predictable as complexity grows.
-
-In practical terms, this chapter helps you avoid three common failures:
-
-- coupling core logic too tightly to one implementation path
-- missing the handoff boundaries between setup, execution, and validation
-- shipping changes without clear rollback or observability strategy
-
-After working through this chapter, you should be able to reason about `Chapter 3: Component Integration` as an operating subsystem inside **Dyad Tutorial: Local-First AI App Building**, with explicit contracts for inputs, state transitions, and outputs.
-
-Use the implementation notes around `display`, `user`, `information` as your checklist when adapting these patterns to your own repository.
-
-## How it Works Under the Hood
-
-Under the hood, `Chapter 3: Component Integration` usually follows a repeatable control path:
-
-1. **Context bootstrap**: initialize runtime config and prerequisites for `components`.
-2. **Input normalization**: shape incoming data so `table` receives stable contracts.
-3. **Core execution**: run the main logic branch and propagate intermediate state through `component`.
-4. **Policy and safety checks**: enforce limits, auth scopes, and failure boundaries.
-5. **Output composition**: return canonical result payloads for downstream consumers.
-6. **Operational telemetry**: emit logs/metrics needed for debugging and performance tuning.
-
-When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
-
-## Source Walkthrough
-
-Use the following upstream sources to verify implementation details while reading this chapter:
-
-- [Dyad README](https://github.com/dyad-sh/dyad/blob/main/README.md)
- Why it matters: authoritative reference on `Dyad README` (github.com).
-- [Dyad Releases](https://github.com/dyad-sh/dyad/releases)
- Why it matters: authoritative reference on `Dyad Releases` (github.com).
-- [Dyad Repository](https://github.com/dyad-sh/dyad)
- Why it matters: authoritative reference on `Dyad Repository` (github.com).
-
-Suggested trace strategy:
-- search upstream code for `components` and `table` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
-
-## Chapter Connections
-
-- [Tutorial Index](README.md)
-- [Previous Chapter: Chapter 2: Natural Language App Building](02-natural-language-building.md)
-- [Next Chapter: Chapter 4: Data Management](04-data-management.md)
-- [Main Catalog](../../README.md#-tutorial-catalog)
-- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
+## How These Components Connect
+
+```mermaid
+flowchart TD
+ A[Existing component in project] --> B[Select via Dyad UI]
+ B --> C[Prompt: modify this component]
+ C --> D[LLM generates targeted diff]
+ D --> E[Component selector highlights changes]
+ E --> F[Apply or reject per component]
+ F --> G[Integrated into app]
+```
diff --git a/tutorials/dyad-tutorial/04-data-management.md b/tutorials/dyad-tutorial/04-data-management.md
index cac24991..248aa83d 100644
--- a/tutorials/dyad-tutorial/04-data-management.md
+++ b/tutorials/dyad-tutorial/04-data-management.md
@@ -5,6 +5,7 @@ parent: "Dyad Tutorial"
nav_order: 4
---
+
# Chapter 4: Data Management
Welcome to **Chapter 4: Data Management**. In this part of **Dyad Tutorial: Local-First AI App Building**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
@@ -132,509 +133,15 @@ You've learned data management fundamentals. Next, we'll explore API integration
## Depth Expansion Playbook
-<!-- depth-expansion-v2 -->
-
-This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
-
-### Strategic Context
-
-- tutorial: **Dyad Tutorial: Local-First AI App Building**
-- tutorial slug: **dyad-tutorial**
-- chapter focus: **Chapter 4: Data Management**
-- system context: **Dyad Tutorial**
-- objective: move from surface-level usage to repeatable engineering operation
-
-### Architecture Decomposition
-
-1. Define the runtime boundary for `Chapter 4: Data Management`.
-2. Separate control-plane decisions from data-plane execution.
-3. Capture input contracts, transformation points, and output contracts.
-4. Trace state transitions across request lifecycle stages.
-5. Identify extension hooks and policy interception points.
-6. Map ownership boundaries for team and automation workflows.
-7. Specify rollback and recovery paths for unsafe changes.
-8. Track observability signals for correctness, latency, and cost.
-
-### Operator Decision Matrix
-
-| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
-|:--------------|:--------------|:------------------|:---------|
-| Runtime mode | managed defaults | explicit policy config | speed vs control |
-| State handling | local ephemeral | durable persisted state | simplicity vs auditability |
-| Tool integration | direct API use | mediated adapter layer | velocity vs governance |
-| Rollout method | manual change | staged + canary rollout | effort vs safety |
-| Incident response | best effort logs | runbooks + SLO alerts | cost vs reliability |
-
-### Failure Modes and Countermeasures
-
-| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
-|:-------------|:-------------|:-------------------|:---------------|
-| stale context | inconsistent outputs | missing refresh window | enforce context TTL and refresh hooks |
-| policy drift | unexpected execution | ad hoc overrides | centralize policy profiles |
-| auth mismatch | 401/403 bursts | credential sprawl | rotation schedule + scope minimization |
-| schema breakage | parser/validation errors | unmanaged upstream changes | contract tests per release |
-| retry storms | queue congestion | no backoff controls | jittered backoff + circuit breakers |
-| silent regressions | quality drop without alerts | weak baseline metrics | eval harness with thresholds |
-
-### Implementation Runbook
-
-1. Establish a reproducible baseline environment.
-2. Capture chapter-specific success criteria before changes.
-3. Implement minimal viable path with explicit interfaces.
-4. Add observability before expanding feature scope.
-5. Run deterministic tests for happy-path behavior.
-6. Inject failure scenarios for negative-path validation.
-7. Compare output quality against baseline snapshots.
-8. Promote through staged environments with rollback gates.
-9. Record operational lessons in release notes.
-
-### Quality Gate Checklist
-
-- [ ] chapter-level assumptions are explicit and testable
-- [ ] API/tool boundaries are documented with input/output examples
-- [ ] failure handling includes retry, timeout, and fallback policy
-- [ ] security controls include auth scopes and secret rotation plans
-- [ ] observability includes logs, metrics, traces, and alert thresholds
-- [ ] deployment guidance includes canary and rollback paths
-- [ ] docs include links to upstream sources and related tracks
-- [ ] post-release verification confirms expected behavior under load
-
-### Source Alignment
-
-- [Dyad README](https://github.com/dyad-sh/dyad/blob/main/README.md)
-- [Dyad Releases](https://github.com/dyad-sh/dyad/releases)
-- [Dyad Repository](https://github.com/dyad-sh/dyad)
-
-### Cross-Tutorial Connection Map
-
-- [bolt.diy Tutorial](../bolt-diy-tutorial/)
-- [Vercel AI SDK Tutorial](../vercel-ai-tutorial/)
-- [Cline Tutorial](../cline-tutorial/)
-- [Roo Code Tutorial](../roo-code-tutorial/)
-- [Chapter 1: Getting Started](01-getting-started.md)
-
-### Advanced Practice Exercises
-
-1. Build a minimal end-to-end implementation for `Chapter 4: Data Management`.
-2. Add instrumentation and measure baseline latency and error rate.
-3. Introduce one controlled failure and confirm graceful recovery.
-4. Add policy constraints and verify they are enforced consistently.
-5. Run a staged rollout and document rollback decision criteria.
-
-### Review Questions
-
-1. Which execution boundary matters most for this chapter and why?
-2. What signal detects regressions earliest in your environment?
-3. What tradeoff did you make between delivery speed and governance?
-4. How would you recover from the highest-impact failure mode?
-5. What must be automated before scaling to team-wide adoption?
-
-### Scenario Playbook 1: Chapter 4: Data Management
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 2: Chapter 4: Data Management
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 3: Chapter 4: Data Management
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 4: Chapter 4: Data Management
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 5: Chapter 4: Data Management
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 6: Chapter 4: Data Management
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 7: Chapter 4: Data Management
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 8: Chapter 4: Data Management
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 9: Chapter 4: Data Management
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 10: Chapter 4: Data Management
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 11: Chapter 4: Data Management
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 12: Chapter 4: Data Management
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 13: Chapter 4: Data Management
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 14: Chapter 4: Data Management
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 15: Chapter 4: Data Management
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 16: Chapter 4: Data Management
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 17: Chapter 4: Data Management
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 18: Chapter 4: Data Management
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 19: Chapter 4: Data Management
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 20: Chapter 4: Data Management
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 21: Chapter 4: Data Management
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 22: Chapter 4: Data Management
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 23: Chapter 4: Data Management
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 24: Chapter 4: Data Management
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 25: Chapter 4: Data Management
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 26: Chapter 4: Data Management
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 27: Chapter 4: Data Management
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 28: Chapter 4: Data Management
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 29: Chapter 4: Data Management
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 30: Chapter 4: Data Management
-
-- tutorial context: **Dyad Tutorial: Local-First AI App Building**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-## What Problem Does This Solve?
-
-Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for `user`, `functionality`, `validation` so behavior stays predictable as complexity grows.
-
-In practical terms, this chapter helps you avoid three common failures:
-
-- coupling core logic too tightly to one implementation path
-- missing the handoff boundaries between setup, execution, and validation
-- shipping changes without clear rollback or observability strategy
-
-After working through this chapter, you should be able to reason about `Chapter 4: Data Management` as an operating subsystem inside **Dyad Tutorial: Local-First AI App Building**, with explicit contracts for inputs, state transitions, and outputs.
-
-Use the implementation notes around `Implement`, `fields`, `email` as your checklist when adapting these patterns to your own repository.
-
-## How it Works Under the Hood
-
-Under the hood, `Chapter 4: Data Management` usually follows a repeatable control path:
-
-1. **Context bootstrap**: initialize runtime config and prerequisites for `user`.
-2. **Input normalization**: shape incoming data so `functionality` receives stable contracts.
-3. **Core execution**: run the main logic branch and propagate intermediate state through `validation`.
-4. **Policy and safety checks**: enforce limits, auth scopes, and failure boundaries.
-5. **Output composition**: return canonical result payloads for downstream consumers.
-6. **Operational telemetry**: emit logs/metrics needed for debugging and performance tuning.
-
-When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
-
-## Source Walkthrough
-
-Use the following upstream sources to verify implementation details while reading this chapter:
-
-- [Dyad README](https://github.com/dyad-sh/dyad/blob/main/README.md)
- Why it matters: authoritative reference on `Dyad README` (github.com).
-- [Dyad Releases](https://github.com/dyad-sh/dyad/releases)
- Why it matters: authoritative reference on `Dyad Releases` (github.com).
-- [Dyad Repository](https://github.com/dyad-sh/dyad)
- Why it matters: authoritative reference on `Dyad Repository` (github.com).
-
-Suggested trace strategy:
-- search upstream code for `user` and `functionality` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
-
-## Chapter Connections
-
-- [Tutorial Index](README.md)
-- [Previous Chapter: Chapter 3: Component Integration](03-component-integration.md)
-- [Next Chapter: Chapter 5: API Integration](05-api-integration.md)
-- [Main Catalog](../../README.md#-tutorial-catalog)
-- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
+## How These Components Connect
+
+```mermaid
+flowchart TD
+ A[Virtual filesystem layer] --> B{Operation}
+ B -->|Write| C[Buffer change in memory]
+ B -->|Read| D[Overlay on top of disk files]
+ C --> E[User reviews diff]
+ E -->|Accept| F[Flush to real filesystem]
+ E -->|Reject| G[Discard virtual changes]
+ D --> H[Consistent state for LLM context]
+```
diff --git a/tutorials/dyad-tutorial/05-api-integration.md b/tutorials/dyad-tutorial/05-api-integration.md
index d09255ca..7de0adbb 100644
--- a/tutorials/dyad-tutorial/05-api-integration.md
+++ b/tutorials/dyad-tutorial/05-api-integration.md
@@ -817,20 +817,26 @@ Under the hood, `Chapter 5: API Integration` usually follows a repeatable contro
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
-## Source Walkthrough
+## Source Code Walkthrough
-Use the following upstream sources to verify implementation details while reading this chapter:
+### `src/lib/chat.ts`
-- [Dyad README](https://github.com/dyad-sh/dyad/blob/main/README.md)
- Why it matters: authoritative reference on `Dyad README` (github.com).
-- [Dyad Releases](https://github.com/dyad-sh/dyad/releases)
- Why it matters: authoritative reference on `Dyad Releases` (github.com).
-- [Dyad Repository](https://github.com/dyad-sh/dyad)
- Why it matters: authoritative reference on `Dyad Repository` (github.com).
+The `createApp` function in [`src/lib/chat.ts`](https://github.com/dyad-sh/dyad/blob/main/src/lib/chat.ts) is the API integration entrypoint for creating new app projects via the IPC bridge:
-Suggested trace strategy:
-- search upstream code for `response` and `Error` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+```ts
+export async function createApp(
+ params: CreateAppParams,
+): Promise<CreateAppResult> {
+ try {
+ return await ipc.app.createApp(params);
+ } catch (error) {
+ console.error("[CHAT] Error creating app:", error);
+ throw error;
+ }
+}
+```
+
+All API calls between the renderer (React) and main (Electron) processes go through the `ipc` object from `src/ipc/types.ts`. This pattern ensures type safety across the process boundary and enables Dyad to run all AI generation locally without any external server.
## Chapter Connections
diff --git a/tutorials/dyad-tutorial/06-customization-styling.md b/tutorials/dyad-tutorial/06-customization-styling.md
index 2b20e73c..b9e3e14d 100644
--- a/tutorials/dyad-tutorial/06-customization-styling.md
+++ b/tutorials/dyad-tutorial/06-customization-styling.md
@@ -876,20 +876,19 @@ Under the hood, `Chapter 6: Customization and Styling` usually follows a repeata
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
-## Source Walkthrough
+## Source Code Walkthrough
-Use the following upstream sources to verify implementation details while reading this chapter:
+### `forge.config.ts`
-- [Dyad README](https://github.com/dyad-sh/dyad/blob/main/README.md)
- Why it matters: authoritative reference on `Dyad README` (github.com).
-- [Dyad Releases](https://github.com/dyad-sh/dyad/releases)
- Why it matters: authoritative reference on `Dyad Releases` (github.com).
-- [Dyad Repository](https://github.com/dyad-sh/dyad)
- Why it matters: authoritative reference on `Dyad Repository` (github.com).
+The `VitePlugin` and `FusesPlugin` configuration in [`forge.config.ts`](https://github.com/dyad-sh/dyad/blob/main/forge.config.ts) controls how the Electron app is packaged and which native capabilities are enabled. The `FuseV1Options` security fuses lock down the app for production distribution:
-Suggested trace strategy:
-- search upstream code for `dark` and `gray` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+```ts
+import { VitePlugin } from "@electron-forge/plugin-vite";
+import { FusesPlugin } from "@electron-forge/plugin-fuses";
+import { FuseV1Options, FuseVersion } from "@electron/fuses";
+```
+
+Dyad's UI customization system uses Tailwind CSS with the `components.json` shadcn/ui configuration. Theme tokens (colors, radii, fonts) are configured here and applied globally — changes propagate to all generated app UI components because Dyad scaffolds them with the same Tailwind config.
## Chapter Connections
diff --git a/tutorials/dyad-tutorial/07-testing-validation.md b/tutorials/dyad-tutorial/07-testing-validation.md
index a5f5677b..0b5aaf86 100644
--- a/tutorials/dyad-tutorial/07-testing-validation.md
+++ b/tutorials/dyad-tutorial/07-testing-validation.md
@@ -934,20 +934,30 @@ Under the hood, `Chapter 7: Testing and Validation` usually follows a repeatable
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
-## Source Walkthrough
+## Source Code Walkthrough
-Use the following upstream sources to verify implementation details while reading this chapter:
+### `playwright.config.ts`
-- [Dyad README](https://github.com/dyad-sh/dyad/blob/main/README.md)
- Why it matters: authoritative reference on `Dyad README` (github.com).
-- [Dyad Releases](https://github.com/dyad-sh/dyad/releases)
- Why it matters: authoritative reference on `Dyad Releases` (github.com).
-- [Dyad Repository](https://github.com/dyad-sh/dyad)
- Why it matters: authoritative reference on `Dyad Repository` (github.com).
+The `generateWebServerConfigs` function in [`playwright.config.ts`](https://github.com/dyad-sh/dyad/blob/main/playwright.config.ts) generates parallel fake LLM server configurations for E2E testing, one per Playwright worker:
-Suggested trace strategy:
-- search upstream code for `expect` and `name` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+```ts
+function generateWebServerConfigs(): PlaywrightTestConfig["webServer"] {
+ const configs: NonNullable<PlaywrightTestConfig["webServer"]> = [];
+
+ for (let i = 0; i < parallelism; i++) {
+ const port = FAKE_LLM_BASE_PORT + i;
+ configs.push({
+ command: `cd testing/fake-llm-server && npm run build && npm start -- --port=${port}`,
+ url: `http://localhost:${port}/health`,
+ reuseExistingServer: !process.env.CI,
+ });
+ }
+
+ return configs;
+}
+```
+
+The fake LLM server in `testing/fake-llm-server/` responds with deterministic outputs, allowing E2E tests to run without real API keys. Each worker gets its own server to avoid test interference.
## Chapter Connections
diff --git a/tutorials/dyad-tutorial/08-deployment-sharing.md b/tutorials/dyad-tutorial/08-deployment-sharing.md
index c84d29a4..43cb64e3 100644
--- a/tutorials/dyad-tutorial/08-deployment-sharing.md
+++ b/tutorials/dyad-tutorial/08-deployment-sharing.md
@@ -834,20 +834,41 @@ Under the hood, `Chapter 8: Deployment and Sharing` usually follows a repeatable
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
-## Source Walkthrough
+## Source Code Walkthrough
-Use the following upstream sources to verify implementation details while reading this chapter:
+### `forge.config.ts`
-- [Dyad README](https://github.com/dyad-sh/dyad/blob/main/README.md)
- Why it matters: authoritative reference on `Dyad README` (github.com).
-- [Dyad Releases](https://github.com/dyad-sh/dyad/releases)
- Why it matters: authoritative reference on `Dyad Releases` (github.com).
-- [Dyad Repository](https://github.com/dyad-sh/dyad)
- Why it matters: authoritative reference on `Dyad Repository` (github.com).
+The `ignore` function in [`forge.config.ts`](https://github.com/dyad-sh/dyad/blob/main/forge.config.ts) controls which files are bundled into the Electron distribution package:
-Suggested trace strategy:
-- search upstream code for `build` and `name` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+```ts
+// Based on https://github.com/electron/forge/blob/6b2d547a7216c30fde1e1fddd1118eee5d872945/packages/plugin/vite/src/VitePlugin.ts#L124
+const ignore = (file: string) => {
+ if (!file) return false;
+ // `file` always starts with `/`
+ if (file === "/node_modules") {
+ return false;
+ }
+ if (file.startsWith("/drizzle")) {
+ return false;
+ }
+ if (file.startsWith("/scaffold")) {
+ return false;
+ }
+ if (file.startsWith("/worker") && !file.startsWith("/workers")) {
+ return false;
+ }
+ if (file.startsWith("/node_modules/better-sqlite3")) {
+ return false;
+ }
+ if (file.startsWith("/node_modules/node-pty")) {
+ return false;
+ }
+ if (file.startsWith("/.vite")) {
+ return false;
+ }
+```
+
+This function is important because it defines which native modules and bundled assets (drizzle migrations, scaffold templates, worker scripts) are included in the packaged Electron app — controlling both bundle size and runtime correctness across Windows, macOS, and Linux installers produced by `MakerSquirrel`, `MakerZIP`, `MakerDeb`, and `MakerRpm`.
## Chapter Connections
diff --git a/tutorials/elizaos-tutorial/01-getting-started.md b/tutorials/elizaos-tutorial/01-getting-started.md
index 7e5d508c..8ac5c1fd 100644
--- a/tutorials/elizaos-tutorial/01-getting-started.md
+++ b/tutorials/elizaos-tutorial/01-getting-started.md
@@ -360,16 +360,29 @@ Under the hood, `Chapter 1: Getting Started with ElizaOS` usually follows a repe
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
-## Source Walkthrough
-
-Use the following upstream sources to verify implementation details while reading this chapter:
-
-- [ElizaOS](https://github.com/elizaOS/eliza)
- Why it matters: authoritative reference on `ElizaOS` (github.com).
+## Source Code Walkthrough
+
+### `packages/elizaos/src/commands/create.ts`
+
+The `create` command in [`packages/elizaos/src/commands/create.ts`](https://github.com/elizaOS/eliza/blob/develop/packages/elizaos/src/commands/create.ts) scaffolds new agent projects. It uses `@clack/prompts` for an interactive TUI that asks for project name, language (TypeScript, Python, Rust), and template category:
+
+```ts
+const LANGUAGE_NAMES: Record<string, string> = {
+ typescript: "TypeScript",
+ python: "Python",
+ rust: "Rust",
+ "rust-wasm": "Rust (WASM)",
+};
+
+const CATEGORY_ICONS: Record<string, string> = {
+ plugin: "🔧",
+ chat: "💬",
+ a2a: "🤝",
+ mcp: "🔌",
+};
+```
-Suggested trace strategy:
-- search upstream code for `elizaos` and `plugin` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+The scaffolded project structure includes an `AGENTS.md` character file, plugin configuration, and a platform connector entry point. Running `elizaos dev` starts the agent with hot-reload.
## Chapter Connections
diff --git a/tutorials/elizaos-tutorial/02-agent-runtime.md b/tutorials/elizaos-tutorial/02-agent-runtime.md
index 6ea1d6d3..94e9ef84 100644
--- a/tutorials/elizaos-tutorial/02-agent-runtime.md
+++ b/tutorials/elizaos-tutorial/02-agent-runtime.md
@@ -595,16 +595,23 @@ Under the hood, `Chapter 2: Agent Runtime` usually follows a repeatable control
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
-## Source Walkthrough
+## Source Code Walkthrough
-Use the following upstream sources to verify implementation details while reading this chapter:
+### `packages/elizaos/src/index.ts`
-- [ElizaOS](https://github.com/elizaOS/eliza)
- Why it matters: authoritative reference on `ElizaOS` (github.com).
+The public API of the elizaOS CLI in [`packages/elizaos/src/index.ts`](https://github.com/elizaOS/eliza/blob/develop/packages/elizaos/src/index.ts) exports the three core commands composing the agent runtime lifecycle:
-Suggested trace strategy:
-- search upstream code for `plugin` and `message` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+```ts
+/**
+ * elizaOS CLI - Public API
+ */
+
+export { create, info, version } from "./commands/index.js";
+export { loadManifest } from "./manifest.js";
+export type { Example, ExampleLanguage, ExamplesManifest } from "./types.js";
+```
+
+The `loadManifest` function resolves `examples-manifest.json`, which catalogs agent templates. The agent runtime loop (action → memory → response) is bootstrapped from the character file via `elizaos start`. The `daemon` package under `packages/daemon/` handles long-running agent process supervision.
## Chapter Connections
diff --git a/tutorials/elizaos-tutorial/03-character-system.md b/tutorials/elizaos-tutorial/03-character-system.md
index bcbf4cb9..0b8f47f2 100644
--- a/tutorials/elizaos-tutorial/03-character-system.md
+++ b/tutorials/elizaos-tutorial/03-character-system.md
@@ -470,16 +470,29 @@ Under the hood, `Chapter 3: Character System` usually follows a repeatable contr
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
-## Source Walkthrough
+## Source Code Walkthrough
-Use the following upstream sources to verify implementation details while reading this chapter:
+### `packages/elizaos/src/manifest.ts`
-- [ElizaOS](https://github.com/elizaOS/eliza)
- Why it matters: authoritative reference on `ElizaOS` (github.com).
+The `loadManifest` function in [`packages/elizaos/src/manifest.ts`](https://github.com/elizaOS/eliza/blob/develop/packages/elizaos/src/manifest.ts) resolves the `examples-manifest.json` that ships with the CLI — this manifest catalogs the available character/agent templates by language and category:
-Suggested trace strategy:
-- search upstream code for `plugin` and `elizaos` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+```ts
+export function loadManifest(): ExamplesManifest {
+ if (cachedManifest) {
+ return cachedManifest;
+ }
+
+ // Try to load from dist directory (when installed as package)
+ const distManifestPath = path.join(__dirname, "examples-manifest.json");
+ if (fs.existsSync(distManifestPath)) {
+ const content = fs.readFileSync(distManifestPath, "utf-8");
+ cachedManifest = JSON.parse(content) as ExamplesManifest;
+ return cachedManifest;
+ }
+}
+```
+
+Character files are JSON/YAML documents consumed by the agent runtime. The `ExamplesManifest` type in `packages/elizaos/src/types.ts` defines the schema with `languages`, `examples`, and per-example `category` fields that map to agent persona templates.
## Chapter Connections
diff --git a/tutorials/elizaos-tutorial/04-plugin-architecture.md b/tutorials/elizaos-tutorial/04-plugin-architecture.md
index 3b05a765..d7aaa49b 100644
--- a/tutorials/elizaos-tutorial/04-plugin-architecture.md
+++ b/tutorials/elizaos-tutorial/04-plugin-architecture.md
@@ -574,16 +574,28 @@ Under the hood, `Chapter 4: Plugin Architecture` usually follows a repeatable co
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
-## Source Walkthrough
-
-Use the following upstream sources to verify implementation details while reading this chapter:
-
-- [ElizaOS](https://github.com/elizaOS/eliza)
- Why it matters: authoritative reference on `ElizaOS` (github.com).
+## Source Code Walkthrough
+
+### `packages/elizaos/src/commands/create.ts`
+
+The `CATEGORY_ICONS` map in [`packages/elizaos/src/commands/create.ts`](https://github.com/elizaOS/eliza/blob/develop/packages/elizaos/src/commands/create.ts) enumerates the built-in plugin categories available when scaffolding a new plugin:
+
+```ts
+const CATEGORY_ICONS: Record<string, string> = {
+ plugin: "🔧",
+ chat: "💬",
+ "text-adventure": "🎮",
+ a2a: "🤝",
+ mcp: "🔌",
+ html: "📄",
+ react: "⚛️",
+ aws: "☁️",
+ gcp: "🌩️",
+ cloudflare: "🔶",
+};
+```
-Suggested trace strategy:
-- search upstream code for `runtime` and `name` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+Each plugin template under `packages/elizaos/examples/` provides a minimal TypeScript/Python/Rust stub with the required `ElizaPlugin` interface. Plugins register actions, evaluators, and providers — the three extension points of the elizaOS agent runtime.
## Chapter Connections
diff --git a/tutorials/elizaos-tutorial/05-memory-rag.md b/tutorials/elizaos-tutorial/05-memory-rag.md
index f15430bc..ba82f160 100644
--- a/tutorials/elizaos-tutorial/05-memory-rag.md
+++ b/tutorials/elizaos-tutorial/05-memory-rag.md
@@ -614,16 +614,29 @@ Under the hood, `Chapter 5: Memory & RAG` usually follows a repeatable control p
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
-## Source Walkthrough
+## Source Code Walkthrough
-Use the following upstream sources to verify implementation details while reading this chapter:
+### `packages/elizaos/src/manifest.ts`
-- [ElizaOS](https://github.com/elizaOS/eliza)
- Why it matters: authoritative reference on `ElizaOS` (github.com).
+The `getExamplesByLanguage` and `getAvailableLanguages` helpers in [`packages/elizaos/src/manifest.ts`](https://github.com/elizaOS/eliza/blob/develop/packages/elizaos/src/manifest.ts) show how elizaOS separates agent knowledge by language/runtime context:
-Suggested trace strategy:
-- search upstream code for `text` and `chunks` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+```ts
+export function getExamplesByLanguage(
+ language: string,
+): ExamplesManifest["examples"] {
+ const manifest = loadManifest();
+ return manifest.examples.filter((example) =>
+ example.languages.some((lang) => lang.language === language),
+ );
+}
+
+export function getAvailableLanguages(): string[] {
+ const manifest = loadManifest();
+ return manifest.languages;
+}
+```
+
+In the agent runtime, memory storage uses a vector database (PGLite by default, PostgreSQL in production) where each memory record contains the embedding, source text, and metadata. The `elizaos` agent retrieves context-relevant memories before generating a response, forming the RAG loop.
## Chapter Connections
diff --git a/tutorials/elizaos-tutorial/06-platform-connectors.md b/tutorials/elizaos-tutorial/06-platform-connectors.md
index b1a83359..6b15f05f 100644
--- a/tutorials/elizaos-tutorial/06-platform-connectors.md
+++ b/tutorials/elizaos-tutorial/06-platform-connectors.md
@@ -547,16 +547,33 @@ Under the hood, `Chapter 6: Platform Connectors` usually follows a repeatable co
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
-## Source Walkthrough
-
-Use the following upstream sources to verify implementation details while reading this chapter:
-
-- [ElizaOS](https://github.com/elizaOS/eliza)
- Why it matters: authoritative reference on `ElizaOS` (github.com).
+## Source Code Walkthrough
+
+### `packages/elizaos/src/commands/create.ts`
+
+Platform connector templates for Discord, Telegram, Twitter, and Web are available as project categories in [`packages/elizaos/src/commands/create.ts`](https://github.com/elizaOS/eliza/blob/develop/packages/elizaos/src/commands/create.ts). Each template includes the connector plugin registration and environment variable scaffolding:
+
+```ts
+const SKIP_PATTERNS = [
+ "node_modules",
+ ".git",
+ "target",
+ "__pycache__",
+ ".venv",
+ "dist",
+];
+
+function copyDir(src: string, dest: string): void {
+ fs.mkdirSync(dest, { recursive: true });
+ const entries = fs.readdirSync(src, { withFileTypes: true });
+ for (const entry of entries) {
+ if (shouldSkip(entry.name)) continue;
+ // copy template files
+ }
+}
+```
-Suggested trace strategy:
-- search upstream code for `text` and `content` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+Platform connectors in elizaOS are plugins that register a `Client` interface — the `elizaos start` command instantiates each configured client and wires it to the agent runtime's message handler.
## Chapter Connections
diff --git a/tutorials/elizaos-tutorial/07-multi-agent.md b/tutorials/elizaos-tutorial/07-multi-agent.md
index cba11e99..44931246 100644
--- a/tutorials/elizaos-tutorial/07-multi-agent.md
+++ b/tutorials/elizaos-tutorial/07-multi-agent.md
@@ -603,16 +603,17 @@ Under the hood, `Chapter 7: Multi-Agent Orchestration` usually follows a repeata
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
-## Source Walkthrough
+## Source Code Walkthrough
-Use the following upstream sources to verify implementation details while reading this chapter:
+### `packages/elizaos/src/commands/info.ts`
-- [ElizaOS](https://github.com/elizaOS/eliza)
- Why it matters: authoritative reference on `ElizaOS` (github.com).
+The `info` command in [`packages/elizaos/src/commands/info.ts`](https://github.com/elizaOS/eliza/blob/develop/packages/elizaos/src/commands/info.ts) exposes runtime metadata about the running elizaOS instance — including active agents, loaded plugins, and registered clients. This is the diagnostic entrypoint for multi-agent deployments:
-Suggested trace strategy:
-- search upstream code for `group` and `agent` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+```ts
+export { create, info, version } from "./commands/index.js";
+```
+
+The `a2a` (agent-to-agent) template category in the elizaOS manifest demonstrates how multiple agents communicate via the A2A protocol. Each agent runs as an independent process supervised by the `daemon` package, and agents communicate through a shared message bus or direct HTTP calls.
## Chapter Connections
diff --git a/tutorials/elizaos-tutorial/08-production-deployment.md b/tutorials/elizaos-tutorial/08-production-deployment.md
index 03952d50..9cdc760c 100644
--- a/tutorials/elizaos-tutorial/08-production-deployment.md
+++ b/tutorials/elizaos-tutorial/08-production-deployment.md
@@ -599,16 +599,29 @@ Under the hood, `Chapter 8: Production Deployment` usually follows a repeatable
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
-## Source Walkthrough
-
-Use the following upstream sources to verify implementation details while reading this chapter:
-
-- [ElizaOS](https://github.com/elizaOS/eliza)
- Why it matters: authoritative reference on `ElizaOS` (github.com).
+## Source Code Walkthrough
+
+### `packages/elizaos/src/commands/version.ts`
+
+The `version` command in [`packages/elizaos/src/commands/version.ts`](https://github.com/elizaOS/eliza/blob/develop/packages/elizaos/src/commands/version.ts) reads the elizaOS CLI version from `package.json`. In production deployments this is used for health checks and compatibility validation between the CLI and the agent runtime packages:
+
+```ts
+function getCliVersion(): string {
+ try {
+ const pkgPath = path.join(__dirname, "..", "..", "package.json");
+ const content = fs.readFileSync(pkgPath, "utf-8");
+ const pkg = JSON.parse(content) as { version: string };
+ return pkg.version;
+ } catch {
+ const distPkgPath = path.join(__dirname, "..", "..", "..", "package.json");
+ const content = fs.readFileSync(distPkgPath, "utf-8");
+ const pkg = JSON.parse(content) as { version: string };
+ return pkg.version;
+ }
+}
+```
-Suggested trace strategy:
-- search upstream code for `elizaos` and `wallet` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+Production elizaOS deployments use Docker containers built from the repo's `Dockerfile`. The `daemon` package manages process lifecycle, restart policies, and health monitoring for long-running agent instances.
## Chapter Connections
diff --git a/tutorials/everything-claude-code-tutorial/01-getting-started.md b/tutorials/everything-claude-code-tutorial/01-getting-started.md
index 65764e9a..80c18b04 100644
--- a/tutorials/everything-claude-code-tutorial/01-getting-started.md
+++ b/tutorials/everything-claude-code-tutorial/01-getting-started.md
@@ -52,170 +52,168 @@ You now have a functioning baseline configuration.
Next: [Chapter 2: Architecture and Component Topology](02-architecture-and-component-topology.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `scripts/claw.js`
+### `scripts/harness-audit.js`
-The `isValidSessionName` function in [`scripts/claw.js`](https://github.com/affaan-m/everything-claude-code/blob/HEAD/scripts/claw.js) handles a key part of this chapter's functionality:
+The `normalizeScope` function in [`scripts/harness-audit.js`](https://github.com/affaan-m/everything-claude-code/blob/HEAD/scripts/harness-audit.js) handles a key part of this chapter's functionality:
```js
-const DEFAULT_COMPACT_KEEP_TURNS = 20;
-
-function isValidSessionName(name) {
- return typeof name === 'string' && name.length > 0 && SESSION_NAME_RE.test(name);
-}
-
-function getClawDir() {
- return path.join(os.homedir(), '.claude', 'claw');
-}
-
-function getSessionPath(name) {
- return path.join(getClawDir(), `${name}.md`);
-}
+];
-function listSessions(dir) {
- const clawDir = dir || getClawDir();
- if (!fs.existsSync(clawDir)) return [];
- return fs.readdirSync(clawDir)
- .filter(f => f.endsWith('.md'))
- .map(f => f.replace(/\.md$/, ''));
-}
-
-function loadHistory(filePath) {
- try {
- return fs.readFileSync(filePath, 'utf8');
- } catch {
- return '';
+function normalizeScope(scope) {
+ const value = (scope || 'repo').toLowerCase();
+ if (!['repo', 'hooks', 'skills', 'commands', 'agents'].includes(value)) {
+ throw new Error(`Invalid scope: ${scope}`);
}
-}
-
-function appendTurn(filePath, role, content, timestamp) {
- const ts = timestamp || new Date().toISOString();
+ return value;
+}
+
+function parseArgs(argv) {
+ const args = argv.slice(2);
+ const parsed = {
+ scope: 'repo',
+ format: 'text',
+ help: false,
+ root: path.resolve(process.env.AUDIT_ROOT || process.cwd()),
+ };
+
+ for (let index = 0; index < args.length; index += 1) {
+ const arg = args[index];
+
+ if (arg === '--help' || arg === '-h') {
+ parsed.help = true;
+ continue;
+ }
+
+ if (arg === '--format') {
+ parsed.format = (args[index + 1] || '').toLowerCase();
+ index += 1;
+ continue;
+ }
```
This function is important because it defines how Everything Claude Code Tutorial: Production Configuration Patterns for Claude Code implements the patterns covered in this chapter.
-### `scripts/claw.js`
+### `scripts/harness-audit.js`
-The `getClawDir` function in [`scripts/claw.js`](https://github.com/affaan-m/everything-claude-code/blob/HEAD/scripts/claw.js) handles a key part of this chapter's functionality:
+The `parseArgs` function in [`scripts/harness-audit.js`](https://github.com/affaan-m/everything-claude-code/blob/HEAD/scripts/harness-audit.js) handles a key part of this chapter's functionality:
```js
}
-function getClawDir() {
- return path.join(os.homedir(), '.claude', 'claw');
-}
-
-function getSessionPath(name) {
- return path.join(getClawDir(), `${name}.md`);
-}
-
-function listSessions(dir) {
- const clawDir = dir || getClawDir();
- if (!fs.existsSync(clawDir)) return [];
- return fs.readdirSync(clawDir)
- .filter(f => f.endsWith('.md'))
- .map(f => f.replace(/\.md$/, ''));
-}
-
-function loadHistory(filePath) {
- try {
- return fs.readFileSync(filePath, 'utf8');
- } catch {
- return '';
- }
-}
-
-function appendTurn(filePath, role, content, timestamp) {
- const ts = timestamp || new Date().toISOString();
- const entry = `### [${ts}] ${role}\n${content}\n---\n`;
- fs.mkdirSync(path.dirname(filePath), { recursive: true });
- fs.appendFileSync(filePath, entry, 'utf8');
-}
+function parseArgs(argv) {
+ const args = argv.slice(2);
+ const parsed = {
+ scope: 'repo',
+ format: 'text',
+ help: false,
+ root: path.resolve(process.env.AUDIT_ROOT || process.cwd()),
+ };
+
+ for (let index = 0; index < args.length; index += 1) {
+ const arg = args[index];
+
+ if (arg === '--help' || arg === '-h') {
+ parsed.help = true;
+ continue;
+ }
+
+ if (arg === '--format') {
+ parsed.format = (args[index + 1] || '').toLowerCase();
+ index += 1;
+ continue;
+ }
+
+ if (arg === '--scope') {
+ parsed.scope = normalizeScope(args[index + 1]);
+ index += 1;
+ continue;
+ }
+
+ if (arg === '--root') {
```
This function is important because it defines how Everything Claude Code Tutorial: Production Configuration Patterns for Claude Code implements the patterns covered in this chapter.
-### `scripts/claw.js`
+### `scripts/harness-audit.js`
-The `getSessionPath` function in [`scripts/claw.js`](https://github.com/affaan-m/everything-claude-code/blob/HEAD/scripts/claw.js) handles a key part of this chapter's functionality:
+The `fileExists` function in [`scripts/harness-audit.js`](https://github.com/affaan-m/everything-claude-code/blob/HEAD/scripts/harness-audit.js) handles a key part of this chapter's functionality:
```js
}
-function getSessionPath(name) {
- return path.join(getClawDir(), `${name}.md`);
+function fileExists(rootDir, relativePath) {
+ return fs.existsSync(path.join(rootDir, relativePath));
}
-function listSessions(dir) {
- const clawDir = dir || getClawDir();
- if (!fs.existsSync(clawDir)) return [];
- return fs.readdirSync(clawDir)
- .filter(f => f.endsWith('.md'))
- .map(f => f.replace(/\.md$/, ''));
+function readText(rootDir, relativePath) {
+ return fs.readFileSync(path.join(rootDir, relativePath), 'utf8');
}
-function loadHistory(filePath) {
- try {
- return fs.readFileSync(filePath, 'utf8');
- } catch {
- return '';
+function countFiles(rootDir, relativeDir, extension) {
+ const dirPath = path.join(rootDir, relativeDir);
+ if (!fs.existsSync(dirPath)) {
+ return 0;
}
-}
-
-function appendTurn(filePath, role, content, timestamp) {
- const ts = timestamp || new Date().toISOString();
- const entry = `### [${ts}] ${role}\n${content}\n---\n`;
- fs.mkdirSync(path.dirname(filePath), { recursive: true });
- fs.appendFileSync(filePath, entry, 'utf8');
-}
-function normalizeSkillList(raw) {
- if (!raw) return [];
- if (Array.isArray(raw)) return raw.map(s => String(s).trim()).filter(Boolean);
+ const stack = [dirPath];
+ let count = 0;
+
+ while (stack.length > 0) {
+ const current = stack.pop();
+ const entries = fs.readdirSync(current, { withFileTypes: true });
+
+ for (const entry of entries) {
+ const nextPath = path.join(current, entry.name);
+ if (entry.isDirectory()) {
+ stack.push(nextPath);
+ } else if (!extension || entry.name.endsWith(extension)) {
+ count += 1;
+ }
+ }
+ }
```
This function is important because it defines how Everything Claude Code Tutorial: Production Configuration Patterns for Claude Code implements the patterns covered in this chapter.
-### `scripts/claw.js`
+### `scripts/harness-audit.js`
-The `listSessions` function in [`scripts/claw.js`](https://github.com/affaan-m/everything-claude-code/blob/HEAD/scripts/claw.js) handles a key part of this chapter's functionality:
+The `readText` function in [`scripts/harness-audit.js`](https://github.com/affaan-m/everything-claude-code/blob/HEAD/scripts/harness-audit.js) handles a key part of this chapter's functionality:
```js
}
-function listSessions(dir) {
- const clawDir = dir || getClawDir();
- if (!fs.existsSync(clawDir)) return [];
- return fs.readdirSync(clawDir)
- .filter(f => f.endsWith('.md'))
- .map(f => f.replace(/\.md$/, ''));
+function readText(rootDir, relativePath) {
+ return fs.readFileSync(path.join(rootDir, relativePath), 'utf8');
}
-function loadHistory(filePath) {
- try {
- return fs.readFileSync(filePath, 'utf8');
- } catch {
- return '';
+function countFiles(rootDir, relativeDir, extension) {
+ const dirPath = path.join(rootDir, relativeDir);
+ if (!fs.existsSync(dirPath)) {
+ return 0;
}
-}
-function appendTurn(filePath, role, content, timestamp) {
- const ts = timestamp || new Date().toISOString();
- const entry = `### [${ts}] ${role}\n${content}\n---\n`;
- fs.mkdirSync(path.dirname(filePath), { recursive: true });
- fs.appendFileSync(filePath, entry, 'utf8');
-}
+ const stack = [dirPath];
+ let count = 0;
+
+ while (stack.length > 0) {
+ const current = stack.pop();
+ const entries = fs.readdirSync(current, { withFileTypes: true });
+
+ for (const entry of entries) {
+ const nextPath = path.join(current, entry.name);
+ if (entry.isDirectory()) {
+ stack.push(nextPath);
+ } else if (!extension || entry.name.endsWith(extension)) {
+ count += 1;
+ }
+ }
+ }
-function normalizeSkillList(raw) {
- if (!raw) return [];
- if (Array.isArray(raw)) return raw.map(s => String(s).trim()).filter(Boolean);
- return String(raw).split(',').map(s => s.trim()).filter(Boolean);
+ return count;
}
-function loadECCContext(skillList) {
```
This function is important because it defines how Everything Claude Code Tutorial: Production Configuration Patterns for Claude Code implements the patterns covered in this chapter.
@@ -225,11 +223,11 @@ This function is important because it defines how Everything Claude Code Tutoria
```mermaid
flowchart TD
- A[isValidSessionName]
- B[getClawDir]
- C[getSessionPath]
- D[listSessions]
- E[loadHistory]
+ A[normalizeScope]
+ B[parseArgs]
+ C[fileExists]
+ D[readText]
+ E[countFiles]
A --> B
B --> C
C --> D
diff --git a/tutorials/everything-claude-code-tutorial/02-architecture-and-component-topology.md b/tutorials/everything-claude-code-tutorial/02-architecture-and-component-topology.md
index ea0c897f..2245f5ae 100644
--- a/tutorials/everything-claude-code-tutorial/02-architecture-and-component-topology.md
+++ b/tutorials/everything-claude-code-tutorial/02-architecture-and-component-topology.md
@@ -45,170 +45,168 @@ You now understand the component architecture and boundaries.
Next: [Chapter 3: Installation Modes and Rules Strategy](03-installation-modes-and-rules-strategy.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `scripts/claw.js`
+### `scripts/harness-audit.js`
-The `parseTurns` function in [`scripts/claw.js`](https://github.com/affaan-m/everything-claude-code/blob/HEAD/scripts/claw.js) handles a key part of this chapter's functionality:
+The `summarizeCategoryScores` function in [`scripts/harness-audit.js`](https://github.com/affaan-m/everything-claude-code/blob/HEAD/scripts/harness-audit.js) handles a key part of this chapter's functionality:
```js
}
-function parseTurns(history) {
- const turns = [];
- const regex = /### \[([^\]]+)\] ([^\n]+)\n([\s\S]*?)\n---\n/g;
- let match;
- while ((match = regex.exec(history)) !== null) {
- turns.push({ timestamp: match[1], role: match[2], content: match[3] });
+function summarizeCategoryScores(checks) {
+ const scores = {};
+ for (const category of CATEGORIES) {
+ const inCategory = checks.filter(check => check.category === category);
+ const max = inCategory.reduce((sum, check) => sum + check.points, 0);
+ const earned = inCategory
+ .filter(check => check.pass)
+ .reduce((sum, check) => sum + check.points, 0);
+
+ const normalized = max === 0 ? 0 : Math.round((earned / max) * 10);
+ scores[category] = {
+ score: normalized,
+ earned,
+ max,
+ };
}
- return turns;
-}
-function estimateTokenCount(text) {
- return Math.ceil((text || '').length / 4);
+ return scores;
}
-function getSessionMetrics(filePath) {
- const history = loadHistory(filePath);
- const turns = parseTurns(history);
- const charCount = history.length;
- const tokenEstimate = estimateTokenCount(history);
- const userTurns = turns.filter(t => t.role === 'User').length;
- const assistantTurns = turns.filter(t => t.role === 'Assistant').length;
-
- return {
- turns: turns.length,
- userTurns,
- assistantTurns,
- charCount,
- tokenEstimate,
- };
-}
+function buildReport(scope, options = {}) {
+ const rootDir = path.resolve(options.rootDir || process.cwd());
+ const targetMode = options.targetMode || detectTargetMode(rootDir);
+ const checks = (targetMode === 'repo' ? getRepoChecks(rootDir) : getConsumerChecks(rootDir))
+ .filter(check => check.scopes.includes(scope));
+ const categoryScores = summarizeCategoryScores(checks);
+ const maxScore = checks.reduce((sum, check) => sum + check.points, 0);
+ const overallScore = checks
+ .filter(check => check.pass)
+ .reduce((sum, check) => sum + check.points, 0);
```
This function is important because it defines how Everything Claude Code Tutorial: Production Configuration Patterns for Claude Code implements the patterns covered in this chapter.
-### `scripts/claw.js`
+### `scripts/harness-audit.js`
-The `estimateTokenCount` function in [`scripts/claw.js`](https://github.com/affaan-m/everything-claude-code/blob/HEAD/scripts/claw.js) handles a key part of this chapter's functionality:
+The `buildReport` function in [`scripts/harness-audit.js`](https://github.com/affaan-m/everything-claude-code/blob/HEAD/scripts/harness-audit.js) handles a key part of this chapter's functionality:
```js
}
-function estimateTokenCount(text) {
- return Math.ceil((text || '').length / 4);
-}
-
-function getSessionMetrics(filePath) {
- const history = loadHistory(filePath);
- const turns = parseTurns(history);
- const charCount = history.length;
- const tokenEstimate = estimateTokenCount(history);
- const userTurns = turns.filter(t => t.role === 'User').length;
- const assistantTurns = turns.filter(t => t.role === 'Assistant').length;
+function buildReport(scope, options = {}) {
+ const rootDir = path.resolve(options.rootDir || process.cwd());
+ const targetMode = options.targetMode || detectTargetMode(rootDir);
+ const checks = (targetMode === 'repo' ? getRepoChecks(rootDir) : getConsumerChecks(rootDir))
+ .filter(check => check.scopes.includes(scope));
+ const categoryScores = summarizeCategoryScores(checks);
+ const maxScore = checks.reduce((sum, check) => sum + check.points, 0);
+ const overallScore = checks
+ .filter(check => check.pass)
+ .reduce((sum, check) => sum + check.points, 0);
+
+ const failedChecks = checks.filter(check => !check.pass);
+ const topActions = failedChecks
+ .sort((left, right) => right.points - left.points)
+ .slice(0, 3)
+ .map(check => ({
+ action: check.fix,
+ path: check.path,
+ category: check.category,
+ points: check.points,
+ }));
return {
- turns: turns.length,
- userTurns,
- assistantTurns,
- charCount,
- tokenEstimate,
- };
-}
-
-function searchSessions(query, dir) {
- const q = String(query || '').toLowerCase().trim();
- if (!q) return [];
-
- const sessionDir = dir || getClawDir();
- const sessions = listSessions(sessionDir);
- const results = [];
- for (const name of sessions) {
- const p = path.join(sessionDir, `${name}.md`);
+ scope,
+ root_dir: rootDir,
+ target_mode: targetMode,
+ deterministic: true,
+ rubric_version: '2026-03-30',
+ overall_score: overallScore,
+ max_score: maxScore,
```
This function is important because it defines how Everything Claude Code Tutorial: Production Configuration Patterns for Claude Code implements the patterns covered in this chapter.
-### `scripts/claw.js`
+### `scripts/harness-audit.js`
-The `getSessionMetrics` function in [`scripts/claw.js`](https://github.com/affaan-m/everything-claude-code/blob/HEAD/scripts/claw.js) handles a key part of this chapter's functionality:
+The `printText` function in [`scripts/harness-audit.js`](https://github.com/affaan-m/everything-claude-code/blob/HEAD/scripts/harness-audit.js) handles a key part of this chapter's functionality:
```js
}
-function getSessionMetrics(filePath) {
- const history = loadHistory(filePath);
- const turns = parseTurns(history);
- const charCount = history.length;
- const tokenEstimate = estimateTokenCount(history);
- const userTurns = turns.filter(t => t.role === 'User').length;
- const assistantTurns = turns.filter(t => t.role === 'Assistant').length;
+function printText(report) {
+ console.log(`Harness Audit (${report.scope}, ${report.target_mode}): ${report.overall_score}/${report.max_score}`);
+ console.log(`Root: ${report.root_dir}`);
+ console.log('');
- return {
- turns: turns.length,
- userTurns,
- assistantTurns,
- charCount,
- tokenEstimate,
- };
-}
+ for (const category of CATEGORIES) {
+ const data = report.categories[category];
+ if (!data || data.max === 0) {
+ continue;
+ }
+
+ console.log(`- ${category}: ${data.score}/10 (${data.earned}/${data.max} pts)`);
+ }
-function searchSessions(query, dir) {
- const q = String(query || '').toLowerCase().trim();
- if (!q) return [];
+ const failed = report.checks.filter(check => !check.pass);
+ console.log('');
+ console.log(`Checks: ${report.checks.length} total, ${failed.length} failing`);
- const sessionDir = dir || getClawDir();
- const sessions = listSessions(sessionDir);
- const results = [];
- for (const name of sessions) {
- const p = path.join(sessionDir, `${name}.md`);
- const content = loadHistory(p);
- if (!content) continue;
+ if (failed.length > 0) {
+ console.log('');
+ console.log('Top 3 Actions:');
+ report.top_actions.forEach((action, index) => {
+ console.log(`${index + 1}) [${action.category}] ${action.action} (${action.path})`);
+ });
+ }
+}
- const idx = content.toLowerCase().indexOf(q);
+function showHelp(exitCode = 0) {
+ console.log(`
+Usage: node scripts/harness-audit.js [scope] [--scope <repo|hooks|skills|commands|agents>] [--format <text|json>]
```
This function is important because it defines how Everything Claude Code Tutorial: Production Configuration Patterns for Claude Code implements the patterns covered in this chapter.
-### `scripts/claw.js`
+### `scripts/harness-audit.js`
-The `searchSessions` function in [`scripts/claw.js`](https://github.com/affaan-m/everything-claude-code/blob/HEAD/scripts/claw.js) handles a key part of this chapter's functionality:
+The `showHelp` function in [`scripts/harness-audit.js`](https://github.com/affaan-m/everything-claude-code/blob/HEAD/scripts/harness-audit.js) handles a key part of this chapter's functionality:
```js
}
-function searchSessions(query, dir) {
- const q = String(query || '').toLowerCase().trim();
- if (!q) return [];
-
- const sessionDir = dir || getClawDir();
- const sessions = listSessions(sessionDir);
- const results = [];
- for (const name of sessions) {
- const p = path.join(sessionDir, `${name}.md`);
- const content = loadHistory(p);
- if (!content) continue;
-
- const idx = content.toLowerCase().indexOf(q);
- if (idx >= 0) {
- const start = Math.max(0, idx - 40);
- const end = Math.min(content.length, idx + q.length + 40);
- const snippet = content.slice(start, end).replace(/\n/g, ' ');
- results.push({ session: name, snippet });
- }
- }
- return results;
+function showHelp(exitCode = 0) {
+ console.log(`
+Usage: node scripts/harness-audit.js [scope] [--scope <repo|hooks|skills|commands|agents>] [--format <text|json>]
+ [--root <path>]
+
+Deterministic harness audit based on explicit file/rule checks.
+Audits the current working directory by default and auto-detects ECC repo mode vs consumer-project mode.
+`);
+ process.exit(exitCode);
}
-function compactSession(filePath, keepTurns = DEFAULT_COMPACT_KEEP_TURNS) {
- const history = loadHistory(filePath);
- if (!history) return false;
+function main() {
+ try {
+ const args = parseArgs(process.argv);
- const turns = parseTurns(history);
- if (turns.length <= keepTurns) return false;
+ if (args.help) {
+ showHelp(0);
+ return;
+ }
+ const report = buildReport(args.scope, { rootDir: args.root });
+
+ if (args.format === 'json') {
+ console.log(JSON.stringify(report, null, 2));
+ } else {
+ printText(report);
+ }
+ } catch (error) {
+ console.error(`Error: ${error.message}`);
+ process.exit(1);
```
This function is important because it defines how Everything Claude Code Tutorial: Production Configuration Patterns for Claude Code implements the patterns covered in this chapter.
@@ -218,11 +216,11 @@ This function is important because it defines how Everything Claude Code Tutoria
```mermaid
flowchart TD
- A[parseTurns]
- B[estimateTokenCount]
- C[getSessionMetrics]
- D[searchSessions]
- E[compactSession]
+ A[summarizeCategoryScores]
+ B[buildReport]
+ C[printText]
+ D[showHelp]
+ E[main]
A --> B
B --> C
C --> D
diff --git a/tutorials/everything-claude-code-tutorial/03-installation-modes-and-rules-strategy.md b/tutorials/everything-claude-code-tutorial/03-installation-modes-and-rules-strategy.md
index 25508ddf..fe132431 100644
--- a/tutorials/everything-claude-code-tutorial/03-installation-modes-and-rules-strategy.md
+++ b/tutorials/everything-claude-code-tutorial/03-installation-modes-and-rules-strategy.md
@@ -43,170 +43,168 @@ You now have a reproducible installation strategy.
Next: [Chapter 4: Agents, Skills, and Command Orchestration](04-agents-skills-and-command-orchestration.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `scripts/claw.js`
-The `handleSessions` function in [`scripts/claw.js`](https://github.com/affaan-m/everything-claude-code/blob/HEAD/scripts/claw.js) handles a key part of this chapter's functionality:
+The `loadECCContext` function in [`scripts/claw.js`](https://github.com/affaan-m/everything-claude-code/blob/HEAD/scripts/claw.js) handles a key part of this chapter's functionality:
```js
}
-function handleSessions(dir) {
- const sessions = listSessions(dir);
- if (sessions.length === 0) {
- console.log('(no sessions)');
- return;
+function loadECCContext(skillList) {
+ const requested = normalizeSkillList(skillList !== undefined ? skillList : process.env.CLAW_SKILLS || '');
+ if (requested.length === 0) return '';
+
+ const chunks = [];
+ for (const name of requested) {
+ const skillPath = path.join(process.cwd(), 'skills', name, 'SKILL.md');
+ try {
+ chunks.push(fs.readFileSync(skillPath, 'utf8'));
+ } catch {
+ // Skip missing skills silently to keep REPL usable.
+ }
}
- console.log('Sessions:');
- for (const s of sessions) {
- console.log(` - ${s}`);
- }
+ return chunks.join('\n\n');
}
-function handleHelp() {
- console.log('NanoClaw REPL Commands:');
- console.log(' /help Show this help');
- console.log(' /clear Clear current session history');
- console.log(' /history Print full conversation history');
- console.log(' /sessions List saved sessions');
- console.log(' /model [name] Show/set model');
- console.log(' /load <skill-name> Load a skill into active context');
- console.log(' /branch <session-name> Branch current session into a new session');
- console.log(' /search <query> Search query across sessions');
- console.log(' /compact Keep recent turns, compact older context');
- console.log(' /export <md|json|txt> [path] Export current session');
- console.log(' /metrics Show session metrics');
- console.log(' exit Quit the REPL');
+function buildPrompt(systemPrompt, history, userMessage) {
+ const parts = [];
+ if (systemPrompt) parts.push(`=== SYSTEM CONTEXT ===\n${systemPrompt}\n`);
+ if (history) parts.push(`=== CONVERSATION HISTORY ===\n${history}\n`);
+ parts.push(`=== USER MESSAGE ===\n${userMessage}`);
+ return parts.join('\n');
}
-function main() {
+function askClaude(systemPrompt, history, userMessage, model) {
+ const fullPrompt = buildPrompt(systemPrompt, history, userMessage);
+ const args = [];
+ if (model) {
+ args.push('--model', model);
```
This function is important because it defines how Everything Claude Code Tutorial: Production Configuration Patterns for Claude Code implements the patterns covered in this chapter.
### `scripts/claw.js`
-The `handleHelp` function in [`scripts/claw.js`](https://github.com/affaan-m/everything-claude-code/blob/HEAD/scripts/claw.js) handles a key part of this chapter's functionality:
+The `buildPrompt` function in [`scripts/claw.js`](https://github.com/affaan-m/everything-claude-code/blob/HEAD/scripts/claw.js) handles a key part of this chapter's functionality:
```js
}
-function handleHelp() {
- console.log('NanoClaw REPL Commands:');
- console.log(' /help Show this help');
- console.log(' /clear Clear current session history');
- console.log(' /history Print full conversation history');
- console.log(' /sessions List saved sessions');
- console.log(' /model [name] Show/set model');
- console.log(' /load <skill-name> Load a skill into active context');
- console.log(' /branch <session-name> Branch current session into a new session');
- console.log(' /search <query> Search query across sessions');
- console.log(' /compact Keep recent turns, compact older context');
- console.log(' /export <md|json|txt> [path] Export current session');
- console.log(' /metrics Show session metrics');
- console.log(' exit Quit the REPL');
+function buildPrompt(systemPrompt, history, userMessage) {
+ const parts = [];
+ if (systemPrompt) parts.push(`=== SYSTEM CONTEXT ===\n${systemPrompt}\n`);
+ if (history) parts.push(`=== CONVERSATION HISTORY ===\n${history}\n`);
+ parts.push(`=== USER MESSAGE ===\n${userMessage}`);
+ return parts.join('\n');
}
-function main() {
- const initialSessionName = process.env.CLAW_SESSION || 'default';
- if (!isValidSessionName(initialSessionName)) {
- console.error(`Error: Invalid session name "${initialSessionName}". Use alphanumeric characters and hyphens only.`);
- process.exit(1);
+function askClaude(systemPrompt, history, userMessage, model) {
+ const fullPrompt = buildPrompt(systemPrompt, history, userMessage);
+ const args = [];
+ if (model) {
+ args.push('--model', model);
}
+ args.push('-p', fullPrompt);
- fs.mkdirSync(getClawDir(), { recursive: true });
+ const result = spawnSync('claude', args, {
+ encoding: 'utf8',
+ stdio: ['pipe', 'pipe', 'pipe'],
+ env: { ...process.env, CLAUDECODE: '' },
+ timeout: 300000,
+ });
- const state = {
- sessionName: initialSessionName,
- sessionPath: getSessionPath(initialSessionName),
- model: DEFAULT_MODEL,
- skills: normalizeSkillList(process.env.CLAW_SKILLS || ''),
+ if (result.error) {
+ return `[Error: ${result.error.message}]`;
+ }
+
+ if (result.status !== 0 && result.stderr) {
+ return `[Error: claude exited with code ${result.status}: ${result.stderr.trim()}]`;
+ }
```
This function is important because it defines how Everything Claude Code Tutorial: Production Configuration Patterns for Claude Code implements the patterns covered in this chapter.
### `scripts/claw.js`
-The `main` function in [`scripts/claw.js`](https://github.com/affaan-m/everything-claude-code/blob/HEAD/scripts/claw.js) handles a key part of this chapter's functionality:
+The `askClaude` function in [`scripts/claw.js`](https://github.com/affaan-m/everything-claude-code/blob/HEAD/scripts/claw.js) handles a key part of this chapter's functionality:
```js
}
-function main() {
- const initialSessionName = process.env.CLAW_SESSION || 'default';
- if (!isValidSessionName(initialSessionName)) {
- console.error(`Error: Invalid session name "${initialSessionName}". Use alphanumeric characters and hyphens only.`);
- process.exit(1);
+function askClaude(systemPrompt, history, userMessage, model) {
+ const fullPrompt = buildPrompt(systemPrompt, history, userMessage);
+ const args = [];
+ if (model) {
+ args.push('--model', model);
}
+ args.push('-p', fullPrompt);
- fs.mkdirSync(getClawDir(), { recursive: true });
+ const result = spawnSync('claude', args, {
+ encoding: 'utf8',
+ stdio: ['pipe', 'pipe', 'pipe'],
+ env: { ...process.env, CLAUDECODE: '' },
+ timeout: 300000,
+ });
- const state = {
- sessionName: initialSessionName,
- sessionPath: getSessionPath(initialSessionName),
- model: DEFAULT_MODEL,
- skills: normalizeSkillList(process.env.CLAW_SKILLS || ''),
- };
-
- let eccContext = loadECCContext(state.skills);
-
- const loadedCount = state.skills.filter(skillExists).length;
+ if (result.error) {
+ return `[Error: ${result.error.message}]`;
+ }
- console.log(`NanoClaw v2 — Session: ${state.sessionName}`);
- console.log(`Model: ${state.model}`);
- if (loadedCount > 0) {
- console.log(`Loaded ${loadedCount} skill(s) as context.`);
+ if (result.status !== 0 && result.stderr) {
+ return `[Error: claude exited with code ${result.status}: ${result.stderr.trim()}]`;
}
- console.log('Type /help for commands, exit to quit.\n');
- const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+ return (result.stdout || '').trim();
+}
- const prompt = () => {
+function parseTurns(history) {
+ const turns = [];
+ const regex = /### \[([^\]]+)\] ([^\n]+)\n([\s\S]*?)\n---\n/g;
+ let match;
```
This function is important because it defines how Everything Claude Code Tutorial: Production Configuration Patterns for Claude Code implements the patterns covered in this chapter.
-### `scripts/harness-audit.js`
+### `scripts/claw.js`
-The `normalizeScope` function in [`scripts/harness-audit.js`](https://github.com/affaan-m/everything-claude-code/blob/HEAD/scripts/harness-audit.js) handles a key part of this chapter's functionality:
+The `parseTurns` function in [`scripts/claw.js`](https://github.com/affaan-m/everything-claude-code/blob/HEAD/scripts/claw.js) handles a key part of this chapter's functionality:
```js
-];
+}
-function normalizeScope(scope) {
- const value = (scope || 'repo').toLowerCase();
- if (!['repo', 'hooks', 'skills', 'commands', 'agents'].includes(value)) {
- throw new Error(`Invalid scope: ${scope}`);
+function parseTurns(history) {
+ const turns = [];
+ const regex = /### \[([^\]]+)\] ([^\n]+)\n([\s\S]*?)\n---\n/g;
+ let match;
+ while ((match = regex.exec(history)) !== null) {
+ turns.push({ timestamp: match[1], role: match[2], content: match[3] });
}
- return value;
+ return turns;
}
-function parseArgs(argv) {
- const args = argv.slice(2);
- const parsed = {
- scope: 'repo',
- format: 'text',
- help: false,
- };
-
- for (let index = 0; index < args.length; index += 1) {
- const arg = args[index];
-
- if (arg === '--help' || arg === '-h') {
- parsed.help = true;
- continue;
- }
-
- if (arg === '--format') {
- parsed.format = (args[index + 1] || '').toLowerCase();
- index += 1;
- continue;
- }
+function estimateTokenCount(text) {
+ return Math.ceil((text || '').length / 4);
+}
+function getSessionMetrics(filePath) {
+ const history = loadHistory(filePath);
+ const turns = parseTurns(history);
+ const charCount = history.length;
+ const tokenEstimate = estimateTokenCount(history);
+ const userTurns = turns.filter(t => t.role === 'User').length;
+ const assistantTurns = turns.filter(t => t.role === 'Assistant').length;
+
+ return {
+ turns: turns.length,
+ userTurns,
+ assistantTurns,
+ charCount,
+ tokenEstimate,
+ };
+}
```
This function is important because it defines how Everything Claude Code Tutorial: Production Configuration Patterns for Claude Code implements the patterns covered in this chapter.
@@ -216,11 +214,11 @@ This function is important because it defines how Everything Claude Code Tutoria
```mermaid
flowchart TD
- A[handleSessions]
- B[handleHelp]
- C[main]
- D[normalizeScope]
- E[parseArgs]
+ A[loadECCContext]
+ B[buildPrompt]
+ C[askClaude]
+ D[parseTurns]
+ E[estimateTokenCount]
A --> B
B --> C
C --> D
diff --git a/tutorials/everything-claude-code-tutorial/04-agents-skills-and-command-orchestration.md b/tutorials/everything-claude-code-tutorial/04-agents-skills-and-command-orchestration.md
index 7c345e39..3766247c 100644
--- a/tutorials/everything-claude-code-tutorial/04-agents-skills-and-command-orchestration.md
+++ b/tutorials/everything-claude-code-tutorial/04-agents-skills-and-command-orchestration.md
@@ -43,170 +43,168 @@ You now have a practical command/agent orchestration baseline.
Next: [Chapter 5: Hooks, MCP, and Continuous Learning Loops](05-hooks-mcp-and-continuous-learning-loops.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `scripts/harness-audit.js`
+### `scripts/claw.js`
-The `summarizeCategoryScores` function in [`scripts/harness-audit.js`](https://github.com/affaan-m/everything-claude-code/blob/HEAD/scripts/harness-audit.js) handles a key part of this chapter's functionality:
+The `handleHistory` function in [`scripts/claw.js`](https://github.com/affaan-m/everything-claude-code/blob/HEAD/scripts/claw.js) handles a key part of this chapter's functionality:
```js
}
-function summarizeCategoryScores(checks) {
- const scores = {};
- for (const category of CATEGORIES) {
- const inCategory = checks.filter(check => check.category === category);
- const max = inCategory.reduce((sum, check) => sum + check.points, 0);
- const earned = inCategory
- .filter(check => check.pass)
- .reduce((sum, check) => sum + check.points, 0);
-
- const normalized = max === 0 ? 0 : Math.round((earned / max) * 10);
- scores[category] = {
- score: normalized,
- earned,
- max,
- };
+function handleHistory(sessionPath) {
+ const history = loadHistory(sessionPath);
+ if (!history) {
+ console.log('(no history)');
+ return;
}
-
- return scores;
+ console.log(history);
}
-function buildReport(scope) {
- const checks = getChecks().filter(check => check.scopes.includes(scope));
- const categoryScores = summarizeCategoryScores(checks);
- const maxScore = checks.reduce((sum, check) => sum + check.points, 0);
- const overallScore = checks
- .filter(check => check.pass)
- .reduce((sum, check) => sum + check.points, 0);
+function handleSessions(dir) {
+ const sessions = listSessions(dir);
+ if (sessions.length === 0) {
+ console.log('(no sessions)');
+ return;
+ }
- const failedChecks = checks.filter(check => !check.pass);
- const topActions = failedChecks
+ console.log('Sessions:');
+ for (const s of sessions) {
+ console.log(` - ${s}`);
+ }
+}
+
+function handleHelp() {
+ console.log('NanoClaw REPL Commands:');
+ console.log(' /help Show this help');
+ console.log(' /clear Clear current session history');
+ console.log(' /history Print full conversation history');
+ console.log(' /sessions List saved sessions');
+ console.log(' /model [name] Show/set model');
+ console.log(' /load <skill-name> Load a skill into active context');
```
This function is important because it defines how Everything Claude Code Tutorial: Production Configuration Patterns for Claude Code implements the patterns covered in this chapter.
-### `scripts/harness-audit.js`
+### `scripts/claw.js`
-The `buildReport` function in [`scripts/harness-audit.js`](https://github.com/affaan-m/everything-claude-code/blob/HEAD/scripts/harness-audit.js) handles a key part of this chapter's functionality:
+The `handleSessions` function in [`scripts/claw.js`](https://github.com/affaan-m/everything-claude-code/blob/HEAD/scripts/claw.js) handles a key part of this chapter's functionality:
```js
}
-function buildReport(scope) {
- const checks = getChecks().filter(check => check.scopes.includes(scope));
- const categoryScores = summarizeCategoryScores(checks);
- const maxScore = checks.reduce((sum, check) => sum + check.points, 0);
- const overallScore = checks
- .filter(check => check.pass)
- .reduce((sum, check) => sum + check.points, 0);
-
- const failedChecks = checks.filter(check => !check.pass);
- const topActions = failedChecks
- .sort((left, right) => right.points - left.points)
- .slice(0, 3)
- .map(check => ({
- action: check.fix,
- path: check.path,
- category: check.category,
- points: check.points,
- }));
-
- return {
- scope,
- deterministic: true,
- rubric_version: '2026-03-16',
- overall_score: overallScore,
- max_score: maxScore,
- categories: categoryScores,
- checks: checks.map(check => ({
- id: check.id,
- category: check.category,
- points: check.points,
+function handleSessions(dir) {
+ const sessions = listSessions(dir);
+ if (sessions.length === 0) {
+ console.log('(no sessions)');
+ return;
+ }
+
+ console.log('Sessions:');
+ for (const s of sessions) {
+ console.log(` - ${s}`);
+ }
+}
+
+function handleHelp() {
+ console.log('NanoClaw REPL Commands:');
+ console.log(' /help Show this help');
+ console.log(' /clear Clear current session history');
+ console.log(' /history Print full conversation history');
+ console.log(' /sessions List saved sessions');
+ console.log(' /model [name] Show/set model');
+ console.log(' /load <skill-name> Load a skill into active context');
+ console.log(' /branch <session-name> Branch current session into a new session');
+ console.log(' /search <query> Search query across sessions');
+ console.log(' /compact Keep recent turns, compact older context');
+ console.log(' /export <md|json|txt> [path] Export current session');
+ console.log(' /metrics Show session metrics');
+ console.log(' exit Quit the REPL');
+}
+
+function main() {
```
This function is important because it defines how Everything Claude Code Tutorial: Production Configuration Patterns for Claude Code implements the patterns covered in this chapter.
-### `scripts/harness-audit.js`
+### `scripts/claw.js`
-The `printText` function in [`scripts/harness-audit.js`](https://github.com/affaan-m/everything-claude-code/blob/HEAD/scripts/harness-audit.js) handles a key part of this chapter's functionality:
+The `handleHelp` function in [`scripts/claw.js`](https://github.com/affaan-m/everything-claude-code/blob/HEAD/scripts/claw.js) handles a key part of this chapter's functionality:
```js
}
-function printText(report) {
- console.log(`Harness Audit (${report.scope}): ${report.overall_score}/${report.max_score}`);
- console.log('');
-
- for (const category of CATEGORIES) {
- const data = report.categories[category];
- if (!data || data.max === 0) {
- continue;
- }
-
- console.log(`- ${category}: ${data.score}/10 (${data.earned}/${data.max} pts)`);
- }
-
- const failed = report.checks.filter(check => !check.pass);
- console.log('');
- console.log(`Checks: ${report.checks.length} total, ${failed.length} failing`);
+function handleHelp() {
+ console.log('NanoClaw REPL Commands:');
+ console.log(' /help Show this help');
+ console.log(' /clear Clear current session history');
+ console.log(' /history Print full conversation history');
+ console.log(' /sessions List saved sessions');
+ console.log(' /model [name] Show/set model');
+ console.log(' /load <skill-name> Load a skill into active context');
+ console.log(' /branch <session-name> Branch current session into a new session');
+ console.log(' /search <query> Search query across sessions');
+ console.log(' /compact Keep recent turns, compact older context');
+ console.log(' /export <md|json|txt> [path] Export current session');
+ console.log(' /metrics Show session metrics');
+ console.log(' exit Quit the REPL');
+}
- if (failed.length > 0) {
- console.log('');
- console.log('Top 3 Actions:');
- report.top_actions.forEach((action, index) => {
- console.log(`${index + 1}) [${action.category}] ${action.action} (${action.path})`);
- });
+function main() {
+ const initialSessionName = process.env.CLAW_SESSION || 'default';
+ if (!isValidSessionName(initialSessionName)) {
+ console.error(`Error: Invalid session name "${initialSessionName}". Use alphanumeric characters and hyphens only.`);
+ process.exit(1);
}
-}
-function showHelp(exitCode = 0) {
- console.log(`
-Usage: node scripts/harness-audit.js [scope] [--scope <repo|hooks|skills|commands|agents>] [--format <text|json>]
+ fs.mkdirSync(getClawDir(), { recursive: true });
+ const state = {
+ sessionName: initialSessionName,
+ sessionPath: getSessionPath(initialSessionName),
+ model: DEFAULT_MODEL,
+ skills: normalizeSkillList(process.env.CLAW_SKILLS || ''),
```
This function is important because it defines how Everything Claude Code Tutorial: Production Configuration Patterns for Claude Code implements the patterns covered in this chapter.
-### `scripts/harness-audit.js`
+### `scripts/claw.js`
-The `showHelp` function in [`scripts/harness-audit.js`](https://github.com/affaan-m/everything-claude-code/blob/HEAD/scripts/harness-audit.js) handles a key part of this chapter's functionality:
+The `main` function in [`scripts/claw.js`](https://github.com/affaan-m/everything-claude-code/blob/HEAD/scripts/claw.js) handles a key part of this chapter's functionality:
```js
}
-function showHelp(exitCode = 0) {
- console.log(`
-Usage: node scripts/harness-audit.js [scope] [--scope <repo|hooks|skills|commands|agents>] [--format <text|json>]
-
-Deterministic harness audit based on explicit file/rule checks.
-`);
- process.exit(exitCode);
-}
-
function main() {
- try {
- const args = parseArgs(process.argv);
-
- if (args.help) {
- showHelp(0);
- return;
- }
-
- const report = buildReport(args.scope);
-
- if (args.format === 'json') {
- console.log(JSON.stringify(report, null, 2));
- } else {
- printText(report);
- }
- } catch (error) {
- console.error(`Error: ${error.message}`);
+ const initialSessionName = process.env.CLAW_SESSION || 'default';
+ if (!isValidSessionName(initialSessionName)) {
+ console.error(`Error: Invalid session name "${initialSessionName}". Use alphanumeric characters and hyphens only.`);
process.exit(1);
}
-}
+
+ fs.mkdirSync(getClawDir(), { recursive: true });
+
+ const state = {
+ sessionName: initialSessionName,
+ sessionPath: getSessionPath(initialSessionName),
+ model: DEFAULT_MODEL,
+ skills: normalizeSkillList(process.env.CLAW_SKILLS || ''),
+ };
+
+ let eccContext = loadECCContext(state.skills);
+
+ const loadedCount = state.skills.filter(skillExists).length;
+
+ console.log(`NanoClaw v2 — Session: ${state.sessionName}`);
+ console.log(`Model: ${state.model}`);
+ if (loadedCount > 0) {
+ console.log(`Loaded ${loadedCount} skill(s) as context.`);
+ }
+ console.log('Type /help for commands, exit to quit.\n');
+
+ const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+
+ const prompt = () => {
```
This function is important because it defines how Everything Claude Code Tutorial: Production Configuration Patterns for Claude Code implements the patterns covered in this chapter.
@@ -216,11 +214,11 @@ This function is important because it defines how Everything Claude Code Tutoria
```mermaid
flowchart TD
- A[summarizeCategoryScores]
- B[buildReport]
- C[printText]
- D[showHelp]
- E[main]
+ A[handleHistory]
+ B[handleSessions]
+ C[handleHelp]
+ D[main]
+ E[showHelp]
A --> B
B --> C
C --> D
diff --git a/tutorials/everything-claude-code-tutorial/05-hooks-mcp-and-continuous-learning-loops.md b/tutorials/everything-claude-code-tutorial/05-hooks-mcp-and-continuous-learning-loops.md
index af7e33dc..18a7115d 100644
--- a/tutorials/everything-claude-code-tutorial/05-hooks-mcp-and-continuous-learning-loops.md
+++ b/tutorials/everything-claude-code-tutorial/05-hooks-mcp-and-continuous-learning-loops.md
@@ -44,170 +44,168 @@ You now understand how to run automated feedback loops with controlled risk.
Next: [Chapter 6: Cross-Platform Workflows (Cursor and OpenCode)](06-cross-platform-workflows-cursor-and-opencode.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `scripts/install-plan.js`
+### `.codebuddy/install.js`
-The `printPlan` function in [`scripts/install-plan.js`](https://github.com/affaan-m/everything-claude-code/blob/HEAD/scripts/install-plan.js) handles a key part of this chapter's functionality:
+The `ensureDir` function in [`.codebuddy/install.js`](https://github.com/affaan-m/everything-claude-code/blob/HEAD/.codebuddy/install.js) handles a key part of this chapter's functionality:
```js
-}
-
-function printPlan(plan) {
- console.log('Install plan:\n');
- console.log(
- 'Note: target filtering and operation output currently reflect scaffold-level adapter planning, not a byte-for-byte mirror of legacy install.sh copy paths.\n'
- );
- console.log(`Profile: ${plan.profileId || '(custom modules)'}`);
- console.log(`Target: ${plan.target || '(all targets)'}`);
- console.log(`Included components: ${plan.includedComponentIds.join(', ') || '(none)'}`);
- console.log(`Excluded components: ${plan.excludedComponentIds.join(', ') || '(none)'}`);
- console.log(`Requested: ${plan.requestedModuleIds.join(', ')}`);
- if (plan.targetAdapterId) {
- console.log(`Adapter: ${plan.targetAdapterId}`);
- console.log(`Target root: ${plan.targetRoot}`);
- console.log(`Install-state: ${plan.installStatePath}`);
- }
- console.log('');
- console.log(`Selected modules (${plan.selectedModuleIds.length}):`);
- for (const module of plan.selectedModules) {
- console.log(`- ${module.id} [${module.kind}]`);
+ * Ensure directory exists
+ */
+function ensureDir(dirPath) {
+ try {
+ if (!fs.existsSync(dirPath)) {
+ fs.mkdirSync(dirPath, { recursive: true });
+ }
+ } catch (err) {
+ if (err.code !== 'EEXIST') {
+ throw err;
+ }
}
+}
- if (plan.skippedModuleIds.length > 0) {
- console.log('');
- console.log(`Skipped for target ${plan.target} (${plan.skippedModuleIds.length}):`);
- for (const module of plan.skippedModules) {
- console.log(`- ${module.id} [${module.kind}]`);
+/**
+ * Read lines from a file
+ */
+function readLines(filePath) {
+ try {
+ if (!fs.existsSync(filePath)) {
+ return [];
}
+ const content = fs.readFileSync(filePath, 'utf8');
+ return content.split('\n').filter(line => line.length > 0);
+ } catch {
+ return [];
}
+}
- if (plan.excludedModuleIds.length > 0) {
+/**
+ * Check if manifest contains an entry
+ */
```
This function is important because it defines how Everything Claude Code Tutorial: Production Configuration Patterns for Claude Code implements the patterns covered in this chapter.
-### `scripts/install-plan.js`
+### `.codebuddy/install.js`
-The `main` function in [`scripts/install-plan.js`](https://github.com/affaan-m/everything-claude-code/blob/HEAD/scripts/install-plan.js) handles a key part of this chapter's functionality:
+The `readLines` function in [`.codebuddy/install.js`](https://github.com/affaan-m/everything-claude-code/blob/HEAD/.codebuddy/install.js) handles a key part of this chapter's functionality:
```js
-}
-
-function main() {
+ * Read lines from a file
+ */
+function readLines(filePath) {
try {
- const options = parseArgs(process.argv);
-
- if (options.help || process.argv.length <= 2) {
- showHelp();
- process.exit(0);
+ if (!fs.existsSync(filePath)) {
+ return [];
}
+ const content = fs.readFileSync(filePath, 'utf8');
+ return content.split('\n').filter(line => line.length > 0);
+ } catch {
+ return [];
+ }
+}
- if (options.listProfiles) {
- const profiles = listInstallProfiles();
- if (options.json) {
- console.log(JSON.stringify({ profiles }, null, 2));
- } else {
- printProfiles(profiles);
- }
- return;
- }
+/**
+ * Check if manifest contains an entry
+ */
+function manifestHasEntry(manifestPath, entry) {
+ const lines = readLines(manifestPath);
+ return lines.includes(entry);
+}
- if (options.listModules) {
- const modules = listInstallModules();
- if (options.json) {
- console.log(JSON.stringify({ modules }, null, 2));
- } else {
- printModules(modules);
- }
- return;
+/**
+ * Add entry to manifest
+ */
+function ensureManifestEntry(manifestPath, entry) {
+ try {
+ const lines = readLines(manifestPath);
+ if (!lines.includes(entry)) {
+ const content = lines.join('\n') + (lines.length > 0 ? '\n' : '') + entry + '\n';
+ fs.writeFileSync(manifestPath, content, 'utf8');
}
-
- if (options.listComponents) {
```
This function is important because it defines how Everything Claude Code Tutorial: Production Configuration Patterns for Claude Code implements the patterns covered in this chapter.
-### `scripts/skill-create-output.js`
+### `.codebuddy/install.js`
-The `SkillCreateOutput` class in [`scripts/skill-create-output.js`](https://github.com/affaan-m/everything-claude-code/blob/HEAD/scripts/skill-create-output.js) handles a key part of this chapter's functionality:
+The `manifestHasEntry` function in [`.codebuddy/install.js`](https://github.com/affaan-m/everything-claude-code/blob/HEAD/.codebuddy/install.js) handles a key part of this chapter's functionality:
```js
+ * Check if manifest contains an entry
+ */
+function manifestHasEntry(manifestPath, entry) {
+ const lines = readLines(manifestPath);
+ return lines.includes(entry);
+}
-// Main output formatter
-class SkillCreateOutput {
- constructor(repoName, options = {}) {
- this.repoName = repoName;
- this.options = options;
- this.width = options.width || 70;
+/**
+ * Add entry to manifest
+ */
+function ensureManifestEntry(manifestPath, entry) {
+ try {
+ const lines = readLines(manifestPath);
+ if (!lines.includes(entry)) {
+ const content = lines.join('\n') + (lines.length > 0 ? '\n' : '') + entry + '\n';
+ fs.writeFileSync(manifestPath, content, 'utf8');
+ }
+ } catch (err) {
+ console.error(`Error updating manifest: ${err.message}`);
}
+}
- header() {
- const subtitle = `Extracting patterns from ${chalk.cyan(this.repoName)}`;
-
- console.log('\n');
- console.log(chalk.bold(chalk.magenta('╔════════════════════════════════════════════════════════════════╗')));
- console.log(chalk.bold(chalk.magenta('║')) + chalk.bold(' 🔮 ECC Skill Creator ') + chalk.bold(chalk.magenta('║')));
- console.log(chalk.bold(chalk.magenta('║')) + ` ${subtitle}${' '.repeat(Math.max(0, 59 - stripAnsi(subtitle).length))}` + chalk.bold(chalk.magenta('║')));
- console.log(chalk.bold(chalk.magenta('╚════════════════════════════════════════════════════════════════╝')));
- console.log('');
- }
+/**
+ * Copy a file and manage in manifest
+ */
+function copyManagedFile(sourcePath, targetPath, manifestPath, manifestEntry, makeExecutable = false) {
+ const alreadyManaged = manifestHasEntry(manifestPath, manifestEntry);
- async analyzePhase(data) {
- const steps = [
- { name: 'Parsing git history...', duration: 300 },
- { name: `Found ${chalk.yellow(data.commits)} commits`, duration: 200 },
- { name: 'Analyzing commit patterns...', duration: 400 },
- { name: 'Detecting file co-changes...', duration: 300 },
- { name: 'Identifying workflows...', duration: 400 },
- { name: 'Extracting architecture patterns...', duration: 300 },
- ];
-
- await animateProgress('Analyzing Repository', steps);
- }
+ // If target file already exists
+ if (fs.existsSync(targetPath)) {
+ if (alreadyManaged) {
+ ensureManifestEntry(manifestPath, manifestEntry);
```
-This class is important because it defines how Everything Claude Code Tutorial: Production Configuration Patterns for Claude Code implements the patterns covered in this chapter.
+This function is important because it defines how Everything Claude Code Tutorial: Production Configuration Patterns for Claude Code implements the patterns covered in this chapter.
-### `scripts/skill-create-output.js`
+### `.codebuddy/install.js`
-The `box` function in [`scripts/skill-create-output.js`](https://github.com/affaan-m/everything-claude-code/blob/HEAD/scripts/skill-create-output.js) handles a key part of this chapter's functionality:
+The `ensureManifestEntry` function in [`.codebuddy/install.js`](https://github.com/affaan-m/everything-claude-code/blob/HEAD/.codebuddy/install.js) handles a key part of this chapter's functionality:
```js
-
-// Helper functions
-function box(title, content, width = 60) {
- const lines = content.split('\n');
- const top = `${BOX.topLeft}${BOX.horizontal} ${chalk.bold(chalk.cyan(title))} ${BOX.horizontal.repeat(Math.max(0, width - title.length - 5))}${BOX.topRight}`;
- const bottom = `${BOX.bottomLeft}${BOX.horizontal.repeat(width - 2)}${BOX.bottomRight}`;
- const middle = lines.map(line => {
- const padding = width - 4 - stripAnsi(line).length;
- return `${BOX.vertical} ${line}${' '.repeat(Math.max(0, padding))} ${BOX.vertical}`;
- }).join('\n');
- return `${top}\n${middle}\n${bottom}`;
-}
-
-function stripAnsi(str) {
- // eslint-disable-next-line no-control-regex
- return str.replace(/\x1b\[[0-9;]*m/g, '');
+ * Add entry to manifest
+ */
+function ensureManifestEntry(manifestPath, entry) {
+ try {
+ const lines = readLines(manifestPath);
+ if (!lines.includes(entry)) {
+ const content = lines.join('\n') + (lines.length > 0 ? '\n' : '') + entry + '\n';
+ fs.writeFileSync(manifestPath, content, 'utf8');
+ }
+ } catch (err) {
+ console.error(`Error updating manifest: ${err.message}`);
+ }
}
-function progressBar(percent, width = 30) {
- const filled = Math.min(width, Math.max(0, Math.round(width * percent / 100)));
- const empty = width - filled;
- const bar = chalk.green('█'.repeat(filled)) + chalk.gray('░'.repeat(empty));
- return `${bar} ${chalk.bold(percent)}%`;
-}
+/**
+ * Copy a file and manage in manifest
+ */
+function copyManagedFile(sourcePath, targetPath, manifestPath, manifestEntry, makeExecutable = false) {
+ const alreadyManaged = manifestHasEntry(manifestPath, manifestEntry);
-function sleep(ms) {
- return new Promise(resolve => setTimeout(resolve, ms));
-}
-
-async function animateProgress(label, steps, callback) {
- process.stdout.write(`\n${chalk.cyan('⏳')} ${label}...\n`);
+ // If target file already exists
+ if (fs.existsSync(targetPath)) {
+ if (alreadyManaged) {
+ ensureManifestEntry(manifestPath, manifestEntry);
+ }
+ return false;
+ }
+ // Copy the file
+ try {
+ ensureDir(path.dirname(targetPath));
+ fs.copyFileSync(sourcePath, targetPath);
```
This function is important because it defines how Everything Claude Code Tutorial: Production Configuration Patterns for Claude Code implements the patterns covered in this chapter.
@@ -217,11 +215,11 @@ This function is important because it defines how Everything Claude Code Tutoria
```mermaid
flowchart TD
- A[printPlan]
- B[main]
- C[SkillCreateOutput]
- D[box]
- E[stripAnsi]
+ A[ensureDir]
+ B[readLines]
+ C[manifestHasEntry]
+ D[ensureManifestEntry]
+ E[copyManagedFile]
A --> B
B --> C
C --> D
diff --git a/tutorials/everything-claude-code-tutorial/06-cross-platform-workflows-cursor-and-opencode.md b/tutorials/everything-claude-code-tutorial/06-cross-platform-workflows-cursor-and-opencode.md
index 6c679800..be3b0b57 100644
--- a/tutorials/everything-claude-code-tutorial/06-cross-platform-workflows-cursor-and-opencode.md
+++ b/tutorials/everything-claude-code-tutorial/06-cross-platform-workflows-cursor-and-opencode.md
@@ -38,144 +38,136 @@ You now have a practical cross-platform portability model.
Next: [Chapter 7: Testing, Verification, and Troubleshooting](07-testing-verification-and-troubleshooting.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `scripts/setup-package-manager.js`
+### `scripts/skill-create-output.js`
-The `detectAndShow` function in [`scripts/setup-package-manager.js`](https://github.com/affaan-m/everything-claude-code/blob/HEAD/scripts/setup-package-manager.js) handles a key part of this chapter's functionality:
+The `sleep` function in [`scripts/skill-create-output.js`](https://github.com/affaan-m/everything-claude-code/blob/HEAD/scripts/skill-create-output.js) handles a key part of this chapter's functionality:
```js
}
-function detectAndShow() {
- const pm = getPackageManager();
- const available = getAvailablePackageManagers();
- const fromLock = detectFromLockFile();
- const fromPkg = detectFromPackageJson();
-
- console.log('\n=== Package Manager Detection ===\n');
-
- console.log('Current selection:');
- console.log(` Package Manager: ${pm.name}`);
- console.log(` Source: ${pm.source}`);
- console.log('');
-
- console.log('Detection results:');
- console.log(` From package.json: ${fromPkg || 'not specified'}`);
- console.log(` From lock file: ${fromLock || 'not found'}`);
- console.log(` Environment var: ${process.env.CLAUDE_PACKAGE_MANAGER || 'not set'}`);
- console.log('');
-
- console.log('Available package managers:');
- for (const pmName of Object.keys(PACKAGE_MANAGERS)) {
- const installed = available.includes(pmName);
- const indicator = installed ? '✓' : '✗';
- const current = pmName === pm.name ? ' (current)' : '';
- console.log(` ${indicator} ${pmName}${current}`);
+function sleep(ms) {
+ return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+async function animateProgress(label, steps, callback) {
+ process.stdout.write(`\n${chalk.cyan('[RUN]')} ${label}...\n`);
+
+ for (let i = 0; i < steps.length; i++) {
+ const step = steps[i];
+ process.stdout.write(` ${chalk.gray(SPINNER[i % SPINNER.length])} ${step.name}`);
+ await sleep(step.duration || 500);
+ process.stdout.clearLine?.(0) || process.stdout.write('\r');
+ process.stdout.cursorTo?.(0) || process.stdout.write('\r');
+ process.stdout.write(` ${chalk.green('[DONE]')} ${step.name}\n`);
+ if (callback) callback(step, i);
+ }
+}
+
+// Main output formatter
+class SkillCreateOutput {
+ constructor(repoName, options = {}) {
+ this.repoName = repoName;
+ this.options = options;
+ this.width = options.width || 70;
}
- console.log('');
- console.log('Commands:');
- console.log(` Install: ${pm.config.installCmd}`);
+ header() {
+ const subtitle = `Extracting patterns from ${chalk.cyan(this.repoName)}`;
+
+ console.log('\n');
```
This function is important because it defines how Everything Claude Code Tutorial: Production Configuration Patterns for Claude Code implements the patterns covered in this chapter.
-### `scripts/setup-package-manager.js`
+### `scripts/skill-create-output.js`
-The `listAvailable` function in [`scripts/setup-package-manager.js`](https://github.com/affaan-m/everything-claude-code/blob/HEAD/scripts/setup-package-manager.js) handles a key part of this chapter's functionality:
+The `animateProgress` function in [`scripts/skill-create-output.js`](https://github.com/affaan-m/everything-claude-code/blob/HEAD/scripts/skill-create-output.js) handles a key part of this chapter's functionality:
```js
}
-function listAvailable() {
- const available = getAvailablePackageManagers();
- const pm = getPackageManager();
-
- console.log('\nAvailable Package Managers:\n');
-
- for (const pmName of Object.keys(PACKAGE_MANAGERS)) {
- const config = PACKAGE_MANAGERS[pmName];
- const installed = available.includes(pmName);
- const current = pmName === pm.name ? ' (current)' : '';
-
- console.log(`${pmName}${current}`);
- console.log(` Installed: ${installed ? 'Yes' : 'No'}`);
- console.log(` Lock file: ${config.lockFile}`);
- console.log(` Install: ${config.installCmd}`);
- console.log(` Run: ${config.runCmd}`);
- console.log('');
+async function animateProgress(label, steps, callback) {
+ process.stdout.write(`\n${chalk.cyan('[RUN]')} ${label}...\n`);
+
+ for (let i = 0; i < steps.length; i++) {
+ const step = steps[i];
+ process.stdout.write(` ${chalk.gray(SPINNER[i % SPINNER.length])} ${step.name}`);
+ await sleep(step.duration || 500);
+ process.stdout.clearLine?.(0) || process.stdout.write('\r');
+ process.stdout.cursorTo?.(0) || process.stdout.write('\r');
+ process.stdout.write(` ${chalk.green('[DONE]')} ${step.name}\n`);
+ if (callback) callback(step, i);
}
}
-function setGlobal(pmName) {
- if (!PACKAGE_MANAGERS[pmName]) {
- console.error(`Error: Unknown package manager "${pmName}"`);
- console.error(`Available: ${Object.keys(PACKAGE_MANAGERS).join(', ')}`);
- process.exit(1);
+// Main output formatter
+class SkillCreateOutput {
+ constructor(repoName, options = {}) {
+ this.repoName = repoName;
+ this.options = options;
+ this.width = options.width || 70;
}
- const available = getAvailablePackageManagers();
- if (!available.includes(pmName)) {
- console.warn(`Warning: ${pmName} is not installed on your system`);
+ header() {
+ const subtitle = `Extracting patterns from ${chalk.cyan(this.repoName)}`;
+
+ console.log('\n');
+ console.log(chalk.bold(chalk.magenta('╔════════════════════════════════════════════════════════════════╗')));
+ console.log(chalk.bold(chalk.magenta('║')) + chalk.bold(' ECC Skill Creator ') + chalk.bold(chalk.magenta('║')));
+ console.log(chalk.bold(chalk.magenta('║')) + ` ${subtitle}${' '.repeat(Math.max(0, 59 - stripAnsi(subtitle).length))}` + chalk.bold(chalk.magenta('║')));
+ console.log(chalk.bold(chalk.magenta('╚════════════════════════════════════════════════════════════════╝')));
```
This function is important because it defines how Everything Claude Code Tutorial: Production Configuration Patterns for Claude Code implements the patterns covered in this chapter.
-### `scripts/setup-package-manager.js`
+### `scripts/skill-create-output.js`
-The `setGlobal` function in [`scripts/setup-package-manager.js`](https://github.com/affaan-m/everything-claude-code/blob/HEAD/scripts/setup-package-manager.js) handles a key part of this chapter's functionality:
+The `demo` function in [`scripts/skill-create-output.js`](https://github.com/affaan-m/everything-claude-code/blob/HEAD/scripts/skill-create-output.js) handles a key part of this chapter's functionality:
```js
-}
-
-function setGlobal(pmName) {
- if (!PACKAGE_MANAGERS[pmName]) {
- console.error(`Error: Unknown package manager "${pmName}"`);
- console.error(`Available: ${Object.keys(PACKAGE_MANAGERS).join(', ')}`);
- process.exit(1);
- }
-
- const available = getAvailablePackageManagers();
- if (!available.includes(pmName)) {
- console.warn(`Warning: ${pmName} is not installed on your system`);
- }
-
- try {
- setPreferredPackageManager(pmName);
- console.log(`\n✓ Global preference set to: ${pmName}`);
- console.log(' Saved to: ~/.claude/package-manager.json');
- console.log('');
- } catch (err) {
- console.error(`Error: ${err.message}`);
- process.exit(1);
- }
-}
-
-function setProject(pmName) {
- if (!PACKAGE_MANAGERS[pmName]) {
- console.error(`Error: Unknown package manager "${pmName}"`);
- console.error(`Available: ${Object.keys(PACKAGE_MANAGERS).join(', ')}`);
- process.exit(1);
- }
+// Demo function to show the output
+async function demo() {
+ const output = new SkillCreateOutput('PMX');
+
+ output.header();
+
+ await output.analyzePhase({
+ commits: 200,
+ });
+
+ output.analysisResults({
+ commits: 200,
+ timeRange: 'Nov 2024 - Jan 2025',
+ contributors: 4,
+ files: 847,
+ });
+
+ output.patterns([
+ {
+ name: 'Conventional Commits',
+ trigger: 'when writing commit messages',
+ confidence: 0.85,
+ evidence: 'Found in 150/200 commits (feat:, fix:, refactor:)',
+ },
+ {
+ name: 'Client/Server Component Split',
+ trigger: 'when creating Next.js pages',
+ confidence: 0.90,
+ evidence: 'Observed in markets/, premarkets/, portfolio/',
+ },
+ {
```
This function is important because it defines how Everything Claude Code Tutorial: Production Configuration Patterns for Claude Code implements the patterns covered in this chapter.
### `scripts/setup-package-manager.js`
-The `setProject` function in [`scripts/setup-package-manager.js`](https://github.com/affaan-m/everything-claude-code/blob/HEAD/scripts/setup-package-manager.js) handles a key part of this chapter's functionality:
+The `showHelp` function in [`scripts/setup-package-manager.js`](https://github.com/affaan-m/everything-claude-code/blob/HEAD/scripts/setup-package-manager.js) handles a key part of this chapter's functionality:
```js
- getPackageManager,
- setPreferredPackageManager,
- setProjectPackageManager,
- getAvailablePackageManagers,
- detectFromLockFile,
- detectFromPackageJson
} = require('./lib/package-manager');
function showHelp() {
@@ -202,6 +194,12 @@ Examples:
# Detect current package manager
node scripts/setup-package-manager.js --detect
+ # Set pnpm as global preference
+ node scripts/setup-package-manager.js --global pnpm
+
+ # Set bun for current project
+ node scripts/setup-package-manager.js --project bun
+
```
This function is important because it defines how Everything Claude Code Tutorial: Production Configuration Patterns for Claude Code implements the patterns covered in this chapter.
@@ -211,11 +209,11 @@ This function is important because it defines how Everything Claude Code Tutoria
```mermaid
flowchart TD
- A[detectAndShow]
- B[listAvailable]
- C[setGlobal]
- D[setProject]
- E[showHelp]
+ A[sleep]
+ B[animateProgress]
+ C[demo]
+ D[showHelp]
+ E[detectAndShow]
A --> B
B --> C
C --> D
diff --git a/tutorials/everything-claude-code-tutorial/07-testing-verification-and-troubleshooting.md b/tutorials/everything-claude-code-tutorial/07-testing-verification-and-troubleshooting.md
index ccf727a7..780e475d 100644
--- a/tutorials/everything-claude-code-tutorial/07-testing-verification-and-troubleshooting.md
+++ b/tutorials/everything-claude-code-tutorial/07-testing-verification-and-troubleshooting.md
@@ -39,169 +39,167 @@ You now have a reliability playbook for daily operations.
Next: [Chapter 8: Contribution Workflow and Governance](08-contribution-workflow-and-governance.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `scripts/sessions-cli.js`
+### `.codebuddy/uninstall.js`
-The `printWorkers` function in [`scripts/sessions-cli.js`](https://github.com/affaan-m/everything-claude-code/blob/HEAD/scripts/sessions-cli.js) handles a key part of this chapter's functionality:
+The `findEmptyDirs` function in [`.codebuddy/uninstall.js`](https://github.com/affaan-m/everything-claude-code/blob/HEAD/.codebuddy/uninstall.js) handles a key part of this chapter's functionality:
```js
-}
-
-function printWorkers(workers) {
- console.log(`Workers: ${workers.length}`);
- if (workers.length === 0) {
- console.log(' - none');
- return;
- }
-
- for (const worker of workers) {
- console.log(` - ${worker.id || worker.label || '(unknown)'} ${worker.state || 'unknown'}`);
- console.log(` Branch: ${worker.branch || '(unknown)'}`);
- console.log(` Worktree: ${worker.worktree || '(unknown)'}`);
- }
-}
-
-function printSkillRuns(skillRuns) {
- console.log(`Skill runs: ${skillRuns.length}`);
- if (skillRuns.length === 0) {
- console.log(' - none');
- return;
+ * Recursively find empty directories
+ */
+function findEmptyDirs(dirPath) {
+ const emptyDirs = [];
+
+ function walkDirs(currentPath) {
+ try {
+ const entries = fs.readdirSync(currentPath, { withFileTypes: true });
+ const subdirs = entries.filter(e => e.isDirectory());
+
+ for (const subdir of subdirs) {
+ const subdirPath = path.join(currentPath, subdir.name);
+ walkDirs(subdirPath);
+ }
+
+ // Check if directory is now empty
+ try {
+ const remaining = fs.readdirSync(currentPath);
+ if (remaining.length === 0 && currentPath !== dirPath) {
+ emptyDirs.push(currentPath);
+ }
+ } catch {
+ // Directory might have been deleted
+ }
+ } catch {
+ // Ignore errors
+ }
}
- for (const skillRun of skillRuns) {
- console.log(` - ${skillRun.id} ${skillRun.outcome} ${skillRun.skillId}@${skillRun.skillVersion}`);
- console.log(` Task: ${skillRun.taskDescription}`);
- console.log(` Duration: ${skillRun.durationMs ?? '(unknown)'} ms`);
- }
+ walkDirs(dirPath);
+ return emptyDirs.sort().reverse(); // Sort in reverse for removal
}
-
-function printDecisions(decisions) {
- console.log(`Decisions: ${decisions.length}`);
```
This function is important because it defines how Everything Claude Code Tutorial: Production Configuration Patterns for Claude Code implements the patterns covered in this chapter.
-### `scripts/sessions-cli.js`
+### `.codebuddy/uninstall.js`
-The `printSkillRuns` function in [`scripts/sessions-cli.js`](https://github.com/affaan-m/everything-claude-code/blob/HEAD/scripts/sessions-cli.js) handles a key part of this chapter's functionality:
+The `walkDirs` function in [`.codebuddy/uninstall.js`](https://github.com/affaan-m/everything-claude-code/blob/HEAD/.codebuddy/uninstall.js) handles a key part of this chapter's functionality:
```js
-}
-
-function printSkillRuns(skillRuns) {
- console.log(`Skill runs: ${skillRuns.length}`);
- if (skillRuns.length === 0) {
- console.log(' - none');
- return;
- }
-
- for (const skillRun of skillRuns) {
- console.log(` - ${skillRun.id} ${skillRun.outcome} ${skillRun.skillId}@${skillRun.skillVersion}`);
- console.log(` Task: ${skillRun.taskDescription}`);
- console.log(` Duration: ${skillRun.durationMs ?? '(unknown)'} ms`);
- }
-}
-
-function printDecisions(decisions) {
- console.log(`Decisions: ${decisions.length}`);
- if (decisions.length === 0) {
- console.log(' - none');
- return;
+ const emptyDirs = [];
+
+ function walkDirs(currentPath) {
+ try {
+ const entries = fs.readdirSync(currentPath, { withFileTypes: true });
+ const subdirs = entries.filter(e => e.isDirectory());
+
+ for (const subdir of subdirs) {
+ const subdirPath = path.join(currentPath, subdir.name);
+ walkDirs(subdirPath);
+ }
+
+ // Check if directory is now empty
+ try {
+ const remaining = fs.readdirSync(currentPath);
+ if (remaining.length === 0 && currentPath !== dirPath) {
+ emptyDirs.push(currentPath);
+ }
+ } catch {
+ // Directory might have been deleted
+ }
+ } catch {
+ // Ignore errors
+ }
}
- for (const decision of decisions) {
- console.log(` - ${decision.id} ${decision.status}`);
- console.log(` Title: ${decision.title}`);
- console.log(` Alternatives: ${decision.alternatives.join(', ') || '(none)'}`);
- }
+ walkDirs(dirPath);
+ return emptyDirs.sort().reverse(); // Sort in reverse for removal
}
-function printSessionDetail(payload) {
- console.log(`Session: ${payload.session.id}`);
+/**
+ * Prompt user for confirmation
```
This function is important because it defines how Everything Claude Code Tutorial: Production Configuration Patterns for Claude Code implements the patterns covered in this chapter.
-### `scripts/sessions-cli.js`
+### `.codebuddy/uninstall.js`
-The `printDecisions` function in [`scripts/sessions-cli.js`](https://github.com/affaan-m/everything-claude-code/blob/HEAD/scripts/sessions-cli.js) handles a key part of this chapter's functionality:
+The `promptConfirm` function in [`.codebuddy/uninstall.js`](https://github.com/affaan-m/everything-claude-code/blob/HEAD/.codebuddy/uninstall.js) handles a key part of this chapter's functionality:
```js
-}
-
-function printDecisions(decisions) {
- console.log(`Decisions: ${decisions.length}`);
- if (decisions.length === 0) {
- console.log(' - none');
- return;
- }
-
- for (const decision of decisions) {
- console.log(` - ${decision.id} ${decision.status}`);
- console.log(` Title: ${decision.title}`);
- console.log(` Alternatives: ${decision.alternatives.join(', ') || '(none)'}`);
- }
-}
+ * Prompt user for confirmation
+ */
+async function promptConfirm(question) {
+ return new Promise((resolve) => {
+ const rl = readline.createInterface({
+ input: process.stdin,
+ output: process.stdout,
+ });
-function printSessionDetail(payload) {
- console.log(`Session: ${payload.session.id}`);
- console.log(`Harness: ${payload.session.harness}`);
- console.log(`Adapter: ${payload.session.adapterId}`);
- console.log(`State: ${payload.session.state}`);
- console.log(`Repo: ${payload.session.repoRoot || '(unknown)'}`);
- console.log(`Started: ${payload.session.startedAt || '(unknown)'}`);
- console.log(`Ended: ${payload.session.endedAt || '(active)'}`);
- console.log();
- printWorkers(payload.workers);
- console.log();
- printSkillRuns(payload.skillRuns);
- console.log();
- printDecisions(payload.decisions);
+ rl.question(question, (answer) => {
+ rl.close();
+ resolve(/^[yY]$/.test(answer));
+ });
+ });
}
+/**
+ * Main uninstall function
+ */
+async function doUninstall() {
+ const codebuddyDirName = '.codebuddy';
+
+ // Parse arguments
+ let targetDir = process.cwd();
+ if (process.argv.length > 2) {
+ const arg = process.argv[2];
+ if (arg === '~' || arg === getHomeDir()) {
+ targetDir = getHomeDir();
+ } else {
+ targetDir = path.resolve(arg);
+ }
+ }
```
This function is important because it defines how Everything Claude Code Tutorial: Production Configuration Patterns for Claude Code implements the patterns covered in this chapter.
-### `scripts/sessions-cli.js`
+### `.codebuddy/uninstall.js`
-The `printSessionDetail` function in [`scripts/sessions-cli.js`](https://github.com/affaan-m/everything-claude-code/blob/HEAD/scripts/sessions-cli.js) handles a key part of this chapter's functionality:
+The `doUninstall` function in [`.codebuddy/uninstall.js`](https://github.com/affaan-m/everything-claude-code/blob/HEAD/.codebuddy/uninstall.js) handles a key part of this chapter's functionality:
```js
-}
-
-function printSessionDetail(payload) {
- console.log(`Session: ${payload.session.id}`);
- console.log(`Harness: ${payload.session.harness}`);
- console.log(`Adapter: ${payload.session.adapterId}`);
- console.log(`State: ${payload.session.state}`);
- console.log(`Repo: ${payload.session.repoRoot || '(unknown)'}`);
- console.log(`Started: ${payload.session.startedAt || '(unknown)'}`);
- console.log(`Ended: ${payload.session.endedAt || '(active)'}`);
- console.log();
- printWorkers(payload.workers);
- console.log();
- printSkillRuns(payload.skillRuns);
- console.log();
- printDecisions(payload.decisions);
-}
+ * Main uninstall function
+ */
+async function doUninstall() {
+ const codebuddyDirName = '.codebuddy';
+
+ // Parse arguments
+ let targetDir = process.cwd();
+ if (process.argv.length > 2) {
+ const arg = process.argv[2];
+ if (arg === '~' || arg === getHomeDir()) {
+ targetDir = getHomeDir();
+ } else {
+ targetDir = path.resolve(arg);
+ }
+ }
-async function main() {
- let store = null;
+ // Determine codebuddy full path
+ let codebuddyFullPath;
+ const baseName = path.basename(targetDir);
- try {
- const options = parseArgs(process.argv);
- if (options.help) {
- showHelp(0);
- }
+ if (baseName === codebuddyDirName) {
+ codebuddyFullPath = targetDir;
+ } else {
+ codebuddyFullPath = path.join(targetDir, codebuddyDirName);
+ }
- store = await createStateStore({
- dbPath: options.dbPath,
- homeDir: process.env.HOME,
- });
+ console.log('ECC CodeBuddy Uninstaller');
+ console.log('==========================');
+ console.log('');
+ console.log(`Target: ${codebuddyFullPath}/`);
+ console.log('');
```
@@ -212,11 +210,11 @@ This function is important because it defines how Everything Claude Code Tutoria
```mermaid
flowchart TD
- A[printWorkers]
- B[printSkillRuns]
- C[printDecisions]
- D[printSessionDetail]
- E[main]
+ A[findEmptyDirs]
+ B[walkDirs]
+ C[promptConfirm]
+ D[doUninstall]
+ E[getHelpText]
A --> B
B --> C
C --> D
diff --git a/tutorials/everything-claude-code-tutorial/08-contribution-workflow-and-governance.md b/tutorials/everything-claude-code-tutorial/08-contribution-workflow-and-governance.md
index a71ce6d9..e8628743 100644
--- a/tutorials/everything-claude-code-tutorial/08-contribution-workflow-and-governance.md
+++ b/tutorials/everything-claude-code-tutorial/08-contribution-workflow-and-governance.md
@@ -50,170 +50,168 @@ Next steps:
- codify verification gates for all workflow changes
- contribute one focused component with tests and docs
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `scripts/status.js`
+### `scripts/catalog.js`
-The `printGovernance` function in [`scripts/status.js`](https://github.com/affaan-m/everything-claude-code/blob/HEAD/scripts/status.js) handles a key part of this chapter's functionality:
+The `showHelp` function in [`scripts/catalog.js`](https://github.com/affaan-m/everything-claude-code/blob/HEAD/scripts/catalog.js) handles a key part of this chapter's functionality:
```js
-}
+});
-function printGovernance(section) {
- console.log(`Pending governance events: ${section.pendingCount}`);
- if (section.events.length === 0) {
- console.log(' - none');
- return;
- }
+function showHelp(exitCode = 0) {
+ console.log(`
+Discover ECC install components and profiles
- for (const event of section.events) {
- console.log(` - ${event.id} ${event.eventType}`);
- console.log(` Session: ${event.sessionId || '(none)'}`);
- console.log(` Created: ${event.createdAt}`);
- }
-}
+Usage:
+ node scripts/catalog.js profiles [--json]
+ node scripts/catalog.js components [--family <family>] [--target <target>] [--json]
+ node scripts/catalog.js show <component-id> [--json]
+
+Examples:
+ node scripts/catalog.js profiles
+ node scripts/catalog.js components --family language
+ node scripts/catalog.js show framework:nextjs
+`);
-function printHuman(payload) {
- console.log('ECC status\n');
- console.log(`Database: ${payload.dbPath}\n`);
- printActiveSessions(payload.activeSessions);
- console.log();
- printSkillRuns(payload.skillRuns);
- console.log();
- printInstallHealth(payload.installHealth);
- console.log();
- printGovernance(payload.governance);
+ process.exit(exitCode);
}
-async function main() {
- let store = null;
+function normalizeFamily(value) {
+ if (!value) {
+ return null;
+ }
+
+ const normalized = String(value).trim().toLowerCase();
+ return FAMILY_ALIASES[normalized] || normalized;
+}
- try {
+function parseArgs(argv) {
+ const args = argv.slice(2);
+ const parsed = {
```
This function is important because it defines how Everything Claude Code Tutorial: Production Configuration Patterns for Claude Code implements the patterns covered in this chapter.
-### `scripts/status.js`
+### `scripts/catalog.js`
-The `printHuman` function in [`scripts/status.js`](https://github.com/affaan-m/everything-claude-code/blob/HEAD/scripts/status.js) handles a key part of this chapter's functionality:
+The `normalizeFamily` function in [`scripts/catalog.js`](https://github.com/affaan-m/everything-claude-code/blob/HEAD/scripts/catalog.js) handles a key part of this chapter's functionality:
```js
}
-function printHuman(payload) {
- console.log('ECC status\n');
- console.log(`Database: ${payload.dbPath}\n`);
- printActiveSessions(payload.activeSessions);
- console.log();
- printSkillRuns(payload.skillRuns);
- console.log();
- printInstallHealth(payload.installHealth);
- console.log();
- printGovernance(payload.governance);
+function normalizeFamily(value) {
+ if (!value) {
+ return null;
+ }
+
+ const normalized = String(value).trim().toLowerCase();
+ return FAMILY_ALIASES[normalized] || normalized;
}
-async function main() {
- let store = null;
+function parseArgs(argv) {
+ const args = argv.slice(2);
+ const parsed = {
+ command: null,
+ componentId: null,
+ family: null,
+ target: null,
+ json: false,
+ help: false,
+ };
+
+ if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+ parsed.help = true;
+ return parsed;
+ }
- try {
- const options = parseArgs(process.argv);
- if (options.help) {
- showHelp(0);
- }
+ parsed.command = args[0];
- store = await createStateStore({
- dbPath: options.dbPath,
- homeDir: process.env.HOME,
- });
+ for (let index = 1; index < args.length; index += 1) {
+ const arg = args[index];
- const payload = {
- dbPath: store.dbPath,
- ...store.getStatus({
- activeLimit: options.limit,
```
This function is important because it defines how Everything Claude Code Tutorial: Production Configuration Patterns for Claude Code implements the patterns covered in this chapter.
-### `scripts/status.js`
+### `scripts/catalog.js`
-The `main` function in [`scripts/status.js`](https://github.com/affaan-m/everything-claude-code/blob/HEAD/scripts/status.js) handles a key part of this chapter's functionality:
+The `parseArgs` function in [`scripts/catalog.js`](https://github.com/affaan-m/everything-claude-code/blob/HEAD/scripts/catalog.js) handles a key part of this chapter's functionality:
```js
}
-async function main() {
- let store = null;
-
- try {
- const options = parseArgs(process.argv);
- if (options.help) {
- showHelp(0);
- }
-
- store = await createStateStore({
- dbPath: options.dbPath,
- homeDir: process.env.HOME,
- });
-
- const payload = {
- dbPath: store.dbPath,
- ...store.getStatus({
- activeLimit: options.limit,
- recentSkillRunLimit: 20,
- pendingLimit: options.limit,
- }),
- };
-
- if (options.json) {
- console.log(JSON.stringify(payload, null, 2));
- } else {
- printHuman(payload);
- }
- } catch (error) {
- console.error(`Error: ${error.message}`);
+function parseArgs(argv) {
+ const args = argv.slice(2);
+ const parsed = {
+ command: null,
+ componentId: null,
+ family: null,
+ target: null,
+ json: false,
+ help: false,
+ };
+
+ if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+ parsed.help = true;
+ return parsed;
+ }
+
+ parsed.command = args[0];
+
+ for (let index = 1; index < args.length; index += 1) {
+ const arg = args[index];
+
+ if (arg === '--help' || arg === '-h') {
+ parsed.help = true;
+ } else if (arg === '--json') {
+ parsed.json = true;
+ } else if (arg === '--family') {
+ if (!args[index + 1]) {
+ throw new Error('Missing value for --family');
+ }
+ parsed.family = normalizeFamily(args[index + 1]);
```
This function is important because it defines how Everything Claude Code Tutorial: Production Configuration Patterns for Claude Code implements the patterns covered in this chapter.
-### `scripts/skills-health.js`
+### `scripts/catalog.js`
-The `showHelp` function in [`scripts/skills-health.js`](https://github.com/affaan-m/everything-claude-code/blob/HEAD/scripts/skills-health.js) handles a key part of this chapter's functionality:
+The `printProfiles` function in [`scripts/catalog.js`](https://github.com/affaan-m/everything-claude-code/blob/HEAD/scripts/catalog.js) handles a key part of this chapter's functionality:
```js
-const { renderDashboard } = require('./lib/skill-evolution/dashboard');
-
-function showHelp() {
- console.log(`
-Usage: node scripts/skills-health.js [options]
-
-Options:
- --json Emit machine-readable JSON
- --skills-root <path> Override curated skills root
- --learned-root <path> Override learned skills root
- --imported-root <path> Override imported skills root
- --home <path> Override home directory for learned/imported skill roots
- --runs-file <path> Override skill run JSONL path
- --now <timestamp> Override current time for deterministic reports
- --dashboard Show rich health dashboard with charts
- --panel <name> Show only a specific panel (success-rate, failures, amendments, versions)
- --warn-threshold <n> Decline sensitivity threshold (default: 0.1)
- --help Show this help text
-`);
}
-function requireValue(argv, index, argName) {
- const value = argv[index + 1];
- if (!value || value.startsWith('--')) {
- throw new Error(`Missing value for ${argName}`);
+function printProfiles(profiles) {
+ console.log('Install profiles:\n');
+ for (const profile of profiles) {
+ console.log(`- ${profile.id} (${profile.moduleCount} modules)`);
+ console.log(` ${profile.description}`);
}
+}
- return value;
+function printComponents(components) {
+ console.log('Install components:\n');
+ for (const component of components) {
+ console.log(`- ${component.id} [${component.family}]`);
+ console.log(` targets=${component.targets.join(', ')} modules=${component.moduleIds.join(', ')}`);
+ console.log(` ${component.description}`);
+ }
}
-function parseArgs(argv) {
- const options = {};
+function printComponent(component) {
+ console.log(`Install component: ${component.id}\n`);
+ console.log(`Family: ${component.family}`);
+ console.log(`Targets: ${component.targets.join(', ')}`);
+ console.log(`Modules: ${component.moduleIds.join(', ')}`);
+ console.log(`Description: ${component.description}`);
+
+ if (component.modules.length > 0) {
+ console.log('\nResolved modules:');
+ for (const module of component.modules) {
+ console.log(`- ${module.id} [${module.kind}]`);
+ console.log(
+ ` targets=${module.targets.join(', ')} default=${module.defaultInstall} cost=${module.cost} stability=${module.stability}`
```
This function is important because it defines how Everything Claude Code Tutorial: Production Configuration Patterns for Claude Code implements the patterns covered in this chapter.
@@ -223,11 +221,11 @@ This function is important because it defines how Everything Claude Code Tutoria
```mermaid
flowchart TD
- A[printGovernance]
- B[printHuman]
- C[main]
- D[showHelp]
- E[requireValue]
+ A[showHelp]
+ B[normalizeFamily]
+ C[parseArgs]
+ D[printProfiles]
+ E[printComponents]
A --> B
B --> C
C --> D
diff --git a/tutorials/fabric-tutorial/01-getting-started.md b/tutorials/fabric-tutorial/01-getting-started.md
index de71d8e2..04a36d91 100644
--- a/tutorials/fabric-tutorial/01-getting-started.md
+++ b/tutorials/fabric-tutorial/01-getting-started.md
@@ -545,22 +545,32 @@ Under the hood, `Chapter 1: Getting Started with Fabric` usually follows a repea
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
-## Source Walkthrough
-
-Use the following upstream sources to verify implementation details while reading this chapter:
-
-- [GitHub Repository](https://github.com/danielmiessler/Fabric)
- Why it matters: authoritative reference on `GitHub Repository` (github.com).
-- [Pattern Library](https://github.com/danielmiessler/fabric/tree/main/data/patterns)
- Why it matters: authoritative reference on `Pattern Library` (github.com).
-- [Community Patterns](https://github.com/danielmiessler/Fabric#community-patterns)
- Why it matters: authoritative reference on `Community Patterns` (github.com).
-- [AI Codebase Knowledge Builder](https://github.com/johnxie/awesome-code-docs)
- Why it matters: authoritative reference on `AI Codebase Knowledge Builder` (github.com).
-
-Suggested trace strategy:
-- search upstream code for `fabric` and `patterns` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+## Source Code Walkthrough
+
+### `internal/core/chatter.go`
+
+The `Chatter` struct in [`internal/core/chatter.go`](https://github.com/danielmiessler/fabric/blob/main/internal/core/chatter.go) is the central execution engine that loads a pattern, calls the AI vendor, and returns the response:
+
+```go
+type Chatter struct {
+ db *fsdb.Db
+
+ Stream bool
+ DryRun bool
+
+ model string
+ modelContextLength int
+ vendor ai.Vendor
+}
+
+// joinPromptSections trims each part, drops empty ones, and joins the rest with newline separators.
+func joinPromptSections(parts ...string) string {
+ sections := make([]string, 0, len(parts))
+ for _, part := range parts {
+ trimmed := strings.TrimSpace(part)
+```
+
+The `Chatter` reads the pattern's `system.md` file from the `fsdb` (filesystem database), combines it with user input via `joinPromptSections`, and sends the composed prompt to the configured AI vendor. The `DryRun` flag lets you preview the composed prompt without making an API call.
## Chapter Connections
diff --git a/tutorials/fabric-tutorial/02-pattern-system.md b/tutorials/fabric-tutorial/02-pattern-system.md
index 340eae4d..23a187f0 100644
--- a/tutorials/fabric-tutorial/02-pattern-system.md
+++ b/tutorials/fabric-tutorial/02-pattern-system.md
@@ -12,6 +12,20 @@ Welcome to **Chapter 2: Pattern System**. In this part of **Fabric Tutorial: Ope
> Understand Fabric's modular pattern architecture for creating reusable AI-powered cognitive workflows.
+## Pattern System Architecture
+
+```mermaid
+graph TD
+ PatternDir["data/patterns/<name>/"] --> SystemMD["system.md\n(expert prompt)"]
+ PatternDir --> UserMD["user.md\n(optional user template)"]
+ CLI["fabric --pattern <name>"] --> Chatter["internal/core/chatter.go\nChatter.Send()"]
+ SystemMD --> Chatter
+ UserMD --> Chatter
+ Stdin["stdin / --text"] --> Chatter
+ Chatter --> Vendor["ai.Vendor\n(OpenAI / Anthropic / Ollama...)"]
+ Vendor --> Output["stdout / file"]
+```
+
## Overview
Patterns are the core building blocks of Fabric. They are carefully crafted prompt templates that encode expert knowledge for specific cognitive tasks. This chapter explores how patterns work and how to use them effectively.
@@ -467,22 +481,30 @@ Under the hood, `Chapter 2: Pattern System` usually follows a repeatable control
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
-## Source Walkthrough
+## Source Code Walkthrough
+
+### `internal/plugins/template/extension_manager.go`
-Use the following upstream sources to verify implementation details while reading this chapter:
+The `ExtensionManager` in [`internal/plugins/template/extension_manager.go`](https://github.com/danielmiessler/fabric/blob/main/internal/plugins/template/extension_manager.go) manages how template extensions (custom patterns with YAML config) are registered and executed:
-- [GitHub Repository](https://github.com/danielmiessler/Fabric)
- Why it matters: authoritative reference on `GitHub Repository` (github.com).
-- [Pattern Library](https://github.com/danielmiessler/fabric/tree/main/data/patterns)
- Why it matters: authoritative reference on `Pattern Library` (github.com).
-- [Community Patterns](https://github.com/danielmiessler/Fabric#community-patterns)
- Why it matters: authoritative reference on `Community Patterns` (github.com).
-- [AI Codebase Knowledge Builder](https://github.com/johnxie/awesome-code-docs)
- Why it matters: authoritative reference on `AI Codebase Knowledge Builder` (github.com).
+```go
+type ExtensionManager struct {
+ registry *ExtensionRegistry
+ executor *ExtensionExecutor
+ configDir string
+}
+
+func NewExtensionManager(configDir string) *ExtensionManager {
+ registry := NewExtensionRegistry(configDir)
+ return &ExtensionManager{
+ registry: registry,
+ executor: NewExtensionExecutor(registry),
+ configDir: configDir,
+ }
+}
+```
-Suggested trace strategy:
-- search upstream code for `fabric` and `summarize` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+Built-in patterns live in `data/patterns/<name>/system.md`. Each pattern's `system.md` is a pure markdown prompt with no code — the entire AI logic is encoded in natural language, making patterns easy to audit, version, and share.
## Chapter Connections
diff --git a/tutorials/fabric-tutorial/03-basic-usage.md b/tutorials/fabric-tutorial/03-basic-usage.md
index 53a5cbf2..b9bf3abb 100644
--- a/tutorials/fabric-tutorial/03-basic-usage.md
+++ b/tutorials/fabric-tutorial/03-basic-usage.md
@@ -12,6 +12,20 @@ Welcome to **Chapter 3: Basic Usage**. In this part of **Fabric Tutorial: Open-S
> Master core commands and workflows for everyday cognitive augmentation with Fabric.
+## Basic Usage Flow
+
+```mermaid
+flowchart LR
+ Stdin["stdin\necho 'text' |"] --> CLI["fabric --pattern <name>"]
+ FileIn["--text 'content'"] --> CLI
+ URL["--youtube / --url"] --> CLI
+ CLI --> Chatter["Chatter.Send()"]
+ Chatter --> Stream["--stream\n(real-time output)"]
+ Chatter --> Save["--output <file>"]
+ Chatter --> Copy["--copy\n(clipboard)"]
+ Stream --> Terminal["Terminal output"]
+```
+
## Overview
This chapter covers the fundamental ways to use Fabric for daily tasks. You'll learn command-line operations, input/output handling, and common workflow patterns.
@@ -430,22 +444,29 @@ Under the hood, `Chapter 3: Basic Usage` usually follows a repeatable control pa
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
-## Source Walkthrough
+## Source Code Walkthrough
+
+### `internal/core/chatter.go`
-Use the following upstream sources to verify implementation details while reading this chapter:
+The `recordFirstStreamError` helper in [`internal/core/chatter.go`](https://github.com/danielmiessler/fabric/blob/main/internal/core/chatter.go) shows how Fabric handles streaming errors gracefully — only the first error is recorded, subsequent ones are discarded:
-- [GitHub Repository](https://github.com/danielmiessler/Fabric)
- Why it matters: authoritative reference on `GitHub Repository` (github.com).
-- [Pattern Library](https://github.com/danielmiessler/fabric/tree/main/data/patterns)
- Why it matters: authoritative reference on `Pattern Library` (github.com).
-- [Community Patterns](https://github.com/danielmiessler/Fabric#community-patterns)
- Why it matters: authoritative reference on `Community Patterns` (github.com).
-- [AI Codebase Knowledge Builder](https://github.com/johnxie/awesome-code-docs)
- Why it matters: authoritative reference on `AI Codebase Knowledge Builder` (github.com).
+```go
+// recordFirstStreamError sends err to errChan if the channel is empty; subsequent errors are discarded.
+func recordFirstStreamError(errChan chan error, err error) {
+ if err == nil {
+ return
+ }
+
+ select {
+ case errChan <- err:
+ default:
+ // Second+ error discarded; log for observability
+ debuglog.Debug(debuglog.Wire, "additional stream error discarded: %v\n", err)
+ }
+}
+```
-Suggested trace strategy:
-- search upstream code for `fabric` and `summarize` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+The `--stream` flag activates streaming output mode — the AI response tokens are printed as they arrive. The `--dry-run` flag prints the composed prompt without making the API call, which is useful for debugging pattern composition.
## Chapter Connections
diff --git a/tutorials/fabric-tutorial/04-advanced-patterns.md b/tutorials/fabric-tutorial/04-advanced-patterns.md
index c6420f55..6860ddcf 100644
--- a/tutorials/fabric-tutorial/04-advanced-patterns.md
+++ b/tutorials/fabric-tutorial/04-advanced-patterns.md
@@ -12,6 +12,20 @@ Welcome to **Chapter 4: Advanced Patterns**. In this part of **Fabric Tutorial:
> Master sophisticated pattern techniques for complex cognitive tasks and specialized domains.
+## Advanced Pattern Composition
+
+```mermaid
+graph LR
+ Input["Input text"] --> P1["Pattern 1\nextract_wisdom"]
+ P1 --> Out1["Insights list"]
+ Out1 --> P2["Pattern 2\ncreate_report"]
+ P2 --> Out2["Structured report"]
+ Out2 --> P3["Pattern 3\nsummarize"]
+ P3 --> Final["Final summary"]
+ Vars["--variable key=val"] --> P1
+ Context["--context file.txt"] --> P2
+```
+
## Overview
Advanced patterns go beyond simple text processing to handle complex multi-step tasks, domain-specific analysis, and nuanced outputs. This chapter explores sophisticated pattern usage and customization.
@@ -521,22 +535,20 @@ Under the hood, `Chapter 4: Advanced Patterns` usually follows a repeatable cont
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
-## Source Walkthrough
+## Source Code Walkthrough
+
+### `internal/plugins/template/extension_executor.go`
-Use the following upstream sources to verify implementation details while reading this chapter:
+The `ExtensionExecutor` in [`internal/plugins/template/extension_executor.go`](https://github.com/danielmiessler/fabric/blob/main/internal/plugins/template/extension_executor.go) runs template extensions as subprocesses, enabling advanced patterns to call external tools and scripts:
-- [GitHub Repository](https://github.com/danielmiessler/Fabric)
- Why it matters: authoritative reference on `GitHub Repository` (github.com).
-- [Pattern Library](https://github.com/danielmiessler/fabric/tree/main/data/patterns)
- Why it matters: authoritative reference on `Pattern Library` (github.com).
-- [Community Patterns](https://github.com/danielmiessler/Fabric#community-patterns)
- Why it matters: authoritative reference on `Community Patterns` (github.com).
-- [AI Codebase Knowledge Builder](https://github.com/johnxie/awesome-code-docs)
- Why it matters: authoritative reference on `AI Codebase Knowledge Builder` (github.com).
+```go
+// ExtensionExecutor runs registered extensions from the registry
+type ExtensionExecutor struct {
+ registry *ExtensionRegistry
+}
+```
-Suggested trace strategy:
-- search upstream code for `fabric` and `input` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+Advanced patterns use `{{.Variable}}` Go template syntax in `user.md` to inject dynamic context into prompts. The `datetime.go` utility in `internal/plugins/template/` injects the current date/time into patterns that need temporal awareness.
## Chapter Connections
diff --git a/tutorials/fabric-tutorial/05-stitch-composition.md b/tutorials/fabric-tutorial/05-stitch-composition.md
index 08bb34b2..eaa29596 100644
--- a/tutorials/fabric-tutorial/05-stitch-composition.md
+++ b/tutorials/fabric-tutorial/05-stitch-composition.md
@@ -12,6 +12,19 @@ Welcome to **Chapter 5: Stitch Composition**. In this part of **Fabric Tutorial:
> Create sophisticated AI workflows by composing patterns into reusable Stitches.
+## Stitch Workflow Composition
+
+```mermaid
+flowchart TD
+ Input["Input"] --> Stitch["Stitch YAML\n(ordered steps)"]
+ Stitch --> Step1["Step 1: pattern_a\n(extract insights)"]
+ Step1 --> Step2["Step 2: pattern_b\n(format output)"]
+ Step2 --> Step3["Step 3: pattern_c\n(generate summary)"]
+ Step3 --> Output["Final Output"]
+ Vars["Variables\n({{.key}})"] --> Step1
+ Vars --> Step2
+```
+
## Overview
Stitches are Fabric's way of composing multiple patterns into coherent workflows. They enable complex multi-step processing pipelines that can be saved, shared, and reused.
@@ -517,22 +530,26 @@ Under the hood, `Chapter 5: Stitch Composition` usually follows a repeatable con
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
-## Source Walkthrough
+## Source Code Walkthrough
+
+### `internal/plugins/template/extension_manager.go`
-Use the following upstream sources to verify implementation details while reading this chapter:
+The `ListExtensions` method in [`internal/plugins/template/extension_manager.go`](https://github.com/danielmiessler/fabric/blob/main/internal/plugins/template/extension_manager.go) shows how Fabric's extension (stitch) system iterates over all registered workflow entries:
-- [GitHub Repository](https://github.com/danielmiessler/Fabric)
- Why it matters: authoritative reference on `GitHub Repository` (github.com).
-- [Pattern Library](https://github.com/danielmiessler/fabric/tree/main/data/patterns)
- Why it matters: authoritative reference on `Pattern Library` (github.com).
-- [Community Patterns](https://github.com/danielmiessler/Fabric#community-patterns)
- Why it matters: authoritative reference on `Community Patterns` (github.com).
-- [AI Codebase Knowledge Builder](https://github.com/johnxie/awesome-code-docs)
- Why it matters: authoritative reference on `AI Codebase Knowledge Builder` (github.com).
+```go
+func (em *ExtensionManager) ListExtensions() error {
+ if em.registry == nil || em.registry.registry.Extensions == nil {
+ return errors.New(i18n.T("extension_registry_not_initialized"))
+ }
+
+ for name, entry := range em.registry.registry.Extensions {
+ fmt.Printf(i18n.T("extension_name_label"), name)
+ // Try to load extension details
+ }
+}
+```
-Suggested trace strategy:
-- search upstream code for `input` and `name` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+Stitches are stored as YAML files in `~/.config/fabric/` alongside patterns. The `ExtensionRegistry` loads them at startup and makes them available as named workflows that chain Fabric pattern calls.
## Chapter Connections
diff --git a/tutorials/fabric-tutorial/06-custom-patterns.md b/tutorials/fabric-tutorial/06-custom-patterns.md
index 6499ac50..61427058 100644
--- a/tutorials/fabric-tutorial/06-custom-patterns.md
+++ b/tutorials/fabric-tutorial/06-custom-patterns.md
@@ -12,6 +12,17 @@ Welcome to **Chapter 6: Custom Patterns**. In this part of **Fabric Tutorial: Op
> Design and implement custom patterns tailored to your specific cognitive tasks and domains.
+## Custom Pattern Development Workflow
+
+```mermaid
+graph TD
+ Design["Design prompt\n(system.md)"] --> Test["Test with fabric --pattern\n--dry-run"]
+ Test --> Iterate["Iterate\n(refine system.md)"]
+ Iterate --> Store["Store in\n~/.config/fabric/patterns/<name>/"]
+ Store --> Share["Share via git\nor fabric --save"]
+ Share --> Update["fabric --update\n(pull from remote)"]
+```
+
## Overview
While Fabric provides many built-in patterns, creating custom patterns allows you to encode your specific expertise and workflows. This chapter covers pattern design principles and implementation techniques.
@@ -584,22 +595,24 @@ Under the hood, `Chapter 6: Custom Patterns` usually follows a repeatable contro
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
-## Source Walkthrough
+## Source Code Walkthrough
-Use the following upstream sources to verify implementation details while reading this chapter:
+### `internal/plugins/template/extension_manager.go`
-- [GitHub Repository](https://github.com/danielmiessler/Fabric)
- Why it matters: authoritative reference on `GitHub Repository` (github.com).
-- [Pattern Library](https://github.com/danielmiessler/fabric/tree/main/data/patterns)
- Why it matters: authoritative reference on `Pattern Library` (github.com).
-- [Community Patterns](https://github.com/danielmiessler/Fabric#community-patterns)
- Why it matters: authoritative reference on `Community Patterns` (github.com).
-- [AI Codebase Knowledge Builder](https://github.com/johnxie/awesome-code-docs)
- Why it matters: authoritative reference on `AI Codebase Knowledge Builder` (github.com).
+The `NewExtensionManager` constructor in [`internal/plugins/template/extension_manager.go`](https://github.com/danielmiessler/fabric/blob/main/internal/plugins/template/extension_manager.go) initializes the custom pattern storage from the user's config directory:
+
+```go
+func NewExtensionManager(configDir string) *ExtensionManager {
+ registry := NewExtensionRegistry(configDir)
+ return &ExtensionManager{
+ registry: registry,
+ executor: NewExtensionExecutor(registry),
+ configDir: configDir,
+ }
+}
+```
-Suggested trace strategy:
-- search upstream code for `Test` and `fabric` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+Custom patterns are stored in `~/.config/fabric/patterns/<pattern-name>/system.md`. The `configDir` is determined by the OS XDG base directories. Running `fabric --list` enumerates all patterns found in the config directory, including both built-in (from `data/patterns/`) and custom user patterns.
## Chapter Connections
diff --git a/tutorials/fabric-tutorial/07-integration-api.md b/tutorials/fabric-tutorial/07-integration-api.md
index 2c49e040..1047f332 100644
--- a/tutorials/fabric-tutorial/07-integration-api.md
+++ b/tutorials/fabric-tutorial/07-integration-api.md
@@ -12,6 +12,20 @@ Welcome to **Chapter 7: Integration & API**. In this part of **Fabric Tutorial:
> Integrate Fabric into applications, automate workflows, and build custom tools using Fabric's API.
+## Integration Architecture
+
+```mermaid
+graph TD
+ App["External App"] --> REST["fabric --serve\n(REST API)"]
+ App --> Pipe["Shell Pipe\necho text | fabric -p <name>"]
+ App --> Script["Script Integration\nbash / Python subprocess"]
+ REST --> Chatter["Chatter.Send()"]
+ Pipe --> Chatter
+ Script --> Chatter
+ Chatter --> Vendor["AI Vendor API"]
+ Vendor --> Response["JSON / streamed response"]
+```
+
## Overview
Fabric can be integrated into larger systems through its REST API, Python SDK, and various automation interfaces. This chapter covers integration patterns for building AI-augmented applications.
@@ -547,22 +561,20 @@ Under the hood, `Chapter 7: Integration & API` usually follows a repeatable cont
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
-## Source Walkthrough
+## Source Code Walkthrough
+
+### `internal/core/plugin_registry.go`
-Use the following upstream sources to verify implementation details while reading this chapter:
+The `NewPluginRegistry` function in [`internal/core/plugin_registry.go`](https://github.com/danielmiessler/fabric/blob/main/internal/core/plugin_registry.go) wires together all AI vendor plugins, tools (YouTube, Jina, Spotify), and strategy plugins into the central registry used by the REST server:
-- [GitHub Repository](https://github.com/danielmiessler/Fabric)
- Why it matters: authoritative reference on `GitHub Repository` (github.com).
-- [Pattern Library](https://github.com/danielmiessler/fabric/tree/main/data/patterns)
- Why it matters: authoritative reference on `Pattern Library` (github.com).
-- [Community Patterns](https://github.com/danielmiessler/Fabric#community-patterns)
- Why it matters: authoritative reference on `Community Patterns` (github.com).
-- [AI Codebase Knowledge Builder](https://github.com/johnxie/awesome-code-docs)
- Why it matters: authoritative reference on `AI Codebase Knowledge Builder` (github.com).
+```go
+func NewPluginRegistry(db *fsdb.Db) (ret *PluginRegistry, err error) {
+ // Imports all vendor plugins:
+ // anthropic, azure, bedrock, codex, copilot, gemini, openai, ollama...
+}
+```
-Suggested trace strategy:
-- search upstream code for `pattern` and `fabric` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+The REST API server (`fabric --serve`) exposes a `/chat` endpoint that accepts a JSON body with `pattern`, `input`, and `model` fields. Responses can be streamed via Server-Sent Events. The `internal/server/` package implements this HTTP layer.
## Chapter Connections
diff --git a/tutorials/fabric-tutorial/08-enterprise-deployment.md b/tutorials/fabric-tutorial/08-enterprise-deployment.md
index b8678dd4..1d775737 100644
--- a/tutorials/fabric-tutorial/08-enterprise-deployment.md
+++ b/tutorials/fabric-tutorial/08-enterprise-deployment.md
@@ -12,6 +12,19 @@ Welcome to **Chapter 8: Enterprise Deployment**. In this part of **Fabric Tutori
> Deploy Fabric at scale with security, compliance, and team collaboration features.
+## Enterprise Deployment Architecture
+
+```mermaid
+graph TD
+ Team["Team Members"] --> Gateway["API Gateway\n(nginx / caddy)"]
+ Gateway --> FabricServer["fabric --serve\n(Go HTTP server)"]
+ FabricServer --> Registry["PluginRegistry\n(vendor plugins)"]
+ Registry --> AzureOAI["Azure OpenAI\n(enterprise endpoint)"]
+ Registry --> Bedrock["AWS Bedrock\n(IAM-controlled)"]
+ FabricServer --> PatternStore["Shared Pattern Store\n(git repo / S3)"]
+ PatternStore --> CustomPatterns["Team Custom Patterns"]
+```
+
## Overview
Enterprise deployment of Fabric requires careful consideration of security, scalability, access control, and governance. This chapter covers production-ready deployment patterns and best practices.
@@ -649,22 +662,23 @@ Under the hood, `Chapter 8: Enterprise Deployment` usually follows a repeatable
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
-## Source Walkthrough
+## Source Code Walkthrough
-Use the following upstream sources to verify implementation details while reading this chapter:
+### `internal/core/plugin_registry.go`
-- [GitHub Repository](https://github.com/danielmiessler/Fabric)
- Why it matters: authoritative reference on `GitHub Repository` (github.com).
-- [Pattern Library](https://github.com/danielmiessler/fabric/tree/main/data/patterns)
- Why it matters: authoritative reference on `Pattern Library` (github.com).
-- [Community Patterns](https://github.com/danielmiessler/Fabric#community-patterns)
- Why it matters: authoritative reference on `Community Patterns` (github.com).
-- [AI Codebase Knowledge Builder](https://github.com/johnxie/awesome-code-docs)
- Why it matters: authoritative reference on `AI Codebase Knowledge Builder` (github.com).
-
-Suggested trace strategy:
-- search upstream code for `fabric` and `patterns` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+The enterprise vendor integrations are all registered via `NewPluginRegistry` in [`internal/core/plugin_registry.go`](https://github.com/danielmiessler/fabric/blob/main/internal/core/plugin_registry.go). It imports Azure, AWS Bedrock, Azure Entra (identity), and GitHub Copilot plugins for enterprise scenarios:
+
+```go
+import (
+ "github.com/danielmiessler/fabric/internal/plugins/ai/azure"
+ "github.com/danielmiessler/fabric/internal/plugins/ai/azure_entra"
+ "github.com/danielmiessler/fabric/internal/plugins/ai/azureaigateway"
+ "github.com/danielmiessler/fabric/internal/plugins/ai/bedrock"
+ "github.com/danielmiessler/fabric/internal/plugins/ai/copilot"
+)
+```
+
+Configuration is stored in `~/.config/fabric/.env` (per-user) or can be overridden via environment variables for container deployments. The `.goreleaser.yaml` at the repo root defines multi-platform binary releases for enterprise distribution via package managers or direct download.
## Chapter Connections
diff --git a/tutorials/fastmcp-tutorial/01-getting-started.md b/tutorials/fastmcp-tutorial/01-getting-started.md
index eb969d3e..7cb6989d 100644
--- a/tutorials/fastmcp-tutorial/01-getting-started.md
+++ b/tutorials/fastmcp-tutorial/01-getting-started.md
@@ -39,186 +39,16 @@ You now have a reliable baseline for expanding FastMCP servers beyond toy exampl
Next: [Chapter 2: Core Abstractions: Components, Providers, Transforms](02-core-abstractions-components-providers-transforms.md)
-## Depth Expansion Playbook
-
-## Source Code Walkthrough
-
-### `scripts/auto_close_needs_mre.py`
-
-The `from` class in [`scripts/auto_close_needs_mre.py`](https://github.com/jlowin/fastmcp/blob/HEAD/scripts/auto_close_needs_mre.py) handles a key part of this chapter's functionality:
-
-```py
-
-This script runs on a schedule to automatically close issues that have been
-marked as "needs MRE" and haven't received activity from the issue author
-within 7 days.
-"""
-
-import os
-from dataclasses import dataclass
-from datetime import datetime, timedelta, timezone
-
-import httpx
-
-
-@dataclass
-class Issue:
- """Represents a GitHub issue."""
-
- number: int
- title: str
- state: str
- created_at: str
- user_id: int
- user_login: str
- body: str | None
-
-
-@dataclass
-class Comment:
- """Represents a GitHub comment."""
-
- id: int
- body: str
-```
-
-This class is important because it defines how FastMCP Tutorial: Building and Operating MCP Servers with Pythonic Control implements the patterns covered in this chapter.
-
-### `scripts/auto_close_needs_mre.py`
-
-The `class` class in [`scripts/auto_close_needs_mre.py`](https://github.com/jlowin/fastmcp/blob/HEAD/scripts/auto_close_needs_mre.py) handles a key part of this chapter's functionality:
-
-```py
-
-import os
-from dataclasses import dataclass
-from datetime import datetime, timedelta, timezone
-
-import httpx
-
-
-@dataclass
-class Issue:
- """Represents a GitHub issue."""
-
- number: int
- title: str
- state: str
- created_at: str
- user_id: int
- user_login: str
- body: str | None
-
-
-@dataclass
-class Comment:
- """Represents a GitHub comment."""
-
- id: int
- body: str
- created_at: str
- user_id: int
- user_login: str
-
-
-```
-
-This class is important because it defines how FastMCP Tutorial: Building and Operating MCP Servers with Pythonic Control implements the patterns covered in this chapter.
-
-### `scripts/auto_close_needs_mre.py`
-
-The `class` class in [`scripts/auto_close_needs_mre.py`](https://github.com/jlowin/fastmcp/blob/HEAD/scripts/auto_close_needs_mre.py) handles a key part of this chapter's functionality:
-
-```py
-
-import os
-from dataclasses import dataclass
-from datetime import datetime, timedelta, timezone
-
-import httpx
-
-
-@dataclass
-class Issue:
- """Represents a GitHub issue."""
-
- number: int
- title: str
- state: str
- created_at: str
- user_id: int
- user_login: str
- body: str | None
-
-
-@dataclass
-class Comment:
- """Represents a GitHub comment."""
-
- id: int
- body: str
- created_at: str
- user_id: int
- user_login: str
-
-
-```
-
-This class is important because it defines how FastMCP Tutorial: Building and Operating MCP Servers with Pythonic Control implements the patterns covered in this chapter.
-
-### `scripts/auto_close_needs_mre.py`
-
-The `class` class in [`scripts/auto_close_needs_mre.py`](https://github.com/jlowin/fastmcp/blob/HEAD/scripts/auto_close_needs_mre.py) handles a key part of this chapter's functionality:
-
-```py
-
-import os
-from dataclasses import dataclass
-from datetime import datetime, timedelta, timezone
-
-import httpx
-
-
-@dataclass
-class Issue:
- """Represents a GitHub issue."""
-
- number: int
- title: str
- state: str
- created_at: str
- user_id: int
- user_login: str
- body: str | None
-
-
-@dataclass
-class Comment:
- """Represents a GitHub comment."""
-
- id: int
- body: str
- created_at: str
- user_id: int
- user_login: str
-
-
-```
-
-This class is important because it defines how FastMCP Tutorial: Building and Operating MCP Servers with Pythonic Control implements the patterns covered in this chapter.
-
-
## How These Components Connect
```mermaid
flowchart TD
- A[from]
- B[class]
- C[class]
- D[class]
- E[GitHubClient]
- A --> B
- B --> C
- C --> D
+ A[Install fastmcp] --> B[Create FastMCP server]
+ B --> C[Define tools with @mcp.tool]
+ B --> D[Define resources with @mcp.resource]
+ C --> E[Run: mcp.run()]
D --> E
+ E --> F{Transport}
+ F -->|stdio| G[Claude Desktop / local host]
+ F -->|SSE/HTTP| H[Remote clients]
```
diff --git a/tutorials/fastmcp-tutorial/02-core-abstractions-components-providers-transforms.md b/tutorials/fastmcp-tutorial/02-core-abstractions-components-providers-transforms.md
index 8835cbe0..3163236f 100644
--- a/tutorials/fastmcp-tutorial/02-core-abstractions-components-providers-transforms.md
+++ b/tutorials/fastmcp-tutorial/02-core-abstractions-components-providers-transforms.md
@@ -43,186 +43,17 @@ You now have a design vocabulary for building maintainable FastMCP surfaces.
Next: [Chapter 3: Server Runtime and Transports](03-server-runtime-and-transports.md)
-## Depth Expansion Playbook
-
-## Source Code Walkthrough
-
-### `scripts/auto_close_duplicates.py`
-
-The `class` class in [`scripts/auto_close_duplicates.py`](https://github.com/jlowin/fastmcp/blob/HEAD/scripts/auto_close_duplicates.py) handles a key part of this chapter's functionality:
-
-```py
-
-import os
-from dataclasses import dataclass
-from datetime import datetime, timedelta, timezone
-
-import httpx
-
-
-@dataclass
-class Issue:
- """Represents a GitHub issue."""
-
- number: int
- title: str
- state: str
- created_at: str
- user_id: int
- user_login: str
-
-
-@dataclass
-class Comment:
- """Represents a GitHub comment."""
-
- id: int
- body: str
- created_at: str
- user_id: int
- user_login: str
- user_type: str
-
-
-```
-
-This class is important because it defines how FastMCP Tutorial: Building and Operating MCP Servers with Pythonic Control implements the patterns covered in this chapter.
-
-### `scripts/auto_close_duplicates.py`
-
-The `class` class in [`scripts/auto_close_duplicates.py`](https://github.com/jlowin/fastmcp/blob/HEAD/scripts/auto_close_duplicates.py) handles a key part of this chapter's functionality:
-
-```py
-
-import os
-from dataclasses import dataclass
-from datetime import datetime, timedelta, timezone
-
-import httpx
-
-
-@dataclass
-class Issue:
- """Represents a GitHub issue."""
-
- number: int
- title: str
- state: str
- created_at: str
- user_id: int
- user_login: str
-
-
-@dataclass
-class Comment:
- """Represents a GitHub comment."""
-
- id: int
- body: str
- created_at: str
- user_id: int
- user_login: str
- user_type: str
-
-
-```
-
-This class is important because it defines how FastMCP Tutorial: Building and Operating MCP Servers with Pythonic Control implements the patterns covered in this chapter.
-
-### `scripts/auto_close_duplicates.py`
-
-The `class` class in [`scripts/auto_close_duplicates.py`](https://github.com/jlowin/fastmcp/blob/HEAD/scripts/auto_close_duplicates.py) handles a key part of this chapter's functionality:
-
-```py
-
-import os
-from dataclasses import dataclass
-from datetime import datetime, timedelta, timezone
-
-import httpx
-
-
-@dataclass
-class Issue:
- """Represents a GitHub issue."""
-
- number: int
- title: str
- state: str
- created_at: str
- user_id: int
- user_login: str
-
-
-@dataclass
-class Comment:
- """Represents a GitHub comment."""
-
- id: int
- body: str
- created_at: str
- user_id: int
- user_login: str
- user_type: str
-
-
-```
-
-This class is important because it defines how FastMCP Tutorial: Building and Operating MCP Servers with Pythonic Control implements the patterns covered in this chapter.
-
-### `scripts/auto_close_duplicates.py`
-
-The `GitHubClient` class in [`scripts/auto_close_duplicates.py`](https://github.com/jlowin/fastmcp/blob/HEAD/scripts/auto_close_duplicates.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-class GitHubClient:
- """Client for interacting with GitHub API."""
-
- def __init__(self, token: str, owner: str, repo: str):
- self.token = token
- self.owner = owner
- self.repo = repo
- self.headers = {
- "Authorization": f"token {token}",
- "Accept": "application/vnd.github.v3+json",
- }
- self.base_url = f"https://api.github.com/repos/{owner}/{repo}"
-
- def get_potential_duplicate_issues(self) -> list[Issue]:
- """Fetch open issues with the potential-duplicate label."""
- url = f"{self.base_url}/issues"
- issues = []
-
- with httpx.Client() as client:
- page = 1
- while page <= 10: # Safety limit
- response = client.get(
- url,
- headers=self.headers,
- params={
- "state": "open",
- "labels": "potential-duplicate",
- "per_page": 100,
- "page": page,
- },
-```
-
-This class is important because it defines how FastMCP Tutorial: Building and Operating MCP Servers with Pythonic Control implements the patterns covered in this chapter.
-
-
## How These Components Connect
```mermaid
flowchart TD
- A[class]
- B[class]
- C[class]
- D[GitHubClient]
- E[find_duplicate_comment]
- A --> B
- B --> C
- C --> D
- D --> E
+ A[FastMCP Server] --> B[Tools]
+ A --> C[Resources]
+ A --> D[Prompts]
+ B --> E[Python function decorated with @mcp.tool]
+ C --> F[URI-addressable data via @mcp.resource]
+ D --> G[Prompt templates via @mcp.prompt]
+ E --> H[MCP ToolResult]
+ F --> I[MCP ResourceContents]
+ G --> J[MCP GetPromptResult]
```
diff --git a/tutorials/fastmcp-tutorial/03-server-runtime-and-transports.md b/tutorials/fastmcp-tutorial/03-server-runtime-and-transports.md
index 66922813..aec2bf87 100644
--- a/tutorials/fastmcp-tutorial/03-server-runtime-and-transports.md
+++ b/tutorials/fastmcp-tutorial/03-server-runtime-and-transports.md
@@ -45,186 +45,15 @@ You now have a transport selection framework that aligns with operational realit
Next: [Chapter 4: Client Architecture and Transport Patterns](04-client-architecture-and-transport-patterns.md)
-## Depth Expansion Playbook
-
-## Source Code Walkthrough
-
-### `examples/mount_example.py`
-
-The `weather_data` function in [`examples/mount_example.py`](https://github.com/jlowin/fastmcp/blob/HEAD/examples/mount_example.py) handles a key part of this chapter's functionality:
-
-```py
-
-@weather_app.resource(uri="weather://forecast")
-async def weather_data():
- """Return current weather data."""
- return {"temperature": 72, "conditions": "sunny", "humidity": 45, "wind_speed": 5}
-
-
-# News sub-application
-news_app = FastMCP("News App")
-
-
-@news_app.tool
-def get_news_headlines() -> list[str]:
- """Get the latest news headlines."""
- return [
- "Tech company launches new product",
- "Local team wins championship",
- "Scientists make breakthrough discovery",
- ]
-
-
-@news_app.resource(uri="news://headlines")
-async def news_data():
- """Return latest news data."""
- return {
- "top_story": "Breaking news: Important event happened",
- "categories": ["politics", "sports", "technology"],
- "sources": ["AP", "Reuters", "Local Sources"],
- }
-
-
-# Main application
-```
-
-This function is important because it defines how FastMCP Tutorial: Building and Operating MCP Servers with Pythonic Control implements the patterns covered in this chapter.
-
-### `examples/mount_example.py`
-
-The `get_news_headlines` function in [`examples/mount_example.py`](https://github.com/jlowin/fastmcp/blob/HEAD/examples/mount_example.py) handles a key part of this chapter's functionality:
-
-```py
-
-@news_app.tool
-def get_news_headlines() -> list[str]:
- """Get the latest news headlines."""
- return [
- "Tech company launches new product",
- "Local team wins championship",
- "Scientists make breakthrough discovery",
- ]
-
-
-@news_app.resource(uri="news://headlines")
-async def news_data():
- """Return latest news data."""
- return {
- "top_story": "Breaking news: Important event happened",
- "categories": ["politics", "sports", "technology"],
- "sources": ["AP", "Reuters", "Local Sources"],
- }
-
-
-# Main application
-app = FastMCP("Main App")
-
-
-@app.tool
-def check_app_status() -> dict[str, str]:
- """Check the status of the main application."""
- return {"status": "running", "version": "1.0.0", "uptime": "3h 24m"}
-
-
-# Mount sub-applications
-```
-
-This function is important because it defines how FastMCP Tutorial: Building and Operating MCP Servers with Pythonic Control implements the patterns covered in this chapter.
-
-### `examples/mount_example.py`
-
-The `news_data` function in [`examples/mount_example.py`](https://github.com/jlowin/fastmcp/blob/HEAD/examples/mount_example.py) handles a key part of this chapter's functionality:
-
-```py
-
-@news_app.resource(uri="news://headlines")
-async def news_data():
- """Return latest news data."""
- return {
- "top_story": "Breaking news: Important event happened",
- "categories": ["politics", "sports", "technology"],
- "sources": ["AP", "Reuters", "Local Sources"],
- }
-
-
-# Main application
-app = FastMCP("Main App")
-
-
-@app.tool
-def check_app_status() -> dict[str, str]:
- """Check the status of the main application."""
- return {"status": "running", "version": "1.0.0", "uptime": "3h 24m"}
-
-
-# Mount sub-applications
-app.mount(server=weather_app, prefix="weather")
-
-app.mount(server=news_app, prefix="news")
-
-
-async def get_server_details():
- """Print information about mounted resources."""
- # Print available tools
- tools = await app.list_tools()
- print(f"\nAvailable tools ({len(tools)}):")
-```
-
-This function is important because it defines how FastMCP Tutorial: Building and Operating MCP Servers with Pythonic Control implements the patterns covered in this chapter.
-
-### `examples/mount_example.py`
-
-The `check_app_status` function in [`examples/mount_example.py`](https://github.com/jlowin/fastmcp/blob/HEAD/examples/mount_example.py) handles a key part of this chapter's functionality:
-
-```py
-
-@app.tool
-def check_app_status() -> dict[str, str]:
- """Check the status of the main application."""
- return {"status": "running", "version": "1.0.0", "uptime": "3h 24m"}
-
-
-# Mount sub-applications
-app.mount(server=weather_app, prefix="weather")
-
-app.mount(server=news_app, prefix="news")
-
-
-async def get_server_details():
- """Print information about mounted resources."""
- # Print available tools
- tools = await app.list_tools()
- print(f"\nAvailable tools ({len(tools)}):")
- for tool in tools:
- print(f" - {tool.name}: {tool.description}")
-
- # Print available resources
- print("\nAvailable resources:")
-
- # Distinguish between native and imported resources
- # Native resources would be those directly in the main app (not prefixed)
-
- resources = await app.list_resources()
-
- native_resources = [
- str(r.uri)
- for r in resources
-```
-
-This function is important because it defines how FastMCP Tutorial: Building and Operating MCP Servers with Pythonic Control implements the patterns covered in this chapter.
-
-
## How These Components Connect
```mermaid
flowchart TD
- A[weather_data]
- B[get_news_headlines]
- C[news_data]
- D[check_app_status]
- E[get_server_details]
- A --> B
- B --> C
- C --> D
- D --> E
+ A[FastMCP Server] --> B{Transport selection}
+ B -->|stdio| C[subprocess pipe]
+ B -->|SSE| D[HTTP /sse endpoint]
+ B -->|Streamable HTTP| E[HTTP /mcp endpoint]
+ C --> F[Local host integration]
+ D --> G[Browser / remote client]
+ E --> H[Modern MCP clients]
```
diff --git a/tutorials/fastmcp-tutorial/04-client-architecture-and-transport-patterns.md b/tutorials/fastmcp-tutorial/04-client-architecture-and-transport-patterns.md
index f7b6bae9..f7934486 100644
--- a/tutorials/fastmcp-tutorial/04-client-architecture-and-transport-patterns.md
+++ b/tutorials/fastmcp-tutorial/04-client-architecture-and-transport-patterns.md
@@ -40,185 +40,16 @@ You now have a client architecture baseline for robust FastMCP integrations.
Next: [Chapter 5: Integrations: Claude Code, Cursor, and Tooling](05-integrations-claude-code-cursor-and-tooling.md)
-## Depth Expansion Playbook
-
-## Source Code Walkthrough
-
-### `scripts/benchmark_imports.py`
-
-The `print_table` function in [`scripts/benchmark_imports.py`](https://github.com/jlowin/fastmcp/blob/HEAD/scripts/benchmark_imports.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def print_table(results: list[dict[str, float | str | None]]) -> None:
- current_group = None
- print(f"\n{'Module':<45} {'Median':>8} {'Min':>8} {'Max':>8}")
- print("-" * 71)
- for r in results:
- if r["group"] != current_group:
- current_group = r["group"]
- group_labels = {
- "floor": "--- Unavoidable floor ---",
- "auth": "--- Auth stack (incremental over mcp) ---",
- "docket": "--- Docket stack (incremental over mcp) ---",
- "other": "--- Other deps (incremental over mcp) ---",
- "fastmcp": "--- FastMCP totals ---",
- }
- print(f"\n{group_labels.get(current_group, current_group)}")
- if r["median_ms"] is not None:
- print(
- f" {r['label']:<43} {r['median_ms']:>7.1f}ms"
- f" {r['min_ms']:>7.1f}ms {r['max_ms']:>7.1f}ms"
- )
- else:
- print(f" {r['label']:<43} error")
-
-
-def main() -> None:
- parser = argparse.ArgumentParser(description="Benchmark fastmcp import times")
- parser.add_argument(
- "--runs", type=int, default=5, help="Number of runs per measurement (default 5)"
- )
- parser.add_argument("--json", action="store_true", help="Output results as JSON")
-```
-
-This function is important because it defines how FastMCP Tutorial: Building and Operating MCP Servers with Pythonic Control implements the patterns covered in this chapter.
-
-### `scripts/benchmark_imports.py`
-
-The `main` function in [`scripts/benchmark_imports.py`](https://github.com/jlowin/fastmcp/blob/HEAD/scripts/benchmark_imports.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def main() -> None:
- parser = argparse.ArgumentParser(description="Benchmark fastmcp import times")
- parser.add_argument(
- "--runs", type=int, default=5, help="Number of runs per measurement (default 5)"
- )
- parser.add_argument("--json", action="store_true", help="Output results as JSON")
- args = parser.parse_args()
-
- print(f"Benchmarking import times ({args.runs} runs each)...")
- print(f"Python: {sys.version.split()[0]}")
- print(f"Executable: {sys.executable}")
-
- results = []
- for case in CASES:
- r = measure(case, args.runs)
- results.append(r)
- if not args.json:
- ms = f"{r['median_ms']:.1f}ms" if r["median_ms"] is not None else "error"
- print(f" {case.label}: {ms}")
-
- if args.json:
- print(json.dumps(results, indent=2))
- else:
- print_table(results)
-
-
-if __name__ == "__main__":
- main()
-
-```
-
-This function is important because it defines how FastMCP Tutorial: Building and Operating MCP Servers with Pythonic Control implements the patterns covered in this chapter.
-
-### `examples/memory.py`
-
-The `from` class in [`examples/memory.py`](https://github.com/jlowin/fastmcp/blob/HEAD/examples/memory.py) handles a key part of this chapter's functionality:
-
-```py
-import math
-import os
-from dataclasses import dataclass
-from datetime import datetime, timezone
-from typing import Annotated, Any, Self
-
-import asyncpg
-import numpy as np
-from openai import AsyncOpenAI
-from pgvector.asyncpg import register_vector
-from pydantic import BaseModel, Field
-from pydantic_ai import Agent
-
-import fastmcp
-from fastmcp import FastMCP
-
-MAX_DEPTH = 5
-SIMILARITY_THRESHOLD = 0.7
-DECAY_FACTOR = 0.99
-REINFORCEMENT_FACTOR = 1.1
-
-DEFAULT_LLM_MODEL = "openai:gpt-4o"
-DEFAULT_EMBEDDING_MODEL = "text-embedding-3-small"
-
-# Dependencies are configured in memory.fastmcp.json
-mcp = FastMCP("memory")
-
-DB_DSN = "postgresql://postgres:postgres@localhost:54320/memory_db"
-# reset memory by deleting the profile directory
-PROFILE_DIR = (
- fastmcp.settings.home / os.environ.get("USER", "anon") / "memory"
-).resolve()
-```
-
-This class is important because it defines how FastMCP Tutorial: Building and Operating MCP Servers with Pythonic Control implements the patterns covered in this chapter.
-
-### `examples/memory.py`
-
-The `class` class in [`examples/memory.py`](https://github.com/jlowin/fastmcp/blob/HEAD/examples/memory.py) handles a key part of this chapter's functionality:
-
-```py
-import math
-import os
-from dataclasses import dataclass
-from datetime import datetime, timezone
-from typing import Annotated, Any, Self
-
-import asyncpg
-import numpy as np
-from openai import AsyncOpenAI
-from pgvector.asyncpg import register_vector
-from pydantic import BaseModel, Field
-from pydantic_ai import Agent
-
-import fastmcp
-from fastmcp import FastMCP
-
-MAX_DEPTH = 5
-SIMILARITY_THRESHOLD = 0.7
-DECAY_FACTOR = 0.99
-REINFORCEMENT_FACTOR = 1.1
-
-DEFAULT_LLM_MODEL = "openai:gpt-4o"
-DEFAULT_EMBEDDING_MODEL = "text-embedding-3-small"
-
-# Dependencies are configured in memory.fastmcp.json
-mcp = FastMCP("memory")
-
-DB_DSN = "postgresql://postgres:postgres@localhost:54320/memory_db"
-# reset memory by deleting the profile directory
-PROFILE_DIR = (
- fastmcp.settings.home / os.environ.get("USER", "anon") / "memory"
-).resolve()
-```
-
-This class is important because it defines how FastMCP Tutorial: Building and Operating MCP Servers with Pythonic Control implements the patterns covered in this chapter.
-
-
## How These Components Connect
```mermaid
flowchart TD
- A[print_table]
- B[main]
- C[from]
- D[class]
- E[MemoryNode]
- A --> B
- B --> C
- C --> D
- D --> E
+ A[FastMCP Client] --> B{Connection type}
+ B -->|stdio| C[Spawns server subprocess]
+ B -->|SSE| D[HTTP event stream]
+ B -->|in-process| E[Direct Python call]
+ C --> F[call_tool / read_resource]
+ D --> F
+ E --> F
+ F --> G[Structured result]
```
diff --git a/tutorials/fastmcp-tutorial/05-integrations-claude-code-cursor-and-tooling.md b/tutorials/fastmcp-tutorial/05-integrations-claude-code-cursor-and-tooling.md
index 233a543c..60138abf 100644
--- a/tutorials/fastmcp-tutorial/05-integrations-claude-code-cursor-and-tooling.md
+++ b/tutorials/fastmcp-tutorial/05-integrations-claude-code-cursor-and-tooling.md
@@ -39,186 +39,16 @@ You now have practical host integration patterns for daily coding workflows.
Next: [Chapter 6: Configuration, Auth, and Deployment](06-configuration-auth-and-deployment.md)
-## Depth Expansion Playbook
-
-## Source Code Walkthrough
-
-### `examples/memory.py`
-
-The `add_memory` function in [`examples/memory.py`](https://github.com/jlowin/fastmcp/blob/HEAD/examples/memory.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-async def add_memory(content: str, deps: Deps):
- new_memory = await MemoryNode.from_content(content, deps)
- await new_memory.save(deps)
-
- similar_memories = await find_similar_memories(new_memory.embedding, deps)
- for memory in similar_memories:
- if memory.id != new_memory.id:
- await new_memory.merge_with(memory, deps)
-
- await update_importance(new_memory.embedding, deps)
-
- await prune_memories(deps)
-
- return f"Remembered: {content}"
-
-
-async def find_similar_memories(embedding: list[float], deps: Deps) -> list[MemoryNode]:
- async with deps.pool.acquire() as conn:
- rows = await conn.fetch(
- """
- SELECT id, content, summary, importance, access_count, timestamp, embedding
- FROM memories
- ORDER BY embedding <-> $1
- LIMIT 5
- """,
- embedding,
- )
- memories = [
- MemoryNode(
- id=row["id"],
-```
-
-This function is important because it defines how FastMCP Tutorial: Building and Operating MCP Servers with Pythonic Control implements the patterns covered in this chapter.
-
-### `examples/memory.py`
-
-The `find_similar_memories` function in [`examples/memory.py`](https://github.com/jlowin/fastmcp/blob/HEAD/examples/memory.py) handles a key part of this chapter's functionality:
-
-```py
- await new_memory.save(deps)
-
- similar_memories = await find_similar_memories(new_memory.embedding, deps)
- for memory in similar_memories:
- if memory.id != new_memory.id:
- await new_memory.merge_with(memory, deps)
-
- await update_importance(new_memory.embedding, deps)
-
- await prune_memories(deps)
-
- return f"Remembered: {content}"
-
-
-async def find_similar_memories(embedding: list[float], deps: Deps) -> list[MemoryNode]:
- async with deps.pool.acquire() as conn:
- rows = await conn.fetch(
- """
- SELECT id, content, summary, importance, access_count, timestamp, embedding
- FROM memories
- ORDER BY embedding <-> $1
- LIMIT 5
- """,
- embedding,
- )
- memories = [
- MemoryNode(
- id=row["id"],
- content=row["content"],
- summary=row["summary"],
- importance=row["importance"],
- access_count=row["access_count"],
-```
-
-This function is important because it defines how FastMCP Tutorial: Building and Operating MCP Servers with Pythonic Control implements the patterns covered in this chapter.
-
-### `examples/memory.py`
-
-The `update_importance` function in [`examples/memory.py`](https://github.com/jlowin/fastmcp/blob/HEAD/examples/memory.py) handles a key part of this chapter's functionality:
-
-```py
- await new_memory.merge_with(memory, deps)
-
- await update_importance(new_memory.embedding, deps)
-
- await prune_memories(deps)
-
- return f"Remembered: {content}"
-
-
-async def find_similar_memories(embedding: list[float], deps: Deps) -> list[MemoryNode]:
- async with deps.pool.acquire() as conn:
- rows = await conn.fetch(
- """
- SELECT id, content, summary, importance, access_count, timestamp, embedding
- FROM memories
- ORDER BY embedding <-> $1
- LIMIT 5
- """,
- embedding,
- )
- memories = [
- MemoryNode(
- id=row["id"],
- content=row["content"],
- summary=row["summary"],
- importance=row["importance"],
- access_count=row["access_count"],
- timestamp=row["timestamp"],
- embedding=row["embedding"],
- )
- for row in rows
- ]
-```
-
-This function is important because it defines how FastMCP Tutorial: Building and Operating MCP Servers with Pythonic Control implements the patterns covered in this chapter.
-
-### `examples/memory.py`
-
-The `prune_memories` function in [`examples/memory.py`](https://github.com/jlowin/fastmcp/blob/HEAD/examples/memory.py) handles a key part of this chapter's functionality:
-
-```py
- await update_importance(new_memory.embedding, deps)
-
- await prune_memories(deps)
-
- return f"Remembered: {content}"
-
-
-async def find_similar_memories(embedding: list[float], deps: Deps) -> list[MemoryNode]:
- async with deps.pool.acquire() as conn:
- rows = await conn.fetch(
- """
- SELECT id, content, summary, importance, access_count, timestamp, embedding
- FROM memories
- ORDER BY embedding <-> $1
- LIMIT 5
- """,
- embedding,
- )
- memories = [
- MemoryNode(
- id=row["id"],
- content=row["content"],
- summary=row["summary"],
- importance=row["importance"],
- access_count=row["access_count"],
- timestamp=row["timestamp"],
- embedding=row["embedding"],
- )
- for row in rows
- ]
- return memories
-
-```
-
-This function is important because it defines how FastMCP Tutorial: Building and Operating MCP Servers with Pythonic Control implements the patterns covered in this chapter.
-
-
## How These Components Connect
```mermaid
flowchart TD
- A[add_memory]
- B[find_similar_memories]
- C[update_importance]
- D[prune_memories]
- E[display_memory_tree]
- A --> B
- B --> C
- C --> D
- D --> E
+ A[FastMCP server running] --> B{Host integration}
+ B -->|Claude Desktop| C[claude_desktop_config.json]
+ B -->|Claude Code| D[mcp add command]
+ B -->|Cursor| E[.cursor/mcp.json]
+ C --> F[Host spawns server via stdio]
+ D --> F
+ E --> F
+ F --> G[Tools available in AI coding session]
```
diff --git a/tutorials/fastmcp-tutorial/06-configuration-auth-and-deployment.md b/tutorials/fastmcp-tutorial/06-configuration-auth-and-deployment.md
index df3f4981..21b8a8c0 100644
--- a/tutorials/fastmcp-tutorial/06-configuration-auth-and-deployment.md
+++ b/tutorials/fastmcp-tutorial/06-configuration-auth-and-deployment.md
@@ -39,186 +39,17 @@ You now have a deployment-ready configuration and auth approach for FastMCP syst
Next: [Chapter 7: Testing, Contributing, and Upgrade Strategy](07-testing-contributing-and-upgrade-strategy.md)
-## Depth Expansion Playbook
-
-## Source Code Walkthrough
-
-### `examples/tags_example.py`
-
-The `get_admin_stats` function in [`examples/tags_example.py`](https://github.com/jlowin/fastmcp/blob/HEAD/examples/tags_example.py) handles a key part of this chapter's functionality:
-
-```py
-
-@app.get("/admin/stats", tags=["admin", "internal"])
-async def get_admin_stats():
- """Get admin statistics - internal use"""
- return {"total_users": 100, "active_sessions": 25}
-
-
-@app.get("/health", tags=["public"])
-async def health_check():
- """Public health check"""
- return {"status": "healthy"}
-
-
-@app.get("/metrics")
-async def get_metrics():
- """Metrics endpoint with no tags"""
- return {"requests": 1000, "errors": 5}
-
-
-async def main():
- """Demonstrate different tag-based routing strategies."""
-
- print("=== Example 1: Make admin-tagged routes tools ===")
-
- # Strategy 1: Convert admin-tagged routes to tools
- mcp1 = FastMCP.from_fastapi(
- app=app,
- route_maps=[
- RouteMap(methods="*", pattern=r".*", mcp_type=MCPType.TOOL, tags={"admin"}),
- RouteMap(methods=["GET"], pattern=r".*", mcp_type=MCPType.RESOURCE),
- ],
- )
-```
-
-This function is important because it defines how FastMCP Tutorial: Building and Operating MCP Servers with Pythonic Control implements the patterns covered in this chapter.
-
-### `examples/tags_example.py`
-
-The `health_check` function in [`examples/tags_example.py`](https://github.com/jlowin/fastmcp/blob/HEAD/examples/tags_example.py) handles a key part of this chapter's functionality:
-
-```py
-
-@app.get("/health", tags=["public"])
-async def health_check():
- """Public health check"""
- return {"status": "healthy"}
-
-
-@app.get("/metrics")
-async def get_metrics():
- """Metrics endpoint with no tags"""
- return {"requests": 1000, "errors": 5}
-
-
-async def main():
- """Demonstrate different tag-based routing strategies."""
-
- print("=== Example 1: Make admin-tagged routes tools ===")
-
- # Strategy 1: Convert admin-tagged routes to tools
- mcp1 = FastMCP.from_fastapi(
- app=app,
- route_maps=[
- RouteMap(methods="*", pattern=r".*", mcp_type=MCPType.TOOL, tags={"admin"}),
- RouteMap(methods=["GET"], pattern=r".*", mcp_type=MCPType.RESOURCE),
- ],
- )
-
- tools = await mcp1.list_tools()
- resources = await mcp1.list_resources()
-
- print(f"Tools ({len(tools)}): {', '.join(t.name for t in tools)}")
- print(f"Resources ({len(resources)}): {', '.join(str(r.uri) for r in resources)}")
-```
-
-This function is important because it defines how FastMCP Tutorial: Building and Operating MCP Servers with Pythonic Control implements the patterns covered in this chapter.
-
-### `examples/tags_example.py`
-
-The `get_metrics` function in [`examples/tags_example.py`](https://github.com/jlowin/fastmcp/blob/HEAD/examples/tags_example.py) handles a key part of this chapter's functionality:
-
-```py
-
-@app.get("/metrics")
-async def get_metrics():
- """Metrics endpoint with no tags"""
- return {"requests": 1000, "errors": 5}
-
-
-async def main():
- """Demonstrate different tag-based routing strategies."""
-
- print("=== Example 1: Make admin-tagged routes tools ===")
-
- # Strategy 1: Convert admin-tagged routes to tools
- mcp1 = FastMCP.from_fastapi(
- app=app,
- route_maps=[
- RouteMap(methods="*", pattern=r".*", mcp_type=MCPType.TOOL, tags={"admin"}),
- RouteMap(methods=["GET"], pattern=r".*", mcp_type=MCPType.RESOURCE),
- ],
- )
-
- tools = await mcp1.list_tools()
- resources = await mcp1.list_resources()
-
- print(f"Tools ({len(tools)}): {', '.join(t.name for t in tools)}")
- print(f"Resources ({len(resources)}): {', '.join(str(r.uri) for r in resources)}")
-
- print("\n=== Example 2: Exclude internal routes ===")
-
- # Strategy 2: Exclude internal routes entirely
- mcp2 = FastMCP.from_fastapi(
- app=app,
-```
-
-This function is important because it defines how FastMCP Tutorial: Building and Operating MCP Servers with Pythonic Control implements the patterns covered in this chapter.
-
-### `examples/tags_example.py`
-
-The `main` function in [`examples/tags_example.py`](https://github.com/jlowin/fastmcp/blob/HEAD/examples/tags_example.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-async def main():
- """Demonstrate different tag-based routing strategies."""
-
- print("=== Example 1: Make admin-tagged routes tools ===")
-
- # Strategy 1: Convert admin-tagged routes to tools
- mcp1 = FastMCP.from_fastapi(
- app=app,
- route_maps=[
- RouteMap(methods="*", pattern=r".*", mcp_type=MCPType.TOOL, tags={"admin"}),
- RouteMap(methods=["GET"], pattern=r".*", mcp_type=MCPType.RESOURCE),
- ],
- )
-
- tools = await mcp1.list_tools()
- resources = await mcp1.list_resources()
-
- print(f"Tools ({len(tools)}): {', '.join(t.name for t in tools)}")
- print(f"Resources ({len(resources)}): {', '.join(str(r.uri) for r in resources)}")
-
- print("\n=== Example 2: Exclude internal routes ===")
-
- # Strategy 2: Exclude internal routes entirely
- mcp2 = FastMCP.from_fastapi(
- app=app,
- route_maps=[
- RouteMap(
- methods="*", pattern=r".*", mcp_type=MCPType.EXCLUDE, tags={"internal"}
- ),
- RouteMap(methods=["GET"], pattern=r".*", mcp_type=MCPType.RESOURCE),
-```
-
-This function is important because it defines how FastMCP Tutorial: Building and Operating MCP Servers with Pythonic Control implements the patterns covered in this chapter.
-
-
## How These Components Connect
```mermaid
flowchart TD
- A[get_admin_stats]
- B[health_check]
- C[get_metrics]
- D[main]
- E[from]
- A --> B
- B --> C
- C --> D
- D --> E
+ A[FastMCP server] --> B{Auth model}
+ B -->|No auth| C[stdio / local only]
+ B -->|Bearer token| D[HTTP Authorization header]
+ B -->|OAuth| E[Token exchange flow]
+ D --> F[Protected HTTP endpoint]
+ E --> F
+ C --> G[Local subprocess]
+ F --> H[Production deployment]
+ H --> I[Docker / cloud service]
```
diff --git a/tutorials/fastmcp-tutorial/07-testing-contributing-and-upgrade-strategy.md b/tutorials/fastmcp-tutorial/07-testing-contributing-and-upgrade-strategy.md
index 5a81d907..764d77b8 100644
--- a/tutorials/fastmcp-tutorial/07-testing-contributing-and-upgrade-strategy.md
+++ b/tutorials/fastmcp-tutorial/07-testing-contributing-and-upgrade-strategy.md
@@ -41,170 +41,16 @@ You now have a safer maintenance model for evolving FastMCP server/client system
Next: [Chapter 8: Production Operations and Governance](08-production-operations-and-governance.md)
-## Depth Expansion Playbook
-
-## Source Code Walkthrough
-
-### `examples/text_me.py`
-
-The `text_me` function in [`examples/text_me.py`](https://github.com/jlowin/fastmcp/blob/HEAD/examples/text_me.py) handles a key part of this chapter's functionality:
-
-```py
-
-@mcp.tool(name="textme", description="Send a text message to me")
-def text_me(text_content: str) -> str:
- """Send a text message to a phone number via https://surgemsg.com/"""
- with httpx.Client() as client:
- response = client.post(
- "https://api.surgemsg.com/messages",
- headers={
- "Authorization": f"Bearer {surge_settings.api_key}",
- "Surge-Account": surge_settings.account_id,
- "Content-Type": "application/json",
- },
- json={
- "body": text_content,
- "conversation": {
- "contact": {
- "first_name": surge_settings.my_first_name,
- "last_name": surge_settings.my_last_name,
- "phone_number": surge_settings.my_phone_number,
- }
- },
- },
- )
- response.raise_for_status()
- return f"Message sent: {text_content}"
-
-```
-
-This function is important because it defines how FastMCP Tutorial: Building and Operating MCP Servers with Pythonic Control implements the patterns covered in this chapter.
-
-### `examples/custom_tool_serializer_decorator.py`
-
-The `with_serializer` function in [`examples/custom_tool_serializer_decorator.py`](https://github.com/jlowin/fastmcp/blob/HEAD/examples/custom_tool_serializer_decorator.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def with_serializer(serializer: Callable[[Any], str]):
- """Decorator to apply custom serialization to tool output."""
-
- def decorator(fn):
- @wraps(fn)
- def wrapper(*args, **kwargs):
- result = fn(*args, **kwargs)
- return ToolResult(content=serializer(result), structured_content=result)
-
- @wraps(fn)
- async def async_wrapper(*args, **kwargs):
- result = await fn(*args, **kwargs)
- return ToolResult(content=serializer(result), structured_content=result)
-
- return async_wrapper if inspect.iscoroutinefunction(fn) else wrapper
-
- return decorator
-
-
-# Create reusable serializer decorators
-with_yaml = with_serializer(lambda d: yaml.dump(d, width=100, sort_keys=False))
-
-server = FastMCP(name="CustomSerializerExample")
-
-
-@server.tool
-@with_yaml
-def get_example_data() -> dict:
- """Returns some example data serialized as YAML."""
- return {"name": "Test", "value": 123, "status": True}
-```
-
-This function is important because it defines how FastMCP Tutorial: Building and Operating MCP Servers with Pythonic Control implements the patterns covered in this chapter.
-
-### `examples/custom_tool_serializer_decorator.py`
-
-The `get_example_data` function in [`examples/custom_tool_serializer_decorator.py`](https://github.com/jlowin/fastmcp/blob/HEAD/examples/custom_tool_serializer_decorator.py) handles a key part of this chapter's functionality:
-
-```py
-@server.tool
-@with_yaml
-def get_example_data() -> dict:
- """Returns some example data serialized as YAML."""
- return {"name": "Test", "value": 123, "status": True}
-
-
-@server.tool
-def get_json_data() -> dict:
- """Returns data with default JSON serialization."""
- return {"format": "json", "data": [1, 2, 3]}
-
-
-async def example_usage():
- # YAML serialized tool
- yaml_result = await server._call_tool_mcp("get_example_data", {})
- print("YAML Tool Result:")
- print(yaml_result)
- print()
-
- # Default JSON serialized tool
- json_result = await server._call_tool_mcp("get_json_data", {})
- print("JSON Tool Result:")
- print(json_result)
-
-
-if __name__ == "__main__":
- asyncio.run(example_usage())
- server.run()
-
-```
-
-This function is important because it defines how FastMCP Tutorial: Building and Operating MCP Servers with Pythonic Control implements the patterns covered in this chapter.
-
-### `examples/custom_tool_serializer_decorator.py`
-
-The `get_json_data` function in [`examples/custom_tool_serializer_decorator.py`](https://github.com/jlowin/fastmcp/blob/HEAD/examples/custom_tool_serializer_decorator.py) handles a key part of this chapter's functionality:
-
-```py
-
-@server.tool
-def get_json_data() -> dict:
- """Returns data with default JSON serialization."""
- return {"format": "json", "data": [1, 2, 3]}
-
-
-async def example_usage():
- # YAML serialized tool
- yaml_result = await server._call_tool_mcp("get_example_data", {})
- print("YAML Tool Result:")
- print(yaml_result)
- print()
-
- # Default JSON serialized tool
- json_result = await server._call_tool_mcp("get_json_data", {})
- print("JSON Tool Result:")
- print(json_result)
-
-
-if __name__ == "__main__":
- asyncio.run(example_usage())
- server.run()
-
-```
-
-This function is important because it defines how FastMCP Tutorial: Building and Operating MCP Servers with Pythonic Control implements the patterns covered in this chapter.
-
-
## How These Components Connect
```mermaid
flowchart TD
- A[text_me]
- B[with_serializer]
- C[get_example_data]
- D[get_json_data]
- E[example_usage]
- A --> B
- B --> C
- C --> D
- D --> E
+ A[FastMCP server code] --> B[Unit tests]
+ B --> C[In-process Client calls]
+ C --> D[Assert tool output]
+ A --> E[Integration tests]
+ E --> F[stdio transport]
+ F --> G[End-to-end tool validation]
+ G --> H[CI pipeline]
+ H --> I[Merge / release]
```
diff --git a/tutorials/fastmcp-tutorial/08-production-operations-and-governance.md b/tutorials/fastmcp-tutorial/08-production-operations-and-governance.md
index 9ef18f22..83028929 100644
--- a/tutorials/fastmcp-tutorial/08-production-operations-and-governance.md
+++ b/tutorials/fastmcp-tutorial/08-production-operations-and-governance.md
@@ -37,186 +37,16 @@ This chapter consolidates day-2 operations, governance, and reliability practice
You now have an end-to-end framework for designing, integrating, and operating FastMCP systems in production.
-## Depth Expansion Playbook
-
-## Source Code Walkthrough
-
-### `examples/elicitation.py`
-
-The `from` class in [`examples/elicitation.py`](https://github.com/jlowin/fastmcp/blob/HEAD/examples/elicitation.py) handles a key part of this chapter's functionality:
-
-```py
-"""
-
-from dataclasses import dataclass
-
-from fastmcp import Context, FastMCP
-
-mcp = FastMCP("Elicitation Demo")
-
-
-@mcp.tool
-async def greet(ctx: Context) -> str:
- """Greet the user by name (asks for their name)."""
- result = await ctx.elicit("What is your name?", response_type=str)
-
- if result.action == "accept":
- return f"Hello, {result.data}!"
- return "Maybe next time!"
-
-
-@mcp.tool
-async def survey(ctx: Context) -> str:
- """Run a short survey collecting structured info."""
-
- @dataclass
- class SurveyResponse:
- favorite_color: str
- lucky_number: int
-
- result = await ctx.elicit(
- "Quick survey — tell us about yourself:",
- response_type=SurveyResponse,
- )
-```
-
-This class is important because it defines how FastMCP Tutorial: Building and Operating MCP Servers with Pythonic Control implements the patterns covered in this chapter.
-
-### `examples/elicitation.py`
-
-The `class` class in [`examples/elicitation.py`](https://github.com/jlowin/fastmcp/blob/HEAD/examples/elicitation.py) handles a key part of this chapter's functionality:
-
-```py
-"""
-
-from dataclasses import dataclass
-
-from fastmcp import Context, FastMCP
-
-mcp = FastMCP("Elicitation Demo")
-
-
-@mcp.tool
-async def greet(ctx: Context) -> str:
- """Greet the user by name (asks for their name)."""
- result = await ctx.elicit("What is your name?", response_type=str)
-
- if result.action == "accept":
- return f"Hello, {result.data}!"
- return "Maybe next time!"
-
-
-@mcp.tool
-async def survey(ctx: Context) -> str:
- """Run a short survey collecting structured info."""
-
- @dataclass
- class SurveyResponse:
- favorite_color: str
- lucky_number: int
-
- result = await ctx.elicit(
- "Quick survey — tell us about yourself:",
- response_type=SurveyResponse,
- )
-```
-
-This class is important because it defines how FastMCP Tutorial: Building and Operating MCP Servers with Pythonic Control implements the patterns covered in this chapter.
-
-### `examples/elicitation.py`
-
-The `greet` function in [`examples/elicitation.py`](https://github.com/jlowin/fastmcp/blob/HEAD/examples/elicitation.py) handles a key part of this chapter's functionality:
-
-```py
-
- fastmcp list examples/elicitation.py
- fastmcp call examples/elicitation.py greet
- fastmcp call examples/elicitation.py survey
-"""
-
-from dataclasses import dataclass
-
-from fastmcp import Context, FastMCP
-
-mcp = FastMCP("Elicitation Demo")
-
-
-@mcp.tool
-async def greet(ctx: Context) -> str:
- """Greet the user by name (asks for their name)."""
- result = await ctx.elicit("What is your name?", response_type=str)
-
- if result.action == "accept":
- return f"Hello, {result.data}!"
- return "Maybe next time!"
-
-
-@mcp.tool
-async def survey(ctx: Context) -> str:
- """Run a short survey collecting structured info."""
-
- @dataclass
- class SurveyResponse:
- favorite_color: str
- lucky_number: int
-
-```
-
-This function is important because it defines how FastMCP Tutorial: Building and Operating MCP Servers with Pythonic Control implements the patterns covered in this chapter.
-
-### `examples/elicitation.py`
-
-The `survey` function in [`examples/elicitation.py`](https://github.com/jlowin/fastmcp/blob/HEAD/examples/elicitation.py) handles a key part of this chapter's functionality:
-
-```py
- fastmcp list examples/elicitation.py
- fastmcp call examples/elicitation.py greet
- fastmcp call examples/elicitation.py survey
-"""
-
-from dataclasses import dataclass
-
-from fastmcp import Context, FastMCP
-
-mcp = FastMCP("Elicitation Demo")
-
-
-@mcp.tool
-async def greet(ctx: Context) -> str:
- """Greet the user by name (asks for their name)."""
- result = await ctx.elicit("What is your name?", response_type=str)
-
- if result.action == "accept":
- return f"Hello, {result.data}!"
- return "Maybe next time!"
-
-
-@mcp.tool
-async def survey(ctx: Context) -> str:
- """Run a short survey collecting structured info."""
-
- @dataclass
- class SurveyResponse:
- favorite_color: str
- lucky_number: int
-
- result = await ctx.elicit(
-```
-
-This function is important because it defines how FastMCP Tutorial: Building and Operating MCP Servers with Pythonic Control implements the patterns covered in this chapter.
-
-
## How These Components Connect
```mermaid
flowchart TD
- A[from]
- B[class]
- C[greet]
- D[survey]
- E[addBanner]
- A --> B
- B --> C
- C --> D
- D --> E
+ A[Production FastMCP server] --> B[Health checks]
+ B --> C{Status}
+ C -->|Healthy| D[Serve MCP requests]
+ C -->|Unhealthy| E[Restart container]
+ D --> F[Structured logging]
+ F --> G[Observability platform]
+ A --> H[Version pinning]
+ H --> I[Staged upgrade testing]
```
diff --git a/tutorials/figma-context-mcp-tutorial/01-getting-started.md b/tutorials/figma-context-mcp-tutorial/01-getting-started.md
index 97227ba6..c8d7b080 100644
--- a/tutorials/figma-context-mcp-tutorial/01-getting-started.md
+++ b/tutorials/figma-context-mcp-tutorial/01-getting-started.md
@@ -44,184 +44,182 @@ You now have a working MCP bridge between Figma and your coding assistant.
Next: [Chapter 2: Architecture and Context Translation](02-architecture-and-context-translation.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/server.ts`
+### `scripts/benchmark-simplify.ts`
-The `startServer` function in [`src/server.ts`](https://github.com/GLips/Figma-Context-MCP/blob/HEAD/src/server.ts) handles a key part of this chapter's functionality:
+The `timedExtractor` function in [`scripts/benchmark-simplify.ts`](https://github.com/GLips/Figma-Context-MCP/blob/HEAD/scripts/benchmark-simplify.ts) handles a key part of this chapter's functionality:
```ts
- * Start the MCP server in either stdio or HTTP mode.
- */
-export async function startServer(): Promise<void> {
- const config = getServerConfig();
-
- const serverOptions = {
- isHTTP: !config.isStdioMode,
- outputFormat: config.outputFormat as "yaml" | "json",
- skipImageDownloads: config.skipImageDownloads,
- imageDir: config.imageDir,
+}
+
+function timedExtractor(fn: ExtractorFn, timing: ExtractorTiming): ExtractorFn {
+ return (node, result, context) => {
+ const start = performance.now();
+ fn(node, result, context);
+ timing.totalMs += performance.now() - start;
+ timing.calls++;
};
+}
- if (config.isStdioMode) {
- const server = createServer(config.auth, serverOptions);
- const transport = new StdioServerTransport();
- await server.connect(transport);
- } else {
- const createMcpServer = () => createServer(config.auth, serverOptions);
- console.log(`Initializing Figma MCP Server in HTTP mode on ${config.host}:${config.port}...`);
- await startHttpServer(config.host, config.port, createMcpServer);
-
- process.on("SIGINT", async () => {
- Logger.log("Shutting down server...");
- await stopHttpServer();
- Logger.log("Server shutdown complete");
- process.exit(0);
- });
+function countOutputNodes(nodes: SimplifiedNode[]): number {
+ let count = 0;
+ for (const node of nodes) {
+ count++;
+ if (node.children) {
+ count += countOutputNodes(node.children);
+ }
}
+ return count;
}
-export async function startHttpServer(
- host: string,
+/** Count objects with id+type fields recursively — rough estimate of Figma node count. */
+function countRawNodes(obj: unknown): number {
+ if (!obj || typeof obj !== "object") return 0;
+ const record = obj as Record<string, unknown>;
+ let count = 0;
+
+ if ("id" in record && "type" in record) count = 1;
+
+ for (const value of Object.values(record)) {
+ if (Array.isArray(value)) {
```
This function is important because it defines how Figma Context MCP Tutorial: Design-to-Code Workflows for Coding Agents implements the patterns covered in this chapter.
-### `src/server.ts`
+### `scripts/benchmark-simplify.ts`
-The `startHttpServer` function in [`src/server.ts`](https://github.com/GLips/Figma-Context-MCP/blob/HEAD/src/server.ts) handles a key part of this chapter's functionality:
+The `countOutputNodes` function in [`scripts/benchmark-simplify.ts`](https://github.com/GLips/Figma-Context-MCP/blob/HEAD/scripts/benchmark-simplify.ts) handles a key part of this chapter's functionality:
```ts
- const createMcpServer = () => createServer(config.auth, serverOptions);
- console.log(`Initializing Figma MCP Server in HTTP mode on ${config.host}:${config.port}...`);
- await startHttpServer(config.host, config.port, createMcpServer);
-
- process.on("SIGINT", async () => {
- Logger.log("Shutting down server...");
- await stopHttpServer();
- Logger.log("Server shutdown complete");
- process.exit(0);
- });
- }
}
-export async function startHttpServer(
- host: string,
- port: number,
- createMcpServer: () => McpServer,
-): Promise<Server> {
- if (httpServer) {
- throw new Error("HTTP server is already running");
+function countOutputNodes(nodes: SimplifiedNode[]): number {
+ let count = 0;
+ for (const node of nodes) {
+ count++;
+ if (node.children) {
+ count += countOutputNodes(node.children);
+ }
}
+ return count;
+}
+
+/** Count objects with id+type fields recursively — rough estimate of Figma node count. */
+function countRawNodes(obj: unknown): number {
+ if (!obj || typeof obj !== "object") return 0;
+ const record = obj as Record<string, unknown>;
+ let count = 0;
+
+ if ("id" in record && "type" in record) count = 1;
- const app = express();
+ for (const value of Object.values(record)) {
+ if (Array.isArray(value)) {
+ for (const item of value) count += countRawNodes(item);
+ } else if (value && typeof value === "object") {
+ count += countRawNodes(value);
+ }
+ }
- // Parse JSON requests for the Streamable HTTP endpoint only, will break SSE endpoint
- app.use("/mcp", express.json());
+ return count;
+}
- // Modern Streamable HTTP endpoint
- app.post("/mcp", async (req, res) => {
- Logger.log("Received StreamableHTTP request");
- const sessionId = req.headers["mcp-session-id"] as string | undefined;
- let transport: StreamableHTTPServerTransport;
```
This function is important because it defines how Figma Context MCP Tutorial: Design-to-Code Workflows for Coding Agents implements the patterns covered in this chapter.
-### `src/server.ts`
+### `scripts/benchmark-simplify.ts`
-The `stopHttpServer` function in [`src/server.ts`](https://github.com/GLips/Figma-Context-MCP/blob/HEAD/src/server.ts) handles a key part of this chapter's functionality:
+The `countRawNodes` function in [`scripts/benchmark-simplify.ts`](https://github.com/GLips/Figma-Context-MCP/blob/HEAD/scripts/benchmark-simplify.ts) handles a key part of this chapter's functionality:
```ts
- process.on("SIGINT", async () => {
- Logger.log("Shutting down server...");
- await stopHttpServer();
- Logger.log("Server shutdown complete");
- process.exit(0);
- });
- }
-}
-export async function startHttpServer(
- host: string,
- port: number,
- createMcpServer: () => McpServer,
-): Promise<Server> {
- if (httpServer) {
- throw new Error("HTTP server is already running");
+/** Count objects with id+type fields recursively — rough estimate of Figma node count. */
+function countRawNodes(obj: unknown): number {
+ if (!obj || typeof obj !== "object") return 0;
+ const record = obj as Record<string, unknown>;
+ let count = 0;
+
+ if ("id" in record && "type" in record) count = 1;
+
+ for (const value of Object.values(record)) {
+ if (Array.isArray(value)) {
+ for (const item of value) count += countRawNodes(item);
+ } else if (value && typeof value === "object") {
+ count += countRawNodes(value);
+ }
}
- const app = express();
+ return count;
+}
- // Parse JSON requests for the Streamable HTTP endpoint only, will break SSE endpoint
- app.use("/mcp", express.json());
+function formatBytes(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`;
+}
- // Modern Streamable HTTP endpoint
- app.post("/mcp", async (req, res) => {
- Logger.log("Received StreamableHTTP request");
- const sessionId = req.headers["mcp-session-id"] as string | undefined;
- let transport: StreamableHTTPServerTransport;
+function formatMs(ms: number): string {
+ if (ms < 1000) return `${ms.toFixed(1)} ms`;
+ return `${(ms / 1000).toFixed(2)} s`;
+}
- if (sessionId && sessions[sessionId]) {
- // Reuse existing transport
- Logger.log("Reusing existing StreamableHTTP transport for sessionId", sessionId);
+async function main() {
```
This function is important because it defines how Figma Context MCP Tutorial: Design-to-Code Workflows for Coding Agents implements the patterns covered in this chapter.
-### `src/services/figma.ts`
+### `scripts/benchmark-simplify.ts`
-The `FigmaService` class in [`src/services/figma.ts`](https://github.com/GLips/Figma-Context-MCP/blob/HEAD/src/services/figma.ts) handles a key part of this chapter's functionality:
+The `formatBytes` function in [`scripts/benchmark-simplify.ts`](https://github.com/GLips/Figma-Context-MCP/blob/HEAD/scripts/benchmark-simplify.ts) handles a key part of this chapter's functionality:
```ts
-};
-
-export class FigmaService {
- private readonly apiKey: string;
- private readonly oauthToken: string;
- private readonly useOAuth: boolean;
- private readonly baseUrl = "https://api.figma.com/v1";
-
- constructor({ figmaApiKey, figmaOAuthToken, useOAuth }: FigmaAuthOptions) {
- this.apiKey = figmaApiKey || "";
- this.oauthToken = figmaOAuthToken || "";
- this.useOAuth = !!useOAuth && !!this.oauthToken;
+}
+
+function formatBytes(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`;
+}
+
+function formatMs(ms: number): string {
+ if (ms < 1000) return `${ms.toFixed(1)} ms`;
+ return `${(ms / 1000).toFixed(2)} s`;
+}
+
+async function main() {
+ if (!existsSync(INPUT_PATH)) {
+ console.error(
+ `Input file not found: ${INPUT_PATH}\n\n` +
+ `Run the server in dev mode and fetch a Figma file first.\n` +
+ `The server writes raw API responses to logs/figma-raw.json.`,
+ );
+ process.exit(1);
}
- private getAuthHeaders(): Record<string, string> {
- if (this.useOAuth) {
- Logger.log("Using OAuth Bearer token for authentication");
- return { Authorization: `Bearer ${this.oauthToken}` };
- } else {
- Logger.log("Using Personal Access Token for authentication");
- return { "X-Figma-Token": this.apiKey };
- }
+ let session: Session | undefined;
+ if (PROFILE_FLAG) {
+ session = new Session();
+ session.connect();
+ await session.post("Profiler.enable");
+ await session.post("Profiler.start");
+ console.log("CPU profiler started\n");
}
- /**
- * Filters out null values from Figma image responses. This ensures we only work with valid image URLs.
- */
- private filterValidImages(
- images: { [key: string]: string | null } | undefined,
- ): Record<string, string> {
- if (!images) return {};
- return Object.fromEntries(Object.entries(images).filter(([, value]) => !!value)) as Record<
```
-This class is important because it defines how Figma Context MCP Tutorial: Design-to-Code Workflows for Coding Agents implements the patterns covered in this chapter.
+This function is important because it defines how Figma Context MCP Tutorial: Design-to-Code Workflows for Coding Agents implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[startServer]
- B[startHttpServer]
- C[stopHttpServer]
- D[FigmaService]
- E[findOrCreateVar]
+ A[timedExtractor]
+ B[countOutputNodes]
+ C[countRawNodes]
+ D[formatBytes]
+ E[formatMs]
A --> B
B --> C
C --> D
diff --git a/tutorials/figma-context-mcp-tutorial/02-architecture-and-context-translation.md b/tutorials/figma-context-mcp-tutorial/02-architecture-and-context-translation.md
index 678e75ca..ef74789a 100644
--- a/tutorials/figma-context-mcp-tutorial/02-architecture-and-context-translation.md
+++ b/tutorials/figma-context-mcp-tutorial/02-architecture-and-context-translation.md
@@ -38,10 +38,49 @@ You now understand the transformation layer that makes MCP design context effect
Next: [Chapter 3: Frame Targeting and Context Scope](03-frame-targeting-and-context-scope.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
+### `src/server.ts`
+
+The `stopHttpServer` function in [`src/server.ts`](https://github.com/GLips/Figma-Context-MCP/blob/HEAD/src/server.ts) handles a key part of this chapter's functionality:
+
+```ts
+ process.on("SIGINT", async () => {
+ Logger.log("Shutting down server...");
+ await stopHttpServer();
+ Logger.log("Server shutdown complete");
+ process.exit(0);
+ });
+ }
+}
+
+export async function startHttpServer(
+ host: string,
+ port: number,
+ createMcpServer: () => McpServer,
+): Promise<Server> {
+ if (httpServer) {
+ throw new Error("HTTP server is already running");
+ }
+
+ const app = createMcpExpressApp({ host });
+
+ const handlePost = async (req: Request, res: Response) => {
+ Logger.log("Received StreamableHTTP request");
+ const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+ const mcpServer = createMcpServer();
+ const conn: ActiveConnection = { transport, server: mcpServer };
+ activeConnections.add(conn);
+ res.on("close", () => {
+ activeConnections.delete(conn);
+ transport.close();
+ mcpServer.close();
+ });
+ await mcpServer.connect(transport);
+```
+
+This function is important because it defines how Figma Context MCP Tutorial: Design-to-Code Workflows for Coding Agents implements the patterns covered in this chapter.
+
### `src/config.ts`
The `envStr` function in [`src/config.ts`](https://github.com/GLips/Figma-Context-MCP/blob/HEAD/src/config.ts) handles a key part of this chapter's functionality:
@@ -165,57 +204,16 @@ export function getServerConfig(): ServerConfig {
This function is important because it defines how Figma Context MCP Tutorial: Design-to-Code Workflows for Coding Agents implements the patterns covered in this chapter.
-### `src/config.ts`
-
-The `maskApiKey` function in [`src/config.ts`](https://github.com/GLips/Figma-Context-MCP/blob/HEAD/src/config.ts) handles a key part of this chapter's functionality:
-
-```ts
-}
-
-function maskApiKey(key: string): string {
- if (!key || key.length <= 4) return "****";
- return `****${key.slice(-4)}`;
-}
-
-export function getServerConfig(): ServerConfig {
- const argv = cli({
- name: "figma-developer-mcp",
- version: process.env.NPM_PACKAGE_VERSION ?? "unknown",
- flags: {
- figmaApiKey: {
- type: String,
- description: "Figma API key (Personal Access Token)",
- },
- figmaOauthToken: {
- type: String,
- description: "Figma OAuth Bearer token",
- },
- env: {
- type: String,
- description: "Path to custom .env file to load environment variables from",
- },
- port: {
- type: Number,
- description: "Port to run the server on",
- },
- host: {
- type: String,
- description: "Host to run the server on",
- },
-```
-
-This function is important because it defines how Figma Context MCP Tutorial: Design-to-Code Workflows for Coding Agents implements the patterns covered in this chapter.
-
## How These Components Connect
```mermaid
flowchart TD
- A[envStr]
- B[envInt]
- C[envBool]
- D[maskApiKey]
- E[getServerConfig]
+ A[stopHttpServer]
+ B[envStr]
+ C[envInt]
+ D[envBool]
+ E[maskApiKey]
A --> B
B --> C
C --> D
diff --git a/tutorials/figma-context-mcp-tutorial/03-frame-targeting-and-context-scope.md b/tutorials/figma-context-mcp-tutorial/03-frame-targeting-and-context-scope.md
index 14e0bfc5..58566a8e 100644
--- a/tutorials/figma-context-mcp-tutorial/03-frame-targeting-and-context-scope.md
+++ b/tutorials/figma-context-mcp-tutorial/03-frame-targeting-and-context-scope.md
@@ -27,170 +27,168 @@ You now have practical scoping techniques that improve one-shot implementation q
Next: [Chapter 4: Prompt Patterns for One-Shot UI Implementation](04-prompt-patterns-for-one-shot-ui-implementation.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/transformers/style.ts`
+### `src/extractors/built-in.ts`
-The `generateTransformHash` function in [`src/transformers/style.ts`](https://github.com/GLips/Figma-Context-MCP/blob/HEAD/src/transformers/style.ts) handles a key part of this chapter's functionality:
+The `getStyleCache` function in [`src/extractors/built-in.ts`](https://github.com/GLips/Figma-Context-MCP/blob/HEAD/src/extractors/built-in.ts) handles a key part of this chapter's functionality:
```ts
- * @returns Short hash string for filename suffix
- */
-function generateTransformHash(transform: Transform): string {
- const values = transform.flat();
- const hash = values.reduce((acc, val) => {
- // Simple hash function - convert to string and create checksum
- const str = val.toString();
- for (let i = 0; i < str.length; i++) {
- acc = ((acc << 5) - acc + str.charCodeAt(i)) & 0xffffffff;
- }
- return acc;
- }, 0);
+const styleCaches = new WeakMap<GlobalVars, Map<string, string>>();
- // Convert to positive hex string, take first 6 chars
- return Math.abs(hash).toString(16).substring(0, 6);
+function getStyleCache(globalVars: GlobalVars): Map<string, string> {
+ let cache = styleCaches.get(globalVars);
+ if (!cache) {
+ cache = new Map();
+ styleCaches.set(globalVars, cache);
+ }
+ return cache;
}
/**
- * Handle imageTransform for post-processing (not CSS translation)
- *
- * When Figma includes an imageTransform matrix, it means the image is cropped/transformed.
- * This function converts the transform into processing instructions for Sharp.
- *
- * @param imageTransform - Figma's 2x3 transform matrix [[scaleX, skewX, translateX], [skewY, scaleY, translateY]]
- * @returns Processing metadata for image cropping
+ * Find an existing global style variable with the same value, or create one.
*/
-function handleImageTransform(
- imageTransform: Transform,
-): NonNullable<SimplifiedImageFill["imageDownloadArguments"]> {
- const transformHash = generateTransformHash(imageTransform);
- return {
- needsCropping: true,
-```
-
-This function is important because it defines how Figma Context MCP Tutorial: Design-to-Code Workflows for Coding Agents implements the patterns covered in this chapter.
+function findOrCreateVar(globalVars: GlobalVars, value: StyleTypes, prefix: string): string {
+ const cache = getStyleCache(globalVars);
+ const key = JSON.stringify(value);
-### `src/transformers/style.ts`
+ const existing = cache.get(key);
+ if (existing) return existing;
-The `handleImageTransform` function in [`src/transformers/style.ts`](https://github.com/GLips/Figma-Context-MCP/blob/HEAD/src/transformers/style.ts) handles a key part of this chapter's functionality:
-
-```ts
- * @returns Processing metadata for image cropping
- */
-function handleImageTransform(
- imageTransform: Transform,
-): NonNullable<SimplifiedImageFill["imageDownloadArguments"]> {
- const transformHash = generateTransformHash(imageTransform);
- return {
- needsCropping: true,
- requiresImageDimensions: false,
- cropTransform: imageTransform,
- filenameSuffix: `${transformHash}`,
- };
+ const varId = generateVarId(prefix);
+ globalVars.styles[varId] = value;
+ cache.set(key, varId);
+ return varId;
}
/**
- * Build simplified stroke information from a Figma node
- *
- * @param n - The Figma node to extract stroke information from
- * @param hasChildren - Whether the node has children (affects paint processing)
- * @returns Simplified stroke object with colors and properties
+ * Extracts layout-related properties from a node.
*/
-export function buildSimplifiedStrokes(
- n: FigmaDocumentNode,
- hasChildren: boolean = false,
-): SimplifiedStroke {
- let strokes: SimplifiedStroke = { colors: [] };
- if (hasValue("strokes", n) && Array.isArray(n.strokes) && n.strokes.length) {
- strokes.colors = n.strokes.filter(isVisible).map((stroke) => parsePaint(stroke, hasChildren));
- }
-
- if (hasValue("strokeWeight", n) && typeof n.strokeWeight === "number" && n.strokeWeight > 0) {
- strokes.strokeWeight = `${n.strokeWeight}px`;
+export const layoutExtractor: ExtractorFn = (node, result, context) => {
+ const layout = buildSimplifiedLayout(node, context.parent);
```
This function is important because it defines how Figma Context MCP Tutorial: Design-to-Code Workflows for Coding Agents implements the patterns covered in this chapter.
-### `src/transformers/style.ts`
+### `src/extractors/built-in.ts`
-The `buildSimplifiedStrokes` function in [`src/transformers/style.ts`](https://github.com/GLips/Figma-Context-MCP/blob/HEAD/src/transformers/style.ts) handles a key part of this chapter's functionality:
+The `findOrCreateVar` function in [`src/extractors/built-in.ts`](https://github.com/GLips/Figma-Context-MCP/blob/HEAD/src/extractors/built-in.ts) handles a key part of this chapter's functionality:
```ts
- * @returns Simplified stroke object with colors and properties
+ * Find an existing global style variable with the same value, or create one.
*/
-export function buildSimplifiedStrokes(
- n: FigmaDocumentNode,
- hasChildren: boolean = false,
-): SimplifiedStroke {
- let strokes: SimplifiedStroke = { colors: [] };
- if (hasValue("strokes", n) && Array.isArray(n.strokes) && n.strokes.length) {
- strokes.colors = n.strokes.filter(isVisible).map((stroke) => parsePaint(stroke, hasChildren));
- }
+function findOrCreateVar(globalVars: GlobalVars, value: StyleTypes, prefix: string): string {
+ const cache = getStyleCache(globalVars);
+ const key = JSON.stringify(value);
- if (hasValue("strokeWeight", n) && typeof n.strokeWeight === "number" && n.strokeWeight > 0) {
- strokes.strokeWeight = `${n.strokeWeight}px`;
- }
+ const existing = cache.get(key);
+ if (existing) return existing;
- if (hasValue("strokeDashes", n) && Array.isArray(n.strokeDashes) && n.strokeDashes.length) {
- strokes.strokeDashes = n.strokeDashes;
- }
+ const varId = generateVarId(prefix);
+ globalVars.styles[varId] = value;
+ cache.set(key, varId);
+ return varId;
+}
- if (hasValue("individualStrokeWeights", n, isStrokeWeights)) {
- strokes.strokeWeight = generateCSSShorthand(n.individualStrokeWeights);
+/**
+ * Extracts layout-related properties from a node.
+ */
+export const layoutExtractor: ExtractorFn = (node, result, context) => {
+ const layout = buildSimplifiedLayout(node, context.parent);
+ if (Object.keys(layout).length > 1) {
+ result.layout = findOrCreateVar(context.globalVars, layout, "layout");
}
-
- return strokes;
-}
+};
/**
- * Convert a Figma paint (solid, image, gradient) to a SimplifiedFill
- * @param raw - The Figma paint to convert
- * @param hasChildren - Whether the node has children (determines CSS properties)
- * @returns The converted SimplifiedFill
+ * Extracts text content and text styling from a node.
*/
+export const textExtractor: ExtractorFn = (node, result, context) => {
+ // Extract text content
+ if (isTextNode(node)) {
+ result.text = extractNodeText(node);
```
This function is important because it defines how Figma Context MCP Tutorial: Design-to-Code Workflows for Coding Agents implements the patterns covered in this chapter.
-### `src/transformers/style.ts`
+### `src/extractors/built-in.ts`
-The `parsePaint` function in [`src/transformers/style.ts`](https://github.com/GLips/Figma-Context-MCP/blob/HEAD/src/transformers/style.ts) handles a key part of this chapter's functionality:
+The `getStyleName` function in [`src/extractors/built-in.ts`](https://github.com/GLips/Figma-Context-MCP/blob/HEAD/src/extractors/built-in.ts) handles a key part of this chapter's functionality:
```ts
- let strokes: SimplifiedStroke = { colors: [] };
- if (hasValue("strokes", n) && Array.isArray(n.strokes) && n.strokes.length) {
- strokes.colors = n.strokes.filter(isVisible).map((stroke) => parsePaint(stroke, hasChildren));
+ if (textStyle) {
+ // Prefer Figma named style when available
+ const styleName = getStyleName(node, context, ["text", "typography"]);
+ if (styleName) {
+ context.globalVars.styles[styleName] = textStyle;
+ result.textStyle = styleName;
+ } else {
+ result.textStyle = findOrCreateVar(context.globalVars, textStyle, "style");
+ }
+ }
}
+};
- if (hasValue("strokeWeight", n) && typeof n.strokeWeight === "number" && n.strokeWeight > 0) {
- strokes.strokeWeight = `${n.strokeWeight}px`;
+/**
+ * Extracts visual appearance properties (fills, strokes, effects, opacity, border radius).
+ */
+export const visualsExtractor: ExtractorFn = (node, result, context) => {
+ // Check if node has children to determine CSS properties
+ const hasChildren =
+ hasValue("children", node) && Array.isArray(node.children) && node.children.length > 0;
+
+ // fills
+ if (hasValue("fills", node) && Array.isArray(node.fills) && node.fills.length) {
+ const fills = node.fills.map((fill) => parsePaint(fill, hasChildren)).reverse();
+ const styleName = getStyleName(node, context, ["fill", "fills"]);
+ if (styleName) {
+ context.globalVars.styles[styleName] = fills;
+ result.fills = styleName;
+ } else {
+ result.fills = findOrCreateVar(context.globalVars, fills, "fill");
+ }
}
+```
- if (hasValue("strokeDashes", n) && Array.isArray(n.strokeDashes) && n.strokeDashes.length) {
- strokes.strokeDashes = n.strokeDashes;
- }
+This function is important because it defines how Figma Context MCP Tutorial: Design-to-Code Workflows for Coding Agents implements the patterns covered in this chapter.
+
+### `src/extractors/built-in.ts`
+
+The `collapseSvgContainers` function in [`src/extractors/built-in.ts`](https://github.com/GLips/Figma-Context-MCP/blob/HEAD/src/extractors/built-in.ts) handles a key part of this chapter's functionality:
- if (hasValue("individualStrokeWeights", n, isStrokeWeights)) {
- strokes.strokeWeight = generateCSSShorthand(n.individualStrokeWeights);
+```ts
+ * @returns Children to include (empty array if collapsed)
+ */
+export function collapseSvgContainers(
+ node: FigmaDocumentNode,
+ result: SimplifiedNode,
+ children: SimplifiedNode[],
+): SimplifiedNode[] {
+ const allChildrenAreSvgEligible = children.every((child) => SVG_ELIGIBLE_TYPES.has(child.type));
+
+ if (
+ (node.type === "FRAME" ||
+ node.type === "GROUP" ||
+ node.type === "INSTANCE" ||
+ node.type === "BOOLEAN_OPERATION") &&
+ allChildrenAreSvgEligible &&
+ !hasImageFillInChildren(node)
+ ) {
+ // Collapse to IMAGE-SVG and omit children
+ result.type = "IMAGE-SVG";
+ return [];
}
- return strokes;
+ // Include all children normally
+ return children;
}
/**
- * Convert a Figma paint (solid, image, gradient) to a SimplifiedFill
- * @param raw - The Figma paint to convert
- * @param hasChildren - Whether the node has children (determines CSS properties)
- * @returns The converted SimplifiedFill
- */
-export function parsePaint(raw: Paint, hasChildren: boolean = false): SimplifiedFill {
- if (raw.type === "IMAGE") {
- const baseImageFill: SimplifiedImageFill = {
- type: "IMAGE",
- imageRef: raw.imageRef,
- ...(raw.gifRef ? { gifRef: raw.gifRef } : {}),
+ * Check whether a node or its direct children have image fills.
+ *
+ * Only direct children need checking because afterChildren runs bottom-up:
+ * if a deeper descendant has image fills, its parent won't collapse (stays FRAME),
+ * and FRAME isn't SVG-eligible, so the chain breaks naturally at each level.
```
This function is important because it defines how Figma Context MCP Tutorial: Design-to-Code Workflows for Coding Agents implements the patterns covered in this chapter.
@@ -200,11 +198,11 @@ This function is important because it defines how Figma Context MCP Tutorial: De
```mermaid
flowchart TD
- A[generateTransformHash]
- B[handleImageTransform]
- C[buildSimplifiedStrokes]
- D[parsePaint]
- E[parsePatternPaint]
+ A[getStyleCache]
+ B[findOrCreateVar]
+ C[getStyleName]
+ D[collapseSvgContainers]
+ E[hasImageFillInChildren]
A --> B
B --> C
C --> D
diff --git a/tutorials/figma-context-mcp-tutorial/04-prompt-patterns-for-one-shot-ui-implementation.md b/tutorials/figma-context-mcp-tutorial/04-prompt-patterns-for-one-shot-ui-implementation.md
index 3e36c3ce..123020ff 100644
--- a/tutorials/figma-context-mcp-tutorial/04-prompt-patterns-for-one-shot-ui-implementation.md
+++ b/tutorials/figma-context-mcp-tutorial/04-prompt-patterns-for-one-shot-ui-implementation.md
@@ -32,184 +32,182 @@ You now have prompt patterns that convert design context into higher-fidelity co
Next: [Chapter 5: MCP Client Integrations](05-mcp-client-integrations.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/transformers/style.ts`
+### `src/transformers/layout.ts`
-The `mapGradientStops` function in [`src/transformers/style.ts`](https://github.com/GLips/Figma-Context-MCP/blob/HEAD/src/transformers/style.ts) handles a key part of this chapter's functionality:
+The `convertSizing` function in [`src/transformers/layout.ts`](https://github.com/GLips/Figma-Context-MCP/blob/HEAD/src/transformers/layout.ts) handles a key part of this chapter's functionality:
```ts
- * Map gradient stops from Figma's handle-based coordinate system to CSS percentages
- */
-function mapGradientStops(
- gradient: Extract<
- Paint,
- { type: "GRADIENT_LINEAR" | "GRADIENT_RADIAL" | "GRADIENT_ANGULAR" | "GRADIENT_DIAMOND" }
- >,
- elementBounds: { width: number; height: number } = { width: 1, height: 1 },
-): { stops: string; cssGeometry: string } {
- const handles = gradient.gradientHandlePositions;
- if (!handles || handles.length < 2) {
- const stops = gradient.gradientStops
- .map(({ position, color }) => {
- const cssColor = formatRGBAColor(color, 1);
- return `${cssColor} ${Math.round(position * 100)}%`;
- })
- .join(", ");
- return { stops, cssGeometry: "0deg" };
+
+// interpret sizing
+function convertSizing(
+ s?: HasLayoutTrait["layoutSizingHorizontal"] | HasLayoutTrait["layoutSizingVertical"],
+) {
+ if (s === "FIXED") return "fixed";
+ if (s === "FILL") return "fill";
+ if (s === "HUG") return "hug";
+ return undefined;
+}
+
+function buildSimplifiedFrameValues(n: FigmaDocumentNode): SimplifiedLayout | { mode: "none" } {
+ if (!isFrame(n)) {
+ return { mode: "none" };
}
- const [handle1, handle2, handle3] = handles;
-
- switch (gradient.type) {
- case "GRADIENT_LINEAR": {
- return mapLinearGradient(gradient.gradientStops, handle1, handle2, elementBounds);
- }
- case "GRADIENT_RADIAL": {
- return mapRadialGradient(gradient.gradientStops, handle1, handle2, handle3, elementBounds);
- }
- case "GRADIENT_ANGULAR": {
- return mapAngularGradient(gradient.gradientStops, handle1, handle2, handle3, elementBounds);
- }
+ const frameValues: SimplifiedLayout = {
+ mode:
+ !n.layoutMode || n.layoutMode === "NONE"
+ ? "none"
+ : n.layoutMode === "HORIZONTAL"
+ ? "row"
+ : "column",
+ };
+
+ const overflowScroll: SimplifiedLayout["overflowScroll"] = [];
+ if (n.overflowDirection?.includes("HORIZONTAL")) overflowScroll.push("x");
+ if (n.overflowDirection?.includes("VERTICAL")) overflowScroll.push("y");
+ if (overflowScroll.length > 0) frameValues.overflowScroll = overflowScroll;
+
+ if (frameValues.mode === "none") {
+ return frameValues;
```
This function is important because it defines how Figma Context MCP Tutorial: Design-to-Code Workflows for Coding Agents implements the patterns covered in this chapter.
-### `src/transformers/style.ts`
+### `src/transformers/layout.ts`
-The `mapLinearGradient` function in [`src/transformers/style.ts`](https://github.com/GLips/Figma-Context-MCP/blob/HEAD/src/transformers/style.ts) handles a key part of this chapter's functionality:
+The `buildSimplifiedFrameValues` function in [`src/transformers/layout.ts`](https://github.com/GLips/Figma-Context-MCP/blob/HEAD/src/transformers/layout.ts) handles a key part of this chapter's functionality:
```ts
- switch (gradient.type) {
- case "GRADIENT_LINEAR": {
- return mapLinearGradient(gradient.gradientStops, handle1, handle2, elementBounds);
- }
- case "GRADIENT_RADIAL": {
- return mapRadialGradient(gradient.gradientStops, handle1, handle2, handle3, elementBounds);
- }
- case "GRADIENT_ANGULAR": {
- return mapAngularGradient(gradient.gradientStops, handle1, handle2, handle3, elementBounds);
- }
- case "GRADIENT_DIAMOND": {
- return mapDiamondGradient(gradient.gradientStops, handle1, handle2, handle3, elementBounds);
- }
- default: {
- const stops = gradient.gradientStops
- .map(({ position, color }) => {
- const cssColor = formatRGBAColor(color, 1);
- return `${cssColor} ${Math.round(position * 100)}%`;
- })
- .join(", ");
- return { stops, cssGeometry: "0deg" };
- }
+ parent?: FigmaDocumentNode,
+): SimplifiedLayout {
+ const frameValues = buildSimplifiedFrameValues(n);
+ const layoutValues = buildSimplifiedLayoutValues(n, parent, frameValues.mode) || {};
+
+ return { ...frameValues, ...layoutValues };
+}
+
+function convertJustifyContent(align?: HasFramePropertiesTrait["primaryAxisAlignItems"]) {
+ switch (align) {
+ case "MIN":
+ return undefined;
+ case "MAX":
+ return "flex-end";
+ case "CENTER":
+ return "center";
+ case "SPACE_BETWEEN":
+ return "space-between";
+ default:
+ return undefined;
}
}
-/**
- * Map linear gradient from Figma handles to CSS
- */
-function mapLinearGradient(
- gradientStops: { position: number; color: RGBA }[],
- start: Vector,
- end: Vector,
+function convertAlignItems(
+ align: HasFramePropertiesTrait["counterAxisAlignItems"] | undefined,
+ children: FigmaDocumentNode[],
+ mode: "row" | "column",
+) {
+ // Row cross-axis is vertical; column cross-axis is horizontal
+ const crossSizing = mode === "row" ? "layoutSizingVertical" : "layoutSizingHorizontal";
+ const allStretch =
+ children.length > 0 &&
```
This function is important because it defines how Figma Context MCP Tutorial: Design-to-Code Workflows for Coding Agents implements the patterns covered in this chapter.
-### `src/transformers/style.ts`
+### `src/transformers/layout.ts`
-The `findExtendedLineIntersections` function in [`src/transformers/style.ts`](https://github.com/GLips/Figma-Context-MCP/blob/HEAD/src/transformers/style.ts) handles a key part of this chapter's functionality:
+The `buildSimplifiedLayoutValues` function in [`src/transformers/layout.ts`](https://github.com/GLips/Figma-Context-MCP/blob/HEAD/src/transformers/layout.ts) handles a key part of this chapter's functionality:
```ts
+): SimplifiedLayout {
+ const frameValues = buildSimplifiedFrameValues(n);
+ const layoutValues = buildSimplifiedLayoutValues(n, parent, frameValues.mode) || {};
+
+ return { ...frameValues, ...layoutValues };
+}
- // Find where the extended gradient line intersects the element boundaries
- const extendedIntersections = findExtendedLineIntersections(start, end);
-
- if (extendedIntersections.length >= 2) {
- // The gradient line extended to fill the element
- const fullLineStart = Math.min(extendedIntersections[0], extendedIntersections[1]);
- const fullLineEnd = Math.max(extendedIntersections[0], extendedIntersections[1]);
- // Map gradient stops from the Figma line segment to the full CSS line
- const mappedStops = gradientStops.map(({ position, color }) => {
- const cssColor = formatRGBAColor(color, 1);
-
- // Position along the Figma gradient line (0 = start handle, 1 = end handle)
- const figmaLinePosition = position;
-
- // The Figma line spans from t=0 to t=1
- // The full extended line spans from fullLineStart to fullLineEnd
- // Map the figma position to the extended line
- const tOnExtendedLine = figmaLinePosition * (1 - 0) + 0; // This is just figmaLinePosition
- const extendedPosition = (tOnExtendedLine - fullLineStart) / (fullLineEnd - fullLineStart);
- const clampedPosition = Math.max(0, Math.min(1, extendedPosition));
-
- return `${cssColor} ${Math.round(clampedPosition * 100)}%`;
- });
-
- return {
- stops: mappedStops.join(", "),
- cssGeometry: `${Math.round(angle)}deg`,
- };
+function convertJustifyContent(align?: HasFramePropertiesTrait["primaryAxisAlignItems"]) {
+ switch (align) {
+ case "MIN":
+ return undefined;
+ case "MAX":
+ return "flex-end";
+ case "CENTER":
+ return "center";
+ case "SPACE_BETWEEN":
+ return "space-between";
+ default:
+ return undefined;
}
+}
- // Fallback to simple gradient if intersection calculation fails
+function convertAlignItems(
+ align: HasFramePropertiesTrait["counterAxisAlignItems"] | undefined,
+ children: FigmaDocumentNode[],
+ mode: "row" | "column",
+) {
+ // Row cross-axis is vertical; column cross-axis is horizontal
+ const crossSizing = mode === "row" ? "layoutSizingVertical" : "layoutSizingHorizontal";
+ const allStretch =
+ children.length > 0 &&
+ children.every(
```
This function is important because it defines how Figma Context MCP Tutorial: Design-to-Code Workflows for Coding Agents implements the patterns covered in this chapter.
-### `src/transformers/style.ts`
+### `src/transformers/layout.ts`
-The `mapRadialGradient` function in [`src/transformers/style.ts`](https://github.com/GLips/Figma-Context-MCP/blob/HEAD/src/transformers/style.ts) handles a key part of this chapter's functionality:
+The `SimplifiedLayout` interface in [`src/transformers/layout.ts`](https://github.com/GLips/Figma-Context-MCP/blob/HEAD/src/transformers/layout.ts) handles a key part of this chapter's functionality:
```ts
- }
- case "GRADIENT_RADIAL": {
- return mapRadialGradient(gradient.gradientStops, handle1, handle2, handle3, elementBounds);
- }
- case "GRADIENT_ANGULAR": {
- return mapAngularGradient(gradient.gradientStops, handle1, handle2, handle3, elementBounds);
- }
- case "GRADIENT_DIAMOND": {
- return mapDiamondGradient(gradient.gradientStops, handle1, handle2, handle3, elementBounds);
- }
- default: {
- const stops = gradient.gradientStops
- .map(({ position, color }) => {
- const cssColor = formatRGBAColor(color, 1);
- return `${cssColor} ${Math.round(position * 100)}%`;
- })
- .join(", ");
- return { stops, cssGeometry: "0deg" };
- }
- }
+import { generateCSSShorthand, pixelRound } from "~/utils/common.js";
+
+export interface SimplifiedLayout {
+ mode: "none" | "row" | "column";
+ justifyContent?: "flex-start" | "flex-end" | "center" | "space-between" | "baseline" | "stretch";
+ alignItems?: "flex-start" | "flex-end" | "center" | "space-between" | "baseline" | "stretch";
+ alignSelf?: "flex-start" | "flex-end" | "center" | "stretch";
+ wrap?: boolean;
+ gap?: string;
+ locationRelativeToParent?: {
+ x: number;
+ y: number;
+ };
+ dimensions?: {
+ width?: number;
+ height?: number;
+ aspectRatio?: number;
+ };
+ padding?: string;
+ sizing?: {
+ horizontal?: "fixed" | "fill" | "hug";
+ vertical?: "fixed" | "fill" | "hug";
+ };
+ overflowScroll?: ("x" | "y")[];
+ position?: "absolute";
}
-/**
- * Map linear gradient from Figma handles to CSS
- */
-function mapLinearGradient(
- gradientStops: { position: number; color: RGBA }[],
- start: Vector,
- end: Vector,
- _elementBounds: { width: number; height: number },
-): { stops: string; cssGeometry: string } {
- // Calculate the gradient line in element space
+// Convert Figma's layout config into a more typical flex-like schema
+export function buildSimplifiedLayout(
+ n: FigmaDocumentNode,
+ parent?: FigmaDocumentNode,
+): SimplifiedLayout {
```
-This function is important because it defines how Figma Context MCP Tutorial: Design-to-Code Workflows for Coding Agents implements the patterns covered in this chapter.
+This interface is important because it defines how Figma Context MCP Tutorial: Design-to-Code Workflows for Coding Agents implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[mapGradientStops]
- B[mapLinearGradient]
- C[findExtendedLineIntersections]
- D[mapRadialGradient]
- E[mapAngularGradient]
+ A[convertSizing]
+ B[buildSimplifiedFrameValues]
+ C[buildSimplifiedLayoutValues]
+ D[SimplifiedLayout]
+ E[translateScaleMode]
A --> B
B --> C
C --> D
diff --git a/tutorials/figma-context-mcp-tutorial/05-mcp-client-integrations.md b/tutorials/figma-context-mcp-tutorial/05-mcp-client-integrations.md
index 272f5739..b253d2eb 100644
--- a/tutorials/figma-context-mcp-tutorial/05-mcp-client-integrations.md
+++ b/tutorials/figma-context-mcp-tutorial/05-mcp-client-integrations.md
@@ -26,169 +26,168 @@ You now know how to operationalize Figma Context MCP across coding-agent clients
Next: [Chapter 6: Performance and Token Optimization](06-performance-and-token-optimization.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/utils/image-processing.ts`
+### `src/transformers/style.ts`
-The `applyCropTransform` function in [`src/utils/image-processing.ts`](https://github.com/GLips/Figma-Context-MCP/blob/HEAD/src/utils/image-processing.ts) handles a key part of this chapter's functionality:
+The `parsePatternPaint` function in [`src/transformers/style.ts`](https://github.com/GLips/Figma-Context-MCP/blob/HEAD/src/transformers/style.ts) handles a key part of this chapter's functionality:
```ts
- * @returns Promise<string> - Path to the cropped image
+ }
+ } else if (raw.type === "PATTERN") {
+ return parsePatternPaint(raw);
+ } else if (
+ ["GRADIENT_LINEAR", "GRADIENT_RADIAL", "GRADIENT_ANGULAR", "GRADIENT_DIAMOND"].includes(
+ raw.type,
+ )
+ ) {
+ return {
+ type: raw.type as
+ | "GRADIENT_LINEAR"
+ | "GRADIENT_RADIAL"
+ | "GRADIENT_ANGULAR"
+ | "GRADIENT_DIAMOND",
+ gradient: convertGradientToCss(raw),
+ };
+ } else {
+ throw new Error(`Unknown paint type: ${raw.type}`);
+ }
+}
+
+/**
+ * Convert a Figma PatternPaint to a CSS-like pattern fill.
+ *
+ * Ignores `tileType` and `spacing` from the Figma API currently as there's
+ * no great way to translate them to CSS.
+ *
+ * @param raw - The Figma PatternPaint to convert
+ * @returns The converted pattern SimplifiedFill
*/
-export async function applyCropTransform(
- imagePath: string,
- cropTransform: Transform,
-): Promise<string> {
- const { Logger } = await import("./logger.js");
-
- try {
- // Extract transform values (skew values intentionally unused for now)
- const scaleX = cropTransform[0]?.[0] ?? 1;
- const translateX = cropTransform[0]?.[2] ?? 0;
- const scaleY = cropTransform[1]?.[1] ?? 1;
- const translateY = cropTransform[1]?.[2] ?? 0;
-
- const image = await Jimp.read(imagePath);
- const { width, height } = image;
-
- // Calculate crop region based on transform matrix
- // Figma's transform matrix represents how the image is positioned within its container
- // We need to extract the visible portion based on the scaling and translation
-
- // The transform matrix defines the visible area as:
- // - scaleX/scaleY: how much of the original image is visible (0-1)
- // - translateX/translateY: offset of the visible area (0-1, relative to image size)
-
- const cropLeft = Math.max(0, Math.round(translateX * width));
- const cropTop = Math.max(0, Math.round(translateY * height));
- const cropWidth = Math.min(width - cropLeft, Math.round(scaleX * width));
- const cropHeight = Math.min(height - cropTop, Math.round(scaleY * height));
-
- if (cropWidth <= 0 || cropHeight <= 0) {
+function parsePatternPaint(
+ raw: Extract<Paint, { type: "PATTERN" }>,
```
This function is important because it defines how Figma Context MCP Tutorial: Design-to-Code Workflows for Coding Agents implements the patterns covered in this chapter.
-### `src/utils/image-processing.ts`
+### `src/transformers/style.ts`
-The `getImageDimensions` function in [`src/utils/image-processing.ts`](https://github.com/GLips/Figma-Context-MCP/blob/HEAD/src/utils/image-processing.ts) handles a key part of this chapter's functionality:
+The `hexToRgba` function in [`src/transformers/style.ts`](https://github.com/GLips/Figma-Context-MCP/blob/HEAD/src/transformers/style.ts) handles a key part of this chapter's functionality:
```ts
- * @returns Promise<{width: number, height: number}>
+ * @returns Color string in rgba format
*/
-export async function getImageDimensions(imagePath: string): Promise<{
- width: number;
- height: number;
-}> {
- const image = await Jimp.read(imagePath);
- return { width: image.width, height: image.height };
-}
+export function hexToRgba(hex: string, opacity: number = 1): string {
+ // Remove possible # prefix
+ hex = hex.replace("#", "");
+
+ // Handle shorthand hex values (e.g., #FFF)
+ if (hex.length === 3) {
+ hex = hex[0] + hex[0] + hex[1] + hex[1] + hex[2] + hex[2];
+ }
+
+ // Convert hex to RGB values
+ const r = parseInt(hex.substring(0, 2), 16);
+ const g = parseInt(hex.substring(2, 4), 16);
+ const b = parseInt(hex.substring(4, 6), 16);
-export type ImageProcessingResult = {
- filePath: string;
- originalDimensions: { width: number; height: number };
- finalDimensions: { width: number; height: number };
- wasCropped: boolean;
- cropRegion?: { left: number; top: number; width: number; height: number };
- cssVariables?: string;
- processingLog: string[];
-};
+ // Ensure opacity is in the 0-1 range
+ const validOpacity = Math.min(Math.max(opacity, 0), 1);
+
+ return `rgba(${r}, ${g}, ${b}, ${validOpacity})`;
+}
/**
- * Enhanced image download with post-processing
- * @param fileName - The filename to save as
- * @param localPath - The local path to save to
- * @param imageUrl - Image URL
- * @param needsCropping - Whether to apply crop transform
- * @param cropTransform - Transform matrix for cropping
- * @param requiresImageDimensions - Whether to generate dimension metadata
- * @returns Promise<ImageProcessingResult> - Detailed processing information
- */
-export async function downloadAndProcessImage(
- fileName: string,
+ * Convert color from RGBA to { hex, opacity }
+ *
+ * @param color - The color to convert, including alpha channel
+ * @param opacity - The opacity of the color, if not included in alpha channel
+ * @returns The converted color
+ **/
+export function convertColor(color: RGBA, opacity = 1): ColorValue {
+ const r = Math.round(color.r * 255);
+ const g = Math.round(color.g * 255);
```
This function is important because it defines how Figma Context MCP Tutorial: Design-to-Code Workflows for Coding Agents implements the patterns covered in this chapter.
-### `src/utils/image-processing.ts`
+### `src/transformers/style.ts`
-The `downloadAndProcessImage` function in [`src/utils/image-processing.ts`](https://github.com/GLips/Figma-Context-MCP/blob/HEAD/src/utils/image-processing.ts) handles a key part of this chapter's functionality:
+The `convertColor` function in [`src/transformers/style.ts`](https://github.com/GLips/Figma-Context-MCP/blob/HEAD/src/transformers/style.ts) handles a key part of this chapter's functionality:
```ts
- * @returns Promise<ImageProcessingResult> - Detailed processing information
- */
-export async function downloadAndProcessImage(
- fileName: string,
- localPath: string,
- imageUrl: string,
- needsCropping: boolean = false,
- cropTransform?: Transform,
- requiresImageDimensions: boolean = false,
-): Promise<ImageProcessingResult> {
- const { Logger } = await import("./logger.js");
- const processingLog: string[] = [];
-
- // First download the original image
- const { downloadFigmaImage } = await import("./common.js");
- const originalPath = await downloadFigmaImage(fileName, localPath, imageUrl);
- Logger.log(`Downloaded original image: ${originalPath}`);
-
- // SVGs are vector — jimp can't read them and cropping/dimensions don't apply
- const isSvg = fileName.toLowerCase().endsWith(".svg");
- if (isSvg) {
+ } else if (raw.type === "SOLID") {
+ // treat as SOLID
+ const { hex, opacity } = convertColor(raw.color!, raw.opacity);
+ if (opacity === 1) {
+ return hex;
+ } else {
+ return formatRGBAColor(raw.color!, opacity);
+ }
+ } else if (raw.type === "PATTERN") {
+ return parsePatternPaint(raw);
+ } else if (
+ ["GRADIENT_LINEAR", "GRADIENT_RADIAL", "GRADIENT_ANGULAR", "GRADIENT_DIAMOND"].includes(
+ raw.type,
+ )
+ ) {
return {
- filePath: originalPath,
- originalDimensions: { width: 0, height: 0 },
- finalDimensions: { width: 0, height: 0 },
- wasCropped: false,
- processingLog,
+ type: raw.type as
+ | "GRADIENT_LINEAR"
+ | "GRADIENT_RADIAL"
+ | "GRADIENT_ANGULAR"
+ | "GRADIENT_DIAMOND",
+ gradient: convertGradientToCss(raw),
};
+ } else {
+ throw new Error(`Unknown paint type: ${raw.type}`);
}
+}
- // Get original dimensions before any processing
- const originalDimensions = await getImageDimensions(originalPath);
+/**
+ * Convert a Figma PatternPaint to a CSS-like pattern fill.
+ *
+ * Ignores `tileType` and `spacing` from the Figma API currently as there's
```
This function is important because it defines how Figma Context MCP Tutorial: Design-to-Code Workflows for Coding Agents implements the patterns covered in this chapter.
-### `src/utils/image-processing.ts`
+### `src/transformers/style.ts`
-The `generateImageCSSVariables` function in [`src/utils/image-processing.ts`](https://github.com/GLips/Figma-Context-MCP/blob/HEAD/src/utils/image-processing.ts) handles a key part of this chapter's functionality:
+The `formatRGBAColor` function in [`src/transformers/style.ts`](https://github.com/GLips/Figma-Context-MCP/blob/HEAD/src/transformers/style.ts) handles a key part of this chapter's functionality:
```ts
- let cssVariables: string | undefined;
- if (requiresImageDimensions) {
- cssVariables = generateImageCSSVariables(finalDimensions);
+ return hex;
+ } else {
+ return formatRGBAColor(raw.color!, opacity);
+ }
+ } else if (raw.type === "PATTERN") {
+ return parsePatternPaint(raw);
+ } else if (
+ ["GRADIENT_LINEAR", "GRADIENT_RADIAL", "GRADIENT_ANGULAR", "GRADIENT_DIAMOND"].includes(
+ raw.type,
+ )
+ ) {
+ return {
+ type: raw.type as
+ | "GRADIENT_LINEAR"
+ | "GRADIENT_RADIAL"
+ | "GRADIENT_ANGULAR"
+ | "GRADIENT_DIAMOND",
+ gradient: convertGradientToCss(raw),
+ };
+ } else {
+ throw new Error(`Unknown paint type: ${raw.type}`);
}
-
- return {
- filePath: finalPath,
- originalDimensions,
- finalDimensions,
- wasCropped,
- cropRegion,
- cssVariables,
- processingLog,
- };
}
/**
- * Create CSS custom properties for image dimensions
- * @param imagePath - Path to the image file
- * @returns Promise<string> - CSS custom properties
- */
-export function generateImageCSSVariables({
- width,
- height,
-}: {
- width: number;
- height: number;
-}): string {
- return `--original-width: ${width}px; --original-height: ${height}px;`;
-}
-
+ * Convert a Figma PatternPaint to a CSS-like pattern fill.
+ *
+ * Ignores `tileType` and `spacing` from the Figma API currently as there's
+ * no great way to translate them to CSS.
+ *
+ * @param raw - The Figma PatternPaint to convert
+ * @returns The converted pattern SimplifiedFill
```
This function is important because it defines how Figma Context MCP Tutorial: Design-to-Code Workflows for Coding Agents implements the patterns covered in this chapter.
@@ -198,11 +197,11 @@ This function is important because it defines how Figma Context MCP Tutorial: De
```mermaid
flowchart TD
- A[applyCropTransform]
- B[getImageDimensions]
- C[downloadAndProcessImage]
- D[generateImageCSSVariables]
- E[extractFromDesign]
+ A[parsePatternPaint]
+ B[hexToRgba]
+ C[convertColor]
+ D[formatRGBAColor]
+ E[mapGradientStops]
A --> B
B --> C
C --> D
diff --git a/tutorials/figma-context-mcp-tutorial/06-performance-and-token-optimization.md b/tutorials/figma-context-mcp-tutorial/06-performance-and-token-optimization.md
index d8573a97..cd9cbd61 100644
--- a/tutorials/figma-context-mcp-tutorial/06-performance-and-token-optimization.md
+++ b/tutorials/figma-context-mcp-tutorial/06-performance-and-token-optimization.md
@@ -27,170 +27,168 @@ You now have token and latency controls for efficient design-to-code workflows.
Next: [Chapter 7: Team Workflows and Design Governance](07-team-workflows-and-design-governance.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/extractors/node-walker.ts`
+### `src/transformers/style.ts`
-The `shouldTraverseChildren` function in [`src/extractors/node-walker.ts`](https://github.com/GLips/Figma-Context-MCP/blob/HEAD/src/extractors/node-walker.ts) handles a key part of this chapter's functionality:
+The `mapDiamondGradient` function in [`src/transformers/style.ts`](https://github.com/GLips/Figma-Context-MCP/blob/HEAD/src/transformers/style.ts) handles a key part of this chapter's functionality:
```ts
-
- // Handle children recursively
- if (shouldTraverseChildren(node, context, options)) {
- const childContext: TraversalContext = {
- ...context,
- currentDepth: context.currentDepth + 1,
- parent: node,
- };
-
- // Use the same pattern as the existing parseNode function
- if (hasValue("children", node) && node.children.length > 0) {
- const children = node.children
- .filter((child) => shouldProcessNode(child, options))
- .map((child) => processNodeWithExtractors(child, extractors, childContext, options))
- .filter((child): child is SimplifiedNode => child !== null);
-
- if (children.length > 0) {
- // Allow custom logic to modify parent and control which children to include
- const childrenToInclude = options.afterChildren
- ? options.afterChildren(node, result, children)
- : children;
-
- if (childrenToInclude.length > 0) {
- result.children = childrenToInclude;
- }
- }
+ }
+ case "GRADIENT_DIAMOND": {
+ return mapDiamondGradient(gradient.gradientStops, handle1, handle2, handle3, elementBounds);
+ }
+ default: {
+ const stops = gradient.gradientStops
+ .map(({ position, color }) => {
+ const cssColor = formatRGBAColor(color, 1);
+ return `${cssColor} ${Math.round(position * 100)}%`;
+ })
+ .join(", ");
+ return { stops, cssGeometry: "0deg" };
}
}
-
- return result;
}
+/**
+ * Map linear gradient from Figma handles to CSS
+ */
+function mapLinearGradient(
+ gradientStops: { position: number; color: RGBA }[],
+ start: Vector,
+ end: Vector,
+ _elementBounds: { width: number; height: number },
+): { stops: string; cssGeometry: string } {
+ // Calculate the gradient line in element space
+ const dx = end.x - start.x;
+ const dy = end.y - start.y;
+ const gradientLength = Math.sqrt(dx * dx + dy * dy);
+
+ // Handle degenerate case
+ if (gradientLength === 0) {
```
This function is important because it defines how Figma Context MCP Tutorial: Design-to-Code Workflows for Coding Agents implements the patterns covered in this chapter.
-### `src/utils/common.ts`
+### `src/transformers/style.ts`
-The `downloadFigmaImage` function in [`src/utils/common.ts`](https://github.com/GLips/Figma-Context-MCP/blob/HEAD/src/utils/common.ts) handles a key part of this chapter's functionality:
+The `convertGradientToCss` function in [`src/transformers/style.ts`](https://github.com/GLips/Figma-Context-MCP/blob/HEAD/src/transformers/style.ts) handles a key part of this chapter's functionality:
```ts
- * @throws Error if download fails
- */
-export async function downloadFigmaImage(
- fileName: string,
- localPath: string,
- imageUrl: string,
-): Promise<string> {
- try {
- // Ensure local path exists
- if (!fs.existsSync(localPath)) {
- fs.mkdirSync(localPath, { recursive: true });
- }
-
- // Build the complete file path and verify it stays within localPath
- const fullPath = path.resolve(path.join(localPath, fileName));
- const resolvedLocalPath = path.resolve(localPath);
- if (!fullPath.startsWith(resolvedLocalPath + path.sep)) {
- throw new Error(`File path escapes target directory: ${fileName}`);
- }
-
- // Use fetch to download the image
- const response = await fetch(imageUrl, {
- method: "GET",
- });
-
- if (!response.ok) {
- throw new Error(`Failed to download image: ${response.statusText}`);
- }
-
- // Create write stream
- const writer = fs.createWriteStream(fullPath);
+ | "GRADIENT_ANGULAR"
+ | "GRADIENT_DIAMOND",
+ gradient: convertGradientToCss(raw),
+ };
+ } else {
+ throw new Error(`Unknown paint type: ${raw.type}`);
+ }
+}
+/**
+ * Convert a Figma PatternPaint to a CSS-like pattern fill.
+ *
+ * Ignores `tileType` and `spacing` from the Figma API currently as there's
+ * no great way to translate them to CSS.
+ *
+ * @param raw - The Figma PatternPaint to convert
+ * @returns The converted pattern SimplifiedFill
+ */
+function parsePatternPaint(
+ raw: Extract<Paint, { type: "PATTERN" }>,
+): Extract<SimplifiedFill, { type: "PATTERN" }> {
+ /**
+ * The only CSS-like repeat value supported by Figma is repeat.
+ *
+ * They also have hexagonal horizontal and vertical repeats, but
+ * those aren't easy to pull off in CSS, so we just use repeat.
+ */
+ let backgroundRepeat = "repeat";
+
+ let horizontal = "left";
+ switch (raw.horizontalAlignment) {
+ case "START":
```
This function is important because it defines how Figma Context MCP Tutorial: Design-to-Code Workflows for Coding Agents implements the patterns covered in this chapter.
-### `src/utils/common.ts`
+### `src/transformers/style.ts`
-The `generateVarId` function in [`src/utils/common.ts`](https://github.com/GLips/Figma-Context-MCP/blob/HEAD/src/utils/common.ts) handles a key part of this chapter's functionality:
+The `ColorValue` interface in [`src/transformers/style.ts`](https://github.com/GLips/Figma-Context-MCP/blob/HEAD/src/transformers/style.ts) handles a key part of this chapter's functionality:
```ts
- * @returns A 6-character random ID string with prefix
- */
-export function generateVarId(prefix: string = "var"): StyleId {
- const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
- let result = "";
-
- for (let i = 0; i < 6; i++) {
- const randomIndex = Math.floor(Math.random() * chars.length);
- result += chars[randomIndex];
- }
-
- return `${prefix}_${result}` as StyleId;
+export type CSSRGBAColor = `rgba(${number}, ${number}, ${number}, ${number})`;
+export type CSSHexColor = `#${string}`;
+export interface ColorValue {
+ hex: CSSHexColor;
+ opacity: number;
}
/**
- * Generate a CSS shorthand for values that come with top, right, bottom, and left
- *
- * input: { top: 10, right: 10, bottom: 10, left: 10 }
- * output: "10px"
- *
- * input: { top: 10, right: 20, bottom: 10, left: 20 }
- * output: "10px 20px"
+ * Simplified image fill with CSS properties and processing metadata
*
- * input: { top: 10, right: 20, bottom: 30, left: 40 }
- * output: "10px 20px 30px 40px"
+ * This type represents an image fill that can be used as either:
+ * - background-image (when parent node has children)
+ * - <img> tag (when parent node has no children)
*
- * @param values - The values to generate the shorthand for
- * @returns The generated shorthand
+ * The CSS properties are mutually exclusive based on usage context.
*/
-export function generateCSSShorthand(
- values: {
- top: number;
+export type SimplifiedImageFill = {
+ type: "IMAGE";
+ imageRef: string;
+ /**
+ * Present when the fill is an animated GIF. Use this ref (instead of imageRef) when calling
+ * download_figma_images to retrieve the animated GIF file; imageRef only points to a static
+ * snapshot frame.
+ */
+ gifRef?: string;
+ scaleMode: "FILL" | "FIT" | "TILE" | "STRETCH";
+ /**
+ * For TILE mode, the scaling factor relative to original image size
+ */
+ scalingFactor?: number;
+
+ // CSS properties for background-image usage (when node has children)
```
-This function is important because it defines how Figma Context MCP Tutorial: Design-to-Code Workflows for Coding Agents implements the patterns covered in this chapter.
+This interface is important because it defines how Figma Context MCP Tutorial: Design-to-Code Workflows for Coding Agents implements the patterns covered in this chapter.
-### `src/utils/common.ts`
+### `src/extractors/node-walker.ts`
-The `generateCSSShorthand` function in [`src/utils/common.ts`](https://github.com/GLips/Figma-Context-MCP/blob/HEAD/src/utils/common.ts) handles a key part of this chapter's functionality:
+The `getNodesProcessed` function in [`src/extractors/node-walker.ts`](https://github.com/GLips/Figma-Context-MCP/blob/HEAD/src/extractors/node-walker.ts) handles a key part of this chapter's functionality:
```ts
- * @returns The generated shorthand
- */
-export function generateCSSShorthand(
- values: {
- top: number;
- right: number;
- bottom: number;
- left: number;
- },
- {
- ignoreZero = true,
- suffix = "px",
- }: {
- /**
- * If true and all values are 0, return undefined. Defaults to true.
- */
- ignoreZero?: boolean;
- /**
- * The suffix to add to the shorthand. Defaults to "px".
- */
- suffix?: string;
- } = {},
-) {
- const { top, right, bottom, left } = values;
- if (ignoreZero && top === 0 && right === 0 && bottom === 0 && left === 0) {
- return undefined;
- }
- if (top === right && right === bottom && bottom === left) {
- return `${top}${suffix}`;
+let nodesProcessed = 0;
+
+export function getNodesProcessed(): number {
+ return nodesProcessed;
+}
+
+async function maybeYield(): Promise<void> {
+ nodesProcessed++;
+ if (nodesProcessed % YIELD_INTERVAL === 0) {
+ await new Promise<void>((resolve) => setImmediate(resolve));
}
- if (right === left) {
- if (top === bottom) {
+}
+
+/**
+ * Extract data from Figma nodes using a flexible, single-pass approach.
+ *
+ * @param nodes - The Figma nodes to process
+ * @param extractors - Array of extractor functions to apply during traversal
+ * @param options - Traversal options (filtering, depth limits, etc.)
+ * @param globalVars - Global variables for style deduplication
+ * @returns Object containing processed nodes and updated global variables
+ */
+export async function extractFromDesign(
+ nodes: FigmaDocumentNode[],
+ extractors: ExtractorFn[],
+ options: TraversalOptions = {},
+ globalVars: GlobalVars = { styles: {} },
+): Promise<{ nodes: SimplifiedNode[]; globalVars: GlobalVars }> {
+ const context: TraversalContext = {
+ globalVars,
+ currentDepth: 0,
+ };
```
This function is important because it defines how Figma Context MCP Tutorial: Design-to-Code Workflows for Coding Agents implements the patterns covered in this chapter.
@@ -200,11 +198,11 @@ This function is important because it defines how Figma Context MCP Tutorial: De
```mermaid
flowchart TD
- A[shouldTraverseChildren]
- B[downloadFigmaImage]
- C[generateVarId]
- D[generateCSSShorthand]
- E[isVisible]
+ A[mapDiamondGradient]
+ B[convertGradientToCss]
+ C[ColorValue]
+ D[getNodesProcessed]
+ E[maybeYield]
A --> B
B --> C
C --> D
diff --git a/tutorials/figma-context-mcp-tutorial/07-team-workflows-and-design-governance.md b/tutorials/figma-context-mcp-tutorial/07-team-workflows-and-design-governance.md
index b0f28488..c793691b 100644
--- a/tutorials/figma-context-mcp-tutorial/07-team-workflows-and-design-governance.md
+++ b/tutorials/figma-context-mcp-tutorial/07-team-workflows-and-design-governance.md
@@ -26,170 +26,168 @@ You now have a team governance baseline for consistent design-to-code execution.
Next: [Chapter 8: Production Security and Operations](08-production-security-and-operations.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/transformers/layout.ts`
+### `src/extractors/node-walker.ts`
-The `convertAlignItems` function in [`src/transformers/layout.ts`](https://github.com/GLips/Figma-Context-MCP/blob/HEAD/src/transformers/layout.ts) handles a key part of this chapter's functionality:
+The `shouldTraverseChildren` function in [`src/extractors/node-walker.ts`](https://github.com/GLips/Figma-Context-MCP/blob/HEAD/src/extractors/node-walker.ts) handles a key part of this chapter's functionality:
```ts
-}
-function convertAlignItems(
- align: HasFramePropertiesTrait["counterAxisAlignItems"] | undefined,
- children: FigmaDocumentNode[],
- mode: "row" | "column",
-) {
- // Row cross-axis is vertical; column cross-axis is horizontal
- const crossSizing = mode === "row" ? "layoutSizingVertical" : "layoutSizingHorizontal";
- const allStretch =
- children.length > 0 &&
- children.every(
- (c) =>
- ("layoutPositioning" in c && c.layoutPositioning === "ABSOLUTE") ||
- (crossSizing in c && (c as Record<string, unknown>)[crossSizing] === "FILL"),
- );
- if (allStretch) return "stretch";
-
- switch (align) {
- case "MIN":
- return undefined;
- case "MAX":
- return "flex-end";
- case "CENTER":
- return "center";
- case "BASELINE":
- return "baseline";
- default:
- return undefined;
+ // Handle children recursively
+ if (shouldTraverseChildren(node, context, options)) {
+ const childContext: TraversalContext = {
+ ...context,
+ currentDepth: context.currentDepth + 1,
+ parent: node,
+ };
+
+ // Use the same pattern as the existing parseNode function
+ if (hasValue("children", node) && node.children.length > 0) {
+ const children: SimplifiedNode[] = [];
+ for (const child of node.children) {
+ if (!shouldProcessNode(child, options)) continue;
+ const processed = await processNodeWithExtractors(child, extractors, childContext, options);
+ if (processed !== null) children.push(processed);
+ }
+
+ if (children.length > 0) {
+ // Allow custom logic to modify parent and control which children to include
+ const childrenToInclude = options.afterChildren
+ ? options.afterChildren(node, result, children)
+ : children;
+
+ if (childrenToInclude.length > 0) {
+ result.children = childrenToInclude;
+ }
+ }
+ }
}
-}
+ return result;
```
This function is important because it defines how Figma Context MCP Tutorial: Design-to-Code Workflows for Coding Agents implements the patterns covered in this chapter.
-### `src/transformers/layout.ts`
+### `src/utils/common.ts`
-The `convertSelfAlign` function in [`src/transformers/layout.ts`](https://github.com/GLips/Figma-Context-MCP/blob/HEAD/src/transformers/layout.ts) handles a key part of this chapter's functionality:
+The `downloadFigmaImage` function in [`src/utils/common.ts`](https://github.com/GLips/Figma-Context-MCP/blob/HEAD/src/utils/common.ts) handles a key part of this chapter's functionality:
```ts
-}
-
-function convertSelfAlign(align?: HasLayoutTrait["layoutAlign"]) {
- switch (align) {
- case "MIN":
- // MIN, AKA flex-start, is the default alignment
- return undefined;
- case "MAX":
- return "flex-end";
- case "CENTER":
- return "center";
- case "STRETCH":
- return "stretch";
- default:
- return undefined;
- }
-}
-
-// interpret sizing
-function convertSizing(
- s?: HasLayoutTrait["layoutSizingHorizontal"] | HasLayoutTrait["layoutSizingVertical"],
-) {
- if (s === "FIXED") return "fixed";
- if (s === "FILL") return "fill";
- if (s === "HUG") return "hug";
- return undefined;
-}
+ * @throws Error if download fails
+ */
+export async function downloadFigmaImage(
+ fileName: string,
+ localPath: string,
+ imageUrl: string,
+): Promise<string> {
+ try {
+ // Ensure local path exists
+ if (!fs.existsSync(localPath)) {
+ fs.mkdirSync(localPath, { recursive: true });
+ }
+
+ // Build the complete file path and verify it stays within localPath
+ const fullPath = path.resolve(path.join(localPath, fileName));
+ const resolvedLocalPath = path.resolve(localPath);
+ if (!fullPath.startsWith(resolvedLocalPath + path.sep)) {
+ throw new Error(`File path escapes target directory: ${fileName}`);
+ }
+
+ // Use fetch to download the image
+ const response = await fetch(imageUrl, {
+ method: "GET",
+ });
+
+ if (!response.ok) {
+ throw new Error(`Failed to download image: ${response.statusText}`);
+ }
+
+ // Create write stream
+ const writer = fs.createWriteStream(fullPath);
-function buildSimplifiedFrameValues(n: FigmaDocumentNode): SimplifiedLayout | { mode: "none" } {
- if (!isFrame(n)) {
- return { mode: "none" };
- }
```
This function is important because it defines how Figma Context MCP Tutorial: Design-to-Code Workflows for Coding Agents implements the patterns covered in this chapter.
-### `src/transformers/layout.ts`
+### `src/utils/common.ts`
-The `convertSizing` function in [`src/transformers/layout.ts`](https://github.com/GLips/Figma-Context-MCP/blob/HEAD/src/transformers/layout.ts) handles a key part of this chapter's functionality:
+The `generateVarId` function in [`src/utils/common.ts`](https://github.com/GLips/Figma-Context-MCP/blob/HEAD/src/utils/common.ts) handles a key part of this chapter's functionality:
```ts
+ * @returns A 6-character random ID string with prefix
+ */
+export function generateVarId(prefix: string = "var"): StyleId {
+ const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
+ let result = "";
+
+ for (let i = 0; i < 6; i++) {
+ const randomIndex = Math.floor(Math.random() * chars.length);
+ result += chars[randomIndex];
+ }
-// interpret sizing
-function convertSizing(
- s?: HasLayoutTrait["layoutSizingHorizontal"] | HasLayoutTrait["layoutSizingVertical"],
-) {
- if (s === "FIXED") return "fixed";
- if (s === "FILL") return "fill";
- if (s === "HUG") return "hug";
- return undefined;
+ return `${prefix}_${result}` as StyleId;
}
-function buildSimplifiedFrameValues(n: FigmaDocumentNode): SimplifiedLayout | { mode: "none" } {
- if (!isFrame(n)) {
- return { mode: "none" };
- }
-
- const frameValues: SimplifiedLayout = {
- mode:
- !n.layoutMode || n.layoutMode === "NONE"
- ? "none"
- : n.layoutMode === "HORIZONTAL"
- ? "row"
- : "column",
- };
-
- const overflowScroll: SimplifiedLayout["overflowScroll"] = [];
- if (n.overflowDirection?.includes("HORIZONTAL")) overflowScroll.push("x");
- if (n.overflowDirection?.includes("VERTICAL")) overflowScroll.push("y");
- if (overflowScroll.length > 0) frameValues.overflowScroll = overflowScroll;
-
- if (frameValues.mode === "none") {
- return frameValues;
+/**
+ * Generate a CSS shorthand for values that come with top, right, bottom, and left
+ *
+ * input: { top: 10, right: 10, bottom: 10, left: 10 }
+ * output: "10px"
+ *
+ * input: { top: 10, right: 20, bottom: 10, left: 20 }
+ * output: "10px 20px"
+ *
+ * input: { top: 10, right: 20, bottom: 30, left: 40 }
+ * output: "10px 20px 30px 40px"
+ *
+ * @param values - The values to generate the shorthand for
+ * @returns The generated shorthand
+ */
+export function generateCSSShorthand(
+ values: {
+ top: number;
```
This function is important because it defines how Figma Context MCP Tutorial: Design-to-Code Workflows for Coding Agents implements the patterns covered in this chapter.
-### `src/transformers/layout.ts`
+### `src/utils/common.ts`
-The `buildSimplifiedFrameValues` function in [`src/transformers/layout.ts`](https://github.com/GLips/Figma-Context-MCP/blob/HEAD/src/transformers/layout.ts) handles a key part of this chapter's functionality:
+The `generateCSSShorthand` function in [`src/utils/common.ts`](https://github.com/GLips/Figma-Context-MCP/blob/HEAD/src/utils/common.ts) handles a key part of this chapter's functionality:
```ts
- parent?: FigmaDocumentNode,
-): SimplifiedLayout {
- const frameValues = buildSimplifiedFrameValues(n);
- const layoutValues = buildSimplifiedLayoutValues(n, parent, frameValues.mode) || {};
-
- return { ...frameValues, ...layoutValues };
-}
-
-function convertJustifyContent(align?: HasFramePropertiesTrait["primaryAxisAlignItems"]) {
- switch (align) {
- case "MIN":
- return undefined;
- case "MAX":
- return "flex-end";
- case "CENTER":
- return "center";
- case "SPACE_BETWEEN":
- return "space-between";
- default:
- return undefined;
- }
-}
-
-function convertAlignItems(
- align: HasFramePropertiesTrait["counterAxisAlignItems"] | undefined,
- children: FigmaDocumentNode[],
- mode: "row" | "column",
+ * @returns The generated shorthand
+ */
+export function generateCSSShorthand(
+ values: {
+ top: number;
+ right: number;
+ bottom: number;
+ left: number;
+ },
+ {
+ ignoreZero = true,
+ suffix = "px",
+ }: {
+ /**
+ * If true and all values are 0, return undefined. Defaults to true.
+ */
+ ignoreZero?: boolean;
+ /**
+ * The suffix to add to the shorthand. Defaults to "px".
+ */
+ suffix?: string;
+ } = {},
) {
- // Row cross-axis is vertical; column cross-axis is horizontal
- const crossSizing = mode === "row" ? "layoutSizingVertical" : "layoutSizingHorizontal";
- const allStretch =
- children.length > 0 &&
+ const { top, right, bottom, left } = values;
+ if (ignoreZero && top === 0 && right === 0 && bottom === 0 && left === 0) {
+ return undefined;
+ }
+ if (top === right && right === bottom && bottom === left) {
+ return `${top}${suffix}`;
+ }
+ if (right === left) {
+ if (top === bottom) {
```
This function is important because it defines how Figma Context MCP Tutorial: Design-to-Code Workflows for Coding Agents implements the patterns covered in this chapter.
@@ -199,11 +197,11 @@ This function is important because it defines how Figma Context MCP Tutorial: De
```mermaid
flowchart TD
- A[convertAlignItems]
- B[convertSelfAlign]
- C[convertSizing]
- D[buildSimplifiedFrameValues]
- E[buildSimplifiedLayoutValues]
+ A[shouldTraverseChildren]
+ B[downloadFigmaImage]
+ C[generateVarId]
+ D[generateCSSShorthand]
+ E[isVisible]
A --> B
B --> C
C --> D
diff --git a/tutorials/figma-context-mcp-tutorial/08-production-security-and-operations.md b/tutorials/figma-context-mcp-tutorial/08-production-security-and-operations.md
index 08e3f815..e85fa799 100644
--- a/tutorials/figma-context-mcp-tutorial/08-production-security-and-operations.md
+++ b/tutorials/figma-context-mcp-tutorial/08-production-security-and-operations.md
@@ -32,15 +32,100 @@ This chapter covers secure deployment and operational policies for Figma context
You now have the security and operations baseline for running Figma Context MCP in production teams.
-## Depth Expansion Playbook
-
## Source Code Walkthrough
+### `src/utils/image-processing.ts`
+
+The `generateImageCSSVariables` function in [`src/utils/image-processing.ts`](https://github.com/GLips/Figma-Context-MCP/blob/HEAD/src/utils/image-processing.ts) handles a key part of this chapter's functionality:
+
+```ts
+ let cssVariables: string | undefined;
+ if (requiresImageDimensions) {
+ cssVariables = generateImageCSSVariables(finalDimensions);
+ }
+
+ return {
+ filePath: finalPath,
+ originalDimensions,
+ finalDimensions,
+ wasCropped,
+ cropRegion,
+ cssVariables,
+ processingLog,
+ };
+}
+
+/**
+ * Create CSS custom properties for image dimensions
+ * @param imagePath - Path to the image file
+ * @returns Promise<string> - CSS custom properties
+ */
+export function generateImageCSSVariables({
+ width,
+ height,
+}: {
+ width: number;
+ height: number;
+}): string {
+ return `--original-width: ${width}px; --original-height: ${height}px;`;
+}
+
+```
+
+This function is important because it defines how Figma Context MCP Tutorial: Design-to-Code Workflows for Coding Agents implements the patterns covered in this chapter.
+
+### `src/utils/fetch-with-retry.ts`
+
+The `formatHeadersForCurl` function in [`src/utils/fetch-with-retry.ts`](https://github.com/GLips/Figma-Context-MCP/blob/HEAD/src/utils/fetch-with-retry.ts) handles a key part of this chapter's functionality:
+
+```ts
+ );
+
+ const curlHeaders = formatHeadersForCurl(options.headers);
+ // Most options here are to ensure stderr only contains errors, so we can use it to confidently check if an error occurred.
+ // -s: Silent mode—no progress bar in stderr
+ // -S: Show errors in stderr
+ // --fail-with-body: curl errors with code 22, and outputs body of failed request, e.g. "Fetch failed with status 404"
+ // -L: Follow redirects
+ const curlArgs = ["-s", "-S", "--fail-with-body", "-L", ...curlHeaders, url];
+
+ try {
+ // Fallback to curl for corporate networks that have proxies that sometimes block fetch
+ Logger.log(`[fetchWithRetry] Executing curl with args: ${JSON.stringify(curlArgs)}`);
+ const { stdout, stderr } = await execFileAsync("curl", curlArgs);
+
+ if (stderr) {
+ // curl often outputs progress to stderr, so only treat as error if stdout is empty
+ // or if stderr contains typical error keywords.
+ if (
+ !stdout ||
+ stderr.toLowerCase().includes("error") ||
+ stderr.toLowerCase().includes("fail")
+ ) {
+ throw new Error(`Curl command failed with stderr: ${stderr}`);
+ }
+ Logger.log(
+ `[fetchWithRetry] Curl command for ${url} produced stderr (but might be informational): ${stderr}`,
+ );
+ }
+
+ if (!stdout) {
+ throw new Error("Curl command returned empty stdout.");
+```
+
+This function is important because it defines how Figma Context MCP Tutorial: Design-to-Code Workflows for Coding Agents implements the patterns covered in this chapter.
+
### `src/extractors/types.ts`
-The `TraversalOptions` interface in [`src/extractors/types.ts`](https://github.com/GLips/Figma-Context-MCP/blob/HEAD/src/extractors/types.ts) handles a key part of this chapter's functionality:
+The `TraversalContext` interface in [`src/extractors/types.ts`](https://github.com/GLips/Figma-Context-MCP/blob/HEAD/src/extractors/types.ts) handles a key part of this chapter's functionality:
```ts
+};
+
+export interface TraversalContext {
+ globalVars: GlobalVars & { extraStyles?: Record<string, Style> };
+ currentDepth: number;
+ parent?: FigmaDocumentNode;
}
export interface TraversalOptions {
@@ -67,62 +152,23 @@ export interface TraversalOptions {
*
* @param node - The current Figma node being processed
* @param result - SimplifiedNode object being built—this can be mutated inside the extractor
- * @param context - Traversal context including globalVars and parent info. This can also be mutated inside the extractor.
- */
-export type ExtractorFn = (
- node: FigmaDocumentNode,
- result: SimplifiedNode,
- context: TraversalContext,
```
This interface is important because it defines how Figma Context MCP Tutorial: Design-to-Code Workflows for Coding Agents implements the patterns covered in this chapter.
### `src/extractors/types.ts`
-The `SimplifiedDesign` interface in [`src/extractors/types.ts`](https://github.com/GLips/Figma-Context-MCP/blob/HEAD/src/extractors/types.ts) handles a key part of this chapter's functionality:
+The `TraversalOptions` interface in [`src/extractors/types.ts`](https://github.com/GLips/Figma-Context-MCP/blob/HEAD/src/extractors/types.ts) handles a key part of this chapter's functionality:
```ts
-) => void;
-
-export interface SimplifiedDesign {
- name: string;
- nodes: SimplifiedNode[];
- components: Record<string, SimplifiedComponentDefinition>;
- componentSets: Record<string, SimplifiedComponentSetDefinition>;
- globalVars: GlobalVars;
}
-export interface SimplifiedNode {
- id: string;
- name: string;
- type: string; // e.g. FRAME, TEXT, INSTANCE, RECTANGLE, etc.
- // text
- text?: string;
- textStyle?: string;
- // appearance
- fills?: string;
- styles?: string;
- strokes?: string;
- // Non-stylable stroke properties are kept on the node when stroke uses a named color style
- strokeWeight?: string;
- strokeDashes?: number[];
- strokeWeights?: string;
- effects?: string;
- opacity?: number;
- borderRadius?: string;
- // layout & alignment
- layout?: string;
- // for rect-specific strokes, etc.
- componentId?: string;
-```
-
-This interface is important because it defines how Figma Context MCP Tutorial: Design-to-Code Workflows for Coding Agents implements the patterns covered in this chapter.
-
-### `src/extractors/types.ts`
-
-The `SimplifiedNode` interface in [`src/extractors/types.ts`](https://github.com/GLips/Figma-Context-MCP/blob/HEAD/src/extractors/types.ts) handles a key part of this chapter's functionality:
-
-```ts
+export interface TraversalOptions {
+ maxDepth?: number;
+ nodeFilter?: (node: FigmaDocumentNode) => boolean;
+ /**
+ * Called after children are processed, allowing modification of the parent node
+ * and control over which children to include in the output.
*
* @param node - Original Figma node
* @param result - SimplifiedNode being built (can be mutated)
@@ -147,32 +193,6 @@ export type ExtractorFn = (
node: FigmaDocumentNode,
result: SimplifiedNode,
context: TraversalContext,
-) => void;
-
-export interface SimplifiedDesign {
- name: string;
- nodes: SimplifiedNode[];
- components: Record<string, SimplifiedComponentDefinition>;
- componentSets: Record<string, SimplifiedComponentSetDefinition>;
- globalVars: GlobalVars;
-```
-
-This interface is important because it defines how Figma Context MCP Tutorial: Design-to-Code Workflows for Coding Agents implements the patterns covered in this chapter.
-
-### `src/extractors/types.ts`
-
-The `BoundingBox` interface in [`src/extractors/types.ts`](https://github.com/GLips/Figma-Context-MCP/blob/HEAD/src/extractors/types.ts) handles a key part of this chapter's functionality:
-
-```ts
-}
-
-export interface BoundingBox {
- x: number;
- y: number;
- width: number;
- height: number;
-}
-
```
This interface is important because it defines how Figma Context MCP Tutorial: Design-to-Code Workflows for Coding Agents implements the patterns covered in this chapter.
@@ -182,11 +202,11 @@ This interface is important because it defines how Figma Context MCP Tutorial: D
```mermaid
flowchart TD
- A[TraversalOptions]
- B[SimplifiedDesign]
- C[SimplifiedNode]
- D[BoundingBox]
- E[simplifyRawFigmaObject]
+ A[generateImageCSSVariables]
+ B[formatHeadersForCurl]
+ C[TraversalContext]
+ D[TraversalOptions]
+ E[SimplifiedDesign]
A --> B
B --> C
C --> D
diff --git a/tutorials/firecrawl-mcp-server-tutorial/01-getting-started-and-core-setup.md b/tutorials/firecrawl-mcp-server-tutorial/01-getting-started-and-core-setup.md
index 9cd5166a..30bad968 100644
--- a/tutorials/firecrawl-mcp-server-tutorial/01-getting-started-and-core-setup.md
+++ b/tutorials/firecrawl-mcp-server-tutorial/01-getting-started-and-core-setup.md
@@ -5,90 +5,147 @@ nav_order: 1
parent: Firecrawl MCP Server Tutorial
---
-
# Chapter 1: Getting Started and Core Setup
-Welcome to **Chapter 1: Getting Started and Core Setup**. In this part of **Firecrawl MCP Server Tutorial: Web Scraping and Search Tools for MCP Clients**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
-
-
-This chapter gets Firecrawl MCP running with minimum viable configuration.
+Firecrawl MCP Server (`firecrawl-mcp`) is a TypeScript MCP server that exposes the Firecrawl web-scraping API as MCP tools. This lets LLM-powered clients like Claude Desktop, Cursor, and Windsurf scrape URLs, search the web, crawl sites, and extract structured data — all through the standard MCP tool-call interface.
## Learning Goals
-- launch Firecrawl MCP with cloud credentials
-- verify tool availability in your client
-- capture initial connectivity checks
+- Launch Firecrawl MCP with cloud credentials in under five minutes
+- Understand the two deployment modes: stdio (local) and HTTP service (cloud)
+- Verify tool availability in your MCP client
+- Capture initial connectivity and authentication checks
-## Quick Start Command
+## Architecture at a Glance
-```bash
-env FIRECRAWL_API_KEY=fc-YOUR_API_KEY npx -y firecrawl-mcp
+```mermaid
+graph LR
+ CLIENT[MCP Client\nClaude Desktop · Cursor · Windsurf]
+ CLIENT -->|MCP tools/call| SERVER[firecrawl-mcp\nfastMCP server\nNode.js]
+ SERVER -->|REST API| FIRECRAWL[Firecrawl API\napi.firecrawl.dev]
+ SERVER -.->|or| SELFHOSTED[Self-hosted Firecrawl\nFIRECRAWL_API_URL]
+
+ SERVER --> TOOLS[Exposed tools:\nfirecrawl_scrape\nfirecrawl_map\nfirecrawl_crawl\nfirecrawl_search\nfirecrawl_extract\n...]
```
-## First-Run Checklist
+The server is built on top of the `firecrawl-fastmcp` library (a custom FastMCP variant), uses `zod` for tool input validation, and delegates all scraping to the `@mendable/firecrawl-js` SDK.
-1. API key is valid
-2. client connects to server process
-3. at least one scrape/search call succeeds
-4. logs show no repeated auth or rate-limit failures
+## Prerequisites
-## Source References
+- Node.js 18 or higher
+- A Firecrawl API key from [firecrawl.dev](https://firecrawl.dev) (or a self-hosted instance URL)
+- `npx` available (bundled with Node.js)
-- [README Installation](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/README.md)
+## Quick Start (stdio mode)
-## Summary
+```bash
+# Cloud mode — pass API key via environment
+FIRECRAWL_API_KEY=fc-your-api-key npx -y firecrawl-mcp
+```
-You now have a working Firecrawl MCP baseline.
+That single command downloads and runs the server. The server starts in stdio mode and waits for an MCP client to connect.
-Next: [Chapter 2: Architecture, Transports, and Versioning](02-architecture-transports-and-versioning.md)
+## Quick Start (Claude Desktop)
-## Source Code Walkthrough
+Add to `claude_desktop_config.json`:
+
+```json
+{
+ "mcpServers": {
+ "firecrawl": {
+ "command": "npx",
+ "args": ["-y", "firecrawl-mcp"],
+ "env": {
+ "FIRECRAWL_API_KEY": "fc-your-api-key"
+ }
+ }
+ }
+}
+```
-### `src/types/fastmcp.d.ts`
+Restart Claude Desktop. The Firecrawl tools appear in the hammer icon menu.
-The `FastMCP` class in [`src/types/fastmcp.d.ts`](https://github.com/firecrawl/firecrawl-mcp-server/blob/HEAD/src/types/fastmcp.d.ts) handles a key part of this chapter's functionality:
+## Self-Hosted Mode
-```ts
- ) => unknown | Promise<unknown>;
-
- export class FastMCP<Session = unknown> {
- constructor(options: {
- name: string;
- version?: string;
- logger?: Logger;
- roots?: { enabled?: boolean };
- authenticate?: (
- request: { headers: IncomingHttpHeaders }
- ) => Promise<Session> | Session;
- health?: {
- enabled?: boolean;
- message?: string;
- path?: string;
- status?: number;
- };
- });
-
- addTool(tool: {
- name: string;
- description?: string;
- parameters?: unknown;
- execute: ToolExecute<Session>;
- }): void;
-
- start(args?: TransportArgs): Promise<void>;
+If you run a private Firecrawl instance:
+
+```json
+{
+ "mcpServers": {
+ "firecrawl": {
+ "command": "npx",
+ "args": ["-y", "firecrawl-mcp"],
+ "env": {
+ "FIRECRAWL_API_URL": "http://localhost:3002"
+ }
+ }
}
}
+```
+When `FIRECRAWL_API_URL` is set, `FIRECRAWL_API_KEY` becomes optional.
+## First-Run Checklist
+```mermaid
+flowchart TD
+ START[Start server]
+ START --> AUTH{Auth check}
+ AUTH -->|Cloud mode| APIKEY[FIRECRAWL_API_KEY present?]
+ AUTH -->|Self-hosted| URL[FIRECRAWL_API_URL present?]
+ APIKEY --> LAUNCH[Server launches\nwith authenticated session]
+ URL --> LAUNCH
+ LAUNCH --> TOOLS[Client connects,\nlists tools]
+ TOOLS --> CALL[Call firecrawl_scrape with a known URL]
+ CALL --> RESULT{Response received?}
+ RESULT -- Yes --> OK[Baseline validated]
+ RESULT -- No --> DEBUG[Check logs, API key, network]
```
-This class is important because it defines how Firecrawl MCP Server Tutorial: Web Scraping and Search Tools for MCP Clients implements the patterns covered in this chapter.
+1. API key is valid and not expired
+2. `npx` can reach the npm registry (or use `--prefer-offline` with local cache)
+3. Client connects and lists at least 5 tools
+4. A basic scrape call returns markdown content for a known URL
+5. Logs show no repeated auth or rate-limit failures
+## Key Dependencies
-## How These Components Connect
+From `package.json`:
-```mermaid
-flowchart TD
- A[FastMCP]
+| Package | Role |
+|:--------|:-----|
+| `firecrawl-fastmcp` | FastMCP server framework providing MCP transport |
+| `@mendable/firecrawl-js` | Official Firecrawl REST API client |
+| `zod` | Runtime input validation for all tool parameters |
+| `dotenv` | Optional `.env` file support for local development |
+
+## Source Code Walkthrough
+
+### `src/index.ts`
+
+The `createClient` function in [`src/index.ts`](https://github.com/mendableai/firecrawl-mcp-server/blob/main/src/index.ts) shows how the MCP server connects to the Firecrawl API:
+
+```ts
+function createClient(apiKey?: string): FirecrawlApp {
+ const config: any = {
+ ...(process.env.FIRECRAWL_API_URL && {
+ apiUrl: process.env.FIRECRAWL_API_URL,
+ }),
+ };
+
+ // Only add apiKey if it's provided (required for cloud, optional for self-hosted)
+ if (apiKey) {
+ config.apiKey = apiKey;
+ }
+
+ return new FirecrawlApp(config);
+}
```
+
+This function is important because it implements the two-mode setup covered in this chapter: cloud mode uses `FIRECRAWL_API_KEY`, while self-hosted mode uses `FIRECRAWL_API_URL` — making the API key optional when a custom endpoint is configured.
+
+## Summary
+
+Firecrawl MCP runs as a Node.js process that bridges MCP tool calls to the Firecrawl REST API. The quickest path to a working setup is `FIRECRAWL_API_KEY=fc-... npx -y firecrawl-mcp` for stdio testing, or the Claude Desktop config block for integrated usage. Self-hosted deployments use `FIRECRAWL_API_URL` instead of the API key.
+
+Next: [Chapter 2: Architecture, Transports, and Versioning](02-architecture-transports-and-versioning.md)
diff --git a/tutorials/firecrawl-mcp-server-tutorial/02-architecture-transports-and-versioning.md b/tutorials/firecrawl-mcp-server-tutorial/02-architecture-transports-and-versioning.md
index 48992dd8..6bd311e9 100644
--- a/tutorials/firecrawl-mcp-server-tutorial/02-architecture-transports-and-versioning.md
+++ b/tutorials/firecrawl-mcp-server-tutorial/02-architecture-transports-and-versioning.md
@@ -5,91 +5,198 @@ nav_order: 2
parent: Firecrawl MCP Server Tutorial
---
-
# Chapter 2: Architecture, Transports, and Versioning
-Welcome to **Chapter 2: Architecture, Transports, and Versioning**. In this part of **Firecrawl MCP Server Tutorial: Web Scraping and Search Tools for MCP Clients**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
+This chapter explains the internal architecture of the `firecrawl-mcp` server — how it uses `firecrawl-fastmcp` to manage sessions and transports, the three deployment modes (stdio, SSE local, HTTP streamable), and the V1-to-V2 API versioning model.
+## Learning Goals
-Firecrawl MCP supports local transports and cloud-mode versioned endpoints, with V2 as the default modern path.
+- Understand the server's deployment transport options and their tradeoffs
+- Map how cloud mode and local mode differ in authentication and session handling
+- Understand V1 vs V2 Firecrawl API endpoint differences
+- Avoid migration mistakes in existing client integrations
-## Learning Goals
+## Server Initialization Architecture
-- understand transport mode implications
-- map V1 vs V2 endpoint differences
-- avoid migration mistakes in existing integrations
+```mermaid
+graph TD
+ SERVER[FastMCP server instance\nfirecrawl-fastmcp]
+ SERVER --> AUTH[authenticate callback\nextracts API key from headers\nor uses env var]
+ SERVER --> HEALTH[Health endpoint\nGET /health → 200 OK]
+ SERVER --> LOGGER[ConsoleLogger\nonly active in service modes]
+ SERVER --> TOOLS[addTool calls\none per Firecrawl operation]
+
+ AUTH --> SESSION[SessionData\nfirecrawlApiKey per connection]
+ SESSION --> CLIENT[createClient per request\nFirecrawlApp instance]
+```
-## Endpoint Model Highlights
+The server is built using `new FastMCP<SessionData>(options)` from `firecrawl-fastmcp`. Key initialization choices:
+
+```typescript
+const server = new FastMCP<SessionData>({
+ name: 'firecrawl-fastmcp',
+ version: '3.0.0',
+ logger: new ConsoleLogger(),
+ roots: { enabled: false }, // no roots support
+ authenticate: async (request) => {
+ if (process.env.CLOUD_SERVICE === 'true') {
+ // Per-request API key from headers
+ const apiKey = extractApiKey(request.headers);
+ if (!apiKey) throw new Error('Firecrawl API key is required');
+ return { firecrawlApiKey: apiKey };
+ } else {
+ // Shared API key from environment
+ return { firecrawlApiKey: process.env.FIRECRAWL_API_KEY };
+ }
+ },
+ health: { enabled: true, message: 'ok', path: '/health', status: 200 },
+});
+```
-| Mode | Notes |
-|:-----|:------|
-| local stdio/streamable | V2 behavior by default |
-| cloud service mode | versioned V1 and V2 endpoint paths |
+## Transport Modes
-## Versioning Guidance
+```mermaid
+graph LR
+ MODES[Deployment Modes]
+ MODES --> STDIO[stdio\nDefault local mode\nno env flag needed]
+ MODES --> SSE[SSE_LOCAL=true\nHTTP server with SSE transport\nlocal use only]
+ MODES --> HTTP[HTTP_STREAMABLE_SERVER=true\nStreamable HTTP transport\nfor hosted deployments]
+ MODES --> CLOUD[CLOUD_SERVICE=true\nMulti-tenant hosted mode\nper-request API key auth]
+```
-- V1 endpoints remain for backward compatibility.
-- V2 is the current path for modern tool behavior and API support.
-- migration requires endpoint and tool-surface awareness.
+### Stdio Mode (Default)
-## Source References
+The standard local mode used by Claude Desktop, Cursor, and other desktop clients. The `npx -y firecrawl-mcp` command defaults to stdio. No HTTP server is started; the MCP protocol flows through stdin/stdout.
-- [Versioning Guide](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/VERSIONING.md)
-- [README Transport Setup](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/README.md)
+```bash
+# stdio mode — Claude Desktop spawns this as a subprocess
+FIRECRAWL_API_KEY=fc-... npx -y firecrawl-mcp
+```
-## Summary
+### SSE Local Mode
-You now understand the transport and version boundaries that shape deployment architecture.
+Starts an HTTP server with SSE transport for local testing. Useful when connecting multiple clients to the same server instance:
-Next: [Chapter 3: Tool Selection: Scrape, Map, Crawl, Search, Extract](03-tool-selection-scrape-map-crawl-search-extract.md)
+```bash
+SSE_LOCAL=true FIRECRAWL_API_KEY=fc-... node dist/index.js
+```
-## Source Code Walkthrough
+### HTTP Streamable Mode
-### `src/types/fastmcp.d.ts`
+Starts a server using the modern StreamableHTTP transport for hosted deployments:
-The `Logger` interface in [`src/types/fastmcp.d.ts`](https://github.com/firecrawl/firecrawl-mcp-server/blob/HEAD/src/types/fastmcp.d.ts) handles a key part of this chapter's functionality:
+```bash
+HTTP_STREAMABLE_SERVER=true FIRECRAWL_API_KEY=fc-... node dist/index.js
+```
-```ts
- import type { IncomingHttpHeaders } from 'http';
-
- export interface Logger {
- debug(...args: unknown[]): void;
- error(...args: unknown[]): void;
- info(...args: unknown[]): void;
- log(...args: unknown[]): void;
- warn(...args: unknown[]): void;
- }
+### Cloud Service Mode
+
+Multi-tenant mode for hosted Firecrawl MCP deployments. Each request must include an API key in the request headers:
- export type TransportArgs =
- | { transportType: 'stdio' }
- | {
- transportType: 'httpStream';
- httpStream: { port: number; host?: string; stateless?: boolean };
- };
+```bash
+CLOUD_SERVICE=true node dist/index.js
+```
- export interface ToolContext<Session = unknown> {
- session?: Session;
- log: Logger;
+Accepted headers for API key in cloud mode:
+- `x-firecrawl-api-key: fc-...`
+- `x-api-key: fc-...`
+- `Authorization: Bearer fc-...`
+
+```typescript
+function extractApiKey(headers: IncomingHttpHeaders): string | undefined {
+ const headerApiKey = headers['x-firecrawl-api-key'] || headers['x-api-key'];
+ if (headerApiKey) return Array.isArray(headerApiKey) ? headerApiKey[0] : headerApiKey;
+ const headerAuth = headers['authorization'];
+ if (typeof headerAuth === 'string' && headerAuth.toLowerCase().startsWith('bearer ')) {
+ return headerAuth.slice(7).trim();
}
+ return undefined;
+}
+```
+
+## Safe Mode
- export type ToolExecute<Session = unknown> = (
- args: unknown,
- context: ToolContext<Session>
- ) => unknown | Promise<unknown>;
+When `CLOUD_SERVICE=true`, the server automatically enables **safe mode**, which restricts the browser action types available in `firecrawl_scrape` to a safe subset:
- export class FastMCP<Session = unknown> {
- constructor(options: {
- name: string;
- version?: string;
- logger?: Logger;
+```typescript
+const SAFE_MODE = process.env.CLOUD_SERVICE === 'true';
+
+// Safe mode: only wait, screenshot, scroll, scrape
+// Full mode: also click, write, press, executeJavascript, generatePDF
+const allowedActionTypes = SAFE_MODE ? safeActionTypes : allActionTypes;
```
-This interface is important because it defines how Firecrawl MCP Server Tutorial: Web Scraping and Search Tools for MCP Clients implements the patterns covered in this chapter.
+This is designed to comply with ChatGPT plugin safety requirements for hosted deployments.
+## Firecrawl API Versioning (V1 vs V2)
-## How These Components Connect
+The server's `VERSIONING.md` documents the transition from V1 to V2 Firecrawl API endpoints.
```mermaid
-flowchart TD
- A[Logger]
+graph LR
+ V1[V1 API\nLegacy endpoints\ne.g., /v0/scrape]
+ V2[V2 API\nModern endpoints\ne.g., /v1/scrape]
+
+ V1 --> BACK[Preserved for backward\ncompatibility in cloud]
+ V2 --> DEFAULT[Default in all\ncurrent tool implementations]
+ V2 --> FEATURES[New features:\nextraction schemas\nbatch jobs\nchangeTracking format]
```
+
+The MCP server itself always calls V2 endpoints through the `@mendable/firecrawl-js` SDK (v4.x). V1 compatibility is handled at the Firecrawl API service level, not in the MCP server code.
+
+**Practical impact**: If you pin the `firecrawl-mcp` version, you get consistent API behavior. Upgrading the MCP server version may change the available tool parameters as new V2 features are exposed.
+
+## Transport Mode Environment Variables Summary
+
+| Environment Variable | Effect |
+|:---------------------|:-------|
+| (none) | stdio mode — default for desktop clients |
+| `SSE_LOCAL=true` | HTTP + SSE transport on a local port |
+| `HTTP_STREAMABLE_SERVER=true` | StreamableHTTP transport |
+| `CLOUD_SERVICE=true` | Multi-tenant hosted mode, enables per-request API key auth and safe mode |
+| `FIRECRAWL_API_KEY` | API key for cloud usage |
+| `FIRECRAWL_API_URL` | Base URL for self-hosted instance |
+
+## Source Code Walkthrough
+
+### `src/index.ts`
+
+The transport selection block at the bottom of [`src/index.ts`](https://github.com/mendableai/firecrawl-mcp-server/blob/main/src/index.ts) shows how the four deployment modes are wired:
+
+```ts
+const PORT = Number(process.env.PORT || 3000);
+const HOST =
+ process.env.CLOUD_SERVICE === 'true'
+ ? '0.0.0.0'
+ : process.env.HOST || 'localhost';
+
+if (
+ process.env.CLOUD_SERVICE === 'true' ||
+ process.env.SSE_LOCAL === 'true' ||
+ process.env.HTTP_STREAMABLE_SERVER === 'true'
+) {
+ args = {
+ transportType: 'httpStream',
+ httpStream: {
+ port: PORT,
+ host: HOST,
+ stateless: true,
+ },
+ };
+} else {
+ // default: stdio
+ args = {
+ transportType: 'stdio',
+ };
+}
+
+await server.start(args);
+```
+
+This block is important because it implements the transport architecture covered in this chapter: a single codebase serves stdio (local MCP clients), SSE/StreamableHTTP (local HTTP), and cloud multi-tenant mode — selected entirely via environment variables.
+
+## Summary
+
+The server supports four deployment modes (stdio, SSE local, StreamableHTTP, and cloud multi-tenant) controlled by environment variables. Cloud mode adds per-request API key extraction from HTTP headers and enables safe mode to restrict browser action types. The underlying Firecrawl API runs V2 endpoints by default via the `@mendable/firecrawl-js` SDK; V1 is a legacy cloud-side concern, not an MCP-layer concern.
+
+Next: [Chapter 3: Tool Selection: Scrape, Map, Crawl, Search, Extract](03-tool-selection-scrape-map-crawl-search-extract.md)
diff --git a/tutorials/firecrawl-mcp-server-tutorial/03-tool-selection-scrape-map-crawl-search-extract.md b/tutorials/firecrawl-mcp-server-tutorial/03-tool-selection-scrape-map-crawl-search-extract.md
index 3bb18e94..4cdf80bf 100644
--- a/tutorials/firecrawl-mcp-server-tutorial/03-tool-selection-scrape-map-crawl-search-extract.md
+++ b/tutorials/firecrawl-mcp-server-tutorial/03-tool-selection-scrape-map-crawl-search-extract.md
@@ -5,88 +5,197 @@ nav_order: 3
parent: Firecrawl MCP Server Tutorial
---
-
# Chapter 3: Tool Selection: Scrape, Map, Crawl, Search, Extract
-Welcome to **Chapter 3: Tool Selection: Scrape, Map, Crawl, Search, Extract**. In this part of **Firecrawl MCP Server Tutorial: Web Scraping and Search Tools for MCP Clients**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
+Firecrawl MCP exposes distinct tools for each information-retrieval pattern. Choosing the right tool avoids unnecessary API credits and reduces latency. This chapter maps each tool to its use case, explains key parameters, and provides the decision logic for complex research tasks.
+## Learning Goals
-Effective Firecrawl usage depends on selecting the right tool for each information-retrieval task.
+- Choose tools based on known vs. unknown URL scope
+- Combine tools for multi-step research pipelines
+- Understand format options and extraction schemas
+- Avoid over-crawling when simpler methods suffice
-## Learning Goals
+## Tool Decision Framework
+
+```mermaid
+flowchart TD
+ START[What do I need?]
+ START --> Q1{Do I have\nexact URLs?}
+ Q1 -- Yes, one URL --> SCRAPE[firecrawl_scrape\nSingle URL, rich formats]
+ Q1 -- Yes, multiple URLs --> BATCH[firecrawl_batch_scrape\nUp to 10 URLs in parallel]
+ Q1 -- No --> Q2{Do I know\nthe domain?}
+ Q2 -- Yes, want URL list --> MAP[firecrawl_map\nDiscover all URLs on domain]
+ Q2 -- Yes, want content --> CRAWL[firecrawl_crawl\nTraverse site, collect pages]
+ Q2 -- No, need web search --> SEARCH[firecrawl_search\nGoogle-style search + scrape]
+ SCRAPE --> Q3{Need structured data?}
+ Q3 -- Yes --> EXTRACT[firecrawl_extract\nLLM-powered schema extraction]
+ Q3 -- No --> DONE[Done]
+```
-- choose tools based on known vs unknown URL scope
-- combine tools for multi-step research tasks
-- avoid over-crawling when simpler methods suffice
+## `firecrawl_scrape` — Single URL Content Extraction
+
+The primary workhorse. Fetches and converts a single URL to the requested output formats. The description in source code: *"The most powerful, fastest and most reliable scraper tool."*
+
+```typescript
+// From src/index.ts — scrapeParamsSchema (key parameters)
+const scrapeParamsSchema = z.object({
+ url: z.string().url(),
+ formats: z.array(z.enum([
+ 'markdown', 'html', 'rawHtml', 'screenshot',
+ 'links', 'summary', 'changeTracking', 'branding',
+ 'json', 'query'
+ ])).optional(),
+ onlyMainContent: z.boolean().optional(), // strip nav/footer
+ waitFor: z.number().optional(), // ms to wait for JS rendering
+ mobile: z.boolean().optional(), // use mobile viewport
+ proxy: z.enum(['basic', 'stealth', 'enhanced', 'auto']).optional(),
+ location: z.object({ country: z.string().optional() }).optional(),
+ storeInCache: z.boolean().optional(), // cache result
+ zeroDataRetention: z.boolean().optional(),// delete after return
+});
+```
-## Tool Selection Matrix
+Key `formats` options:
-| Task Type | Preferred Tool |
-|:----------|:---------------|
-| single known URL | `scrape` |
-| many known URLs | batch scrape variants |
-| discover URLs on a domain | `map` |
-| broad web discovery | `search` |
-| large site traversal | `crawl` with strict limits |
-| structured extraction | `extract` with schema guidance |
+| Format | Output |
+|:-------|:-------|
+| `markdown` | Clean markdown (default, best for LLMs) |
+| `html` | Processed HTML |
+| `rawHtml` | Raw HTML before processing |
+| `screenshot` | Base64-encoded PNG screenshot |
+| `links` | Array of all links on the page |
+| `summary` | LLM-generated page summary |
+| `json` | Structured extraction (requires `jsonOptions.prompt` or `.schema`) |
+| `query` | Answer a specific question about the page content |
-## Source References
+## `firecrawl_map` — URL Discovery
-- [README Tool Guide](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/README.md)
+Returns a list of all URLs on a domain without fetching content. Use this when you need to discover what pages exist before deciding what to scrape.
-## Summary
+```mermaid
+sequenceDiagram
+ participant LLM
+ participant MCP Server
+ participant Firecrawl API
+
+ LLM->>MCP Server: firecrawl_map {url: "https://docs.example.com"}
+ MCP Server->>Firecrawl API: map request
+ Firecrawl API-->>MCP Server: ["/docs/intro", "/docs/api", "/blog/post-1", ...]
+ MCP Server-->>LLM: URL list (up to sitemap limit)
+ LLM->>LLM: Filter relevant URLs
+ LLM->>MCP Server: firecrawl_batch_scrape {urls: [filtered list]}
+```
-You now have a decision framework for tool selection that balances depth, cost, and speed.
+Parameters: `url`, `limit` (max URLs to return), `search` (filter by keyword), `ignoreSitemap`, `includeSubdomains`.
-Next: [Chapter 4: Client Integrations: Cursor, Claude, Windsurf, VS Code](04-client-integrations-cursor-claude-windsurf-vscode.md)
+## `firecrawl_crawl` — Recursive Site Traversal
-## Source Code Walkthrough
+Crawls a site by following internal links, collecting content from each page. Returns a job ID; content is returned asynchronously or polled via `firecrawl_check_crawl_status`.
+
+**Use carefully**: Crawls can consume significant API credits. Always set `maxDepth` and `limit`:
+
+```json
+{
+ "url": "https://docs.example.com",
+ "maxDepth": 2,
+ "limit": 50,
+ "scrapeOptions": {
+ "formats": ["markdown"],
+ "onlyMainContent": true
+ }
+}
+```
-### `src/types/fastmcp.d.ts`
+## `firecrawl_search` — Web Search + Scrape
-The `ToolContext` interface in [`src/types/fastmcp.d.ts`](https://github.com/firecrawl/firecrawl-mcp-server/blob/HEAD/src/types/fastmcp.d.ts) handles a key part of this chapter's functionality:
+Performs a web search and returns scraped content for the top results in a single call. Useful when you don't know which domain contains the information you need.
-```ts
- };
+```mermaid
+flowchart LR
+ QUERY[Search query:\nnpm package zod v4 changes]
+ QUERY --> SEARCH_API[Firecrawl search\n= web search + automatic scraping]
+ SEARCH_API --> RESULTS[Top N results\nwith markdown content]
+ RESULTS --> LLM[LLM synthesizes\nfrom multiple sources]
+```
- export interface ToolContext<Session = unknown> {
- session?: Session;
- log: Logger;
+Parameters: `query`, `limit` (number of results), `lang`, `country`, `scrapeOptions` (format control for each result).
+
+## `firecrawl_extract` — LLM-Powered Structured Extraction
+
+Extracts structured data from one or more URLs using a schema or natural language prompt. Returns a JSON object rather than raw content.
+
+```json
+{
+ "urls": ["https://example.com/product"],
+ "prompt": "Extract product name, price, and availability",
+ "schema": {
+ "type": "object",
+ "properties": {
+ "name": { "type": "string" },
+ "price": { "type": "number" },
+ "available": { "type": "boolean" }
+ }
}
+}
+```
+
+Best for: pricing data, contact information, structured product catalogs, repeated page patterns.
- export type ToolExecute<Session = unknown> = (
+## `firecrawl_batch_scrape` — Parallel Multi-URL Scraping
+
+Submits up to 10 URLs for parallel scraping. Returns a job ID. Poll with `firecrawl_check_batch_scrape_status` to get results.
+
+## Tool Selection Summary
+
+| Tool | Best For | Credit Cost | Response Mode |
+|:-----|:---------|:------------|:--------------|
+| `firecrawl_scrape` | Single known URL | Low (1 credit) | Synchronous |
+| `firecrawl_batch_scrape` | 2–10 known URLs | Medium | Async (poll) |
+| `firecrawl_map` | Discover URLs on domain | Low | Synchronous |
+| `firecrawl_crawl` | Full site content harvest | High | Async (poll) |
+| `firecrawl_search` | Unknown source, topic-first | Medium | Synchronous |
+| `firecrawl_extract` | Structured data extraction | Medium | Sync or Async |
+
+## Source Code Walkthrough
+
+### `src/index.ts`
+
+The `firecrawl_map` tool definition in [`src/index.ts`](https://github.com/mendableai/firecrawl-mcp-server/blob/main/src/index.ts) illustrates the tool registration pattern used by all tools in this chapter:
+
+```ts
+server.addTool({
+ name: 'firecrawl_map',
+ description: `Map a website to discover all indexed URLs on the site.
+
+**Best for:** Discovering URLs on a website before deciding what to scrape...
+**Not recommended for:** When you already know which specific URL you need (use scrape)...`,
+ parameters: z.object({
+ url: z.string().url(),
+ search: z.string().optional(),
+ sitemap: z.enum(['include', 'skip', 'only']).optional(),
+ includeSubdomains: z.boolean().optional(),
+ limit: z.number().optional(),
+ ignoreQueryParameters: z.boolean().optional(),
+ }),
+ execute: async (
args: unknown,
- context: ToolContext<Session>
- ) => unknown | Promise<unknown>;
-
- export class FastMCP<Session = unknown> {
- constructor(options: {
- name: string;
- version?: string;
- logger?: Logger;
- roots?: { enabled?: boolean };
- authenticate?: (
- request: { headers: IncomingHttpHeaders }
- ) => Promise<Session> | Session;
- health?: {
- enabled?: boolean;
- message?: string;
- path?: string;
- status?: number;
- };
- });
-
- addTool(tool: {
- name: string;
- description?: string;
+ { session, log }: { session?: SessionData; log: Logger }
+ ): Promise<string> => {
+ const { url, ...options } = args as { url: string } & Record<string, unknown>;
+ const client = getClient(session);
+ const cleaned = removeEmptyTopLevel(options as Record<string, unknown>);
+ log.info('Mapping URL', { url: String(url) });
+ const res = await client.map(String(url), { ...cleaned, origin: ORIGIN } as any);
+ return asText(res);
+ },
+});
```
-This interface is important because it defines how Firecrawl MCP Server Tutorial: Web Scraping and Search Tools for MCP Clients implements the patterns covered in this chapter.
+This registration pattern is important because it defines how each tool in this chapter connects Zod-validated inputs to the `@mendable/firecrawl-js` SDK client — with `removeEmptyTopLevel` stripping null/empty fields before the API call.
+## Summary
-## How These Components Connect
+`firecrawl_scrape` is the default choice for any known URL. Use `firecrawl_map` to discover URLs before batch-scraping. Use `firecrawl_search` when you don't know the source. Use `firecrawl_crawl` only with explicit depth and limit constraints. Use `firecrawl_extract` when you need structured JSON instead of prose content.
-```mermaid
-flowchart TD
- A[ToolContext]
-```
+Next: [Chapter 4: Client Integrations: Cursor, Claude, Windsurf, VS Code](04-client-integrations-cursor-claude-windsurf-vscode.md)
diff --git a/tutorials/firecrawl-mcp-server-tutorial/04-client-integrations-cursor-claude-windsurf-vscode.md b/tutorials/firecrawl-mcp-server-tutorial/04-client-integrations-cursor-claude-windsurf-vscode.md
index e70cfa09..f0fe7ff3 100644
--- a/tutorials/firecrawl-mcp-server-tutorial/04-client-integrations-cursor-claude-windsurf-vscode.md
+++ b/tutorials/firecrawl-mcp-server-tutorial/04-client-integrations-cursor-claude-windsurf-vscode.md
@@ -5,86 +5,212 @@ nav_order: 4
parent: Firecrawl MCP Server Tutorial
---
-
# Chapter 4: Client Integrations: Cursor, Claude, Windsurf, VS Code
-Welcome to **Chapter 4: Client Integrations: Cursor, Claude, Windsurf, VS Code**. In this part of **Firecrawl MCP Server Tutorial: Web Scraping and Search Tools for MCP Clients**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
-
-
-Firecrawl MCP is widely used because it can be configured across major coding-agent clients.
+Firecrawl MCP is used across multiple MCP host clients. This chapter gives precise configuration blocks for each major integration, explains environment variable handling differences between clients, and covers team standardization practices.
## Learning Goals
-- configure Firecrawl MCP for major client ecosystems
-- standardize environment key handling across clients
-- reduce configuration drift between local and team setups
+- Configure Firecrawl MCP for each major client ecosystem with accurate config blocks
+- Standardize API key handling across clients and environments
+- Reduce configuration drift between local and team setups
+- Know where each client stores and reads its MCP configuration
-## Integration Patterns
+## Integration Overview
-| Client | Integration Style |
-|:-------|:------------------|
-| Cursor | MCP server JSON in settings |
-| Claude Desktop | `claude_desktop_config.json` command block |
-| Windsurf | model config MCP section |
-| VS Code | `mcp.servers` or workspace `mcp.json` |
+```mermaid
+graph TD
+ FIRECRAWL[firecrawl-mcp server\nnpx -y firecrawl-mcp]
+
+ FIRECRAWL --> CLAUDE[Claude Desktop\nclaude_desktop_config.json]
+ FIRECRAWL --> CURSOR[Cursor IDE\n.cursor/mcp.json]
+ FIRECRAWL --> WINDSURF[Windsurf IDE\n~/.codeium/windsurf/mcp_config.json]
+ FIRECRAWL --> VSCODE[VS Code\n.vscode/mcp.json or settings.json]
+ FIRECRAWL --> SMITHERY[Smithery registry\nsmithery.yaml hosted mode]
+```
-## Source References
+## Claude Desktop
-- [README Client Config Sections](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/README.md)
+Config file: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows)
-## Summary
+```json
+{
+ "mcpServers": {
+ "firecrawl": {
+ "command": "npx",
+ "args": ["-y", "firecrawl-mcp"],
+ "env": {
+ "FIRECRAWL_API_KEY": "fc-your-api-key"
+ }
+ }
+ }
+}
+```
-You now have a cross-client setup model for consistent Firecrawl MCP usage.
+For self-hosted Firecrawl:
+```json
+{
+ "mcpServers": {
+ "firecrawl-local": {
+ "command": "npx",
+ "args": ["-y", "firecrawl-mcp"],
+ "env": {
+ "FIRECRAWL_API_URL": "http://localhost:3002"
+ }
+ }
+ }
+}
+```
-Next: [Chapter 5: Configuration, Retries, and Credit Monitoring](05-configuration-retries-and-credit-monitoring.md)
+## Cursor
-## Source Code Walkthrough
+Config file: `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` in the project root (workspace-scoped)
-### `src/index.ts`
+```json
+{
+ "mcpServers": {
+ "firecrawl": {
+ "command": "npx",
+ "args": ["-y", "firecrawl-mcp"],
+ "env": {
+ "FIRECRAWL_API_KEY": "fc-your-api-key"
+ }
+ }
+ }
+}
+```
-The `ConsoleLogger` class in [`src/index.ts`](https://github.com/firecrawl/firecrawl-mcp-server/blob/HEAD/src/index.ts) handles a key part of this chapter's functionality:
+Cursor supports both global and project-level MCP configs. The project-level config takes precedence. This is useful for teams that need different API keys per project.
-```ts
-}
+## Windsurf
-class ConsoleLogger implements Logger {
- private shouldLog =
- process.env.CLOUD_SERVICE === 'true' ||
- process.env.SSE_LOCAL === 'true' ||
- process.env.HTTP_STREAMABLE_SERVER === 'true';
+Config file: `~/.codeium/windsurf/mcp_config.json`
- debug(...args: unknown[]): void {
- if (this.shouldLog) {
- console.debug('[DEBUG]', new Date().toISOString(), ...args);
+```json
+{
+ "mcpServers": {
+ "firecrawl": {
+ "command": "npx",
+ "args": ["-y", "firecrawl-mcp"],
+ "env": {
+ "FIRECRAWL_API_KEY": "fc-your-api-key"
+ }
}
}
- error(...args: unknown[]): void {
- if (this.shouldLog) {
- console.error('[ERROR]', new Date().toISOString(), ...args);
- }
- }
- info(...args: unknown[]): void {
- if (this.shouldLog) {
- console.log('[INFO]', new Date().toISOString(), ...args);
+}
+```
+
+## VS Code (with MCP-capable extensions)
+
+Config in `.vscode/mcp.json` (workspace) or user settings:
+
+```json
+{
+ "servers": {
+ "firecrawl": {
+ "type": "stdio",
+ "command": "npx",
+ "args": ["-y", "firecrawl-mcp"],
+ "env": {
+ "FIRECRAWL_API_KEY": "fc-your-api-key"
+ }
}
}
- log(...args: unknown[]): void {
- if (this.shouldLog) {
- console.log('[LOG]', new Date().toISOString(), ...args);
+}
+```
+
+## Docker-Based Config
+
+For teams that prefer a containerized server (from `Dockerfile` in the repo):
+
+```json
+{
+ "mcpServers": {
+ "firecrawl": {
+ "command": "docker",
+ "args": [
+ "run", "--rm", "-i",
+ "-e", "FIRECRAWL_API_KEY=fc-your-api-key",
+ "firecrawl-mcp:latest"
+ ]
}
}
- warn(...args: unknown[]): void {
- if (this.shouldLog) {
- console.warn('[WARN]', new Date().toISOString(), ...args);
- }
+}
+```
+
+Build the image first:
+```bash
+docker build -t firecrawl-mcp:latest .
```
-This class is important because it defines how Firecrawl MCP Server Tutorial: Web Scraping and Search Tools for MCP Clients implements the patterns covered in this chapter.
+## Smithery Registry (Hosted Mode)
+Firecrawl MCP is listed on [Smithery](https://smithery.ai) as `io.github.firecrawl/firecrawl-mcp-server` (matching the `mcpName` in `package.json`). Smithery-managed hosts can connect directly without running a local process.
-## How These Components Connect
+## API Key Management Across Environments
```mermaid
flowchart TD
- A[ConsoleLogger]
+ APIKEY[FIRECRAWL_API_KEY]
+ APIKEY --> LOCAL[Local dev:\nIn client config env block\nor .env file at project root]
+ APIKEY --> TEAM[Team shared:\nIn 1Password / AWS Secrets Manager\nInjected via dotenv or CI environment]
+ APIKEY --> CI[CI/CD:\nGitHub Actions secret\nOr injected at test time]
+
+ NEVER[Never:\ngit-committed config files\nwith API keys]
```
+
+**Best practice**: Never put real API keys in config files committed to source control. Use:
+- Cursor/Windsurf/Claude Desktop: local config files outside the project directory (already excluded from git by default since they live in `~/.config` or `~/Library/...`)
+- VS Code workspace configs: add `.vscode/mcp.json` to `.gitignore` if it contains credentials, or reference environment variables via `${env:FIRECRAWL_API_KEY}` syntax if supported by your extension
+
+## Cross-Client Validation
+
+After setting up any client:
+
+```
+1. Open a conversation or coding session in the client
+2. Ask: "List all available MCP tools"
+ → Should include firecrawl_scrape, firecrawl_search, etc.
+3. Ask: "Scrape https://example.com and give me the main content as markdown"
+ → Should return clean markdown content
+4. Ask: "Search the web for 'MCP TypeScript SDK v2 changes'"
+ → Should return search results with scraped content
+```
+
+## Source Code Walkthrough
+
+### `smithery.yaml`
+
+The [`smithery.yaml`](https://github.com/mendableai/firecrawl-mcp-server/blob/main/smithery.yaml) config file defines the canonical client integration pattern used by Smithery and serves as the reference spec for all client configs in this chapter:
+
+```yaml
+startCommand:
+ type: stdio
+ configSchema:
+ type: object
+ required:
+ - fireCrawlApiKey
+ properties:
+ fireCrawlApiKey:
+ type: string
+ description: Your Firecrawl API key. Required for cloud API usage.
+ fireCrawlApiUrl:
+ type: string
+ description:
+ Custom API endpoint for self-hosted instances. If provided, API key
+ becomes optional.
+ commandFunction:
+ |-
+ (config) => ({ command: 'node', args: ['dist/index.js'], env: {
+ FIRECRAWL_API_KEY: config.fireCrawlApiKey,
+ FIRECRAWL_API_URL: config.fireCrawlApiUrl || ''
+ } })
+```
+
+This file is important because it defines the canonical config interface: `FIRECRAWL_API_KEY` is required for cloud use, and `FIRECRAWL_API_URL` makes the key optional for self-hosted deployments — the same contract mirrored in every client config (Cursor, Claude Desktop, Windsurf, VS Code) covered in this chapter.
+
+## Summary
+
+All major MCP-capable clients use the same config pattern: `command: npx, args: [-y, firecrawl-mcp], env: {FIRECRAWL_API_KEY: ...}`. The only variation is the config file location. Avoid committing API keys — use environment injection or local-only config files. Docker provides a reproducible alternative to `npx` for teams that need version-pinned deployments.
+
+Next: [Chapter 5: Configuration, Retries, and Credit Monitoring](05-configuration-retries-and-credit-monitoring.md)
diff --git a/tutorials/firecrawl-mcp-server-tutorial/05-configuration-retries-and-credit-monitoring.md b/tutorials/firecrawl-mcp-server-tutorial/05-configuration-retries-and-credit-monitoring.md
index bb3c735a..0c4f2752 100644
--- a/tutorials/firecrawl-mcp-server-tutorial/05-configuration-retries-and-credit-monitoring.md
+++ b/tutorials/firecrawl-mcp-server-tutorial/05-configuration-retries-and-credit-monitoring.md
@@ -5,87 +5,182 @@ nav_order: 5
parent: Firecrawl MCP Server Tutorial
---
-
# Chapter 5: Configuration, Retries, and Credit Monitoring
-Welcome to **Chapter 5: Configuration, Retries, and Credit Monitoring**. In this part of **Firecrawl MCP Server Tutorial: Web Scraping and Search Tools for MCP Clients**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
+Production reliability of Firecrawl MCP depends on correct retry behavior, credit threshold awareness, and proper endpoint configuration. This chapter covers all environment variables that affect runtime behavior and how to tune them for your workload.
+## Learning Goals
-Production reliability depends on proper retry controls and credit thresholds.
+- Configure retry behavior for rate-limited and transient failure environments
+- Tune credit warning and critical thresholds to prevent service interruptions
+- Support cloud and self-hosted API endpoints cleanly
+- Understand how the logger activates and what it captures
-## Learning Goals
+## Full Environment Variable Reference
-- configure retry behavior for rate-limited environments
-- tune warning and critical thresholds for credits
-- support cloud and self-hosted API endpoints cleanly
+```mermaid
+graph TD
+ ENV[Environment Variables]
+ ENV --> AUTH[Authentication]
+ ENV --> ENDPOINT[Endpoint]
+ ENV --> RETRY[Retry/Backoff]
+ ENV --> CREDITS[Credit Monitoring]
+ ENV --> MODE[Transport Mode]
+
+ AUTH --> AK[FIRECRAWL_API_KEY\nCloud API key]
+ ENDPOINT --> URL[FIRECRAWL_API_URL\nSelf-hosted base URL]
+ RETRY --> MAX[FIRECRAWL_RETRY_MAX_ATTEMPTS\nDefault: 3]
+ RETRY --> INIT[FIRECRAWL_RETRY_INITIAL_DELAY\nDefault: 1000ms]
+ RETRY --> MAX_D[FIRECRAWL_RETRY_MAX_DELAY\nDefault: 10000ms]
+ RETRY --> MULT[FIRECRAWL_RETRY_BACKOFF_FACTOR\nDefault: 2]
+ CREDITS --> WARN[FIRECRAWL_CREDIT_WARNING_THRESHOLD\nDefault: 1000]
+ CREDITS --> CRIT[FIRECRAWL_CREDIT_CRITICAL_THRESHOLD\nDefault: 100]
+ MODE --> CS[CLOUD_SERVICE\nSSE_LOCAL\nHTTP_STREAMABLE_SERVER]
+```
-## Key Environment Variables
+## Retry Configuration
-| Variable | Purpose |
-|:---------|:--------|
-| `FIRECRAWL_API_KEY` | authentication for cloud usage |
-| `FIRECRAWL_API_URL` | custom endpoint for self-hosted deployments |
-| `FIRECRAWL_RETRY_*` | retry/backoff behavior controls |
-| `FIRECRAWL_CREDIT_*` | warning and critical credit thresholds |
+The server implements exponential backoff with jitter for all Firecrawl API calls. Configure with:
-## Source References
+| Variable | Default | Description |
+|:---------|:--------|:------------|
+| `FIRECRAWL_RETRY_MAX_ATTEMPTS` | `3` | Maximum retry attempts per call |
+| `FIRECRAWL_RETRY_INITIAL_DELAY` | `1000` | Initial delay in milliseconds |
+| `FIRECRAWL_RETRY_MAX_DELAY` | `10000` | Maximum delay cap in milliseconds |
+| `FIRECRAWL_RETRY_BACKOFF_FACTOR` | `2` | Exponential backoff multiplier |
-- [README Configuration](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/README.md)
-- [Changelog 1.2.4 and 1.2.0](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/CHANGELOG.md)
+### Backoff Calculation
-## Summary
+With defaults, the retry delays work as:
+- Attempt 1 fail → wait ~1000ms (+ jitter)
+- Attempt 2 fail → wait ~2000ms (+ jitter)
+- Attempt 3 fail → return error to client
-You now know which controls matter most for resilient Firecrawl MCP operations.
+```
+delay = min(INITIAL_DELAY * BACKOFF_FACTOR^(attempt-1), MAX_DELAY) + jitter
+```
-Next: [Chapter 6: Batch Workflows, Deep Research, and API Evolution](06-batch-workflows-deep-research-and-api-evolution.md)
+```mermaid
+flowchart TD
+ CALL[API call to Firecrawl]
+ CALL --> RESP{Response}
+ RESP -- Success --> RETURN[Return result to MCP client]
+ RESP -- 429 Rate Limited --> RETRY{Attempts < MAX_ATTEMPTS?}
+ RESP -- 5xx Transient --> RETRY
+ RETRY -- Yes --> WAIT[Wait: exponential backoff\nwith jitter]
+ WAIT --> CALL
+ RETRY -- No --> ERROR[Return error to MCP client]
+```
+
+### Tuning for Your Workload
+
+For batch research workloads (many calls in sequence):
+```bash
+FIRECRAWL_RETRY_MAX_ATTEMPTS=5
+FIRECRAWL_RETRY_INITIAL_DELAY=2000
+FIRECRAWL_RETRY_MAX_DELAY=30000
+FIRECRAWL_RETRY_BACKOFF_FACTOR=2
+```
+
+For interactive use (user waiting for response):
+```bash
+FIRECRAWL_RETRY_MAX_ATTEMPTS=2
+FIRECRAWL_RETRY_INITIAL_DELAY=500
+FIRECRAWL_RETRY_MAX_DELAY=3000
+```
+
+## Credit Monitoring
+
+Firecrawl cloud accounts have an API credit balance. The server watches credit usage and can warn or fail gracefully before credits are exhausted.
-## Source Code Walkthrough
+| Variable | Default | Effect |
+|:---------|:--------|:-------|
+| `FIRECRAWL_CREDIT_WARNING_THRESHOLD` | `1000` | Log a warning when credits fall below this level |
+| `FIRECRAWL_CREDIT_CRITICAL_THRESHOLD` | `100` | Return an error instead of calling API when below this level |
-### `src/index.ts`
+### Credit Thresholds in Practice
-The `extractApiKey` function in [`src/index.ts`](https://github.com/firecrawl/firecrawl-mcp-server/blob/HEAD/src/index.ts) handles a key part of this chapter's functionality:
+```mermaid
+flowchart LR
+ CREDITS[Current credit balance]
+ CREDITS -->|above warning| NORMAL[Normal operation]
+ CREDITS -->|below WARNING\nthreshold| WARN[Log warning:\nLow credit balance]
+ CREDITS -->|below CRITICAL\nthreshold| BLOCK[Block API calls:\nReturn credit error to client]
+```
+
+Set thresholds based on your usage patterns:
+- **High-volume batch jobs**: Raise `FIRECRAWL_CREDIT_WARNING_THRESHOLD` to 5000 to get earlier notice
+- **Shared team account**: Set `FIRECRAWL_CREDIT_CRITICAL_THRESHOLD` to 500 to leave a buffer for other users
+- **Individual developer**: Lower thresholds are fine
+
+## Self-Hosted Configuration
+
+For a self-hosted Firecrawl instance:
-```ts
+```bash
+FIRECRAWL_API_URL=http://localhost:3002
+# No FIRECRAWL_API_KEY needed when API_URL is set
+```
+
+The `createClient` function in `src/index.ts` handles this:
+```typescript
+function createClient(apiKey?: string): FirecrawlApp {
+ const config: any = {
+ ...(process.env.FIRECRAWL_API_URL && {
+ apiUrl: process.env.FIRECRAWL_API_URL,
+ }),
+ };
+ if (apiKey) config.apiKey = apiKey;
+ return new FirecrawlApp(config);
}
+```
-function extractApiKey(headers: IncomingHttpHeaders): string | undefined {
- const headerAuth = headers['authorization'];
- const headerApiKey = (headers['x-firecrawl-api-key'] ||
- headers['x-api-key']) as string | string[] | undefined;
+When `FIRECRAWL_API_URL` is set, the `apiKey` is passed only if provided — allowing anonymous self-hosted access.
- if (headerApiKey) {
- return Array.isArray(headerApiKey) ? headerApiKey[0] : headerApiKey;
- }
+## Logging Configuration
- if (
- typeof headerAuth === 'string' &&
- headerAuth.toLowerCase().startsWith('bearer ')
- ) {
- return headerAuth.slice(7).trim();
- }
+The `ConsoleLogger` in `src/index.ts` only activates when running in a service transport mode:
- return undefined;
+```typescript
+class ConsoleLogger {
+ private shouldLog =
+ process.env.CLOUD_SERVICE === 'true' ||
+ process.env.SSE_LOCAL === 'true' ||
+ process.env.HTTP_STREAMABLE_SERVER === 'true';
}
+```
-function removeEmptyTopLevel<T extends Record<string, any>>(
- obj: T
-): Partial<T> {
- const out: Partial<T> = {};
- for (const [k, v] of Object.entries(obj)) {
- if (v == null) continue;
- if (typeof v === 'string' && v.trim() === '') continue;
- if (Array.isArray(v) && v.length === 0) continue;
- if (
- typeof v === 'object' &&
- !Array.isArray(v) &&
+In stdio mode (desktop clients), logging is suppressed to keep stdout clean for the JSON-RPC protocol. Enable it by running in SSE or HTTP mode, or add your own stderr-based logging.
+
+## Complete Production Config Example
+
+```json
+{
+ "mcpServers": {
+ "firecrawl": {
+ "command": "npx",
+ "args": ["-y", "firecrawl-mcp@3"],
+ "env": {
+ "FIRECRAWL_API_KEY": "fc-your-api-key",
+ "FIRECRAWL_RETRY_MAX_ATTEMPTS": "4",
+ "FIRECRAWL_RETRY_INITIAL_DELAY": "1500",
+ "FIRECRAWL_RETRY_MAX_DELAY": "15000",
+ "FIRECRAWL_CREDIT_WARNING_THRESHOLD": "2000",
+ "FIRECRAWL_CREDIT_CRITICAL_THRESHOLD": "200"
+ }
+ }
+ }
+}
```
-This function is important because it defines how Firecrawl MCP Server Tutorial: Web Scraping and Search Tools for MCP Clients implements the patterns covered in this chapter.
+## Source References
+
+- [README Configuration](https://github.com/mendableai/firecrawl-mcp-server/blob/main/README.md)
+- [CHANGELOG](https://github.com/mendableai/firecrawl-mcp-server/blob/main/CHANGELOG.md)
+- [src/index.ts — createClient, ConsoleLogger](https://github.com/mendableai/firecrawl-mcp-server/blob/main/src/index.ts)
+## Summary
-## How These Components Connect
+Retry behavior is configured via four `FIRECRAWL_RETRY_*` environment variables using exponential backoff with defaults that work for most cases. Credit monitoring uses two threshold variables that trigger warnings and hard blocks. Self-hosted deployments set `FIRECRAWL_API_URL` (making `FIRECRAWL_API_KEY` optional). Logging only activates in non-stdio transport modes to protect the JSON-RPC stream.
-```mermaid
-flowchart TD
- A[extractApiKey]
-```
+Next: [Chapter 6: Batch Workflows, Deep Research, and API Evolution](06-batch-workflows-deep-research-and-api-evolution.md)
diff --git a/tutorials/firecrawl-mcp-server-tutorial/06-batch-workflows-deep-research-and-api-evolution.md b/tutorials/firecrawl-mcp-server-tutorial/06-batch-workflows-deep-research-and-api-evolution.md
index 1114e04d..a4966aef 100644
--- a/tutorials/firecrawl-mcp-server-tutorial/06-batch-workflows-deep-research-and-api-evolution.md
+++ b/tutorials/firecrawl-mcp-server-tutorial/06-batch-workflows-deep-research-and-api-evolution.md
@@ -5,85 +5,181 @@ nav_order: 6
parent: Firecrawl MCP Server Tutorial
---
-
# Chapter 6: Batch Workflows, Deep Research, and API Evolution
-Welcome to **Chapter 6: Batch Workflows, Deep Research, and API Evolution**. In this part of **Firecrawl MCP Server Tutorial: Web Scraping and Search Tools for MCP Clients**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
+This chapter covers multi-step research workflows using Firecrawl MCP tools in sequence, explains the async batch job model, and documents the historical evolution from V1-era tools to the current V2 API surface.
+## Learning Goals
-Firecrawl MCP has evolved from legacy V1 tooling to modern V2 behavior; teams need to plan around those differences.
+- Build multi-step deep research pipelines with combined tools
+- Use batch jobs and polling patterns correctly for async operations
+- Map V1-only capabilities versus V2 defaults
+- Plan endpoint migration without breaking LLM workflows
-## Learning Goals
+## Multi-Step Research Pattern
-- understand batch processing behavior and limits
-- map V1-only capabilities versus V2 defaults
-- plan endpoint migration without breaking clients
+Firecrawl tools compose naturally in agentic workflows. A typical deep research pipeline:
-## Evolution Highlights
+```mermaid
+flowchart TD
+ TOPIC[Research topic:\nMCP protocol changes in 2025]
+ TOPIC --> SEARCH[Step 1: firecrawl_search\nFind relevant sources]
+ SEARCH --> MAP[Step 2: firecrawl_map\nDiscover URL structure of\nhighest-value domains]
+ MAP --> BATCH[Step 3: firecrawl_batch_scrape\nScrape filtered URLs in parallel]
+ BATCH --> EXTRACT[Step 4: firecrawl_extract\nExtract structured facts with schema]
+ EXTRACT --> SYNTHESIZE[LLM synthesizes\nfrom structured results]
+```
-| Version | Notable Focus |
-|:--------|:--------------|
-| V1 | legacy endpoints plus deep-research/llmstxt oriented tools |
-| V2 | modern API methods, improved extraction/search behavior |
+### Pattern 1: Search → Batch Scrape
-## Source References
+When you don't know the source domain:
-- [Versioning Guide](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/VERSIONING.md)
-- [README Tool Guidance](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/README.md)
+```
+1. firecrawl_search("MCP protocol StreamableHTTP transport", limit=5)
+ → Returns top 5 URLs with initial content snippets
-## Summary
+2. firecrawl_batch_scrape([url1, url2, url3, ...], formats=["markdown"])
+ → Submits batch job, returns job_id
-You now have a migration-aware perspective on batch and advanced Firecrawl MCP usage.
+3. firecrawl_check_batch_scrape_status(job_id)
+ → Poll until status == "completed", returns full content per URL
+```
-Next: [Chapter 7: Reliability, Observability, and Failure Handling](07-reliability-observability-and-failure-handling.md)
+### Pattern 2: Map → Targeted Scrape
-## Source Code Walkthrough
+When you know the domain but need specific pages:
-### `src/index.ts`
+```
+1. firecrawl_map("https://modelcontextprotocol.io", search="transport")
+ → Returns filtered URL list matching "transport"
+
+2. firecrawl_scrape(url, formats=["markdown"], onlyMainContent=true)
+ → For each relevant URL (if small number)
+ Or
+ firecrawl_batch_scrape([urls], ...)
+ → For larger URL sets
+```
-The `createClient` function in [`src/index.ts`](https://github.com/firecrawl/firecrawl-mcp-server/blob/HEAD/src/index.ts) handles a key part of this chapter's functionality:
+### Pattern 3: Crawl + Extract for Structured Research
-```ts
-});
+```
+1. firecrawl_crawl("https://docs.example.com", maxDepth=2, limit=30)
+ → Starts crawl job, returns crawl_id
-function createClient(apiKey?: string): FirecrawlApp {
- const config: any = {
- ...(process.env.FIRECRAWL_API_URL && {
- apiUrl: process.env.FIRECRAWL_API_URL,
- }),
- };
+2. firecrawl_check_crawl_status(crawl_id)
+ → Poll until complete
- // Only add apiKey if it's provided (required for cloud, optional for self-hosted)
- if (apiKey) {
- config.apiKey = apiKey;
- }
+3. firecrawl_extract([all crawled URLs],
+ schema={"type":"object","properties":{"summary":{"type":"string"}}})
+ → Extract structured summaries across all pages
+```
- return new FirecrawlApp(config);
-}
+## Async Job Model
-const ORIGIN = 'mcp-fastmcp';
+Several tools run asynchronously and return job IDs:
-// Safe mode is enabled by default for cloud service to comply with ChatGPT safety requirements
-const SAFE_MODE = process.env.CLOUD_SERVICE === 'true';
+```mermaid
+sequenceDiagram
+ participant LLM
+ participant MCP Server
+ participant Firecrawl API
+
+ LLM->>MCP Server: firecrawl_crawl {url, maxDepth, limit}
+ MCP Server->>Firecrawl API: POST /v1/crawl
+ Firecrawl API-->>MCP Server: {id: "crawl-abc123"}
+ MCP Server-->>LLM: {crawl_id: "crawl-abc123", status: "started"}
+
+ loop Poll until complete
+ LLM->>MCP Server: firecrawl_check_crawl_status {crawl_id}
+ MCP Server->>Firecrawl API: GET /v1/crawl/crawl-abc123
+ Firecrawl API-->>MCP Server: {status: "scraping", completed: 15, total: 30}
+ MCP Server-->>LLM: status update
+ end
+
+ LLM->>MCP Server: firecrawl_check_crawl_status {crawl_id}
+ MCP Server->>Firecrawl API: GET /v1/crawl/crawl-abc123
+ Firecrawl API-->>MCP Server: {status: "completed", data: [...]}
+ MCP Server-->>LLM: full crawl results
+```
-function getClient(session?: SessionData): FirecrawlApp {
- // For cloud service, API key is required
- if (process.env.CLOUD_SERVICE === 'true') {
- if (!session || !session.firecrawlApiKey) {
- throw new Error('Unauthorized');
- }
- return createClient(session.firecrawlApiKey);
- }
+## V1 vs V2 API Evolution
+
+The server's `VERSIONING.md` documents the transition. The MCP server (v3+) always calls V2 endpoints via the `@mendable/firecrawl-js` SDK.
- // For self-hosted instances, API key is optional if FIRECRAWL_API_URL is provided
+```mermaid
+graph LR
+ V1[V1 legacy API\n/v0/* endpoints]
+ V2[V2 modern API\n/v1/* endpoints]
+
+ V1 --> CRAWL1[v0/crawl\nblocking, simpler params]
+ V1 --> SCRAPE1[v0/scrape\nbasic formats]
+ V1 --> SEARCH1[/search\nbasic search]
+
+ V2 --> CRAWL2[v1/crawl\nasync, webhook support\nbatch scraping]
+ V2 --> SCRAPE2[v1/scrape\nrich formats: json, query,\nchangeTracking, branding]
+ V2 --> SEARCH2[v1/search\ncountry, language filters]
+ V2 --> EXTRACT2[v1/extract\nLLM-powered extraction]
+ V2 --> BATCH2[v1/batch/scrape\nparallel job model]
```
-This function is important because it defines how Firecrawl MCP Server Tutorial: Web Scraping and Search Tools for MCP Clients implements the patterns covered in this chapter.
+### MCP Server Version to API Version Mapping
+| MCP Server Version | Default API | Notes |
+|:-------------------|:------------|:------|
+| v1.x | V1 (legacy) | Deprecated |
+| v2.x | V1 + V2 mixed | Transition period |
+| v3.x (current) | V2 exclusively | All new features, `@mendable/firecrawl-js` v4 |
-## How These Components Connect
+If you pin `npx -y firecrawl-mcp@2`, you get V1-era tool behavior. Always use `firecrawl-mcp@3` or latest for V2 tools.
-```mermaid
-flowchart TD
- A[createClient]
+## Special Tools: `firecrawl_deep_research` and `firecrawl_generate_llmstxt`
+
+V3 introduced dedicated high-level research tools that orchestrate multiple API calls internally:
+
+### `firecrawl_deep_research`
+
+Runs a multi-step research workflow automatically — searches, maps, scrapes, and synthesizes. Returns a comprehensive research report.
+
+```json
+{
+ "query": "How does the MCP protocol handle authentication in 2025?",
+ "maxDepth": 3,
+ "timeLimit": 120,
+ "maxUrls": 20
+}
```
+
+### `firecrawl_generate_llmstxt`
+
+Generates an `llms.txt`-format document from a website, suitable for providing a site's content as LLM context. Based on the [llms.txt standard](https://llmstxt.org).
+
+## `removeEmptyTopLevel` Parameter Cleaning
+
+The server includes a utility function that removes empty, null, or zero-length fields from request payloads before sending to the API:
+
+```typescript
+function removeEmptyTopLevel<T extends Record<string, any>>(obj: T): Partial<T> {
+ const out: Partial<T> = {};
+ for (const [k, v] of Object.entries(obj)) {
+ if (v == null) continue;
+ if (typeof v === 'string' && v.trim() === '') continue;
+ if (Array.isArray(v) && v.length === 0) continue;
+ if (typeof v === 'object' && !Array.isArray(v) && Object.keys(v).length === 0) continue;
+ out[k] = v;
+ }
+ return out;
+}
+```
+
+This prevents sending empty `actions: []` or `location: {}` to the API, which would otherwise cause validation errors.
+
+## Source References
+
+- [VERSIONING.md](https://github.com/mendableai/firecrawl-mcp-server/blob/main/VERSIONING.md)
+- [src/index.ts — tool implementations](https://github.com/mendableai/firecrawl-mcp-server/blob/main/src/index.ts)
+
+## Summary
+
+Firecrawl tools compose into powerful research pipelines: search to discover sources, map to navigate domains, batch-scrape for parallel collection, extract for structured output. Async tools (crawl, batch_scrape) use a poll-and-wait pattern with job IDs. The v3 MCP server runs V2 API endpoints exclusively — pin to `firecrawl-mcp@3` or use `latest` for current tool behavior.
+
+Next: [Chapter 7: Reliability, Observability, and Failure Handling](07-reliability-observability-and-failure-handling.md)
diff --git a/tutorials/firecrawl-mcp-server-tutorial/07-reliability-observability-and-failure-handling.md b/tutorials/firecrawl-mcp-server-tutorial/07-reliability-observability-and-failure-handling.md
index e345cdf4..e2966462 100644
--- a/tutorials/firecrawl-mcp-server-tutorial/07-reliability-observability-and-failure-handling.md
+++ b/tutorials/firecrawl-mcp-server-tutorial/07-reliability-observability-and-failure-handling.md
@@ -5,85 +5,162 @@ nav_order: 7
parent: Firecrawl MCP Server Tutorial
---
-
# Chapter 7: Reliability, Observability, and Failure Handling
-Welcome to **Chapter 7: Reliability, Observability, and Failure Handling**. In this part of **Firecrawl MCP Server Tutorial: Web Scraping and Search Tools for MCP Clients**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
+This chapter turns error handling and operational controls into a concrete runbook. It covers how the server handles Firecrawl API failures, what constitutes a reliable tool response, and how to instrument enough observability to diagnose failures.
+## Learning Goals
-This chapter turns error handling and operational controls into an explicit runbook.
+- Detect and handle rate-limit and transient failure patterns from the Firecrawl API
+- Instrument sufficient logging to debug tool-call failures
+- Prevent runaway crawl workloads from consuming excessive credits
+- Understand the error response format MCP clients receive
-## Learning Goals
+## Error Response Model
-- detect and handle rate-limit and transient failure patterns
-- instrument enough logging to debug tool-call failures
-- prevent runaway crawl workloads
+When a Firecrawl API call fails after exhausting retries, the server returns an error as a tool result — not as a JSON-RPC error. This means the LLM receives the error message and can communicate it to the user or retry with different parameters.
-## Reliability Practices
+```mermaid
+flowchart TD
+ CALL[Tool call: firecrawl_scrape]
+ CALL --> API[Firecrawl API call]
+ API --> RESP{Response code}
+
+ RESP -- 200 OK --> SUCCESS[Return content to LLM]
+ RESP -- 429 Rate Limited --> RETRY[Retry with backoff]
+ RESP -- 401 Unauthorized --> AUTH_ERR[Error: Invalid API key]
+ RESP -- 402 Payment Required --> CREDIT_ERR[Error: Insufficient credits]
+ RESP -- 5xx Server Error --> RETRY
+ RETRY -->|max attempts exceeded| FAIL[Return error text to LLM]
+ AUTH_ERR --> FAIL
+ CREDIT_ERR --> FAIL
+```
-1. set retry values intentionally for your workload profile
-2. cap crawl depth and scope per request
-3. monitor credit thresholds and alert before service interruption
-4. track client errors by transport and endpoint version
+Error responses from the server follow this pattern:
+```json
+{
+ "content": [
+ {
+ "type": "text",
+ "text": "Error: Failed to scrape URL after 3 attempts. Last error: 429 Too Many Requests"
+ }
+ ]
+}
+```
-## Source References
+The LLM can parse this and decide to retry, try an alternative URL, or report the failure to the user.
-- [README Rate Limiting and Configuration](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/README.md)
-- [Changelog](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/CHANGELOG.md)
+## Authentication Failure Modes
-## Summary
+```mermaid
+flowchart LR
+ AUTHFAIL[Authentication failures]
+ AUTHFAIL --> F1[FIRECRAWL_API_KEY missing\n→ server exits at startup]
+ AUTHFAIL --> F2[Invalid API key\n→ 401 on first API call\nreturned as tool error]
+ AUTHFAIL --> F3[Expired API key\n→ 401 on first API call\nreturned as tool error]
+ AUTHFAIL --> F4[Cloud mode: no header key\n→ authenticate() throws\nconnection rejected]
+```
-You now have a reliability checklist for sustained Firecrawl MCP operations.
+For cloud mode (`CLOUD_SERVICE=true`), authentication failures reject the MCP connection at the `authenticate` callback level — before any tools can be called. For local mode, the API key is validated on the first actual API call.
-Next: [Chapter 8: Security, Governance, and Contribution Workflow](08-security-governance-and-contribution-workflow.md)
+## Rate Limiting Defense
-## Source Code Walkthrough
+The primary protection against rate limiting is the exponential backoff retry system (see Chapter 5). Additional strategies:
-### `src/index.ts`
+### Tool Call Throttling
-The `getClient` function in [`src/index.ts`](https://github.com/firecrawl/firecrawl-mcp-server/blob/HEAD/src/index.ts) handles a key part of this chapter's functionality:
+If you're driving many tool calls from an agentic loop, add delays between calls in your agent logic:
-```ts
-const SAFE_MODE = process.env.CLOUD_SERVICE === 'true';
+```python
+# In an agentic framework driving Firecrawl tool calls
+import asyncio
-function getClient(session?: SessionData): FirecrawlApp {
- // For cloud service, API key is required
- if (process.env.CLOUD_SERVICE === 'true') {
- if (!session || !session.firecrawlApiKey) {
- throw new Error('Unauthorized');
- }
- return createClient(session.firecrawlApiKey);
- }
+for url in urls_to_scrape:
+ result = await client.call_tool("firecrawl_scrape", {"url": url, "formats": ["markdown"]})
+ await asyncio.sleep(0.5) # 500ms between calls to stay under rate limits
+```
- // For self-hosted instances, API key is optional if FIRECRAWL_API_URL is provided
- if (
- !process.env.FIRECRAWL_API_URL &&
- (!session || !session.firecrawlApiKey)
- ) {
- throw new Error(
- 'Unauthorized: API key is required when not using a self-hosted instance'
- );
- }
+### Prefer Batch Operations
- return createClient(session?.firecrawlApiKey);
-}
+Use `firecrawl_batch_scrape` instead of calling `firecrawl_scrape` in a loop — the batch endpoint is optimized for parallel processing within Firecrawl's infrastructure and counts against rate limits differently than sequential single-URL calls.
+
+## Preventing Runaway Crawls
-function asText(data: unknown): string {
- return JSON.stringify(data, null, 2);
+`firecrawl_crawl` without limits can consume hundreds of credits on large sites. Always set explicit limits:
+
+```json
+{
+ "url": "https://docs.example.com",
+ "maxDepth": 2,
+ "limit": 50,
+ "maxDiscoveryDepth": 2,
+ "scrapeOptions": {
+ "formats": ["markdown"],
+ "onlyMainContent": true
+ }
}
+```
+
+| Parameter | Recommended Limit | Rationale |
+|:----------|:------------------|:----------|
+| `maxDepth` | 2–3 | Prevents infinite link-following |
+| `limit` | 20–100 | Hard cap on total pages |
+| `maxDiscoveryDepth` | Same as `maxDepth` | Controls URL discovery breadth |
+
+## Observability: What to Monitor
-// scrape tool (v2 semantics, minimal args)
-// Centralized scrape params (used by scrape, and referenced in search/crawl scrapeOptions)
+### In Stdio Mode (Desktop Clients)
-// Define safe action types
+Logging is suppressed by `ConsoleLogger` in stdio mode. To add diagnostic output without polluting the JSON-RPC stream:
+
+```typescript
+// Write debug info to stderr (safe in stdio mode)
+process.stderr.write(`[debug] Scraping URL: ${url}\n`);
```
-This function is important because it defines how Firecrawl MCP Server Tutorial: Web Scraping and Search Tools for MCP Clients implements the patterns covered in this chapter.
+Stderr output is captured to Claude Desktop's MCP log: `~/Library/Logs/Claude/mcp-server-firecrawl.log`
+### In Service Mode
-## How These Components Connect
+With `CLOUD_SERVICE=true`, `SSE_LOCAL=true`, or `HTTP_STREAMABLE_SERVER=true`, the `ConsoleLogger` activates and writes timestamped `[DEBUG]`, `[INFO]`, `[WARN]`, `[ERROR]` lines to stdout.
```mermaid
-flowchart TD
- A[getClient]
+graph TD
+ LOG[ConsoleLogger output]
+ LOG --> DEBUG[debug: per-tool call entry/exit]
+ LOG --> INFO[info: server startup, transport binding]
+ LOG --> WARN[warn: retry attempts, credit thresholds]
+ LOG --> ERROR[error: authentication failures, API errors after max retries]
+```
+
+## Failure Recovery Runbook
+
+| Failure | Diagnosis | Recovery |
+|:--------|:----------|:---------|
+| Tool not appearing in client | Config syntax error | Validate JSON, check npx path |
+| All tools return "Unauthorized" | Invalid or missing API key | Check `FIRECRAWL_API_KEY` in env |
+| Tools fail with "credit" error | Credits below critical threshold | Top up Firecrawl account credits |
+| Scrape returns empty content | JavaScript-heavy page, no wait | Add `waitFor: 2000` to scrape params |
+| Crawl job stuck in "scraping" | Site has anti-bot protection | Use `proxy: "stealth"` option |
+| Batch job returns partial results | Some URLs failed | Check per-URL status in batch result |
+
+## Health Endpoint
+
+In HTTP transport modes, the server exposes a health endpoint:
+
```
+GET /health → 200 OK body: "ok"
+```
+
+This is configured in `server` initialization and is useful for load balancer health checks in hosted deployments.
+
+## Source References
+
+- [src/index.ts — error handling and retry logic](https://github.com/mendableai/firecrawl-mcp-server/blob/main/src/index.ts)
+- [CHANGELOG](https://github.com/mendableai/firecrawl-mcp-server/blob/main/CHANGELOG.md)
+
+## Summary
+
+Firecrawl MCP returns errors as tool content (not JSON-RPC errors) so the LLM can handle them gracefully. Authentication failures in local mode surface on first API call; in cloud mode they reject the connection at authentication time. The most important reliability controls are: exponential backoff (tuned via env vars), crawl depth and page limits, and credit monitoring thresholds. In stdio mode, log to stderr for diagnostics without corrupting the MCP stream.
+
+Next: [Chapter 8: Security, Governance, and Contribution Workflow](08-security-governance-and-contribution-workflow.md)
diff --git a/tutorials/firecrawl-mcp-server-tutorial/08-security-governance-and-contribution-workflow.md b/tutorials/firecrawl-mcp-server-tutorial/08-security-governance-and-contribution-workflow.md
index 225d1183..0a632e2e 100644
--- a/tutorials/firecrawl-mcp-server-tutorial/08-security-governance-and-contribution-workflow.md
+++ b/tutorials/firecrawl-mcp-server-tutorial/08-security-governance-and-contribution-workflow.md
@@ -5,87 +5,182 @@ nav_order: 8
parent: Firecrawl MCP Server Tutorial
---
-
# Chapter 8: Security, Governance, and Contribution Workflow
-Welcome to **Chapter 8: Security, Governance, and Contribution Workflow**. In this part of **Firecrawl MCP Server Tutorial: Web Scraping and Search Tools for MCP Clients**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
+This chapter covers API key security, scraping governance policies, Docker-based deployment controls, and the contribution workflow for `firecrawl-mcp`.
+## Learning Goals
-This chapter concludes with governance patterns for production use and contribution pathways.
+- Manage API keys and endpoint trust boundaries safely
+- Define governance around scraping behavior and data handling
+- Align contribution work with versioning and release rhythm
+- Understand safe mode and its compliance implications
-## Learning Goals
+## API Key Security
-- manage API keys and endpoint trust boundaries safely
-- define governance around scraping behavior and data handling
-- align contribution work with versioning and release rhythm
+```mermaid
+flowchart TD
+ APIKEY[FIRECRAWL_API_KEY]
+ APIKEY --> LOCAL[Local use:\nIn client config env block\nnever in project files]
+ APIKEY --> TEAM[Team/shared use:\nSecrets manager\ninjected at runtime]
+ APIKEY --> CLOUD[Hosted service:\nPer-request header auth\nCLOUD_SERVICE=true mode]
+
+ LOCAL --> ROTATE[Rotate quarterly\nor on personnel change]
+ TEAM --> AUDIT[Audit access to secrets]
+ CLOUD --> HEADER[Header: x-firecrawl-api-key\nor Authorization: Bearer]
+```
-## Governance Questions
+### Key Rotation
-| Question | Why It Matters |
-|:---------|:---------------|
-| where are API keys stored and rotated? | prevents credential leakage |
-| which domains are allowed for crawl/search jobs? | controls data and compliance risk |
-| what release channel is approved for production clients? | avoids unplanned breaking changes |
+Firecrawl API keys are long-lived bearer tokens. Rotation practices:
+- Generate a new key in the Firecrawl dashboard before revoking the old one
+- Update all client configs simultaneously (or use a secrets manager to propagate automatically)
+- Verify the new key works in Inspector before updating production configs
+- Revoke the old key only after confirming zero active usage
-## Source References
+### Never Commit Keys
-- [README](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/README.md)
-- [Versioning](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/VERSIONING.md)
-- [Releases](https://github.com/firecrawl/firecrawl-mcp-server/releases)
+The `docker/entrypoint.sh` and `docker/nginx.conf` files demonstrate environment variable injection at the container level. Use the same pattern for any deployment:
-## Summary
+```yaml
+# docker-compose.yml pattern
+services:
+ firecrawl-mcp:
+ image: firecrawl-mcp:latest
+ environment:
+ - FIRECRAWL_API_KEY=${FIRECRAWL_API_KEY} # from .env or CI secret
+```
-You now have an end-to-end model for adopting and operating Firecrawl MCP Server with strong governance.
+## Safe Mode and Compliance
-Next: combine this with [MCP Chrome](../mcp-chrome-tutorial/) and [MCP Inspector](../mcp-inspector-tutorial/) for full browsing-data toolchains.
+When `CLOUD_SERVICE=true`, safe mode is automatically enabled. This restricts browser automation actions to a safe subset:
-## Source Code Walkthrough
+```typescript
+const safeActionTypes = ['wait', 'screenshot', 'scroll', 'scrape'] as const;
+const otherActions = ['click', 'write', 'press', 'executeJavascript', 'generatePDF'] as const;
+const allowedActionTypes = SAFE_MODE ? safeActionTypes : allActionTypes;
+```
-### `src/index.ts`
+Safe mode was designed for ChatGPT plugin compliance. Implications:
+- In hosted deployments, users cannot automate interactive browser actions (click, fill forms, execute JavaScript)
+- In local deployments (`CLOUD_SERVICE` not set), all action types are available
-The `asText` function in [`src/index.ts`](https://github.com/firecrawl/firecrawl-mcp-server/blob/HEAD/src/index.ts) handles a key part of this chapter's functionality:
+If your use case requires JavaScript execution or form filling, run the server locally without `CLOUD_SERVICE=true`.
-```ts
-}
+## Scraping Governance
+
+When deploying Firecrawl MCP as a shared team tool, define governance policies:
+
+| Policy Area | Questions to Answer |
+|:-----------|:--------------------|
+| Allowed domains | Which external domains can be scraped? Is competitor content allowed? |
+| Data retention | Does scraped content stay in LLM context only, or is it persisted? Set `zeroDataRetention: true` for sensitive requests |
+| Rate limits | Per-user or per-team credit budgets? Monitor via credit threshold env vars |
+| Robots.txt compliance | Firecrawl respects robots.txt by default — document any overrides |
+| Legal/copyright | Review terms of service for scraped content before using in products |
-function asText(data: unknown): string {
- return JSON.stringify(data, null, 2);
+### Zero Data Retention
+
+For sensitive scraping operations (internal documents, regulated content), use:
+
+```json
+{
+ "url": "https://internal.example.com/sensitive-doc",
+ "formats": ["markdown"],
+ "zeroDataRetention": true
}
+```
-// scrape tool (v2 semantics, minimal args)
-// Centralized scrape params (used by scrape, and referenced in search/crawl scrapeOptions)
+When `zeroDataRetention: true`, Firecrawl deletes the scraped content from its servers immediately after returning the response.
-// Define safe action types
-const safeActionTypes = ['wait', 'screenshot', 'scroll', 'scrape'] as const;
-const otherActions = [
- 'click',
- 'write',
- 'press',
- 'executeJavascript',
- 'generatePDF',
-] as const;
-const allActionTypes = [...safeActionTypes, ...otherActions] as const;
-
-// Use appropriate action types based on safe mode
-const allowedActionTypes = SAFE_MODE ? safeActionTypes : allActionTypes;
+## Docker Security
+
+The repo includes a `Dockerfile` and `Dockerfile.service` for containerized deployments. Security practices:
-function buildFormatsArray(
- args: Record<string, unknown>
-): Record<string, unknown>[] | undefined {
- const formats = args.formats as string[] | undefined;
- if (!formats || formats.length === 0) return undefined;
+```dockerfile
+# Recommended additions to the Docker build
+# Pin Node.js version for reproducibility
+FROM node:18.20-alpine
- const result: Record<string, unknown>[] = [];
- for (const fmt of formats) {
- if (fmt === 'json') {
+# Run as non-root user
+RUN addgroup -S firecrawl && adduser -S firecrawl -G firecrawl
+USER firecrawl
+
+# Read-only filesystem where possible
+# Secrets injected via environment, never COPY'd
```
-This function is important because it defines how Firecrawl MCP Server Tutorial: Web Scraping and Search Tools for MCP Clients implements the patterns covered in this chapter.
+The `docker/nginx.conf` provides a reverse proxy configuration for service deployments, including SSL termination and request buffering.
+## Versioning and Release Policy
-## How These Components Connect
+The `VERSIONING.md` documents the release cadence:
```mermaid
-flowchart TD
- A[asText]
+graph LR
+ MAIN[main branch\ncontinuous development]
+ MAIN --> BETA[npm tag: beta\ncanary releases for testing]
+ BETA --> STABLE[npm tag: latest\nstable releases]
+
+ STABLE --> PATCH[Patch: x.x.N\nbug fixes, no API changes]
+ STABLE --> MINOR[Minor: x.N.0\nnew tools, backward compatible]
+ STABLE --> MAJOR[Major: N.0.0\nbreaking tool changes]
```
+
+For production clients, pin to a minor version:
+```json
+{ "args": ["-y", "firecrawl-mcp@3"] }
+```
+
+Avoid unpinned `firecrawl-mcp` in production — `npx -y firecrawl-mcp` always fetches latest and may break on major version bumps.
+
+## Contribution Workflow
+
+The `firecrawl-mcp` server is maintained by the Mendable/Firecrawl team. Contributions follow a standard GitHub flow:
+
+```mermaid
+flowchart LR
+ FORK[Fork mendableai/firecrawl-mcp-server]
+ FORK --> BRANCH[Create feature branch]
+ BRANCH --> CODE[Implement change in src/index.ts]
+ CODE --> TEST[Run: npm test\nRun: npm run lint]
+ TEST --> PR[Open pull request\nagainst main branch]
+ PR --> REVIEW[Team review]
+ REVIEW --> MERGE[Merge + release]
+```
+
+### CI Checks
+
+The `.github/workflows/ci.yml` runs on every PR:
+```bash
+npm install
+npm run lint # ESLint on src/**/*.ts
+npm test # Jest test suite
+```
+
+Build before testing locally:
+```bash
+npm run build # tsc + chmod
+npm test
+```
+
+## Reporting Security Issues
+
+The project uses GitHub's security advisory feature. For vulnerabilities:
+1. Go to the repository's Security tab
+2. Click "Report a vulnerability"
+3. Do not disclose in public issues
+
+## Source References
+
+- [README](https://github.com/mendableai/firecrawl-mcp-server/blob/main/README.md)
+- [VERSIONING.md](https://github.com/mendableai/firecrawl-mcp-server/blob/main/VERSIONING.md)
+- [Dockerfile](https://github.com/mendableai/firecrawl-mcp-server/blob/main/Dockerfile)
+- [docker/nginx.conf](https://github.com/mendableai/firecrawl-mcp-server/blob/main/docker/nginx.conf)
+- [GitHub Releases](https://github.com/mendableai/firecrawl-mcp-server/releases)
+
+## Summary
+
+API key security requires environment injection (never git-committed), quarterly rotation, and secrets manager usage for shared deployments. Safe mode (enabled automatically in cloud service mode) restricts browser automation to a safe subset for compliance. For sensitive scraping, use `zeroDataRetention: true`. Pin the MCP server version in production configs to avoid unexpected breaking changes on major version bumps.
+
+Return to the [Firecrawl MCP Server Tutorial index](README.md).
diff --git a/tutorials/firecrawl-tutorial/README.md b/tutorials/firecrawl-tutorial/README.md
index 8ff0e684..a124296a 100644
--- a/tutorials/firecrawl-tutorial/README.md
+++ b/tutorials/firecrawl-tutorial/README.md
@@ -13,7 +13,7 @@ format_version: v2
[](https://github.com/mendableai/firecrawl)
-Firecrawl<sup>[View Repo](https://github.com/firecrawl/firecrawl)</sup> is a powerful web scraping and data extraction platform specifically designed for Large Language Models. It provides clean, structured data extraction from websites, making it easy to build RAG systems, content analysis tools, and AI-powered applications that need access to web content.
+Firecrawl<sup>[View Repo](https://github.com/mendableai/firecrawl)</sup> is a powerful web scraping and data extraction platform specifically designed for Large Language Models. It provides clean, structured data extraction from websites, making it easy to build RAG systems, content analysis tools, and AI-powered applications that need access to web content.
Firecrawl handles the complexity of web scraping - dealing with JavaScript rendering, anti-bot measures, and data cleaning - so you can focus on building amazing AI applications.
diff --git a/tutorials/fireproof-tutorial/01-getting-started.md b/tutorials/fireproof-tutorial/01-getting-started.md
index ec96a76d..6b75cf3c 100644
--- a/tutorials/fireproof-tutorial/01-getting-started.md
+++ b/tutorials/fireproof-tutorial/01-getting-started.md
@@ -51,184 +51,182 @@ You now have Fireproof running with a minimal document lifecycle.
Next: [Chapter 2: Core Document API and Query Lifecycle](02-core-document-api-and-query-lifecycle.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `cli/version-pinner.ts`
+### `cli/cmd-evento.ts`
-The `VersionPinner` class in [`cli/version-pinner.ts`](https://github.com/fireproof-storage/fireproof/blob/HEAD/cli/version-pinner.ts) handles a key part of this chapter's functionality:
+The `isCmdTSMsg` function in [`cli/cmd-evento.ts`](https://github.com/fireproof-storage/fireproof/blob/HEAD/cli/cmd-evento.ts) handles a key part of this chapter's functionality:
```ts
+});
+export type CmdTSMsg = typeof CmdTSMsg.infer;
+export function isCmdTSMsg(u: unknown): u is CmdTSMsg {
+ return !(CmdTSMsg(u) instanceof type.errors);
}
+export type WrapCmdTSMsg<T> = Omit<CmdTSMsg, "result"> & { result: T };
-export class VersionPinner {
- private allDeps: Record<string, string> = {};
+export const CmdProgress = type({
+ type: "'core-cli.progress'",
+ level: "'info'|'warn'|'error'",
+ message: "string",
+});
+export type CmdProgress = typeof CmdProgress.infer;
- private constructor(allDeps: Record<string, string>) {
- this.allDeps = allDeps;
- }
+export function isCmdProgress(u: unknown): u is CmdProgress {
+ return !(CmdProgress(u) instanceof type.errors);
+}
- /**
- * Helper function to pin dependencies
- */
- private pinDependencies(
- deps: Record<string, string> | undefined,
- workspaceVersion: string,
- _3rdPartyVersionModifier: "~" | "^" | "" | undefined,
- ): Record<string, string> {
- const pinnedDeps: Record<string, string> = {};
-
- if (!deps) {
- return pinnedDeps;
- }
-
- for (const [name, version] of Object.entries(deps)) {
- // Check if version is not pinned (starts with ^ or ~ or *)
- // Note: Also catch malformed versions like "1-beta" that should be resolved from lockfile
- if (version.startsWith("workspace:")) {
- // Replace workspace dependencies with the workspace version
- pinnedDeps[name] = workspaceVersion;
- } else {
- // Look up the exact version in lockfile
- if (this.allDeps[name]) {
+export async function sendMsg<Q, S>(
+ ctx: HandleTriggerCtx<WrapCmdTSMsg<unknown>, Q, S>,
+ result: S,
+): Promise<Result<EventoResultType>> {
+ await ctx.send.send(ctx, {
+ ...ctx.request,
+ result,
+ } satisfies WrapCmdTSMsg<S>);
+ return Result.Ok(EventoResult.Continue);
+}
+
+export async function sendProgress<Q, S>(
+ ctx: HandleTriggerCtx<WrapCmdTSMsg<unknown>, Q, S>,
+ level: CmdProgress["level"],
```
-This class is important because it defines how Fireproof Tutorial: Local-First Document Database for AI-Native Apps implements the patterns covered in this chapter.
+This function is important because it defines how Fireproof Tutorial: Local-First Document Database for AI-Native Apps implements the patterns covered in this chapter.
-### `cli/version-pinner.ts`
+### `cli/cmd-evento.ts`
-The `getPackageDependencies` function in [`cli/version-pinner.ts`](https://github.com/fireproof-storage/fireproof/blob/HEAD/cli/version-pinner.ts) handles a key part of this chapter's functionality:
+The `isCmdProgress` function in [`cli/cmd-evento.ts`](https://github.com/fireproof-storage/fireproof/blob/HEAD/cli/cmd-evento.ts) handles a key part of this chapter's functionality:
```ts
- * @returns Package dependencies information or null if not found
- */
-export async function getPackageDependencies(packageName: string, lockfilePath: string): Promise<PackageDependencies | null> {
- const projectDir = lockfilePath.replace(/\/[^/]+$/, "");
- const lockfile = await readWantedLockfile(projectDir, { ignoreIncompatible: false });
-
- if (!lockfile?.packages) {
- throw new Error(`No lockfile found at ${lockfilePath}`);
- }
+export type CmdProgress = typeof CmdProgress.infer;
- // Find the package in the lockfile
- // Key format examples:
- // - "/@adviser/cement@0.5.2"
- // - "/@adviser/cement@0.5.2(typescript@5.9.3)"
- for (const [key, pkgInfo] of Object.entries(lockfile.packages)) {
- const match = key.match(/^\/?(@?[^@]+)@(.+?)(?:\(|$)/);
- if (match) {
- const [, name, version] = match;
- if (name === packageName) {
- return {
- name,
- version,
- dependencies: pkgInfo.dependencies || {},
- peerDependencies: pkgInfo.peerDependencies || {},
- transitivePeerDependencies: pkgInfo.transitivePeerDependencies || [],
- };
- }
- }
- }
+export function isCmdProgress(u: unknown): u is CmdProgress {
+ return !(CmdProgress(u) instanceof type.errors);
+}
+
+export async function sendMsg<Q, S>(
+ ctx: HandleTriggerCtx<WrapCmdTSMsg<unknown>, Q, S>,
+ result: S,
+): Promise<Result<EventoResultType>> {
+ await ctx.send.send(ctx, {
+ ...ctx.request,
+ result,
+ } satisfies WrapCmdTSMsg<S>);
+ return Result.Ok(EventoResult.Continue);
+}
- return null;
+export async function sendProgress<Q, S>(
+ ctx: HandleTriggerCtx<WrapCmdTSMsg<unknown>, Q, S>,
+ level: CmdProgress["level"],
+ message: string,
+): Promise<void> {
+ await ctx.send.send(ctx, {
+ ...ctx.request,
+ result: {
+ type: "core-cli.progress",
+ level,
+ message,
+ } satisfies CmdProgress,
+ } satisfies WrapCmdTSMsg<CmdProgress>);
}
+
```
This function is important because it defines how Fireproof Tutorial: Local-First Document Database for AI-Native Apps implements the patterns covered in this chapter.
-### `cli/version-pinner.ts`
+### `cli/cmd-evento.ts`
-The `getAllTransitiveDependencies` function in [`cli/version-pinner.ts`](https://github.com/fireproof-storage/fireproof/blob/HEAD/cli/version-pinner.ts) handles a key part of this chapter's functionality:
+The `cmdTsEvento` function in [`cli/cmd-evento.ts`](https://github.com/fireproof-storage/fireproof/blob/HEAD/cli/cmd-evento.ts) handles a key part of this chapter's functionality:
```ts
- * @returns Map of package name to version
- */
-export async function getAllTransitiveDependencies(
- packageName: string,
- lockfilePath: string,
- depth = Infinity,
-): Promise<Map<string, string>> {
- const result = new Map<string, string>();
- const visited = new Set<string>();
-
- async function traverse(pkgName: string, currentDepth: number) {
- if (currentDepth > depth || visited.has(pkgName)) {
- return;
- }
- visited.add(pkgName);
-
- const pkgInfo = await getPackageDependencies(pkgName, lockfilePath);
- if (!pkgInfo) {
- return;
- }
-
- result.set(pkgName, pkgInfo.version);
-
- // Traverse dependencies
- for (const [depName] of Object.entries(pkgInfo.dependencies)) {
- await traverse(depName, currentDepth + 1);
- }
- }
-
- await traverse(packageName, 0);
- return result;
}
+
+export function cmdTsEvento() {
+ const evento = new Evento({
+ encode: (i) => {
+ if (isCmdTSMsg(i)) {
+ return Promise.resolve(Result.Ok(i.result));
+ }
+ return Promise.resolve(Result.Err("not a cmd-ts-msg"));
+ },
+ decode: (i) => Promise.resolve(Result.Ok(i)),
+ });
+ evento.push([
+ wellKnownEvento,
+ writeEnvEvento,
+ keyEvento,
+ preSignedUrlEvento,
+ retryEvento,
+ dependabotEvento,
+ updateDepsEvento,
+ setScriptsEvento,
+ setDependenciesEvento,
+ tscEvento,
+ testContainerBuildEvento,
+ testContainerTemplateEvento,
+ testContainerPublishEvento,
+ deviceIdCreateEvento,
+ deviceIdCsrEvento,
+ deviceIdExportEvento,
+ deviceIdCertEvento,
+ deviceIdCaCertEvento,
+ deviceIdRegisterEvento,
```
This function is important because it defines how Fireproof Tutorial: Local-First Document Database for AI-Native Apps implements the patterns covered in this chapter.
-### `cli/version-pinner.ts`
+### `cli/main.ts`
-The `traverse` function in [`cli/version-pinner.ts`](https://github.com/fireproof-storage/fireproof/blob/HEAD/cli/version-pinner.ts) handles a key part of this chapter's functionality:
+The `OutputSelector` class in [`cli/main.ts`](https://github.com/fireproof-storage/fireproof/blob/HEAD/cli/main.ts) handles a key part of this chapter's functionality:
```ts
- * @param packageName - Name of the package
- * @param lockfilePath - Path to the directory containing pnpm-lock.yaml
- * @param depth - Maximum depth to traverse (default: Infinity)
- * @returns Map of package name to version
- */
-export async function getAllTransitiveDependencies(
- packageName: string,
- lockfilePath: string,
- depth = Infinity,
-): Promise<Map<string, string>> {
- const result = new Map<string, string>();
- const visited = new Set<string>();
-
- async function traverse(pkgName: string, currentDepth: number) {
- if (currentDepth > depth || visited.has(pkgName)) {
- return;
- }
- visited.add(pkgName);
-
- const pkgInfo = await getPackageDependencies(pkgName, lockfilePath);
- if (!pkgInfo) {
- return;
- }
-
- result.set(pkgName, pkgInfo.version);
-
- // Traverse dependencies
- for (const [depName] of Object.entries(pkgInfo.dependencies)) {
- await traverse(depName, currentDepth + 1);
- }
+import { updateDepsCmd, isResUpdateDeps } from "./cmds/update-deps-cmd.js";
+
+class OutputSelector implements EventoSendProvider<unknown, unknown, unknown> {
+ readonly tstream = new TransformStream<unknown, WrapCmdTSMsg<unknown>>();
+ readonly outputStream: ReadableStream<WrapCmdTSMsg<unknown>> = this.tstream.readable;
+ readonly writer = this.tstream.writable.getWriter();
+ async send<IS, OS>(_trigger: HandleTriggerCtx<unknown, unknown, unknown>, data: IS): Promise<Result<OS, Error>> {
+ await this.writer.write(data);
+ return Promise.resolve(Result.Ok());
+ }
+ done(_trigger: HandleTriggerCtx<unknown, unknown, unknown>): Promise<Result<void>> {
+ this.writer.releaseLock();
+ this.tstream.writable.close();
+ return Promise.resolve(Result.Ok());
}
+}
+async function main() {
+ dotenv.config(process.env.FP_ENV ?? ".env");
+ const sthis = ensureSuperThis();
+
+ // tsc bypass: called directly before cmd-ts runs
+ if (process.argv[2] === "tsc") {
+ return handleTsc(process.argv.slice(3), sthis);
+ }
+
+ const ctx: CliCtx = {
+ sthis,
+ cliStream: createCliStream(),
+ };
+
+ const rs = await runSafely(
```
-This function is important because it defines how Fireproof Tutorial: Local-First Document Database for AI-Native Apps implements the patterns covered in this chapter.
+This class is important because it defines how Fireproof Tutorial: Local-First Document Database for AI-Native Apps implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[VersionPinner]
- B[getPackageDependencies]
- C[getAllTransitiveDependencies]
- D[traverse]
- E[PinVersionOptions]
+ A[isCmdTSMsg]
+ B[isCmdProgress]
+ C[cmdTsEvento]
+ D[OutputSelector]
+ E[main]
A --> B
B --> C
C --> D
diff --git a/tutorials/fireproof-tutorial/02-core-document-api-and-query-lifecycle.md b/tutorials/fireproof-tutorial/02-core-document-api-and-query-lifecycle.md
index 3519416e..591a1f71 100644
--- a/tutorials/fireproof-tutorial/02-core-document-api-and-query-lifecycle.md
+++ b/tutorials/fireproof-tutorial/02-core-document-api-and-query-lifecycle.md
@@ -42,184 +42,165 @@ You now understand the document lifecycle and read/query semantics.
Next: [Chapter 3: React Hooks and Live Local-First UX](03-react-hooks-and-live-local-first-ux.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `cli/update-deps-cmd.ts`
-
-The `updateDepsCmd` function in [`cli/update-deps-cmd.ts`](https://github.com/fireproof-storage/fireproof/blob/HEAD/cli/update-deps-cmd.ts) handles a key part of this chapter's functionality:
-
-```ts
+### `smoke/patch-fp-version.js`
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
-export function updateDepsCmd(sthis: SuperThis) {
- const cmd = command({
- name: "updateDeps",
- description: "Update all matching dependencies to a specified version across the monorepo",
- version: "1.0.0",
- args: {
- ver: option({
- type: string,
- long: "ver",
- short: "V",
- description: "The version to update to (e.g., 0.24.3 or 0.24.2-dev-clerk)",
- }),
- pkg: multioption({
- type: array(string),
- long: "pkg",
- short: "p",
- description: "Package name regex pattern to match (can be specified multiple times)",
- defaultValue: () => ["use-fireproof", "@fireproof/.*"],
- defaultValueIsSerializable: true,
- }),
- currentDir: option({
- type: string,
- long: "currentDir",
- short: "C",
- description: "Directory to search for package.json files",
- defaultValue: () => process.cwd(),
- defaultValueIsSerializable: true,
- }),
- dryRun: flag({
- long: "dry-run",
-```
-
-This function is important because it defines how Fireproof Tutorial: Local-First Document Database for AI-Native Apps implements the patterns covered in this chapter.
+The `main` function in [`smoke/patch-fp-version.js`](https://github.com/fireproof-storage/fireproof/blob/HEAD/smoke/patch-fp-version.js) handles a key part of this chapter's functionality:
-### `cli/update-deps-cmd.ts`
-
-The `PackageJson` interface in [`cli/update-deps-cmd.ts`](https://github.com/fireproof-storage/fireproof/blob/HEAD/cli/update-deps-cmd.ts) handles a key part of this chapter's functionality:
-
-```ts
-import { SuperThis } from "@fireproof/core-types-base";
-
-interface PackageJson {
- dependencies?: Record<string, string>;
- devDependencies?: Record<string, string>;
+```js
}
-// Find all package.json files recursively using zx glob (respects .gitignore)
-async function findPackageJsonFiles(dir: string): Promise<string[]> {
- const files = await glob([`${dir}/**/package.json`, `!${dir}/**/node_modules/**`], {
- gitignore: true,
- });
- return files;
+async function main() {
+ const args = process.argv.reverse();
+ const packageJsonName = args[1];
+ const version = args[0];
+ // eslint-disable-next-line no-undef, no-console
+ console.log(`Update Version in ${packageJsonName} to ${version}`);
+ const packageJson = JSON.parse(await fs.readFile(packageJsonName));
+ for (const i of ["devDependencies", "dependencies", "peerDependencies"]) {
+ patch(packageJson[i], version);
+ }
+ await fs.writeFile(packageJsonName, JSON.stringify(packageJson, null, 2));
}
-// Find packages matching the regex patterns in a package.json
-async function findMatchingPackages(packageJsonPath: string, patterns: string[]): Promise<string[]> {
- let pkg: PackageJson;
- try {
- const content = await readFile(packageJsonPath, "utf-8");
- pkg = JSON.parse(content) as PackageJson;
- } catch (e) {
- console.warn(`⚠️ Skipping unreadable/invalid JSON: ${packageJsonPath}`);
- return [];
- }
+main().catch((e) => {
+ // eslint-disable-next-line no-undef, no-console
+ console.error(e);
+ process.exit(1);
+});
- const allDeps = {
- ...(pkg.dependencies ?? {}),
- ...(pkg.devDependencies ?? {}),
- };
+```
+
+This function is important because it defines how Fireproof Tutorial: Local-First Document Database for AI-Native Apps implements the patterns covered in this chapter.
- const matchingPackages = new Set<string>();
+### `scripts/convert_uint8.py`
+
+The `file_to_js_uint8array` function in [`scripts/convert_uint8.py`](https://github.com/fireproof-storage/fireproof/blob/HEAD/scripts/convert_uint8.py) handles a key part of this chapter's functionality:
+
+```py
+import os
+
+def file_to_js_uint8array(input_file, output_file):
+ with open(input_file, 'rb') as f:
+ content = f.read()
+
+ uint8array = ', '.join(str(byte) for byte in content)
+
+ js_content = f"const fileContent = new Uint8Array([{uint8array}]);\n\n"
+ js_content += "// You can use this Uint8Array as needed in your JavaScript code\n"
+ js_content += "// For example, to create a Blob:\n"
+ js_content += "// const blob = new Blob([fileContent], { type: 'application/octet-stream' });\n"
+
+ with open(output_file, 'w') as f:
+ f.write(js_content)
+
+if __name__ == "__main__":
+ if len(sys.argv) != 2:
+ print("Usage: python script.py <input_file>")
+ sys.exit(1)
+
+ input_file = sys.argv[1]
+ output_file = os.path.splitext(input_file)[0] + '.js'
+
+ file_to_js_uint8array(input_file, output_file)
+ print(f"Converted {input_file} to {output_file}")
```
-This interface is important because it defines how Fireproof Tutorial: Local-First Document Database for AI-Native Apps implements the patterns covered in this chapter.
+This function is important because it defines how Fireproof Tutorial: Local-First Document Database for AI-Native Apps implements the patterns covered in this chapter.
-### `cli/device-id-cmd.ts`
+### `cli/create-cli-stream.ts`
-The `getStdin` function in [`cli/device-id-cmd.ts`](https://github.com/fireproof-storage/fireproof/blob/HEAD/cli/device-id-cmd.ts) handles a key part of this chapter's functionality:
+The `createCliStream` function in [`cli/create-cli-stream.ts`](https://github.com/fireproof-storage/fireproof/blob/HEAD/cli/create-cli-stream.ts) handles a key part of this chapter's functionality:
```ts
-import { sts } from "@fireproof/core-runtime";
-
-function getStdin(): Promise<string> {
- return new Promise<string>((resolve) => {
- let data = "";
- process.stdin.setEncoding("utf8");
- process.stdin.on("readable", () => {
- let chunk;
- while ((chunk = process.stdin.read()) !== null) {
- data += chunk;
- }
- });
- process.stdin.on("end", () => resolve(data));
- });
-}
+export type HandlerReturnType = never;
-// Reusable subject options for certificates and CSRs
-// Common Name is always required
-function subjectOptions() {
+export function createCliStream(): CliStream<HandlerArgsType, HandlerReturnType> {
+ const tstream = new TransformStream<WrapCmdTSMsg<unknown>>();
+ const writer = tstream.writable.getWriter();
+ const pending = new Set<Promise<void>>();
return {
- commonName: option({
- long: "common-name",
- short: "cn",
- description: "Common Name (required, e.g., 'My Device' or 'device-serial')",
- type: string,
- }),
- organization: option({
- long: "organization",
- short: "o",
- description: "Organization name",
- type: string,
- defaultValue: () => "You did not set the Organization",
+ stream: tstream.readable,
+ close: async () => {
+ await Promise.allSettled(pending);
+ writer.releaseLock();
+ await tstream.writable.close();
+ },
+ enqueue: ((wrappedFunc: (a: unknown) => unknown) => {
+ return (args: unknown) => {
+ const queued = Promise.resolve(wrappedFunc(args))
+ .then((result) => {
+ const cmdTsMsg = {
+ type: "msg.cmd-ts",
+ cmdTs: {
+ raw: args,
+ outputFormat: "text",
+ },
+ result,
+ } satisfies WrapCmdTSMsg<unknown>;
+ return writer.write(cmdTsMsg);
+ })
+ .then(() => undefined)
+ .finally(() => pending.delete(queued));
+ pending.add(queued);
+ return undefined;
+ };
```
This function is important because it defines how Fireproof Tutorial: Local-First Document Database for AI-Native Apps implements the patterns covered in this chapter.
-### `cli/device-id-cmd.ts`
+### `cli/create-cli-stream.ts`
-The `subjectOptions` function in [`cli/device-id-cmd.ts`](https://github.com/fireproof-storage/fireproof/blob/HEAD/cli/device-id-cmd.ts) handles a key part of this chapter's functionality:
+The `CliStream` interface in [`cli/create-cli-stream.ts`](https://github.com/fireproof-storage/fireproof/blob/HEAD/cli/create-cli-stream.ts) handles a key part of this chapter's functionality:
```ts
-// Reusable subject options for certificates and CSRs
-// Common Name is always required
-function subjectOptions() {
+export type EnqueueFn<Args extends readonly unknown[], Return, RealReturn = unknown> = (fn: (...a: Args) => RealReturn) => Return;
+
+export interface CliStream<Args extends readonly unknown[], Return, RealReturn = unknown> {
+ stream: ReadableStream<RealReturn>;
+ enqueue(fn: (...a: Args) => RealReturn): Return;
+ close(): Promise<void>;
+}
+
+export type HandlerArgsType = Parameters<Parameters<typeof command>[0]["handler"]>;
+export type HandlerReturnType = never;
+
+export function createCliStream(): CliStream<HandlerArgsType, HandlerReturnType> {
+ const tstream = new TransformStream<WrapCmdTSMsg<unknown>>();
+ const writer = tstream.writable.getWriter();
+ const pending = new Set<Promise<void>>();
return {
- commonName: option({
- long: "common-name",
- short: "cn",
- description: "Common Name (required, e.g., 'My Device' or 'device-serial')",
- type: string,
- }),
- organization: option({
- long: "organization",
- short: "o",
- description: "Organization name",
- type: string,
- defaultValue: () => "You did not set the Organization",
- }),
- locality: option({
- long: "locality",
- short: "l",
- description: "Locality/City",
- type: string,
- defaultValue: () => "You did not set the City",
- }),
- state: option({
- long: "state",
- short: "s",
- description: "State or Province",
- type: string,
- defaultValue: () => "You did not set the State",
- }),
- country: option({
+ stream: tstream.readable,
+ close: async () => {
+ await Promise.allSettled(pending);
+ writer.releaseLock();
+ await tstream.writable.close();
+ },
+ enqueue: ((wrappedFunc: (a: unknown) => unknown) => {
+ return (args: unknown) => {
+ const queued = Promise.resolve(wrappedFunc(args))
+ .then((result) => {
+ const cmdTsMsg = {
+ type: "msg.cmd-ts",
+ cmdTs: {
+ raw: args,
+ outputFormat: "text",
+ },
```
-This function is important because it defines how Fireproof Tutorial: Local-First Document Database for AI-Native Apps implements the patterns covered in this chapter.
+This interface is important because it defines how Fireproof Tutorial: Local-First Document Database for AI-Native Apps implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[updateDepsCmd]
- B[PackageJson]
- C[getStdin]
- D[subjectOptions]
- E[buildSubject]
+ A[main]
+ B[file_to_js_uint8array]
+ C[createCliStream]
+ D[CliStream]
+ E[exec]
A --> B
B --> C
C --> D
diff --git a/tutorials/fireproof-tutorial/03-react-hooks-and-live-local-first-ux.md b/tutorials/fireproof-tutorial/03-react-hooks-and-live-local-first-ux.md
index 3b3e84c2..8fe85a76 100644
--- a/tutorials/fireproof-tutorial/03-react-hooks-and-live-local-first-ux.md
+++ b/tutorials/fireproof-tutorial/03-react-hooks-and-live-local-first-ux.md
@@ -40,184 +40,182 @@ You now have the React mental model for real-time local-first Fireproof UIs.
Next: [Chapter 4: Ledger, CRDT, and Causal Consistency](04-ledger-crdt-and-causal-consistency.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `cli/well-known-cmd.ts`
+### `core/blockstore/attachable-store.ts`
-The `wellKnownCmd` function in [`cli/well-known-cmd.ts`](https://github.com/fireproof-storage/fireproof/blob/HEAD/cli/well-known-cmd.ts) handles a key part of this chapter's functionality:
+The `WALActiveStoreImpl` class in [`core/blockstore/attachable-store.ts`](https://github.com/fireproof-storage/fireproof/blob/HEAD/core/blockstore/attachable-store.ts) handles a key part of this chapter's functionality:
```ts
-import { exportSPKI } from "jose";
-
-export function wellKnownCmd(_sthis: SuperThis) {
- return command({
- name: "well-known",
- description: "Fetch well-known JWKS from URLs",
- version: "1.0.0",
- args: {
- json: flag({
- long: "json",
- description: "Output as JSON (default)",
- defaultValue: () => false,
- }),
- jsons: flag({
- long: "jsons",
- description: "Output as single-line quoted JSON string",
- defaultValue: () => false,
- }),
- pem: flag({
- long: "pem",
- description: "Output as PEM format per key",
- defaultValue: () => false,
- }),
- env: flag({
- long: "env",
- description: "Output as environment variables with single-lined PEM",
- defaultValue: () => false,
- }),
- presetKey: option({
- type: string,
- long: "presetKey",
- defaultValue: () => "",
+}
+
+class WALActiveStoreImpl extends WALActiveStore {
+ readonly ref: ActiveStore;
+ readonly active: WALStore;
+ protected readonly attached: WALAttachedStores;
+
+ constructor(ref: ActiveStore, active: WALStore, attached: WALAttachedStores) {
+ super();
+ this.ref = ref;
+ this.active = active;
+ this.attached = attached;
+ }
+
+ local(): WALStore {
+ return this.attached.local();
+ }
+ remotes(): WALStore[] {
+ return this.attached.remotes();
+ }
+}
+
+class WALAttachedStoresImpl implements WALAttachedStores {
+ readonly attached: AttachedStores;
+ constructor(attached: AttachedStores) {
+ this.attached = attached;
+ }
+ local(): WALStore {
+ return this.attached.local().active.wal;
+ }
+ remotes(): WALStore[] {
+ return (
```
-This function is important because it defines how Fireproof Tutorial: Local-First Document Database for AI-Native Apps implements the patterns covered in this chapter.
+This class is important because it defines how Fireproof Tutorial: Local-First Document Database for AI-Native Apps implements the patterns covered in this chapter.
-### `cli/dependabot-cmd.ts`
+### `core/blockstore/attachable-store.ts`
-The `fetchDependabotPRs` function in [`cli/dependabot-cmd.ts`](https://github.com/fireproof-storage/fireproof/blob/HEAD/cli/dependabot-cmd.ts) handles a key part of this chapter's functionality:
+The `WALAttachedStoresImpl` class in [`core/blockstore/attachable-store.ts`](https://github.com/fireproof-storage/fireproof/blob/HEAD/core/blockstore/attachable-store.ts) handles a key part of this chapter's functionality:
```ts
}
-async function fetchDependabotPRs(): Promise<PR[]> {
- try {
- const result = await $`gh pr list --author app/dependabot --json number,title,author,url,headRefName --limit 100`;
- const prs = JSON.parse(result.stdout) as PR[];
- return prs;
- } catch (error) {
- console.error("Failed to fetch Dependabot PRs:", error);
- throw error;
+class WALAttachedStoresImpl implements WALAttachedStores {
+ readonly attached: AttachedStores;
+ constructor(attached: AttachedStores) {
+ this.attached = attached;
+ }
+ local(): WALStore {
+ return this.attached.local().active.wal;
+ }
+ remotes(): WALStore[] {
+ return (
+ this.attached
+ .remotes()
+ .filter(({ active }) => active.wal)
+ // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+ .map(({ active }) => active.wal!)
+ );
}
}
-async function applyPR(pr: PR, rebase: boolean): Promise<void> {
- try {
- console.log(`\nProcessing PR #${pr.number}: ${pr.title}`);
-
- if (rebase) {
- // Rebase and merge the PR
- await $`gh pr merge ${pr.number} --auto --rebase`;
- console.log(`✓ Rebased and merged PR #${pr.number}`);
- } else {
- // Just checkout the PR
- await $`gh pr checkout ${pr.number}`;
- console.log(`✓ Checked out PR #${pr.number}`);
- }
- } catch (error) {
- console.error(`✗ Failed to process PR #${pr.number}:`, error);
- throw error;
+class ActiveStoreImpl<T extends DataAndMetaAndWalStore> implements ActiveStore {
+ readonly active: T;
+ readonly attached: AttachedRemotesImpl;
+
+ constructor(active: T, attached: AttachedRemotesImpl) {
+ this.active = active;
+ this.attached = attached;
}
-}
+ local(): LocalActiveStore {
+ return this.attached.local();
```
-This function is important because it defines how Fireproof Tutorial: Local-First Document Database for AI-Native Apps implements the patterns covered in this chapter.
+This class is important because it defines how Fireproof Tutorial: Local-First Document Database for AI-Native Apps implements the patterns covered in this chapter.
-### `cli/dependabot-cmd.ts`
+### `core/blockstore/attachable-store.ts`
-The `applyPR` function in [`cli/dependabot-cmd.ts`](https://github.com/fireproof-storage/fireproof/blob/HEAD/cli/dependabot-cmd.ts) handles a key part of this chapter's functionality:
+The `ActiveStoreImpl` class in [`core/blockstore/attachable-store.ts`](https://github.com/fireproof-storage/fireproof/blob/HEAD/core/blockstore/attachable-store.ts) handles a key part of this chapter's functionality:
```ts
}
-async function applyPR(pr: PR, rebase: boolean): Promise<void> {
- try {
- console.log(`\nProcessing PR #${pr.number}: ${pr.title}`);
-
- if (rebase) {
- // Rebase and merge the PR
- await $`gh pr merge ${pr.number} --auto --rebase`;
- console.log(`✓ Rebased and merged PR #${pr.number}`);
- } else {
- // Just checkout the PR
- await $`gh pr checkout ${pr.number}`;
- console.log(`✓ Checked out PR #${pr.number}`);
- }
- } catch (error) {
- console.error(`✗ Failed to process PR #${pr.number}:`, error);
- throw error;
+class FileActiveStoreImpl extends FileActiveStore {
+ readonly ref: ActiveStore;
+ readonly active: FileStore;
+ protected readonly attached: FileAttachedStores;
+
+ constructor(ref: ActiveStore, active: FileStore, attached: FileAttachedStores) {
+ super();
+ this.ref = ref;
+ this.active = active;
+ this.attached = attached;
+ }
+ local(): FileStore {
+ return this.attached.local();
+ }
+ remotes(): FileStore[] {
+ return this.attached.remotes();
}
}
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
-export function dependabotCmd(sthis: SuperThis) {
- const cmd = command({
- name: "dependabot",
- description: "Fetch and apply Dependabot PRs",
- version: "1.0.0",
- args: {
- rebase: flag({
- long: "rebase",
- short: "r",
- description: "Automatically rebase and merge the PRs",
+class CarActiveStoreImpl extends CarActiveStore {
+ readonly ref: ActiveStore;
+ readonly active: CarStore;
+ protected readonly attached: CarAttachedStores;
+
+ constructor(ref: ActiveStore, active: CarStore, attached: CarAttachedStores) {
+ super();
+ this.ref = ref;
+ this.active = active;
+ this.attached = attached;
+ }
```
-This function is important because it defines how Fireproof Tutorial: Local-First Document Database for AI-Native Apps implements the patterns covered in this chapter.
+This class is important because it defines how Fireproof Tutorial: Local-First Document Database for AI-Native Apps implements the patterns covered in this chapter.
-### `cli/dependabot-cmd.ts`
+### `core/blockstore/attachable-store.ts`
-The `dependabotCmd` function in [`cli/dependabot-cmd.ts`](https://github.com/fireproof-storage/fireproof/blob/HEAD/cli/dependabot-cmd.ts) handles a key part of this chapter's functionality:
+The `AttachedRemotesImpl` class in [`core/blockstore/attachable-store.ts`](https://github.com/fireproof-storage/fireproof/blob/HEAD/core/blockstore/attachable-store.ts) handles a key part of this chapter's functionality:
```ts
+class ActiveStoreImpl<T extends DataAndMetaAndWalStore> implements ActiveStore {
+ readonly active: T;
+ readonly attached: AttachedRemotesImpl;
+
+ constructor(active: T, attached: AttachedRemotesImpl) {
+ this.active = active;
+ this.attached = attached;
+ }
+
+ local(): LocalActiveStore {
+ return this.attached.local();
+ }
+ remotes(): ActiveStore[] {
+ return this.attached.remotes();
+ // return [
+ // this.attached.remotes().filter(i => i !== this.active)
+ // ]
+ }
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
-export function dependabotCmd(sthis: SuperThis) {
- const cmd = command({
- name: "dependabot",
- description: "Fetch and apply Dependabot PRs",
- version: "1.0.0",
- args: {
- rebase: flag({
- long: "rebase",
- short: "r",
- description: "Automatically rebase and merge the PRs",
- }),
- apply: flag({
- long: "apply",
- short: "a",
- description: "Apply (checkout) all Dependabot PRs",
- }),
- prNumber: option({
- long: "pr",
- short: "p",
- type: string,
- defaultValue: () => "",
- description: "Apply a specific PR number",
- }),
- list: flag({
- long: "list",
- short: "l",
- description: "List all Dependabot PRs (default action)",
- }),
- },
- handler: async (args) => {
+ baseStores(): BaseStore[] {
+ const bs: BaseStore[] = [this.active.car, this.active.file, this.active.meta];
+ if (this.active.wal) {
+ bs.push(this.active.wal);
+ }
+ return bs;
+ }
+ carStore(): CarActiveStore {
+ return new CarActiveStoreImpl(this, this.active.car, new CarAttachedStoresImpl(this.attached));
+ }
+ fileStore(): FileActiveStore {
+ return new FileActiveStoreImpl(this, this.active.file, new FileAttachedStoresImpl(this.attached));
+ }
```
-This function is important because it defines how Fireproof Tutorial: Local-First Document Database for AI-Native Apps implements the patterns covered in this chapter.
+This class is important because it defines how Fireproof Tutorial: Local-First Document Database for AI-Native Apps implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[wellKnownCmd]
- B[fetchDependabotPRs]
- C[applyPR]
- D[dependabotCmd]
- E[PR]
+ A[WALActiveStoreImpl]
+ B[WALAttachedStoresImpl]
+ C[ActiveStoreImpl]
+ D[AttachedRemotesImpl]
+ E[isLoadable]
A --> B
B --> C
C --> D
diff --git a/tutorials/fireproof-tutorial/04-ledger-crdt-and-causal-consistency.md b/tutorials/fireproof-tutorial/04-ledger-crdt-and-causal-consistency.md
index c9925658..330f99ed 100644
--- a/tutorials/fireproof-tutorial/04-ledger-crdt-and-causal-consistency.md
+++ b/tutorials/fireproof-tutorial/04-ledger-crdt-and-causal-consistency.md
@@ -35,164 +35,168 @@ You now understand the core consistency model behind Fireproof write and merge b
Next: [Chapter 5: Storage Gateways and Sync Topology](05-storage-gateways-and-sync-topology.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `cli/cloud-token-key-cmd.ts`
+### `core/runtime/utils.ts`
-The `ourToJWK` function in [`cli/cloud-token-key-cmd.ts`](https://github.com/fireproof-storage/fireproof/blob/HEAD/cli/cloud-token-key-cmd.ts) handles a key part of this chapter's functionality:
+The `pathOpsImpl` class in [`core/runtime/utils.ts`](https://github.com/fireproof-storage/fireproof/blob/HEAD/core/runtime/utils.ts) handles a key part of this chapter's functionality:
```ts
-import { z } from "zod/v4";
-
-async function ourToJWK(env: string, sthis: SuperThis): Promise<Result<{ keys: (JWKPublic | JWKPrivate)[] }>> {
- const rCryptoKeys = await exception2Result(() => rt.sts.env2jwk(env, undefined, sthis));
- if (rCryptoKeys.isErr()) {
- return Result.Err(rCryptoKeys);
+// presetEnv: presetEnv(),
+// });
+class pathOpsImpl implements PathOps {
+ join(...paths: string[]): string {
+ return paths.map((i) => i.replace(/\/+$/, "")).join("/");
}
- const cryptoKeys = rCryptoKeys.Ok();
-
- // Convert each key individually for better error reporting
- const keys: (JWKPrivate | JWKPublic)[] = [];
- for (const key of cryptoKeys) {
- const rKey = await exception2Result(() => exportJWK(key));
- if (rKey.isErr()) {
- return Result.Err(rKey);
- }
- const parsed = z.union([JWKPublicSchema, JWKPrivateSchema]).safeParse(rKey.Ok());
- if (!parsed.success) {
- return Result.Err(`Invalid JWK public key: ${parsed.error.message}`);
- }
- keys.push(parsed.data);
+ dirname(path: string) {
+ return path.split("/").slice(0, -1).join("/");
}
-
- return Result.Ok({ keys });
+ basename(path: string): string {
+ return path.split("/").pop() || "";
+ }
+ // homedir() {
+ // throw new Error("SysContainer:homedir is not available in seeded state");
+ // }
}
-
-export function keyCmd(sthis: SuperThis) {
- return command({
- name: "cli-key-cmds",
- description: "handle keys for cloud token generation",
- version: "1.0.0",
- args: {
+const pathOps = new pathOpsImpl();
+const txtOps = ((txtEncoder, txtDecoder) => ({
+ id: () => "fp-txtOps",
+ encode: (input: string) => txtEncoder.encode(input),
+ decode: (input: ToUInt8) => txtDecoder.decode(coerceIntoUint8(input).Ok()),
+
+ base64: {
+ encode: (input: ToUInt8 | string) => {
+ if (typeof input === "string") {
+ const data = txtEncoder.encode(input);
+ return btoa(String.fromCharCode(...data));
+ }
+ let charStr = "";
+ for (const i of coerceIntoUint8(input).Ok()) {
+ charStr += String.fromCharCode(i);
+ }
```
-This function is important because it defines how Fireproof Tutorial: Local-First Document Database for AI-Native Apps implements the patterns covered in this chapter.
+This class is important because it defines how Fireproof Tutorial: Local-First Document Database for AI-Native Apps implements the patterns covered in this chapter.
-### `cli/cloud-token-key-cmd.ts`
+### `core/runtime/utils.ts`
-The `keyCmd` function in [`cli/cloud-token-key-cmd.ts`](https://github.com/fireproof-storage/fireproof/blob/HEAD/cli/cloud-token-key-cmd.ts) handles a key part of this chapter's functionality:
+The `Hasher` class in [`core/runtime/utils.ts`](https://github.com/fireproof-storage/fireproof/blob/HEAD/core/runtime/utils.ts) handles a key part of this chapter's functionality:
```ts
}
-export function keyCmd(sthis: SuperThis) {
- return command({
- name: "cli-key-cmds",
- description: "handle keys for cloud token generation",
- version: "1.0.0",
- args: {
- generatePair: flag({
- long: "generatePair",
- short: "g",
- }),
- ourToJWK: option({
- long: "ourToJWK",
- short: "o",
- defaultValue: () => "",
- type: string,
- }),
- JWKToour: option({
- long: "JWKToour",
- short: "j",
- defaultValue: () => "",
- type: string,
- }),
- },
- handler: async (args) => {
- switch (true) {
- case !!args.ourToJWK:
- {
- const r = await ourToJWK(args.ourToJWK, sthis);
- if (r.isErr()) {
- // eslint-disable-next-line no-console
+type HasherInput = Uint8Array | string | number | boolean;
+
+class Hasher {
+ private readonly hasher: XXH64;
+ private readonly ende: typeof txtOps;
+ constructor(ende?: typeof txtOps) {
+ this.hasher = XXH.h64();
+ this.ende = ende || txtOps;
+ }
+ update(x: HasherInput): Hasher {
+ switch (true) {
+ case x instanceof Uint8Array:
+ this.hasher.update(x);
+ break;
+ case typeof x === "string":
+ this.hasher.update(this.ende.encode(x));
+ break;
+ case typeof x === "number":
+ this.hasher.update(this.ende.encode(x.toString()));
+ break;
+ case typeof x === "boolean":
+ this.hasher.update(this.ende.encode(x ? "true" : "false"));
+ break;
+ default:
+ throw new Error(`unsupported type ${typeof x}`);
+ }
+ return this;
+ }
+ digest(x?: HasherInput): string {
+ if (!(x === undefined || x === null)) {
```
-This function is important because it defines how Fireproof Tutorial: Local-First Document Database for AI-Native Apps implements the patterns covered in this chapter.
+This class is important because it defines how Fireproof Tutorial: Local-First Document Database for AI-Native Apps implements the patterns covered in this chapter.
-### `cli/run.js`
+### `core/runtime/utils.ts`
-The `exec` function in [`cli/run.js`](https://github.com/fireproof-storage/fireproof/blob/HEAD/cli/run.js) handles a key part of this chapter's functionality:
+The `globalLogger` function in [`core/runtime/utils.ts`](https://github.com/fireproof-storage/fireproof/blob/HEAD/core/runtime/utils.ts) handles a key part of this chapter's functionality:
-```js
-import * as process from "process";
+```ts
+//export { Result };
-function exec(cmd, args) {
- // process.env.PATH = `${[
- // `${runDirectory}`,
- // path.join(runDirectory, "./node_modules/.bin")
- // ].join(":")}:${process.env.PATH}`
- const tsc = spawn(cmd, args, {
- stdio: "inherit", // inherits stdin, stdout, and stderr
- });
+const _globalLogger = new ResolveOnce();
+function globalLogger(): Logger {
+ return _globalLogger.once(() => new LoggerImpl());
+}
- tsc.on("close", (code) => {
- process.exit(code);
- });
+const registerFP_DEBUG = new ResolveOnce();
- tsc.on("error", (error) => {
- // eslint-disable-next-line no-console, no-undef
- console.error(`Failed to start ${cmd}: ${error.message}`);
- process.exit(1);
- });
+interface superThisOpts {
+ readonly logger: Logger;
+ readonly env: Env;
+ readonly pathOps: PathOps;
+ readonly crypto: CryptoRuntime;
+ readonly ctx: AppContext;
+ readonly txt: TextEndeCoder;
}
-// const idxTsc = process.argv.findIndex(i => i === 'tsc')
-const idxRunIdx = process.argv.findIndex((i) => i.endsWith("run.js"));
-const runDirectory = path.dirname(process.argv[idxRunIdx]);
-const mainJs = path.join(runDirectory, "main.js");
-//const mainWithDistJs = path.join(runDirectory, "dist", "npm", "main.js");
-//const mainJs = fs.existsSync(mainPublishedJs) ? mainPublishedJs : fs.existsSync(mainWithDistJs) ? mainWithDistJs : undefined;
-if (fs.existsSync(mainJs)) {
- // make windows happy file://
- const addFile = `file://${mainJs}`;
- // eslint-disable-next-line no-console, no-undef
+class SuperThisImpl implements SuperThis {
+ readonly logger: Logger;
+ readonly env: Env;
+ readonly pathOps: PathOps;
+ readonly ctx: AppContext;
+ readonly txt: TextEndeCoder;
+ readonly crypto: CryptoRuntime;
+
+ constructor(opts: superThisOpts) {
+ this.logger = opts.logger;
+ this.env = opts.env;
+ this.crypto = opts.crypto;
+ this.pathOps = opts.pathOps;
+ this.txt = opts.txt;
```
This function is important because it defines how Fireproof Tutorial: Local-First Document Database for AI-Native Apps implements the patterns covered in this chapter.
-### `scripts/convert_uint8.py`
-
-The `file_to_js_uint8array` function in [`scripts/convert_uint8.py`](https://github.com/fireproof-storage/fireproof/blob/HEAD/scripts/convert_uint8.py) handles a key part of this chapter's functionality:
-
-```py
-import os
-
-def file_to_js_uint8array(input_file, output_file):
- with open(input_file, 'rb') as f:
- content = f.read()
-
- uint8array = ', '.join(str(byte) for byte in content)
-
- js_content = f"const fileContent = new Uint8Array([{uint8array}]);\n\n"
- js_content += "// You can use this Uint8Array as needed in your JavaScript code\n"
- js_content += "// For example, to create a Blob:\n"
- js_content += "// const blob = new Blob([fileContent], { type: 'application/octet-stream' });\n"
-
- with open(output_file, 'w') as f:
- f.write(js_content)
-
-if __name__ == "__main__":
- if len(sys.argv) != 2:
- print("Usage: python script.py <input_file>")
- sys.exit(1)
-
- input_file = sys.argv[1]
- output_file = os.path.splitext(input_file)[0] + '.js'
-
- file_to_js_uint8array(input_file, output_file)
- print(f"Converted {input_file} to {output_file}")
+### `core/runtime/utils.ts`
+
+The `presetEnv` function in [`core/runtime/utils.ts`](https://github.com/fireproof-storage/fireproof/blob/HEAD/core/runtime/utils.ts) handles a key part of this chapter's functionality:
+
+```ts
+
+// const pathOps =
+function presetEnv(ipreset?: Map<string, string> | Record<string, string>): Map<string, string> {
+ let preset: Record<string, string> = {};
+ if (ipreset instanceof Map) {
+ preset = Object.fromEntries<string>(ipreset.entries());
+ } else if (typeof ipreset === "object" && ipreset !== null) {
+ preset = ipreset;
+ }
+ const penv = new Map([
+ // ["FP_DEBUG", "xxx"],
+ // ["FP_ENV", "development"],
+ ...Array.from(
+ Object.entries({
+ ...setPresetEnv({}),
+ ...preset,
+ }),
+ ), // .map(([k, v]) => [k, v as string])
+ ]);
+ // console.log(">>>>>>", penv)
+ return penv;
+}
+// const envImpl = envFactory({
+// symbol: "FP_ENV",
+// presetEnv: presetEnv(),
+// });
+class pathOpsImpl implements PathOps {
+ join(...paths: string[]): string {
+ return paths.map((i) => i.replace(/\/+$/, "")).join("/");
+ }
+ dirname(path: string) {
+ return path.split("/").slice(0, -1).join("/");
```
This function is important because it defines how Fireproof Tutorial: Local-First Document Database for AI-Native Apps implements the patterns covered in this chapter.
@@ -202,11 +206,11 @@ This function is important because it defines how Fireproof Tutorial: Local-Firs
```mermaid
flowchart TD
- A[ourToJWK]
- B[keyCmd]
- C[exec]
- D[file_to_js_uint8array]
- E[isPowerShell]
+ A[pathOpsImpl]
+ B[Hasher]
+ C[globalLogger]
+ D[presetEnv]
+ E[onSuperThis]
A --> B
B --> C
C --> D
diff --git a/tutorials/fireproof-tutorial/05-storage-gateways-and-sync-topology.md b/tutorials/fireproof-tutorial/05-storage-gateways-and-sync-topology.md
index 7eecf883..89f86d6f 100644
--- a/tutorials/fireproof-tutorial/05-storage-gateways-and-sync-topology.md
+++ b/tutorials/fireproof-tutorial/05-storage-gateways-and-sync-topology.md
@@ -39,157 +39,182 @@ You now have a storage and sync topology model for different deployment targets.
Next: [Chapter 6: Files, Attachments, and Rich Data Flows](06-files-attachments-and-rich-data-flows.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `smoke/get-fp-version.js`
-
-The `getVersion` function in [`smoke/get-fp-version.js`](https://github.com/fireproof-storage/fireproof/blob/HEAD/smoke/get-fp-version.js) handles a key part of this chapter's functionality:
-
-```js
-import * as process from "node:process";
-
-function getVersion(version = "refs/tags/v0.0.0-smoke") {
- if (process.env.GITHUB_REF && process.env.GITHUB_REF.startsWith("refs/tags/v")) {
- version = process.env.GITHUB_REF;
- }
- return version.split("/").slice(-1)[0].replace(/^v/, "");
-}
-
-async function main() {
- const gitHead = (await $`git rev-parse --short HEAD`).stdout.trim();
- const dateTick = (await $`date +%s`).stdout.trim();
- // eslint-disable-next-line no-console, no-undef
- console.log(getVersion(`refs/tags/v0.0.0-smoke-${gitHead}-${dateTick}`));
-}
+### `core/runtime/utils.ts`
-main().catch((e) => {
- // eslint-disable-next-line no-console, no-undef
- console.error(e);
- process.exit(1);
-});
+The `coerceIntoUint8` function in [`core/runtime/utils.ts`](https://github.com/fireproof-storage/fireproof/blob/HEAD/core/runtime/utils.ts) handles a key part of this chapter's functionality:
+```ts
+ id: () => "fp-txtOps",
+ encode: (input: string) => txtEncoder.encode(input),
+ decode: (input: ToUInt8) => txtDecoder.decode(coerceIntoUint8(input).Ok()),
+
+ base64: {
+ encode: (input: ToUInt8 | string) => {
+ if (typeof input === "string") {
+ const data = txtEncoder.encode(input);
+ return btoa(String.fromCharCode(...data));
+ }
+ let charStr = "";
+ for (const i of coerceIntoUint8(input).Ok()) {
+ charStr += String.fromCharCode(i);
+ }
+ return btoa(charStr);
+ },
+ decodeUint8: (input: string) => {
+ const data = atob(input.replace(/\s+/g, ""));
+ return new Uint8Array(data.split("").map((c) => c.charCodeAt(0)));
+ },
+ decode: (input: string) => {
+ const data = atob(input.replace(/\s+/g, ""));
+ const uint8 = new Uint8Array(data.split("").map((c) => c.charCodeAt(0)));
+ return txtDecoder.decode(uint8);
+ },
+ },
+ base58: {
+ encode: (input: ToUInt8 | string) => {
+ if (typeof input === "string") {
+ const data = txtEncoder.encode(input);
+ return base58btc.encode(data);
+ }
```
This function is important because it defines how Fireproof Tutorial: Local-First Document Database for AI-Native Apps implements the patterns covered in this chapter.
-### `smoke/get-fp-version.js`
+### `core/runtime/utils.ts`
-The `main` function in [`smoke/get-fp-version.js`](https://github.com/fireproof-storage/fireproof/blob/HEAD/smoke/get-fp-version.js) handles a key part of this chapter's functionality:
+The `coercePromiseIntoUint8` function in [`core/runtime/utils.ts`](https://github.com/fireproof-storage/fireproof/blob/HEAD/core/runtime/utils.ts) handles a key part of this chapter's functionality:
-```js
+```ts
}
-async function main() {
- const gitHead = (await $`git rev-parse --short HEAD`).stdout.trim();
- const dateTick = (await $`date +%s`).stdout.trim();
- // eslint-disable-next-line no-console, no-undef
- console.log(getVersion(`refs/tags/v0.0.0-smoke-${gitHead}-${dateTick}`));
+export async function coercePromiseIntoUint8(raw: PromiseToUInt8): Promise<Result<Uint8Array>> {
+ if (raw instanceof Uint8Array) {
+ return Result.Ok(raw);
+ }
+ if (Result.Is(raw)) {
+ return raw;
+ }
+ if (typeof raw.then === "function") {
+ try {
+ return coercePromiseIntoUint8(await raw);
+ } catch (e) {
+ return Result.Err(e as Error);
+ }
+ }
+ return Result.Err("Not a Uint8Array");
}
-main().catch((e) => {
- // eslint-disable-next-line no-console, no-undef
- console.error(e);
- process.exit(1);
-});
-
+export function makeName(fnString: string) {
+ const regex = /\(([^,()]+,\s*[^,()]+|\[[^\]]+\],\s*[^,()]+)\)/g;
+ let found: RegExpExecArray | null = null;
+ const matches = Array.from(fnString.matchAll(regex), (match) => match[1].trim());
+ if (matches.length === 0) {
+ found = /=>\s*{?\s*([^{}]+)\s*}?/.exec(fnString);
+ if (found && found[1].includes("return")) {
+ found = null;
+ }
+ }
+ if (!found) {
+ return fnString;
+ } else {
```
This function is important because it defines how Fireproof Tutorial: Local-First Document Database for AI-Native Apps implements the patterns covered in this chapter.
-### `core/blockstore/loader.ts`
+### `core/runtime/utils.ts`
-The `CommitAction` class in [`core/blockstore/loader.ts`](https://github.com/fireproof-storage/fireproof/blob/HEAD/core/blockstore/loader.ts) handles a key part of this chapter's functionality:
+The `makeName` function in [`core/runtime/utils.ts`](https://github.com/fireproof-storage/fireproof/blob/HEAD/core/runtime/utils.ts) handles a key part of this chapter's functionality:
```ts
-// }
-
-class CommitAction implements CommitParams {
- readonly carLog: CarLog;
- readonly encoder: AsyncBlockEncoder<24, Uint8Array>;
- readonly threshold: number;
- readonly attached: AttachedStores;
- readonly opts: CommitOpts;
- readonly commitQueue: CommitQueueIf<CarGroup>;
- readonly logger: Logger;
-
- constructor(
- logger: Logger,
- carLog: CarLog,
- commitQueue: CommitQueueIf<CarGroup>,
- encoder: AsyncBlockEncoder<24, Uint8Array>,
- attached: AttachedStores,
- threshold: number,
- opts: CommitOpts,
- ) {
- this.logger = logger;
- this.carLog = carLog;
- this.commitQueue = commitQueue;
- this.attached = attached;
- // this.carLog = carLog;
- this.encoder = encoder;
- this.threshold = threshold;
- this.opts = opts;
+}
+
+export function makeName(fnString: string) {
+ const regex = /\(([^,()]+,\s*[^,()]+|\[[^\]]+\],\s*[^,()]+)\)/g;
+ let found: RegExpExecArray | null = null;
+ const matches = Array.from(fnString.matchAll(regex), (match) => match[1].trim());
+ if (matches.length === 0) {
+ found = /=>\s*{?\s*([^{}]+)\s*}?/.exec(fnString);
+ if (found && found[1].includes("return")) {
+ found = null;
+ }
+ }
+ if (!found) {
+ return fnString;
+ } else {
+ // it's a consise arrow function, match everything after the arrow
+ return found[1];
}
+}
- async writeCar(block: AnyBlock): Promise<void> {
- await this.attached.local().active.car.save(block);
+export function storeType2DataMetaWal(store: StoreType) {
+ switch (store) {
+ case "car":
+ case "file":
+ return "data";
+ case "meta":
+ case "wal":
+ return store;
+ default:
+ throw new Error(`unknown store ${store}`);
+ }
+}
```
-This class is important because it defines how Fireproof Tutorial: Local-First Document Database for AI-Native Apps implements the patterns covered in this chapter.
+This function is important because it defines how Fireproof Tutorial: Local-First Document Database for AI-Native Apps implements the patterns covered in this chapter.
-### `core/blockstore/loader.ts`
+### `core/runtime/utils.ts`
-The `Loader` class in [`core/blockstore/loader.ts`](https://github.com/fireproof-storage/fireproof/blob/HEAD/core/blockstore/loader.ts) handles a key part of this chapter's functionality:
+The `storeType2DataMetaWal` function in [`core/runtime/utils.ts`](https://github.com/fireproof-storage/fireproof/blob/HEAD/core/runtime/utils.ts) handles a key part of this chapter's functionality:
```ts
-// await params.metaStore.save(newDbMeta);
-
-export class Loader implements Loadable {
- // readonly name: string;
- readonly blockstoreParent?: BlockFetcher;
- readonly ebOpts: BlockstoreRuntime;
- readonly logger: Logger;
- readonly commitQueue: CommitQueueIf<CarGroup>;
- isCompacting = false;
- readonly cidCache: KeyedResolvOnce<FPBlock>;
- private readonly maxConcurrentCarReader: ReturnType<typeof pLimit>;
- private readonly maxConcurrentWrite = pLimit(1);
- readonly seenCompacted: LRUSet<string>;
- // readonly processedCars: Set<string> = new Set<string>();
- readonly sthis: SuperThis;
- readonly taskManager: TaskManager;
-
- readonly carLog: CarLog = new CarLog();
- // key?: string;
- // keyId?: string;
- // remoteMetaStore?: MetaStore;
- // remoteCarStore?: DataStore;
- // remoteFileStore?: DataStore;
-
- readonly attachedStores: AttachedStores;
-
- async tryToLoadStaleCars(store: ActiveStore) {
- const staleLoadcars: Promise<FPBlock<CarBlockItem>>[] = [];
- for (const { value: rvalue } of this.cidCache.values()) {
- if (rvalue.isErr()) {
- this.logger.Error().Err(rvalue).Msg("error loading car");
- return;
+}
+
+export function storeType2DataMetaWal(store: StoreType) {
+ switch (store) {
+ case "car":
+ case "file":
+ return "data";
+ case "meta":
+ case "wal":
+ return store;
+ default:
+ throw new Error(`unknown store ${store}`);
+ }
+}
+
+export function ensureURIDefaults(
+ sthis: SuperThis,
+ names: { name: string; localURI?: URI },
+ curi: CoerceURI | undefined,
+ uri: URI,
+ store: StoreType,
+ ctx?: Partial<{
+ readonly idx: boolean;
+ readonly file: boolean;
+ }>,
+): URI {
+ ctx = ctx || {};
+ const ret = (curi ? URI.from(curi) : uri).build().setParam(PARAM.STORE, store).defParam(PARAM.NAME, names.name);
+ if (names.localURI) {
+ const rParams = names.localURI.getParamsResult({
+ [PARAM.NAME]: param.OPTIONAL,
+ [PARAM.STORE_KEY]: param.OPTIONAL,
```
-This class is important because it defines how Fireproof Tutorial: Local-First Document Database for AI-Native Apps implements the patterns covered in this chapter.
+This function is important because it defines how Fireproof Tutorial: Local-First Document Database for AI-Native Apps implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[getVersion]
- B[main]
- C[CommitAction]
- D[Loader]
- E[carLogIncludesGroup]
+ A[coerceIntoUint8]
+ B[coercePromiseIntoUint8]
+ C[makeName]
+ D[storeType2DataMetaWal]
+ E[ensureURIDefaults]
A --> B
B --> C
C --> D
diff --git a/tutorials/fireproof-tutorial/06-files-attachments-and-rich-data-flows.md b/tutorials/fireproof-tutorial/06-files-attachments-and-rich-data-flows.md
index c038af50..5ef52406 100644
--- a/tutorials/fireproof-tutorial/06-files-attachments-and-rich-data-flows.md
+++ b/tutorials/fireproof-tutorial/06-files-attachments-and-rich-data-flows.md
@@ -36,104 +36,54 @@ You now understand how to model and render rich media payloads in Fireproof docu
Next: [Chapter 7: Runtime Coverage: Browser, Node, Deno, and Edge](07-runtime-coverage-browser-node-deno-and-edge.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `core/runtime/utils.ts`
-The `pathOpsImpl` class in [`core/runtime/utils.ts`](https://github.com/fireproof-storage/fireproof/blob/HEAD/core/runtime/utils.ts) handles a key part of this chapter's functionality:
+The `mimeBlockParser` function in [`core/runtime/utils.ts`](https://github.com/fireproof-storage/fireproof/blob/HEAD/core/runtime/utils.ts) handles a key part of this chapter's functionality:
```ts
-// presetEnv: presetEnv(),
-// });
-class pathOpsImpl implements PathOps {
- join(...paths: string[]): string {
- return paths.map((i) => i.replace(/\/+$/, "")).join("/");
- }
- dirname(path: string) {
- return path.split("/").slice(0, -1).join("/");
- }
- basename(path: string): string {
- return path.split("/").pop() || "";
- }
- // homedir() {
- // throw new Error("SysContainer:homedir is not available in seeded state");
- // }
}
-const pathOps = new pathOpsImpl();
-const txtOps = ((txtEncoder, txtDecoder) => ({
- id: () => "fp-txtOps",
- encode: (input: string) => txtEncoder.encode(input),
- decode: (input: ToUInt8) => txtDecoder.decode(coerceIntoUint8(input).Ok()),
-
- base64: {
- encode: (input: ToUInt8 | string) => {
- if (typeof input === "string") {
- const data = txtEncoder.encode(input);
- return btoa(String.fromCharCode(...data));
- }
- let charStr = "";
- for (const i of coerceIntoUint8(input).Ok()) {
- charStr += String.fromCharCode(i);
- }
-```
-This class is important because it defines how Fireproof Tutorial: Local-First Document Database for AI-Native Apps implements the patterns covered in this chapter.
+export function mimeBlockParser(mime: string): MimeBlock[] {
+ const blocks: MimeBlock[] = [];
+ const lines = mime.split("\n");
-### `core/runtime/utils.ts`
+ let i = 0;
+ let lastProcessedIndex = -1; // Track the last line we've added to a block
-The `Hasher` class in [`core/runtime/utils.ts`](https://github.com/fireproof-storage/fireproof/blob/HEAD/core/runtime/utils.ts) handles a key part of this chapter's functionality:
+ while (i < lines.length) {
+ const line = lines[i];
-```ts
-}
+ // Check if this line starts a PEM-style block
+ // Minimum 3 dashes, allow optional whitespace before/after dashes and case-insensitive BEGIN/END
+ const beginMatch = line.match(/^(-{3,})\s*(BEGIN)\s+(.+?)\s*(-{3,})$/i);
-type HasherInput = Uint8Array | string | number | boolean;
+ if (beginMatch) {
+ // Found a BEGIN marker
+ const leadingDashes = beginMatch[1].length;
+ const trailingDashes = beginMatch[4].length;
+ const blockType = beginMatch[3];
-class Hasher {
- private readonly hasher: XXH64;
- private readonly ende: typeof txtOps;
- constructor(ende?: typeof txtOps) {
- this.hasher = XXH.h64();
- this.ende = ende || txtOps;
- }
- update(x: HasherInput): Hasher {
- switch (true) {
- case x instanceof Uint8Array:
- this.hasher.update(x);
- break;
- case typeof x === "string":
- this.hasher.update(this.ende.encode(x));
- break;
- case typeof x === "number":
- this.hasher.update(this.ende.encode(x.toString()));
- break;
- case typeof x === "boolean":
- this.hasher.update(this.ende.encode(x ? "true" : "false"));
- break;
- default:
- throw new Error(`unsupported type ${typeof x}`);
- }
- return this;
- }
- digest(x?: HasherInput): string {
- if (!(x === undefined || x === null)) {
+ // Create a regex pattern for the matching END marker (case-insensitive)
+ // Escape special regex characters in blockType
+ const escapedBlockType = blockType.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+ // END marker must have the same number of leading and trailing dashes as BEGIN
+ const endPattern = new RegExp(`^-{${leadingDashes}}\\s*(END)\\s+${escapedBlockType}\\s*-{${trailingDashes}}$`, "i");
+
+ // Collect preBegin content (everything between lastProcessedIndex and current BEGIN)
+ const preBegin: string[] = [];
+ for (let j = lastProcessedIndex + 1; j < i; j++) {
+ preBegin.push(lines[j]);
```
-This class is important because it defines how Fireproof Tutorial: Local-First Document Database for AI-Native Apps implements the patterns covered in this chapter.
+This function is important because it defines how Fireproof Tutorial: Local-First Document Database for AI-Native Apps implements the patterns covered in this chapter.
### `core/runtime/utils.ts`
-The `globalLogger` function in [`core/runtime/utils.ts`](https://github.com/fireproof-storage/fireproof/blob/HEAD/core/runtime/utils.ts) handles a key part of this chapter's functionality:
+The `superThisOpts` interface in [`core/runtime/utils.ts`](https://github.com/fireproof-storage/fireproof/blob/HEAD/core/runtime/utils.ts) handles a key part of this chapter's functionality:
```ts
-//export { Result };
-
-const _globalLogger = new ResolveOnce();
-function globalLogger(): Logger {
- return _globalLogger.once(() => new LoggerImpl());
-}
-
const registerFP_DEBUG = new ResolveOnce();
interface superThisOpts {
@@ -159,61 +109,109 @@ class SuperThisImpl implements SuperThis {
this.crypto = opts.crypto;
this.pathOps = opts.pathOps;
this.txt = opts.txt;
+ this.ctx = opts.ctx;
+ // console.log("superThis", this);
+ }
+
+ nextId(bytes = 6): { str: string; bin: Uint8Array } {
+ const bin = this.crypto.randomBytes(bytes);
+ return {
```
-This function is important because it defines how Fireproof Tutorial: Local-First Document Database for AI-Native Apps implements the patterns covered in this chapter.
+This interface is important because it defines how Fireproof Tutorial: Local-First Document Database for AI-Native Apps implements the patterns covered in this chapter.
### `core/runtime/utils.ts`
-The `presetEnv` function in [`core/runtime/utils.ts`](https://github.com/fireproof-storage/fireproof/blob/HEAD/core/runtime/utils.ts) handles a key part of this chapter's functionality:
+The `Store` interface in [`core/runtime/utils.ts`](https://github.com/fireproof-storage/fireproof/blob/HEAD/core/runtime/utils.ts) handles a key part of this chapter's functionality:
```ts
+ PARAM,
+ PathOps,
+ StoreType,
+ SuperThis,
+ SuperThisOpts,
+ TextEndeCoder,
+ PromiseToUInt8,
+ ToUInt8,
+ HasLogger,
+} from "@fireproof/core-types-base";
+import { base58btc } from "multiformats/bases/base58";
+import { sha256 } from "multiformats/hashes/sha2";
+import { CID } from "multiformats/cid";
+import * as json from "multiformats/codecs/json";
+import { XXH, XXH64 } from "@adviser/ts-xxhash";
+import { z } from "zod/v4";
+
+//export type { Logger };
+//export { Result };
-// const pathOps =
-function presetEnv(ipreset?: Map<string, string> | Record<string, string>): Map<string, string> {
- let preset: Record<string, string> = {};
- if (ipreset instanceof Map) {
- preset = Object.fromEntries<string>(ipreset.entries());
- } else if (typeof ipreset === "object" && ipreset !== null) {
- preset = ipreset;
- }
- const penv = new Map([
- // ["FP_DEBUG", "xxx"],
- // ["FP_ENV", "development"],
- ...Array.from(
- Object.entries({
- ...setPresetEnv({}),
- ...preset,
- }),
- ), // .map(([k, v]) => [k, v as string])
- ]);
- // console.log(">>>>>>", penv)
- return penv;
+const _globalLogger = new ResolveOnce();
+function globalLogger(): Logger {
+ return _globalLogger.once(() => new LoggerImpl());
}
-// const envImpl = envFactory({
-// symbol: "FP_ENV",
-// presetEnv: presetEnv(),
-// });
-class pathOpsImpl implements PathOps {
- join(...paths: string[]): string {
- return paths.map((i) => i.replace(/\/+$/, "")).join("/");
- }
- dirname(path: string) {
- return path.split("/").slice(0, -1).join("/");
+
+const registerFP_DEBUG = new ResolveOnce();
+
+interface superThisOpts {
+ readonly logger: Logger;
+ readonly env: Env;
+ readonly pathOps: PathOps;
+ readonly crypto: CryptoRuntime;
```
-This function is important because it defines how Fireproof Tutorial: Local-First Document Database for AI-Native Apps implements the patterns covered in this chapter.
+This interface is important because it defines how Fireproof Tutorial: Local-First Document Database for AI-Native Apps implements the patterns covered in this chapter.
+
+### `core/runtime/utils.ts`
+
+The `MimeBlock` interface in [`core/runtime/utils.ts`](https://github.com/fireproof-storage/fireproof/blob/HEAD/core/runtime/utils.ts) handles a key part of this chapter's functionality:
+
+```ts
+
+*/
+export interface MimeBlock {
+ readonly preBegin?: string;
+ readonly begin?: string;
+ readonly end?: string;
+ readonly postEnd?: string;
+ readonly content: string;
+}
+
+export function mimeBlockParser(mime: string): MimeBlock[] {
+ const blocks: MimeBlock[] = [];
+ const lines = mime.split("\n");
+
+ let i = 0;
+ let lastProcessedIndex = -1; // Track the last line we've added to a block
+
+ while (i < lines.length) {
+ const line = lines[i];
+
+ // Check if this line starts a PEM-style block
+ // Minimum 3 dashes, allow optional whitespace before/after dashes and case-insensitive BEGIN/END
+ const beginMatch = line.match(/^(-{3,})\s*(BEGIN)\s+(.+?)\s*(-{3,})$/i);
+
+ if (beginMatch) {
+ // Found a BEGIN marker
+ const leadingDashes = beginMatch[1].length;
+ const trailingDashes = beginMatch[4].length;
+ const blockType = beginMatch[3];
+
+ // Create a regex pattern for the matching END marker (case-insensitive)
+ // Escape special regex characters in blockType
+```
+
+This interface is important because it defines how Fireproof Tutorial: Local-First Document Database for AI-Native Apps implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[pathOpsImpl]
- B[Hasher]
- C[globalLogger]
- D[presetEnv]
- E[onSuperThis]
+ A[mimeBlockParser]
+ B[superThisOpts]
+ C[Store]
+ D[MimeBlock]
+ E[BaseStoreImpl]
A --> B
B --> C
C --> D
diff --git a/tutorials/fireproof-tutorial/07-runtime-coverage-browser-node-deno-and-edge.md b/tutorials/fireproof-tutorial/07-runtime-coverage-browser-node-deno-and-edge.md
index 9514a5f1..fa1cb3e6 100644
--- a/tutorials/fireproof-tutorial/07-runtime-coverage-browser-node-deno-and-edge.md
+++ b/tutorials/fireproof-tutorial/07-runtime-coverage-browser-node-deno-and-edge.md
@@ -39,170 +39,168 @@ You now have a portability model for deploying Fireproof across browser and serv
Next: [Chapter 8: Production Operations, Security, and Debugging](08-production-operations-security-and-debugging.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `core/runtime/utils.ts`
+### `core/blockstore/store.ts`
-The `getKey` function in [`core/runtime/utils.ts`](https://github.com/fireproof-storage/fireproof/blob/HEAD/core/runtime/utils.ts) handles a key part of this chapter's functionality:
+The `BaseStoreOpts` interface in [`core/blockstore/store.ts`](https://github.com/fireproof-storage/fireproof/blob/HEAD/core/blockstore/store.ts) handles a key part of this chapter's functionality:
```ts
}
-export function getKey(url: URI, logger: Logger): string {
- const result = url.getParam(PARAM.KEY);
- if (!result) throw logger.Error().Str("url", url.toString()).Msg(`key not found`).AsError();
- return result;
+export interface BaseStoreOpts {
+ readonly gateway: InterceptorGateway;
+ readonly loader: Loadable;
}
-export function getName(sthis: SuperThis, url: URI): string {
- let result = url.getParam(PARAM.NAME);
- if (!result) {
- result = sthis.pathOps.dirname(url.pathname);
- if (result.length === 0) {
- throw sthis.logger.Error().Str("url", url.toString()).Msg(`name not found`).AsError();
- }
- }
- return result;
-}
+export abstract class BaseStoreImpl {
+ // should be injectable
-// export function exception2Result<T = void>(fn: () => Promise<T>): Promise<Result<T>> {
-// return fn()
-// .then((value) => Result.Ok(value))
-// .catch((e) => Result.Err(e));
-// }
+ abstract readonly storeType: StoreType;
+ // readonly name: string;
-export async function exceptionWrapper<T, E extends Error>(fn: () => Promise<Result<T, E>>): Promise<Result<T, E>> {
- return fn().catch((e) => Result.Err(e));
-}
-
-// // the big side effect party --- hate it
-// export function sanitizeURL(url: URL) {
-// url.searchParams.sort();
+ private _url: URI;
+ readonly logger: Logger;
+ readonly sthis: SuperThis;
+ readonly gateway: InterceptorGateway;
+ get realGateway(): SerdeGateway {
+ return this.gateway.innerGW;
+ }
+ // readonly keybag: KeyBag;
+ readonly opts: StoreOpts;
+ readonly loader: Loadable;
+ readonly myId: string;
+ // readonly loader: Loadable;
+ constructor(sthis: SuperThis, url: URI, opts: BaseStoreOpts, logger: Logger) {
+ // this.name = name;
+ this.myId = sthis.nextId().str;
+ this._url = url;
+ this.opts = opts;
+ // this.keybag = opts.keybag;
+ this.loader = opts.loader;
```
-This function is important because it defines how Fireproof Tutorial: Local-First Document Database for AI-Native Apps implements the patterns covered in this chapter.
+This interface is important because it defines how Fireproof Tutorial: Local-First Document Database for AI-Native Apps implements the patterns covered in this chapter.
-### `core/runtime/utils.ts`
+### `core/base/crdt-helpers.ts`
-The `getName` function in [`core/runtime/utils.ts`](https://github.com/fireproof-storage/fireproof/blob/HEAD/core/runtime/utils.ts) handles a key part of this chapter's functionality:
+The `DirtyEventFetcher` class in [`core/base/crdt-helpers.ts`](https://github.com/fireproof-storage/fireproof/blob/HEAD/core/base/crdt-helpers.ts) handles a key part of this chapter's functionality:
```ts
}
-export function getName(sthis: SuperThis, url: URI): string {
- let result = url.getParam(PARAM.NAME);
- if (!result) {
- result = sthis.pathOps.dirname(url.pathname);
- if (result.length === 0) {
- throw sthis.logger.Error().Str("url", url.toString()).Msg(`name not found`).AsError();
+class DirtyEventFetcher<T> extends EventFetcher<T> {
+ readonly logger: Logger;
+ constructor(logger: Logger, blocks: BlockFetcher) {
+ super(toPailFetcher(blocks));
+ this.logger = logger;
+ }
+ async get(link: EventLink<T>): Promise<EventBlockView<T>> {
+ try {
+ return await super.get(link);
+ } catch (e) {
+ this.logger.Error().Ref("link", link.toString()).Err(e).Msg("Missing event");
+ return { value: undefined } as unknown as EventBlockView<T>;
}
}
- return result;
-}
-
-// export function exception2Result<T = void>(fn: () => Promise<T>): Promise<Result<T>> {
-// return fn()
-// .then((value) => Result.Ok(value))
-// .catch((e) => Result.Err(e));
-// }
-
-export async function exceptionWrapper<T, E extends Error>(fn: () => Promise<Result<T, E>>): Promise<Result<T, E>> {
- return fn().catch((e) => Result.Err(e));
}
-// // the big side effect party --- hate it
-// export function sanitizeURL(url: URL) {
-// url.searchParams.sort();
-// // const searchParams = Object.entries(url.searchParams).sort(([a], [b]) => a.localeCompare(b));
-// // console.log("searchParams", searchParams);
-// // for (const [key] of searchParams) {
-// // url.searchParams.delete(key);
-// // }
-// // for (const [key, value] of searchParams) {
+export async function clockChangesSince<T extends DocTypes>(
+ blocks: BlockFetcher,
+ head: ClockHead,
+ since: ClockHead,
+ opts: ChangesOptions,
+ logger: Logger,
+): Promise<{ result: DocUpdate<T>[]; head: ClockHead }> {
+ const eventsFetcher = (
+ opts.dirty ? new DirtyEventFetcher<Operation>(logger, blocks) : new EventFetcher<Operation>(toPailFetcher(blocks))
+ ) as EventFetcher<Operation>;
+ const keys = new Set<string>();
+ const updates = await gatherUpdates<T>(
+ blocks,
+ eventsFetcher,
```
-This function is important because it defines how Fireproof Tutorial: Local-First Document Database for AI-Native Apps implements the patterns covered in this chapter.
+This class is important because it defines how Fireproof Tutorial: Local-First Document Database for AI-Native Apps implements the patterns covered in this chapter.
-### `core/runtime/utils.ts`
+### `core/base/crdt-helpers.ts`
-The `sanitizeURL` function in [`core/runtime/utils.ts`](https://github.com/fireproof-storage/fireproof/blob/HEAD/core/runtime/utils.ts) handles a key part of this chapter's functionality:
+The `toPailFetcher` function in [`core/base/crdt-helpers.ts`](https://github.com/fireproof-storage/fireproof/blob/HEAD/core/base/crdt-helpers.ts) handles a key part of this chapter's functionality:
```ts
+}
-// // the big side effect party --- hate it
-// export function sanitizeURL(url: URL) {
-// url.searchParams.sort();
-// // const searchParams = Object.entries(url.searchParams).sort(([a], [b]) => a.localeCompare(b));
-// // console.log("searchParams", searchParams);
-// // for (const [key] of searchParams) {
-// // url.searchParams.delete(key);
-// // }
-// // for (const [key, value] of searchParams) {
-// // url.searchParams.set(key, value);
-// // }
-// }
-
-export function UInt8ArrayEqual(a: Uint8Array, b: Uint8Array): boolean {
- if (a.length !== b.length) {
- return false;
- }
- for (let i = 0; i < a.length; i++) {
- if (a[i] !== b[i]) {
- return false;
- }
- }
- return true;
+export function toPailFetcher(tblocks: BlockFetcher): PailBlockFetcher {
+ return {
+ get: async <T = unknown, C extends number = number, A extends number = number, V extends Version = 1>(
+ link: Link<T, C, A, V>,
+ ) => {
+ const block = await tblocks.get(link);
+ return block
+ ? ({
+ cid: block.cid,
+ bytes: block.bytes,
+ } as Block<T, C, A, V>)
+ : undefined;
+ },
+ };
}
-export function inplaceFilter<T>(i: T[], pred: (i: T, idx: number) => boolean): T[] {
- const founds: number[] = [];
- for (let j = 0; j < i.length; j++) {
- if (!pred(i[j], j)) {
- founds.push(j);
+export function sanitizeDocumentFields<T>(obj: T): T {
+ if (Array.isArray(obj)) {
+ return obj.map((item: unknown) => {
+ if (typeof item === "object" && item !== null) {
+ return sanitizeDocumentFields(item);
+ }
+ return item;
+ }) as T;
+ } else if (typeof obj === "object" && obj !== null) {
+ // Preserve Uint8Array for CBOR byte string encoding
+ if (isUint8Array(obj)) {
+ return obj;
}
+ // Special case for Date objects - convert to ISO string
```
This function is important because it defines how Fireproof Tutorial: Local-First Document Database for AI-Native Apps implements the patterns covered in this chapter.
-### `core/runtime/utils.ts`
+### `core/base/crdt-helpers.ts`
-The `UInt8ArrayEqual` function in [`core/runtime/utils.ts`](https://github.com/fireproof-storage/fireproof/blob/HEAD/core/runtime/utils.ts) handles a key part of this chapter's functionality:
+The `processFileset` function in [`core/base/crdt-helpers.ts`](https://github.com/fireproof-storage/fireproof/blob/HEAD/core/base/crdt-helpers.ts) handles a key part of this chapter's functionality:
```ts
-// }
-
-export function UInt8ArrayEqual(a: Uint8Array, b: Uint8Array): boolean {
- if (a.length !== b.length) {
- return false;
- }
- for (let i = 0; i < a.length; i++) {
- if (a[i] !== b[i]) {
- return false;
- }
- }
- return true;
-}
-
-export function inplaceFilter<T>(i: T[], pred: (i: T, idx: number) => boolean): T[] {
- const founds: number[] = [];
- for (let j = 0; j < i.length; j++) {
- if (!pred(i[j], j)) {
- founds.push(j);
- }
+async function processFiles<T extends DocTypes>(store: StoreRuntime, blocks: CarTransaction, doc: DocSet<T>, logger: Logger) {
+ if (doc._files) {
+ await processFileset(logger, store, blocks, doc._files);
}
- for (let j = founds.length - 1; j >= 0; j--) {
- i.splice(founds[j], 1);
+ if (doc._publicFiles) {
+ await processFileset(logger, store, blocks, doc._publicFiles /*, true*/);
}
- return i;
}
-export function coerceIntoUint8(raw: ToUInt8): Result<Uint8Array> {
- if (raw instanceof Uint8Array) {
- return Result.Ok(raw);
- }
- if (Result.Is(raw)) {
+async function processFileset(
+ logger: Logger,
+ store: StoreRuntime,
+ blocks: CarTransaction,
+ files: DocFiles /*, publicFiles = false */,
+) {
+ const dbBlockstore = blocks.parent as unknown as EncryptedBlockstore;
+ if (!dbBlockstore.loader) throw logger.Error().Msg("Missing loader, ledger name is required").AsError();
+ const t = new CarTransactionImpl(dbBlockstore); // maybe this should move to encrypted-blockstore
+ const didPut = [];
+ // let totalSize = 0
+ for (const filename in files) {
+ if (File === files[filename].constructor) {
+ const file = files[filename] as File;
+
+ // totalSize += file.size
+ const { cid, blocks: fileBlocks } = await store.encodeFile(file);
+ didPut.push(filename);
+ for (const block of fileBlocks) {
+ // console.log("processFileset", block.cid.toString())
+ t.putSync(await fileBlock2FPBlock(block));
+ }
+ files[filename] = { cid, type: file.type, size: file.size, lastModified: file.lastModified } as DocFileMeta;
```
This function is important because it defines how Fireproof Tutorial: Local-First Document Database for AI-Native Apps implements the patterns covered in this chapter.
@@ -212,11 +210,11 @@ This function is important because it defines how Fireproof Tutorial: Local-Firs
```mermaid
flowchart TD
- A[getKey]
- B[getName]
- C[sanitizeURL]
- D[UInt8ArrayEqual]
- E[coerceIntoUint8]
+ A[BaseStoreOpts]
+ B[DirtyEventFetcher]
+ C[toPailFetcher]
+ D[processFileset]
+ E[readFileset]
A --> B
B --> C
C --> D
diff --git a/tutorials/fireproof-tutorial/08-production-operations-security-and-debugging.md b/tutorials/fireproof-tutorial/08-production-operations-security-and-debugging.md
index 7545dce6..6a654885 100644
--- a/tutorials/fireproof-tutorial/08-production-operations-security-and-debugging.md
+++ b/tutorials/fireproof-tutorial/08-production-operations-security-and-debugging.md
@@ -41,170 +41,158 @@ Production Fireproof deployments need explicit practices for observability, key
You now have a practical baseline for operating Fireproof in production-grade app workflows.
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `core/runtime/utils.ts`
+### `dashboard/backend/create-handler.ts`
-The `setPresetEnv` function in [`core/runtime/utils.ts`](https://github.com/fireproof-storage/fireproof/blob/HEAD/core/runtime/utils.ts) handles a key part of this chapter's functionality:
+The `DefaultHttpHeaders` function in [`dashboard/backend/create-handler.ts`](https://github.com/fireproof-storage/fireproof/blob/HEAD/dashboard/backend/create-handler.ts) handles a key part of this chapter's functionality:
```ts
- ...Array.from(
- Object.entries({
- ...setPresetEnv({}),
- ...preset,
- }),
- ), // .map(([k, v]) => [k, v as string])
- ]);
- // console.log(">>>>>>", penv)
- return penv;
+);
+
+export function DefaultHttpHeaders(...h: CoercedHeadersInit[]): HeadersInit {
+ return defaultHttpHeaders()
+ .Merge(...h)
+ .AsHeaderInit();
}
-// const envImpl = envFactory({
-// symbol: "FP_ENV",
-// presetEnv: presetEnv(),
-// });
-class pathOpsImpl implements PathOps {
- join(...paths: string[]): string {
- return paths.map((i) => i.replace(/\/+$/, "")).join("/");
- }
- dirname(path: string) {
- return path.split("/").slice(0, -1).join("/");
+
+export type DashSqlite = BaseSQLiteDatabase<"async", ResultSet | D1Result, Record<string, never>>;
+
+export type BindPromise<T> = (promise: Promise<T>) => Promise<T>;
+
+class ReqResEventoEnDecoder implements EventoEnDecoder<Request, string> {
+ async encode(args: Request): Promise<Result<unknown>> {
+ if (args.method === "POST" || args.method === "PUT") {
+ const body = (await args.json()) as unknown;
+ return Result.Ok(body);
+ }
+ return Result.Ok(null);
}
- basename(path: string): string {
- return path.split("/").pop() || "";
+ decode(data: unknown): Promise<Result<string>> {
+ return Promise.resolve(Result.Ok(JSON.stringify(data)));
}
- // homedir() {
- // throw new Error("SysContainer:homedir is not available in seeded state");
- // }
}
-const pathOps = new pathOpsImpl();
-const txtOps = ((txtEncoder, txtDecoder) => ({
- id: () => "fp-txtOps",
- encode: (input: string) => txtEncoder.encode(input),
+
+interface ResponseType {
+ type: "Response";
+ payload: {
+ status: number;
+ headers: HeadersInit;
+ body: BodyInit;
+ };
```
This function is important because it defines how Fireproof Tutorial: Local-First Document Database for AI-Native Apps implements the patterns covered in this chapter.
-### `core/runtime/utils.ts`
+### `dashboard/backend/create-handler.ts`
-The `hashStringAsync` function in [`core/runtime/utils.ts`](https://github.com/fireproof-storage/fireproof/blob/HEAD/core/runtime/utils.ts) handles a key part of this chapter's functionality:
+The `isResponseType` function in [`dashboard/backend/create-handler.ts`](https://github.com/fireproof-storage/fireproof/blob/HEAD/dashboard/backend/create-handler.ts) handles a key part of this chapter's functionality:
```ts
- }
-}
-export async function hashStringAsync(str: string): Promise<string> {
- const bytes = json.encode(str);
- const hash = await sha256.digest(bytes);
- return CID.create(1, json.code, hash).toString();
}
-export function hashStringSync(str: string): string {
- return new Hasher().update(str).digest();
+function isResponseType(obj: unknown): obj is ResponseType {
+ if (typeof obj !== "object" || obj === null) {
+ return false;
+ }
+ return (obj as ResponseType).type === "Response";
}
-export function hashObjectSync<T extends NonNullable<S>, S>(o: T): string {
- const hasher = new Hasher();
- toSorted(o, (x, key) => {
- switch (key) {
- case "Null":
- case "Array":
- case "Function":
- break;
- case "Date":
- hasher.update(`D:${(x as Date).toISOString()}`);
- break;
- case "Symbol":
- hasher.update(`S:(x as symbol).toString()}`);
- break;
- case "Key":
- hasher.update(`K:${x as string}`);
- break;
- case "String":
- hasher.update(`S:${x as string}`);
- break;
+export const fpApiEvento = Lazy(() => {
+ const evento = new Evento(new ReqResEventoEnDecoder());
+ evento.push(
+ {
+ hash: "cors-preflight",
+ validate: (ctx: ValidateTriggerCtx<Request, unknown, unknown>) => {
+ const { request: req } = ctx;
+ if (req && req.method === "OPTIONS") {
+ return Promise.resolve(Result.Ok(Option.Some("Send CORS preflight response")));
+ }
+ return Promise.resolve(Result.Ok(Option.None()));
+ },
+ handle: async (ctx: HandleTriggerCtx<Request, string, unknown>): Promise<Result<EventoResultType>> => {
+ await ctx.send.send(ctx, {
+ type: "Response",
+ payload: {
+ status: 200,
+ headers: DefaultHttpHeaders({ "Content-Type": "application/json" }),
+ body: JSON.stringify({ type: "ok", message: "CORS preflight" }),
+ },
+ } satisfies ResponseType);
+ return Result.Ok(EventoResult.Stop);
+ },
```
This function is important because it defines how Fireproof Tutorial: Local-First Document Database for AI-Native Apps implements the patterns covered in this chapter.
-### `core/runtime/utils.ts`
+### `dashboard/backend/create-handler.ts`
-The `hashStringSync` function in [`core/runtime/utils.ts`](https://github.com/fireproof-storage/fireproof/blob/HEAD/core/runtime/utils.ts) handles a key part of this chapter's functionality:
+The `ResponseType` interface in [`dashboard/backend/create-handler.ts`](https://github.com/fireproof-storage/fireproof/blob/HEAD/dashboard/backend/create-handler.ts) handles a key part of this chapter's functionality:
```ts
}
-export function hashStringSync(str: string): string {
- return new Hasher().update(str).digest();
+interface ResponseType {
+ type: "Response";
+ payload: {
+ status: number;
+ headers: HeadersInit;
+ body: BodyInit;
+ };
}
-export function hashObjectSync<T extends NonNullable<S>, S>(o: T): string {
- const hasher = new Hasher();
- toSorted(o, (x, key) => {
- switch (key) {
- case "Null":
- case "Array":
- case "Function":
- break;
- case "Date":
- hasher.update(`D:${(x as Date).toISOString()}`);
- break;
- case "Symbol":
- hasher.update(`S:(x as symbol).toString()}`);
- break;
- case "Key":
- hasher.update(`K:${x as string}`);
- break;
- case "String":
- hasher.update(`S:${x as string}`);
- break;
- case "Boolean":
- hasher.update(`B:${x ? "true" : "false"}`);
- break;
- case "Number":
- hasher.update(`N:${(x as number).toString()}`);
- break;
-```
-
-This function is important because it defines how Fireproof Tutorial: Local-First Document Database for AI-Native Apps implements the patterns covered in this chapter.
+function isResponseType(obj: unknown): obj is ResponseType {
+ if (typeof obj !== "object" || obj === null) {
+ return false;
+ }
+ return (obj as ResponseType).type === "Response";
+}
-### `core/runtime/utils.ts`
+export const fpApiEvento = Lazy(() => {
+ const evento = new Evento(new ReqResEventoEnDecoder());
+ evento.push(
+ {
+ hash: "cors-preflight",
+ validate: (ctx: ValidateTriggerCtx<Request, unknown, unknown>) => {
+ const { request: req } = ctx;
+ if (req && req.method === "OPTIONS") {
+ return Promise.resolve(Result.Ok(Option.Some("Send CORS preflight response")));
+ }
+ return Promise.resolve(Result.Ok(Option.None()));
+ },
+ handle: async (ctx: HandleTriggerCtx<Request, string, unknown>): Promise<Result<EventoResultType>> => {
+ await ctx.send.send(ctx, {
+```
-The `sleep` function in [`core/runtime/utils.ts`](https://github.com/fireproof-storage/fireproof/blob/HEAD/core/runtime/utils.ts) handles a key part of this chapter's functionality:
+This interface is important because it defines how Fireproof Tutorial: Local-First Document Database for AI-Native Apps implements the patterns covered in this chapter.
-```ts
-}
+### `smoke/get-fp-version.js`
-export function sleep(ms: number) {
- return new Promise((resolve) => setTimeout(resolve, ms));
-}
+The `getVersion` function in [`smoke/get-fp-version.js`](https://github.com/fireproof-storage/fireproof/blob/HEAD/smoke/get-fp-version.js) handles a key part of this chapter's functionality:
-/**
- * Deep clone a value
- */
-export function deepClone<T>(value: T): T {
- return (structuredClone ?? ((v: T) => JSON.parse(JSON.stringify(v))))(value);
-}
+```js
+import * as process from "node:process";
-function coerceLogger(loggerOrHasLogger: Logger | HasLogger): Logger {
- if (IsLogger(loggerOrHasLogger)) {
- return loggerOrHasLogger;
- } else {
- return loggerOrHasLogger.logger;
+function getVersion(version = "refs/tags/v0.0.0-smoke") {
+ if (process.env.GITHUB_REF && process.env.GITHUB_REF.startsWith("refs/tags/v")) {
+ version = process.env.GITHUB_REF;
}
+ return version.split("/").slice(-1)[0].replace(/^v/, "");
}
-export function timerStart(loggerOrHasLogger: Logger | HasLogger, tag: string) {
- coerceLogger(loggerOrHasLogger).Debug().TimerStart(tag).Msg("Timing started");
+async function main() {
+ const gitHead = (await $`git rev-parse --short HEAD`).stdout.trim();
+ const dateTick = (await $`date +%s`).stdout.trim();
+ // eslint-disable-next-line no-console, no-undef
+ console.log(getVersion(`refs/tags/v0.0.0-smoke-${gitHead}-${dateTick}`));
}
-export function timerEnd(loggerOrHasLogger: Logger | HasLogger, tag: string) {
- coerceLogger(loggerOrHasLogger).Debug().TimerEnd(tag).Msg("Timing ended");
-}
+main().catch((e) => {
+ // eslint-disable-next-line no-console, no-undef
+ console.error(e);
+ process.exit(1);
+});
-export function deepFreeze<T extends object>(o?: T): T | undefined {
- if (!o) return undefined;
- Object.freeze(o);
```
This function is important because it defines how Fireproof Tutorial: Local-First Document Database for AI-Native Apps implements the patterns covered in this chapter.
@@ -214,11 +202,11 @@ This function is important because it defines how Fireproof Tutorial: Local-Firs
```mermaid
flowchart TD
- A[setPresetEnv]
- B[hashStringAsync]
- C[hashStringSync]
- D[sleep]
- E[coerceLogger]
+ A[DefaultHttpHeaders]
+ B[isResponseType]
+ C[ResponseType]
+ D[getVersion]
+ E[main]
A --> B
B --> C
C --> D
diff --git a/tutorials/flowise-tutorial/01-system-overview.md b/tutorials/flowise-tutorial/01-system-overview.md
index b2f713ca..6ba4bb12 100644
--- a/tutorials/flowise-tutorial/01-system-overview.md
+++ b/tutorials/flowise-tutorial/01-system-overview.md
@@ -6,6 +6,7 @@ has_children: false
parent: "Flowise LLM Orchestration"
---
+
# Chapter 1: Flowise System Overview
Welcome to **Chapter 1: Flowise System Overview**. In this part of **Flowise LLM Orchestration: Deep Dive Tutorial**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
@@ -566,94 +567,18 @@ Suggested trace strategy:
## Depth Expansion Playbook
-<!-- depth-expansion-v2 -->
-
-This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
-
-### Strategic Context
-
-- tutorial: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- tutorial slug: **flowise-tutorial**
-- chapter focus: **Chapter 1: Flowise System Overview**
-- system context: **Flowise Llm Orchestration**
-- objective: move from surface-level usage to repeatable engineering operation
-
-### Architecture Decomposition
-
-1. Define the runtime boundary for `Chapter 1: Flowise System Overview`.
-2. Separate control-plane decisions from data-plane execution.
-3. Capture input contracts, transformation points, and output contracts.
-4. Trace state transitions across request lifecycle stages.
-5. Identify extension hooks and policy interception points.
-6. Map ownership boundaries for team and automation workflows.
-7. Specify rollback and recovery paths for unsafe changes.
-8. Track observability signals for correctness, latency, and cost.
-
-### Operator Decision Matrix
-
-| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
-|:--------------|:--------------|:------------------|:---------|
-| Runtime mode | managed defaults | explicit policy config | speed vs control |
-| State handling | local ephemeral | durable persisted state | simplicity vs auditability |
-| Tool integration | direct API use | mediated adapter layer | velocity vs governance |
-| Rollout method | manual change | staged + canary rollout | effort vs safety |
-| Incident response | best effort logs | runbooks + SLO alerts | cost vs reliability |
-
-### Failure Modes and Countermeasures
-
-| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
-|:-------------|:-------------|:-------------------|:---------------|
-| stale context | inconsistent outputs | missing refresh window | enforce context TTL and refresh hooks |
-| policy drift | unexpected execution | ad hoc overrides | centralize policy profiles |
-| auth mismatch | 401/403 bursts | credential sprawl | rotation schedule + scope minimization |
-| schema breakage | parser/validation errors | unmanaged upstream changes | contract tests per release |
-| retry storms | queue congestion | no backoff controls | jittered backoff + circuit breakers |
-| silent regressions | quality drop without alerts | weak baseline metrics | eval harness with thresholds |
-
-### Implementation Runbook
-
-1. Establish a reproducible baseline environment.
-2. Capture chapter-specific success criteria before changes.
-3. Implement minimal viable path with explicit interfaces.
-4. Add observability before expanding feature scope.
-5. Run deterministic tests for happy-path behavior.
-6. Inject failure scenarios for negative-path validation.
-7. Compare output quality against baseline snapshots.
-8. Promote through staged environments with rollback gates.
-9. Record operational lessons in release notes.
-
-### Quality Gate Checklist
-
-- [ ] chapter-level assumptions are explicit and testable
-- [ ] API/tool boundaries are documented with input/output examples
-- [ ] failure handling includes retry, timeout, and fallback policy
-- [ ] security controls include auth scopes and secret rotation plans
-- [ ] observability includes logs, metrics, traces, and alert thresholds
-- [ ] deployment guidance includes canary and rollback paths
-- [ ] docs include links to upstream sources and related tracks
-- [ ] post-release verification confirms expected behavior under load
-
-### Source Alignment
-
-- [Flowise](https://github.com/FlowiseAI/Flowise)
-- [AI Codebase Knowledge Builder](https://github.com/The-Pocket/Tutorial-Codebase-Knowledge)
-
-### Cross-Tutorial Connection Map
-
-- Related tutorials are listed in this tutorial index.
-
-### Advanced Practice Exercises
+## How These Components Connect
-1. Build a minimal end-to-end implementation for `Chapter 1: Flowise System Overview`.
-2. Add instrumentation and measure baseline latency and error rate.
-3. Introduce one controlled failure and confirm graceful recovery.
-4. Add policy constraints and verify they are enforced consistently.
-5. Run a staged rollout and document rollback decision criteria.
-
-### Review Questions
-
-1. Which execution boundary matters most for this chapter and why?
-2. What signal detects regressions earliest in your environment?
-3. What tradeoff did you make between delivery speed and governance?
-4. How would you recover from the highest-impact failure mode?
-5. What must be automated before scaling to team-wide adoption?
+```mermaid
+flowchart TD
+ A[User] --> B[Flowise Web UI]
+ B --> C[Drag-and-drop canvas]
+ C --> D[Node graph: LLM + tools + chains]
+ D --> E[Flowise API server]
+ E --> F[Execute flow]
+ F --> G[LLM provider]
+ F --> H[Vector store]
+ F --> I[External tools]
+ G --> J[Response to user]
+ H --> J
+```
diff --git a/tutorials/flowise-tutorial/03-node-development.md b/tutorials/flowise-tutorial/03-node-development.md
index 36a6642a..c4b42200 100644
--- a/tutorials/flowise-tutorial/03-node-development.md
+++ b/tutorials/flowise-tutorial/03-node-development.md
@@ -940,6 +940,20 @@ After working through this chapter, you should be able to reason about `Chapter
Use the implementation notes around `inputs`, `model`, `node` as your checklist when adapting these patterns to your own repository.
+## Node Development Architecture
+
+```mermaid
+flowchart TD
+ A[Custom Node TypeScript class] --> B[Extend INode interface]
+ B --> C[Define inputs / outputs / credentials]
+ C --> D[Implement async init method]
+ D --> E[Build LangChain component]
+ E --> F[Return to Flowise runtime]
+ F --> G[Node available in canvas]
+ G --> H[Connected in drag-and-drop flow]
+ H --> I[Flow executed via POST /api/v1/prediction]
+```
+
## How it Works Under the Hood
Under the hood, `Chapter 3: Node Development` usually follows a repeatable control path:
diff --git a/tutorials/flowise-tutorial/04-advanced-integrations.md b/tutorials/flowise-tutorial/04-advanced-integrations.md
index 6b8031db..1f9c6ad4 100644
--- a/tutorials/flowise-tutorial/04-advanced-integrations.md
+++ b/tutorials/flowise-tutorial/04-advanced-integrations.md
@@ -1206,6 +1206,21 @@ After working through this chapter, you should be able to reason about `Chapter
Use the implementation notes around `description`, `requirements`, `provider` as your checklist when adapting these patterns to your own repository.
+## Advanced Integration Architecture
+
+```mermaid
+flowchart TD
+ A[Flowise flow] --> B{Integration type}
+ B -->|Multiple LLMs| C[Provider nodes: OpenAI, Anthropic, etc.]
+ B -->|Vector stores| D[Pinecone, Weaviate, Chroma nodes]
+ B -->|External APIs| E[Custom tool nodes]
+ C --> F[Conditional routing node]
+ D --> F
+ E --> F
+ F --> G[Merged output]
+ G --> H[Response node]
+```
+
## How it Works Under the Hood
Under the hood, `Chapter 4: Advanced Integrations` usually follows a repeatable control path:
diff --git a/tutorials/flowise-tutorial/05-production-deployment.md b/tutorials/flowise-tutorial/05-production-deployment.md
index d3927209..293bba80 100644
--- a/tutorials/flowise-tutorial/05-production-deployment.md
+++ b/tutorials/flowise-tutorial/05-production-deployment.md
@@ -1123,6 +1123,22 @@ After working through this chapter, you should be able to reason about `Chapter
Use the implementation notes around `workflowId`, `production`, `metadata` as your checklist when adapting these patterns to your own repository.
+## Production Deployment Architecture
+
+```mermaid
+flowchart TD
+ A[Flowise Docker image] --> B[docker-compose or K8s]
+ B --> C{Storage backend}
+ C -->|SQLite| D[Single node deployment]
+ C -->|PostgreSQL| E[HA multi-node deployment]
+ D --> F[Flowise server :3000]
+ E --> F
+ F --> G[Nginx / load balancer]
+ G --> H[API clients / UI users]
+ F --> I[Vector store connections]
+ F --> J[LLM provider APIs]
+```
+
## How it Works Under the Hood
Under the hood, `Chapter 5: Production Deployment` usually follows a repeatable control path:
diff --git a/tutorials/flowise-tutorial/06-security-governance.md b/tutorials/flowise-tutorial/06-security-governance.md
index b698a40b..4ae5251b 100644
--- a/tutorials/flowise-tutorial/06-security-governance.md
+++ b/tutorials/flowise-tutorial/06-security-governance.md
@@ -6,6 +6,7 @@ has_children: false
parent: "Flowise LLM Orchestration"
---
+
# Chapter 6: Security and Governance
Welcome to **Chapter 6: Security and Governance**. In this part of **Flowise LLM Orchestration: Deep Dive Tutorial**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
@@ -107,478 +108,16 @@ Suggested trace strategy:
## Depth Expansion Playbook
-<!-- depth-expansion-v2 -->
-
-This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
-
-### Strategic Context
-
-- tutorial: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- tutorial slug: **flowise-tutorial**
-- chapter focus: **Chapter 6: Security and Governance**
-- system context: **Flowise Llm Orchestration**
-- objective: move from surface-level usage to repeatable engineering operation
-
-### Architecture Decomposition
-
-1. Define the runtime boundary for `Chapter 6: Security and Governance`.
-2. Separate control-plane decisions from data-plane execution.
-3. Capture input contracts, transformation points, and output contracts.
-4. Trace state transitions across request lifecycle stages.
-5. Identify extension hooks and policy interception points.
-6. Map ownership boundaries for team and automation workflows.
-7. Specify rollback and recovery paths for unsafe changes.
-8. Track observability signals for correctness, latency, and cost.
-
-### Operator Decision Matrix
-
-| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
-|:--------------|:--------------|:------------------|:---------|
-| Runtime mode | managed defaults | explicit policy config | speed vs control |
-| State handling | local ephemeral | durable persisted state | simplicity vs auditability |
-| Tool integration | direct API use | mediated adapter layer | velocity vs governance |
-| Rollout method | manual change | staged + canary rollout | effort vs safety |
-| Incident response | best effort logs | runbooks + SLO alerts | cost vs reliability |
-
-### Failure Modes and Countermeasures
-
-| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
-|:-------------|:-------------|:-------------------|:---------------|
-| stale context | inconsistent outputs | missing refresh window | enforce context TTL and refresh hooks |
-| policy drift | unexpected execution | ad hoc overrides | centralize policy profiles |
-| auth mismatch | 401/403 bursts | credential sprawl | rotation schedule + scope minimization |
-| schema breakage | parser/validation errors | unmanaged upstream changes | contract tests per release |
-| retry storms | queue congestion | no backoff controls | jittered backoff + circuit breakers |
-| silent regressions | quality drop without alerts | weak baseline metrics | eval harness with thresholds |
-
-### Implementation Runbook
-
-1. Establish a reproducible baseline environment.
-2. Capture chapter-specific success criteria before changes.
-3. Implement minimal viable path with explicit interfaces.
-4. Add observability before expanding feature scope.
-5. Run deterministic tests for happy-path behavior.
-6. Inject failure scenarios for negative-path validation.
-7. Compare output quality against baseline snapshots.
-8. Promote through staged environments with rollback gates.
-9. Record operational lessons in release notes.
-
-### Quality Gate Checklist
-
-- [ ] chapter-level assumptions are explicit and testable
-- [ ] API/tool boundaries are documented with input/output examples
-- [ ] failure handling includes retry, timeout, and fallback policy
-- [ ] security controls include auth scopes and secret rotation plans
-- [ ] observability includes logs, metrics, traces, and alert thresholds
-- [ ] deployment guidance includes canary and rollback paths
-- [ ] docs include links to upstream sources and related tracks
-- [ ] post-release verification confirms expected behavior under load
-
-### Source Alignment
-
-- [Flowise](https://github.com/FlowiseAI/Flowise)
-- [AI Codebase Knowledge Builder](https://github.com/The-Pocket/Tutorial-Codebase-Knowledge)
-
-### Cross-Tutorial Connection Map
-
-- Related tutorials are listed in this tutorial index.
-
-### Advanced Practice Exercises
-
-1. Build a minimal end-to-end implementation for `Chapter 6: Security and Governance`.
-2. Add instrumentation and measure baseline latency and error rate.
-3. Introduce one controlled failure and confirm graceful recovery.
-4. Add policy constraints and verify they are enforced consistently.
-5. Run a staged rollout and document rollback decision criteria.
-
-### Review Questions
-
-1. Which execution boundary matters most for this chapter and why?
-2. What signal detects regressions earliest in your environment?
-3. What tradeoff did you make between delivery speed and governance?
-4. How would you recover from the highest-impact failure mode?
-5. What must be automated before scaling to team-wide adoption?
-
-### Scenario Playbook 1: Chapter 6: Security and Governance
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 2: Chapter 6: Security and Governance
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 3: Chapter 6: Security and Governance
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 4: Chapter 6: Security and Governance
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 5: Chapter 6: Security and Governance
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 6: Chapter 6: Security and Governance
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 7: Chapter 6: Security and Governance
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 8: Chapter 6: Security and Governance
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 9: Chapter 6: Security and Governance
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 10: Chapter 6: Security and Governance
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 11: Chapter 6: Security and Governance
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 12: Chapter 6: Security and Governance
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 13: Chapter 6: Security and Governance
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 14: Chapter 6: Security and Governance
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 15: Chapter 6: Security and Governance
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 16: Chapter 6: Security and Governance
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 17: Chapter 6: Security and Governance
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 18: Chapter 6: Security and Governance
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 19: Chapter 6: Security and Governance
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 20: Chapter 6: Security and Governance
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 21: Chapter 6: Security and Governance
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 22: Chapter 6: Security and Governance
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 23: Chapter 6: Security and Governance
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 24: Chapter 6: Security and Governance
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 25: Chapter 6: Security and Governance
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 26: Chapter 6: Security and Governance
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 27: Chapter 6: Security and Governance
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 28: Chapter 6: Security and Governance
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 29: Chapter 6: Security and Governance
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 30: Chapter 6: Security and Governance
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 31: Chapter 6: Security and Governance
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 32: Chapter 6: Security and Governance
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
+## How These Components Connect
+
+```mermaid
+flowchart TD
+ A[Flowise server] --> B{Auth layer}
+ B -->|Basic auth| C[Username/password]
+ B -->|API key| D[X-Authorization header]
+ C --> E[Protected UI access]
+ D --> F[Protected API access]
+ E --> G[Chatflow execution]
+ F --> G
+ G --> H[Audit trail in DB]
+```
diff --git a/tutorials/flowise-tutorial/07-observability.md b/tutorials/flowise-tutorial/07-observability.md
index 16fb63fa..f7666249 100644
--- a/tutorials/flowise-tutorial/07-observability.md
+++ b/tutorials/flowise-tutorial/07-observability.md
@@ -6,6 +6,7 @@ has_children: false
parent: "Flowise LLM Orchestration"
---
+
# Chapter 7: Observability
Welcome to **Chapter 7: Observability**. In this part of **Flowise LLM Orchestration: Deep Dive Tutorial**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
@@ -104,478 +105,17 @@ Suggested trace strategy:
## Depth Expansion Playbook
-<!-- depth-expansion-v2 -->
-
-This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
-
-### Strategic Context
-
-- tutorial: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- tutorial slug: **flowise-tutorial**
-- chapter focus: **Chapter 7: Observability**
-- system context: **Flowise Llm Orchestration**
-- objective: move from surface-level usage to repeatable engineering operation
-
-### Architecture Decomposition
-
-1. Define the runtime boundary for `Chapter 7: Observability`.
-2. Separate control-plane decisions from data-plane execution.
-3. Capture input contracts, transformation points, and output contracts.
-4. Trace state transitions across request lifecycle stages.
-5. Identify extension hooks and policy interception points.
-6. Map ownership boundaries for team and automation workflows.
-7. Specify rollback and recovery paths for unsafe changes.
-8. Track observability signals for correctness, latency, and cost.
-
-### Operator Decision Matrix
-
-| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
-|:--------------|:--------------|:------------------|:---------|
-| Runtime mode | managed defaults | explicit policy config | speed vs control |
-| State handling | local ephemeral | durable persisted state | simplicity vs auditability |
-| Tool integration | direct API use | mediated adapter layer | velocity vs governance |
-| Rollout method | manual change | staged + canary rollout | effort vs safety |
-| Incident response | best effort logs | runbooks + SLO alerts | cost vs reliability |
-
-### Failure Modes and Countermeasures
-
-| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
-|:-------------|:-------------|:-------------------|:---------------|
-| stale context | inconsistent outputs | missing refresh window | enforce context TTL and refresh hooks |
-| policy drift | unexpected execution | ad hoc overrides | centralize policy profiles |
-| auth mismatch | 401/403 bursts | credential sprawl | rotation schedule + scope minimization |
-| schema breakage | parser/validation errors | unmanaged upstream changes | contract tests per release |
-| retry storms | queue congestion | no backoff controls | jittered backoff + circuit breakers |
-| silent regressions | quality drop without alerts | weak baseline metrics | eval harness with thresholds |
-
-### Implementation Runbook
-
-1. Establish a reproducible baseline environment.
-2. Capture chapter-specific success criteria before changes.
-3. Implement minimal viable path with explicit interfaces.
-4. Add observability before expanding feature scope.
-5. Run deterministic tests for happy-path behavior.
-6. Inject failure scenarios for negative-path validation.
-7. Compare output quality against baseline snapshots.
-8. Promote through staged environments with rollback gates.
-9. Record operational lessons in release notes.
-
-### Quality Gate Checklist
-
-- [ ] chapter-level assumptions are explicit and testable
-- [ ] API/tool boundaries are documented with input/output examples
-- [ ] failure handling includes retry, timeout, and fallback policy
-- [ ] security controls include auth scopes and secret rotation plans
-- [ ] observability includes logs, metrics, traces, and alert thresholds
-- [ ] deployment guidance includes canary and rollback paths
-- [ ] docs include links to upstream sources and related tracks
-- [ ] post-release verification confirms expected behavior under load
-
-### Source Alignment
-
-- [Flowise](https://github.com/FlowiseAI/Flowise)
-- [AI Codebase Knowledge Builder](https://github.com/The-Pocket/Tutorial-Codebase-Knowledge)
-
-### Cross-Tutorial Connection Map
-
-- Related tutorials are listed in this tutorial index.
-
-### Advanced Practice Exercises
-
-1. Build a minimal end-to-end implementation for `Chapter 7: Observability`.
-2. Add instrumentation and measure baseline latency and error rate.
-3. Introduce one controlled failure and confirm graceful recovery.
-4. Add policy constraints and verify they are enforced consistently.
-5. Run a staged rollout and document rollback decision criteria.
-
-### Review Questions
-
-1. Which execution boundary matters most for this chapter and why?
-2. What signal detects regressions earliest in your environment?
-3. What tradeoff did you make between delivery speed and governance?
-4. How would you recover from the highest-impact failure mode?
-5. What must be automated before scaling to team-wide adoption?
-
-### Scenario Playbook 1: Chapter 7: Observability
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 2: Chapter 7: Observability
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 3: Chapter 7: Observability
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 4: Chapter 7: Observability
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 5: Chapter 7: Observability
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 6: Chapter 7: Observability
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 7: Chapter 7: Observability
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 8: Chapter 7: Observability
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 9: Chapter 7: Observability
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 10: Chapter 7: Observability
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 11: Chapter 7: Observability
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 12: Chapter 7: Observability
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 13: Chapter 7: Observability
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 14: Chapter 7: Observability
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 15: Chapter 7: Observability
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 16: Chapter 7: Observability
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 17: Chapter 7: Observability
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 18: Chapter 7: Observability
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 19: Chapter 7: Observability
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 20: Chapter 7: Observability
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 21: Chapter 7: Observability
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 22: Chapter 7: Observability
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 23: Chapter 7: Observability
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 24: Chapter 7: Observability
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 25: Chapter 7: Observability
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 26: Chapter 7: Observability
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 27: Chapter 7: Observability
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 28: Chapter 7: Observability
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 29: Chapter 7: Observability
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 30: Chapter 7: Observability
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 31: Chapter 7: Observability
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 32: Chapter 7: Observability
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
+## How These Components Connect
+
+```mermaid
+flowchart TD
+ A[Flow execution] --> B[Flowise server logs]
+ B --> C{Observability target}
+ C -->|LangSmith| D[Trace every LLM call]
+ C -->|LangFuse| E[OSS tracing]
+ C -->|Custom| F[Webhook callbacks]
+ D --> G[Latency / cost / errors]
+ E --> G
+ F --> G
+ G --> H[Dashboard / alerts]
+```
diff --git a/tutorials/flowise-tutorial/08-extension-ecosystem.md b/tutorials/flowise-tutorial/08-extension-ecosystem.md
index b4bf4036..afff2ceb 100644
--- a/tutorials/flowise-tutorial/08-extension-ecosystem.md
+++ b/tutorials/flowise-tutorial/08-extension-ecosystem.md
@@ -6,6 +6,7 @@ has_children: false
parent: "Flowise LLM Orchestration"
---
+
# Chapter 8: Extension Ecosystem
Welcome to **Chapter 8: Extension Ecosystem**. In this part of **Flowise LLM Orchestration: Deep Dive Tutorial**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
@@ -96,490 +97,17 @@ Suggested trace strategy:
## Depth Expansion Playbook
-<!-- depth-expansion-v2 -->
-
-This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
-
-### Strategic Context
-
-- tutorial: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- tutorial slug: **flowise-tutorial**
-- chapter focus: **Chapter 8: Extension Ecosystem**
-- system context: **Flowise Llm Orchestration**
-- objective: move from surface-level usage to repeatable engineering operation
-
-### Architecture Decomposition
-
-1. Define the runtime boundary for `Chapter 8: Extension Ecosystem`.
-2. Separate control-plane decisions from data-plane execution.
-3. Capture input contracts, transformation points, and output contracts.
-4. Trace state transitions across request lifecycle stages.
-5. Identify extension hooks and policy interception points.
-6. Map ownership boundaries for team and automation workflows.
-7. Specify rollback and recovery paths for unsafe changes.
-8. Track observability signals for correctness, latency, and cost.
-
-### Operator Decision Matrix
-
-| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
-|:--------------|:--------------|:------------------|:---------|
-| Runtime mode | managed defaults | explicit policy config | speed vs control |
-| State handling | local ephemeral | durable persisted state | simplicity vs auditability |
-| Tool integration | direct API use | mediated adapter layer | velocity vs governance |
-| Rollout method | manual change | staged + canary rollout | effort vs safety |
-| Incident response | best effort logs | runbooks + SLO alerts | cost vs reliability |
-
-### Failure Modes and Countermeasures
-
-| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
-|:-------------|:-------------|:-------------------|:---------------|
-| stale context | inconsistent outputs | missing refresh window | enforce context TTL and refresh hooks |
-| policy drift | unexpected execution | ad hoc overrides | centralize policy profiles |
-| auth mismatch | 401/403 bursts | credential sprawl | rotation schedule + scope minimization |
-| schema breakage | parser/validation errors | unmanaged upstream changes | contract tests per release |
-| retry storms | queue congestion | no backoff controls | jittered backoff + circuit breakers |
-| silent regressions | quality drop without alerts | weak baseline metrics | eval harness with thresholds |
-
-### Implementation Runbook
-
-1. Establish a reproducible baseline environment.
-2. Capture chapter-specific success criteria before changes.
-3. Implement minimal viable path with explicit interfaces.
-4. Add observability before expanding feature scope.
-5. Run deterministic tests for happy-path behavior.
-6. Inject failure scenarios for negative-path validation.
-7. Compare output quality against baseline snapshots.
-8. Promote through staged environments with rollback gates.
-9. Record operational lessons in release notes.
-
-### Quality Gate Checklist
-
-- [ ] chapter-level assumptions are explicit and testable
-- [ ] API/tool boundaries are documented with input/output examples
-- [ ] failure handling includes retry, timeout, and fallback policy
-- [ ] security controls include auth scopes and secret rotation plans
-- [ ] observability includes logs, metrics, traces, and alert thresholds
-- [ ] deployment guidance includes canary and rollback paths
-- [ ] docs include links to upstream sources and related tracks
-- [ ] post-release verification confirms expected behavior under load
-
-### Source Alignment
-
-- [Flowise](https://github.com/FlowiseAI/Flowise)
-- [AI Codebase Knowledge Builder](https://github.com/The-Pocket/Tutorial-Codebase-Knowledge)
-
-### Cross-Tutorial Connection Map
-
-- Related tutorials are listed in this tutorial index.
-
-### Advanced Practice Exercises
-
-1. Build a minimal end-to-end implementation for `Chapter 8: Extension Ecosystem`.
-2. Add instrumentation and measure baseline latency and error rate.
-3. Introduce one controlled failure and confirm graceful recovery.
-4. Add policy constraints and verify they are enforced consistently.
-5. Run a staged rollout and document rollback decision criteria.
-
-### Review Questions
-
-1. Which execution boundary matters most for this chapter and why?
-2. What signal detects regressions earliest in your environment?
-3. What tradeoff did you make between delivery speed and governance?
-4. How would you recover from the highest-impact failure mode?
-5. What must be automated before scaling to team-wide adoption?
-
-### Scenario Playbook 1: Chapter 8: Extension Ecosystem
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 2: Chapter 8: Extension Ecosystem
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 3: Chapter 8: Extension Ecosystem
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 4: Chapter 8: Extension Ecosystem
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 5: Chapter 8: Extension Ecosystem
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 6: Chapter 8: Extension Ecosystem
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 7: Chapter 8: Extension Ecosystem
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 8: Chapter 8: Extension Ecosystem
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 9: Chapter 8: Extension Ecosystem
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 10: Chapter 8: Extension Ecosystem
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 11: Chapter 8: Extension Ecosystem
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 12: Chapter 8: Extension Ecosystem
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 13: Chapter 8: Extension Ecosystem
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 14: Chapter 8: Extension Ecosystem
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 15: Chapter 8: Extension Ecosystem
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 16: Chapter 8: Extension Ecosystem
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 17: Chapter 8: Extension Ecosystem
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 18: Chapter 8: Extension Ecosystem
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 19: Chapter 8: Extension Ecosystem
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 20: Chapter 8: Extension Ecosystem
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 21: Chapter 8: Extension Ecosystem
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 22: Chapter 8: Extension Ecosystem
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 23: Chapter 8: Extension Ecosystem
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 24: Chapter 8: Extension Ecosystem
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 25: Chapter 8: Extension Ecosystem
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 26: Chapter 8: Extension Ecosystem
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 27: Chapter 8: Extension Ecosystem
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 28: Chapter 8: Extension Ecosystem
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 29: Chapter 8: Extension Ecosystem
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 30: Chapter 8: Extension Ecosystem
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 31: Chapter 8: Extension Ecosystem
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 32: Chapter 8: Extension Ecosystem
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 33: Chapter 8: Extension Ecosystem
-
-- tutorial context: **Flowise LLM Orchestration: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
+## How These Components Connect
+
+```mermaid
+flowchart TD
+ A[Flowise core] --> B[Built-in nodes]
+ B --> C[LLM providers]
+ B --> D[Vector stores]
+ B --> E[Memory / agents]
+ A --> F[Custom node]
+ F --> G[packages/components/nodes/]
+ G --> H[TypeScript class extending BaseNode]
+ H --> I[Registered in node index]
+ I --> J[Available in canvas UI]
+```
diff --git a/tutorials/gemini-cli-tutorial/01-getting-started.md b/tutorials/gemini-cli-tutorial/01-getting-started.md
index 88143a62..1eb8dbe4 100644
--- a/tutorials/gemini-cli-tutorial/01-getting-started.md
+++ b/tutorials/gemini-cli-tutorial/01-getting-started.md
@@ -73,170 +73,168 @@ You now have a working Gemini CLI baseline for both interactive and scripted usa
Next: [Chapter 2: Architecture, Tools, and Agent Loop](02-architecture-tools-and-agent-loop.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `scripts/lint.js`
+### `scripts/get-release-version.js`
-The `getPlatformArch` function in [`scripts/lint.js`](https://github.com/google-gemini/gemini-cli/blob/HEAD/scripts/lint.js) handles a key part of this chapter's functionality:
+The `readJson` function in [`scripts/get-release-version.js`](https://github.com/google-gemini/gemini-cli/blob/HEAD/scripts/get-release-version.js) handles a key part of this chapter's functionality:
```js
- process.env.GEMINI_LINT_TEMP_DIR || join(tmpdir(), 'gemini-cli-linters');
-
-function getPlatformArch() {
- const platform = process.platform;
- const arch = process.arch;
- if (platform === 'linux' && arch === 'x64') {
- return {
- actionlint: 'linux_amd64',
- shellcheck: 'linux.x86_64',
- };
- }
- if (platform === 'darwin' && arch === 'x64') {
- return {
- actionlint: 'darwin_amd64',
- shellcheck: 'darwin.x86_64',
- };
- }
- if (platform === 'darwin' && arch === 'arm64') {
- return {
- actionlint: 'darwin_arm64',
- shellcheck: 'darwin.aarch64',
- };
- }
- if (platform === 'win32' && arch === 'x64') {
- return {
- actionlint: 'windows_amd64',
- // shellcheck is not used for Windows since it uses the .zip release
- // which has a consistent name across architectures
- };
- }
- throw new Error(`Unsupported platform/architecture: ${platform}/${arch}`);
+const TAG_PREVIEW = 'preview';
+
+function readJson(filePath) {
+ return JSON.parse(readFileSync(filePath, 'utf-8'));
}
+
+function getArgs() {
+ return yargs(hideBin(process.argv))
+ .option('type', {
+ description: 'The type of release to generate a version for.',
+ choices: [TAG_NIGHTLY, 'promote-nightly', 'stable', TAG_PREVIEW, 'patch'],
+ default: TAG_NIGHTLY,
+ })
+ .option('patch-from', {
+ description: 'When type is "patch", specifies the source branch.',
+ choices: ['stable', TAG_PREVIEW],
+ string: true,
+ })
+ .option('stable_version_override', {
+ description: 'Override the calculated stable version.',
+ string: true,
+ })
+ .option('cli-package-name', {
+ description:
+ 'fully qualified package name with scope (e.g @google/gemini-cli)',
+ string: true,
+ default: '@google/gemini-cli',
+ })
+ .option('preview_version_override', {
+ description: 'Override the calculated preview version.',
+ string: true,
+ })
```
This function is important because it defines how Gemini CLI Tutorial: Terminal-First Agent Workflows with Google Gemini implements the patterns covered in this chapter.
-### `scripts/lint.js`
+### `scripts/get-release-version.js`
-The `runCommand` function in [`scripts/lint.js`](https://github.com/google-gemini/gemini-cli/blob/HEAD/scripts/lint.js) handles a key part of this chapter's functionality:
+The `getArgs` function in [`scripts/get-release-version.js`](https://github.com/google-gemini/gemini-cli/blob/HEAD/scripts/get-release-version.js) handles a key part of this chapter's functionality:
```js
-};
-
-function runCommand(command, stdio = 'inherit') {
- try {
- const env = { ...process.env };
- const nodeBin = join(process.cwd(), 'node_modules', '.bin');
- const sep = isWindows ? ';' : ':';
- const pythonBin = isWindows
- ? join(PYTHON_VENV_PATH, 'Scripts')
- : join(PYTHON_VENV_PATH, 'bin');
- // Windows sometimes uses 'Path' instead of 'PATH'
- const pathKey = 'Path' in env ? 'Path' : 'PATH';
- env[pathKey] = [
- nodeBin,
- join(TEMP_DIR, 'actionlint'),
- join(TEMP_DIR, 'shellcheck'),
- pythonBin,
- env[pathKey],
- ].join(sep);
- execSync(command, { stdio, env, shell: true });
- return true;
- } catch (_e) {
- return false;
- }
}
-export function setupLinters() {
- console.log('Setting up linters...');
- if (!process.env.GEMINI_LINT_TEMP_DIR) {
- rmSync(TEMP_DIR, { recursive: true, force: true });
- }
- mkdirSync(TEMP_DIR, { recursive: true });
+function getArgs() {
+ return yargs(hideBin(process.argv))
+ .option('type', {
+ description: 'The type of release to generate a version for.',
+ choices: [TAG_NIGHTLY, 'promote-nightly', 'stable', TAG_PREVIEW, 'patch'],
+ default: TAG_NIGHTLY,
+ })
+ .option('patch-from', {
+ description: 'When type is "patch", specifies the source branch.',
+ choices: ['stable', TAG_PREVIEW],
+ string: true,
+ })
+ .option('stable_version_override', {
+ description: 'Override the calculated stable version.',
+ string: true,
+ })
+ .option('cli-package-name', {
+ description:
+ 'fully qualified package name with scope (e.g @google/gemini-cli)',
+ string: true,
+ default: '@google/gemini-cli',
+ })
+ .option('preview_version_override', {
+ description: 'Override the calculated preview version.',
+ string: true,
+ })
+ .option('stable-base-version', {
+ description: 'Base version to use for calculating next preview/nightly.',
+ string: true,
+ })
```
This function is important because it defines how Gemini CLI Tutorial: Terminal-First Agent Workflows with Google Gemini implements the patterns covered in this chapter.
-### `scripts/lint.js`
+### `scripts/get-release-version.js`
-The `setupLinters` function in [`scripts/lint.js`](https://github.com/google-gemini/gemini-cli/blob/HEAD/scripts/lint.js) handles a key part of this chapter's functionality:
+The `getLatestTag` function in [`scripts/get-release-version.js`](https://github.com/google-gemini/gemini-cli/blob/HEAD/scripts/get-release-version.js) handles a key part of this chapter's functionality:
```js
}
-export function setupLinters() {
- console.log('Setting up linters...');
- if (!process.env.GEMINI_LINT_TEMP_DIR) {
- rmSync(TEMP_DIR, { recursive: true, force: true });
- }
- mkdirSync(TEMP_DIR, { recursive: true });
-
- for (const linter in LINTERS) {
- const { check, installer } = LINTERS[linter];
- if (!runCommand(check, 'ignore')) {
- console.log(`Installing ${linter}...`);
- if (!runCommand(installer)) {
- console.error(
- `Failed to install ${linter}. Please install it manually.`,
- );
- process.exit(1);
- }
- }
- }
- console.log('All required linters are available.');
-}
-
-export function runESLint() {
- console.log('\nRunning ESLint...');
- if (!runCommand('npm run lint')) {
- process.exit(1);
+function getLatestTag(pattern) {
+ const command = `git tag -l '${pattern}'`;
+ try {
+ const tags = execSync(command)
+ .toString()
+ .trim()
+ .split('\n')
+ .filter(Boolean);
+ if (tags.length === 0) return '';
+
+ // Convert tags to versions (remove 'v' prefix) and sort by semver
+ const versions = tags
+ .map((tag) => tag.replace(/^v/, ''))
+ .filter((version) => semver.valid(version))
+ .sort((a, b) => semver.rcompare(a, b)); // rcompare for descending order
+
+ if (versions.length === 0) return '';
+
+ // Return the latest version with 'v' prefix restored
+ return `v${versions[0]}`;
+ } catch (error) {
+ console.error(
+ `Failed to get latest git tag for pattern "${pattern}": ${error.message}`,
+ );
+ return '';
}
}
-export function runActionlint() {
+function getVersionFromNPM({ args, npmDistTag } = {}) {
+ const command = `npm view ${args['cli-package-name']} version --tag=${npmDistTag}`;
```
This function is important because it defines how Gemini CLI Tutorial: Terminal-First Agent Workflows with Google Gemini implements the patterns covered in this chapter.
-### `scripts/lint.js`
+### `scripts/get-release-version.js`
-The `runESLint` function in [`scripts/lint.js`](https://github.com/google-gemini/gemini-cli/blob/HEAD/scripts/lint.js) handles a key part of this chapter's functionality:
+The `getVersionFromNPM` function in [`scripts/get-release-version.js`](https://github.com/google-gemini/gemini-cli/blob/HEAD/scripts/get-release-version.js) handles a key part of this chapter's functionality:
```js
}
-export function runESLint() {
- console.log('\nRunning ESLint...');
- if (!runCommand('npm run lint')) {
- process.exit(1);
- }
-}
-
-export function runActionlint() {
- console.log('\nRunning actionlint...');
- if (!runCommand(LINTERS.actionlint.run)) {
- process.exit(1);
- }
-}
-
-export function runShellcheck() {
- console.log('\nRunning shellcheck...');
- if (!runCommand(LINTERS.shellcheck.run)) {
- process.exit(1);
+function getVersionFromNPM({ args, npmDistTag } = {}) {
+ const command = `npm view ${args['cli-package-name']} version --tag=${npmDistTag}`;
+ try {
+ return execSync(command).toString().trim();
+ } catch (error) {
+ console.error(
+ `Failed to get NPM version for dist-tag "${npmDistTag}": ${error.message}`,
+ );
+ return '';
}
}
-export function runYamllint() {
- console.log('\nRunning yamllint...');
- if (!runCommand(LINTERS.yamllint.run)) {
- process.exit(1);
+function getAllVersionsFromNPM({ args } = {}) {
+ const command = `npm view ${args['cli-package-name']} versions --json`;
+ try {
+ const versionsJson = execSync(command).toString().trim();
+ return JSON.parse(versionsJson);
+ } catch (error) {
+ console.error(`Failed to get all NPM versions: ${error.message}`);
+ return [];
}
}
-export function runPrettier() {
- console.log('\nRunning Prettier...');
+function isVersionDeprecated({ args, version } = {}) {
+ const command = `npm view ${args['cli-package-name']}@${version} deprecated`;
+ try {
+ const output = execSync(command).toString().trim();
+ return output.length > 0;
+ } catch (error) {
+ // This command shouldn't fail for existing versions, but as a safeguard:
```
This function is important because it defines how Gemini CLI Tutorial: Terminal-First Agent Workflows with Google Gemini implements the patterns covered in this chapter.
@@ -246,11 +244,11 @@ This function is important because it defines how Gemini CLI Tutorial: Terminal-
```mermaid
flowchart TD
- A[getPlatformArch]
- B[runCommand]
- C[setupLinters]
- D[runESLint]
- E[runActionlint]
+ A[readJson]
+ B[getArgs]
+ C[getLatestTag]
+ D[getVersionFromNPM]
+ E[getAllVersionsFromNPM]
A --> B
B --> C
C --> D
diff --git a/tutorials/gemini-cli-tutorial/02-architecture-tools-and-agent-loop.md b/tutorials/gemini-cli-tutorial/02-architecture-tools-and-agent-loop.md
index febeef7d..596dc9f9 100644
--- a/tutorials/gemini-cli-tutorial/02-architecture-tools-and-agent-loop.md
+++ b/tutorials/gemini-cli-tutorial/02-architecture-tools-and-agent-loop.md
@@ -56,170 +56,168 @@ You now have a strong mental model of Gemini CLI execution internals.
Next: [Chapter 3: Authentication and Model Access Strategy](03-authentication-and-model-access-strategy.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `scripts/lint.js`
+### `scripts/get-release-version.js`
-The `runTSConfigLinter` function in [`scripts/lint.js`](https://github.com/google-gemini/gemini-cli/blob/HEAD/scripts/lint.js) handles a key part of this chapter's functionality:
+The `validateVersion` function in [`scripts/get-release-version.js`](https://github.com/google-gemini/gemini-cli/blob/HEAD/scripts/get-release-version.js) handles a key part of this chapter's functionality:
```js
}
-export function runTSConfigLinter() {
- console.log('\nRunning tsconfig linter...');
-
- let files = [];
- try {
- // Find all tsconfig.json files under packages/ using a git pathspec
- files = execSync("git ls-files 'packages/**/tsconfig.json'")
- .toString()
- .trim()
- .split('\n')
- .filter(Boolean);
- } catch (e) {
- console.error('Error finding tsconfig.json files:', e.message);
- process.exit(1);
- }
-
- let hasError = false;
+function validateVersion(version, format, name) {
+ const versionRegex = {
+ 'X.Y.Z': /^\d+\.\d+\.\d+$/,
+ 'X.Y.Z-preview.N': /^\d+\.\d+\.\d+-preview\.\d+$/,
+ };
- for (const file of files) {
- const tsconfigPath = join(process.cwd(), file);
- if (!existsSync(tsconfigPath)) {
- console.error(`Error: ${tsconfigPath} does not exist.`);
- hasError = true;
- continue;
- }
+ if (!versionRegex[format] || !versionRegex[format].test(version)) {
+ throw new Error(
+ `Invalid ${name}: ${version}. Must be in ${format} format.`,
+ );
+ }
+}
- try {
- const content = readFileSync(tsconfigPath, 'utf-8');
- const config = JSON.parse(stripJSONComments(content));
+function getStableVersion(args) {
+ const { latestVersion: latestPreviewVersion } = getAndVerifyTags({
+ npmDistTag: TAG_PREVIEW,
+ args,
+ });
+ let releaseVersion;
+ if (args['stable_version_override']) {
+ const overrideVersion = args['stable_version_override'].replace(/^v/, '');
+ validateVersion(overrideVersion, 'X.Y.Z', 'stable_version_override');
+ releaseVersion = overrideVersion;
+ } else {
+ releaseVersion = latestPreviewVersion.replace(/-preview.*/, '');
+ }
+ const { latestTag: previousStableTag } = getAndVerifyTags({
+ npmDistTag: TAG_LATEST,
+ args,
```
This function is important because it defines how Gemini CLI Tutorial: Terminal-First Agent Workflows with Google Gemini implements the patterns covered in this chapter.
-### `scripts/lint.js`
+### `scripts/get-release-version.js`
-The `main` function in [`scripts/lint.js`](https://github.com/google-gemini/gemini-cli/blob/HEAD/scripts/lint.js) handles a key part of this chapter's functionality:
+The `getStableVersion` function in [`scripts/get-release-version.js`](https://github.com/google-gemini/gemini-cli/blob/HEAD/scripts/get-release-version.js) handles a key part of this chapter's functionality:
```js
+}
- function getChangedFiles() {
- const baseRef = process.env.GITHUB_BASE_REF || 'main';
- try {
- execSync(`git fetch origin ${baseRef}`);
- const mergeBase = execSync(`git merge-base HEAD origin/${baseRef}`)
- .toString()
- .trim();
- return execSync(`git diff --name-only ${mergeBase}..HEAD`)
- .toString()
- .trim()
- .split('\n')
- .filter(Boolean);
- } catch (_error) {
- console.error(`Could not get changed files against origin/${baseRef}.`);
- try {
- console.log('Falling back to diff against HEAD~1');
- return execSync(`git diff --name-only HEAD~1..HEAD`)
- .toString()
- .trim()
- .split('\n')
- .filter(Boolean);
- } catch (_fallbackError) {
- console.error('Could not get changed files against HEAD~1 either.');
- process.exit(1);
- }
- }
+function getStableVersion(args) {
+ const { latestVersion: latestPreviewVersion } = getAndVerifyTags({
+ npmDistTag: TAG_PREVIEW,
+ args,
+ });
+ let releaseVersion;
+ if (args['stable_version_override']) {
+ const overrideVersion = args['stable_version_override'].replace(/^v/, '');
+ validateVersion(overrideVersion, 'X.Y.Z', 'stable_version_override');
+ releaseVersion = overrideVersion;
+ } else {
+ releaseVersion = latestPreviewVersion.replace(/-preview.*/, '');
}
- const changedFiles = getChangedFiles();
- let violationsFound = false;
+ const { latestTag: previousStableTag } = getAndVerifyTags({
+ npmDistTag: TAG_LATEST,
+ args,
+ });
+
+ return {
+ releaseVersion,
+ npmTag: TAG_LATEST,
+ previousReleaseTag: previousStableTag,
+ };
+}
+
+function getPreviewVersion(args) {
+ const latestStableVersion = getStableBaseVersion(args);
+ let releaseVersion;
```
This function is important because it defines how Gemini CLI Tutorial: Terminal-First Agent Workflows with Google Gemini implements the patterns covered in this chapter.
-### `scripts/telemetry_utils.js`
+### `scripts/get-release-version.js`
-The `getJson` function in [`scripts/telemetry_utils.js`](https://github.com/google-gemini/gemini-cli/blob/HEAD/scripts/telemetry_utils.js) handles a key part of this chapter's functionality:
+The `getPreviewVersion` function in [`scripts/get-release-version.js`](https://github.com/google-gemini/gemini-cli/blob/HEAD/scripts/get-release-version.js) handles a key part of this chapter's functionality:
```js
-);
-
-export function getJson(url) {
- const tmpFile = path.join(
- os.tmpdir(),
- `gemini-cli-releases-${Date.now()}.json`,
- );
- try {
- const result = spawnSync(
- 'curl',
- ['-sL', '-H', 'User-Agent: gemini-cli-dev-script', '-o', tmpFile, url],
- { stdio: 'pipe', encoding: 'utf-8' },
+}
+
+function getPreviewVersion(args) {
+ const latestStableVersion = getStableBaseVersion(args);
+
+ let releaseVersion;
+ if (args['preview_version_override']) {
+ const overrideVersion = args['preview_version_override'].replace(/^v/, '');
+ validateVersion(
+ overrideVersion,
+ 'X.Y.Z-preview.N',
+ 'preview_version_override',
);
- if (result.status !== 0) {
- throw new Error(result.stderr);
- }
- const content = fs.readFileSync(tmpFile, 'utf-8');
- return JSON.parse(content);
- } catch (e) {
- console.error(`Failed to fetch or parse JSON from ${url}`);
- throw e;
- } finally {
- if (fs.existsSync(tmpFile)) {
- fs.unlinkSync(tmpFile);
- }
+ releaseVersion = overrideVersion;
+ } else {
+ const major = semver.major(latestStableVersion);
+ const minor = semver.minor(latestStableVersion);
+ const nextMinor = minor + 1;
+ releaseVersion = `${major}.${nextMinor}.0-preview.0`;
}
-}
-export function downloadFile(url, dest) {
- try {
- const result = spawnSync('curl', ['-fL', '-sS', '-o', dest, url], {
- stdio: 'pipe',
+ const { latestTag: previousPreviewTag } = getAndVerifyTags({
+ npmDistTag: TAG_PREVIEW,
+ args,
+ });
+
+ return {
+ releaseVersion,
+ npmTag: TAG_PREVIEW,
+ previousReleaseTag: previousPreviewTag,
+ };
+}
```
This function is important because it defines how Gemini CLI Tutorial: Terminal-First Agent Workflows with Google Gemini implements the patterns covered in this chapter.
-### `scripts/telemetry_utils.js`
+### `scripts/get-release-version.js`
-The `downloadFile` function in [`scripts/telemetry_utils.js`](https://github.com/google-gemini/gemini-cli/blob/HEAD/scripts/telemetry_utils.js) handles a key part of this chapter's functionality:
+The `getPatchVersion` function in [`scripts/get-release-version.js`](https://github.com/google-gemini/gemini-cli/blob/HEAD/scripts/get-release-version.js) handles a key part of this chapter's functionality:
```js
}
-export function downloadFile(url, dest) {
- try {
- const result = spawnSync('curl', ['-fL', '-sS', '-o', dest, url], {
- stdio: 'pipe',
- encoding: 'utf-8',
- });
- if (result.status !== 0) {
- throw new Error(result.stderr);
- }
- return dest;
- } catch (e) {
- console.error(`Failed to download file from ${url}`);
- throw e;
- }
-}
-
-export function findFile(startPath, filter) {
- if (!fs.existsSync(startPath)) {
- return null;
+function getPatchVersion(args) {
+ const patchFrom = args['patch-from'];
+ if (!patchFrom || (patchFrom !== 'stable' && patchFrom !== TAG_PREVIEW)) {
+ throw new Error(
+ 'Patch type must be specified with --patch-from=stable or --patch-from=preview',
+ );
}
- const files = fs.readdirSync(startPath);
- for (const file of files) {
- const filename = path.join(startPath, file);
- const stat = fs.lstatSync(filename);
- if (stat.isDirectory()) {
- const result = findFile(filename, filter);
- if (result) return result;
- } else if (filter(file)) {
- return filename;
- }
+ const distTag = patchFrom === 'stable' ? TAG_LATEST : TAG_PREVIEW;
+ const { latestVersion, latestTag } = getAndVerifyTags({
+ npmDistTag: distTag,
+ args,
+ });
+
+ if (patchFrom === 'stable') {
+ // For stable versions, increment the patch number: 0.5.4 -> 0.5.5
+ const versionParts = latestVersion.split('.');
+ const major = versionParts[0];
+ const minor = versionParts[1];
+ const patch = versionParts[2] ? parseInt(versionParts[2]) : 0;
+ const releaseVersion = `${major}.${minor}.${patch + 1}`;
+ return {
+ releaseVersion,
+ npmTag: distTag,
+ previousReleaseTag: latestTag,
+ };
+ } else {
+ // For preview versions, increment the preview number: 0.6.0-preview.2 -> 0.6.0-preview.3
+ const [version, prereleasePart] = latestVersion.split('-');
+ if (!prereleasePart || !prereleasePart.startsWith('preview.')) {
+ throw new Error(
```
This function is important because it defines how Gemini CLI Tutorial: Terminal-First Agent Workflows with Google Gemini implements the patterns covered in this chapter.
@@ -229,11 +227,11 @@ This function is important because it defines how Gemini CLI Tutorial: Terminal-
```mermaid
flowchart TD
- A[runTSConfigLinter]
- B[main]
- C[getJson]
- D[downloadFile]
- E[findFile]
+ A[validateVersion]
+ B[getStableVersion]
+ C[getPreviewVersion]
+ D[getPatchVersion]
+ E[getVersion]
A --> B
B --> C
C --> D
diff --git a/tutorials/gemini-cli-tutorial/03-authentication-and-model-access-strategy.md b/tutorials/gemini-cli-tutorial/03-authentication-and-model-access-strategy.md
index fe33aa23..28c3c431 100644
--- a/tutorials/gemini-cli-tutorial/03-authentication-and-model-access-strategy.md
+++ b/tutorials/gemini-cli-tutorial/03-authentication-and-model-access-strategy.md
@@ -67,12 +67,133 @@ You now have a clear and repeatable auth/model-access strategy.
Next: [Chapter 4: Settings, Context, and Custom Commands](04-settings-context-and-custom-commands.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `scripts/telemetry_utils.js`
+The `moveBinary` function in [`scripts/telemetry_utils.js`](https://github.com/google-gemini/gemini-cli/blob/HEAD/scripts/telemetry_utils.js) handles a key part of this chapter's functionality:
+
+```js
+}
+
+export function moveBinary(source, destination) {
+ try {
+ fs.renameSync(source, destination);
+ } catch (error) {
+ if (error.code !== 'EXDEV') {
+ throw error;
+ }
+ // Handle a cross-device error: copy-to-temp-then-rename.
+ const destDir = path.dirname(destination);
+ const destFile = path.basename(destination);
+ const tempDest = path.join(destDir, `${destFile}.tmp`);
+
+ try {
+ fs.copyFileSync(source, tempDest);
+ fs.renameSync(tempDest, destination);
+ } catch (moveError) {
+ // If copy or rename fails, clean up the intermediate temp file.
+ if (fs.existsSync(tempDest)) {
+ fs.unlinkSync(tempDest);
+ }
+ throw moveError;
+ }
+ fs.unlinkSync(source);
+ }
+}
+
+export function waitForPort(port, timeout = 10000) {
+ return new Promise((resolve, reject) => {
+ const startTime = Date.now();
+ const tryConnect = () => {
+```
+
+This function is important because it defines how Gemini CLI Tutorial: Terminal-First Agent Workflows with Google Gemini implements the patterns covered in this chapter.
+
+### `scripts/telemetry_utils.js`
+
+The `waitForPort` function in [`scripts/telemetry_utils.js`](https://github.com/google-gemini/gemini-cli/blob/HEAD/scripts/telemetry_utils.js) handles a key part of this chapter's functionality:
+
+```js
+}
+
+export function waitForPort(port, timeout = 10000) {
+ return new Promise((resolve, reject) => {
+ const startTime = Date.now();
+ const tryConnect = () => {
+ const socket = new net.Socket();
+ socket.once('connect', () => {
+ socket.end();
+ resolve();
+ });
+ socket.once('error', (_) => {
+ if (Date.now() - startTime > timeout) {
+ reject(new Error(`Timeout waiting for port ${port} to open.`));
+ } else {
+ setTimeout(tryConnect, 500);
+ }
+ });
+ socket.connect(port, 'localhost');
+ };
+ tryConnect();
+ });
+}
+
+export async function ensureBinary(
+ executableName,
+ repo,
+ assetNameCallback,
+ binaryNameInArchive,
+ isJaeger = false,
+) {
+ const executablePath = path.join(BIN_DIR, executableName);
+```
+
+This function is important because it defines how Gemini CLI Tutorial: Terminal-First Agent Workflows with Google Gemini implements the patterns covered in this chapter.
+
+### `scripts/telemetry_utils.js`
+
+The `ensureBinary` function in [`scripts/telemetry_utils.js`](https://github.com/google-gemini/gemini-cli/blob/HEAD/scripts/telemetry_utils.js) handles a key part of this chapter's functionality:
+
+```js
+}
+
+export async function ensureBinary(
+ executableName,
+ repo,
+ assetNameCallback,
+ binaryNameInArchive,
+ isJaeger = false,
+) {
+ const executablePath = path.join(BIN_DIR, executableName);
+ if (fileExists(executablePath)) {
+ console.log(`✅ ${executableName} already exists at ${executablePath}`);
+ return executablePath;
+ }
+
+ console.log(`🔍 ${executableName} not found. Downloading from ${repo}...`);
+
+ const platform = process.platform === 'win32' ? 'windows' : process.platform;
+ const arch = process.arch === 'x64' ? 'amd64' : process.arch;
+ const ext = platform === 'windows' ? 'zip' : 'tar.gz';
+
+ if (isJaeger && platform === 'windows' && arch === 'arm64') {
+ console.warn(
+ `⚠️ Jaeger does not have a release for Windows on ARM64. Skipping.`,
+ );
+ return null;
+ }
+
+ let release;
+ let asset;
+
+ if (isJaeger) {
+```
+
+This function is important because it defines how Gemini CLI Tutorial: Terminal-First Agent Workflows with Google Gemini implements the patterns covered in this chapter.
+
+### `scripts/telemetry_utils.js`
+
The `manageTelemetrySettings` function in [`scripts/telemetry_utils.js`](https://github.com/google-gemini/gemini-cli/blob/HEAD/scripts/telemetry_utils.js) handles a key part of this chapter's functionality:
```js
@@ -112,139 +233,16 @@ export function manageTelemetrySettings(
This function is important because it defines how Gemini CLI Tutorial: Terminal-First Agent Workflows with Google Gemini implements the patterns covered in this chapter.
-### `scripts/telemetry_utils.js`
-
-The `registerCleanup` function in [`scripts/telemetry_utils.js`](https://github.com/google-gemini/gemini-cli/blob/HEAD/scripts/telemetry_utils.js) handles a key part of this chapter's functionality:
-
-```js
-}
-
-export function registerCleanup(
- getProcesses,
- getLogFileDescriptors,
- originalSandboxSetting,
-) {
- let cleanedUp = false;
- const cleanup = () => {
- if (cleanedUp) return;
- cleanedUp = true;
-
- console.log('\n👋 Shutting down...');
-
- manageTelemetrySettings(false, null, null, originalSandboxSetting);
-
- const processes = getProcesses ? getProcesses() : [];
- processes.forEach((proc) => {
- if (proc && proc.pid) {
- const name = path.basename(proc.spawnfile);
- try {
- console.log(`🛑 Stopping ${name} (PID: ${proc.pid})...`);
- process.kill(proc.pid, 'SIGTERM');
- console.log(`✅ ${name} stopped.`);
- } catch (e) {
- if (e.code !== 'ESRCH') {
- console.error(`Error stopping ${name}: ${e.message}`);
- }
- }
- }
- });
-
-```
-
-This function is important because it defines how Gemini CLI Tutorial: Terminal-First Agent Workflows with Google Gemini implements the patterns covered in this chapter.
-
-### `eslint.config.js`
-
-The `instantiation` class in [`eslint.config.js`](https://github.com/google-gemini/gemini-cli/blob/HEAD/eslint.config.js) handles a key part of this chapter's functionality:
-
-```js
- 'CallExpression[callee.object.name="Object"][callee.property.name="create"]',
- message:
- 'Avoid using Object.create() in product code. Use object spread {...obj}, explicit class instantiation, structuredClone(), or copy constructors instead.',
- },
- {
- selector: 'Identifier[name="Reflect"]',
- message:
- 'Avoid using Reflect namespace in product code. Do not use reflection to make copies. Instead, use explicit object copying or cloning (structuredClone() for values, new instance/clone function for classes).',
- },
- ],
- },
- },
- {
- // Allow os.homedir() in tests and paths.ts where it is used to implement the helper
- files: [
- '**/*.test.ts',
- '**/*.test.tsx',
- 'packages/core/src/utils/paths.ts',
- 'packages/test-utils/src/**/*.ts',
- 'scripts/**/*.js',
- ],
- rules: {
- 'no-restricted-imports': 'off',
- },
- },
- {
- // Prevent self-imports in packages
- files: ['packages/core/src/**/*.{ts,tsx}'],
- rules: {
- 'no-restricted-imports': [
- 'error',
- {
-```
-
-This class is important because it defines how Gemini CLI Tutorial: Terminal-First Agent Workflows with Google Gemini implements the patterns covered in this chapter.
-
-### `eslint.config.js`
-
-The `and` interface in [`eslint.config.js`](https://github.com/google-gemini/gemini-cli/blob/HEAD/eslint.config.js) handles a key part of this chapter's functionality:
-
-```js
- 'UnaryExpression[operator="typeof"] > MemberExpression[computed=true][property.type="Literal"]',
- message:
- 'Do not use typeof to check object properties. Define a TypeScript interface and a type guard function instead.',
- },
-];
-
-export default tseslint.config(
- {
- // Global ignores
- ignores: [
- '**/node_modules/**',
- 'eslint.config.js',
- 'packages/**/dist/**',
- 'bundle/**',
- 'package/bundle/**',
- '.integration-tests/**',
- 'dist/**',
- 'evals/**',
- 'packages/test-utils/**',
- '.gemini/**',
- '**/*.d.ts',
- ],
- },
- eslint.configs.recommended,
- ...tseslint.configs.recommended,
- reactHooks.configs['recommended-latest'],
- reactPlugin.configs.flat.recommended,
- reactPlugin.configs.flat['jsx-runtime'], // Add this if you are using React 17+
- {
- // Settings for eslint-plugin-react
- settings: {
- react: {
-```
-
-This interface is important because it defines how Gemini CLI Tutorial: Terminal-First Agent Workflows with Google Gemini implements the patterns covered in this chapter.
-
## How These Components Connect
```mermaid
flowchart TD
- A[manageTelemetrySettings]
- B[registerCleanup]
- C[instantiation]
- D[and]
- E[readJson]
+ A[moveBinary]
+ B[waitForPort]
+ C[ensureBinary]
+ D[manageTelemetrySettings]
+ E[registerCleanup]
A --> B
B --> C
C --> D
diff --git a/tutorials/gemini-cli-tutorial/04-settings-context-and-custom-commands.md b/tutorials/gemini-cli-tutorial/04-settings-context-and-custom-commands.md
index 17686b7b..a8aab017 100644
--- a/tutorials/gemini-cli-tutorial/04-settings-context-and-custom-commands.md
+++ b/tutorials/gemini-cli-tutorial/04-settings-context-and-custom-commands.md
@@ -54,170 +54,168 @@ You now know how to codify Gemini CLI behavior with durable settings and command
Next: [Chapter 5: MCP, Extensions, and Skills](05-mcp-extensions-and-skills.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `scripts/get-release-version.js`
+### `scripts/generate-settings-schema.ts`
-The `doesVersionExist` function in [`scripts/get-release-version.js`](https://github.com/google-gemini/gemini-cli/blob/HEAD/scripts/get-release-version.js) handles a key part of this chapter's functionality:
+The `buildSchemaForType` function in [`scripts/generate-settings-schema.ts`](https://github.com/google-gemini/gemini-cli/blob/HEAD/scripts/generate-settings-schema.ts) handles a key part of this chapter's functionality:
-```js
-}
+```ts
+ const schemaShape = definition.ref
+ ? buildRefSchema(definition.ref, defs)
+ : buildSchemaForType(definition, pathSegments, defs);
-function doesVersionExist({ args, version } = {}) {
- // Check NPM
- try {
- const command = `npm view ${args['cli-package-name']}@${version} version 2>/dev/null`;
- const output = execSync(command).toString().trim();
- if (output === version) {
- console.error(`Version ${version} already exists on NPM.`);
- return true;
- }
- } catch (_error) {
- // This is expected if the version doesn't exist.
- }
+ return { ...base, ...schemaShape };
+}
- // Check Git tags
- try {
- const command = `git tag -l 'v${version}'`;
- const tagOutput = execSync(command).toString().trim();
- if (tagOutput === `v${version}`) {
- console.error(`Git tag v${version} already exists.`);
- return true;
- }
- } catch (error) {
- console.error(`Failed to check git tags for conflicts: ${error.message}`);
+function buildCollectionSchema(
+ collection: SettingCollectionDefinition,
+ pathSegments: string[],
+ defs: Map<string, JsonSchema>,
+): JsonSchema {
+ if (collection.ref) {
+ return buildRefSchema(collection.ref, defs);
}
+ return buildSchemaForType(collection, pathSegments, defs);
+}
- // Check GitHub releases
- try {
- const command = `gh release view "v${version}" --json tagName --jq .tagName 2>/dev/null`;
- const output = execSync(command).toString().trim();
- if (output === `v${version}`) {
+function buildSchemaForType(
+ source: SettingDefinition | SettingCollectionDefinition,
+ pathSegments: string[],
+ defs: Map<string, JsonSchema>,
+): JsonSchema {
+ switch (source.type) {
+ case 'boolean':
+ case 'string':
+ case 'number':
+ return { type: source.type };
+ case 'enum':
+ return buildEnumSchema(source.options);
+ case 'array': {
+ const itemPath = [...pathSegments, '<items>'];
```
This function is important because it defines how Gemini CLI Tutorial: Terminal-First Agent Workflows with Google Gemini implements the patterns covered in this chapter.
-### `scripts/get-release-version.js`
-
-The `getAndVerifyTags` function in [`scripts/get-release-version.js`](https://github.com/google-gemini/gemini-cli/blob/HEAD/scripts/get-release-version.js) handles a key part of this chapter's functionality:
-
-```js
-}
-
-function getAndVerifyTags({ npmDistTag, args } = {}) {
- // Detect rollback scenarios and get the correct baseline
- const rollbackInfo = detectRollbackAndGetBaseline({ args, npmDistTag });
- const baselineVersion = rollbackInfo.baseline;
-
- if (!baselineVersion) {
- throw new Error(`Unable to determine baseline version for ${npmDistTag}`);
- }
-
- if (rollbackInfo.isRollback) {
- // Rollback scenario: warn about the rollback but don't fail
- console.error(
- `Rollback detected! NPM ${npmDistTag} tag is ${rollbackInfo.distTagVersion}, but using ${baselineVersion} as baseline for next version calculation (highest existing version).`,
- );
+### `scripts/generate-settings-schema.ts`
+
+The `buildEnumSchema` function in [`scripts/generate-settings-schema.ts`](https://github.com/google-gemini/gemini-cli/blob/HEAD/scripts/generate-settings-schema.ts) handles a key part of this chapter's functionality:
+
+```ts
+ return { type: source.type };
+ case 'enum':
+ return buildEnumSchema(source.options);
+ case 'array': {
+ const itemPath = [...pathSegments, '<items>'];
+ const items = isSettingDefinition(source)
+ ? source.items
+ ? buildCollectionSchema(source.items, itemPath, defs)
+ : {}
+ : source.properties
+ ? buildInlineObjectSchema(source.properties, itemPath, defs)
+ : {};
+ return { type: 'array', items };
+ }
+ case 'object':
+ return isSettingDefinition(source)
+ ? buildObjectDefinitionSchema(source, pathSegments, defs)
+ : buildObjectCollectionSchema(source, pathSegments, defs);
+ default:
+ return {};
}
-
- // Not verifying against git tags or GitHub releases as per user request.
-
- return {
- latestVersion: baselineVersion,
- latestTag: `v${baselineVersion}`,
- };
}
-function getStableBaseVersion(args) {
- let latestStableVersion = args['stable-base-version'];
- if (!latestStableVersion) {
- const { latestVersion } = getAndVerifyTags({
- npmDistTag: TAG_LATEST,
- args,
+function buildEnumSchema(
+ options:
+ | SettingDefinition['options']
+ | SettingCollectionDefinition['options'],
+): JsonSchema {
+ const values = options?.map((option) => option.value) ?? [];
+ const inferred = inferTypeFromValues(values);
+ return {
+ type: inferred ?? undefined,
```
This function is important because it defines how Gemini CLI Tutorial: Terminal-First Agent Workflows with Google Gemini implements the patterns covered in this chapter.
-### `scripts/get-release-version.js`
+### `scripts/generate-settings-schema.ts`
-The `getStableBaseVersion` function in [`scripts/get-release-version.js`](https://github.com/google-gemini/gemini-cli/blob/HEAD/scripts/get-release-version.js) handles a key part of this chapter's functionality:
+The `buildObjectDefinitionSchema` function in [`scripts/generate-settings-schema.ts`](https://github.com/google-gemini/gemini-cli/blob/HEAD/scripts/generate-settings-schema.ts) handles a key part of this chapter's functionality:
-```js
-}
-
-function getStableBaseVersion(args) {
- let latestStableVersion = args['stable-base-version'];
- if (!latestStableVersion) {
- const { latestVersion } = getAndVerifyTags({
- npmDistTag: TAG_LATEST,
- args,
- });
- latestStableVersion = latestVersion;
+```ts
+ case 'object':
+ return isSettingDefinition(source)
+ ? buildObjectDefinitionSchema(source, pathSegments, defs)
+ : buildObjectCollectionSchema(source, pathSegments, defs);
+ default:
+ return {};
}
- return latestStableVersion;
}
-function promoteNightlyVersion({ args } = {}) {
- const latestStableVersion = getStableBaseVersion(args);
-
- const { latestTag: previousNightlyTag } = getAndVerifyTags({
- npmDistTag: TAG_NIGHTLY,
- args,
- });
-
- const major = semver.major(latestStableVersion);
- const minor = semver.minor(latestStableVersion);
- const nextMinor = minor + 2;
- const date = new Date().toISOString().slice(0, 10).replace(/-/g, '');
- const gitShortHash = execSync('git rev-parse --short HEAD').toString().trim();
+function buildEnumSchema(
+ options:
+ | SettingDefinition['options']
+ | SettingCollectionDefinition['options'],
+): JsonSchema {
+ const values = options?.map((option) => option.value) ?? [];
+ const inferred = inferTypeFromValues(values);
return {
- releaseVersion: `${major}.${nextMinor}.0-nightly.${date}.${gitShortHash}`,
- npmTag: TAG_NIGHTLY,
- previousReleaseTag: previousNightlyTag,
+ type: inferred ?? undefined,
+ enum: values,
};
+}
+
+function buildObjectDefinitionSchema(
+ definition: SettingDefinition,
+ pathSegments: string[],
+ defs: Map<string, JsonSchema>,
+): JsonSchema {
+ const properties = definition.properties
+ ? buildObjectProperties(definition.properties, pathSegments, defs)
+ : undefined;
+
+ const schema: JsonSchema = {
```
This function is important because it defines how Gemini CLI Tutorial: Terminal-First Agent Workflows with Google Gemini implements the patterns covered in this chapter.
-### `scripts/get-release-version.js`
+### `scripts/generate-settings-schema.ts`
-The `promoteNightlyVersion` function in [`scripts/get-release-version.js`](https://github.com/google-gemini/gemini-cli/blob/HEAD/scripts/get-release-version.js) handles a key part of this chapter's functionality:
+The `buildObjectCollectionSchema` function in [`scripts/generate-settings-schema.ts`](https://github.com/google-gemini/gemini-cli/blob/HEAD/scripts/generate-settings-schema.ts) handles a key part of this chapter's functionality:
-```js
+```ts
+ return isSettingDefinition(source)
+ ? buildObjectDefinitionSchema(source, pathSegments, defs)
+ : buildObjectCollectionSchema(source, pathSegments, defs);
+ default:
+ return {};
+ }
}
-function promoteNightlyVersion({ args } = {}) {
- const latestStableVersion = getStableBaseVersion(args);
-
- const { latestTag: previousNightlyTag } = getAndVerifyTags({
- npmDistTag: TAG_NIGHTLY,
- args,
- });
-
- const major = semver.major(latestStableVersion);
- const minor = semver.minor(latestStableVersion);
- const nextMinor = minor + 2;
- const date = new Date().toISOString().slice(0, 10).replace(/-/g, '');
- const gitShortHash = execSync('git rev-parse --short HEAD').toString().trim();
+function buildEnumSchema(
+ options:
+ | SettingDefinition['options']
+ | SettingCollectionDefinition['options'],
+): JsonSchema {
+ const values = options?.map((option) => option.value) ?? [];
+ const inferred = inferTypeFromValues(values);
return {
- releaseVersion: `${major}.${nextMinor}.0-nightly.${date}.${gitShortHash}`,
- npmTag: TAG_NIGHTLY,
- previousReleaseTag: previousNightlyTag,
+ type: inferred ?? undefined,
+ enum: values,
};
}
-function getNightlyVersion() {
- const packageJson = readJson('package.json');
- const baseVersion = packageJson.version.split('-')[0];
- const date = new Date().toISOString().slice(0, 10).replace(/-/g, '');
- const gitShortHash = execSync('git rev-parse --short HEAD').toString().trim();
- const releaseVersion = `${baseVersion}-nightly.${date}.${gitShortHash}`;
- const previousReleaseTag = getLatestTag('v*-nightly*');
-
- return {
- releaseVersion,
+function buildObjectDefinitionSchema(
+ definition: SettingDefinition,
+ pathSegments: string[],
+ defs: Map<string, JsonSchema>,
+): JsonSchema {
+ const properties = definition.properties
+ ? buildObjectProperties(definition.properties, pathSegments, defs)
+ : undefined;
+
+ const schema: JsonSchema = {
+ type: 'object',
```
This function is important because it defines how Gemini CLI Tutorial: Terminal-First Agent Workflows with Google Gemini implements the patterns covered in this chapter.
@@ -227,11 +225,11 @@ This function is important because it defines how Gemini CLI Tutorial: Terminal-
```mermaid
flowchart TD
- A[doesVersionExist]
- B[getAndVerifyTags]
- C[getStableBaseVersion]
- D[promoteNightlyVersion]
- E[getNightlyVersion]
+ A[buildSchemaForType]
+ B[buildEnumSchema]
+ C[buildObjectDefinitionSchema]
+ D[buildObjectCollectionSchema]
+ E[buildObjectProperties]
A --> B
B --> C
C --> D
diff --git a/tutorials/gemini-cli-tutorial/05-mcp-extensions-and-skills.md b/tutorials/gemini-cli-tutorial/05-mcp-extensions-and-skills.md
index 2019121f..5bf1fe02 100644
--- a/tutorials/gemini-cli-tutorial/05-mcp-extensions-and-skills.md
+++ b/tutorials/gemini-cli-tutorial/05-mcp-extensions-and-skills.md
@@ -52,17 +52,19 @@ You now have an extensibility model that balances capability and control.
Next: [Chapter 6: Headless Mode and CI Automation](06-headless-mode-and-ci-automation.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `scripts/generate-settings-schema.ts`
-The `generateSettingsSchema` function in [`scripts/generate-settings-schema.ts`](https://github.com/google-gemini/gemini-cli/blob/HEAD/scripts/generate-settings-schema.ts) handles a key part of this chapter's functionality:
+The `GenerateOptions` interface in [`scripts/generate-settings-schema.ts`](https://github.com/google-gemini/gemini-cli/blob/HEAD/scripts/generate-settings-schema.ts) handles a key part of this chapter's functionality:
```ts
}
+interface GenerateOptions {
+ checkOnly: boolean;
+}
+
export async function generateSettingsSchema(
options: GenerateOptions,
): Promise<void> {
@@ -89,133 +91,129 @@ export async function generateSettingsSchema(
}
if (
- existing &&
- normalizeForCompare(existing) === normalizeForCompare(formatted)
- ) {
- if (!options.checkOnly) {
```
-This function is important because it defines how Gemini CLI Tutorial: Terminal-First Agent Workflows with Google Gemini implements the patterns covered in this chapter.
+This interface is important because it defines how Gemini CLI Tutorial: Terminal-First Agent Workflows with Google Gemini implements the patterns covered in this chapter.
-### `scripts/generate-settings-schema.ts`
+### `evals/subagents.eval.ts`
-The `main` function in [`scripts/generate-settings-schema.ts`](https://github.com/google-gemini/gemini-cli/blob/HEAD/scripts/generate-settings-schema.ts) handles a key part of this chapter's functionality:
+The `readProjectFile` function in [`evals/subagents.eval.ts`](https://github.com/google-gemini/gemini-cli/blob/HEAD/evals/subagents.eval.ts) handles a key part of this chapter's functionality:
```ts
-const OUTPUT_RELATIVE_PATH = ['schemas', 'settings.schema.json'];
-const SCHEMA_ID =
- 'https://raw.githubusercontent.com/google-gemini/gemini-cli/main/schemas/settings.schema.json';
-
-type JsonPrimitive = string | number | boolean | null;
-type JsonValue = JsonPrimitive | JsonValue[] | { [key: string]: JsonValue };
-
-interface JsonSchema {
- [key: string]: JsonValue | JsonSchema | JsonSchema[] | undefined;
- $schema?: string;
- $id?: string;
- title?: string;
- description?: string;
- markdownDescription?: string;
- type?: string | string[];
- enum?: JsonPrimitive[];
- default?: JsonValue;
- properties?: Record<string, JsonSchema>;
- items?: JsonSchema;
- additionalProperties?: boolean | JsonSchema;
- required?: string[];
- $ref?: string;
- anyOf?: JsonSchema[];
-}
+);
-interface GenerateOptions {
- checkOnly: boolean;
+function readProjectFile(
+ rig: { testDir: string | null },
+ relativePath: string,
+): string {
+ return fs.readFileSync(path.join(rig.testDir!, relativePath), 'utf8');
}
-export async function generateSettingsSchema(
- options: GenerateOptions,
-): Promise<void> {
+describe('subagent eval test cases', () => {
+ /**
+ * Checks whether the outer agent reliably utilizes an expert subagent to
+ * accomplish a task when one is available.
+ *
+ * Note that the test is intentionally crafted to avoid the word "document"
+ * or "docs". We want to see the outer agent make the connection even when
+ * the prompt indirectly implies need of expertise.
+ *
+ * This tests the system prompt's subagent specific clauses.
+ */
+ evalTest('USUALLY_PASSES', {
+ name: 'should delegate to user provided agent with relevant expertise',
+ params: {
+ settings: {
+ experimental: {
+ enableAgents: true,
+ },
+ },
+ },
+ prompt: 'Please update README.md with a description of this library.',
+ files: {
+ ...TEST_AGENTS.DOCS_AGENT.asFile(),
```
This function is important because it defines how Gemini CLI Tutorial: Terminal-First Agent Workflows with Google Gemini implements the patterns covered in this chapter.
-### `scripts/generate-settings-schema.ts`
+### `scripts/run_regression_check.js`
-The `buildSchemaObject` function in [`scripts/generate-settings-schema.ts`](https://github.com/google-gemini/gemini-cli/blob/HEAD/scripts/generate-settings-schema.ts) handles a key part of this chapter's functionality:
+The `runTests` function in [`scripts/run_regression_check.js`](https://github.com/google-gemini/gemini-cli/blob/HEAD/scripts/run_regression_check.js) handles a key part of this chapter's functionality:
-```ts
- await mkdir(path.dirname(outputPath), { recursive: true });
+```js
+ * Runs a set of tests using Vitest and returns the results.
+ */
+function runTests(files, pattern, model) {
+ const outputDir = path.resolve(
+ process.cwd(),
+ `evals/logs/pr-run-${Date.now()}`,
+ );
+ fs.mkdirSync(outputDir, { recursive: true });
- const schemaObject = buildSchemaObject(getSettingsSchema());
- const formatted = await formatWithPrettier(
- JSON.stringify(schemaObject, null, 2),
- outputPath,
+ const filesToRun = files || 'evals/';
+ console.log(
+ `🚀 Running tests in ${filesToRun} with pattern: ${pattern?.slice(0, 100)}...`,
);
- let existing: string | undefined;
try {
- existing = await readFile(outputPath, 'utf8');
- } catch (error) {
- if ((error as NodeJS.ErrnoException).code !== 'ENOENT') {
- throw error;
- }
+ const cmd = `npx vitest run --config evals/vitest.config.ts ${filesToRun} -t "${pattern}" --reporter=json --reporter=default --outputFile="${path.join(outputDir, 'report.json')}"`;
+ execSync(cmd, {
+ stdio: 'inherit',
+ env: { ...process.env, RUN_EVALS: '1', GEMINI_MODEL: model },
+ });
+ } catch {
+ // Vitest returns a non-zero exit code when tests fail. This is expected.
+ // We continue execution and handle the failures by parsing the JSON report.
}
- if (
- existing &&
- normalizeForCompare(existing) === normalizeForCompare(formatted)
- ) {
- if (!options.checkOnly) {
- console.log('Settings JSON schema already up to date.');
- }
- return;
- }
+ const reportPath = path.join(outputDir, 'report.json');
+ return fs.existsSync(reportPath)
+ ? JSON.parse(fs.readFileSync(reportPath, 'utf-8'))
+ : null;
+}
- if (options.checkOnly) {
- console.error(
- 'Settings JSON schema is out of date. Run `npm run schema:settings` to regenerate.',
- );
- process.exitCode = 1;
+/**
```
This function is important because it defines how Gemini CLI Tutorial: Terminal-First Agent Workflows with Google Gemini implements the patterns covered in this chapter.
-### `scripts/generate-settings-schema.ts`
-
-The `buildSettingSchema` function in [`scripts/generate-settings-schema.ts`](https://github.com/google-gemini/gemini-cli/blob/HEAD/scripts/generate-settings-schema.ts) handles a key part of this chapter's functionality:
-
-```ts
+### `scripts/run_regression_check.js`
- for (const [key, definition] of Object.entries(schema)) {
- root.properties![key] = buildSettingSchema(definition, [key], defs);
- }
+The `findAssertion` function in [`scripts/run_regression_check.js`](https://github.com/google-gemini/gemini-cli/blob/HEAD/scripts/run_regression_check.js) handles a key part of this chapter's functionality:
- if (defs.size > 0) {
- root.$defs = Object.fromEntries(defs.entries());
+```js
+ * Helper to find a specific assertion by name across all test files.
+ */
+function findAssertion(report, testName) {
+ if (!report?.testResults) return null;
+ for (const fileResult of report.testResults) {
+ const assertion = fileResult.assertionResults.find(
+ (a) => a.title === testName,
+ );
+ if (assertion) return assertion;
}
-
- return root;
+ return null;
}
-function buildSettingSchema(
- definition: SettingDefinition,
- pathSegments: string[],
- defs: Map<string, JsonSchema>,
-): JsonSchema {
- const base: JsonSchema = {
- title: definition.label,
- description: definition.description,
- markdownDescription: buildMarkdownDescription(definition),
- };
-
- if (definition.default !== undefined) {
- base.default = definition.default as JsonValue;
+/**
+ * Parses command line arguments to identify model, files, and test pattern.
+ */
+function parseArgs() {
+ const modelArg = process.argv[2];
+ const remainingArgs = process.argv.slice(3);
+ const fullArgsString = remainingArgs.join(' ');
+ const testPatternIndex = remainingArgs.indexOf('--test-pattern');
+
+ if (testPatternIndex !== -1) {
+ return {
+ model: modelArg,
+ files: remainingArgs.slice(0, testPatternIndex).join(' '),
+ pattern: remainingArgs.slice(testPatternIndex + 1).join(' '),
+ };
}
- const schemaShape = definition.ref
- ? buildRefSchema(definition.ref, defs)
- : buildSchemaForType(definition, pathSegments, defs);
-
- return { ...base, ...schemaShape };
+ if (fullArgsString.includes('--test-pattern')) {
+ const parts = fullArgsString.split('--test-pattern');
```
This function is important because it defines how Gemini CLI Tutorial: Terminal-First Agent Workflows with Google Gemini implements the patterns covered in this chapter.
@@ -225,11 +223,11 @@ This function is important because it defines how Gemini CLI Tutorial: Terminal-
```mermaid
flowchart TD
- A[generateSettingsSchema]
- B[main]
- C[buildSchemaObject]
- D[buildSettingSchema]
- E[buildCollectionSchema]
+ A[GenerateOptions]
+ B[readProjectFile]
+ C[runTests]
+ D[findAssertion]
+ E[parseArgs]
A --> B
B --> C
C --> D
diff --git a/tutorials/gemini-cli-tutorial/06-headless-mode-and-ci-automation.md b/tutorials/gemini-cli-tutorial/06-headless-mode-and-ci-automation.md
index 037b1158..6b268d60 100644
--- a/tutorials/gemini-cli-tutorial/06-headless-mode-and-ci-automation.md
+++ b/tutorials/gemini-cli-tutorial/06-headless-mode-and-ci-automation.md
@@ -58,170 +58,168 @@ You now have practical patterns for scriptable and CI-safe Gemini CLI execution.
Next: [Chapter 7: Sandboxing, Security, and Troubleshooting](07-sandboxing-security-and-troubleshooting.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `scripts/generate-settings-schema.ts`
-
-The `buildRefSchema` function in [`scripts/generate-settings-schema.ts`](https://github.com/google-gemini/gemini-cli/blob/HEAD/scripts/generate-settings-schema.ts) handles a key part of this chapter's functionality:
-
-```ts
+### `scripts/aggregate_evals.js`
- const schemaShape = definition.ref
- ? buildRefSchema(definition.ref, defs)
- : buildSchemaForType(definition, pathSegments, defs);
+The `getStats` function in [`scripts/aggregate_evals.js`](https://github.com/google-gemini/gemini-cli/blob/HEAD/scripts/aggregate_evals.js) handles a key part of this chapter's functionality:
- return { ...base, ...schemaShape };
+```js
}
-function buildCollectionSchema(
- collection: SettingCollectionDefinition,
- pathSegments: string[],
- defs: Map<string, JsonSchema>,
-): JsonSchema {
- if (collection.ref) {
- return buildRefSchema(collection.ref, defs);
- }
- return buildSchemaForType(collection, pathSegments, defs);
-}
-
-function buildSchemaForType(
- source: SettingDefinition | SettingCollectionDefinition,
- pathSegments: string[],
- defs: Map<string, JsonSchema>,
-): JsonSchema {
- switch (source.type) {
- case 'boolean':
- case 'string':
- case 'number':
- return { type: source.type };
- case 'enum':
- return buildEnumSchema(source.options);
- case 'array': {
+function getStats(reports) {
+ // Structure: { [model]: { [testName]: { passed, failed, total } } }
+ const statsByModel = {};
+
+ for (const reportPath of reports) {
+ try {
+ const model = getModelFromPath(reportPath);
+ if (!statsByModel[model]) {
+ statsByModel[model] = {};
+ }
+ const testStats = statsByModel[model];
+
+ const content = fs.readFileSync(reportPath, 'utf-8');
+ const json = JSON.parse(content);
+
+ for (const testResult of json.testResults) {
+ for (const assertion of testResult.assertionResults) {
+ const name = assertion.title;
+ if (!testStats[name]) {
+ testStats[name] = { passed: 0, failed: 0, total: 0 };
+ }
+ testStats[name].total++;
+ if (assertion.status === 'passed') {
+ testStats[name].passed++;
+ } else {
+ testStats[name].failed++;
+ }
+ }
+ }
+ } catch (error) {
```
This function is important because it defines how Gemini CLI Tutorial: Terminal-First Agent Workflows with Google Gemini implements the patterns covered in this chapter.
-### `scripts/generate-settings-schema.ts`
-
-The `isSettingDefinition` function in [`scripts/generate-settings-schema.ts`](https://github.com/google-gemini/gemini-cli/blob/HEAD/scripts/generate-settings-schema.ts) handles a key part of this chapter's functionality:
-
-```ts
- case 'array': {
- const itemPath = [...pathSegments, '<items>'];
- const items = isSettingDefinition(source)
- ? source.items
- ? buildCollectionSchema(source.items, itemPath, defs)
- : {}
- : source.properties
- ? buildInlineObjectSchema(source.properties, itemPath, defs)
- : {};
- return { type: 'array', items };
- }
- case 'object':
- return isSettingDefinition(source)
- ? buildObjectDefinitionSchema(source, pathSegments, defs)
- : buildObjectCollectionSchema(source, pathSegments, defs);
- default:
- return {};
- }
-}
+### `scripts/aggregate_evals.js`
-function buildEnumSchema(
- options:
- | SettingDefinition['options']
- | SettingCollectionDefinition['options'],
-): JsonSchema {
- const values = options?.map((option) => option.value) ?? [];
- const inferred = inferTypeFromValues(values);
- return {
- type: inferred ?? undefined,
- enum: values,
- };
+The `fetchHistoricalData` function in [`scripts/aggregate_evals.js`](https://github.com/google-gemini/gemini-cli/blob/HEAD/scripts/aggregate_evals.js) handles a key part of this chapter's functionality:
+
+```js
}
-```
-This function is important because it defines how Gemini CLI Tutorial: Terminal-First Agent Workflows with Google Gemini implements the patterns covered in this chapter.
+function fetchHistoricalData() {
+ const history = [];
-### `scripts/generate-settings-schema.ts`
+ try {
+ // Determine branch
+ const branch = 'main';
-The `buildMarkdownDescription` function in [`scripts/generate-settings-schema.ts`](https://github.com/google-gemini/gemini-cli/blob/HEAD/scripts/generate-settings-schema.ts) handles a key part of this chapter's functionality:
+ // Get recent runs
+ const cmd = `gh run list --workflow evals-nightly.yml --branch "${branch}" --limit ${
+ MAX_HISTORY + 5
+ } --json databaseId,createdAt,url,displayTitle,status,conclusion`;
+ const runsJson = execSync(cmd, { encoding: 'utf-8' });
+ let runs = JSON.parse(runsJson);
-```ts
- title: definition.label,
- description: definition.description,
- markdownDescription: buildMarkdownDescription(definition),
- };
+ // Filter out current run
+ const currentRunId = process.env.GITHUB_RUN_ID;
+ if (currentRunId) {
+ runs = runs.filter((r) => r.databaseId.toString() !== currentRunId);
+ }
- if (definition.default !== undefined) {
- base.default = definition.default as JsonValue;
- }
+ // Filter for runs that likely have artifacts (completed) and take top N
+ // We accept 'failure' too because we want to see stats.
+ runs = runs.filter((r) => r.status === 'completed').slice(0, MAX_HISTORY);
+
+ // Fetch artifacts for each run
+ for (const run of runs) {
+ const tmpDir = fs.mkdtempSync(
+ path.join(os.tmpdir(), `gemini-evals-${run.databaseId}-`),
+ );
+ try {
+```
- const schemaShape = definition.ref
- ? buildRefSchema(definition.ref, defs)
- : buildSchemaForType(definition, pathSegments, defs);
+This function is important because it defines how Gemini CLI Tutorial: Terminal-First Agent Workflows with Google Gemini implements the patterns covered in this chapter.
- return { ...base, ...schemaShape };
-}
+### `scripts/aggregate_evals.js`
-function buildCollectionSchema(
- collection: SettingCollectionDefinition,
- pathSegments: string[],
- defs: Map<string, JsonSchema>,
-): JsonSchema {
- if (collection.ref) {
- return buildRefSchema(collection.ref, defs);
- }
- return buildSchemaForType(collection, pathSegments, defs);
+The `generateMarkdown` function in [`scripts/aggregate_evals.js`](https://github.com/google-gemini/gemini-cli/blob/HEAD/scripts/aggregate_evals.js) handles a key part of this chapter's functionality:
+
+```js
}
-function buildSchemaForType(
- source: SettingDefinition | SettingCollectionDefinition,
- pathSegments: string[],
- defs: Map<string, JsonSchema>,
-): JsonSchema {
+function generateMarkdown(currentStatsByModel, history) {
+ console.log('### Evals Nightly Summary\n');
+ console.log(
+ 'See [evals/README.md](https://github.com/google-gemini/gemini-cli/tree/main/evals) for more details.\n',
+ );
+
+ // Reverse history to show oldest first
+ const reversedHistory = [...history].reverse();
+
+ const models = Object.keys(currentStatsByModel).sort();
+
+ const getPassRate = (statsForModel) => {
+ if (!statsForModel) return '-';
+ const totalStats = Object.values(statsForModel).reduce(
+ (acc, stats) => {
+ acc.passed += stats.passed;
+ acc.total += stats.total;
+ return acc;
+ },
+ { passed: 0, total: 0 },
+ );
+ return totalStats.total > 0
+ ? ((totalStats.passed / totalStats.total) * 100).toFixed(1) + '%'
+ : '-';
+ };
+
+ for (const model of models) {
+ const currentStats = currentStatsByModel[model];
+ const totalPassRate = getPassRate(currentStats);
+
```
This function is important because it defines how Gemini CLI Tutorial: Terminal-First Agent Workflows with Google Gemini implements the patterns covered in this chapter.
-### `scripts/generate-settings-schema.ts`
+### `scripts/sync_project_dry_run.js`
-The `inferTypeFromValues` function in [`scripts/generate-settings-schema.ts`](https://github.com/google-gemini/gemini-cli/blob/HEAD/scripts/generate-settings-schema.ts) handles a key part of this chapter's functionality:
+The `runCommand` function in [`scripts/sync_project_dry_run.js`](https://github.com/google-gemini/gemini-cli/blob/HEAD/scripts/sync_project_dry_run.js) handles a key part of this chapter's functionality:
-```ts
-): JsonSchema {
- const values = options?.map((option) => option.value) ?? [];
- const inferred = inferTypeFromValues(values);
- return {
- type: inferred ?? undefined,
- enum: values,
- };
-}
+```js
+const FORCE_INCLUDE_LABELS = ['🔒 maintainer only'];
-function buildObjectDefinitionSchema(
- definition: SettingDefinition,
- pathSegments: string[],
- defs: Map<string, JsonSchema>,
-): JsonSchema {
- const properties = definition.properties
- ? buildObjectProperties(definition.properties, pathSegments, defs)
- : undefined;
-
- const schema: JsonSchema = {
- type: 'object',
- };
+function runCommand(command) {
+ try {
+ return execSync(command, {
+ encoding: 'utf8',
+ stdio: ['ignore', 'pipe', 'ignore'],
+ maxBuffer: 10 * 1024 * 1024,
+ });
+ } catch {
+ return null;
+ }
+}
- if (properties && Object.keys(properties).length > 0) {
- schema.properties = properties;
+function getIssues(repo) {
+ console.log(`Fetching open issues from ${repo}...`);
+ const json = runCommand(
+ `gh issue list --repo ${repo} --state open --limit 3000 --json number,title,url,labels`,
+ );
+ if (!json) {
+ return [];
}
+ return JSON.parse(json);
+}
- if (definition.additionalProperties) {
- schema.additionalProperties = buildCollectionSchema(
- definition.additionalProperties,
- [...pathSegments, '<additionalProperties>'],
- defs,
- );
+function getIssueBody(repo, number) {
+ const json = runCommand(
+ `gh issue view ${number} --repo ${repo} --json body,title,url,number`,
+ );
+ if (!json) {
+ return null;
+ }
```
This function is important because it defines how Gemini CLI Tutorial: Terminal-First Agent Workflows with Google Gemini implements the patterns covered in this chapter.
@@ -231,11 +229,11 @@ This function is important because it defines how Gemini CLI Tutorial: Terminal-
```mermaid
flowchart TD
- A[buildRefSchema]
- B[isSettingDefinition]
- C[buildMarkdownDescription]
- D[inferTypeFromValues]
- E[ensureDefinition]
+ A[getStats]
+ B[fetchHistoricalData]
+ C[generateMarkdown]
+ D[runCommand]
+ E[getIssues]
A --> B
B --> C
C --> D
diff --git a/tutorials/gemini-cli-tutorial/07-sandboxing-security-and-troubleshooting.md b/tutorials/gemini-cli-tutorial/07-sandboxing-security-and-troubleshooting.md
index 2c2d84e8..1099201d 100644
--- a/tutorials/gemini-cli-tutorial/07-sandboxing-security-and-troubleshooting.md
+++ b/tutorials/gemini-cli-tutorial/07-sandboxing-security-and-troubleshooting.md
@@ -53,170 +53,168 @@ You now have a reliability and risk-control playbook for Gemini CLI operations.
Next: [Chapter 8: Contribution Workflow and Enterprise Operations](08-contribution-workflow-and-enterprise-operations.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `scripts/generate-settings-doc.ts`
-
-The `collectEntries` function in [`scripts/generate-settings-doc.ts`](https://github.com/google-gemini/gemini-cli/blob/HEAD/scripts/generate-settings-doc.ts) handles a key part of this chapter's functionality:
-
-```ts
- const { getSettingsSchema } = await loadSettingsSchemaModule();
- const schema = getSettingsSchema();
- const allSettingsSections = collectEntries(schema, { includeAll: true });
- const filteredSettingsSections = collectEntries(schema, {
- includeAll: false,
- });
-
- const generatedBlock = renderSections(allSettingsSections);
- const generatedTableBlock = renderTableSections(filteredSettingsSections);
-
- await updateFile(docPath, generatedBlock, checkOnly);
- await updateFile(cliSettingsDocPath, generatedTableBlock, checkOnly);
+### `scripts/lint.js`
+
+The `runCommand` function in [`scripts/lint.js`](https://github.com/google-gemini/gemini-cli/blob/HEAD/scripts/lint.js) handles a key part of this chapter's functionality:
+
+```js
+};
+
+function runCommand(command, stdio = 'inherit') {
+ try {
+ const env = { ...process.env };
+ const nodeBin = join(process.cwd(), 'node_modules', '.bin');
+ const sep = isWindows ? ';' : ':';
+ const pythonBin = isWindows
+ ? join(PYTHON_VENV_PATH, 'Scripts')
+ : join(PYTHON_VENV_PATH, 'bin');
+ // Windows sometimes uses 'Path' instead of 'PATH'
+ const pathKey = 'Path' in env ? 'Path' : 'PATH';
+ env[pathKey] = [
+ nodeBin,
+ join(TEMP_DIR, 'actionlint'),
+ join(TEMP_DIR, 'shellcheck'),
+ pythonBin,
+ env[pathKey],
+ ].join(sep);
+ execSync(command, { stdio, env, shell: true });
+ return true;
+ } catch {
+ return false;
+ }
}
-async function updateFile(
- filePath: string,
- newContent: string,
- checkOnly: boolean,
-) {
- const doc = await readFile(filePath, 'utf8');
- const injectedDoc = injectBetweenMarkers({
- document: doc,
- startMarker: START_MARKER,
- endMarker: END_MARKER,
- newContent: newContent,
- paddingBefore: '\n',
- paddingAfter: '\n',
- });
- const formattedDoc = await formatWithPrettier(injectedDoc, filePath);
-
- if (normalizeForCompare(doc) === normalizeForCompare(formattedDoc)) {
- if (!checkOnly) {
+export function setupLinters() {
+ console.log('Setting up linters...');
+ if (!process.env.GEMINI_LINT_TEMP_DIR) {
+ rmSync(TEMP_DIR, { recursive: true, force: true });
+ }
+ mkdirSync(TEMP_DIR, { recursive: true });
```
This function is important because it defines how Gemini CLI Tutorial: Terminal-First Agent Workflows with Google Gemini implements the patterns covered in this chapter.
-### `scripts/generate-settings-doc.ts`
-
-The `formatDescription` function in [`scripts/generate-settings-doc.ts`](https://github.com/google-gemini/gemini-cli/blob/HEAD/scripts/generate-settings-doc.ts) handles a key part of this chapter's functionality:
-
-```ts
- label: definition.label,
- category: definition.category,
- description: formatDescription(definition),
- defaultValue: formatDefaultValue(definition.default, {
- quoteStrings: true,
- }),
- requiresRestart: Boolean(definition.requiresRestart),
- enumValues: definition.options?.map((option) =>
- formatDefaultValue(option.value, { quoteStrings: true }),
- ),
- });
- }
+### `scripts/lint.js`
- if (hasChildren && definition.properties) {
- visit(definition.properties, newPathSegments, sectionKey);
+The `setupLinters` function in [`scripts/lint.js`](https://github.com/google-gemini/gemini-cli/blob/HEAD/scripts/lint.js) handles a key part of this chapter's functionality:
+
+```js
+}
+
+export function setupLinters() {
+ console.log('Setting up linters...');
+ if (!process.env.GEMINI_LINT_TEMP_DIR) {
+ rmSync(TEMP_DIR, { recursive: true, force: true });
+ }
+ mkdirSync(TEMP_DIR, { recursive: true });
+
+ for (const linter in LINTERS) {
+ const { check, installer } = LINTERS[linter];
+ if (!runCommand(check, 'ignore')) {
+ console.log(`Installing ${linter}...`);
+ if (!runCommand(installer)) {
+ console.error(
+ `Failed to install ${linter}. Please install it manually.`,
+ );
+ process.exit(1);
}
}
- };
-
- visit(schema, []);
- return sections;
+ }
+ console.log('All required linters are available.');
}
-function formatDescription(definition: SettingDefinition) {
- if (definition.description?.trim()) {
- return definition.description.trim();
+export function runESLint() {
+ console.log('\nRunning ESLint...');
+ if (!runCommand('npm run lint')) {
+ process.exit(1);
}
- return 'Description not provided.';
}
-function formatType(definition: SettingDefinition): string {
- switch (definition.ref) {
+export function runActionlint() {
```
This function is important because it defines how Gemini CLI Tutorial: Terminal-First Agent Workflows with Google Gemini implements the patterns covered in this chapter.
-### `scripts/generate-settings-doc.ts`
-
-The `formatType` function in [`scripts/generate-settings-doc.ts`](https://github.com/google-gemini/gemini-cli/blob/HEAD/scripts/generate-settings-doc.ts) handles a key part of this chapter's functionality:
-
-```ts
- sections.get(sectionKey)!.push({
- path: newPathSegments.join('.'),
- type: formatType(definition),
- label: definition.label,
- category: definition.category,
- description: formatDescription(definition),
- defaultValue: formatDefaultValue(definition.default, {
- quoteStrings: true,
- }),
- requiresRestart: Boolean(definition.requiresRestart),
- enumValues: definition.options?.map((option) =>
- formatDefaultValue(option.value, { quoteStrings: true }),
- ),
- });
- }
+### `scripts/lint.js`
- if (hasChildren && definition.properties) {
- visit(definition.properties, newPathSegments, sectionKey);
- }
- }
- };
+The `runESLint` function in [`scripts/lint.js`](https://github.com/google-gemini/gemini-cli/blob/HEAD/scripts/lint.js) handles a key part of this chapter's functionality:
- visit(schema, []);
- return sections;
+```js
}
-function formatDescription(definition: SettingDefinition) {
- if (definition.description?.trim()) {
- return definition.description.trim();
+export function runESLint() {
+ console.log('\nRunning ESLint...');
+ if (!runCommand('npm run lint')) {
+ process.exit(1);
}
- return 'Description not provided.';
}
+
+export function runActionlint() {
+ console.log('\nRunning actionlint...');
+ if (!runCommand(LINTERS.actionlint.run)) {
+ process.exit(1);
+ }
+}
+
+export function runShellcheck() {
+ console.log('\nRunning shellcheck...');
+ if (!runCommand(LINTERS.shellcheck.run)) {
+ process.exit(1);
+ }
+}
+
+export function runYamllint() {
+ console.log('\nRunning yamllint...');
+ if (!runCommand(LINTERS.yamllint.run)) {
+ process.exit(1);
+ }
+}
+
+export function runPrettier() {
+ console.log('\nRunning Prettier...');
```
This function is important because it defines how Gemini CLI Tutorial: Terminal-First Agent Workflows with Google Gemini implements the patterns covered in this chapter.
-### `scripts/generate-settings-doc.ts`
+### `scripts/lint.js`
+
+The `runActionlint` function in [`scripts/lint.js`](https://github.com/google-gemini/gemini-cli/blob/HEAD/scripts/lint.js) handles a key part of this chapter's functionality:
-The `renderSections` function in [`scripts/generate-settings-doc.ts`](https://github.com/google-gemini/gemini-cli/blob/HEAD/scripts/generate-settings-doc.ts) handles a key part of this chapter's functionality:
+```js
+}
-```ts
- });
+export function runActionlint() {
+ console.log('\nRunning actionlint...');
+ if (!runCommand(LINTERS.actionlint.run)) {
+ process.exit(1);
+ }
+}
- const generatedBlock = renderSections(allSettingsSections);
- const generatedTableBlock = renderTableSections(filteredSettingsSections);
+export function runShellcheck() {
+ console.log('\nRunning shellcheck...');
+ if (!runCommand(LINTERS.shellcheck.run)) {
+ process.exit(1);
+ }
+}
- await updateFile(docPath, generatedBlock, checkOnly);
- await updateFile(cliSettingsDocPath, generatedTableBlock, checkOnly);
+export function runYamllint() {
+ console.log('\nRunning yamllint...');
+ if (!runCommand(LINTERS.yamllint.run)) {
+ process.exit(1);
+ }
}
-async function updateFile(
- filePath: string,
- newContent: string,
- checkOnly: boolean,
-) {
- const doc = await readFile(filePath, 'utf8');
- const injectedDoc = injectBetweenMarkers({
- document: doc,
- startMarker: START_MARKER,
- endMarker: END_MARKER,
- newContent: newContent,
- paddingBefore: '\n',
- paddingAfter: '\n',
- });
- const formattedDoc = await formatWithPrettier(injectedDoc, filePath);
-
- if (normalizeForCompare(doc) === normalizeForCompare(formattedDoc)) {
- if (!checkOnly) {
- console.log(
- `Settings documentation (${path.basename(filePath)}) already up to date.`,
- );
- }
- return;
+export function runPrettier() {
+ console.log('\nRunning Prettier...');
+ if (!runCommand('prettier --check .')) {
+ console.log(
+ 'Prettier check failed. Please run "npm run format" to fix formatting issues.',
+ );
+ process.exit(1);
+ }
+}
```
This function is important because it defines how Gemini CLI Tutorial: Terminal-First Agent Workflows with Google Gemini implements the patterns covered in this chapter.
@@ -226,11 +224,11 @@ This function is important because it defines how Gemini CLI Tutorial: Terminal-
```mermaid
flowchart TD
- A[collectEntries]
- B[formatDescription]
- C[formatType]
- D[renderSections]
- E[renderTableSections]
+ A[runCommand]
+ B[setupLinters]
+ C[runESLint]
+ D[runActionlint]
+ E[runShellcheck]
A --> B
B --> C
C --> D
diff --git a/tutorials/gemini-cli-tutorial/08-contribution-workflow-and-enterprise-operations.md b/tutorials/gemini-cli-tutorial/08-contribution-workflow-and-enterprise-operations.md
index 961561f1..0577831f 100644
--- a/tutorials/gemini-cli-tutorial/08-contribution-workflow-and-enterprise-operations.md
+++ b/tutorials/gemini-cli-tutorial/08-contribution-workflow-and-enterprise-operations.md
@@ -49,170 +49,168 @@ Next steps:
- run pilot automation in headless mode with strict output contracts
- contribute one focused improvement with tests and docs
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `scripts/sync_project_dry_run.js`
+### `scripts/lint.js`
-The `runCommand` function in [`scripts/sync_project_dry_run.js`](https://github.com/google-gemini/gemini-cli/blob/HEAD/scripts/sync_project_dry_run.js) handles a key part of this chapter's functionality:
+The `main` function in [`scripts/lint.js`](https://github.com/google-gemini/gemini-cli/blob/HEAD/scripts/lint.js) handles a key part of this chapter's functionality:
```js
-const FORCE_INCLUDE_LABELS = ['🔒 maintainer only'];
-
-function runCommand(command) {
- try {
- return execSync(command, {
- encoding: 'utf8',
- stdio: ['ignore', 'pipe', 'ignore'],
- maxBuffer: 10 * 1024 * 1024,
- });
- } catch (_e) {
- return null;
- }
-}
-function getIssues(repo) {
- console.log(`Fetching open issues from ${repo}...`);
- const json = runCommand(
- `gh issue list --repo ${repo} --state open --limit 3000 --json number,title,url,labels`,
- );
- if (!json) {
- return [];
+ function getChangedFiles() {
+ const baseRef = process.env.GITHUB_BASE_REF || 'main';
+ try {
+ execSync(`git fetch origin ${baseRef}`);
+ const mergeBase = execSync(`git merge-base HEAD origin/${baseRef}`)
+ .toString()
+ .trim();
+ return execSync(`git diff --name-only ${mergeBase}..HEAD`)
+ .toString()
+ .trim()
+ .split('\n')
+ .filter(Boolean);
+ } catch {
+ console.error(`Could not get changed files against origin/${baseRef}.`);
+ try {
+ console.log('Falling back to diff against HEAD~1');
+ return execSync(`git diff --name-only HEAD~1..HEAD`)
+ .toString()
+ .trim()
+ .split('\n')
+ .filter(Boolean);
+ } catch {
+ console.error('Could not get changed files against HEAD~1 either.');
+ process.exit(1);
+ }
+ }
}
- return JSON.parse(json);
-}
-function getIssueBody(repo, number) {
- const json = runCommand(
- `gh issue view ${number} --repo ${repo} --json body,title,url,number`,
- );
- if (!json) {
- return null;
- }
+ const changedFiles = getChangedFiles();
+ let violationsFound = false;
+
```
This function is important because it defines how Gemini CLI Tutorial: Terminal-First Agent Workflows with Google Gemini implements the patterns covered in this chapter.
-### `scripts/sync_project_dry_run.js`
+### `evals/tool_output_masking.eval.ts`
-The `getIssues` function in [`scripts/sync_project_dry_run.js`](https://github.com/google-gemini/gemini-cli/blob/HEAD/scripts/sync_project_dry_run.js) handles a key part of this chapter's functionality:
+The `findDir` function in [`evals/tool_output_masking.eval.ts`](https://github.com/google-gemini/gemini-cli/blob/HEAD/evals/tool_output_masking.eval.ts) handles a key part of this chapter's functionality:
-```js
-}
-
-function getIssues(repo) {
- console.log(`Fetching open issues from ${repo}...`);
- const json = runCommand(
- `gh issue list --repo ${repo} --state open --limit 3000 --json number,title,url,labels`,
- );
- if (!json) {
- return [];
- }
- return JSON.parse(json);
-}
+```ts
-function getIssueBody(repo, number) {
- const json = runCommand(
- `gh issue view ${number} --repo ${repo} --json body,title,url,number`,
- );
- if (!json) {
- return null;
+// Recursive function to find a directory by name
+function findDir(base: string, name: string): string | null {
+ if (!fs.existsSync(base)) return null;
+ const files = fs.readdirSync(base);
+ for (const file of files) {
+ const fullPath = path.join(base, file);
+ if (fs.statSync(fullPath).isDirectory()) {
+ if (file === name) return fullPath;
+ const found = findDir(fullPath, name);
+ if (found) return found;
+ }
}
- return JSON.parse(json);
+ return null;
}
-function getProjectItems() {
- console.log(`Fetching items from Project ${PROJECT_ID}...`);
- const json = runCommand(
- `gh project item-list ${PROJECT_ID} --owner ${ORG} --format json --limit 3000`,
- );
- if (!json) {
- return [];
- }
- return JSON.parse(json).items;
+describe('Tool Output Masking Behavioral Evals', () => {
+ /**
+ * Scenario: The agent needs information that was masked in a previous turn.
+ * It should recognize the <tool_output_masked> tag and use a tool to read the file.
+ */
+ evalTest('USUALLY_PASSES', {
+ name: 'should attempt to read the redirected full output file when information is masked',
+ params: {
+ security: {
+ folderTrust: {
+ enabled: true,
+ },
+ },
+ },
+ prompt: '/help',
+ assert: async (rig) => {
```
This function is important because it defines how Gemini CLI Tutorial: Terminal-First Agent Workflows with Google Gemini implements the patterns covered in this chapter.
-### `scripts/sync_project_dry_run.js`
+### `scripts/local_telemetry.js`
-The `getIssueBody` function in [`scripts/sync_project_dry_run.js`](https://github.com/google-gemini/gemini-cli/blob/HEAD/scripts/sync_project_dry_run.js) handles a key part of this chapter's functionality:
+The `main` function in [`scripts/local_telemetry.js`](https://github.com/google-gemini/gemini-cli/blob/HEAD/scripts/local_telemetry.js) handles a key part of this chapter's functionality:
```js
-}
-
-function getIssueBody(repo, number) {
- const json = runCommand(
- `gh issue view ${number} --repo ${repo} --json body,title,url,number`,
- );
- if (!json) {
+`;
+
+async function main() {
+ // 1. Ensure binaries are available, downloading if necessary.
+ // Binaries are stored in the project's .gemini/otel/bin directory
+ // to avoid modifying the user's system.
+ if (!fileExists(BIN_DIR)) fs.mkdirSync(BIN_DIR, { recursive: true });
+
+ const otelcolPath = await ensureBinary(
+ 'otelcol-contrib',
+ 'open-telemetry/opentelemetry-collector-releases',
+ (version, platform, arch, ext) =>
+ `otelcol-contrib_${version}_${platform}_${arch}.${ext}`,
+ 'otelcol-contrib',
+ false, // isJaeger = false
+ ).catch((e) => {
+ console.error(`🛑 Error getting otelcol-contrib: ${e.message}`);
return null;
- }
- return JSON.parse(json);
-}
-
-function getProjectItems() {
- console.log(`Fetching items from Project ${PROJECT_ID}...`);
- const json = runCommand(
- `gh project item-list ${PROJECT_ID} --owner ${ORG} --format json --limit 3000`,
- );
- if (!json) {
- return [];
- }
- return JSON.parse(json).items;
-}
-
-function shouldInclude(issue) {
- const labels = issue.labels.map((l) => l.name);
-
- // Check Force Include first
- if (labels.some((l) => FORCE_INCLUDE_LABELS.includes(l))) {
- return true;
- }
-
- // Check Exclude
+ });
+ if (!otelcolPath) process.exit(1);
+
+ const jaegerPath = await ensureBinary(
+ 'jaeger',
+ 'jaegertracing/jaeger',
+ (version, platform, arch, ext) =>
+ `jaeger-${version}-${platform}-${arch}.${ext}`,
+ 'jaeger',
+ true, // isJaeger = true
+ ).catch((e) => {
+ console.error(`🛑 Error getting jaeger: ${e.message}`);
+ return null;
+ });
```
This function is important because it defines how Gemini CLI Tutorial: Terminal-First Agent Workflows with Google Gemini implements the patterns covered in this chapter.
-### `scripts/sync_project_dry_run.js`
+### `scripts/generate-settings-doc.ts`
-The `getProjectItems` function in [`scripts/sync_project_dry_run.js`](https://github.com/google-gemini/gemini-cli/blob/HEAD/scripts/sync_project_dry_run.js) handles a key part of this chapter's functionality:
+The `main` function in [`scripts/generate-settings-doc.ts`](https://github.com/google-gemini/gemini-cli/blob/HEAD/scripts/generate-settings-doc.ts) handles a key part of this chapter's functionality:
-```js
+```ts
}
-function getProjectItems() {
- console.log(`Fetching items from Project ${PROJECT_ID}...`);
- const json = runCommand(
- `gh project item-list ${PROJECT_ID} --owner ${ORG} --format json --limit 3000`,
- );
- if (!json) {
- return [];
- }
- return JSON.parse(json).items;
-}
+export async function main(argv = process.argv.slice(2)) {
+ const checkOnly = argv.includes('--check');
-function shouldInclude(issue) {
- const labels = issue.labels.map((l) => l.name);
+ await generateSettingsSchema({ checkOnly });
- // Check Force Include first
- if (labels.some((l) => FORCE_INCLUDE_LABELS.includes(l))) {
- return true;
- }
+ const repoRoot = path.resolve(
+ path.dirname(fileURLToPath(import.meta.url)),
+ '..',
+ );
+ const docPath = path.join(repoRoot, 'docs/reference/configuration.md');
+ const cliSettingsDocPath = path.join(repoRoot, 'docs/cli/settings.md');
- // Check Exclude
- if (labels.some((l) => EXCLUDED_LABELS.includes(l))) {
- return false;
- }
+ const { getSettingsSchema } = await loadSettingsSchemaModule();
+ const schema = getSettingsSchema();
+ const allSettingsSections = collectEntries(schema, { includeAll: true });
+ const filteredSettingsSections = collectEntries(schema, {
+ includeAll: false,
+ });
+
+ const generatedBlock = renderSections(allSettingsSections);
+ const generatedTableBlock = renderTableSections(filteredSettingsSections);
- return true;
+ await updateFile(docPath, generatedBlock, checkOnly);
+ await updateFile(cliSettingsDocPath, generatedTableBlock, checkOnly);
}
-// Recursive function to find children
-const visitedParents = new Set();
-async function findChildren(repo, number, depth = 0) {
+async function updateFile(
+ filePath: string,
+ newContent: string,
+ checkOnly: boolean,
```
This function is important because it defines how Gemini CLI Tutorial: Terminal-First Agent Workflows with Google Gemini implements the patterns covered in this chapter.
@@ -222,11 +220,11 @@ This function is important because it defines how Gemini CLI Tutorial: Terminal-
```mermaid
flowchart TD
- A[runCommand]
- B[getIssues]
- C[getIssueBody]
- D[getProjectItems]
- E[shouldInclude]
+ A[main]
+ B[findDir]
+ C[main]
+ D[main]
+ E[updateFile]
A --> B
B --> C
C --> D
diff --git a/tutorials/genai-toolbox-tutorial/01-getting-started.md b/tutorials/genai-toolbox-tutorial/01-getting-started.md
index 8afdaf44..c7a842fb 100644
--- a/tutorials/genai-toolbox-tutorial/01-getting-started.md
+++ b/tutorials/genai-toolbox-tutorial/01-getting-started.md
@@ -40,8 +40,6 @@ You now have a validated local loop for running and invoking Toolbox tools.
Next: [Chapter 2: Architecture and Control Plane](02-architecture-and-control-plane.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `server.json`
@@ -50,21 +48,21 @@ The `the` interface in [`server.json`](https://github.com/googleapis/genai-toolb
```json
"type": "named",
- "name": "--tools-file",
+ "name": "--config",
"description": "File path specifying the tool configuration.",
"default": "tools.yaml",
"isRequired": false
},
{
"type": "named",
- "name": "--tools-files",
- "description": "Multiple file paths specifying tool configurations. Files will be merged. Cannot be used with –-tools-file or –-tools-folder.",
+ "name": "--configs",
+ "description": "Multiple file paths specifying tool configurations. Files will be merged. Cannot be used with –-config or –-config-folder.",
"isRequired": false
},
{
"type": "named",
- "name": "--tools-folder",
- "description": "Directory path containing YAML tool configuration files. All .yaml and .yml files in the directory will be loaded and merged. Cannot be used with –-tools-file or –-tools-files.",
+ "name": "--config-folder",
+ "description": "Directory path containing YAML tool configuration files. All .yaml and .yml files in the directory will be loaded and merged. Cannot be used with –-config or –-configs.",
"isRequired": false
},
{
diff --git a/tutorials/genai-toolbox-tutorial/02-architecture-and-control-plane.md b/tutorials/genai-toolbox-tutorial/02-architecture-and-control-plane.md
index fe858bb5..bee73aaf 100644
--- a/tutorials/genai-toolbox-tutorial/02-architecture-and-control-plane.md
+++ b/tutorials/genai-toolbox-tutorial/02-architecture-and-control-plane.md
@@ -35,170 +35,168 @@ You now understand how Toolbox provides a reusable orchestration layer for datab
Next: [Chapter 3: `tools.yaml`: Sources, Tools, Toolsets, Prompts](03-tools-yaml-sources-tools-toolsets-prompts.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `cmd/internal/options.go`
+### `internal/server/mcp.go`
-The `parsed` interface in [`cmd/internal/options.go`](https://github.com/googleapis/genai-toolbox/blob/HEAD/cmd/internal/options.go) handles a key part of this chapter's functionality:
+The `Set` function in [`internal/server/mcp.go`](https://github.com/googleapis/genai-toolbox/blob/HEAD/internal/server/mcp.go) handles a key part of this chapter's functionality:
```go
+}
- // Parse into ToolsFile struct
- parsed, err := parser.ParseToolsFile(ctx, buf)
- if err != nil {
- errMsg := fmt.Errorf("unable to parse prebuilt tool configuration for '%s': %w", configName, err)
- logger.ErrorContext(ctx, errMsg.Error())
- return isCustomConfigured, errMsg
- }
- allToolsFiles = append(allToolsFiles, parsed)
- }
+func (c traceContextCarrier) Set(key, value string) {
+ c[key] = value
+}
+
+func (c traceContextCarrier) Keys() []string {
+ keys := make([]string, 0, len(c))
+ for k := range c {
+ keys = append(keys, k)
}
+ return keys
+}
- // Load Custom Configurations
- if isCustomConfigured {
- customTools, err := parser.LoadAndMergeToolsFiles(ctx, filesPaths)
- if err != nil {
- logger.ErrorContext(ctx, err.Error())
- return isCustomConfigured, err
- }
- allToolsFiles = append(allToolsFiles, customTools)
+// extractTraceContext extracts W3C Trace Context from params._meta
+func extractTraceContext(ctx context.Context, body []byte) context.Context {
+ // Try to parse the request to extract _meta
+ var req struct {
+ Params struct {
+ Meta struct {
+ Traceparent string `json:"traceparent,omitempty"`
+ Tracestate string `json:"tracestate,omitempty"`
+ } `json:"_meta,omitempty"`
+ } `json:"params,omitempty"`
}
- // Modify version string based on loaded configurations
- if len(opts.PrebuiltConfigs) > 0 {
- tag := "prebuilt"
- if isCustomConfigured {
- tag = "custom"
- }
- // prebuiltConfigs is already sorted above
- for _, configName := range opts.PrebuiltConfigs {
- opts.Cfg.Version += fmt.Sprintf("+%s.%s", tag, configName)
- }
+ if err := json.Unmarshal(body, &req); err != nil {
+ return ctx
+ }
+
+ // If traceparent is present, extract the context
+ if req.Params.Meta.Traceparent != "" {
```
-This interface is important because it defines how GenAI Toolbox Tutorial: MCP-First Database Tooling with Config-Driven Control Planes implements the patterns covered in this chapter.
+This function is important because it defines how GenAI Toolbox Tutorial: MCP-First Database Tooling with Config-Driven Control Planes implements the patterns covered in this chapter.
-### `cmd/internal/tools_file.go`
+### `internal/server/mcp.go`
-The `parseEnv` function in [`cmd/internal/tools_file.go`](https://github.com/googleapis/genai-toolbox/blob/HEAD/cmd/internal/tools_file.go) handles a key part of this chapter's functionality:
+The `Keys` function in [`internal/server/mcp.go`](https://github.com/googleapis/genai-toolbox/blob/HEAD/internal/server/mcp.go) handles a key part of this chapter's functionality:
```go
}
-// parseEnv replaces environment variables ${ENV_NAME} with their values.
-// also support ${ENV_NAME:default_value}.
-func (p *ToolsFileParser) parseEnv(input string) (string, error) {
- re := regexp.MustCompile(`\$\{(\w+)(:([^}]*))?\}`)
+func (c traceContextCarrier) Keys() []string {
+ keys := make([]string, 0, len(c))
+ for k := range c {
+ keys = append(keys, k)
+ }
+ return keys
+}
- if p.EnvVars == nil {
- p.EnvVars = make(map[string]string)
+// extractTraceContext extracts W3C Trace Context from params._meta
+func extractTraceContext(ctx context.Context, body []byte) context.Context {
+ // Try to parse the request to extract _meta
+ var req struct {
+ Params struct {
+ Meta struct {
+ Traceparent string `json:"traceparent,omitempty"`
+ Tracestate string `json:"tracestate,omitempty"`
+ } `json:"_meta,omitempty"`
+ } `json:"params,omitempty"`
}
- var err error
- output := re.ReplaceAllStringFunc(input, func(match string) string {
- parts := re.FindStringSubmatch(match)
-
- // extract the variable name
- variableName := parts[1]
- if value, found := os.LookupEnv(variableName); found {
- p.EnvVars[variableName] = value
- return value
- }
- if len(parts) >= 4 && parts[2] != "" {
- value := parts[3]
- p.EnvVars[variableName] = value
- return value
- }
- err = fmt.Errorf("environment variable not found: %q", variableName)
- return ""
- })
- return output, err
-}
+ if err := json.Unmarshal(body, &req); err != nil {
+ return ctx
+ }
+ // If traceparent is present, extract the context
+ if req.Params.Meta.Traceparent != "" {
+ carrier := traceContextCarrier{
+ "traceparent": req.Params.Meta.Traceparent,
+ }
+ if req.Params.Meta.Tracestate != "" {
```
This function is important because it defines how GenAI Toolbox Tutorial: MCP-First Database Tooling with Config-Driven Control Planes implements the patterns covered in this chapter.
-### `cmd/internal/tools_file.go`
+### `internal/server/mcp.go`
-The `ParseToolsFile` function in [`cmd/internal/tools_file.go`](https://github.com/googleapis/genai-toolbox/blob/HEAD/cmd/internal/tools_file.go) handles a key part of this chapter's functionality:
+The `extractTraceContext` function in [`internal/server/mcp.go`](https://github.com/googleapis/genai-toolbox/blob/HEAD/internal/server/mcp.go) handles a key part of this chapter's functionality:
```go
}
-// ParseToolsFile parses the provided yaml into appropriate configs.
-func (p *ToolsFileParser) ParseToolsFile(ctx context.Context, raw []byte) (ToolsFile, error) {
- var toolsFile ToolsFile
- // Replace environment variables if found
- output, err := p.parseEnv(string(raw))
- if err != nil {
- return toolsFile, fmt.Errorf("error parsing environment variables: %s", err)
+// extractTraceContext extracts W3C Trace Context from params._meta
+func extractTraceContext(ctx context.Context, body []byte) context.Context {
+ // Try to parse the request to extract _meta
+ var req struct {
+ Params struct {
+ Meta struct {
+ Traceparent string `json:"traceparent,omitempty"`
+ Tracestate string `json:"tracestate,omitempty"`
+ } `json:"_meta,omitempty"`
+ } `json:"params,omitempty"`
}
- raw = []byte(output)
- raw, err = ConvertToolsFile(raw)
- if err != nil {
- return toolsFile, fmt.Errorf("error converting tools file: %s", err)
+ if err := json.Unmarshal(body, &req); err != nil {
+ return ctx
}
- // Parse contents
- toolsFile.Sources, toolsFile.AuthServices, toolsFile.EmbeddingModels, toolsFile.Tools, toolsFile.Toolsets, toolsFile.Prompts, err = server.UnmarshalResourceConfig(ctx, raw)
- if err != nil {
- return toolsFile, err
+ // If traceparent is present, extract the context
+ if req.Params.Meta.Traceparent != "" {
+ carrier := traceContextCarrier{
+ "traceparent": req.Params.Meta.Traceparent,
+ }
+ if req.Params.Meta.Tracestate != "" {
+ carrier["tracestate"] = req.Params.Meta.Tracestate
+ }
+ return otel.GetTextMapPropagator().Extract(ctx, carrier)
}
- return toolsFile, nil
-}
-// ConvertToolsFile converts configuration file from v1 to v2 format.
-func ConvertToolsFile(raw []byte) ([]byte, error) {
- var input yaml.MapSlice
- decoder := yaml.NewDecoder(bytes.NewReader(raw), yaml.UseOrderedMap())
+ return ctx
+}
- // convert to tools file v2
- var buf bytes.Buffer
```
This function is important because it defines how GenAI Toolbox Tutorial: MCP-First Database Tooling with Config-Driven Control Planes implements the patterns covered in this chapter.
-### `cmd/internal/tools_file.go`
+### `internal/server/mcp.go`
-The `ConvertToolsFile` function in [`cmd/internal/tools_file.go`](https://github.com/googleapis/genai-toolbox/blob/HEAD/cmd/internal/tools_file.go) handles a key part of this chapter's functionality:
+The `NewStdioSession` function in [`internal/server/mcp.go`](https://github.com/googleapis/genai-toolbox/blob/HEAD/internal/server/mcp.go) handles a key part of this chapter's functionality:
```go
- raw = []byte(output)
+}
- raw, err = ConvertToolsFile(raw)
- if err != nil {
- return toolsFile, fmt.Errorf("error converting tools file: %s", err)
+func NewStdioSession(s *Server, stdin io.Reader, stdout io.Writer) *stdioSession {
+ stdioSession := &stdioSession{
+ server: s,
+ reader: bufio.NewReader(stdin),
+ writer: stdout,
}
+ return stdioSession
+}
- // Parse contents
- toolsFile.Sources, toolsFile.AuthServices, toolsFile.EmbeddingModels, toolsFile.Tools, toolsFile.Toolsets, toolsFile.Prompts, err = server.UnmarshalResourceConfig(ctx, raw)
- if err != nil {
- return toolsFile, err
- }
- return toolsFile, nil
+func (s *stdioSession) Start(ctx context.Context) error {
+ return s.readInputStream(ctx)
}
-// ConvertToolsFile converts configuration file from v1 to v2 format.
-func ConvertToolsFile(raw []byte) ([]byte, error) {
- var input yaml.MapSlice
- decoder := yaml.NewDecoder(bytes.NewReader(raw), yaml.UseOrderedMap())
-
- // convert to tools file v2
- var buf bytes.Buffer
- encoder := yaml.NewEncoder(&buf)
-
- v1keys := []string{"sources", "authSources", "authServices", "embeddingModels", "tools", "toolsets", "prompts"}
- for {
- if err := decoder.Decode(&input); err != nil {
- if err == io.EOF {
- break
- }
- return nil, err
- }
+// readInputStream reads requests/notifications from MCP clients through stdin
+func (s *stdioSession) readInputStream(ctx context.Context) error {
+ sessionStart := time.Now()
+
+ // Define attributes for session metrics
+ // Note: mcp.protocol.version is added dynamically after protocol negotiation
+ sessionAttrs := []attribute.KeyValue{
+ attribute.String("network.transport", "pipe"),
+ attribute.String("network.protocol.name", "stdio"),
+ }
+
+ s.server.instrumentation.McpActiveSessions.Add(ctx, 1, metric.WithAttributes(sessionAttrs...))
+
+ var err error
+ defer func() {
+ // Build full attributes including mcp.protocol.version if negotiated
+ fullAttrs := sessionAttrs
```
This function is important because it defines how GenAI Toolbox Tutorial: MCP-First Database Tooling with Config-Driven Control Planes implements the patterns covered in this chapter.
@@ -208,11 +206,11 @@ This function is important because it defines how GenAI Toolbox Tutorial: MCP-Fi
```mermaid
flowchart TD
- A[parsed]
- B[parseEnv]
- C[ParseToolsFile]
- D[ConvertToolsFile]
- E[transformDocs]
+ A[Set]
+ B[Keys]
+ C[extractTraceContext]
+ D[NewStdioSession]
+ E[Start]
A --> B
B --> C
C --> D
diff --git a/tutorials/genai-toolbox-tutorial/03-tools-yaml-sources-tools-toolsets-prompts.md b/tutorials/genai-toolbox-tutorial/03-tools-yaml-sources-tools-toolsets-prompts.md
index 605ee534..4cd9bbd6 100644
--- a/tutorials/genai-toolbox-tutorial/03-tools-yaml-sources-tools-toolsets-prompts.md
+++ b/tutorials/genai-toolbox-tutorial/03-tools-yaml-sources-tools-toolsets-prompts.md
@@ -35,167 +35,142 @@ You can now design `tools.yaml` schemas that stay readable and stable as capabil
Next: [Chapter 4: MCP Connectivity and Client Integration](04-mcp-connectivity-and-client-integration.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `internal/server/config.go`
+### `internal/server/server.go`
-The `UnmarshalYAMLToolsetConfig` function in [`internal/server/config.go`](https://github.com/googleapis/genai-toolbox/blob/HEAD/internal/server/config.go) handles a key part of this chapter's functionality:
+The `ServeStdio` function in [`internal/server/server.go`](https://github.com/googleapis/genai-toolbox/blob/HEAD/internal/server/server.go) handles a key part of this chapter's functionality:
```go
- toolConfigs[name] = c
- case "toolsets":
- c, err := UnmarshalYAMLToolsetConfig(ctx, name, resource)
- if err != nil {
- return nil, nil, nil, nil, nil, nil, fmt.Errorf("error unmarshaling %s: %s", kind, err)
- }
- if toolsetConfigs == nil {
- toolsetConfigs = make(ToolsetConfigs)
- }
- toolsetConfigs[name] = c
- case "embeddingModels":
- c, err := UnmarshalYAMLEmbeddingModelConfig(ctx, name, resource)
- if err != nil {
- return nil, nil, nil, nil, nil, nil, fmt.Errorf("error unmarshaling %s: %s", kind, err)
- }
- if embeddingModelConfigs == nil {
- embeddingModelConfigs = make(EmbeddingModelConfigs)
- }
- embeddingModelConfigs[name] = c
- case "prompts":
- c, err := UnmarshalYAMLPromptConfig(ctx, name, resource)
- if err != nil {
- return nil, nil, nil, nil, nil, nil, fmt.Errorf("error unmarshaling %s: %s", kind, err)
- }
- if promptConfigs == nil {
- promptConfigs = make(PromptConfigs)
- }
- promptConfigs[name] = c
- default:
- return nil, nil, nil, nil, nil, nil, fmt.Errorf("invalid kind %s", kind)
- }
- }
-```
-
-This function is important because it defines how GenAI Toolbox Tutorial: MCP-First Database Tooling with Config-Driven Control Planes implements the patterns covered in this chapter.
-
-### `internal/server/config.go`
-
-The `UnmarshalYAMLPromptConfig` function in [`internal/server/config.go`](https://github.com/googleapis/genai-toolbox/blob/HEAD/internal/server/config.go) handles a key part of this chapter's functionality:
+}
-```go
- embeddingModelConfigs[name] = c
- case "prompts":
- c, err := UnmarshalYAMLPromptConfig(ctx, name, resource)
- if err != nil {
- return nil, nil, nil, nil, nil, nil, fmt.Errorf("error unmarshaling %s: %s", kind, err)
- }
- if promptConfigs == nil {
- promptConfigs = make(PromptConfigs)
- }
- promptConfigs[name] = c
- default:
- return nil, nil, nil, nil, nil, nil, fmt.Errorf("invalid kind %s", kind)
- }
- }
- return sourceConfigs, authServiceConfigs, embeddingModelConfigs, toolConfigs, toolsetConfigs, promptConfigs, nil
+// ServeStdio starts a new stdio session for mcp.
+func (s *Server) ServeStdio(ctx context.Context, stdin io.Reader, stdout io.Writer) error {
+ stdioServer := NewStdioSession(s, stdin, stdout)
+ return stdioServer.Start(ctx)
}
-func UnmarshalYAMLSourceConfig(ctx context.Context, name string, r map[string]any) (sources.SourceConfig, error) {
- resourceType, ok := r["type"].(string)
- if !ok {
- return nil, fmt.Errorf("missing 'type' field or it is not a string")
- }
- dec, err := util.NewStrictDecoder(r)
- if err != nil {
- return nil, fmt.Errorf("error creating decoder: %w", err)
- }
- sourceConfig, err := sources.DecodeConfig(ctx, resourceType, name, dec)
- if err != nil {
- return nil, err
- }
- return sourceConfig, nil
+// Shutdown gracefully shuts down the server without interrupting any active
+// connections. It uses http.Server.Shutdown() and has the same functionality.
+func (s *Server) Shutdown(ctx context.Context) error {
+ s.logger.DebugContext(ctx, "shutting down the server.")
+ return s.srv.Shutdown(ctx)
}
+
```
This function is important because it defines how GenAI Toolbox Tutorial: MCP-First Database Tooling with Config-Driven Control Planes implements the patterns covered in this chapter.
-### `internal/server/config.go`
+### `internal/server/server.go`
-The `NameValidation` function in [`internal/server/config.go`](https://github.com/googleapis/genai-toolbox/blob/HEAD/internal/server/config.go) handles a key part of this chapter's functionality:
+The `Shutdown` function in [`internal/server/server.go`](https://github.com/googleapis/genai-toolbox/blob/HEAD/internal/server/server.go) handles a key part of this chapter's functionality:
```go
-// Tool names SHOULD NOT contain spaces, commas, or other special characters.
-// Tool names SHOULD be unique within a server.
-func NameValidation(name string) error {
- strLen := len(name)
- if strLen < 1 || strLen > 128 {
- return fmt.Errorf("resource name SHOULD be between 1 and 128 characters in length (inclusive)")
- }
- validChars := regexp.MustCompile("^[a-zA-Z0-9_.-]+$")
- isValid := validChars.MatchString(name)
- if !isValid {
- return fmt.Errorf("invalid character for resource name; only uppercase and lowercase ASCII letters (A-Z, a-z), digits (0-9), underscore (_), hyphen (-), and dot (.) is allowed")
- }
- return nil
+}
+
+// Shutdown gracefully shuts down the server without interrupting any active
+// connections. It uses http.Server.Shutdown() and has the same functionality.
+func (s *Server) Shutdown(ctx context.Context) error {
+ s.logger.DebugContext(ctx, "shutting down the server.")
+ return s.srv.Shutdown(ctx)
}
```
This function is important because it defines how GenAI Toolbox Tutorial: MCP-First Database Tooling with Config-Driven Control Planes implements the patterns covered in this chapter.
-### `internal/server/config.go`
+### `internal/server/server.go`
-The `the` interface in [`internal/server/config.go`](https://github.com/googleapis/genai-toolbox/blob/HEAD/internal/server/config.go) handles a key part of this chapter's functionality:
+The `to` interface in [`internal/server/server.go`](https://github.com/googleapis/genai-toolbox/blob/HEAD/internal/server/server.go) handles a key part of this chapter's functionality:
```go
-// Copyright 2024 Google LLC
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-// http://www.apache.org/licenses/LICENSE-2.0
+// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
+
package server
import (
- "bytes"
"context"
+ "encoding/json"
+ "errors"
"fmt"
"io"
- "regexp"
+ "net"
+ "net/http"
+ "os"
+ "slices"
+ "strconv"
"strings"
+ "time"
- yaml "github.com/goccy/go-yaml"
+ "github.com/go-chi/chi/v5"
+ "github.com/go-chi/chi/v5/middleware"
+ "github.com/go-chi/cors"
+ "github.com/go-chi/httplog/v3"
+ "github.com/go-chi/render"
"github.com/googleapis/genai-toolbox/internal/auth"
- "github.com/googleapis/genai-toolbox/internal/auth/google"
+ "github.com/googleapis/genai-toolbox/internal/auth/generic"
"github.com/googleapis/genai-toolbox/internal/embeddingmodels"
- "github.com/googleapis/genai-toolbox/internal/embeddingmodels/gemini"
- "github.com/googleapis/genai-toolbox/internal/prompts"
- "github.com/googleapis/genai-toolbox/internal/sources"
- "github.com/googleapis/genai-toolbox/internal/tools"
- "github.com/googleapis/genai-toolbox/internal/util"
```
This interface is important because it defines how GenAI Toolbox Tutorial: MCP-First Database Tooling with Config-Driven Control Planes implements the patterns covered in this chapter.
+### `cmd/internal/config.go`
+
+The `parseEnv` function in [`cmd/internal/config.go`](https://github.com/googleapis/genai-toolbox/blob/HEAD/cmd/internal/config.go) handles a key part of this chapter's functionality:
+
+```go
+}
+
+// parseEnv replaces environment variables ${ENV_NAME} with their values.
+// also support ${ENV_NAME:default_value}.
+func (p *ConfigParser) parseEnv(input string) (string, error) {
+ re := regexp.MustCompile(`\$\{(\w+)(:([^}]*))?\}`)
+
+ if p.EnvVars == nil {
+ p.EnvVars = make(map[string]string)
+ }
+
+ var err error
+ output := re.ReplaceAllStringFunc(input, func(match string) string {
+ parts := re.FindStringSubmatch(match)
+
+ // extract the variable name
+ variableName := parts[1]
+ if value, found := os.LookupEnv(variableName); found {
+ p.EnvVars[variableName] = value
+ return value
+ }
+ if len(parts) >= 4 && parts[2] != "" {
+ value := parts[3]
+ p.EnvVars[variableName] = value
+ return value
+ }
+ err = fmt.Errorf("environment variable not found: %q", variableName)
+ return ""
+ })
+ return output, err
+}
+
+```
+
+This function is important because it defines how GenAI Toolbox Tutorial: MCP-First Database Tooling with Config-Driven Control Planes implements the patterns covered in this chapter.
+
## How These Components Connect
```mermaid
flowchart TD
- A[UnmarshalYAMLToolsetConfig]
- B[UnmarshalYAMLPromptConfig]
- C[NameValidation]
- D[the]
- E[InitializeConfigs]
+ A[ServeStdio]
+ B[Shutdown]
+ C[to]
+ D[parseEnv]
+ E[ParseConfig]
A --> B
B --> C
C --> D
diff --git a/tutorials/genai-toolbox-tutorial/04-mcp-connectivity-and-client-integration.md b/tutorials/genai-toolbox-tutorial/04-mcp-connectivity-and-client-integration.md
index ca7b0326..404d35a7 100644
--- a/tutorials/genai-toolbox-tutorial/04-mcp-connectivity-and-client-integration.md
+++ b/tutorials/genai-toolbox-tutorial/04-mcp-connectivity-and-client-integration.md
@@ -36,184 +36,165 @@ You now have a practical framework for choosing and operating Toolbox integratio
Next: [Chapter 5: Prebuilt Connectors and Database Patterns](05-prebuilt-connectors-and-database-patterns.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `internal/server/mcp.go`
+### `cmd/internal/flags.go`
-The `get` function in [`internal/server/mcp.go`](https://github.com/googleapis/genai-toolbox/blob/HEAD/internal/server/mcp.go) handles a key part of this chapter's functionality:
+The `PersistentFlags` function in [`cmd/internal/flags.go`](https://github.com/googleapis/genai-toolbox/blob/HEAD/cmd/internal/flags.go) handles a key part of this chapter's functionality:
```go
+)
+
+// PersistentFlags sets up flags that are available for all commands and
+// subcommands
+// It is also used to set up persistent flags during subcommand unit tests
+func PersistentFlags(parentCmd *cobra.Command, opts *ToolboxOptions) {
+ persistentFlags := parentCmd.PersistentFlags()
+
+ persistentFlags.Var(&opts.Cfg.LogLevel, "log-level", "Specify the minimum level logged. Allowed: 'DEBUG', 'INFO', 'WARN', 'ERROR'.")
+ persistentFlags.Var(&opts.Cfg.LoggingFormat, "logging-format", "Specify logging format to use. Allowed: 'standard' or 'JSON'.")
+ persistentFlags.BoolVar(&opts.Cfg.TelemetryGCP, "telemetry-gcp", false, "Enable exporting directly to Google Cloud Monitoring.")
+ persistentFlags.StringVar(&opts.Cfg.TelemetryOTLP, "telemetry-otlp", "", "Enable exporting using OpenTelemetry Protocol (OTLP) to the specified endpoint (e.g. 'http://127.0.0.1:4318')")
+ persistentFlags.StringVar(&opts.Cfg.TelemetryServiceName, "telemetry-service-name", "toolbox", "Sets the value of the service.name resource attribute for telemetry data.")
+ persistentFlags.StringSliceVar(&opts.Cfg.UserAgentMetadata, "user-agent-metadata", []string{}, "Appends additional metadata to the User-Agent.")
}
-func (m *sseManager) get(id string) (*sseSession, bool) {
- m.mu.Lock()
- defer m.mu.Unlock()
- session, ok := m.sseSessions[id]
- if !ok || session == nil {
- // Be defensive: a nil session entry should be treated as unavailable.
- if ok && session == nil {
- delete(m.sseSessions, id)
- }
- return nil, false
- }
- session.lastActive = time.Now()
- return session, true
-}
-
-func newSseManager(ctx context.Context) *sseManager {
- sseM := &sseManager{
- mu: sync.Mutex{},
- sseSessions: make(map[string]*sseSession),
- }
- go sseM.cleanupRoutine(ctx)
- return sseM
-}
-
-func (m *sseManager) add(id string, session *sseSession) {
- m.mu.Lock()
- defer m.mu.Unlock()
- m.sseSessions[id] = session
- session.lastActive = time.Now()
-}
+// ConfigFileFlags defines flags related to the configuration file.
+// It should be applied to any command that requires configuration loading.
+func ConfigFileFlags(flags *pflag.FlagSet, opts *ToolboxOptions) {
+ flags.StringVar(&opts.Config, "config", "", "File path specifying the tool configuration. Cannot be used with --configs, or --config-folder.")
+ flags.StringVar(&opts.Config, "tools-file", "", "File path specifying the tool configuration. Cannot be used with --tools-files, or --tools-folder.")
+ _ = flags.MarkDeprecated("tools-file", "please use --config instead") // DEPRECATED
+ flags.StringSliceVar(&opts.Configs, "configs", []string{}, "Multiple file paths specifying tool configurations. Files will be merged. Cannot be used with --config, or --config-folder.")
+ flags.StringSliceVar(&opts.Configs, "tools-files", []string{}, "Multiple file paths specifying tool configurations. Files will be merged. Cannot be used with --tools-file, or --tools-folder.")
+ _ = flags.MarkDeprecated("tools-files", "please use --configs instead") // DEPRECATED
+ flags.StringVar(&opts.ConfigFolder, "config-folder", "", "Directory path containing YAML tool configuration files. All .yaml and .yml files in the directory will be loaded and merged. Cannot be used with --config, or --configs.")
+ flags.StringVar(&opts.ConfigFolder, "tools-folder", "", "Directory path containing YAML tool configuration files. All .yaml and .yml files in the directory will be loaded and merged. Cannot be used with --tools-file, or --tools-files.")
+ _ = flags.MarkDeprecated("tools-folder", "please use --config-folder instead") // DEPRECATED
+ // Fetch prebuilt tools sources to customize the help description
+ prebuiltHelp := fmt.Sprintf(
+ "Use a prebuilt tool configuration by source type. Allowed: '%s'. Can be specified multiple times.",
+ strings.Join(prebuiltconfigs.GetPrebuiltSources(), "', '"),
```
This function is important because it defines how GenAI Toolbox Tutorial: MCP-First Database Tooling with Config-Driven Control Planes implements the patterns covered in this chapter.
-### `internal/server/mcp.go`
+### `cmd/internal/flags.go`
-The `newSseManager` function in [`internal/server/mcp.go`](https://github.com/googleapis/genai-toolbox/blob/HEAD/internal/server/mcp.go) handles a key part of this chapter's functionality:
+The `ConfigFileFlags` function in [`cmd/internal/flags.go`](https://github.com/googleapis/genai-toolbox/blob/HEAD/cmd/internal/flags.go) handles a key part of this chapter's functionality:
```go
}
-func newSseManager(ctx context.Context) *sseManager {
- sseM := &sseManager{
- mu: sync.Mutex{},
- sseSessions: make(map[string]*sseSession),
- }
- go sseM.cleanupRoutine(ctx)
- return sseM
-}
-
-func (m *sseManager) add(id string, session *sseSession) {
- m.mu.Lock()
- defer m.mu.Unlock()
- m.sseSessions[id] = session
- session.lastActive = time.Now()
-}
-
-func (m *sseManager) remove(id string) {
- m.mu.Lock()
- delete(m.sseSessions, id)
- m.mu.Unlock()
+// ConfigFileFlags defines flags related to the configuration file.
+// It should be applied to any command that requires configuration loading.
+func ConfigFileFlags(flags *pflag.FlagSet, opts *ToolboxOptions) {
+ flags.StringVar(&opts.Config, "config", "", "File path specifying the tool configuration. Cannot be used with --configs, or --config-folder.")
+ flags.StringVar(&opts.Config, "tools-file", "", "File path specifying the tool configuration. Cannot be used with --tools-files, or --tools-folder.")
+ _ = flags.MarkDeprecated("tools-file", "please use --config instead") // DEPRECATED
+ flags.StringSliceVar(&opts.Configs, "configs", []string{}, "Multiple file paths specifying tool configurations. Files will be merged. Cannot be used with --config, or --config-folder.")
+ flags.StringSliceVar(&opts.Configs, "tools-files", []string{}, "Multiple file paths specifying tool configurations. Files will be merged. Cannot be used with --tools-file, or --tools-folder.")
+ _ = flags.MarkDeprecated("tools-files", "please use --configs instead") // DEPRECATED
+ flags.StringVar(&opts.ConfigFolder, "config-folder", "", "Directory path containing YAML tool configuration files. All .yaml and .yml files in the directory will be loaded and merged. Cannot be used with --config, or --configs.")
+ flags.StringVar(&opts.ConfigFolder, "tools-folder", "", "Directory path containing YAML tool configuration files. All .yaml and .yml files in the directory will be loaded and merged. Cannot be used with --tools-file, or --tools-files.")
+ _ = flags.MarkDeprecated("tools-folder", "please use --config-folder instead") // DEPRECATED
+ // Fetch prebuilt tools sources to customize the help description
+ prebuiltHelp := fmt.Sprintf(
+ "Use a prebuilt tool configuration by source type. Allowed: '%s'. Can be specified multiple times.",
+ strings.Join(prebuiltconfigs.GetPrebuiltSources(), "', '"),
+ )
+ flags.StringSliceVar(&opts.PrebuiltConfigs, "prebuilt", []string{}, prebuiltHelp)
}
-func (m *sseManager) cleanupRoutine(ctx context.Context) {
- timeout := 10 * time.Minute
- ticker := time.NewTicker(timeout)
- defer ticker.Stop()
-
- for {
- select {
- case <-ctx.Done():
+// ServeFlags defines flags for starting and configuring the server.
+func ServeFlags(flags *pflag.FlagSet, opts *ToolboxOptions) {
+ flags.StringVarP(&opts.Cfg.Address, "address", "a", "127.0.0.1", "Address of the interface the server will listen on.")
+ flags.IntVarP(&opts.Cfg.Port, "port", "p", 5000, "Port the server will listen on.")
+ flags.BoolVar(&opts.Cfg.Stdio, "stdio", false, "Listens via MCP STDIO instead of acting as a remote HTTP server.")
+ flags.BoolVar(&opts.Cfg.UI, "ui", false, "Launches the Toolbox UI web server.")
+ flags.BoolVar(&opts.Cfg.EnableAPI, "enable-api", false, "Enable the /api endpoint.")
+ flags.StringVar(&opts.Cfg.ToolboxUrl, "toolbox-url", "", "Specifies the Toolbox URL. Used as the resource field in the MCP PRM file when MCP Auth is enabled. Falls back to TOOLBOX_URL environment variable.")
+ flags.StringVar(&opts.Cfg.McpPrmFile, "mcp-prm-file", "", "Path to a manual Protected Resource Metadata (PRM) JSON file. If provided, overrides auto-generation.")
+ flags.StringSliceVar(&opts.Cfg.AllowedOrigins, "allowed-origins", []string{"*"}, "Specifies a list of origins permitted to access this server. Defaults to '*'.")
```
This function is important because it defines how GenAI Toolbox Tutorial: MCP-First Database Tooling with Config-Driven Control Planes implements the patterns covered in this chapter.
-### `internal/server/mcp.go`
+### `cmd/internal/flags.go`
-The `add` function in [`internal/server/mcp.go`](https://github.com/googleapis/genai-toolbox/blob/HEAD/internal/server/mcp.go) handles a key part of this chapter's functionality:
+The `ServeFlags` function in [`cmd/internal/flags.go`](https://github.com/googleapis/genai-toolbox/blob/HEAD/cmd/internal/flags.go) handles a key part of this chapter's functionality:
```go
}
-func (m *sseManager) add(id string, session *sseSession) {
- m.mu.Lock()
- defer m.mu.Unlock()
- m.sseSessions[id] = session
- session.lastActive = time.Now()
-}
-
-func (m *sseManager) remove(id string) {
- m.mu.Lock()
- delete(m.sseSessions, id)
- m.mu.Unlock()
+// ServeFlags defines flags for starting and configuring the server.
+func ServeFlags(flags *pflag.FlagSet, opts *ToolboxOptions) {
+ flags.StringVarP(&opts.Cfg.Address, "address", "a", "127.0.0.1", "Address of the interface the server will listen on.")
+ flags.IntVarP(&opts.Cfg.Port, "port", "p", 5000, "Port the server will listen on.")
+ flags.BoolVar(&opts.Cfg.Stdio, "stdio", false, "Listens via MCP STDIO instead of acting as a remote HTTP server.")
+ flags.BoolVar(&opts.Cfg.UI, "ui", false, "Launches the Toolbox UI web server.")
+ flags.BoolVar(&opts.Cfg.EnableAPI, "enable-api", false, "Enable the /api endpoint.")
+ flags.StringVar(&opts.Cfg.ToolboxUrl, "toolbox-url", "", "Specifies the Toolbox URL. Used as the resource field in the MCP PRM file when MCP Auth is enabled. Falls back to TOOLBOX_URL environment variable.")
+ flags.StringVar(&opts.Cfg.McpPrmFile, "mcp-prm-file", "", "Path to a manual Protected Resource Metadata (PRM) JSON file. If provided, overrides auto-generation.")
+ flags.StringSliceVar(&opts.Cfg.AllowedOrigins, "allowed-origins", []string{"*"}, "Specifies a list of origins permitted to access this server. Defaults to '*'.")
+ flags.StringSliceVar(&opts.Cfg.AllowedHosts, "allowed-hosts", []string{"*"}, "Specifies a list of hosts permitted to access this server. Defaults to '*'.")
}
-func (m *sseManager) cleanupRoutine(ctx context.Context) {
- timeout := 10 * time.Minute
- ticker := time.NewTicker(timeout)
- defer ticker.Stop()
-
- for {
- select {
- case <-ctx.Done():
- return
- case <-ticker.C:
- func() {
- m.mu.Lock()
- defer m.mu.Unlock()
- now := time.Now()
- for id, sess := range m.sseSessions {
- if now.Sub(sess.lastActive) > timeout {
- delete(m.sseSessions, id)
```
This function is important because it defines how GenAI Toolbox Tutorial: MCP-First Database Tooling with Config-Driven Control Planes implements the patterns covered in this chapter.
-### `internal/server/mcp.go`
+### `cmd/internal/flags.go`
-The `remove` function in [`internal/server/mcp.go`](https://github.com/googleapis/genai-toolbox/blob/HEAD/internal/server/mcp.go) handles a key part of this chapter's functionality:
+The `the` interface in [`cmd/internal/flags.go`](https://github.com/googleapis/genai-toolbox/blob/HEAD/cmd/internal/flags.go) handles a key part of this chapter's functionality:
```go
-}
-
-func (m *sseManager) remove(id string) {
- m.mu.Lock()
- delete(m.sseSessions, id)
- m.mu.Unlock()
-}
-
-func (m *sseManager) cleanupRoutine(ctx context.Context) {
- timeout := 10 * time.Minute
- ticker := time.NewTicker(timeout)
- defer ticker.Stop()
-
- for {
- select {
- case <-ctx.Done():
- return
- case <-ticker.C:
- func() {
- m.mu.Lock()
- defer m.mu.Unlock()
- now := time.Now()
- for id, sess := range m.sseSessions {
- if now.Sub(sess.lastActive) > timeout {
- delete(m.sseSessions, id)
- }
- }
- }()
- }
- }
-}
-
+// Copyright 2026 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package internal
+
+import (
+ "fmt"
+ "strings"
+
+ "github.com/googleapis/genai-toolbox/internal/prebuiltconfigs"
+ "github.com/spf13/cobra"
+ "github.com/spf13/pflag"
+)
+
+// PersistentFlags sets up flags that are available for all commands and
+// subcommands
+// It is also used to set up persistent flags during subcommand unit tests
+func PersistentFlags(parentCmd *cobra.Command, opts *ToolboxOptions) {
+ persistentFlags := parentCmd.PersistentFlags()
+
+ persistentFlags.Var(&opts.Cfg.LogLevel, "log-level", "Specify the minimum level logged. Allowed: 'DEBUG', 'INFO', 'WARN', 'ERROR'.")
```
-This function is important because it defines how GenAI Toolbox Tutorial: MCP-First Database Tooling with Config-Driven Control Planes implements the patterns covered in this chapter.
+This interface is important because it defines how GenAI Toolbox Tutorial: MCP-First Database Tooling with Config-Driven Control Planes implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[get]
- B[newSseManager]
- C[add]
- D[remove]
- E[cleanupRoutine]
+ A[PersistentFlags]
+ B[ConfigFileFlags]
+ C[ServeFlags]
+ D[the]
+ E[Register]
A --> B
B --> C
C --> D
diff --git a/tutorials/genai-toolbox-tutorial/05-prebuilt-connectors-and-database-patterns.md b/tutorials/genai-toolbox-tutorial/05-prebuilt-connectors-and-database-patterns.md
index e444bfa5..5a953643 100644
--- a/tutorials/genai-toolbox-tutorial/05-prebuilt-connectors-and-database-patterns.md
+++ b/tutorials/genai-toolbox-tutorial/05-prebuilt-connectors-and-database-patterns.md
@@ -36,170 +36,168 @@ You now understand how to scale database coverage without losing operational cla
Next: [Chapter 6: Deployment and Observability Patterns](06-deployment-and-observability-patterns.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `internal/util/util.go`
-The `ConvertNumbers` function in [`internal/util/util.go`](https://github.com/googleapis/genai-toolbox/blob/HEAD/internal/util/util.go) handles a key part of this chapter's functionality:
+The `RoundTrip` function in [`internal/util/util.go`](https://github.com/googleapis/genai-toolbox/blob/HEAD/internal/util/util.go) handles a key part of this chapter's functionality:
```go
}
-// ConvertNumbers traverses an interface and converts all json.Number
-// instances to int64 or float64.
-func ConvertNumbers(data any) (any, error) {
- switch v := data.(type) {
- // If it's a map, recursively convert the values.
- case map[string]any:
- for key, val := range v {
- convertedVal, err := ConvertNumbers(val)
- if err != nil {
- return nil, err
- }
- v[key] = convertedVal
- }
- return v, nil
-
- // If it's a slice, recursively convert the elements.
- case []any:
- for i, val := range v {
- convertedVal, err := ConvertNumbers(val)
- if err != nil {
- return nil, err
- }
- v[i] = convertedVal
- }
- return v, nil
-
- // If it's a json.Number, convert it to float or int
- case json.Number:
- // Check for a decimal point to decide the type.
- if strings.Contains(v.String(), ".") {
+type UserAgentRoundTripper struct {
+ userAgent string
+ next http.RoundTripper
+}
+
+func NewUserAgentRoundTripper(ua string, next http.RoundTripper) *UserAgentRoundTripper {
+ return &UserAgentRoundTripper{
+ userAgent: ua,
+ next: next,
+ }
+}
+
+func (rt *UserAgentRoundTripper) RoundTrip(req *http.Request) (*http.Response, error) {
+ // create a deep copy of the request
+ newReq := req.Clone(req.Context())
+ ua := newReq.Header.Get("User-Agent")
+ if ua == "" {
+ newReq.Header.Set("User-Agent", rt.userAgent)
+ } else {
+ newReq.Header.Set("User-Agent", ua+" "+rt.userAgent)
+ }
+ return rt.next.RoundTrip(newReq)
+}
+
+func NewStrictDecoder(v interface{}) (*yaml.Decoder, error) {
+ b, err := yaml.Marshal(v)
+ if err != nil {
+ return nil, fmt.Errorf("fail to marshal %q: %w", v, err)
+ }
+
```
This function is important because it defines how GenAI Toolbox Tutorial: MCP-First Database Tooling with Config-Driven Control Planes implements the patterns covered in this chapter.
### `internal/util/util.go`
-The `UnmarshalYAML` function in [`internal/util/util.go`](https://github.com/googleapis/genai-toolbox/blob/HEAD/internal/util/util.go) handles a key part of this chapter's functionality:
+The `NewStrictDecoder` function in [`internal/util/util.go`](https://github.com/googleapis/genai-toolbox/blob/HEAD/internal/util/util.go) handles a key part of this chapter's functionality:
```go
-
-// DelayedUnmarshaler is struct that saves the provided unmarshal function
-// passed to UnmarshalYAML so it can be re-used later once the target interface
-// is known.
-type DelayedUnmarshaler struct {
- unmarshal func(interface{}) error
}
-func (d *DelayedUnmarshaler) UnmarshalYAML(ctx context.Context, unmarshal func(interface{}) error) error {
- d.unmarshal = unmarshal
- return nil
-}
-
-func (d *DelayedUnmarshaler) Unmarshal(v interface{}) error {
- if d.unmarshal == nil {
- return fmt.Errorf("nothing to unmarshal")
+func NewStrictDecoder(v interface{}) (*yaml.Decoder, error) {
+ b, err := yaml.Marshal(v)
+ if err != nil {
+ return nil, fmt.Errorf("fail to marshal %q: %w", v, err)
}
- return d.unmarshal(v)
+
+ dec := yaml.NewDecoder(
+ bytes.NewReader(b),
+ yaml.Strict(),
+ yaml.Validator(validator.New()),
+ )
+ return dec, nil
}
-type contextKey string
+// loggerKey is the key used to store logger within context
+const loggerKey contextKey = "logger"
-// userAgentKey is the key used to store userAgent within context
-const userAgentKey contextKey = "userAgent"
+// WithLogger adds a logger into the context as a value
+func WithLogger(ctx context.Context, logger log.Logger) context.Context {
+ return context.WithValue(ctx, loggerKey, logger)
+}
-// WithUserAgent adds a user agent into the context as a value
-func WithUserAgent(ctx context.Context, versionString string) context.Context {
- userAgent := "genai-toolbox/" + versionString
- return context.WithValue(ctx, userAgentKey, userAgent)
+// LoggerFromContext retrieves the logger or return an error
+func LoggerFromContext(ctx context.Context) (log.Logger, error) {
+ if logger, ok := ctx.Value(loggerKey).(log.Logger); ok {
+ return logger, nil
+ }
+ return nil, fmt.Errorf("unable to retrieve logger")
}
-// UserAgentFromContext retrieves the user agent or return an error
```
This function is important because it defines how GenAI Toolbox Tutorial: MCP-First Database Tooling with Config-Driven Control Planes implements the patterns covered in this chapter.
### `internal/util/util.go`
-The `Unmarshal` function in [`internal/util/util.go`](https://github.com/googleapis/genai-toolbox/blob/HEAD/internal/util/util.go) handles a key part of this chapter's functionality:
+The `WithLogger` function in [`internal/util/util.go`](https://github.com/googleapis/genai-toolbox/blob/HEAD/internal/util/util.go) handles a key part of this chapter's functionality:
```go
-}
+const loggerKey contextKey = "logger"
-var _ yaml.InterfaceUnmarshalerContext = &DelayedUnmarshaler{}
+// WithLogger adds a logger into the context as a value
+func WithLogger(ctx context.Context, logger log.Logger) context.Context {
+ return context.WithValue(ctx, loggerKey, logger)
+}
-// DelayedUnmarshaler is struct that saves the provided unmarshal function
-// passed to UnmarshalYAML so it can be re-used later once the target interface
-// is known.
-type DelayedUnmarshaler struct {
- unmarshal func(interface{}) error
+// LoggerFromContext retrieves the logger or return an error
+func LoggerFromContext(ctx context.Context) (log.Logger, error) {
+ if logger, ok := ctx.Value(loggerKey).(log.Logger); ok {
+ return logger, nil
+ }
+ return nil, fmt.Errorf("unable to retrieve logger")
}
-func (d *DelayedUnmarshaler) UnmarshalYAML(ctx context.Context, unmarshal func(interface{}) error) error {
- d.unmarshal = unmarshal
- return nil
+const instrumentationKey contextKey = "instrumentation"
+
+// WithInstrumentation adds an instrumentation into the context as a value
+func WithInstrumentation(ctx context.Context, instrumentation *telemetry.Instrumentation) context.Context {
+ return context.WithValue(ctx, instrumentationKey, instrumentation)
}
-func (d *DelayedUnmarshaler) Unmarshal(v interface{}) error {
- if d.unmarshal == nil {
- return fmt.Errorf("nothing to unmarshal")
+// InstrumentationFromContext retrieves the instrumentation or return an error
+func InstrumentationFromContext(ctx context.Context) (*telemetry.Instrumentation, error) {
+ if instrumentation, ok := ctx.Value(instrumentationKey).(*telemetry.Instrumentation); ok {
+ return instrumentation, nil
}
- return d.unmarshal(v)
+ return nil, fmt.Errorf("unable to retrieve instrumentation")
}
-type contextKey string
-
-// userAgentKey is the key used to store userAgent within context
-const userAgentKey contextKey = "userAgent"
-
-// WithUserAgent adds a user agent into the context as a value
-func WithUserAgent(ctx context.Context, versionString string) context.Context {
- userAgent := "genai-toolbox/" + versionString
- return context.WithValue(ctx, userAgentKey, userAgent)
+// GenAIMetricAttrs holds gen_ai and network attributes for metrics
+type GenAIMetricAttrs struct {
```
This function is important because it defines how GenAI Toolbox Tutorial: MCP-First Database Tooling with Config-Driven Control Planes implements the patterns covered in this chapter.
### `internal/util/util.go`
-The `WithUserAgent` function in [`internal/util/util.go`](https://github.com/googleapis/genai-toolbox/blob/HEAD/internal/util/util.go) handles a key part of this chapter's functionality:
+The `LoggerFromContext` function in [`internal/util/util.go`](https://github.com/googleapis/genai-toolbox/blob/HEAD/internal/util/util.go) handles a key part of this chapter's functionality:
```go
-const userAgentKey contextKey = "userAgent"
-
-// WithUserAgent adds a user agent into the context as a value
-func WithUserAgent(ctx context.Context, versionString string) context.Context {
- userAgent := "genai-toolbox/" + versionString
- return context.WithValue(ctx, userAgentKey, userAgent)
}
-// UserAgentFromContext retrieves the user agent or return an error
-func UserAgentFromContext(ctx context.Context) (string, error) {
- if ua := ctx.Value(userAgentKey); ua != nil {
- return ua.(string), nil
- } else {
- return "", fmt.Errorf("unable to retrieve user agent")
+// LoggerFromContext retrieves the logger or return an error
+func LoggerFromContext(ctx context.Context) (log.Logger, error) {
+ if logger, ok := ctx.Value(loggerKey).(log.Logger); ok {
+ return logger, nil
}
+ return nil, fmt.Errorf("unable to retrieve logger")
}
-type UserAgentRoundTripper struct {
- userAgent string
- next http.RoundTripper
+const instrumentationKey contextKey = "instrumentation"
+
+// WithInstrumentation adds an instrumentation into the context as a value
+func WithInstrumentation(ctx context.Context, instrumentation *telemetry.Instrumentation) context.Context {
+ return context.WithValue(ctx, instrumentationKey, instrumentation)
}
-func NewUserAgentRoundTripper(ua string, next http.RoundTripper) *UserAgentRoundTripper {
- return &UserAgentRoundTripper{
- userAgent: ua,
- next: next,
+// InstrumentationFromContext retrieves the instrumentation or return an error
+func InstrumentationFromContext(ctx context.Context) (*telemetry.Instrumentation, error) {
+ if instrumentation, ok := ctx.Value(instrumentationKey).(*telemetry.Instrumentation); ok {
+ return instrumentation, nil
}
+ return nil, fmt.Errorf("unable to retrieve instrumentation")
}
-func (rt *UserAgentRoundTripper) RoundTrip(req *http.Request) (*http.Response, error) {
- // create a deep copy of the request
- newReq := req.Clone(req.Context())
+// GenAIMetricAttrs holds gen_ai and network attributes for metrics
+type GenAIMetricAttrs struct {
+ OperationName string
+ ToolName string
+ PromptName string
+ NetworkProtocolName string
+ NetworkProtocolVersion string
```
This function is important because it defines how GenAI Toolbox Tutorial: MCP-First Database Tooling with Config-Driven Control Planes implements the patterns covered in this chapter.
@@ -209,11 +207,11 @@ This function is important because it defines how GenAI Toolbox Tutorial: MCP-Fi
```mermaid
flowchart TD
- A[ConvertNumbers]
- B[UnmarshalYAML]
- C[Unmarshal]
- D[WithUserAgent]
- E[UserAgentFromContext]
+ A[RoundTrip]
+ B[NewStrictDecoder]
+ C[WithLogger]
+ D[LoggerFromContext]
+ E[WithInstrumentation]
A --> B
B --> C
C --> D
diff --git a/tutorials/genai-toolbox-tutorial/06-deployment-and-observability-patterns.md b/tutorials/genai-toolbox-tutorial/06-deployment-and-observability-patterns.md
index ab62de6f..65964603 100644
--- a/tutorials/genai-toolbox-tutorial/06-deployment-and-observability-patterns.md
+++ b/tutorials/genai-toolbox-tutorial/06-deployment-and-observability-patterns.md
@@ -36,170 +36,168 @@ You now have a deployment model that balances speed with operational controls.
Next: [Chapter 7: CLI, Testing, and Development Workflow](07-cli-testing-and-development-workflow.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `internal/tools/tools.go`
+### `internal/log/log.go`
-The `NewDestructiveAnnotations` function in [`internal/tools/tools.go`](https://github.com/googleapis/genai-toolbox/blob/HEAD/internal/tools/tools.go) handles a key part of this chapter's functionality:
+The `NewStructuredLogger` function in [`internal/log/log.go`](https://github.com/googleapis/genai-toolbox/blob/HEAD/internal/log/log.go) handles a key part of this chapter's functionality:
```go
-}
-
-// NewDestructiveAnnotations creates default annotations for a destructive tool.
-// Use this for tools that create, update, or delete data.
-func NewDestructiveAnnotations() *ToolAnnotations {
- readOnly := false
- destructive := true
- return &ToolAnnotations{
- ReadOnlyHint: &readOnly,
- DestructiveHint: &destructive,
+ switch strings.ToLower(format) {
+ case "json":
+ return NewStructuredLogger(out, err, level)
+ case "standard":
+ return NewStdLogger(out, err, level)
+ default:
+ return nil, fmt.Errorf("logging format invalid: %s", format)
}
}
-// GetAnnotationsOrDefault returns the provided annotations if non-nil,
-// otherwise returns the result of calling defaultFn.
-func GetAnnotationsOrDefault(annotations *ToolAnnotations, defaultFn func() *ToolAnnotations) *ToolAnnotations {
- if annotations != nil {
- return annotations
- }
- return defaultFn()
+// StdLogger is the standard logger
+type StdLogger struct {
+ outLogger *slog.Logger
+ errLogger *slog.Logger
}
-type AccessToken string
-
-func (token AccessToken) ParseBearerToken() (string, error) {
- headerParts := strings.Split(string(token), " ")
- if len(headerParts) != 2 || strings.ToLower(headerParts[0]) != "bearer" {
- return "", util.NewClientServerError("authorization header must be in the format 'Bearer <token>'", http.StatusUnauthorized, nil)
+// NewStdLogger create a Logger that uses out and err for informational and error messages.
+func NewStdLogger(outW, errW io.Writer, logLevel string) (Logger, error) {
+ //Set log level
+ var programLevel = new(slog.LevelVar)
+ slogLevel, err := SeverityToLevel(logLevel)
+ if err != nil {
+ return nil, err
}
- return headerParts[1], nil
-}
+ programLevel.Set(slogLevel)
+
+ handlerOptions := &slog.HandlerOptions{Level: programLevel}
+ return &StdLogger{
+ outLogger: slog.New(NewValueTextHandler(outW, handlerOptions)),
+ errLogger: slog.New(NewValueTextHandler(errW, handlerOptions)),
+ }, nil
```
This function is important because it defines how GenAI Toolbox Tutorial: MCP-First Database Tooling with Config-Driven Control Planes implements the patterns covered in this chapter.
-### `internal/tools/tools.go`
+### `internal/log/log.go`
-The `GetAnnotationsOrDefault` function in [`internal/tools/tools.go`](https://github.com/googleapis/genai-toolbox/blob/HEAD/internal/tools/tools.go) handles a key part of this chapter's functionality:
+The `DebugContext` function in [`internal/log/log.go`](https://github.com/googleapis/genai-toolbox/blob/HEAD/internal/log/log.go) handles a key part of this chapter's functionality:
```go
}
-// GetAnnotationsOrDefault returns the provided annotations if non-nil,
-// otherwise returns the result of calling defaultFn.
-func GetAnnotationsOrDefault(annotations *ToolAnnotations, defaultFn func() *ToolAnnotations) *ToolAnnotations {
- if annotations != nil {
- return annotations
- }
- return defaultFn()
+// DebugContext logs debug messages
+func (sl *StdLogger) DebugContext(ctx context.Context, msg string, keysAndValues ...any) {
+ sl.outLogger.DebugContext(ctx, msg, keysAndValues...)
}
-type AccessToken string
+// InfoContext logs debug messages
+func (sl *StdLogger) InfoContext(ctx context.Context, msg string, keysAndValues ...any) {
+ sl.outLogger.InfoContext(ctx, msg, keysAndValues...)
+}
-func (token AccessToken) ParseBearerToken() (string, error) {
- headerParts := strings.Split(string(token), " ")
- if len(headerParts) != 2 || strings.ToLower(headerParts[0]) != "bearer" {
- return "", util.NewClientServerError("authorization header must be in the format 'Bearer <token>'", http.StatusUnauthorized, nil)
- }
- return headerParts[1], nil
+// WarnContext logs warning messages
+func (sl *StdLogger) WarnContext(ctx context.Context, msg string, keysAndValues ...any) {
+ sl.errLogger.WarnContext(ctx, msg, keysAndValues...)
}
-type Tool interface {
- Invoke(context.Context, SourceProvider, parameters.ParamValues, AccessToken) (any, util.ToolboxError)
- EmbedParams(context.Context, parameters.ParamValues, map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error)
- Manifest() Manifest
- McpManifest() McpManifest
- Authorized([]string) bool
- RequiresClientAuthorization(SourceProvider) (bool, error)
- ToConfig() ToolConfig
- GetAuthTokenHeaderName(SourceProvider) (string, error)
- GetParameters() parameters.Parameters
+// ErrorContext logs error messages
+func (sl *StdLogger) ErrorContext(ctx context.Context, msg string, keysAndValues ...any) {
+ sl.errLogger.ErrorContext(ctx, msg, keysAndValues...)
}
+
+// SlogLogger returns a single standard *slog.Logger that routes
+// records to the outLogger or errLogger based on the log level.
+func (sl *StdLogger) SlogLogger() *slog.Logger {
+ splitHandler := &SplitHandler{
+ OutHandler: sl.outLogger.Handler(),
+ ErrHandler: sl.errLogger.Handler(),
+ }
+ return slog.New(splitHandler)
+}
+
```
This function is important because it defines how GenAI Toolbox Tutorial: MCP-First Database Tooling with Config-Driven Control Planes implements the patterns covered in this chapter.
-### `internal/tools/tools.go`
+### `internal/log/log.go`
-The `ParseBearerToken` function in [`internal/tools/tools.go`](https://github.com/googleapis/genai-toolbox/blob/HEAD/internal/tools/tools.go) handles a key part of this chapter's functionality:
+The `InfoContext` function in [`internal/log/log.go`](https://github.com/googleapis/genai-toolbox/blob/HEAD/internal/log/log.go) handles a key part of this chapter's functionality:
```go
-type AccessToken string
+}
-func (token AccessToken) ParseBearerToken() (string, error) {
- headerParts := strings.Split(string(token), " ")
- if len(headerParts) != 2 || strings.ToLower(headerParts[0]) != "bearer" {
- return "", util.NewClientServerError("authorization header must be in the format 'Bearer <token>'", http.StatusUnauthorized, nil)
- }
- return headerParts[1], nil
+// InfoContext logs debug messages
+func (sl *StdLogger) InfoContext(ctx context.Context, msg string, keysAndValues ...any) {
+ sl.outLogger.InfoContext(ctx, msg, keysAndValues...)
}
-type Tool interface {
- Invoke(context.Context, SourceProvider, parameters.ParamValues, AccessToken) (any, util.ToolboxError)
- EmbedParams(context.Context, parameters.ParamValues, map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error)
- Manifest() Manifest
- McpManifest() McpManifest
- Authorized([]string) bool
- RequiresClientAuthorization(SourceProvider) (bool, error)
- ToConfig() ToolConfig
- GetAuthTokenHeaderName(SourceProvider) (string, error)
- GetParameters() parameters.Parameters
+// WarnContext logs warning messages
+func (sl *StdLogger) WarnContext(ctx context.Context, msg string, keysAndValues ...any) {
+ sl.errLogger.WarnContext(ctx, msg, keysAndValues...)
}
-// SourceProvider defines the minimal view of the server.ResourceManager
-// that the Tool package needs.
-// This is implemented to prevent import cycles.
-type SourceProvider interface {
- GetSource(sourceName string) (sources.Source, bool)
+// ErrorContext logs error messages
+func (sl *StdLogger) ErrorContext(ctx context.Context, msg string, keysAndValues ...any) {
+ sl.errLogger.ErrorContext(ctx, msg, keysAndValues...)
}
-// Manifest is the representation of tools sent to Client SDKs.
-type Manifest struct {
- Description string `json:"description"`
+// SlogLogger returns a single standard *slog.Logger that routes
+// records to the outLogger or errLogger based on the log level.
+func (sl *StdLogger) SlogLogger() *slog.Logger {
+ splitHandler := &SplitHandler{
+ OutHandler: sl.outLogger.Handler(),
+ ErrHandler: sl.errLogger.Handler(),
+ }
+ return slog.New(splitHandler)
+}
+
+const (
+ Debug = "DEBUG"
+ Info = "INFO"
+ Warn = "WARN"
+ Error = "ERROR"
```
This function is important because it defines how GenAI Toolbox Tutorial: MCP-First Database Tooling with Config-Driven Control Planes implements the patterns covered in this chapter.
-### `internal/tools/tools.go`
+### `internal/log/log.go`
-The `GetMcpManifest` function in [`internal/tools/tools.go`](https://github.com/googleapis/genai-toolbox/blob/HEAD/internal/tools/tools.go) handles a key part of this chapter's functionality:
+The `WarnContext` function in [`internal/log/log.go`](https://github.com/googleapis/genai-toolbox/blob/HEAD/internal/log/log.go) handles a key part of this chapter's functionality:
```go
}
-func GetMcpManifest(name, desc string, authInvoke []string, params parameters.Parameters, annotations *ToolAnnotations) McpManifest {
- inputSchema, authParams := params.McpManifest()
- mcpManifest := McpManifest{
- Name: name,
- Description: desc,
- InputSchema: inputSchema,
- Annotations: annotations,
- }
+// WarnContext logs warning messages
+func (sl *StdLogger) WarnContext(ctx context.Context, msg string, keysAndValues ...any) {
+ sl.errLogger.WarnContext(ctx, msg, keysAndValues...)
+}
- // construct metadata, if applicable
- metadata := make(map[string]any)
- if len(authInvoke) > 0 {
- metadata["toolbox/authInvoke"] = authInvoke
- }
- if len(authParams) > 0 {
- metadata["toolbox/authParam"] = authParams
- }
- if len(metadata) > 0 {
- mcpManifest.Metadata = metadata
- }
- return mcpManifest
+// ErrorContext logs error messages
+func (sl *StdLogger) ErrorContext(ctx context.Context, msg string, keysAndValues ...any) {
+ sl.errLogger.ErrorContext(ctx, msg, keysAndValues...)
}
-// Helper function that returns if a tool invocation request is authorized
-func IsAuthorized(authRequiredSources []string, verifiedAuthServices []string) bool {
- if len(authRequiredSources) == 0 {
- // no authorization requirement
- return true
+// SlogLogger returns a single standard *slog.Logger that routes
+// records to the outLogger or errLogger based on the log level.
+func (sl *StdLogger) SlogLogger() *slog.Logger {
+ splitHandler := &SplitHandler{
+ OutHandler: sl.outLogger.Handler(),
+ ErrHandler: sl.errLogger.Handler(),
}
- for _, a := range authRequiredSources {
+ return slog.New(splitHandler)
+}
+
+const (
+ Debug = "DEBUG"
+ Info = "INFO"
+ Warn = "WARN"
+ Error = "ERROR"
+)
+
+// Returns severity level based on string.
+func SeverityToLevel(s string) (slog.Level, error) {
+ switch strings.ToUpper(s) {
```
This function is important because it defines how GenAI Toolbox Tutorial: MCP-First Database Tooling with Config-Driven Control Planes implements the patterns covered in this chapter.
@@ -209,11 +207,11 @@ This function is important because it defines how GenAI Toolbox Tutorial: MCP-Fi
```mermaid
flowchart TD
- A[NewDestructiveAnnotations]
- B[GetAnnotationsOrDefault]
- C[ParseBearerToken]
- D[GetMcpManifest]
- E[IsAuthorized]
+ A[NewStructuredLogger]
+ B[DebugContext]
+ C[InfoContext]
+ D[WarnContext]
+ E[ErrorContext]
A --> B
B --> C
C --> D
diff --git a/tutorials/genai-toolbox-tutorial/07-cli-testing-and-development-workflow.md b/tutorials/genai-toolbox-tutorial/07-cli-testing-and-development-workflow.md
index c91c61db..c3dd909b 100644
--- a/tutorials/genai-toolbox-tutorial/07-cli-testing-and-development-workflow.md
+++ b/tutorials/genai-toolbox-tutorial/07-cli-testing-and-development-workflow.md
@@ -36,152 +36,165 @@ You now have a repeatable workflow for shipping Toolbox changes with lower regre
Next: [Chapter 8: Production Governance and Release Strategy](08-production-governance-and-release-strategy.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `internal/log/log.go`
+### `internal/server/mocks.go`
-The `SlogLogger` function in [`internal/log/log.go`](https://github.com/googleapis/genai-toolbox/blob/HEAD/internal/log/log.go) handles a key part of this chapter's functionality:
+The `SubstituteParams` function in [`internal/server/mocks.go`](https://github.com/googleapis/genai-toolbox/blob/HEAD/internal/server/mocks.go) handles a key part of this chapter's functionality:
```go
}
-// SlogLogger returns a single standard *slog.Logger that routes
-// records to the outLogger or errLogger based on the log level.
-func (sl *StdLogger) SlogLogger() *slog.Logger {
- splitHandler := &SplitHandler{
- OutHandler: sl.outLogger.Handler(),
- ErrHandler: sl.errLogger.Handler(),
+func (p MockPrompt) SubstituteParams(vals parameters.ParamValues) (any, error) {
+ return []prompts.Message{
+ {
+ Role: "user",
+ Content: fmt.Sprintf("substituted %s", p.Name),
+ },
+ }, nil
+}
+
+func (p MockPrompt) ParseArgs(data map[string]any, claimsMap map[string]map[string]any) (parameters.ParamValues, error) {
+ var params parameters.Parameters
+ for _, arg := range p.Args {
+ params = append(params, arg.Parameter)
+ }
+ return parameters.ParseParams(params, data, claimsMap)
+}
+
+func (p MockPrompt) Manifest() prompts.Manifest {
+ var argManifests []parameters.ParameterManifest
+ for _, arg := range p.Args {
+ argManifests = append(argManifests, arg.Manifest())
+ }
+ return prompts.Manifest{
+ Description: p.Description,
+ Arguments: argManifests,
}
- return slog.New(splitHandler)
-}
-
-const (
- Debug = "DEBUG"
- Info = "INFO"
- Warn = "WARN"
- Error = "ERROR"
-)
-
-// Returns severity level based on string.
-func SeverityToLevel(s string) (slog.Level, error) {
- switch strings.ToUpper(s) {
- case Debug:
- return slog.LevelDebug, nil
- case Info:
- return slog.LevelInfo, nil
- case Warn:
- return slog.LevelWarn, nil
- case Error:
- return slog.LevelError, nil
- default:
- return slog.Level(-5), fmt.Errorf("invalid log level")
+}
+
+func (p MockPrompt) McpManifest() prompts.McpManifest {
+ return prompts.GetMcpManifest(p.Name, p.Description, p.Args)
```
This function is important because it defines how GenAI Toolbox Tutorial: MCP-First Database Tooling with Config-Driven Control Planes implements the patterns covered in this chapter.
-### `internal/log/log.go`
+### `internal/server/mocks.go`
-The `Enabled` function in [`internal/log/log.go`](https://github.com/googleapis/genai-toolbox/blob/HEAD/internal/log/log.go) handles a key part of this chapter's functionality:
+The `ParseArgs` function in [`internal/server/mocks.go`](https://github.com/googleapis/genai-toolbox/blob/HEAD/internal/server/mocks.go) handles a key part of this chapter's functionality:
```go
}
-func (h *SplitHandler) Enabled(ctx context.Context, level slog.Level) bool {
- if level >= slog.LevelWarn {
- return h.ErrHandler.Enabled(ctx, level)
+func (p MockPrompt) ParseArgs(data map[string]any, claimsMap map[string]map[string]any) (parameters.ParamValues, error) {
+ var params parameters.Parameters
+ for _, arg := range p.Args {
+ params = append(params, arg.Parameter)
}
- return h.OutHandler.Enabled(ctx, level)
+ return parameters.ParseParams(params, data, claimsMap)
}
-func (h *SplitHandler) Handle(ctx context.Context, r slog.Record) error {
- if r.Level >= slog.LevelWarn {
- return h.ErrHandler.Handle(ctx, r)
+func (p MockPrompt) Manifest() prompts.Manifest {
+ var argManifests []parameters.ParameterManifest
+ for _, arg := range p.Args {
+ argManifests = append(argManifests, arg.Manifest())
+ }
+ return prompts.Manifest{
+ Description: p.Description,
+ Arguments: argManifests,
}
- return h.OutHandler.Handle(ctx, r)
}
-func (h *SplitHandler) WithAttrs(attrs []slog.Attr) slog.Handler {
- return &SplitHandler{
- OutHandler: h.OutHandler.WithAttrs(attrs),
- ErrHandler: h.ErrHandler.WithAttrs(attrs),
- }
+func (p MockPrompt) McpManifest() prompts.McpManifest {
+ return prompts.GetMcpManifest(p.Name, p.Description, p.Args)
}
-func (h *SplitHandler) WithGroup(name string) slog.Handler {
- return &SplitHandler{
- OutHandler: h.OutHandler.WithGroup(name),
- ErrHandler: h.ErrHandler.WithGroup(name),
- }
+func (p MockPrompt) ToConfig() prompts.PromptConfig {
+ return nil
}
```
This function is important because it defines how GenAI Toolbox Tutorial: MCP-First Database Tooling with Config-Driven Control Planes implements the patterns covered in this chapter.
-### `internal/log/log.go`
+### `internal/server/mocks.go`
-The `Handle` function in [`internal/log/log.go`](https://github.com/googleapis/genai-toolbox/blob/HEAD/internal/log/log.go) handles a key part of this chapter's functionality:
+The `Manifest` function in [`internal/server/mocks.go`](https://github.com/googleapis/genai-toolbox/blob/HEAD/internal/server/mocks.go) handles a key part of this chapter's functionality:
```go
- programLevel.Set(slogLevel)
-
- handlerOptions := &slog.HandlerOptions{Level: programLevel}
-
- return &StdLogger{
- outLogger: slog.New(NewValueTextHandler(outW, handlerOptions)),
- errLogger: slog.New(NewValueTextHandler(errW, handlerOptions)),
- }, nil
+ Description string
+ Params []parameters.Parameter
+ manifest tools.Manifest
+ unauthorized bool
+ requiresClientAuthorization bool
}
-// DebugContext logs debug messages
-func (sl *StdLogger) DebugContext(ctx context.Context, msg string, keysAndValues ...any) {
- sl.outLogger.DebugContext(ctx, msg, keysAndValues...)
+func (t MockTool) Invoke(context.Context, tools.SourceProvider, parameters.ParamValues, tools.AccessToken) (any, util.ToolboxError) {
+ mock := []any{t.Name}
+ return mock, nil
}
-// InfoContext logs debug messages
-func (sl *StdLogger) InfoContext(ctx context.Context, msg string, keysAndValues ...any) {
- sl.outLogger.InfoContext(ctx, msg, keysAndValues...)
+func (t MockTool) ToConfig() tools.ToolConfig {
+ return nil
}
-// WarnContext logs warning messages
-func (sl *StdLogger) WarnContext(ctx context.Context, msg string, keysAndValues ...any) {
- sl.errLogger.WarnContext(ctx, msg, keysAndValues...)
+// claims is a map of user info decoded from an auth token
+func (t MockTool) ParseParams(data map[string]any, claimsMap map[string]map[string]any) (parameters.ParamValues, error) {
+ return parameters.ParseParams(t.Params, data, claimsMap)
}
-// ErrorContext logs error messages
-func (sl *StdLogger) ErrorContext(ctx context.Context, msg string, keysAndValues ...any) {
- sl.errLogger.ErrorContext(ctx, msg, keysAndValues...)
+func (t MockTool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {
+ return parameters.EmbedParams(ctx, t.Params, paramValues, embeddingModelsMap, nil)
}
-// SlogLogger returns a single standard *slog.Logger that routes
-// records to the outLogger or errLogger based on the log level.
+func (t MockTool) Manifest() tools.Manifest {
+ pMs := make([]parameters.ParameterManifest, 0, len(t.Params))
+ for _, p := range t.Params {
+ pMs = append(pMs, p.Manifest())
+ }
+ return tools.Manifest{Description: t.Description, Parameters: pMs}
+}
```
This function is important because it defines how GenAI Toolbox Tutorial: MCP-First Database Tooling with Config-Driven Control Planes implements the patterns covered in this chapter.
-### `internal/log/log.go`
+### `internal/server/mocks.go`
-The `WithAttrs` function in [`internal/log/log.go`](https://github.com/googleapis/genai-toolbox/blob/HEAD/internal/log/log.go) handles a key part of this chapter's functionality:
+The `McpManifest` function in [`internal/server/mocks.go`](https://github.com/googleapis/genai-toolbox/blob/HEAD/internal/server/mocks.go) handles a key part of this chapter's functionality:
```go
}
-func (h *SplitHandler) WithAttrs(attrs []slog.Attr) slog.Handler {
- return &SplitHandler{
- OutHandler: h.OutHandler.WithAttrs(attrs),
- ErrHandler: h.ErrHandler.WithAttrs(attrs),
+func (t MockTool) McpManifest() tools.McpManifest {
+ properties := make(map[string]parameters.ParameterMcpManifest)
+ required := make([]string, 0)
+ authParams := make(map[string][]string)
+
+ for _, p := range t.Params {
+ name := p.GetName()
+ paramManifest, authParamList := p.McpManifest()
+ properties[name] = paramManifest
+ required = append(required, name)
+
+ if len(authParamList) > 0 {
+ authParams[name] = authParamList
+ }
}
-}
-func (h *SplitHandler) WithGroup(name string) slog.Handler {
- return &SplitHandler{
- OutHandler: h.OutHandler.WithGroup(name),
- ErrHandler: h.ErrHandler.WithGroup(name),
+ toolsSchema := parameters.McpToolsSchema{
+ Type: "object",
+ Properties: properties,
+ Required: required,
+ }
+
+ mcpManifest := tools.McpManifest{
+ Name: t.Name,
+ Description: t.Description,
+ InputSchema: toolsSchema,
}
-}
+ if len(authParams) > 0 {
+ mcpManifest.Metadata = map[string]any{
```
This function is important because it defines how GenAI Toolbox Tutorial: MCP-First Database Tooling with Config-Driven Control Planes implements the patterns covered in this chapter.
@@ -191,11 +204,11 @@ This function is important because it defines how GenAI Toolbox Tutorial: MCP-Fi
```mermaid
flowchart TD
- A[SlogLogger]
- B[Enabled]
- C[Handle]
- D[WithAttrs]
- E[WithGroup]
+ A[SubstituteParams]
+ B[ParseArgs]
+ C[Manifest]
+ D[McpManifest]
+ E[ToConfig]
A --> B
B --> C
C --> D
diff --git a/tutorials/genai-toolbox-tutorial/08-production-governance-and-release-strategy.md b/tutorials/genai-toolbox-tutorial/08-production-governance-and-release-strategy.md
index 8e4954a4..0e65581e 100644
--- a/tutorials/genai-toolbox-tutorial/08-production-governance-and-release-strategy.md
+++ b/tutorials/genai-toolbox-tutorial/08-production-governance-and-release-strategy.md
@@ -38,181 +38,165 @@ This chapter closes with operating discipline for pre-1.0 and post-1.0 evolution
You now have an operational model for running GenAI Toolbox as production MCP database infrastructure.
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `internal/server/mocks.go`
+### `internal/server/config.go`
-The `McpManifest` function in [`internal/server/mocks.go`](https://github.com/googleapis/genai-toolbox/blob/HEAD/internal/server/mocks.go) handles a key part of this chapter's functionality:
+The `UnmarshalYAMLToolsetConfig` function in [`internal/server/config.go`](https://github.com/googleapis/genai-toolbox/blob/HEAD/internal/server/config.go) handles a key part of this chapter's functionality:
```go
-}
-
-func (t MockTool) McpManifest() tools.McpManifest {
- properties := make(map[string]parameters.ParameterMcpManifest)
- required := make([]string, 0)
- authParams := make(map[string][]string)
-
- for _, p := range t.Params {
- name := p.GetName()
- paramManifest, authParamList := p.McpManifest()
- properties[name] = paramManifest
- required = append(required, name)
-
- if len(authParamList) > 0 {
- authParams[name] = authParamList
+ toolConfigs[name] = c
+ case "toolset":
+ c, err := UnmarshalYAMLToolsetConfig(ctx, name, resource)
+ if err != nil {
+ return nil, nil, nil, nil, nil, nil, fmt.Errorf("error unmarshaling %s: %s", kind, err)
+ }
+ if toolsetConfigs == nil {
+ toolsetConfigs = make(ToolsetConfigs)
+ }
+ toolsetConfigs[name] = c
+ case "embeddingModel":
+ c, err := UnmarshalYAMLEmbeddingModelConfig(ctx, name, resource)
+ if err != nil {
+ return nil, nil, nil, nil, nil, nil, fmt.Errorf("error unmarshaling %s: %s", kind, err)
+ }
+ if embeddingModelConfigs == nil {
+ embeddingModelConfigs = make(EmbeddingModelConfigs)
+ }
+ embeddingModelConfigs[name] = c
+ case "prompt":
+ c, err := UnmarshalYAMLPromptConfig(ctx, name, resource)
+ if err != nil {
+ return nil, nil, nil, nil, nil, nil, fmt.Errorf("error unmarshaling %s: %s", kind, err)
+ }
+ if promptConfigs == nil {
+ promptConfigs = make(PromptConfigs)
+ }
+ promptConfigs[name] = c
+ default:
+ return nil, nil, nil, nil, nil, nil, fmt.Errorf("invalid kind %s", kind)
}
}
-
- toolsSchema := parameters.McpToolsSchema{
- Type: "object",
- Properties: properties,
- Required: required,
- }
-
- mcpManifest := tools.McpManifest{
- Name: t.Name,
- Description: t.Description,
- InputSchema: toolsSchema,
- }
-
- if len(authParams) > 0 {
- mcpManifest.Metadata = map[string]any{
```
This function is important because it defines how GenAI Toolbox Tutorial: MCP-First Database Tooling with Config-Driven Control Planes implements the patterns covered in this chapter.
-### `internal/server/mocks.go`
+### `internal/server/config.go`
-The `GetAuthTokenHeaderName` function in [`internal/server/mocks.go`](https://github.com/googleapis/genai-toolbox/blob/HEAD/internal/server/mocks.go) handles a key part of this chapter's functionality:
+The `UnmarshalYAMLPromptConfig` function in [`internal/server/config.go`](https://github.com/googleapis/genai-toolbox/blob/HEAD/internal/server/config.go) handles a key part of this chapter's functionality:
```go
+ embeddingModelConfigs[name] = c
+ case "prompt":
+ c, err := UnmarshalYAMLPromptConfig(ctx, name, resource)
+ if err != nil {
+ return nil, nil, nil, nil, nil, nil, fmt.Errorf("error unmarshaling %s: %s", kind, err)
+ }
+ if promptConfigs == nil {
+ promptConfigs = make(PromptConfigs)
+ }
+ promptConfigs[name] = c
+ default:
+ return nil, nil, nil, nil, nil, nil, fmt.Errorf("invalid kind %s", kind)
+ }
+ }
+ return sourceConfigs, authServiceConfigs, embeddingModelConfigs, toolConfigs, toolsetConfigs, promptConfigs, nil
}
-func (t MockTool) GetAuthTokenHeaderName(tools.SourceProvider) (string, error) {
- return "Authorization", nil
-}
-
-// MockPrompt is used to mock prompts in tests
-type MockPrompt struct {
- Name string
- Description string
- Args prompts.Arguments
-}
-
-func (p MockPrompt) SubstituteParams(vals parameters.ParamValues) (any, error) {
- return []prompts.Message{
- {
- Role: "user",
- Content: fmt.Sprintf("substituted %s", p.Name),
- },
- }, nil
-}
-
-func (p MockPrompt) ParseArgs(data map[string]any, claimsMap map[string]map[string]any) (parameters.ParamValues, error) {
- var params parameters.Parameters
- for _, arg := range p.Args {
- params = append(params, arg.Parameter)
+func UnmarshalYAMLSourceConfig(ctx context.Context, name string, r map[string]any) (sources.SourceConfig, error) {
+ resourceType, ok := r["type"].(string)
+ if !ok {
+ return nil, fmt.Errorf("missing 'type' field or it is not a string")
+ }
+ dec, err := util.NewStrictDecoder(r)
+ if err != nil {
+ return nil, fmt.Errorf("error creating decoder: %w", err)
+ }
+ sourceConfig, err := sources.DecodeConfig(ctx, resourceType, name, dec)
+ if err != nil {
+ return nil, err
}
- return parameters.ParseParams(params, data, claimsMap)
+ return sourceConfig, nil
}
-
-func (p MockPrompt) Manifest() prompts.Manifest {
- var argManifests []parameters.ParameterManifest
```
This function is important because it defines how GenAI Toolbox Tutorial: MCP-First Database Tooling with Config-Driven Control Planes implements the patterns covered in this chapter.
-### `internal/server/mocks.go`
+### `internal/server/config.go`
-The `SubstituteParams` function in [`internal/server/mocks.go`](https://github.com/googleapis/genai-toolbox/blob/HEAD/internal/server/mocks.go) handles a key part of this chapter's functionality:
+The `NameValidation` function in [`internal/server/config.go`](https://github.com/googleapis/genai-toolbox/blob/HEAD/internal/server/config.go) handles a key part of this chapter's functionality:
```go
-}
-
-func (p MockPrompt) SubstituteParams(vals parameters.ParamValues) (any, error) {
- return []prompts.Message{
- {
- Role: "user",
- Content: fmt.Sprintf("substituted %s", p.Name),
- },
- }, nil
-}
-
-func (p MockPrompt) ParseArgs(data map[string]any, claimsMap map[string]map[string]any) (parameters.ParamValues, error) {
- var params parameters.Parameters
- for _, arg := range p.Args {
- params = append(params, arg.Parameter)
- }
- return parameters.ParseParams(params, data, claimsMap)
-}
-
-func (p MockPrompt) Manifest() prompts.Manifest {
- var argManifests []parameters.ParameterManifest
- for _, arg := range p.Args {
- argManifests = append(argManifests, arg.Manifest())
+// Tool names SHOULD NOT contain spaces, commas, or other special characters.
+// Tool names SHOULD be unique within a server.
+func NameValidation(name string) error {
+ strLen := len(name)
+ if strLen < 1 || strLen > 128 {
+ return fmt.Errorf("resource name SHOULD be between 1 and 128 characters in length (inclusive)")
}
- return prompts.Manifest{
- Description: p.Description,
- Arguments: argManifests,
+ validChars := regexp.MustCompile("^[a-zA-Z0-9_.-]+$")
+ isValid := validChars.MatchString(name)
+ if !isValid {
+ return fmt.Errorf("invalid character for resource name; only uppercase and lowercase ASCII letters (A-Z, a-z), digits (0-9), underscore (_), hyphen (-), and dot (.) is allowed")
}
+ return nil
}
-func (p MockPrompt) McpManifest() prompts.McpManifest {
- return prompts.GetMcpManifest(p.Name, p.Description, p.Args)
```
This function is important because it defines how GenAI Toolbox Tutorial: MCP-First Database Tooling with Config-Driven Control Planes implements the patterns covered in this chapter.
-### `internal/server/mocks.go`
+### `internal/server/config.go`
-The `ParseArgs` function in [`internal/server/mocks.go`](https://github.com/googleapis/genai-toolbox/blob/HEAD/internal/server/mocks.go) handles a key part of this chapter's functionality:
+The `the` interface in [`internal/server/config.go`](https://github.com/googleapis/genai-toolbox/blob/HEAD/internal/server/config.go) handles a key part of this chapter's functionality:
```go
-}
-
-func (p MockPrompt) ParseArgs(data map[string]any, claimsMap map[string]map[string]any) (parameters.ParamValues, error) {
- var params parameters.Parameters
- for _, arg := range p.Args {
- params = append(params, arg.Parameter)
- }
- return parameters.ParseParams(params, data, claimsMap)
-}
-
-func (p MockPrompt) Manifest() prompts.Manifest {
- var argManifests []parameters.ParameterManifest
- for _, arg := range p.Args {
- argManifests = append(argManifests, arg.Manifest())
- }
- return prompts.Manifest{
- Description: p.Description,
- Arguments: argManifests,
- }
-}
-
-func (p MockPrompt) McpManifest() prompts.McpManifest {
- return prompts.GetMcpManifest(p.Name, p.Description, p.Args)
-}
-
-func (p MockPrompt) ToConfig() prompts.PromptConfig {
- return nil
-}
-
+// Copyright 2024 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+package server
+
+import (
+ "bytes"
+ "context"
+ "fmt"
+ "io"
+ "regexp"
+ "strings"
+
+ yaml "github.com/goccy/go-yaml"
+ "github.com/googleapis/genai-toolbox/internal/auth"
+ "github.com/googleapis/genai-toolbox/internal/auth/generic"
+ "github.com/googleapis/genai-toolbox/internal/auth/google"
+ "github.com/googleapis/genai-toolbox/internal/embeddingmodels"
+ "github.com/googleapis/genai-toolbox/internal/embeddingmodels/gemini"
+ "github.com/googleapis/genai-toolbox/internal/prompts"
+ "github.com/googleapis/genai-toolbox/internal/sources"
+ "github.com/googleapis/genai-toolbox/internal/tools"
```
-This function is important because it defines how GenAI Toolbox Tutorial: MCP-First Database Tooling with Config-Driven Control Planes implements the patterns covered in this chapter.
+This interface is important because it defines how GenAI Toolbox Tutorial: MCP-First Database Tooling with Config-Driven Control Planes implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[McpManifest]
- B[GetAuthTokenHeaderName]
- C[SubstituteParams]
- D[ParseArgs]
- E[Manifest]
+ A[UnmarshalYAMLToolsetConfig]
+ B[UnmarshalYAMLPromptConfig]
+ C[NameValidation]
+ D[the]
+ E[NewValueTextHandler]
A --> B
B --> C
C --> D
diff --git a/tutorials/github-mcp-server-tutorial/01-getting-started.md b/tutorials/github-mcp-server-tutorial/01-getting-started.md
index 5b4cf058..6ffeee5e 100644
--- a/tutorials/github-mcp-server-tutorial/01-getting-started.md
+++ b/tutorials/github-mcp-server-tutorial/01-getting-started.md
@@ -45,51 +45,8 @@ You now have a safe baseline connection to GitHub MCP.
Next: [Chapter 2: Remote vs Local Architecture](02-remote-vs-local-architecture.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `ui/vite.config.ts`
-
-The `renameOutput` function in [`ui/vite.config.ts`](https://github.com/github/github-mcp-server/blob/HEAD/ui/vite.config.ts) handles a key part of this chapter's functionality:
-
-```ts
-
-// Plugin to rename the output file and remove the nested directory structure
-function renameOutput(): Plugin {
- return {
- name: "rename-output",
- enforce: "post",
- generateBundle(_, bundle) {
- // Find the HTML file and rename it
- for (const fileName of Object.keys(bundle)) {
- if (fileName.endsWith("index.html")) {
- const chunk = bundle[fileName];
- chunk.fileName = `${app}.html`;
- delete bundle[fileName];
- bundle[`${app}.html`] = chunk;
- break;
- }
- }
- },
- };
-}
-
-export default defineConfig({
- plugins: [react(), viteSingleFile(), renameOutput()],
- build: {
- outDir: resolve(__dirname, "../pkg/github/ui_dist"),
- emptyOutDir: false,
- rollupOptions: {
- input: resolve(__dirname, `src/apps/${app}/index.html`),
- },
- },
-});
-
-```
-
-This function is important because it defines how GitHub MCP Server Tutorial: Production GitHub Operations Through MCP implements the patterns covered in this chapter.
-
### `pkg/github/projects.go`
The `convertToMinimalStatusUpdate` function in [`pkg/github/projects.go`](https://github.com/github/github-mcp-server/blob/HEAD/pkg/github/projects.go) handles a key part of this chapter's functionality:
@@ -213,16 +170,57 @@ Use this tool to list projects for a user or organization, or list project field
This function is important because it defines how GitHub MCP Server Tutorial: Production GitHub Operations Through MCP implements the patterns covered in this chapter.
+### `pkg/github/projects.go`
+
+The `ProjectsGet` function in [`pkg/github/projects.go`](https://github.com/github/github-mcp-server/blob/HEAD/pkg/github/projects.go) handles a key part of this chapter's functionality:
+
+```go
+}
+
+// ProjectsGet returns the tool and handler for getting GitHub Projects resources.
+func ProjectsGet(t translations.TranslationHelperFunc) inventory.ServerTool {
+ tool := NewTool(
+ ToolsetMetadataProjects,
+ mcp.Tool{
+ Name: "projects_get",
+ Description: t("TOOL_PROJECTS_GET_DESCRIPTION", `Get details about specific GitHub Projects resources.
+Use this tool to get details about individual projects, project fields, and project items by their unique IDs.
+`),
+ Annotations: &mcp.ToolAnnotations{
+ Title: t("TOOL_PROJECTS_GET_USER_TITLE", "Get details of GitHub Projects resources"),
+ ReadOnlyHint: true,
+ },
+ InputSchema: &jsonschema.Schema{
+ Type: "object",
+ Properties: map[string]*jsonschema.Schema{
+ "method": {
+ Type: "string",
+ Description: "The method to execute",
+ Enum: []any{
+ projectsMethodGetProject,
+ projectsMethodGetProjectField,
+ projectsMethodGetProjectItem,
+ projectsMethodGetProjectStatusUpdate,
+ },
+ },
+ "owner_type": {
+ Type: "string",
+ Description: "Owner type (user or org). If not provided, will be automatically detected.",
+ Enum: []any{"user", "org"},
+```
+
+This function is important because it defines how GitHub MCP Server Tutorial: Production GitHub Operations Through MCP implements the patterns covered in this chapter.
+
## How These Components Connect
```mermaid
flowchart TD
- A[renameOutput]
- B[convertToMinimalStatusUpdate]
- C[derefString]
- D[ProjectsList]
- E[ProjectsGet]
+ A[convertToMinimalStatusUpdate]
+ B[derefString]
+ C[ProjectsList]
+ D[ProjectsGet]
+ E[ProjectsWrite]
A --> B
B --> C
C --> D
diff --git a/tutorials/github-mcp-server-tutorial/02-remote-vs-local-architecture.md b/tutorials/github-mcp-server-tutorial/02-remote-vs-local-architecture.md
index 8c52b4d8..d4797799 100644
--- a/tutorials/github-mcp-server-tutorial/02-remote-vs-local-architecture.md
+++ b/tutorials/github-mcp-server-tutorial/02-remote-vs-local-architecture.md
@@ -43,170 +43,168 @@ You now understand the operational boundaries of remote and local modes.
Next: [Chapter 3: Authentication and Token Strategy](03-authentication-and-token-strategy.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `pkg/github/notifications.go`
+### `cmd/github-mcp-server/generate_docs.go`
-The `ListNotifications` function in [`pkg/github/notifications.go`](https://github.com/github/github-mcp-server/blob/HEAD/pkg/github/notifications.go) handles a key part of this chapter's functionality:
+The `generateAllDocs` function in [`cmd/github-mcp-server/generate_docs.go`](https://github.com/github/github-mcp-server/blob/HEAD/cmd/github-mcp-server/generate_docs.go) handles a key part of this chapter's functionality:
```go
-)
-
-// ListNotifications creates a tool to list notifications for the current user.
-func ListNotifications(t translations.TranslationHelperFunc) inventory.ServerTool {
- return NewTool(
- ToolsetMetadataNotifications,
- mcp.Tool{
- Name: "list_notifications",
- Description: t("TOOL_LIST_NOTIFICATIONS_DESCRIPTION", "Lists all GitHub notifications for the authenticated user, including unread notifications, mentions, review requests, assignments, and updates on issues or pull requests. Use this tool whenever the user asks what to work on next, requests a summary of their GitHub activity, wants to see pending reviews, or needs to check for new updates or tasks. This tool is the primary way to discover actionable items, reminders, and outstanding work on GitHub. Always call this tool when asked what to work on next, what is pending, or what needs attention in GitHub."),
- Annotations: &mcp.ToolAnnotations{
- Title: t("TOOL_LIST_NOTIFICATIONS_USER_TITLE", "List notifications"),
- ReadOnlyHint: true,
- },
- InputSchema: WithPagination(&jsonschema.Schema{
- Type: "object",
- Properties: map[string]*jsonschema.Schema{
- "filter": {
- Type: "string",
- Description: "Filter notifications to, use default unless specified. Read notifications are ones that have already been acknowledged by the user. Participating notifications are those that the user is directly involved in, such as issues or pull requests they have commented on or created.",
- Enum: []any{FilterDefault, FilterIncludeRead, FilterOnlyParticipating},
- },
- "since": {
- Type: "string",
- Description: "Only show notifications updated after the given time (ISO 8601 format)",
- },
- "before": {
- Type: "string",
- Description: "Only show notifications updated before the given time (ISO 8601 format)",
- },
- "owner": {
- Type: "string",
- Description: "Optional repository owner. If provided with repo, only notifications for this repository are listed.",
+ Long: `Generate the automated sections of README.md and docs/remote-server.md with current tool and toolset information.`,
+ RunE: func(_ *cobra.Command, _ []string) error {
+ return generateAllDocs()
+ },
+}
+
+func init() {
+ rootCmd.AddCommand(generateDocsCmd)
+}
+
+func generateAllDocs() error {
+ for _, doc := range []struct {
+ path string
+ fn func(string) error
+ }{
+ // File to edit, function to generate its docs
+ {"README.md", generateReadmeDocs},
+ {"docs/remote-server.md", generateRemoteServerDocs},
+ {"docs/tool-renaming.md", generateDeprecatedAliasesDocs},
+ } {
+ if err := doc.fn(doc.path); err != nil {
+ return fmt.Errorf("failed to generate docs for %s: %w", doc.path, err)
+ }
+ fmt.Printf("Successfully updated %s with automated documentation\n", doc.path)
+ }
+ return nil
+}
+
+func generateReadmeDocs(readmePath string) error {
+ // Create translation helper
+ t, _ := translations.TranslationHelper()
+
```
This function is important because it defines how GitHub MCP Server Tutorial: Production GitHub Operations Through MCP implements the patterns covered in this chapter.
-### `pkg/github/notifications.go`
+### `cmd/github-mcp-server/generate_docs.go`
-The `DismissNotification` function in [`pkg/github/notifications.go`](https://github.com/github/github-mcp-server/blob/HEAD/pkg/github/notifications.go) handles a key part of this chapter's functionality:
+The `generateReadmeDocs` function in [`cmd/github-mcp-server/generate_docs.go`](https://github.com/github/github-mcp-server/blob/HEAD/cmd/github-mcp-server/generate_docs.go) handles a key part of this chapter's functionality:
```go
+ }{
+ // File to edit, function to generate its docs
+ {"README.md", generateReadmeDocs},
+ {"docs/remote-server.md", generateRemoteServerDocs},
+ {"docs/tool-renaming.md", generateDeprecatedAliasesDocs},
+ } {
+ if err := doc.fn(doc.path); err != nil {
+ return fmt.Errorf("failed to generate docs for %s: %w", doc.path, err)
+ }
+ fmt.Printf("Successfully updated %s with automated documentation\n", doc.path)
+ }
+ return nil
}
-// DismissNotification creates a tool to mark a notification as read/done.
-func DismissNotification(t translations.TranslationHelperFunc) inventory.ServerTool {
- return NewTool(
- ToolsetMetadataNotifications,
- mcp.Tool{
- Name: "dismiss_notification",
- Description: t("TOOL_DISMISS_NOTIFICATION_DESCRIPTION", "Dismiss a notification by marking it as read or done"),
- Annotations: &mcp.ToolAnnotations{
- Title: t("TOOL_DISMISS_NOTIFICATION_USER_TITLE", "Dismiss notification"),
- ReadOnlyHint: false,
- },
- InputSchema: &jsonschema.Schema{
- Type: "object",
- Properties: map[string]*jsonschema.Schema{
- "threadID": {
- Type: "string",
- Description: "The ID of the notification thread",
- },
- "state": {
- Type: "string",
- Description: "The new state of the notification (read/done)",
- Enum: []any{"read", "done"},
- },
- },
- Required: []string{"threadID", "state"},
- },
- },
- []scopes.Scope{scopes.Notifications},
- func(ctx context.Context, deps ToolDependencies, _ *mcp.CallToolRequest, args map[string]any) (*mcp.CallToolResult, any, error) {
- client, err := deps.GetClient(ctx)
+func generateReadmeDocs(readmePath string) error {
+ // Create translation helper
+ t, _ := translations.TranslationHelper()
+
+ // (not available to regular users) while including tools with FeatureFlagDisable.
+ // Build() can only fail if WithTools specifies invalid tools - not used here
+ r, _ := github.NewInventory(t).WithToolsets([]string{"all"}).Build()
+
+ // Generate toolsets documentation
+ toolsetsDoc := generateToolsetsDoc(r)
+
+ // Generate tools documentation
+ toolsDoc := generateToolsDoc(r)
+
+ // Read the current README.md
+ // #nosec G304 - readmePath is controlled by command line flag, not user input
+ content, err := os.ReadFile(readmePath)
+ if err != nil {
```
This function is important because it defines how GitHub MCP Server Tutorial: Production GitHub Operations Through MCP implements the patterns covered in this chapter.
-### `pkg/github/notifications.go`
+### `cmd/github-mcp-server/generate_docs.go`
-The `MarkAllNotificationsRead` function in [`pkg/github/notifications.go`](https://github.com/github/github-mcp-server/blob/HEAD/pkg/github/notifications.go) handles a key part of this chapter's functionality:
+The `generateRemoteServerDocs` function in [`cmd/github-mcp-server/generate_docs.go`](https://github.com/github/github-mcp-server/blob/HEAD/cmd/github-mcp-server/generate_docs.go) handles a key part of this chapter's functionality:
```go
+ // File to edit, function to generate its docs
+ {"README.md", generateReadmeDocs},
+ {"docs/remote-server.md", generateRemoteServerDocs},
+ {"docs/tool-renaming.md", generateDeprecatedAliasesDocs},
+ } {
+ if err := doc.fn(doc.path); err != nil {
+ return fmt.Errorf("failed to generate docs for %s: %w", doc.path, err)
+ }
+ fmt.Printf("Successfully updated %s with automated documentation\n", doc.path)
+ }
+ return nil
}
-// MarkAllNotificationsRead creates a tool to mark all notifications as read.
-func MarkAllNotificationsRead(t translations.TranslationHelperFunc) inventory.ServerTool {
- return NewTool(
- ToolsetMetadataNotifications,
- mcp.Tool{
- Name: "mark_all_notifications_read",
- Description: t("TOOL_MARK_ALL_NOTIFICATIONS_READ_DESCRIPTION", "Mark all notifications as read"),
- Annotations: &mcp.ToolAnnotations{
- Title: t("TOOL_MARK_ALL_NOTIFICATIONS_READ_USER_TITLE", "Mark all notifications as read"),
- ReadOnlyHint: false,
- },
- InputSchema: &jsonschema.Schema{
- Type: "object",
- Properties: map[string]*jsonschema.Schema{
- "lastReadAt": {
- Type: "string",
- Description: "Describes the last point that notifications were checked (optional). Default: Now",
- },
- "owner": {
- Type: "string",
- Description: "Optional repository owner. If provided with repo, only notifications for this repository are marked as read.",
- },
- "repo": {
- Type: "string",
- Description: "Optional repository name. If provided with owner, only notifications for this repository are marked as read.",
- },
- },
- },
- },
- []scopes.Scope{scopes.Notifications},
+func generateReadmeDocs(readmePath string) error {
+ // Create translation helper
+ t, _ := translations.TranslationHelper()
+
+ // (not available to regular users) while including tools with FeatureFlagDisable.
+ // Build() can only fail if WithTools specifies invalid tools - not used here
+ r, _ := github.NewInventory(t).WithToolsets([]string{"all"}).Build()
+
+ // Generate toolsets documentation
+ toolsetsDoc := generateToolsetsDoc(r)
+
+ // Generate tools documentation
+ toolsDoc := generateToolsDoc(r)
+
+ // Read the current README.md
+ // #nosec G304 - readmePath is controlled by command line flag, not user input
+ content, err := os.ReadFile(readmePath)
+ if err != nil {
+ return fmt.Errorf("failed to read README.md: %w", err)
```
This function is important because it defines how GitHub MCP Server Tutorial: Production GitHub Operations Through MCP implements the patterns covered in this chapter.
-### `pkg/github/notifications.go`
+### `cmd/github-mcp-server/generate_docs.go`
-The `GetNotificationDetails` function in [`pkg/github/notifications.go`](https://github.com/github/github-mcp-server/blob/HEAD/pkg/github/notifications.go) handles a key part of this chapter's functionality:
+The `octiconImg` function in [`cmd/github-mcp-server/generate_docs.go`](https://github.com/github/github-mcp-server/blob/HEAD/cmd/github-mcp-server/generate_docs.go) handles a key part of this chapter's functionality:
```go
}
-// GetNotificationDetails creates a tool to get details for a specific notification.
-func GetNotificationDetails(t translations.TranslationHelperFunc) inventory.ServerTool {
- return NewTool(
- ToolsetMetadataNotifications,
- mcp.Tool{
- Name: "get_notification_details",
- Description: t("TOOL_GET_NOTIFICATION_DETAILS_DESCRIPTION", "Get detailed information for a specific GitHub notification, always call this tool when the user asks for details about a specific notification, if you don't know the ID list notifications first."),
- Annotations: &mcp.ToolAnnotations{
- Title: t("TOOL_GET_NOTIFICATION_DETAILS_USER_TITLE", "Get notification details"),
- ReadOnlyHint: true,
- },
- InputSchema: &jsonschema.Schema{
- Type: "object",
- Properties: map[string]*jsonschema.Schema{
- "notificationID": {
- Type: "string",
- Description: "The ID of the notification",
- },
- },
- Required: []string{"notificationID"},
- },
- },
- []scopes.Scope{scopes.Notifications},
- func(ctx context.Context, deps ToolDependencies, _ *mcp.CallToolRequest, args map[string]any) (*mcp.CallToolResult, any, error) {
- client, err := deps.GetClient(ctx)
- if err != nil {
- return utils.NewToolResultErrorFromErr("failed to get GitHub client", err), nil, nil
- }
-
- notificationID, err := RequiredParam[string](args, "notificationID")
+// octiconImg returns an img tag for an Octicon that works with GitHub's light/dark theme.
+// Uses picture element with prefers-color-scheme for automatic theme switching.
+// References icons from the repo's pkg/octicons/icons directory.
+// Optional pathPrefix for files in subdirectories (e.g., "../" for docs/).
+func octiconImg(name string, pathPrefix ...string) string {
+ if name == "" {
+ return ""
+ }
+ prefix := ""
+ if len(pathPrefix) > 0 {
+ prefix = pathPrefix[0]
+ }
+ // Use picture element with media queries for light/dark mode support
+ // GitHub renders these correctly in markdown
+ lightIcon := fmt.Sprintf("%spkg/octicons/icons/%s-light.png", prefix, name)
+ darkIcon := fmt.Sprintf("%spkg/octicons/icons/%s-dark.png", prefix, name)
+ return fmt.Sprintf(`<picture><source media="(prefers-color-scheme: dark)" srcset="%s"><source media="(prefers-color-scheme: light)" srcset="%s"><img src="%s" width="20" height="20" alt="%s"></picture>`, darkIcon, lightIcon, lightIcon, name)
+}
+
+func generateToolsetsDoc(i *inventory.Inventory) string {
+ var buf strings.Builder
+
+ // Add table header and separator (with icon column)
+ buf.WriteString("| | Toolset | Description |\n")
+ buf.WriteString("| --- | ----------------------- | ------------------------------------------------------------- |\n")
+
+ // Add the context toolset row with custom description (strongly recommended)
+ // Get context toolset for its icon
+ contextIcon := octiconImg("person")
+ fmt.Fprintf(&buf, "| %s | `context` | **Strongly recommended**: Tools that provide context about the current user and GitHub context you are operating in |\n", contextIcon)
```
This function is important because it defines how GitHub MCP Server Tutorial: Production GitHub Operations Through MCP implements the patterns covered in this chapter.
@@ -216,11 +214,11 @@ This function is important because it defines how GitHub MCP Server Tutorial: Pr
```mermaid
flowchart TD
- A[ListNotifications]
- B[DismissNotification]
- C[MarkAllNotificationsRead]
- D[GetNotificationDetails]
- E[ManageNotificationSubscription]
+ A[generateAllDocs]
+ B[generateReadmeDocs]
+ C[generateRemoteServerDocs]
+ D[octiconImg]
+ E[generateToolsetsDoc]
A --> B
B --> C
C --> D
diff --git a/tutorials/github-mcp-server-tutorial/03-authentication-and-token-strategy.md b/tutorials/github-mcp-server-tutorial/03-authentication-and-token-strategy.md
index 2d649b88..29b08dbe 100644
--- a/tutorials/github-mcp-server-tutorial/03-authentication-and-token-strategy.md
+++ b/tutorials/github-mcp-server-tutorial/03-authentication-and-token-strategy.md
@@ -47,170 +47,168 @@ You now have an authentication strategy that balances compatibility and risk.
Next: [Chapter 4: Toolsets, Tools, and Dynamic Discovery](04-toolsets-tools-and-dynamic-discovery.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `pkg/github/actions.go`
+### `pkg/github/dependencies.go`
-The `deleteWorkflowRunLogs` function in [`pkg/github/actions.go`](https://github.com/github/github-mcp-server/blob/HEAD/pkg/github/actions.go) handles a key part of this chapter's functionality:
+The `NewToolFromHandler` function in [`pkg/github/dependencies.go`](https://github.com/github/github-mcp-server/blob/HEAD/pkg/github/dependencies.go) handles a key part of this chapter's functionality:
```go
- return cancelWorkflowRun(ctx, client, owner, repo, int64(runID))
- case actionsMethodDeleteWorkflowRunLogs:
- return deleteWorkflowRunLogs(ctx, client, owner, repo, int64(runID))
- default:
- return utils.NewToolResultError(fmt.Sprintf("unknown method: %s", method)), nil, nil
- }
- },
- )
- return tool
}
-// ActionsGetJobLogs returns the tool and handler for getting workflow job logs.
-func ActionsGetJobLogs(t translations.TranslationHelperFunc) inventory.ServerTool {
- tool := NewTool(
- ToolsetMetadataActions,
- mcp.Tool{
- Name: "get_job_logs",
- Description: t("TOOL_GET_JOB_LOGS_CONSOLIDATED_DESCRIPTION", `Get logs for GitHub Actions workflow jobs.
-Use this tool to retrieve logs for a specific job or all failed jobs in a workflow run.
-For single job logs, provide job_id. For all failed jobs in a run, provide run_id with failed_only=true.
-`),
- Annotations: &mcp.ToolAnnotations{
- Title: t("TOOL_GET_JOB_LOGS_CONSOLIDATED_USER_TITLE", "Get GitHub Actions workflow job logs"),
- ReadOnlyHint: true,
- },
- InputSchema: &jsonschema.Schema{
- Type: "object",
- Properties: map[string]*jsonschema.Schema{
- "owner": {
- Type: "string",
- Description: "Repository owner",
- },
+// NewToolFromHandler creates a ServerTool that retrieves ToolDependencies from context at call time.
+// Use this when you have a handler that conforms to mcp.ToolHandler directly.
+//
+// The handler function receives deps extracted from context via MustDepsFromContext.
+// Ensure ContextWithDeps is called to inject deps before any tool handlers are invoked.
+//
+// requiredScopes specifies the minimum OAuth scopes needed for this tool.
+// AcceptedScopes are automatically derived using the scope hierarchy.
+func NewToolFromHandler(
+ toolset inventory.ToolsetMetadata,
+ tool mcp.Tool,
+ requiredScopes []scopes.Scope,
+ handler func(ctx context.Context, deps ToolDependencies, req *mcp.CallToolRequest) (*mcp.CallToolResult, error),
+) inventory.ServerTool {
+ st := inventory.NewServerToolWithRawContextHandler(tool, toolset, func(ctx context.Context, req *mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+ deps := MustDepsFromContext(ctx)
+ return handler(ctx, deps, req)
+ })
+ st.RequiredScopes = scopes.ToStringSlice(requiredScopes...)
+ st.AcceptedScopes = scopes.ExpandScopes(requiredScopes...)
+ return st
+}
+
+type RequestDeps struct {
+ // Static dependencies
+ apiHosts utils.APIHostResolver
+ version string
+ lockdownMode bool
+ RepoAccessOpts []lockdown.RepoAccessOption
+ T translations.TranslationHelperFunc
```
This function is important because it defines how GitHub MCP Server Tutorial: Production GitHub Operations Through MCP implements the patterns covered in this chapter.
-### `pkg/github/minimal_types.go`
+### `pkg/github/dependencies.go`
-The `convertToMinimalPullRequestReview` function in [`pkg/github/minimal_types.go`](https://github.com/github/github-mcp-server/blob/HEAD/pkg/github/minimal_types.go) handles a key part of this chapter's functionality:
+The `NewRequestDeps` function in [`pkg/github/dependencies.go`](https://github.com/github/github-mcp-server/blob/HEAD/pkg/github/dependencies.go) handles a key part of this chapter's functionality:
```go
-// Helper functions
-
-func convertToMinimalPullRequestReview(review *github.PullRequestReview) MinimalPullRequestReview {
- m := MinimalPullRequestReview{
- ID: review.GetID(),
- State: review.GetState(),
- Body: review.GetBody(),
- HTMLURL: review.GetHTMLURL(),
- User: convertToMinimalUser(review.GetUser()),
- CommitID: review.GetCommitID(),
- AuthorAssociation: review.GetAuthorAssociation(),
- }
+}
- if review.SubmittedAt != nil {
- m.SubmittedAt = review.SubmittedAt.Format(time.RFC3339)
+// NewRequestDeps creates a RequestDeps with the provided clients and configuration.
+func NewRequestDeps(
+ apiHosts utils.APIHostResolver,
+ version string,
+ lockdownMode bool,
+ repoAccessOpts []lockdown.RepoAccessOption,
+ t translations.TranslationHelperFunc,
+ contentWindowSize int,
+ featureChecker inventory.FeatureFlagChecker,
+ obsv observability.Exporters,
+) *RequestDeps {
+ return &RequestDeps{
+ apiHosts: apiHosts,
+ version: version,
+ lockdownMode: lockdownMode,
+ RepoAccessOpts: repoAccessOpts,
+ T: t,
+ ContentWindowSize: contentWindowSize,
+ featureChecker: featureChecker,
+ obsv: obsv,
}
-
- return m
}
-func convertToMinimalIssue(issue *github.Issue) MinimalIssue {
- m := MinimalIssue{
- Number: issue.GetNumber(),
- Title: issue.GetTitle(),
- Body: issue.GetBody(),
- State: issue.GetState(),
- StateReason: issue.GetStateReason(),
- Draft: issue.GetDraft(),
- Locked: issue.GetLocked(),
- HTMLURL: issue.GetHTMLURL(),
- User: convertToMinimalUser(issue.GetUser()),
- AuthorAssociation: issue.GetAuthorAssociation(),
+// GetClient implements ToolDependencies.
+func (d *RequestDeps) GetClient(ctx context.Context) (*gogithub.Client, error) {
+ // extract the token from the context
+ tokenInfo, ok := ghcontext.GetTokenInfo(ctx)
+ if !ok {
+ return nil, fmt.Errorf("no token info in context")
+ }
```
This function is important because it defines how GitHub MCP Server Tutorial: Production GitHub Operations Through MCP implements the patterns covered in this chapter.
-### `pkg/github/minimal_types.go`
+### `pkg/github/dependencies.go`
-The `convertToMinimalIssue` function in [`pkg/github/minimal_types.go`](https://github.com/github/github-mcp-server/blob/HEAD/pkg/github/minimal_types.go) handles a key part of this chapter's functionality:
+The `GetClient` function in [`pkg/github/dependencies.go`](https://github.com/github/github-mcp-server/blob/HEAD/pkg/github/dependencies.go) handles a key part of this chapter's functionality:
```go
-}
+// The toolsets package uses `any` for deps and tool handlers type-assert to this interface.
+type ToolDependencies interface {
+ // GetClient returns a GitHub REST API client
+ GetClient(ctx context.Context) (*gogithub.Client, error)
-func convertToMinimalIssue(issue *github.Issue) MinimalIssue {
- m := MinimalIssue{
- Number: issue.GetNumber(),
- Title: issue.GetTitle(),
- Body: issue.GetBody(),
- State: issue.GetState(),
- StateReason: issue.GetStateReason(),
- Draft: issue.GetDraft(),
- Locked: issue.GetLocked(),
- HTMLURL: issue.GetHTMLURL(),
- User: convertToMinimalUser(issue.GetUser()),
- AuthorAssociation: issue.GetAuthorAssociation(),
- Comments: issue.GetComments(),
- }
+ // GetGQLClient returns a GitHub GraphQL client
+ GetGQLClient(ctx context.Context) (*githubv4.Client, error)
- if issue.CreatedAt != nil {
- m.CreatedAt = issue.CreatedAt.Format(time.RFC3339)
- }
- if issue.UpdatedAt != nil {
- m.UpdatedAt = issue.UpdatedAt.Format(time.RFC3339)
- }
- if issue.ClosedAt != nil {
- m.ClosedAt = issue.ClosedAt.Format(time.RFC3339)
- }
+ // GetRawClient returns a raw content client for GitHub
+ GetRawClient(ctx context.Context) (*raw.Client, error)
- for _, label := range issue.Labels {
- if label != nil {
- m.Labels = append(m.Labels, label.GetName())
- }
- }
+ // GetRepoAccessCache returns the lockdown mode repo access cache
+ GetRepoAccessCache(ctx context.Context) (*lockdown.RepoAccessCache, error)
+
+ // GetT returns the translation helper function
+ GetT() translations.TranslationHelperFunc
+
+ // GetFlags returns feature flags
+ GetFlags(ctx context.Context) FeatureFlags
+
+ // GetContentWindowSize returns the content window size for log truncation
+ GetContentWindowSize() int
+
+ // IsFeatureEnabled checks if a feature flag is enabled.
+ IsFeatureEnabled(ctx context.Context, flagName string) bool
+
+ // Logger returns the structured logger, optionally enriched with
+ // request-scoped data from ctx. Integrators provide their own slog.Handler
+ // to control where logs are sent.
+ Logger(ctx context.Context) *slog.Logger
+
+ // Metrics returns the metrics client
```
This function is important because it defines how GitHub MCP Server Tutorial: Production GitHub Operations Through MCP implements the patterns covered in this chapter.
-### `pkg/github/minimal_types.go`
+### `pkg/github/dependencies.go`
-The `fragmentToMinimalIssue` function in [`pkg/github/minimal_types.go`](https://github.com/github/github-mcp-server/blob/HEAD/pkg/github/minimal_types.go) handles a key part of this chapter's functionality:
+The `GetGQLClient` function in [`pkg/github/dependencies.go`](https://github.com/github/github-mcp-server/blob/HEAD/pkg/github/dependencies.go) handles a key part of this chapter's functionality:
```go
-}
+ GetClient(ctx context.Context) (*gogithub.Client, error)
-func fragmentToMinimalIssue(fragment IssueFragment) MinimalIssue {
- m := MinimalIssue{
- Number: int(fragment.Number),
- Title: sanitize.Sanitize(string(fragment.Title)),
- Body: sanitize.Sanitize(string(fragment.Body)),
- State: string(fragment.State),
- Comments: int(fragment.Comments.TotalCount),
- CreatedAt: fragment.CreatedAt.Format(time.RFC3339),
- UpdatedAt: fragment.UpdatedAt.Format(time.RFC3339),
- User: &MinimalUser{
- Login: string(fragment.Author.Login),
- },
- }
+ // GetGQLClient returns a GitHub GraphQL client
+ GetGQLClient(ctx context.Context) (*githubv4.Client, error)
- for _, label := range fragment.Labels.Nodes {
- m.Labels = append(m.Labels, string(label.Name))
- }
+ // GetRawClient returns a raw content client for GitHub
+ GetRawClient(ctx context.Context) (*raw.Client, error)
- return m
-}
+ // GetRepoAccessCache returns the lockdown mode repo access cache
+ GetRepoAccessCache(ctx context.Context) (*lockdown.RepoAccessCache, error)
-func convertToMinimalIssuesResponse(fragment IssueQueryFragment) MinimalIssuesResponse {
- minimalIssues := make([]MinimalIssue, 0, len(fragment.Nodes))
- for _, issue := range fragment.Nodes {
- minimalIssues = append(minimalIssues, fragmentToMinimalIssue(issue))
- }
+ // GetT returns the translation helper function
+ GetT() translations.TranslationHelperFunc
+
+ // GetFlags returns feature flags
+ GetFlags(ctx context.Context) FeatureFlags
+
+ // GetContentWindowSize returns the content window size for log truncation
+ GetContentWindowSize() int
+
+ // IsFeatureEnabled checks if a feature flag is enabled.
+ IsFeatureEnabled(ctx context.Context, flagName string) bool
+
+ // Logger returns the structured logger, optionally enriched with
+ // request-scoped data from ctx. Integrators provide their own slog.Handler
+ // to control where logs are sent.
+ Logger(ctx context.Context) *slog.Logger
+
+ // Metrics returns the metrics client
+ Metrics(ctx context.Context) metrics.Metrics
+}
- return MinimalIssuesResponse{
- Issues: minimalIssues,
- TotalCount: fragment.TotalCount,
```
This function is important because it defines how GitHub MCP Server Tutorial: Production GitHub Operations Through MCP implements the patterns covered in this chapter.
@@ -220,11 +218,11 @@ This function is important because it defines how GitHub MCP Server Tutorial: Pr
```mermaid
flowchart TD
- A[deleteWorkflowRunLogs]
- B[convertToMinimalPullRequestReview]
- C[convertToMinimalIssue]
- D[fragmentToMinimalIssue]
- E[convertToMinimalIssuesResponse]
+ A[NewToolFromHandler]
+ B[NewRequestDeps]
+ C[GetClient]
+ D[GetGQLClient]
+ E[GetRawClient]
A --> B
B --> C
C --> D
diff --git a/tutorials/github-mcp-server-tutorial/04-toolsets-tools-and-dynamic-discovery.md b/tutorials/github-mcp-server-tutorial/04-toolsets-tools-and-dynamic-discovery.md
index 113f1d8b..3eef52d4 100644
--- a/tutorials/github-mcp-server-tutorial/04-toolsets-tools-and-dynamic-discovery.md
+++ b/tutorials/github-mcp-server-tutorial/04-toolsets-tools-and-dynamic-discovery.md
@@ -42,66 +42,68 @@ You now know how to expose just enough capability for each task context.
Next: [Chapter 5: Host Integration Patterns](05-host-integration-patterns.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `pkg/github/discussions.go`
+### `pkg/github/actions.go`
-The `GetDiscussionComments` function in [`pkg/github/discussions.go`](https://github.com/github/github-mcp-server/blob/HEAD/pkg/github/discussions.go) handles a key part of this chapter's functionality:
+The `ActionsRunTrigger` function in [`pkg/github/actions.go`](https://github.com/github/github-mcp-server/blob/HEAD/pkg/github/actions.go) handles a key part of this chapter's functionality:
```go
- // The go-github library's Discussion type lacks isAnswered and answerChosenAt fields,
- // so we use map[string]interface{} for the response (consistent with other functions
- // like ListDiscussions and GetDiscussionComments).
- response := map[string]any{
- "number": int(d.Number),
- "title": string(d.Title),
- "body": string(d.Body),
- "url": string(d.URL),
- "closed": bool(d.Closed),
- "isAnswered": bool(d.IsAnswered),
- "createdAt": d.CreatedAt.Time,
- "category": map[string]any{
- "name": string(d.Category.Name),
- },
- }
-
- // Add optional timestamp fields if present
- if d.AnswerChosenAt != nil {
- response["answerChosenAt"] = d.AnswerChosenAt.Time
- }
-
- out, err := json.Marshal(response)
- if err != nil {
- return nil, nil, fmt.Errorf("failed to marshal discussion: %w", err)
- }
-
- return utils.NewToolResultText(string(out)), nil, nil
- },
- )
}
-func GetDiscussionComments(t translations.TranslationHelperFunc) inventory.ServerTool {
+// ActionsRunTrigger returns the tool and handler for triggering GitHub Actions workflows.
+func ActionsRunTrigger(t translations.TranslationHelperFunc) inventory.ServerTool {
+ tool := NewTool(
+ ToolsetMetadataActions,
+ mcp.Tool{
+ Name: "actions_run_trigger",
+ Description: t("TOOL_ACTIONS_RUN_TRIGGER_DESCRIPTION", "Trigger GitHub Actions workflow operations, including running, re-running, cancelling workflow runs, and deleting workflow run logs."),
+ Annotations: &mcp.ToolAnnotations{
+ Title: t("TOOL_ACTIONS_RUN_TRIGGER_USER_TITLE", "Trigger GitHub Actions workflow actions"),
+ ReadOnlyHint: false,
+ DestructiveHint: jsonschema.Ptr(true),
+ },
+ InputSchema: &jsonschema.Schema{
+ Type: "object",
+ Properties: map[string]*jsonschema.Schema{
+ "method": {
+ Type: "string",
+ Description: "The method to execute",
+ Enum: []any{
+ actionsMethodRunWorkflow,
+ actionsMethodRerunWorkflowRun,
+ actionsMethodRerunFailedJobs,
+ actionsMethodCancelWorkflowRun,
+ actionsMethodDeleteWorkflowRunLogs,
+ },
+ },
+ "owner": {
+ Type: "string",
+ Description: "Repository owner",
+ },
```
This function is important because it defines how GitHub MCP Server Tutorial: Production GitHub Operations Through MCP implements the patterns covered in this chapter.
-### `pkg/github/discussions.go`
+### `pkg/github/actions.go`
-The `ListDiscussionCategories` function in [`pkg/github/discussions.go`](https://github.com/github/github-mcp-server/blob/HEAD/pkg/github/discussions.go) handles a key part of this chapter's functionality:
+The `ActionsGetJobLogs` function in [`pkg/github/actions.go`](https://github.com/github/github-mcp-server/blob/HEAD/pkg/github/actions.go) handles a key part of this chapter's functionality:
```go
}
-func ListDiscussionCategories(t translations.TranslationHelperFunc) inventory.ServerTool {
- return NewTool(
- ToolsetMetadataDiscussions,
+// ActionsGetJobLogs returns the tool and handler for getting workflow job logs.
+func ActionsGetJobLogs(t translations.TranslationHelperFunc) inventory.ServerTool {
+ tool := NewTool(
+ ToolsetMetadataActions,
mcp.Tool{
- Name: "list_discussion_categories",
- Description: t("TOOL_LIST_DISCUSSION_CATEGORIES_DESCRIPTION", "List discussion categories with their id and name, for a repository or organisation."),
+ Name: "get_job_logs",
+ Description: t("TOOL_GET_JOB_LOGS_CONSOLIDATED_DESCRIPTION", `Get logs for GitHub Actions workflow jobs.
+Use this tool to retrieve logs for a specific job or all failed jobs in a workflow run.
+For single job logs, provide job_id. For all failed jobs in a run, provide run_id with failed_only=true.
+`),
Annotations: &mcp.ToolAnnotations{
- Title: t("TOOL_LIST_DISCUSSION_CATEGORIES_USER_TITLE", "List discussion categories"),
+ Title: t("TOOL_GET_JOB_LOGS_CONSOLIDATED_USER_TITLE", "Get GitHub Actions workflow job logs"),
ReadOnlyHint: true,
},
InputSchema: &jsonschema.Schema{
@@ -113,113 +115,109 @@ func ListDiscussionCategories(t translations.TranslationHelperFunc) inventory.Se
},
"repo": {
Type: "string",
- Description: "Repository name. If not provided, discussion categories will be queried at the organisation level.",
+ Description: "Repository name",
},
- },
- Required: []string{"owner"},
- },
- },
- []scopes.Scope{scopes.Repo},
- func(ctx context.Context, deps ToolDependencies, _ *mcp.CallToolRequest, args map[string]any) (*mcp.CallToolResult, any, error) {
- owner, err := RequiredParam[string](args, "owner")
- if err != nil {
- return utils.NewToolResultError(err.Error()), nil, nil
+ "job_id": {
+ Type: "number",
+ Description: "The unique identifier of the workflow job. Required when getting logs for a single job.",
+ },
+ "run_id": {
```
This function is important because it defines how GitHub MCP Server Tutorial: Production GitHub Operations Through MCP implements the patterns covered in this chapter.
-### `pkg/github/discussions.go`
+### `pkg/github/actions.go`
-The `for` interface in [`pkg/github/discussions.go`](https://github.com/github/github-mcp-server/blob/HEAD/pkg/github/discussions.go) handles a key part of this chapter's functionality:
+The `getWorkflow` function in [`pkg/github/actions.go`](https://github.com/github/github-mcp-server/blob/HEAD/pkg/github/actions.go) handles a key part of this chapter's functionality:
```go
-const DefaultGraphQLPageSize = 30
-
-// Common interface for all discussion query types
-type DiscussionQueryResult interface {
- GetDiscussionFragment() DiscussionFragment
-}
-
-// Implement the interface for all query types
-func (q *BasicNoOrder) GetDiscussionFragment() DiscussionFragment {
- return q.Repository.Discussions
-}
-
-func (q *BasicWithOrder) GetDiscussionFragment() DiscussionFragment {
- return q.Repository.Discussions
-}
-
-func (q *WithCategoryAndOrder) GetDiscussionFragment() DiscussionFragment {
- return q.Repository.Discussions
-}
-
-func (q *WithCategoryNoOrder) GetDiscussionFragment() DiscussionFragment {
- return q.Repository.Discussions
-}
-
-type DiscussionFragment struct {
- Nodes []NodeFragment
- PageInfo PageInfoFragment
- TotalCount githubv4.Int
+ switch method {
+ case actionsMethodGetWorkflow:
+ return getWorkflow(ctx, client, owner, repo, resourceID)
+ case actionsMethodGetWorkflowRun:
+ return getWorkflowRun(ctx, client, owner, repo, resourceIDInt)
+ case actionsMethodGetWorkflowJob:
+ return getWorkflowJob(ctx, client, owner, repo, resourceIDInt)
+ case actionsMethodDownloadWorkflowArtifact:
+ return downloadWorkflowArtifact(ctx, client, owner, repo, resourceIDInt)
+ case actionsMethodGetWorkflowRunUsage:
+ return getWorkflowRunUsage(ctx, client, owner, repo, resourceIDInt)
+ case actionsMethodGetWorkflowRunLogsURL:
+ return getWorkflowRunLogsURL(ctx, client, owner, repo, resourceIDInt)
+ default:
+ return utils.NewToolResultError(fmt.Sprintf("unknown method: %s", method)), nil, nil
+ }
+ },
+ )
+ return tool
}
-type NodeFragment struct {
- Number githubv4.Int
+// ActionsRunTrigger returns the tool and handler for triggering GitHub Actions workflows.
+func ActionsRunTrigger(t translations.TranslationHelperFunc) inventory.ServerTool {
+ tool := NewTool(
+ ToolsetMetadataActions,
+ mcp.Tool{
+ Name: "actions_run_trigger",
+ Description: t("TOOL_ACTIONS_RUN_TRIGGER_DESCRIPTION", "Trigger GitHub Actions workflow operations, including running, re-running, cancelling workflow runs, and deleting workflow run logs."),
+ Annotations: &mcp.ToolAnnotations{
+ Title: t("TOOL_ACTIONS_RUN_TRIGGER_USER_TITLE", "Trigger GitHub Actions workflow actions"),
+ ReadOnlyHint: false,
+ DestructiveHint: jsonschema.Ptr(true),
```
-This interface is important because it defines how GitHub MCP Server Tutorial: Production GitHub Operations Through MCP implements the patterns covered in this chapter.
+This function is important because it defines how GitHub MCP Server Tutorial: Production GitHub Operations Through MCP implements the patterns covered in this chapter.
-### `pkg/github/discussions.go`
+### `pkg/github/actions.go`
-The `for` interface in [`pkg/github/discussions.go`](https://github.com/github/github-mcp-server/blob/HEAD/pkg/github/discussions.go) handles a key part of this chapter's functionality:
+The `getWorkflowRun` function in [`pkg/github/actions.go`](https://github.com/github/github-mcp-server/blob/HEAD/pkg/github/actions.go) handles a key part of this chapter's functionality:
```go
-const DefaultGraphQLPageSize = 30
-
-// Common interface for all discussion query types
-type DiscussionQueryResult interface {
- GetDiscussionFragment() DiscussionFragment
-}
-
-// Implement the interface for all query types
-func (q *BasicNoOrder) GetDiscussionFragment() DiscussionFragment {
- return q.Repository.Discussions
-}
-
-func (q *BasicWithOrder) GetDiscussionFragment() DiscussionFragment {
- return q.Repository.Discussions
-}
-
-func (q *WithCategoryAndOrder) GetDiscussionFragment() DiscussionFragment {
- return q.Repository.Discussions
-}
-
-func (q *WithCategoryNoOrder) GetDiscussionFragment() DiscussionFragment {
- return q.Repository.Discussions
-}
-
-type DiscussionFragment struct {
- Nodes []NodeFragment
- PageInfo PageInfoFragment
- TotalCount githubv4.Int
+ return getWorkflow(ctx, client, owner, repo, resourceID)
+ case actionsMethodGetWorkflowRun:
+ return getWorkflowRun(ctx, client, owner, repo, resourceIDInt)
+ case actionsMethodGetWorkflowJob:
+ return getWorkflowJob(ctx, client, owner, repo, resourceIDInt)
+ case actionsMethodDownloadWorkflowArtifact:
+ return downloadWorkflowArtifact(ctx, client, owner, repo, resourceIDInt)
+ case actionsMethodGetWorkflowRunUsage:
+ return getWorkflowRunUsage(ctx, client, owner, repo, resourceIDInt)
+ case actionsMethodGetWorkflowRunLogsURL:
+ return getWorkflowRunLogsURL(ctx, client, owner, repo, resourceIDInt)
+ default:
+ return utils.NewToolResultError(fmt.Sprintf("unknown method: %s", method)), nil, nil
+ }
+ },
+ )
+ return tool
}
-type NodeFragment struct {
- Number githubv4.Int
+// ActionsRunTrigger returns the tool and handler for triggering GitHub Actions workflows.
+func ActionsRunTrigger(t translations.TranslationHelperFunc) inventory.ServerTool {
+ tool := NewTool(
+ ToolsetMetadataActions,
+ mcp.Tool{
+ Name: "actions_run_trigger",
+ Description: t("TOOL_ACTIONS_RUN_TRIGGER_DESCRIPTION", "Trigger GitHub Actions workflow operations, including running, re-running, cancelling workflow runs, and deleting workflow run logs."),
+ Annotations: &mcp.ToolAnnotations{
+ Title: t("TOOL_ACTIONS_RUN_TRIGGER_USER_TITLE", "Trigger GitHub Actions workflow actions"),
+ ReadOnlyHint: false,
+ DestructiveHint: jsonschema.Ptr(true),
+ },
+ InputSchema: &jsonschema.Schema{
```
-This interface is important because it defines how GitHub MCP Server Tutorial: Production GitHub Operations Through MCP implements the patterns covered in this chapter.
+This function is important because it defines how GitHub MCP Server Tutorial: Production GitHub Operations Through MCP implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[GetDiscussionComments]
- B[ListDiscussionCategories]
- C[for]
- D[for]
- E[var]
+ A[ActionsRunTrigger]
+ B[ActionsGetJobLogs]
+ C[getWorkflow]
+ D[getWorkflowRun]
+ E[getWorkflowJob]
A --> B
B --> C
C --> D
diff --git a/tutorials/github-mcp-server-tutorial/05-host-integration-patterns.md b/tutorials/github-mcp-server-tutorial/05-host-integration-patterns.md
index 3e0b8387..0144e528 100644
--- a/tutorials/github-mcp-server-tutorial/05-host-integration-patterns.md
+++ b/tutorials/github-mcp-server-tutorial/05-host-integration-patterns.md
@@ -43,170 +43,168 @@ You now have a host-portable integration strategy for GitHub MCP.
Next: [Chapter 6: Security, Governance, and Enterprise Controls](06-security-governance-and-enterprise-controls.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `pkg/github/params.go`
+### `pkg/github/discussions.go`
-The `toInt` function in [`pkg/github/params.go`](https://github.com/github/github-mcp-server/blob/HEAD/pkg/github/params.go) handles a key part of this chapter's functionality:
+The `var` interface in [`pkg/github/discussions.go`](https://github.com/github/github-mcp-server/blob/HEAD/pkg/github/discussions.go) handles a key part of this chapter's functionality:
```go
-}
-
-// toInt converts a value to int, handling both float64 and string representations.
-// Some MCP clients send numeric values as strings. It rejects NaN, ±Inf,
-// fractional values, and values outside the int range.
-func toInt(val any) (int, error) {
- var f float64
- switch v := val.(type) {
- case float64:
- f = v
- case string:
- var err error
- f, err = strconv.ParseFloat(v, 64)
- if err != nil {
- return 0, fmt.Errorf("invalid numeric value: %s", v)
- }
- default:
- return 0, fmt.Errorf("expected number, got %T", val)
- }
- if math.IsNaN(f) || math.IsInf(f, 0) {
- return 0, fmt.Errorf("non-finite numeric value")
- }
- if f != math.Trunc(f) {
- return 0, fmt.Errorf("non-integer numeric value: %v", f)
- }
- if f > math.MaxInt || f < math.MinInt {
- return 0, fmt.Errorf("numeric value out of int range: %v", f)
- }
- return int(f), nil
-}
-
-// toInt64 converts a value to int64, handling both float64 and string representations.
+ }
+
+ var categoryID *githubv4.ID
+ if category != "" {
+ id := githubv4.ID(category)
+ categoryID = &id
+ }
+
+ vars := map[string]any{
+ "owner": githubv4.String(owner),
+ "repo": githubv4.String(repo),
+ "first": githubv4.Int(*paginationParams.First),
+ }
+ if paginationParams.After != nil {
+ vars["after"] = githubv4.String(*paginationParams.After)
+ } else {
+ vars["after"] = (*githubv4.String)(nil)
+ }
+
+ // this is an extra check in case the tool description is misinterpreted, because
+ // we shouldn't use ordering unless both a 'field' and 'direction' are provided
+ useOrdering := orderBy != "" && direction != ""
+ if useOrdering {
+ vars["orderByField"] = githubv4.DiscussionOrderField(orderBy)
+ vars["orderByDirection"] = githubv4.OrderDirection(direction)
+ }
+
+ if categoryID != nil {
+ vars["categoryId"] = *categoryID
+ }
+
+ discussionQuery := getQueryType(useOrdering, categoryID)
```
-This function is important because it defines how GitHub MCP Server Tutorial: Production GitHub Operations Through MCP implements the patterns covered in this chapter.
+This interface is important because it defines how GitHub MCP Server Tutorial: Production GitHub Operations Through MCP implements the patterns covered in this chapter.
-### `pkg/github/params.go`
+### `pkg/github/minimal_types.go`
-The `toInt64` function in [`pkg/github/params.go`](https://github.com/github/github-mcp-server/blob/HEAD/pkg/github/params.go) handles a key part of this chapter's functionality:
+The `convertToMinimalPullRequestReview` function in [`pkg/github/minimal_types.go`](https://github.com/github/github-mcp-server/blob/HEAD/pkg/github/minimal_types.go) handles a key part of this chapter's functionality:
```go
-}
-
-// toInt64 converts a value to int64, handling both float64 and string representations.
-// Some MCP clients send numeric values as strings. It rejects NaN, ±Inf,
-// fractional values, and values that lose precision in the float64→int64 conversion.
-func toInt64(val any) (int64, error) {
- var f float64
- switch v := val.(type) {
- case float64:
- f = v
- case string:
- var err error
- f, err = strconv.ParseFloat(v, 64)
- if err != nil {
- return 0, fmt.Errorf("invalid numeric value: %s", v)
- }
- default:
- return 0, fmt.Errorf("expected number, got %T", val)
- }
- if math.IsNaN(f) || math.IsInf(f, 0) {
- return 0, fmt.Errorf("non-finite numeric value")
+// Helper functions
+
+func convertToMinimalPullRequestReview(review *github.PullRequestReview) MinimalPullRequestReview {
+ m := MinimalPullRequestReview{
+ ID: review.GetID(),
+ State: review.GetState(),
+ Body: review.GetBody(),
+ HTMLURL: review.GetHTMLURL(),
+ User: convertToMinimalUser(review.GetUser()),
+ CommitID: review.GetCommitID(),
+ AuthorAssociation: review.GetAuthorAssociation(),
}
- if f != math.Trunc(f) {
- return 0, fmt.Errorf("non-integer numeric value: %v", f)
- }
- result := int64(f)
- // Check round-trip to detect precision loss for large int64 values
- if float64(result) != f {
- return 0, fmt.Errorf("numeric value %v is too large to fit in int64", f)
+
+ if review.SubmittedAt != nil {
+ m.SubmittedAt = review.SubmittedAt.Format(time.RFC3339)
}
- return result, nil
+
+ return m
}
+
+func convertToMinimalIssue(issue *github.Issue) MinimalIssue {
+ m := MinimalIssue{
+ Number: issue.GetNumber(),
+ Title: issue.GetTitle(),
+ Body: issue.GetBody(),
+ State: issue.GetState(),
+ StateReason: issue.GetStateReason(),
+ Draft: issue.GetDraft(),
+ Locked: issue.GetLocked(),
+ HTMLURL: issue.GetHTMLURL(),
+ User: convertToMinimalUser(issue.GetUser()),
+ AuthorAssociation: issue.GetAuthorAssociation(),
```
This function is important because it defines how GitHub MCP Server Tutorial: Production GitHub Operations Through MCP implements the patterns covered in this chapter.
-### `pkg/github/params.go`
+### `pkg/github/minimal_types.go`
-The `RequiredInt` function in [`pkg/github/params.go`](https://github.com/github/github-mcp-server/blob/HEAD/pkg/github/params.go) handles a key part of this chapter's functionality:
+The `convertToMinimalIssue` function in [`pkg/github/minimal_types.go`](https://github.com/github/github-mcp-server/blob/HEAD/pkg/github/minimal_types.go) handles a key part of this chapter's functionality:
```go
}
-// RequiredInt is a helper function that can be used to fetch a requested parameter from the request.
-// It does the following checks:
-// 1. Checks if the parameter is present in the request.
-// 2. Checks if the parameter is of the expected type (float64 or numeric string).
-// 3. Checks if the parameter is not empty, i.e: non-zero value
-func RequiredInt(args map[string]any, p string) (int, error) {
- v, ok := args[p]
- if !ok {
- return 0, fmt.Errorf("missing required parameter: %s", p)
+func convertToMinimalIssue(issue *github.Issue) MinimalIssue {
+ m := MinimalIssue{
+ Number: issue.GetNumber(),
+ Title: issue.GetTitle(),
+ Body: issue.GetBody(),
+ State: issue.GetState(),
+ StateReason: issue.GetStateReason(),
+ Draft: issue.GetDraft(),
+ Locked: issue.GetLocked(),
+ HTMLURL: issue.GetHTMLURL(),
+ User: convertToMinimalUser(issue.GetUser()),
+ AuthorAssociation: issue.GetAuthorAssociation(),
+ Comments: issue.GetComments(),
}
- result, err := toInt(v)
- if err != nil {
- return 0, fmt.Errorf("parameter %s is not a valid number: %w", p, err)
+ if issue.CreatedAt != nil {
+ m.CreatedAt = issue.CreatedAt.Format(time.RFC3339)
}
-
- if result == 0 {
- return 0, fmt.Errorf("missing required parameter: %s", p)
+ if issue.UpdatedAt != nil {
+ m.UpdatedAt = issue.UpdatedAt.Format(time.RFC3339)
+ }
+ if issue.ClosedAt != nil {
+ m.ClosedAt = issue.ClosedAt.Format(time.RFC3339)
}
- return result, nil
-}
-
-// RequiredBigInt is a helper function that can be used to fetch a requested parameter from the request.
-// It does the following checks:
-// 1. Checks if the parameter is present in the request.
-// 2. Checks if the parameter is of the expected type (float64 or numeric string).
-// 3. Checks if the parameter is not empty, i.e: non-zero value.
-// 4. Validates that the float64 value can be safely converted to int64 without truncation.
-func RequiredBigInt(args map[string]any, p string) (int64, error) {
+ for _, label := range issue.Labels {
+ if label != nil {
+ m.Labels = append(m.Labels, label.GetName())
+ }
+ }
```
This function is important because it defines how GitHub MCP Server Tutorial: Production GitHub Operations Through MCP implements the patterns covered in this chapter.
-### `pkg/github/params.go`
+### `pkg/github/minimal_types.go`
-The `RequiredBigInt` function in [`pkg/github/params.go`](https://github.com/github/github-mcp-server/blob/HEAD/pkg/github/params.go) handles a key part of this chapter's functionality:
+The `fragmentToMinimalIssue` function in [`pkg/github/minimal_types.go`](https://github.com/github/github-mcp-server/blob/HEAD/pkg/github/minimal_types.go) handles a key part of this chapter's functionality:
```go
}
-// RequiredBigInt is a helper function that can be used to fetch a requested parameter from the request.
-// It does the following checks:
-// 1. Checks if the parameter is present in the request.
-// 2. Checks if the parameter is of the expected type (float64 or numeric string).
-// 3. Checks if the parameter is not empty, i.e: non-zero value.
-// 4. Validates that the float64 value can be safely converted to int64 without truncation.
-func RequiredBigInt(args map[string]any, p string) (int64, error) {
- val, ok := args[p]
- if !ok {
- return 0, fmt.Errorf("missing required parameter: %s", p)
+func fragmentToMinimalIssue(fragment IssueFragment) MinimalIssue {
+ m := MinimalIssue{
+ Number: int(fragment.Number),
+ Title: sanitize.Sanitize(string(fragment.Title)),
+ Body: sanitize.Sanitize(string(fragment.Body)),
+ State: string(fragment.State),
+ Comments: int(fragment.Comments.TotalCount),
+ CreatedAt: fragment.CreatedAt.Format(time.RFC3339),
+ UpdatedAt: fragment.UpdatedAt.Format(time.RFC3339),
+ User: &MinimalUser{
+ Login: string(fragment.Author.Login),
+ },
}
- result, err := toInt64(val)
- if err != nil {
- return 0, fmt.Errorf("parameter %s is not a valid number: %w", p, err)
+ for _, label := range fragment.Labels.Nodes {
+ m.Labels = append(m.Labels, string(label.Name))
}
- if result == 0 {
- return 0, fmt.Errorf("missing required parameter: %s", p)
- }
-
- return result, nil
+ return m
}
-// OptionalParam is a helper function that can be used to fetch a requested parameter from the request.
-// It does the following checks:
-// 1. Checks if the parameter is present in the request, if not, it returns its zero-value
-// 2. If it is present, it checks if the parameter is of the expected type and returns it
-func OptionalParam[T any](args map[string]any, p string) (T, error) {
- var zero T
+func convertToMinimalIssuesResponse(fragment IssueQueryFragment) MinimalIssuesResponse {
+ minimalIssues := make([]MinimalIssue, 0, len(fragment.Nodes))
+ for _, issue := range fragment.Nodes {
+ minimalIssues = append(minimalIssues, fragmentToMinimalIssue(issue))
+ }
+
+ return MinimalIssuesResponse{
+ Issues: minimalIssues,
+ TotalCount: fragment.TotalCount,
```
This function is important because it defines how GitHub MCP Server Tutorial: Production GitHub Operations Through MCP implements the patterns covered in this chapter.
@@ -216,11 +214,11 @@ This function is important because it defines how GitHub MCP Server Tutorial: Pr
```mermaid
flowchart TD
- A[toInt]
- B[toInt64]
- C[RequiredInt]
- D[RequiredBigInt]
- E[OptionalIntParam]
+ A[var]
+ B[convertToMinimalPullRequestReview]
+ C[convertToMinimalIssue]
+ D[fragmentToMinimalIssue]
+ E[convertToMinimalIssuesResponse]
A --> B
B --> C
C --> D
diff --git a/tutorials/github-mcp-server-tutorial/06-security-governance-and-enterprise-controls.md b/tutorials/github-mcp-server-tutorial/06-security-governance-and-enterprise-controls.md
index 05a3fc36..3dae8fa9 100644
--- a/tutorials/github-mcp-server-tutorial/06-security-governance-and-enterprise-controls.md
+++ b/tutorials/github-mcp-server-tutorial/06-security-governance-and-enterprise-controls.md
@@ -41,170 +41,168 @@ You now have a governance model for secure, policy-aligned GitHub MCP usage.
Next: [Chapter 7: Troubleshooting, Read-Only, and Lockdown Operations](07-troubleshooting-read-only-and-lockdown-operations.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `pkg/github/labels.go`
+### `pkg/github/params.go`
-The `GetLabelForLabelsToolset` function in [`pkg/github/labels.go`](https://github.com/github/github-mcp-server/blob/HEAD/pkg/github/labels.go) handles a key part of this chapter's functionality:
+The `convertStringSliceToBigIntSlice` function in [`pkg/github/params.go`](https://github.com/github/github-mcp-server/blob/HEAD/pkg/github/params.go) handles a key part of this chapter's functionality:
```go
}
-// GetLabelForLabelsToolset returns the same GetLabel tool but registered in the labels toolset.
-// This provides conformance with the original behavior where get_label was in both toolsets.
-func GetLabelForLabelsToolset(t translations.TranslationHelperFunc) inventory.ServerTool {
- tool := GetLabel(t)
- tool.Toolset = ToolsetLabels
- return tool
+func convertStringSliceToBigIntSlice(s []string) ([]int64, error) {
+ int64Slice := make([]int64, len(s))
+ for i, str := range s {
+ val, err := convertStringToBigInt(str, 0)
+ if err != nil {
+ return nil, fmt.Errorf("failed to convert element %d (%s) to int64: %w", i, str, err)
+ }
+ int64Slice[i] = val
+ }
+ return int64Slice, nil
+}
+
+func convertStringToBigInt(s string, def int64) (int64, error) {
+ v, err := strconv.ParseInt(s, 10, 64)
+ if err != nil {
+ return def, fmt.Errorf("failed to convert string %s to int64: %w", s, err)
+ }
+ return v, nil
}
-// ListLabels lists labels from a repository
-func ListLabels(t translations.TranslationHelperFunc) inventory.ServerTool {
- return NewTool(
- ToolsetLabels,
- mcp.Tool{
- Name: "list_label",
- Description: t("TOOL_LIST_LABEL_DESCRIPTION", "List labels from a repository"),
- Annotations: &mcp.ToolAnnotations{
- Title: t("TOOL_LIST_LABEL_DESCRIPTION", "List labels from a repository."),
- ReadOnlyHint: true,
- },
- InputSchema: &jsonschema.Schema{
- Type: "object",
- Properties: map[string]*jsonschema.Schema{
- "owner": {
- Type: "string",
- Description: "Repository owner (username or organization name) - required for all operations",
- },
- "repo": {
- Type: "string",
- Description: "Repository name - required for all operations",
- },
+// OptionalBigIntArrayParam is a helper function that can be used to fetch a requested parameter from the request.
+// It does the following checks:
+// 1. Checks if the parameter is present in the request, if not, it returns an empty slice
+// 2. If it is present, iterates the elements, checks each is a string, and converts them to int64 values
+func OptionalBigIntArrayParam(args map[string]any, p string) ([]int64, error) {
+ // Check if the parameter is present in the request
+ if _, ok := args[p]; !ok {
+ return []int64{}, nil
+ }
+
```
This function is important because it defines how GitHub MCP Server Tutorial: Production GitHub Operations Through MCP implements the patterns covered in this chapter.
-### `pkg/github/labels.go`
+### `pkg/github/params.go`
-The `ListLabels` function in [`pkg/github/labels.go`](https://github.com/github/github-mcp-server/blob/HEAD/pkg/github/labels.go) handles a key part of this chapter's functionality:
+The `convertStringToBigInt` function in [`pkg/github/params.go`](https://github.com/github/github-mcp-server/blob/HEAD/pkg/github/params.go) handles a key part of this chapter's functionality:
```go
+ int64Slice := make([]int64, len(s))
+ for i, str := range s {
+ val, err := convertStringToBigInt(str, 0)
+ if err != nil {
+ return nil, fmt.Errorf("failed to convert element %d (%s) to int64: %w", i, str, err)
+ }
+ int64Slice[i] = val
+ }
+ return int64Slice, nil
}
-// ListLabels lists labels from a repository
-func ListLabels(t translations.TranslationHelperFunc) inventory.ServerTool {
- return NewTool(
- ToolsetLabels,
- mcp.Tool{
- Name: "list_label",
- Description: t("TOOL_LIST_LABEL_DESCRIPTION", "List labels from a repository"),
- Annotations: &mcp.ToolAnnotations{
- Title: t("TOOL_LIST_LABEL_DESCRIPTION", "List labels from a repository."),
- ReadOnlyHint: true,
- },
- InputSchema: &jsonschema.Schema{
- Type: "object",
- Properties: map[string]*jsonschema.Schema{
- "owner": {
- Type: "string",
- Description: "Repository owner (username or organization name) - required for all operations",
- },
- "repo": {
- Type: "string",
- Description: "Repository name - required for all operations",
- },
- },
- Required: []string{"owner", "repo"},
- },
- },
- []scopes.Scope{scopes.Repo},
- func(ctx context.Context, deps ToolDependencies, _ *mcp.CallToolRequest, args map[string]any) (*mcp.CallToolResult, any, error) {
- owner, err := RequiredParam[string](args, "owner")
- if err != nil {
+func convertStringToBigInt(s string, def int64) (int64, error) {
+ v, err := strconv.ParseInt(s, 10, 64)
+ if err != nil {
+ return def, fmt.Errorf("failed to convert string %s to int64: %w", s, err)
+ }
+ return v, nil
+}
+
+// OptionalBigIntArrayParam is a helper function that can be used to fetch a requested parameter from the request.
+// It does the following checks:
+// 1. Checks if the parameter is present in the request, if not, it returns an empty slice
+// 2. If it is present, iterates the elements, checks each is a string, and converts them to int64 values
+func OptionalBigIntArrayParam(args map[string]any, p string) ([]int64, error) {
+ // Check if the parameter is present in the request
+ if _, ok := args[p]; !ok {
+ return []int64{}, nil
+ }
+
+ switch v := args[p].(type) {
+ case nil:
+ return []int64{}, nil
```
This function is important because it defines how GitHub MCP Server Tutorial: Production GitHub Operations Through MCP implements the patterns covered in this chapter.
-### `pkg/github/labels.go`
+### `pkg/github/params.go`
-The `LabelWrite` function in [`pkg/github/labels.go`](https://github.com/github/github-mcp-server/blob/HEAD/pkg/github/labels.go) handles a key part of this chapter's functionality:
+The `OptionalBigIntArrayParam` function in [`pkg/github/params.go`](https://github.com/github/github-mcp-server/blob/HEAD/pkg/github/params.go) handles a key part of this chapter's functionality:
```go
}
-// LabelWrite handles create, update, and delete operations for GitHub labels
-func LabelWrite(t translations.TranslationHelperFunc) inventory.ServerTool {
- return NewTool(
- ToolsetLabels,
- mcp.Tool{
- Name: "label_write",
- Description: t("TOOL_LABEL_WRITE_DESCRIPTION", "Perform write operations on repository labels. To set labels on issues, use the 'update_issue' tool."),
- Annotations: &mcp.ToolAnnotations{
- Title: t("TOOL_LABEL_WRITE_TITLE", "Write operations on repository labels."),
- ReadOnlyHint: false,
- },
- InputSchema: &jsonschema.Schema{
- Type: "object",
- Properties: map[string]*jsonschema.Schema{
- "method": {
- Type: "string",
- Description: "Operation to perform: 'create', 'update', or 'delete'",
- Enum: []any{"create", "update", "delete"},
- },
- "owner": {
- Type: "string",
- Description: "Repository owner (username or organization name)",
- },
- "repo": {
- Type: "string",
- Description: "Repository name",
- },
- "name": {
- Type: "string",
- Description: "Label name - required for all operations",
+// OptionalBigIntArrayParam is a helper function that can be used to fetch a requested parameter from the request.
+// It does the following checks:
+// 1. Checks if the parameter is present in the request, if not, it returns an empty slice
+// 2. If it is present, iterates the elements, checks each is a string, and converts them to int64 values
+func OptionalBigIntArrayParam(args map[string]any, p string) ([]int64, error) {
+ // Check if the parameter is present in the request
+ if _, ok := args[p]; !ok {
+ return []int64{}, nil
+ }
+
+ switch v := args[p].(type) {
+ case nil:
+ return []int64{}, nil
+ case []string:
+ return convertStringSliceToBigIntSlice(v)
+ case []any:
+ int64Slice := make([]int64, len(v))
+ for i, v := range v {
+ s, ok := v.(string)
+ if !ok {
+ return []int64{}, fmt.Errorf("parameter %s is not of type string, is %T", p, v)
+ }
+ val, err := convertStringToBigInt(s, 0)
+ if err != nil {
+ return []int64{}, fmt.Errorf("parameter %s: failed to convert element %d (%s) to int64: %w", p, i, s, err)
+ }
+ int64Slice[i] = val
+ }
+ return int64Slice, nil
+ default:
```
This function is important because it defines how GitHub MCP Server Tutorial: Production GitHub Operations Through MCP implements the patterns covered in this chapter.
-### `pkg/github/labels.go`
+### `pkg/github/params.go`
-The `getRepositoryID` function in [`pkg/github/labels.go`](https://github.com/github/github-mcp-server/blob/HEAD/pkg/github/labels.go) handles a key part of this chapter's functionality:
+The `WithPagination` function in [`pkg/github/params.go`](https://github.com/github/github-mcp-server/blob/HEAD/pkg/github/params.go) handles a key part of this chapter's functionality:
```go
+}
- // Get repository ID
- repoID, err := getRepositoryID(ctx, client, owner, repo)
- if err != nil {
- return ghErrors.NewGitHubGraphQLErrorResponse(ctx, "Failed to find repository", err), nil, nil
- }
-
- input := githubv4.CreateLabelInput{
- RepositoryID: repoID,
- Name: githubv4.String(name),
- Color: githubv4.String(color),
- }
- if description != "" {
- d := githubv4.String(description)
- input.Description = &d
- }
-
- var mutation struct {
- CreateLabel struct {
- Label struct {
- Name githubv4.String
- ID githubv4.ID
- }
- } `graphql:"createLabel(input: $input)"`
- }
-
- if err := client.Mutate(ctx, &mutation, input, nil); err != nil {
- return ghErrors.NewGitHubGraphQLErrorResponse(ctx, "Failed to create label", err), nil, nil
- }
-
- return utils.NewToolResultText(fmt.Sprintf("label '%s' created successfully", mutation.CreateLabel.Label.Name)), nil, nil
+// WithPagination adds REST API pagination parameters to a tool.
+// https://docs.github.com/en/rest/using-the-rest-api/using-pagination-in-the-rest-api
+func WithPagination(schema *jsonschema.Schema) *jsonschema.Schema {
+ schema.Properties["page"] = &jsonschema.Schema{
+ Type: "number",
+ Description: "Page number for pagination (min 1)",
+ Minimum: jsonschema.Ptr(1.0),
+ }
+
+ schema.Properties["perPage"] = &jsonschema.Schema{
+ Type: "number",
+ Description: "Results per page for pagination (min 1, max 100)",
+ Minimum: jsonschema.Ptr(1.0),
+ Maximum: jsonschema.Ptr(100.0),
+ }
+
+ return schema
+}
+// WithUnifiedPagination adds REST API pagination parameters to a tool.
+// GraphQL tools will use this and convert page/perPage to GraphQL cursor parameters internally.
+func WithUnifiedPagination(schema *jsonschema.Schema) *jsonschema.Schema {
+ schema.Properties["page"] = &jsonschema.Schema{
+ Type: "number",
+ Description: "Page number for pagination (min 1)",
+ Minimum: jsonschema.Ptr(1.0),
+ }
+
+ schema.Properties["perPage"] = &jsonschema.Schema{
+ Type: "number",
```
This function is important because it defines how GitHub MCP Server Tutorial: Production GitHub Operations Through MCP implements the patterns covered in this chapter.
@@ -214,11 +212,11 @@ This function is important because it defines how GitHub MCP Server Tutorial: Pr
```mermaid
flowchart TD
- A[GetLabelForLabelsToolset]
- B[ListLabels]
- C[LabelWrite]
- D[getRepositoryID]
- E[getLabelID]
+ A[convertStringSliceToBigIntSlice]
+ B[convertStringToBigInt]
+ C[OptionalBigIntArrayParam]
+ D[WithPagination]
+ E[WithUnifiedPagination]
A --> B
B --> C
C --> D
diff --git a/tutorials/github-mcp-server-tutorial/07-troubleshooting-read-only-and-lockdown-operations.md b/tutorials/github-mcp-server-tutorial/07-troubleshooting-read-only-and-lockdown-operations.md
index c03abeff..e04a0903 100644
--- a/tutorials/github-mcp-server-tutorial/07-troubleshooting-read-only-and-lockdown-operations.md
+++ b/tutorials/github-mcp-server-tutorial/07-troubleshooting-read-only-and-lockdown-operations.md
@@ -41,170 +41,168 @@ You now have a troubleshooting runbook for stable GitHub MCP operations.
Next: [Chapter 8: Contribution and Upgrade Workflow](08-contribution-and-upgrade-workflow.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `pkg/github/dependencies.go`
+### `cmd/mcpcurl/main.go`
-The `GetGQLClient` function in [`pkg/github/dependencies.go`](https://github.com/github/github-mcp-server/blob/HEAD/pkg/github/dependencies.go) handles a key part of this chapter's functionality:
+The `buildArgumentsMap` function in [`cmd/mcpcurl/main.go`](https://github.com/github/github-mcp-server/blob/HEAD/cmd/mcpcurl/main.go) handles a key part of this chapter's functionality:
```go
- GetClient(ctx context.Context) (*gogithub.Client, error)
-
- // GetGQLClient returns a GitHub GraphQL client
- GetGQLClient(ctx context.Context) (*githubv4.Client, error)
-
- // GetRawClient returns a raw content client for GitHub
- GetRawClient(ctx context.Context) (*raw.Client, error)
-
- // GetRepoAccessCache returns the lockdown mode repo access cache
- GetRepoAccessCache(ctx context.Context) (*lockdown.RepoAccessCache, error)
-
- // GetT returns the translation helper function
- GetT() translations.TranslationHelperFunc
-
- // GetFlags returns feature flags
- GetFlags(ctx context.Context) FeatureFlags
-
- // GetContentWindowSize returns the content window size for log truncation
- GetContentWindowSize() int
-
- // IsFeatureEnabled checks if a feature flag is enabled.
- IsFeatureEnabled(ctx context.Context, flagName string) bool
-}
+ Run: func(cmd *cobra.Command, _ []string) {
+ // Build a map of arguments from flags
+ arguments, err := buildArgumentsMap(cmd, tool)
+ if err != nil {
+ _, _ = fmt.Fprintf(os.Stderr, "failed to build arguments map: %v\n", err)
+ return
+ }
+
+ jsonData, err := buildJSONRPCRequest("tools/call", tool.Name, arguments)
+ if err != nil {
+ _, _ = fmt.Fprintf(os.Stderr, "failed to build JSONRPC request: %v\n", err)
+ return
+ }
+
+ // Execute the server command
+ serverCmd, err := cmd.Flags().GetString("stdio-server-cmd")
+ if err != nil {
+ _, _ = fmt.Fprintf(os.Stderr, "failed to get stdio-server-cmd: %v\n", err)
+ return
+ }
+ response, err := executeServerCommand(serverCmd, jsonData)
+ if err != nil {
+ _, _ = fmt.Fprintf(os.Stderr, "error executing server command: %v\n", err)
+ return
+ }
+ if err := printResponse(response, prettyPrint); err != nil {
+ _, _ = fmt.Fprintf(os.Stderr, "error printing response: %v\n", err)
+ return
+ }
+ },
+ }
-// BaseDeps is the standard implementation of ToolDependencies for the local server.
-// It stores pre-created clients. The remote server can create its own struct
-// implementing ToolDependencies with different client creation strategies.
-type BaseDeps struct {
- // Pre-created clients
- Client *gogithub.Client
- GQLClient *githubv4.Client
- RawClient *raw.Client
```
This function is important because it defines how GitHub MCP Server Tutorial: Production GitHub Operations Through MCP implements the patterns covered in this chapter.
-### `pkg/github/dependencies.go`
+### `cmd/mcpcurl/main.go`
-The `GetRawClient` function in [`pkg/github/dependencies.go`](https://github.com/github/github-mcp-server/blob/HEAD/pkg/github/dependencies.go) handles a key part of this chapter's functionality:
+The `buildJSONRPCRequest` function in [`cmd/mcpcurl/main.go`](https://github.com/github/github-mcp-server/blob/HEAD/cmd/mcpcurl/main.go) handles a key part of this chapter's functionality:
```go
- GetGQLClient(ctx context.Context) (*githubv4.Client, error)
- // GetRawClient returns a raw content client for GitHub
- GetRawClient(ctx context.Context) (*raw.Client, error)
-
- // GetRepoAccessCache returns the lockdown mode repo access cache
- GetRepoAccessCache(ctx context.Context) (*lockdown.RepoAccessCache, error)
-
- // GetT returns the translation helper function
- GetT() translations.TranslationHelperFunc
-
- // GetFlags returns feature flags
- GetFlags(ctx context.Context) FeatureFlags
-
- // GetContentWindowSize returns the content window size for log truncation
- GetContentWindowSize() int
-
- // IsFeatureEnabled checks if a feature flag is enabled.
- IsFeatureEnabled(ctx context.Context, flagName string) bool
-}
-
-// BaseDeps is the standard implementation of ToolDependencies for the local server.
-// It stores pre-created clients. The remote server can create its own struct
-// implementing ToolDependencies with different client creation strategies.
-type BaseDeps struct {
- // Pre-created clients
- Client *gogithub.Client
- GQLClient *githubv4.Client
- RawClient *raw.Client
-
- // Static dependencies
- RepoAccessCache *lockdown.RepoAccessCache
+ // Build the JSON-RPC request for tools/list
+ jsonRequest, err := buildJSONRPCRequest("tools/list", "", nil)
+ if err != nil {
+ return fmt.Errorf("failed to build JSON-RPC request: %w", err)
+ }
+
+ // Execute the server command and pass the JSON-RPC request
+ response, err := executeServerCommand(serverCmd, jsonRequest)
+ if err != nil {
+ return fmt.Errorf("error executing server command: %w", err)
+ }
+
+ // Output the response
+ fmt.Println(response)
+ return nil
+ },
+ }
+
+ // Create the tools command
+ toolsCmd = &cobra.Command{
+ Use: "tools",
+ Short: "Access available tools",
+ Long: "Contains all dynamically generated tool commands from the schema",
+ }
+)
+
+func main() {
+ rootCmd.AddCommand(schemaCmd)
+
+ // Add global flag for stdio server command
+ rootCmd.PersistentFlags().String("stdio-server-cmd", "", "Shell command to invoke MCP server via stdio (required)")
```
This function is important because it defines how GitHub MCP Server Tutorial: Production GitHub Operations Through MCP implements the patterns covered in this chapter.
-### `pkg/github/dependencies.go`
+### `cmd/mcpcurl/main.go`
-The `GetRepoAccessCache` function in [`pkg/github/dependencies.go`](https://github.com/github/github-mcp-server/blob/HEAD/pkg/github/dependencies.go) handles a key part of this chapter's functionality:
+The `executeServerCommand` function in [`cmd/mcpcurl/main.go`](https://github.com/github/github-mcp-server/blob/HEAD/cmd/mcpcurl/main.go) handles a key part of this chapter's functionality:
```go
- GetRawClient(ctx context.Context) (*raw.Client, error)
-
- // GetRepoAccessCache returns the lockdown mode repo access cache
- GetRepoAccessCache(ctx context.Context) (*lockdown.RepoAccessCache, error)
-
- // GetT returns the translation helper function
- GetT() translations.TranslationHelperFunc
-
- // GetFlags returns feature flags
- GetFlags(ctx context.Context) FeatureFlags
-
- // GetContentWindowSize returns the content window size for log truncation
- GetContentWindowSize() int
-
- // IsFeatureEnabled checks if a feature flag is enabled.
- IsFeatureEnabled(ctx context.Context, flagName string) bool
-}
-
-// BaseDeps is the standard implementation of ToolDependencies for the local server.
-// It stores pre-created clients. The remote server can create its own struct
-// implementing ToolDependencies with different client creation strategies.
-type BaseDeps struct {
- // Pre-created clients
- Client *gogithub.Client
- GQLClient *githubv4.Client
- RawClient *raw.Client
-
- // Static dependencies
- RepoAccessCache *lockdown.RepoAccessCache
- T translations.TranslationHelperFunc
- Flags FeatureFlags
- ContentWindowSize int
+
+ // Execute the server command and pass the JSON-RPC request
+ response, err := executeServerCommand(serverCmd, jsonRequest)
+ if err != nil {
+ return fmt.Errorf("error executing server command: %w", err)
+ }
+
+ // Output the response
+ fmt.Println(response)
+ return nil
+ },
+ }
+
+ // Create the tools command
+ toolsCmd = &cobra.Command{
+ Use: "tools",
+ Short: "Access available tools",
+ Long: "Contains all dynamically generated tool commands from the schema",
+ }
+)
+
+func main() {
+ rootCmd.AddCommand(schemaCmd)
+
+ // Add global flag for stdio server command
+ rootCmd.PersistentFlags().String("stdio-server-cmd", "", "Shell command to invoke MCP server via stdio (required)")
+ _ = rootCmd.MarkPersistentFlagRequired("stdio-server-cmd")
+
+ // Add global flag for pretty printing
+ rootCmd.PersistentFlags().Bool("pretty", true, "Pretty print MCP response (only for JSON or JSONL responses)")
+
+ // Add the tools command to the root command
```
This function is important because it defines how GitHub MCP Server Tutorial: Production GitHub Operations Through MCP implements the patterns covered in this chapter.
-### `pkg/github/dependencies.go`
+### `cmd/mcpcurl/main.go`
-The `GetT` function in [`pkg/github/dependencies.go`](https://github.com/github/github-mcp-server/blob/HEAD/pkg/github/dependencies.go) handles a key part of this chapter's functionality:
+The `printResponse` function in [`cmd/mcpcurl/main.go`](https://github.com/github/github-mcp-server/blob/HEAD/cmd/mcpcurl/main.go) handles a key part of this chapter's functionality:
```go
- GetRepoAccessCache(ctx context.Context) (*lockdown.RepoAccessCache, error)
-
- // GetT returns the translation helper function
- GetT() translations.TranslationHelperFunc
-
- // GetFlags returns feature flags
- GetFlags(ctx context.Context) FeatureFlags
-
- // GetContentWindowSize returns the content window size for log truncation
- GetContentWindowSize() int
-
- // IsFeatureEnabled checks if a feature flag is enabled.
- IsFeatureEnabled(ctx context.Context, flagName string) bool
-}
-
-// BaseDeps is the standard implementation of ToolDependencies for the local server.
-// It stores pre-created clients. The remote server can create its own struct
-// implementing ToolDependencies with different client creation strategies.
-type BaseDeps struct {
- // Pre-created clients
- Client *gogithub.Client
- GQLClient *githubv4.Client
- RawClient *raw.Client
-
- // Static dependencies
- RepoAccessCache *lockdown.RepoAccessCache
- T translations.TranslationHelperFunc
- Flags FeatureFlags
- ContentWindowSize int
-
- // Feature flag checker for runtime checks
- featureChecker inventory.FeatureFlagChecker
+ return
+ }
+ if err := printResponse(response, prettyPrint); err != nil {
+ _, _ = fmt.Fprintf(os.Stderr, "error printing response: %v\n", err)
+ return
+ }
+ },
+ }
+
+ // Initialize viper for this command
+ viperInit := func() {
+ viper.Reset()
+ viper.AutomaticEnv()
+ viper.SetEnvPrefix(strings.ToUpper(tool.Name))
+ viper.SetEnvKeyReplacer(strings.NewReplacer("-", "_"))
+ }
+
+ // We'll call the init function directly instead of with cobra.OnInitialize
+ // to avoid conflicts between commands
+ viperInit()
+
+ // Add flags based on schema properties
+ for name, prop := range tool.InputSchema.Properties {
+ isRequired := slices.Contains(tool.InputSchema.Required, name)
+
+ // Enhance description to indicate if parameter is optional
+ description := prop.Description
+ if !isRequired {
+ description += " (optional)"
+ }
+
+ switch prop.Type {
```
This function is important because it defines how GitHub MCP Server Tutorial: Production GitHub Operations Through MCP implements the patterns covered in this chapter.
@@ -214,11 +212,11 @@ This function is important because it defines how GitHub MCP Server Tutorial: Pr
```mermaid
flowchart TD
- A[GetGQLClient]
- B[GetRawClient]
- C[GetRepoAccessCache]
- D[GetT]
- E[GetFlags]
+ A[buildArgumentsMap]
+ B[buildJSONRPCRequest]
+ C[executeServerCommand]
+ D[printResponse]
+ E[values]
A --> B
B --> C
C --> D
diff --git a/tutorials/github-mcp-server-tutorial/08-contribution-and-upgrade-workflow.md b/tutorials/github-mcp-server-tutorial/08-contribution-and-upgrade-workflow.md
index 446fca17..f7463f23 100644
--- a/tutorials/github-mcp-server-tutorial/08-contribution-and-upgrade-workflow.md
+++ b/tutorials/github-mcp-server-tutorial/08-contribution-and-upgrade-workflow.md
@@ -43,170 +43,168 @@ Next steps:
- define a narrow write-enabled profile for planned automation
- run quarterly review of toolsets, scopes, and host policy alignment
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `pkg/github/tools.go`
+### `pkg/github/repositories_helper.go`
-The `ToStringPtr` function in [`pkg/github/tools.go`](https://github.com/github/github-mcp-server/blob/HEAD/pkg/github/tools.go) handles a key part of this chapter's functionality:
+The `createReferenceFromDefaultBranch` function in [`pkg/github/repositories_helper.go`](https://github.com/github/github-mcp-server/blob/HEAD/pkg/github/repositories_helper.go) handles a key part of this chapter's functionality:
```go
}
-// ToStringPtr converts a string to a *string pointer.
-// Returns nil if the string is empty.
-func ToStringPtr(s string) *string {
- if s == "" {
- return nil
+// createReferenceFromDefaultBranch creates a new branch reference from the repository's default branch
+func createReferenceFromDefaultBranch(ctx context.Context, client *github.Client, owner, repo, branch string) (*github.Reference, error) {
+ defaultRef, err := resolveDefaultBranch(ctx, client, owner, repo)
+ if err != nil {
+ _, _ = ghErrors.NewGitHubAPIErrorToCtx(ctx, "failed to resolve default branch", nil, err)
+ return nil, fmt.Errorf("failed to resolve default branch: %w", err)
}
- return &s
-}
-// GenerateToolsetsHelp generates the help text for the toolsets flag
-func GenerateToolsetsHelp() string {
- // Get toolset group to derive defaults and available toolsets
- // Build() can only fail if WithTools specifies invalid tools - not used here
- r, _ := NewInventory(stubTranslator).Build()
-
- // Format default tools from metadata using strings.Builder
- var defaultBuf strings.Builder
- defaultIDs := r.DefaultToolsetIDs()
- for i, id := range defaultIDs {
- if i > 0 {
- defaultBuf.WriteString(", ")
- }
- defaultBuf.WriteString(string(id))
+ // Create the new branch reference
+ createdRef, resp, err := client.Git.CreateRef(ctx, owner, repo, github.CreateRef{
+ Ref: "refs/heads/" + branch,
+ SHA: *defaultRef.Object.SHA,
+ })
+ if err != nil {
+ _, _ = ghErrors.NewGitHubAPIErrorToCtx(ctx, "failed to create new branch reference", resp, err)
+ return nil, fmt.Errorf("failed to create new branch reference: %w", err)
}
+ if resp != nil && resp.Body != nil {
+ defer func() { _ = resp.Body.Close() }()
+ }
+
+ return createdRef, nil
+}
- // Get all available toolsets (excludes context and dynamic for display)
- allToolsets := r.AvailableToolsets("context", "dynamic")
- var availableBuf strings.Builder
- const maxLineLength = 70
- currentLine := ""
+// matchFiles searches for files in the Git tree that match the given path.
+// It's used when GetContents fails or returns unexpected results.
+func matchFiles(ctx context.Context, client *github.Client, owner, repo, ref, path string, rawOpts *raw.ContentOpts, rawAPIResponseCode int) (*mcp.CallToolResult, any, error) {
+ // Step 1: Get Git Tree recursively
+ tree, response, err := client.Git.GetTree(ctx, owner, repo, ref, true)
+ if err != nil {
```
This function is important because it defines how GitHub MCP Server Tutorial: Production GitHub Operations Through MCP implements the patterns covered in this chapter.
-### `pkg/github/tools.go`
+### `pkg/github/repositories_helper.go`
-The `GenerateToolsetsHelp` function in [`pkg/github/tools.go`](https://github.com/github/github-mcp-server/blob/HEAD/pkg/github/tools.go) handles a key part of this chapter's functionality:
+The `matchFiles` function in [`pkg/github/repositories_helper.go`](https://github.com/github/github-mcp-server/blob/HEAD/pkg/github/repositories_helper.go) handles a key part of this chapter's functionality:
```go
}
-// GenerateToolsetsHelp generates the help text for the toolsets flag
-func GenerateToolsetsHelp() string {
- // Get toolset group to derive defaults and available toolsets
- // Build() can only fail if WithTools specifies invalid tools - not used here
- r, _ := NewInventory(stubTranslator).Build()
-
- // Format default tools from metadata using strings.Builder
- var defaultBuf strings.Builder
- defaultIDs := r.DefaultToolsetIDs()
- for i, id := range defaultIDs {
- if i > 0 {
- defaultBuf.WriteString(", ")
- }
- defaultBuf.WriteString(string(id))
+// matchFiles searches for files in the Git tree that match the given path.
+// It's used when GetContents fails or returns unexpected results.
+func matchFiles(ctx context.Context, client *github.Client, owner, repo, ref, path string, rawOpts *raw.ContentOpts, rawAPIResponseCode int) (*mcp.CallToolResult, any, error) {
+ // Step 1: Get Git Tree recursively
+ tree, response, err := client.Git.GetTree(ctx, owner, repo, ref, true)
+ if err != nil {
+ return ghErrors.NewGitHubAPIErrorResponse(ctx,
+ "failed to get git tree",
+ response,
+ err,
+ ), nil, nil
}
-
- // Get all available toolsets (excludes context and dynamic for display)
- allToolsets := r.AvailableToolsets("context", "dynamic")
- var availableBuf strings.Builder
- const maxLineLength = 70
- currentLine := ""
-
- for i, toolset := range allToolsets {
- id := string(toolset.ID)
- switch {
- case i == 0:
- currentLine = id
- case len(currentLine)+len(id)+2 <= maxLineLength:
- currentLine += ", " + id
- default:
+ defer func() { _ = response.Body.Close() }()
+
+ // Step 2: Filter tree for matching paths
+ const maxMatchingFiles = 3
+ matchingFiles := filterPaths(tree.Entries, path, maxMatchingFiles)
+ if len(matchingFiles) > 0 {
+ matchingFilesJSON, err := json.Marshal(matchingFiles)
+ if err != nil {
+ return utils.NewToolResultError(fmt.Sprintf("failed to marshal matching files: %s", err)), nil, nil
+ }
+ resolvedRefs, err := json.Marshal(rawOpts)
+ if err != nil {
+ return utils.NewToolResultError(fmt.Sprintf("failed to marshal resolved refs: %s", err)), nil, nil
+ }
+ if rawAPIResponseCode > 0 {
+ return utils.NewToolResultText(fmt.Sprintf("Resolved potential matches in the repository tree (resolved refs: %s, matching files: %s), but the content API returned an unexpected status code %d.", string(resolvedRefs), string(matchingFilesJSON), rawAPIResponseCode)), nil, nil
+ }
+ return utils.NewToolResultText(fmt.Sprintf("Resolved potential matches in the repository tree (resolved refs: %s, matching files: %s).", string(resolvedRefs), string(matchingFilesJSON))), nil, nil
```
This function is important because it defines how GitHub MCP Server Tutorial: Production GitHub Operations Through MCP implements the patterns covered in this chapter.
-### `pkg/github/tools.go`
+### `pkg/github/repositories_helper.go`
-The `stubTranslator` function in [`pkg/github/tools.go`](https://github.com/github/github-mcp-server/blob/HEAD/pkg/github/tools.go) handles a key part of this chapter's functionality:
+The `filterPaths` function in [`pkg/github/repositories_helper.go`](https://github.com/github/github-mcp-server/blob/HEAD/pkg/github/repositories_helper.go) handles a key part of this chapter's functionality:
```go
- // Get toolset group to derive defaults and available toolsets
- // Build() can only fail if WithTools specifies invalid tools - not used here
- r, _ := NewInventory(stubTranslator).Build()
-
- // Format default tools from metadata using strings.Builder
- var defaultBuf strings.Builder
- defaultIDs := r.DefaultToolsetIDs()
- for i, id := range defaultIDs {
- if i > 0 {
- defaultBuf.WriteString(", ")
+ // Step 2: Filter tree for matching paths
+ const maxMatchingFiles = 3
+ matchingFiles := filterPaths(tree.Entries, path, maxMatchingFiles)
+ if len(matchingFiles) > 0 {
+ matchingFilesJSON, err := json.Marshal(matchingFiles)
+ if err != nil {
+ return utils.NewToolResultError(fmt.Sprintf("failed to marshal matching files: %s", err)), nil, nil
+ }
+ resolvedRefs, err := json.Marshal(rawOpts)
+ if err != nil {
+ return utils.NewToolResultError(fmt.Sprintf("failed to marshal resolved refs: %s", err)), nil, nil
+ }
+ if rawAPIResponseCode > 0 {
+ return utils.NewToolResultText(fmt.Sprintf("Resolved potential matches in the repository tree (resolved refs: %s, matching files: %s), but the content API returned an unexpected status code %d.", string(resolvedRefs), string(matchingFilesJSON), rawAPIResponseCode)), nil, nil
}
- defaultBuf.WriteString(string(id))
+ return utils.NewToolResultText(fmt.Sprintf("Resolved potential matches in the repository tree (resolved refs: %s, matching files: %s).", string(resolvedRefs), string(matchingFilesJSON))), nil, nil
}
+ return utils.NewToolResultError("Failed to get file contents. The path does not point to a file or directory, or the file does not exist in the repository."), nil, nil
+}
- // Get all available toolsets (excludes context and dynamic for display)
- allToolsets := r.AvailableToolsets("context", "dynamic")
- var availableBuf strings.Builder
- const maxLineLength = 70
- currentLine := ""
-
- for i, toolset := range allToolsets {
- id := string(toolset.ID)
- switch {
- case i == 0:
- currentLine = id
- case len(currentLine)+len(id)+2 <= maxLineLength:
- currentLine += ", " + id
- default:
- if availableBuf.Len() > 0 {
- availableBuf.WriteString(",\n\t ")
- }
- availableBuf.WriteString(currentLine)
+// filterPaths filters the entries in a GitHub tree to find paths that
+// match the given suffix.
+// maxResults limits the number of results returned to first maxResults entries,
+// a maxResults of -1 means no limit.
+// It returns a slice of strings containing the matching paths.
+// Directories are returned with a trailing slash.
+func filterPaths(entries []*github.TreeEntry, path string, maxResults int) []string {
+ // Remove trailing slash for matching purposes, but flag whether we
+ // only want directories.
+ dirOnly := false
+ if strings.HasSuffix(path, "/") {
+ dirOnly = true
```
This function is important because it defines how GitHub MCP Server Tutorial: Production GitHub Operations Through MCP implements the patterns covered in this chapter.
-### `pkg/github/tools.go`
+### `pkg/github/repositories_helper.go`
-The `AddDefaultToolset` function in [`pkg/github/tools.go`](https://github.com/github/github-mcp-server/blob/HEAD/pkg/github/tools.go) handles a key part of this chapter's functionality:
+The `looksLikeSHA` function in [`pkg/github/repositories_helper.go`](https://github.com/github/github-mcp-server/blob/HEAD/pkg/github/repositories_helper.go) handles a key part of this chapter's functionality:
```go
-func stubTranslator(_, fallback string) string { return fallback }
-
-// AddDefaultToolset removes the default toolset and expands it to the actual default toolset IDs
-func AddDefaultToolset(result []string) []string {
- hasDefault := false
- seen := make(map[string]bool)
- for _, toolset := range result {
- seen[toolset] = true
- if toolset == string(ToolsetMetadataDefault.ID) {
- hasDefault = true
- }
- }
+}
- // Only expand if "default" keyword was found
- if !hasDefault {
- return result
+// looksLikeSHA returns true if the string appears to be a Git commit SHA.
+// A SHA is a 40-character hexadecimal string.
+func looksLikeSHA(s string) bool {
+ if len(s) != 40 {
+ return false
}
-
- result = RemoveToolset(result, string(ToolsetMetadataDefault.ID))
-
- // Get default toolset IDs from the Inventory
- // Build() can only fail if WithTools specifies invalid tools - not used here
- r, _ := NewInventory(stubTranslator).Build()
- for _, id := range r.DefaultToolsetIDs() {
- if !seen[string(id)] {
- result = append(result, string(id))
+ for _, c := range s {
+ if (c < '0' || c > '9') && (c < 'a' || c > 'f') && (c < 'A' || c > 'F') {
+ return false
}
}
- return result
+ return true
}
-func RemoveToolset(tools []string, toRemove string) []string {
+// resolveGitReference takes a user-provided ref and sha and resolves them into a
+// definitive commit SHA and its corresponding fully-qualified reference.
+//
+// The resolution logic follows a clear priority:
+//
+// 1. If a specific commit `sha` is provided, it takes precedence and is used directly,
+// and all reference resolution is skipped.
+//
+// 1a. If `sha` is empty but `ref` looks like a commit SHA (40 hexadecimal characters),
+// it is returned as-is without any API calls or reference resolution.
+//
+// 2. If no `sha` is provided and `ref` does not look like a SHA, the function resolves
+// the `ref` string into a fully-qualified format (e.g., "refs/heads/main") by trying
+// the following steps in order:
+// a). **Empty Ref:** If `ref` is empty, the repository's default branch is used.
+// b). **Fully-Qualified:** If `ref` already starts with "refs/", it's considered fully
```
This function is important because it defines how GitHub MCP Server Tutorial: Production GitHub Operations Through MCP implements the patterns covered in this chapter.
@@ -216,11 +214,11 @@ This function is important because it defines how GitHub MCP Server Tutorial: Pr
```mermaid
flowchart TD
- A[ToStringPtr]
- B[GenerateToolsetsHelp]
- C[stubTranslator]
- D[AddDefaultToolset]
- E[RemoveToolset]
+ A[createReferenceFromDefaultBranch]
+ B[matchFiles]
+ C[filterPaths]
+ D[looksLikeSHA]
+ E[resolveGitReference]
A --> B
B --> C
C --> D
diff --git a/tutorials/goose-tutorial/01-getting-started.md b/tutorials/goose-tutorial/01-getting-started.md
index c7dc79a3..dfe2742c 100644
--- a/tutorials/goose-tutorial/01-getting-started.md
+++ b/tutorials/goose-tutorial/01-getting-started.md
@@ -47,203 +47,157 @@ Inside the session, start with a scoped prompt such as:
- "Summarize this repo structure and propose a 3-step refactor plan."
-## Early Failure Triage
+## Platform-Specific Installation Notes
-| Symptom | Likely Cause | First Fix |
-|:--------|:-------------|:----------|
-| no model response | provider not configured correctly | rerun `goose configure` and re-authenticate |
-| tool calls fail unexpectedly | permission mode mismatch | switch mode or adjust per-tool permissions |
-| noisy or irrelevant context | wrong working directory | restart session from repo root |
+### macOS
-## Source References
+Both Homebrew and the install script work. Homebrew is preferred if you manage other CLI tools through it — updates come via `brew upgrade block-goose-cli`. The install script places the binary in `~/.local/bin`; ensure this is on your `PATH`.
-- [Goose Quickstart](https://block.github.io/goose/docs/quickstart)
-- [Install goose](https://block.github.io/goose/docs/getting-started/installation)
-- [Configure LLM Provider](https://block.github.io/goose/docs/getting-started/providers)
+### Linux
-## Summary
+Use the install script. After running it, verify the install with:
-You now have Goose installed, configured, and running in a real project context.
+```bash
+goose --version
+goose info
+```
-Next: [Chapter 2: Architecture and Agent Loop](02-architecture-and-agent-loop.md)
+`goose info` prints the config file path, log directory, and current version — useful for confirming the binary and config are where Goose expects them.
-## Depth Expansion Playbook
+### Windows
-## Source Code Walkthrough
+Use the desktop installer from the GitHub releases page. The CLI is available but the desktop app provides a more stable setup flow on Windows. WSL2 is a supported path for CLI-only usage.
-### `scripts/diagnostics-viewer.py`
+## Desktop vs CLI Tradeoffs
-The `JsonTreeView` class in [`scripts/diagnostics-viewer.py`](https://github.com/block/goose/blob/HEAD/scripts/diagnostics-viewer.py) handles a key part of this chapter's functionality:
+| Factor | Desktop App | CLI |
+|:-------|:------------|:----|
+| first-time setup | guided UI with provider wizard | `goose configure` interactive prompts |
+| session visibility | visual conversation pane | terminal output with streaming |
+| extension management | toggle UI per extension | `goose configure` or `--with-builtin` flag |
+| scripting / CI | not suitable | `goose run` with headless flags |
+| context usage display | token meter in sidebar | printed before each prompt |
-```py
+Most developers use the CLI for scripted tasks and the desktop app for exploratory sessions. Both share the same `~/.config/goose/config.yaml` configuration file.
+## What `goose info` Shows
-class JsonTreeView(Tree):
- """A tree widget for displaying collapsible JSON."""
+After setup, running `goose info` outputs your runtime baseline:
- BINDINGS = [
- Binding("ctrl+o", "toggle_all", "Toggle All", show=True),
- ]
+```
+version: v1.28.0
+config file: ~/.config/goose/config.yaml
+log dir: ~/.config/goose/logs/
+sessions dir: ~/.config/goose/sessions/
+provider: anthropic
+model: claude-sonnet-4-5
+```
- def __init__(self, *args, **kwargs):
- super().__init__(*args, **kwargs)
- self.json_data = None
- self.show_root = False
- self.all_expanded = False
+This is the first command to run when diagnosing unexpected behavior.
- def load_json(self, data: Any, label: str = "JSON"):
- """Load JSON data into the tree."""
- self.json_data = data
- self.clear()
- self.root.label = label
- self._build_tree(self.root, data)
- # Expand all nodes by default
- self.root.expand_all()
+## Early Failure Triage
- def action_toggle_all(self):
- """Toggle expansion of all nodes."""
- self.all_expanded = not self.all_expanded
- if self.all_expanded:
- self.root.expand_all()
- else:
- self.root.collapse_all()
- self.root.expand() # Keep root expanded
-```
+| Symptom | Likely Cause | First Fix |
+|:--------|:-------------|:----------|
+| no model response | provider not configured correctly | rerun `goose configure` and re-authenticate |
+| tool calls fail unexpectedly | permission mode mismatch | switch mode or adjust per-tool permissions |
+| noisy or irrelevant context | wrong working directory | restart session from repo root |
+| `command not found: goose` | binary not on PATH | check `~/.local/bin` is in PATH |
+| auth errors with Anthropic | API key expired or incorrect | regenerate key at console.anthropic.com |
-This class is important because it defines how Goose Tutorial: Extensible Open-Source AI Agent for Real Engineering Work implements the patterns covered in this chapter.
+## Source References
-### `scripts/diagnostics-viewer.py`
+- [Goose Quickstart](https://block.github.io/goose/docs/quickstart)
+- [Install goose](https://block.github.io/goose/docs/getting-started/installation)
+- [Configure LLM Provider](https://block.github.io/goose/docs/getting-started/providers)
-The `of` class in [`scripts/diagnostics-viewer.py`](https://github.com/block/goose/blob/HEAD/scripts/diagnostics-viewer.py) handles a key part of this chapter's functionality:
+## Updating Goose
-```py
+Keep your installation current to get bug fixes and new provider support:
- def action_toggle_all(self):
- """Toggle expansion of all nodes."""
- self.all_expanded = not self.all_expanded
- if self.all_expanded:
- self.root.expand_all()
- else:
- self.root.collapse_all()
- self.root.expand() # Keep root expanded
+```bash
+# Upgrade to latest stable release
+goose update --channel stable
- def on_tree_node_selected(self, event: Tree.NodeSelected):
- """Handle node selection - show modal for truncated strings."""
- node = event.node
+# Check what version you have
+goose info
+```
- # Check if this is a truncated string node
- if node.data and isinstance(node.data, dict) and node.data.get("truncated"):
- key = node.data["key"]
- value = node.data["value"]
+For Homebrew installations, use `brew upgrade block-goose-cli` instead. The install-script path and Homebrew path are independent; do not mix them on the same machine.
- # Show the full string in a modal
- title = f"Full String Value for '{key}'"
- self.app.push_screen(TextViewerModal(title, value))
+## Custom Distros
- # Prevent default tree expansion behavior
- event.stop()
+If your organization wants to ship a pre-configured Goose with specific providers, extensions, and branding, the `CUSTOM_DISTROS.md` file at the repo root documents the distro build process. This is relevant for platform teams that want to standardize Goose across a large engineering org without requiring each developer to run `goose configure` from scratch.
- def _build_tree(self, node, data, max_depth=10, current_depth=0):
- """Recursively build the tree from JSON data."""
- if current_depth > max_depth:
- node.add_leaf("[dim]...[/dim]")
- return
+## Summary
-```
+You now have Goose installed, configured, and running in a real project context.
+
+Next: [Chapter 2: Architecture and Agent Loop](02-architecture-and-agent-loop.md)
+
+## Source Code Walkthrough
-This class is important because it defines how Goose Tutorial: Extensible Open-Source AI Agent for Real Engineering Work implements the patterns covered in this chapter.
+### `crates/goose-cli/src/cli.rs` — CLI entry point and command structure
-### `scripts/diagnostics-viewer.py`
+The top-level `Cli` struct in [`crates/goose-cli/src/cli.rs`](https://github.com/block/goose/blob/main/crates/goose-cli/src/cli.rs) defines the complete command surface you interact with during setup and every session:
-The `of` class in [`scripts/diagnostics-viewer.py`](https://github.com/block/goose/blob/HEAD/scripts/diagnostics-viewer.py) handles a key part of this chapter's functionality:
+```rust
+#[derive(Parser)]
+#[command(name = "goose", author, version, display_name = "", about, long_about = None)]
+pub struct Cli {
+ #[command(subcommand)]
+ command: Option<Command>,
+}
+```
-```py
+Key argument groups surfaced by this file include:
- def action_toggle_all(self):
- """Toggle expansion of all nodes."""
- self.all_expanded = not self.all_expanded
- if self.all_expanded:
- self.root.expand_all()
- else:
- self.root.collapse_all()
- self.root.expand() # Keep root expanded
+- **`Identifier`** — selects a session by `--name (-n)`, `--session-id`, or legacy `--path`
+- **`SessionOptions`** — controls `--debug`, `--max-tool-repetitions`, `--max-turns` (default 1000), and `--container`
+- **`InputOptions`** — accepts `--instructions (-i)` (file path or stdin), `--text (-t)`, `--recipe`, `--system`, and `--params`
+- **`ExtensionOptions`** — adds extensions via `--with-extension`, `--with-builtin`, or disables defaults with `--no-profile`
- def on_tree_node_selected(self, event: Tree.NodeSelected):
- """Handle node selection - show modal for truncated strings."""
- node = event.node
+This is the interface boundary you see when running `goose --help` or `goose session --help`.
- # Check if this is a truncated string node
- if node.data and isinstance(node.data, dict) and node.data.get("truncated"):
- key = node.data["key"]
- value = node.data["value"]
+### `crates/goose-cli/src/commands/configure.rs` — interactive provider setup
- # Show the full string in a modal
- title = f"Full String Value for '{key}'"
- self.app.push_screen(TextViewerModal(title, value))
+The `configure_provider_dialog()` function in [`crates/goose-cli/src/commands/configure.rs`](https://github.com/block/goose/blob/main/crates/goose-cli/src/commands/configure.rs) runs when you execute `goose configure`:
- # Prevent default tree expansion behavior
- event.stop()
+```rust
+pub async fn configure_provider_dialog() -> anyhow::Result<bool> {
+ let config = Config::global();
+ let mut available_providers = providers().await;
+ available_providers.sort_by(|a, b| a.0.display_name.cmp(&b.0.display_name));
- def _build_tree(self, node, data, max_depth=10, current_depth=0):
- """Recursively build the tree from JSON data."""
- if current_depth > max_depth:
- node.add_leaf("[dim]...[/dim]")
- return
+ let provider_items: Vec<(&String, &str, &str)> = available_providers
+ .iter()
+ .map(|(p, _)| (&p.name, p.display_name.as_str(), p.description.as_str()))
+ .collect();
-```
+ let current_provider: Option<String> = config.get_goose_provider().ok();
+ let default_provider = current_provider.unwrap_or_default();
-This class is important because it defines how Goose Tutorial: Extensible Open-Source AI Agent for Real Engineering Work implements the patterns covered in this chapter.
-
-### `scripts/diagnostics-viewer.py`
-
-The `TextViewerModal` class in [`scripts/diagnostics-viewer.py`](https://github.com/block/goose/blob/HEAD/scripts/diagnostics-viewer.py) handles a key part of this chapter's functionality:
-
-```py
- # Show the full string in a modal
- title = f"Full String Value for '{key}'"
- self.app.push_screen(TextViewerModal(title, value))
-
- # Prevent default tree expansion behavior
- event.stop()
-
- def _build_tree(self, node, data, max_depth=10, current_depth=0):
- """Recursively build the tree from JSON data."""
- if current_depth > max_depth:
- node.add_leaf("[dim]...[/dim]")
- return
-
- if isinstance(data, dict):
- for key, value in data.items():
- if isinstance(value, (dict, list)) and value:
- # Expand first level by default
- child = node.add(f"[cyan]{key}[/cyan]: {{...}}" if isinstance(value, dict) else f"[cyan]{key}[/cyan]: [...]", expand=(current_depth == 0))
- child.data = {"key": key, "value": value, "type": type(value).__name__, "expandable": False}
- self._build_tree(child, value, max_depth, current_depth + 1)
- elif isinstance(value, str):
- truncated = truncate_string(value)
- if truncated != value:
- # Make truncated strings expandable
- child = node.add(f"[cyan]{key}[/cyan]: [green]\"{truncated}\"[/green]", expand=False)
- child.data = {"key": key, "value": value, "type": "str", "truncated": True, "expandable": True}
- child.allow_expand = False # Don't show expand icon initially
- else:
- node.add_leaf(f"[cyan]{key}[/cyan]: [green]\"{value}\"[/green]")
- elif isinstance(value, bool):
- # Check bool before int/float since bool is a subclass of int
- node.add_leaf(f"[cyan]{key}[/cyan]: [magenta]{str(value).lower()}[/magenta]")
-```
+ let provider_name = cliclack::select("Which model provider should we use?")
+ .initial_value(&default_provider)
+ .items(&provider_items)
+ .filter_mode()
+ .interact()?;
-This class is important because it defines how Goose Tutorial: Extensible Open-Source AI Agent for Real Engineering Work implements the patterns covered in this chapter.
+ // ... iterate config_keys, collect credentials, test provider
+ Ok(true)
+}
+```
+The function reads `ProviderMetadata` for each registered provider, prompts for required `ConfigKey` credentials via secure input, and validates the connection before writing to `Config::global()`. This is the first thing you run after installing Goose.
## How These Components Connect
```mermaid
flowchart TD
- A[JsonTreeView]
- B[of]
- C[of]
- D[TextViewerModal]
+ A["goose CLI binary\n(crates/goose-cli/src/main.rs)"]
+ B["Cli struct + subcommands\n(src/cli.rs)"]
+ C["configure subcommand\n(src/commands/configure.rs)"]
+ D["Config::global() singleton\n(providers, model, extensions)"]
A --> B
B --> C
C --> D
diff --git a/tutorials/goose-tutorial/02-architecture-and-agent-loop.md b/tutorials/goose-tutorial/02-architecture-and-agent-loop.md
index 51799f47..32d9b4a6 100644
--- a/tutorials/goose-tutorial/02-architecture-and-agent-loop.md
+++ b/tutorials/goose-tutorial/02-architecture-and-agent-loop.md
@@ -20,6 +20,21 @@ This chapter explains how Goose turns requests into concrete engineering actions
- reason about context revision and token efficiency
- use this model to debug misbehavior faster
+## Architecture Diagram
+
+```mermaid
+flowchart TD
+ U[User] --> I["Interface\n(Desktop UI or CLI)"]
+ I --> A["Agent\n(goose-cli / goose-server)"]
+ A --> P["Provider\n(Anthropic, OpenAI, Ollama, etc.)"]
+ P -->|tool_use requests| A
+ A --> E["Extensions\n(MCP servers via goose-mcp)"]
+ E -->|tool results| A
+ A --> C["Conversation\n(context management + compaction)"]
+ C --> A
+ A --> I
+```
+
## Core Components
| Component | Role | Practical Impact |
@@ -51,197 +66,135 @@ Goose treats many execution failures as recoverable signals to the model:
- unavailable tools
- command failures
-This makes multi-step workflows more resilient than simple one-shot prompting.
-
-## Source References
-
-- [Goose Architecture](https://block.github.io/goose/docs/goose-architecture/)
-- [Extensions Design](https://block.github.io/goose/docs/goose-architecture/extensions-design)
+This makes multi-step workflows more resilient than simple one-shot prompting. The model sees the error text as a tool result and can retry with corrected arguments or choose a different approach.
-## Summary
+## Crate Structure
-You now have an operator-level mental model for Goose's execution loop and error paths.
+The codebase is organized as a Rust workspace with clear separation between layers:
-Next: [Chapter 3: Providers and Model Routing](03-providers-and-model-routing.md)
+| Crate | Path | Role |
+|:------|:-----|:-----|
+| `goose-cli` | `crates/goose-cli/` | Binary, interactive session, headless run |
+| `goose-server` | `crates/goose-server/` | HTTP server for desktop app integration |
+| `goose-mcp` | `crates/goose-mcp/` | Built-in MCP extensions (memory, computer controller, etc.) |
+| `goose-acp` | `crates/goose-acp/` | Agent Control Protocol server implementation |
+| `goose-sdk` | `crates/goose-sdk/` | Public SDK for embedding Goose in other tools |
-## Depth Expansion Playbook
+The desktop application communicates with `goose-server` over a local HTTP connection. The CLI uses `goose-cli` directly. Both ultimately call the same `Agent` type from the core goose crate, so behavior is consistent across surfaces.
-## Source Code Walkthrough
+## Observability in the Loop
-### `scripts/diagnostics-viewer.py`
+The `/reply` endpoint in `goose-server` emits structured telemetry at loop completion:
-The `SearchOverlay` class in [`scripts/diagnostics-viewer.py`](https://github.com/block/goose/blob/HEAD/scripts/diagnostics-viewer.py) handles a key part of this chapter's functionality:
+- turn count and total token usage
+- tool call count per session
+- session duration
+- provider and model name
-```py
+This telemetry is logged to the sessions directory. In production, these logs are the primary data source for cost attribution and debugging runaway sessions.
+## Context Revision Strategy
-class SearchOverlay(Container):
- """Search overlay widget."""
+Goose uses two mechanisms to keep context within model limits:
- def __init__(self):
- super().__init__()
- self.display = False
+1. **Auto-compaction** — triggered near `GOOSE_AUTO_COMPACT_THRESHOLD`; the agent rewrites the conversation history with a summarized version, retaining the most recent and most relevant turns
+2. **Fallback strategies** — configured via `GOOSE_CONTEXT_STRATEGY`; options include `summarize` (automatic summary) and `prompt` (pause and ask the user how to proceed)
- def compose(self) -> ComposeResult:
- with Horizontal(id="search-container"):
- yield Static("Search: ", id="search-label")
- yield Input(placeholder="Type to search...", id="search-input")
- yield Static("", id="search-results")
+The `display_context_usage()` call at the top of each loop iteration shows you how far you are from the threshold before you send the next prompt.
+## Request Lifecycle: Step by Step
-class DiagnosticsSession:
- """Represents a diagnostics bundle."""
+Walking through a single turn in detail helps map the architecture to observable behavior:
- def __init__(self, zip_path: Path):
- self.zip_path = zip_path
- self.name = "Unknown Session"
- self.session_id = zip_path.stem
- self.created_at = zip_path.stat().st_mtime
- self._load_session_name()
+1. **User submits prompt** — typed in the CLI editor or sent to `/reply` endpoint
+2. **`CliSession.handle_input()` dispatches** — validates input, handles slash commands, or passes to agent
+3. **`Agent.reply()` called** — packages the `Conversation` (recent messages + system prompt) and available tools into a provider request
+4. **Provider call made** — sent to the configured LLM; streamed response begins arriving
+5. **Model requests tool calls** — if the model emits `tool_use` blocks, the agent queues them
+6. **Permission check** — `PermissionManager` enforces `GooseMode` for each tool; prompts if needed
+7. **Tool executed** — MCP extension handles the call and returns a result (or error)
+8. **Result appended to `Conversation`** — as a `tool_result` message
+9. **Loop back to step 3** — agent continues until model returns a text response or max turns hit
+10. **Context usage displayed** — token count shown at next prompt
- def _load_session_name(self):
- """Extract session name from session.json."""
- try:
- with zipfile.ZipFile(self.zip_path, 'r') as zf:
- # Find session.json
- for name in zf.namelist():
-```
+## Source References
-This class is important because it defines how Goose Tutorial: Extensible Open-Source AI Agent for Real Engineering Work implements the patterns covered in this chapter.
-
-### `scripts/diagnostics-viewer.py`
-
-The `DiagnosticsSession` class in [`scripts/diagnostics-viewer.py`](https://github.com/block/goose/blob/HEAD/scripts/diagnostics-viewer.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-class DiagnosticsSession:
- """Represents a diagnostics bundle."""
-
- def __init__(self, zip_path: Path):
- self.zip_path = zip_path
- self.name = "Unknown Session"
- self.session_id = zip_path.stem
- self.created_at = zip_path.stat().st_mtime
- self._load_session_name()
-
- def _load_session_name(self):
- """Extract session name from session.json."""
- try:
- with zipfile.ZipFile(self.zip_path, 'r') as zf:
- # Find session.json
- for name in zf.namelist():
- if name.endswith('session.json'):
- with zf.open(name) as f:
- data = json.load(f)
- self.name = data.get('name', 'Unknown Session')
- self.session_id = data.get('id', self.zip_path.stem)
- break
- except Exception as e:
- self.name = f"Error loading: {e}"
-
- def get_file_list(self) -> list[str]:
- """Get list of files in the zip, sorted with system.txt first."""
- try:
- with zipfile.ZipFile(self.zip_path, 'r') as zf:
- files = zf.namelist()
-```
+- [Goose Architecture](https://block.github.io/goose/docs/goose-architecture/)
+- [Extensions Design](https://block.github.io/goose/docs/goose-architecture/extensions-design)
-This class is important because it defines how Goose Tutorial: Extensible Open-Source AI Agent for Real Engineering Work implements the patterns covered in this chapter.
+## The ACP Layer
-### `scripts/diagnostics-viewer.py`
+Goose exposes an Agent Control Protocol (ACP) server via `crates/goose-acp/`. ACP is a session-oriented protocol that allows external clients — including the desktop UI, IDE plugins, and custom integrations — to create and manage agent sessions over a standardized interface. The key struct is `GooseAcpSession`, which bridges ACP's session model with Goose's internal `Session` and `Thread` types. This is the abstraction that makes it possible to drive Goose from multiple surfaces without duplicating agent logic.
-The `FileContentPane` class in [`scripts/diagnostics-viewer.py`](https://github.com/block/goose/blob/HEAD/scripts/diagnostics-viewer.py) handles a key part of this chapter's functionality:
+## Debugging the Loop
-```py
+When behavior is unexpected, the most useful debugging signals are:
+1. **Token usage display** — visible at the top of each interactive prompt; if you're near the limit, compaction or truncation may have dropped relevant context
+2. **Tool call logs** — each tool invocation is logged in the session file; export to Markdown to read the full call sequence
+3. **`--debug` flag** — disables output truncation so you see full tool inputs and outputs in the terminal
+4. **`goose session diagnostics`** — generates a ZIP with all session data for deep investigation
-class FileContentPane(Vertical):
- """A pane that shows either JSON tree or plain text."""
+## Summary
- def __init__(self, title: str):
- super().__init__()
- self.title = title
- self.content_type = "empty"
- self.json_data = None
- self.text_content = ""
+You now have an operator-level mental model for Goose's execution loop and error paths.
- def compose(self) -> ComposeResult:
- """Compose the pane content."""
- if self.content_type == "json":
- tree = JsonTreeView(self.title)
- if self.json_data is not None:
- tree.load_json(self.json_data, self.title)
- yield tree
- elif self.content_type == "text":
- with VerticalScroll():
- yield Static(self.text_content)
- else:
- yield Static("[dim]No content[/dim]")
+Next: [Chapter 3: Providers and Model Routing](03-providers-and-model-routing.md)
- def set_json(self, data: Any):
- """Set JSON content."""
- self.content_type = "json"
- self.json_data = data
+## Source Code Walkthrough
- def set_text(self, text: str):
- """Set text content."""
+### `crates/goose-cli/src/session/mod.rs` — the interactive agent loop
+
+The `CliSession` struct in [`crates/goose-cli/src/session/mod.rs`](https://github.com/block/goose/blob/main/crates/goose-cli/src/session/mod.rs) is the heart of every interactive Goose session:
+
+```rust
+pub struct CliSession {
+ agent: Agent,
+ messages: Conversation,
+ session_id: String,
+ completion_cache: Arc<std::sync::RwLock<CompletionCache>>,
+ debug: bool,
+ run_mode: RunMode,
+ scheduled_job_id: Option<String>,
+ max_turns: Option<u32>,
+ edit_mode: Option<EditMode>,
+ retry_config: Option<RetryConfig>,
+ output_format: String,
+}
```
-This class is important because it defines how Goose Tutorial: Extensible Open-Source AI Agent for Real Engineering Work implements the patterns covered in this chapter.
-
-### `scripts/diagnostics-viewer.py`
-
-The `FileViewer` class in [`scripts/diagnostics-viewer.py`](https://github.com/block/goose/blob/HEAD/scripts/diagnostics-viewer.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-class FileViewer(Vertical):
- """Widget for viewing file contents."""
-
- def __init__(self):
- super().__init__()
- self.current_session = None
- self.current_filename = None
- self.current_part = None
-
- def compose(self) -> ComposeResult:
- """Create child widgets."""
- with Vertical(id="content-area"):
- yield Static("[dim]Select a file to view[/dim]")
-
- yield SearchOverlay()
-
- def update_content(self, session: DiagnosticsSession, filename: str, part: str = None):
- """Update the viewer with new file content.
-
- Args:
- session: The diagnostics session
- filename: The file to display
- part: For JSONL files, either "request" or "responses"
- """
- self.current_session = session
- self.current_filename = filename
- self.current_part = part
-
- content = session.read_file(filename)
- if content is None:
+Its `interactive()` method runs the core loop:
+
+```rust
+loop {
+ self.display_context_usage().await?;
+ output::run_status_hook("waiting");
+ let input = input::get_input(&mut editor, ...)?;
+ if matches!(input, InputResult::Exit) {
+ break;
+ }
+ self.handle_input(input, &history_manager, &mut editor).await?;
+}
```
-This class is important because it defines how Goose Tutorial: Extensible Open-Source AI Agent for Real Engineering Work implements the patterns covered in this chapter.
+Each iteration: display token usage, read input, dispatch to `handle_input()`, which calls the `Agent`, streams tool invocations back, and writes results to the `Conversation`. This is the loop described conceptually in the chapter's "Interactive Loop" section.
+
+### `crates/goose-server/src/routes/reply.rs` — server-side agent streaming
+When using the desktop app or API, the `/reply` SSE endpoint in [`crates/goose-server/src/routes/reply.rs`](https://github.com/block/goose/blob/main/crates/goose-server/src/routes/reply.rs) mirrors the CLI loop over HTTP. It accepts a `ChatRequest` and streams `MessageEvent` variants — `Message`, `Error`, `Finish`, `Notification`, `UpdateConversation`, and `Ping` — back to the client. The implementation uses `tokio::select!` to multiplex cancellation signals, heartbeats (every 500ms), and agent stream responses in the same loop. This is how the agent loop maps to both CLI and desktop surfaces without duplicating logic.
## How These Components Connect
```mermaid
flowchart TD
- A[SearchOverlay]
- B[DiagnosticsSession]
- C[FileContentPane]
- D[FileViewer]
+ A["User input (CLI or desktop)"]
+ B["CliSession.interactive()\nor /reply SSE endpoint"]
+ C["Agent: sends messages + tools to LLM"]
+ D["Tool execution via Extensions (MCP)"]
+ E["Conversation updated\nContext usage tracked"]
A --> B
B --> C
C --> D
+ D --> E
+ E --> B
```
diff --git a/tutorials/goose-tutorial/03-providers-and-model-routing.md b/tutorials/goose-tutorial/03-providers-and-model-routing.md
index d9f18fd5..0c2cf154 100644
--- a/tutorials/goose-tutorial/03-providers-and-model-routing.md
+++ b/tutorials/goose-tutorial/03-providers-and-model-routing.md
@@ -20,6 +20,23 @@ This chapter focuses on selecting and configuring model providers for reliabilit
- avoid common routing and rate-limit pitfalls
- standardize provider settings for team usage
+## Provider Selection Decision Tree
+
+```mermaid
+flowchart TD
+ A[Choosing a provider] --> B{Privacy requirement?}
+ B -->|Data must stay local| C[Ollama or Docker Model Runner]
+ B -->|Cloud OK| D{Enterprise policy?}
+ D -->|AWS/GCP constraints| E[Bedrock or Vertex AI]
+ D -->|No constraint| F{Existing subscription?}
+ F -->|Claude Code / Cursor| G[CLI pass-through provider]
+ F -->|No| H[Anthropic or OpenAI direct API]
+ C --> I[Configure local endpoint]
+ E --> I
+ G --> I
+ H --> I
+```
+
## Provider Categories
| Category | Examples | Notes |
@@ -36,211 +53,160 @@ This chapter focuses on selecting and configuring model providers for reliabilit
3. select a model with tool-calling support
4. validate in a short task before long sessions
-## Routing Stability Tips
-
-- start with one default model before adding many alternatives
-- use fallback strategy only after baseline behavior is stable
-- keep provider credentials scoped and rotated
-- document allowed providers in team onboarding docs
-
-## Rate Limit and Failure Management
-
-| Issue | Prevention |
-|:------|:-----------|
-| intermittent API failures | choose providers with retry-aware infrastructure |
-| unstable model performance | pin known-good models for production tasks |
-| auth drift across machines | standardize env var and secret manager strategy |
-
-## Source References
+After initial setup, your provider and model are stored in `~/.config/goose/config.yaml`. You can verify the active configuration at any time with `goose info`.
-- [Supported LLM Providers](https://block.github.io/goose/docs/getting-started/providers)
-- [CLI Providers Guide](https://block.github.io/goose/docs/guides/cli-providers)
-- [Rate Limits Guide](https://block.github.io/goose/docs/guides/handling-llm-rate-limits-with-goose)
+## Provider Credential Storage
-## Summary
+Goose stores API keys in the system keychain when available, falling back to the config file. For team environments:
-You now know how to route Goose through the right provider and model setup for your constraints.
+- use environment variables (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, etc.) rather than storing keys in the config file
+- rotate keys on a regular schedule and update them via `goose configure` or by re-exporting the environment variable
+- for CI, inject credentials as secrets rather than baking them into images or config files
-Next: [Chapter 4: Permissions and Tool Governance](04-permissions-and-tool-governance.md)
+## Ollama Setup for Local Usage
-## Depth Expansion Playbook
+To use Goose with a locally running Ollama model:
-## Source Code Walkthrough
+1. Install Ollama: `curl -fsSL https://ollama.ai/install.sh | sh`
+2. Pull a tool-capable model: `ollama pull qwen2.5-coder:7b`
+3. Run `goose configure` and select "Ollama" as the provider
+4. Select the model name (e.g., `qwen2.5-coder:7b`)
-### `scripts/diagnostics-viewer.py`
+Local providers have no API costs and no data leaves your machine — useful for sensitive codebases or offline environments. Performance depends on your hardware; a GPU is recommended for models larger than 7B parameters.
-The `ContentReady` class in [`scripts/diagnostics-viewer.py`](https://github.com/block/goose/blob/HEAD/scripts/diagnostics-viewer.py) handles a key part of this chapter's functionality:
+## Routing Stability Tips
-```py
+- start with one default model before adding many alternatives
+- use fallback strategy only after baseline behavior is stable
+- keep provider credentials scoped and rotated
+- document allowed providers in team onboarding docs
- # Auto-focus the content
- self.post_message(self.ContentReady())
+## Model Selection Criteria
- def _show_jsonl(self, filename: str, content: str, part: str):
- """Show JSONL file - either request or responses part."""
- lines = [line.strip() for line in content.strip().split('\n') if line.strip()]
+Not all models support tool calling, and models that do vary significantly in reliability. When choosing a model:
- # Parse lines
- request_data = None
- responses = []
+- **tool-calling support is required** — models that only do text completion will fail at step 3 of the agent loop
+- **context window matters** — for large codebases, choose models with 100k+ context; Goose's compaction reduces but does not eliminate context pressure
+- **extended thinking** — Claude and Gemini models support extended thinking mode, configurable during `goose configure`; this improves quality on complex multi-step tasks at higher token cost
- if len(lines) > 0:
- try:
- request_data = json.loads(lines[0])
- except json.JSONDecodeError:
- # Skip malformed request line; diagnostics may be truncated or corrupted
- pass
+## CLI Pass-Through Providers
- for i in range(1, len(lines)):
- try:
- responses.append(json.loads(lines[i]))
- except json.JSONDecodeError:
- # Skip individual malformed response lines; show only valid JSON entries
- pass
+Goose can delegate inference to other CLI tools you already have authenticated:
- # Show content
- content_area = self.query_one("#content-area", Vertical)
- content_area.remove_children()
+```bash
+# Use Claude Code as provider (reuses your Claude subscription)
+# Select "Claude Code" during goose configure
- if part == "request" and request_data:
- tree = JsonTreeView(f"{filename} - request")
+# Use Cursor Agent as provider
+# Select "Cursor Agent" during goose configure
```
-This class is important because it defines how Goose Tutorial: Extensible Open-Source AI Agent for Real Engineering Work implements the patterns covered in this chapter.
+This is useful in organizations where developers already have subscriptions to one of these tools and adding a separate Goose API key would create overhead.
-### `scripts/diagnostics-viewer.py`
+## Environment Variable Overrides
-The `SessionViewer` class in [`scripts/diagnostics-viewer.py`](https://github.com/block/goose/blob/HEAD/scripts/diagnostics-viewer.py) handles a key part of this chapter's functionality:
+Provider and model can be overridden per-invocation without changing the persisted config:
-```py
+```bash
+GOOSE_PROVIDER=openai GOOSE_MODEL=gpt-4o goose run --text "..."
+```
+This is the recommended pattern for CI pipelines where the provider may differ from a developer's local config.
-class SessionViewer(Vertical):
- """Widget for viewing a diagnostics session."""
+## Rate Limit and Failure Management
- BINDINGS = [
- Binding("ctrl+f,cmd+f", "search", "Search", show=True),
- Binding("c", "copy_file", "Copy file", show=True),
- ]
+| Issue | Prevention |
+|:------|:-----------|
+| intermittent API failures | choose providers with retry-aware infrastructure |
+| unstable model performance | pin known-good models for production tasks |
+| auth drift across machines | standardize env var and secret manager strategy |
+| rate limits in CI | use `GOOSE_PROVIDER` env var to select a higher-quota provider for CI |
+| context window exceeded | tune `GOOSE_AUTO_COMPACT_THRESHOLD` and choose a larger context model |
- def __init__(self, session: DiagnosticsSession):
- super().__init__()
- self.session = session
+## Source References
- def compose(self) -> ComposeResult:
- """Create child widgets."""
- yield Static(f"[bold yellow]Session: {self.session.name}[/bold yellow]", id="session-title")
+- [Supported LLM Providers](https://block.github.io/goose/docs/getting-started/providers)
+- [CLI Providers Guide](https://block.github.io/goose/docs/guides/cli-providers)
+- [Rate Limits Guide](https://block.github.io/goose/docs/guides/handling-llm-rate-limits-with-goose)
- with Horizontal(id="main-content"):
- # Left side: File browser
- with Vertical(id="file-browser"):
- yield Static("[bold]Files:[/bold]")
- tree = Tree("Files", id="file-tree")
- tree.show_root = False
+## Verifying Provider Configuration
- # Build file tree
- files = self.session.get_file_list()
+Before running a long session, validate your provider setup with a short test:
- # Group by directory
- dirs = {}
- for file in files:
- parts = file.split('/')
+```bash
+# Quick validation: ask for a one-line response
+goose run --text "Reply with only: 'Provider is working'" --max-turns 2
```
-This class is important because it defines how Goose Tutorial: Extensible Open-Source AI Agent for Real Engineering Work implements the patterns covered in this chapter.
-
-### `scripts/diagnostics-viewer.py`
-
-The `SessionList` class in [`scripts/diagnostics-viewer.py`](https://github.com/block/goose/blob/HEAD/scripts/diagnostics-viewer.py) handles a key part of this chapter's functionality:
-
-```py
+If this fails, the diagnostic path is:
+1. `goose info` — confirm which provider and model are active
+2. Check that the API key environment variable is set (e.g., `echo $ANTHROPIC_API_KEY`)
+3. Re-run `goose configure` to refresh credentials
+4. Check the provider's status page for outages
+## Summary
-class SessionList(Vertical):
- """Widget for listing available sessions."""
-
- def __init__(self, sessions: list[DiagnosticsSession]):
- super().__init__()
- self.sessions = sessions
-
- def compose(self) -> ComposeResult:
- """Create child widgets."""
- yield Static("[bold yellow]Available Diagnostics Sessions[/bold yellow]\n")
-
- if not self.sessions:
- yield Static("[red]No diagnostics files found[/red]")
- else:
- yield Static(f"[dim]Found {len(self.sessions)} session(s)[/dim]\n")
- yield ListView(id="session-list")
+You now know how to route Goose through the right provider and model setup for your constraints.
- def on_mount(self):
- """Populate the list after mounting."""
- list_view = self.query_one(ListView)
- for session in self.sessions:
- item = ListItem(
- Label(f"{session.name}\n[dim]{session.zip_path.name}[/dim]"),
- name=session.zip_path.name
- )
- list_view.append(item)
+Next: [Chapter 4: Permissions and Tool Governance](04-permissions-and-tool-governance.md)
+## How These Components Connect
-class DiagnosticsApp(App):
- """Diagnostics viewer application."""
+```mermaid
+flowchart TD
+ A[goose configure] --> B[Select provider]
+ B --> C{Provider type}
+ C -->|OpenAI| D[OPENAI_API_KEY]
+ C -->|Anthropic| E[ANTHROPIC_API_KEY]
+ C -->|Ollama| F[Local endpoint]
+ C -->|Other| G[Custom credentials]
+ D --> H[~/.config/goose/config.yaml]
+ E --> H
+ F --> H
+ G --> H
+ H --> I[Agent uses configured LLM]
```
-This class is important because it defines how Goose Tutorial: Extensible Open-Source AI Agent for Real Engineering Work implements the patterns covered in this chapter.
-
-### `scripts/diagnostics-viewer.py`
-
-The `DiagnosticsApp` class in [`scripts/diagnostics-viewer.py`](https://github.com/block/goose/blob/HEAD/scripts/diagnostics-viewer.py) handles a key part of this chapter's functionality:
-
-```py
-
+## Source Code Walkthrough
-class DiagnosticsApp(App):
- """Diagnostics viewer application."""
+### `crates/goose-cli/src/commands/configure.rs` — provider selection and credential management
- # Disable command palette (Ctrl+\)
- ENABLE_COMMAND_PALETTE = False
+The `configure_provider_dialog()` function in [`crates/goose-cli/src/commands/configure.rs`](https://github.com/block/goose/blob/main/crates/goose-cli/src/commands/configure.rs) is the main entry point for provider setup:
- CSS = """
- Screen {
- background: $surface;
- }
+```rust
+pub async fn configure_provider_dialog() -> anyhow::Result<bool> {
+ let config = Config::global();
+ let mut available_providers = providers().await;
+ available_providers.sort_by(|a, b| a.0.display_name.cmp(&b.0.display_name));
- /* Modal styles */
- TextViewerModal {
- align: center middle;
- }
+ let provider_name = cliclack::select("Which model provider should we use?")
+ .initial_value(&default_provider)
+ .items(&provider_items)
+ .filter_mode()
+ .interact()?;
- #modal-container {
- width: 80%;
- height: 80%;
- background: $surface;
- border: thick $primary;
- padding: 1;
+ for key in provider_meta.config_keys.iter().filter(|k| k.primary || k.oauth_flow) {
+ if !configure_single_key(config, provider_name, &provider_meta.display_name, key).await? {
+ return Ok(false);
+ }
}
-
- #modal-title {
- background: $primary;
- color: $text;
- padding: 1;
- text-align: center;
- dock: top;
+ // ... model selection, optional extended thinking config, test call
+ Ok(true)
+}
```
-This class is important because it defines how Goose Tutorial: Extensible Open-Source AI Agent for Real Engineering Work implements the patterns covered in this chapter.
+Provider registration uses the `ProviderMetadata` type, which declares `config_keys` (required credentials), `display_name`, and `description`. `Config::global()` is a singleton backed by `~/.config/goose/config.yaml`.
+### `crates/goose-server/src/routes/agent.rs` — runtime provider and model switching
-## How These Components Connect
+The `UpdateProviderRequest` struct in [`crates/goose-server/src/routes/agent.rs`](https://github.com/block/goose/blob/main/crates/goose-server/src/routes/agent.rs) allows the desktop app to swap providers at runtime without restarting the binary:
-```mermaid
-flowchart TD
- A[ContentReady]
- B[SessionViewer]
- C[SessionList]
- D[DiagnosticsApp]
- A --> B
- B --> C
- C --> D
+```rust
+// Deserialized from POST /agent/update_provider
+pub struct UpdateProviderRequest {
+ pub provider: String,
+ pub model: String,
+}
```
+
+The route handler re-initializes the agent with the new provider+model pair while preserving the existing session state. This is what powers the provider dropdown in the Goose desktop UI and is also usable from scripts via the Goose API.
diff --git a/tutorials/goose-tutorial/04-permissions-and-tool-governance.md b/tutorials/goose-tutorial/04-permissions-and-tool-governance.md
index cbe1ad05..7417920a 100644
--- a/tutorials/goose-tutorial/04-permissions-and-tool-governance.md
+++ b/tutorials/goose-tutorial/04-permissions-and-tool-governance.md
@@ -31,206 +31,180 @@ This chapter covers the controls that separate fast automation from unsafe autom
## Tool Governance Practices
-1. prefer `Manual` or `Smart` for production repositories
-2. explicitly deny destructive tools where not needed
-3. keep active tool set small to reduce model confusion
-4. use `.gooseignore` to exclude sensitive or noisy paths
+1. prefer `Approve` or `SmartApprove` for production repositories
+2. explicitly restrict destructive tools where not needed (shell, file write)
+3. keep active tool set small to reduce model confusion — load only the extensions needed for the task
+4. use `.gooseignore` to exclude sensitive or noisy paths from context
+5. use `--container` for any task that executes user-provided or external code
-## Corporate Policy Control
+## What Smart Approval Covers
-For restricted environments, Goose can enforce extension allowlists via `GOOSE_ALLOWLIST` and a hosted YAML allowlist policy.
+`SmartApprove` (also called "Smart Approval" in the UI) applies risk-based logic:
-## Source References
+- **auto-approves** read-only operations: file reads, directory listing, search, web fetch
+- **requires approval** for modification operations: file writes, shell commands, API mutations
+- **always blocks** operations on paths in `.gooseignore`
-- [goose Permission Modes](https://block.github.io/goose/docs/guides/goose-permissions)
-- [Managing Tool Permissions](https://block.github.io/goose/docs/guides/managing-tools/tool-permissions)
-- [goose Extension Allowlist](https://block.github.io/goose/docs/guides/allowlist)
-- [Using .gooseignore](https://block.github.io/goose/docs/guides/using-gooseignore)
+This mode provides most of the safety benefit of full approval mode with significantly less friction for investigation and analysis tasks.
-## Summary
+## Choosing a Permission Mode by Task Class
-You now have a concrete security-control model for tool execution in Goose.
+| Task Class | Recommended Mode | Rationale |
+|:-----------|:-----------------|:----------|
+| exploring an unfamiliar codebase | Chat | no side effects, no accidental writes |
+| reviewing and summarizing PRs | Chat or SmartApprove | read-heavy, minimal write risk |
+| refactoring with human oversight | SmartApprove | approves modifications, skips reads |
+| automated CI task with known scope | Auto + `--max-turns` | bounded task, controlled environment |
+| running untrusted extensions | Approve + `--container` | sandbox + explicit approval at each step |
-Next: [Chapter 5: Sessions and Context Management](05-sessions-and-context-management.md)
+## The `.gooseignore` File
-## Depth Expansion Playbook
+`.gooseignore` follows `.gitignore` syntax and tells Goose which files and directories to treat as off-limits for reads and writes:
-## Source Code Walkthrough
+```
+# .gooseignore example
+.env
+*.pem
+secrets/
+node_modules/
+dist/
+```
+
+Place this file at the repository root. Goose will not expose files matching these patterns as context or attempt to modify them. This is particularly important when your working directory contains credentials or generated artifacts that should never appear in LLM context.
-### `scripts/diagnostics-viewer.py`
+## Container Isolation
-The `truncate_string` function in [`scripts/diagnostics-viewer.py`](https://github.com/block/goose/blob/HEAD/scripts/diagnostics-viewer.py) handles a key part of this chapter's functionality:
+The `--container docker-image:tag` flag in `SessionOptions` forces all extension tool calls to execute inside a Docker container. The agent itself runs on your host, but shell commands, file writes, and other tool-backed actions are forwarded into the container:
-```py
+```bash
+goose session --container ubuntu:22.04 --with-builtin developer
+```
+Use this when:
+- running code generation tasks in a clean environment
+- testing extensions that may have side effects
+- isolating network access for security-sensitive tasks
-def truncate_string(s: str, max_len: int = 100, edge_len: int = 35) -> str:
- """Truncate a string if it's longer than max_len."""
- if len(s) <= max_len:
- return s
+## Risk Assessment by Tool Class
- omitted = len(s) - (2 * edge_len)
- return f"{s[:edge_len]}[{omitted} more]{s[-edge_len:]}"
+Not all tools carry equal risk. When thinking about which permission mode to apply, consider the tool's potential impact:
+| Tool Class | Examples | Risk Level | Recommended Mode |
+|:-----------|:---------|:-----------|:-----------------|
+| Read-only filesystem | `read_file`, `list_directory` | Low | Auto-approve in SmartApprove |
+| Web fetch | `web_search`, `fetch_url` | Low-Medium | Auto-approve in SmartApprove |
+| File writes | `write_file`, `create_file` | Medium | Require approval in SmartApprove |
+| Shell execution | `shell_exec`, `run_command` | High | Require approval in all modes except Auto |
+| External API mutations | `create_pr`, `deploy_service` | High | Use Approve mode |
+| Network configuration | firewall, DNS, routing | Critical | Approve + manual review before run |
-class JsonTreeView(Tree):
- """A tree widget for displaying collapsible JSON."""
+## Corporate Policy Control
- BINDINGS = [
- Binding("ctrl+o", "toggle_all", "Toggle All", show=True),
- ]
+For restricted environments, Goose can enforce extension allowlists via `GOOSE_ALLOWLIST` and a hosted YAML allowlist policy. The allowlist YAML specifies which extension commands and sources are approved, blocking any extension not on the list from loading — even if a user tries to add it via `goose configure`.
- def __init__(self, *args, **kwargs):
- super().__init__(*args, **kwargs)
- self.json_data = None
- self.show_root = False
- self.all_expanded = False
+## Practical Permission Workflow
- def load_json(self, data: Any, label: str = "JSON"):
- """Load JSON data into the tree."""
- self.json_data = data
- self.clear()
- self.root.label = label
- self._build_tree(self.root, data)
- # Expand all nodes by default
- self.root.expand_all()
-```
+When starting a new type of task:
-This function is important because it defines how Goose Tutorial: Extensible Open-Source AI Agent for Real Engineering Work implements the patterns covered in this chapter.
-
-### `scripts/diagnostics-viewer.py`
-
-The `main` function in [`scripts/diagnostics-viewer.py`](https://github.com/block/goose/blob/HEAD/scripts/diagnostics-viewer.py) handles a key part of this chapter's functionality:
-
-```py
- yield Static(f"[bold yellow]Session: {self.session.name}[/bold yellow]", id="session-title")
-
- with Horizontal(id="main-content"):
- # Left side: File browser
- with Vertical(id="file-browser"):
- yield Static("[bold]Files:[/bold]")
- tree = Tree("Files", id="file-tree")
- tree.show_root = False
-
- # Build file tree
- files = self.session.get_file_list()
-
- # Group by directory
- dirs = {}
- for file in files:
- parts = file.split('/')
- is_jsonl = file.endswith('.jsonl')
-
- if len(parts) == 1:
- # Root file
- if is_jsonl:
- # Add two entries for JSONL files
- tree.root.add_leaf(f"{file} - request", data={"file": file, "part": "request"})
- tree.root.add_leaf(f"{file} - responses", data={"file": file, "part": "responses"})
- else:
- tree.root.add_leaf(file, data={"file": file, "part": None})
- else:
- # File in directory
- dir_name = parts[0]
- if dir_name not in dirs:
- dirs[dir_name] = tree.root.add(dir_name, expand=True)
+1. Begin with `SmartApprove` and observe which approvals come up
+2. If the same low-risk approval appears repeatedly, consider explicitly allowing it via `PermissionManager`
+3. If an unexpected high-risk approval appears, stop and review before approving
+4. Document the settled permission profile and share it in team onboarding
-```
+## Per-Tool Permission Overrides
+
+On top of the global mode, individual tools can be set to always-allow or always-deny via the `PermissionManager`. This lets you create configurations like:
+
+- global mode: `SmartApprove`
+- `read_file` tool: always-allow (skip approval for reads)
+- `shell_exec` tool: always-deny unless explicitly re-enabled per session
+
+## Source References
+
+- [goose Permission Modes](https://block.github.io/goose/docs/guides/goose-permissions)
+- [Managing Tool Permissions](https://block.github.io/goose/docs/guides/managing-tools/tool-permissions)
+- [goose Extension Allowlist](https://block.github.io/goose/docs/guides/allowlist)
+- [Using .gooseignore](https://block.github.io/goose/docs/guides/using-gooseignore)
-This function is important because it defines how Goose Tutorial: Extensible Open-Source AI Agent for Real Engineering Work implements the patterns covered in this chapter.
-
-### `recipe-scanner/decode-training-data.py`
-
-The `decode_training_data` function in [`recipe-scanner/decode-training-data.py`](https://github.com/block/goose/blob/HEAD/recipe-scanner/decode-training-data.py) handles a key part of this chapter's functionality:
-
-```py
-from pathlib import Path
-
-def decode_training_data():
- """
- Decode all available training data from environment variables
- Returns a dictionary with risk levels and their decoded recipes
- """
- training_data = {}
-
- # Check for each risk level
- for risk_level in ["LOW", "MEDIUM", "HIGH", "EXTREME"]:
- env_var = f"TRAINING_DATA_{risk_level}"
- encoded_data = os.environ.get(env_var)
-
- if encoded_data:
- try:
- # Decode the base64 outer layer
- json_data = base64.b64decode(encoded_data).decode('utf-8')
-
- # Parse the JSON
- parsed_data = json.loads(json_data)
-
- # Decode each recipe's content
- for recipe in parsed_data.get('recipes', []):
- recipe_content = base64.b64decode(recipe['content_base64']).decode('utf-8')
- recipe['content'] = recipe_content
- # Keep the base64 version for reference but don't need it for analysis
-
- training_data[risk_level.lower()] = parsed_data
- print(f"✅ Decoded {len(parsed_data['recipes'])} {risk_level.lower()} risk recipes")
-
- except Exception as e:
+## Decision Flowchart for Permission Mode
+
+```mermaid
+flowchart TD
+ A[Starting a new task] --> B{Is this a production repository?}
+ B -->|Yes| C[Use SmartApprove or Approve]
+ B -->|No| D{Is this exploratory analysis only?}
+ D -->|Yes| E[Use Chat mode]
+ D -->|No| F{Is the task fully automated in CI?}
+ F -->|Yes| G[Use Auto + --max-turns + --container]
+ F -->|No| H[Use SmartApprove as default]
```
-This function is important because it defines how Goose Tutorial: Extensible Open-Source AI Agent for Real Engineering Work implements the patterns covered in this chapter.
-
-### `recipe-scanner/decode-training-data.py`
-
-The `write_training_files` function in [`recipe-scanner/decode-training-data.py`](https://github.com/block/goose/blob/HEAD/recipe-scanner/decode-training-data.py) handles a key part of this chapter's functionality:
-
-```py
- return training_data
-
-def write_training_files(training_data, output_dir="/tmp/training"):
- """
- Write decoded training files to disk for Goose to analyze
- """
- output_path = Path(output_dir)
- output_path.mkdir(exist_ok=True)
-
- # Write a summary file for Goose
- summary = {
- "training_summary": "Recipe security training data",
- "risk_levels": {},
- "total_recipes": 0
- }
-
- for risk_level, data in training_data.items():
- risk_dir = output_path / risk_level
- risk_dir.mkdir(exist_ok=True)
-
- recipes_info = []
-
- for recipe in data.get('recipes', []):
- # Write the recipe file
- recipe_file = risk_dir / recipe['filename']
- with open(recipe_file, 'w') as f:
- f.write(recipe['content'])
-
- # Write the training notes
- notes_file = risk_dir / f"{recipe['filename']}.notes.txt"
- with open(notes_file, 'w') as f:
- f.write(f"Risk Level: {risk_level.upper()}\n")
+## Quick Reference: Permission Flags
+
+```bash
+# Set mode at configure time (persisted)
+goose configure # select permission mode in wizard
+
+# Override mode for a single session
+GOOSE_MODE=approve goose session
+
+# Sandbox with container isolation
+goose session --container ubuntu:22.04 --with-builtin developer
+
+# Hard cap on iterations
+goose run --text "..." --max-turns 20 --max-tool-repetitions 3
```
-This function is important because it defines how Goose Tutorial: Extensible Open-Source AI Agent for Real Engineering Work implements the patterns covered in this chapter.
+## Summary
+
+You now have a concrete security-control model for tool execution in Goose.
+Next: [Chapter 5: Sessions and Context Management](05-sessions-and-context-management.md)
## How These Components Connect
```mermaid
flowchart TD
- A[truncate_string]
- B[main]
- C[decode_training_data]
- D[write_training_files]
- A --> B
- B --> C
- C --> D
+ A[Agent wants to run tool] --> B{Permission mode}
+ B -->|auto| C[Execute without prompting]
+ B -->|approve| D[User approves each tool call]
+ B -->|deny-all| E[Block all tool execution]
+ C --> F[Tool runs in sandbox or host]
+ D -->|approved| F
+ D -->|denied| G[Agent notified, retries with different approach]
+ E --> G
+```
+
+## Source Code Walkthrough
+
+### `crates/goose-cli/src/commands/configure.rs` — `GooseMode` and `PermissionManager`
+
+The `GooseMode` enum and `PermissionManager` type are both imported by [`crates/goose-cli/src/commands/configure.rs`](https://github.com/block/goose/blob/main/crates/goose-cli/src/commands/configure.rs):
+
+```rust
+use goose::config::{Config, ConfigError, ExperimentManager,
+ ExtensionEntry, GooseMode, PermissionManager};
```
+
+`GooseMode` has four variants backing the four permission modes:
+
+| Variant | Behavior |
+|:--------|:---------|
+| `Auto` | Full file and shell modification without prompts |
+| `Approve` | Requires human approval before every tool action |
+| `SmartApprove` | Risk-based approvals — prompts for modifications, not reads |
+| `Chat` | Provider interaction only, no tool execution |
+
+The `PermissionManager` manages per-tool overrides on top of the global mode. This separation lets you set `SmartApprove` as the global default while explicitly allowing specific read-only tools to run without approval.
+
+### `crates/goose-cli/src/cli.rs` — runtime governance flags
+
+The `SessionOptions` group in [`crates/goose-cli/src/cli.rs`](https://github.com/block/goose/blob/main/crates/goose-cli/src/cli.rs) contains the key runtime governance flags:
+
+```
+--max-tool-repetitions // Limit consecutive identical tool calls
+--max-turns // Iteration ceiling (default: 1000)
+--container IMAGE // Run extensions inside a Docker container
+```
+
+Setting `--container ubuntu:22.04` forwards all tool-backed shell commands into the container, sandboxing writes and network access from the host. This is the recommended approach when running extensions that execute arbitrary code or have broad filesystem access.
diff --git a/tutorials/goose-tutorial/05-sessions-and-context-management.md b/tutorials/goose-tutorial/05-sessions-and-context-management.md
index 1459931c..58bba888 100644
--- a/tutorials/goose-tutorial/05-sessions-and-context-management.md
+++ b/tutorials/goose-tutorial/05-sessions-and-context-management.md
@@ -20,6 +20,21 @@ This chapter explains how Goose keeps long-running workflows productive without
- control runaway loops with max-turn governance
- tune session behavior for interactive vs headless usage
+## Session Lifecycle Overview
+
+```mermaid
+stateDiagram-v2
+ [*] --> Created: goose session -n name
+ Created --> Active: User sends first message
+ Active --> Compacting: Near token threshold
+ Compacting --> Active: Summary inserted, loop continues
+ Active --> Paused: User exits (Ctrl+C or /exit)
+ Paused --> Active: goose session -n name (resume)
+ Active --> Completed: Task done or --max-turns reached
+ Completed --> Exported: goose session export
+ Completed --> [*]: goose session remove
+```
+
## Session Operations
| Action | CLI Example | Outcome |
@@ -47,196 +62,161 @@ Useful environment controls include:
- headless flows: use `summarize` for continuity
- high-risk automation: lower max turns and require approvals
+## Environment Variables Reference
+
+| Variable | Default | Effect |
+|:---------|:--------|:-------|
+| `GOOSE_AUTO_COMPACT_THRESHOLD` | 0.8 (80% of context window) | When to trigger auto-compaction |
+| `GOOSE_CONTEXT_STRATEGY` | `summarize` | Strategy used when compacting (`summarize`, `prompt`, `truncate`) |
+| `GOOSE_MAX_TURNS` | 1000 | Global turn ceiling across all sessions |
+| `GOOSE_SESSION_DIR` | `~/.config/goose/sessions/` | Where session files are stored |
+
+These can be set in your shell profile for system-wide defaults, or in a `.env` file at the project root for project-specific overrides.
+
+## Naming Conventions for Sessions
+
+Good session names make the history useful:
+
+- include a scope: `goose session -n auth-refactor-jan` or `goose session -n release-v2.1`
+- avoid generic names like `test` or `session1` — they are hard to distinguish in `goose session list`
+- for CI-generated sessions, use `$(date +%Y%m%d)-$(git rev-parse --short HEAD)` as the name suffix
+
## Source References
- [Session Management](https://block.github.io/goose/docs/guides/sessions/session-management)
- [Smart Context Management](https://block.github.io/goose/docs/guides/sessions/smart-context-management)
- [Logs and Session Records](https://block.github.io/goose/docs/guides/logs)
-## Summary
+## Exporting Sessions for Review
-You now know how to run longer Goose sessions without uncontrolled context growth.
+Session exports are a powerful debugging and audit tool:
-Next: [Chapter 6: Extensions and MCP Integration](06-extensions-and-mcp-integration.md)
+```bash
+# Export a named session to Markdown for human review
+goose session export --format markdown --name release-hardening \
+ --output release-hardening-session.md
-## Depth Expansion Playbook
+# Export to JSON for programmatic processing
+goose session export --format json --name release-hardening | \
+ jq '[.messages[] | select(.role == "tool")]'
+```
-## Source Code Walkthrough
+The Markdown format reconstructs the full conversation with tool call inputs and outputs inlined — readable without any special tooling. The JSON format exposes the raw `Conversation` struct for scripted analysis.
+
+## Context Strategy Comparison
+
+| Strategy | Behavior | Best For |
+|:---------|:---------|:---------|
+| `summarize` (default) | older turns replaced with LLM-generated summary | headless/CI tasks where continuity matters |
+| `prompt` | pauses and asks the user before compacting | interactive debugging where you want control |
+| `truncate` | drops oldest turns without summarizing | cost-sensitive contexts where summary quality is less important |
+
+Set via `GOOSE_CONTEXT_STRATEGY=summarize` in your environment or in `.env` at the project root.
+
+## Quick Reference: Session Commands
+
+```bash
+# Start a named interactive session
+goose session -n my-task
-### `recipe-scanner/decode-training-data.py`
-
-The `create_goose_instructions` function in [`recipe-scanner/decode-training-data.py`](https://github.com/block/goose/blob/HEAD/recipe-scanner/decode-training-data.py) handles a key part of this chapter's functionality:
-
-```py
- return output_path
-
-def create_goose_instructions(training_data, output_file="/tmp/goose_training_instructions.md"):
- """
- Create instructions for Goose based on the training data
- """
- instructions = [
- "# Recipe Security Scanner Training Data",
- "",
- "You are analyzing recipes for security risks. Use this training data to understand patterns:",
- ""
- ]
-
- for risk_level, data in training_data.items():
- instructions.append(f"## {risk_level.upper()} Risk Examples")
- instructions.append("")
-
- for recipe in data.get('recipes', []):
- instructions.append(f"### {recipe['filename']}")
- instructions.append(f"**Training Notes**: {recipe['training_notes']}")
- instructions.append("")
-
- instructions.extend([
- "## Key Security Patterns to Watch For:",
- "",
- "1. **Hidden UTF-8 Characters**: Invisible or misleading Unicode characters",
- "2. **Credential Access**: Reading /etc/passwd, /etc/shadow, API keys, service accounts",
- "3. **Data Exfiltration**: Sending data to external servers",
- "4. **External Downloads**: Downloading and executing scripts from URLs",
- "5. **Suppressed Output**: Commands that hide their output (> /dev/null)",
- "6. **Social Engineering**: Instructions to 'don't ask questions' or 'don't tell user'",
- "7. **Reverse Shells**: Network connections to attacker-controlled servers",
+# Resume a named session
+goose session -n my-task # re-using the same name resumes
+
+# List all sessions
+goose session list
+goose session list --format json
+
+# Export a session to Markdown
+goose session export --format markdown --name my-task
+
+# Remove old sessions
+goose session remove --name my-task
+
+# Generate diagnostics bundle
+goose session diagnostics --output /tmp/diag.zip
```
-This function is important because it defines how Goose Tutorial: Extensible Open-Source AI Agent for Real Engineering Work implements the patterns covered in this chapter.
+## Summary
-### `examples/frontend_tools.py`
+You now know how to run longer Goose sessions without uncontrolled context growth.
-The `setup_agent` function in [`examples/frontend_tools.py`](https://github.com/block/goose/blob/HEAD/examples/frontend_tools.py) handles a key part of this chapter's functionality:
+Next: [Chapter 6: Extensions and MCP Integration](06-extensions-and-mcp-integration.md)
-```py
+## Session File Storage
+Sessions are stored as files under `~/.config/goose/sessions/`. Named sessions use the name you supply; anonymous sessions get a timestamp-based ID. The structure allows:
-async def setup_agent() -> None:
- """Initialize the agent with our frontend tool."""
- async with httpx.AsyncClient() as client:
- # First create the agent
- response = await client.post(
- f"{GOOSE_URL}/agent/update_provider",
- json={"provider": "databricks", "model": "goose"},
- headers={"X-Secret-Key": SECRET_KEY},
- )
- response.raise_for_status()
- print("Successfully created agent")
+- resuming a session after an interruption: `goose session -n release-hardening`
+- exporting for review: `goose session export --format markdown -n release-hardening`
+- deleting stale sessions to reclaim disk: `goose session remove --name release-hardening`
- # Then add our frontend extension
- response = await client.post(
- f"{GOOSE_URL}/extensions/add",
- json=FRONTEND_CONFIG,
- headers={"X-Secret-Key": SECRET_KEY},
- )
- response.raise_for_status()
- print("Successfully added calculator extension")
+When you resume a session, the full conversation history is loaded into the `Conversation` struct and context management rules apply from that point forward — so even resumed sessions benefit from auto-compaction.
+## Max Turns in Practice
-def execute_calculator(args: Dict[str, Any]) -> List[Dict[str, Any]]:
- """Execute the calculator tool with the given arguments."""
- operation = args["operation"]
- numbers = args["numbers"]
+`GOOSE_MAX_TURNS` and the `--max-turns` CLI flag are the most effective safeguards against runaway automation. A sensible baseline:
- try:
- result = None
- if operation == "add":
-```
+| Context | Recommended `--max-turns` |
+|:--------|:--------------------------|
+| exploration and investigation | default (1000) or unset |
+| focused refactor task | 50–100 |
+| CI automation step | 20–40 |
+| untrusted input or external data | 10–20 |
-This function is important because it defines how Goose Tutorial: Extensible Open-Source AI Agent for Real Engineering Work implements the patterns covered in this chapter.
-
-### `examples/frontend_tools.py`
-
-The `execute_calculator` function in [`examples/frontend_tools.py`](https://github.com/block/goose/blob/HEAD/examples/frontend_tools.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def execute_calculator(args: Dict[str, Any]) -> List[Dict[str, Any]]:
- """Execute the calculator tool with the given arguments."""
- operation = args["operation"]
- numbers = args["numbers"]
-
- try:
- result = None
- if operation == "add":
- result = sum(numbers)
- elif operation == "subtract":
- result = numbers[0] - sum(numbers[1:])
- elif operation == "multiply":
- result = 1
- for n in numbers:
- result *= n
- elif operation == "divide":
- result = numbers[0]
- for n in numbers[1:]:
- result /= n
-
- # Return properly structured Content::Text variant
- return [
- {
- "type": "text",
- "text": str(result),
- "annotations": None, # Required field in Rust struct
- }
- ]
- except Exception as e:
- return [
-```
+When the turn limit is reached, Goose exits the session cleanly (non-zero exit code) so your script or CI pipeline can detect and handle the failure.
-This function is important because it defines how Goose Tutorial: Extensible Open-Source AI Agent for Real Engineering Work implements the patterns covered in this chapter.
-
-### `examples/frontend_tools.py`
-
-The `get_tools` function in [`examples/frontend_tools.py`](https://github.com/block/goose/blob/HEAD/examples/frontend_tools.py) handles a key part of this chapter's functionality:
-
-```py
- ]
-
-def get_tools() -> Dict[str, Any]:
- with httpx.Client() as client:
- response = client.get(
- f"{GOOSE_URL}/agent/tools",
- headers={"X-Secret-Key": SECRET_KEY},
- )
- response.raise_for_status()
- return response.json()
-
-
-def execute_enable_extension(args: Dict[str, Any]) -> List[Dict[str, Any]]:
- """
- Execute the enable_extension tool.
- This function fetches available extensions, finds the one with the provided extension_name,
- and posts its configuration to the /extensions/add endpoint.
- """
- extension = args
- extension_name = extension.get("name")
-
- # Post the extension configuration to enable it
- with httpx.Client() as client:
- payload = {
- "type": extension.get("type"),
- "name": extension.get("name"),
- "cmd": extension.get("cmd"),
- "args": extension.get("args"),
- "envs": extension.get("envs", {}),
- "timeout": extension.get("timeout"),
- "bundled": extension.get("bundled"),
- }
-```
+## Web Session Mode
-This function is important because it defines how Goose Tutorial: Extensible Open-Source AI Agent for Real Engineering Work implements the patterns covered in this chapter.
+`goose web --open` starts a local HTTP server and opens a browser-based chat UI. This is useful when:
+- working on a remote server over SSH without a terminal-friendly setup
+- sharing a session view with a teammate (same machine)
+- using a browser extension or bookmark to quickly open Goose
+The web interface shares the same session storage as the CLI, so sessions started via `goose web` are visible in `goose session list`.
## How These Components Connect
```mermaid
flowchart TD
- A[create_goose_instructions]
- B[setup_agent]
- C[execute_calculator]
- D[get_tools]
- A --> B
- B --> C
- C --> D
+ A[goose session start] --> B[Session file created]
+ B --> C[Conversation messages stored]
+ C --> D{Context window}
+ D -->|Under limit| E[Include all messages]
+ D -->|Near limit| F[Summarize older messages]
+ F --> E
+ E --> G[Send to LLM]
+ G --> H[Response appended to session]
+ H --> C
```
+
+## Source Code Walkthrough
+
+### `crates/goose-cli/src/session/mod.rs` — `CliSession` and context tracking
+
+The `CliSession` struct in [`crates/goose-cli/src/session/mod.rs`](https://github.com/block/goose/blob/main/crates/goose-cli/src/session/mod.rs) holds both the conversation history and the fields that control session lifecycle:
+
+```rust
+pub struct CliSession {
+ agent: Agent,
+ messages: Conversation, // full turn history
+ session_id: String, // used for resume/export
+ max_turns: Option<u32>, // enforces GOOSE_MAX_TURNS ceiling
+ retry_config: Option<RetryConfig>,
+ run_mode: RunMode, // Interactive vs headless (Run)
+ output_format: String, // text or json
+ // ...
+}
+```
+
+Context usage is surfaced via `display_context_usage()`, which queries the session manager for current token counts relative to the model's limit. When compaction fires (controlled by `GOOSE_AUTO_COMPACT_THRESHOLD`), the agent rewrites the `Conversation` with a summarized history.
+
+### `crates/goose-cli/src/commands/session.rs` — session lifecycle operations
+
+[`crates/goose-cli/src/commands/session.rs`](https://github.com/block/goose/blob/main/crates/goose-cli/src/commands/session.rs) implements the session management commands:
+
+- **`handle_session_list()`** — lists all sessions with optional working-directory filter and JSON output mode; handles broken-pipe gracefully when piping to `head` or `grep`
+- **`handle_session_remove()`** — deletes by ID, name, or regex with confirmation before destructive action
+- **`handle_session_export()`** — exports to JSON, YAML, or Markdown; Markdown format reconstructs the full conversation with tool calls inlined
+- **`handle_diagnostics()`** — bundles session metadata and logs into a ZIP file for sharing with support
+
+Named sessions created via `goose session -n release-hardening` are stored under `~/.config/goose/sessions/` and can be resumed or exported at any time.
diff --git a/tutorials/goose-tutorial/06-extensions-and-mcp-integration.md b/tutorials/goose-tutorial/06-extensions-and-mcp-integration.md
index f89b4d5a..527c4d76 100644
--- a/tutorials/goose-tutorial/06-extensions-and-mcp-integration.md
+++ b/tutorials/goose-tutorial/06-extensions-and-mcp-integration.md
@@ -20,18 +20,36 @@ This chapter covers how Goose expands beyond built-ins through MCP extension wor
- add custom MCP servers via UI or CLI
- standardize extension rollout for teams
+## Extension Architecture
+
+```mermaid
+flowchart TD
+ A["Goose Agent"] --> B["Extension Manager"]
+ B --> C["Builtin: Developer\n(crates/goose-mcp/src/)"]
+ B --> D["Builtin: Memory\n(crates/goose-mcp/src/memory/)"]
+ B --> E["Builtin: Computer Controller\n(crates/goose-mcp/src/computercontroller/)"]
+ B --> F["Custom Stdio MCP\n(any MCP-compliant subprocess)"]
+ B --> G["Remote StreamableHttp MCP\n(cloud-hosted MCP server)"]
+ C --> H["Tools exposed to LLM via ToolRouter"]
+ D --> H
+ E --> H
+ F --> H
+ G --> H
+```
+
## Built-In Extension Surface
-Goose includes development and platform extensions such as:
+Goose includes development and platform extensions shipped as part of `crates/goose-mcp/`:
-- Developer
-- Computer Controller
-- Memory
-- Extension Manager
-- Skills
-- Todo
+| Extension | Crate Path | Primary Tools |
+|:----------|:-----------|:--------------|
+| Developer | `src/developer/` | `read_file`, `write_file`, `shell_exec`, `list_directory` |
+| Computer Controller | `src/computercontroller/` | screen capture, mouse/keyboard control, browser, PDF/DOCX/XLSX processing |
+| Memory | `src/memory/` | `remember_memory`, `retrieve_memories`, `remove_memory_category` |
+| AutoVisualiser | `src/autovisualiser/` | auto-generates visualizations from data |
+| Tutorial | `src/tutorial/` | in-agent tutorial guidance |
-These can be toggled based on task needs to reduce tool overload.
+These can be toggled based on task needs to reduce tool overload. Loading fewer extensions means the model sees a smaller tool list, which improves tool selection accuracy for specialized tasks.
## Custom MCP Flow (CLI)
@@ -41,195 +59,151 @@ goose configure
# choose: Command-line Extension OR Remote Extension
```
-Example pattern for an MCP server command:
+Example commands for popular community MCP servers:
```bash
-npx -y @modelcontextprotocol/server-memory
-```
+# Filesystem access (scoped to a directory)
+npx -y @modelcontextprotocol/server-filesystem /path/to/allowed/dir
-## Extension Safety Checklist
-
-1. review extension command/source
-2. set reasonable timeout values
-3. apply tool permissions before broad usage
-4. test in a sandbox repository first
-
-## Source References
+# GitHub integration
+npx -y @modelcontextprotocol/server-github
-- [Using Extensions](https://block.github.io/goose/docs/getting-started/using-extensions)
-- [Model Context Protocol](https://modelcontextprotocol.io/)
-- [MCP Server Directory](https://www.pulsemcp.com/servers)
+# Postgres database
+npx -y @modelcontextprotocol/server-postgres postgresql://user:pass@host/db
-## Summary
+# Brave web search
+npx -y @modelcontextprotocol/server-brave-search
+```
-You now know how to evolve Goose capabilities with built-in and external MCP integrations.
+Each of these spawns as a subprocess that communicates with Goose over stdin/stdout using the MCP protocol. The tools they expose become available to the LLM in the next session.
-Next: [Chapter 7: CLI Workflows and Automation](07-cli-workflows-and-automation.md)
+## Managing Extensions Across Sessions
-## Depth Expansion Playbook
+Extensions added via `goose configure` persist to `~/.config/goose/config.yaml` and load for all future sessions. To use an extension only for a specific session:
-## Source Code Walkthrough
+```bash
+# Only for this session — not persisted
+goose session --with-extension "npx -y @modelcontextprotocol/server-github"
-### `examples/frontend_tools.py`
-
-The `execute_enable_extension` function in [`examples/frontend_tools.py`](https://github.com/block/goose/blob/HEAD/examples/frontend_tools.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def execute_enable_extension(args: Dict[str, Any]) -> List[Dict[str, Any]]:
- """
- Execute the enable_extension tool.
- This function fetches available extensions, finds the one with the provided extension_name,
- and posts its configuration to the /extensions/add endpoint.
- """
- extension = args
- extension_name = extension.get("name")
-
- # Post the extension configuration to enable it
- with httpx.Client() as client:
- payload = {
- "type": extension.get("type"),
- "name": extension.get("name"),
- "cmd": extension.get("cmd"),
- "args": extension.get("args"),
- "envs": extension.get("envs", {}),
- "timeout": extension.get("timeout"),
- "bundled": extension.get("bundled"),
- }
- add_response = client.post(
- f"{GOOSE_URL}/extensions/add",
- json=payload,
- headers={"Content-Type": "application/json", "X-Secret-Key": SECRET_KEY},
- )
- if add_response.status_code != 200:
- error_text = add_response.text
- return [{
- "type": "text",
- "text": f"Error: Failed to enable extension: {error_text}",
+# Only for this run — not persisted
+goose run --text "..." --with-extension "npx -y @modelcontextprotocol/server-github"
```
-This function is important because it defines how Goose Tutorial: Extensible Open-Source AI Agent for Real Engineering Work implements the patterns covered in this chapter.
+To remove a persisted extension, run `goose configure` and select "Remove Extension".
-### `examples/frontend_tools.py`
+## Extension Types in Detail
-The `submit_tool_result` function in [`examples/frontend_tools.py`](https://github.com/block/goose/blob/HEAD/examples/frontend_tools.py) handles a key part of this chapter's functionality:
+Goose supports four distinct extension configuration types:
-```py
+| Type | When to Use | Example |
+|:-----|:------------|:--------|
+| `Builtin` | Bundled extensions shipped with Goose | `--with-builtin developer` |
+| `Stdio` | Any MCP server communicating over stdin/stdout | `npx @modelcontextprotocol/server-filesystem` |
+| `StreamableHttp` | Remote MCP server over HTTP streaming | A deployed cloud MCP endpoint |
+| `Platform` | OS-native system extensions | Built into the desktop app |
+The `Stdio` type covers the vast majority of community MCP servers. You provide the command and arguments; Goose spawns the process and communicates over the MCP protocol.
-def submit_tool_result(tool_id: str, result: List[Dict[str, Any]]) -> None:
- """Submit the tool execution result back to Goose.
+## Enabling Extensions at Runtime (CLI)
- The result should be a list of Content variants (Text, Image, or Resource).
- Each Content variant has a type tag and appropriate fields.
- """
- payload = {
- "id": tool_id,
- "result": {
- "Ok": result # Result enum variant with single key for success case
- },
- }
-
- with httpx.Client(timeout=2.0) as client:
- response = client.post(
- f"{GOOSE_URL}/tool_result",
- json=payload,
- headers={"X-Secret-Key": SECRET_KEY},
- )
- response.raise_for_status()
+Extensions can be injected per-invocation without modifying config:
+```bash
+# Add the developer built-in for this session only
+goose session --with-builtin developer
-async def chat_loop() -> None:
- """Main chat loop that handles the conversation with Goose."""
- session_id = "test-session"
+# Add a custom stdio MCP server for this run only
+goose run --text "Analyze dependencies" \
+ --with-extension "npx -y @modelcontextprotocol/server-filesystem /home/user/project"
- # Use a client with a longer timeout for streaming
- async with httpx.AsyncClient(timeout=60.0) as client:
- # Get user input
- user_message = input("\nYou: ")
+# Load a remote streamable HTTP extension
+goose session --with-streamable-http-extension "https://my-mcp-server.example.com"
```
-This function is important because it defines how Goose Tutorial: Extensible Open-Source AI Agent for Real Engineering Work implements the patterns covered in this chapter.
+Extensions added via flags are not persisted to config. This makes them suitable for CI pipelines where you want a clean, reproducible extension surface.
-### `examples/frontend_tools.py`
+## The Memory Extension in Depth
-The `chat_loop` function in [`examples/frontend_tools.py`](https://github.com/block/goose/blob/HEAD/examples/frontend_tools.py) handles a key part of this chapter's functionality:
+The built-in `Memory` extension (in `crates/goose-mcp/src/memory/`) provides persistent tool-backed memory across sessions:
-```py
+- **`remember_memory`** — stores a key-value pair in a category, optionally tagged
+- **`retrieve_memories`** — fetches all memories in a category (use `"*"` for all)
+- **`remove_memory_category`** — bulk-deletes a category
+- **`remove_specific_memory`** — removes a single entry by content match
+Global memories persist in `~/.config/goose/memory/` and survive across projects. Local memories live in `.goose/memory/` within the project directory. This dual-scope model is useful for storing both personal preferences (global) and project-specific conventions (local).
-async def chat_loop() -> None:
- """Main chat loop that handles the conversation with Goose."""
- session_id = "test-session"
-
- # Use a client with a longer timeout for streaming
- async with httpx.AsyncClient(timeout=60.0) as client:
- # Get user input
- user_message = input("\nYou: ")
- if user_message.lower() in ["exit", "quit"]:
- return
+## Extension Safety Checklist
- # Create the message object
- message = {
- "role": "user",
- "created": int(datetime.now().timestamp()),
- "content": [{"type": "text", "text": user_message}],
- }
+1. review extension command/source before adding
+2. set reasonable timeout values (default: 30s)
+3. apply `SmartApprove` or `Approve` mode when using new extensions
+4. test in a sandbox repository first
+5. add extension commands to your team's allowlist policy before broad rollout
- # Send to /reply endpoint
- payload = {
- "messages": [message],
- "session_id": session_id,
- "session_working_dir": os.getcwd(),
- }
+## Source References
- # Process the stream of responses
- async with client.stream(
- "POST",
- f"{GOOSE_URL}/reply", # lock
- json=payload,
-```
+- [Using Extensions](https://block.github.io/goose/docs/getting-started/using-extensions)
+- [Model Context Protocol](https://modelcontextprotocol.io/)
+- [MCP Server Directory](https://www.pulsemcp.com/servers)
-This function is important because it defines how Goose Tutorial: Extensible Open-Source AI Agent for Real Engineering Work implements the patterns covered in this chapter.
+## Summary
-### `examples/frontend_tools.py`
+You now know how to evolve Goose capabilities with built-in and external MCP integrations.
-The `main` function in [`examples/frontend_tools.py`](https://github.com/block/goose/blob/HEAD/examples/frontend_tools.py) handles a key part of this chapter's functionality:
+Next: [Chapter 7: CLI Workflows and Automation](07-cli-workflows-and-automation.md)
-```py
+## How These Components Connect
+```mermaid
+flowchart TD
+ A[Goose agent] --> B{Extension type}
+ B -->|Built-in| C[goose --with-builtin developer]
+ B -->|Custom MCP| D[goose --with-extension cmd]
+ C --> E[Pre-packaged tools: files, shell, browser]
+ D --> F[MCP server subprocess spawned]
+ F --> G[stdio transport]
+ G --> H[Custom tools exposed to agent]
+ E --> I[Agent tool calls]
+ H --> I
+```
-async def main():
- try:
- # Initialize the agent with our tool
- await setup_agent()
+## Source Code Walkthrough
- # Start the chat loop
- await chat_loop()
+### `crates/goose-mcp/src/memory/mod.rs` — built-in Memory extension
- except Exception as e:
- print(f"Error: {e}")
- raise # Re-raise to see full traceback
+The `MemoryServer` struct in [`crates/goose-mcp/src/memory/mod.rs`](https://github.com/block/goose/blob/main/crates/goose-mcp/src/memory/mod.rs) is one of Goose's built-in MCP extensions:
+```rust
+pub struct MemoryServer {
+ tool_router: ToolRouter<Self>,
+ instructions: String,
+ global_memory_dir: PathBuf, // ~/.config/goose/memory/
+}
+```
-if __name__ == "__main__":
- asyncio.run(main())
+The four tool parameter types expose the full memory API to the model:
-```
+- **`RememberMemoryParams`** — category, data string, optional tags, global/local flag
+- **`RetrieveMemoriesParams`** — category (supports `"*"` for all), storage scope
+- **`RemoveMemoryCategoryParams`** — wildcard category deletion
+- **`RemoveSpecificMemoryParams`** — removes individual items by content match
-This function is important because it defines how Goose Tutorial: Extensible Open-Source AI Agent for Real Engineering Work implements the patterns covered in this chapter.
+Context for local vs. global storage is injected via the `extract_working_dir_from_meta()` helper, which reads the `"agent-working-dir"` header from MCP request metadata.
+### `crates/goose-server/src/routes/agent.rs` — extension add/remove API
-## How These Components Connect
+When adding a custom MCP server via the desktop UI, the server calls the `AddExtensionRequest` handler in [`crates/goose-server/src/routes/agent.rs`](https://github.com/block/goose/blob/main/crates/goose-server/src/routes/agent.rs). The payload mirrors the four `ExtensionConfig` variants:
-```mermaid
-flowchart TD
- A[execute_enable_extension]
- B[submit_tool_result]
- C[chat_loop]
- D[main]
- A --> B
- B --> C
- C --> D
+```rust
+// POST /extensions/add — for a stdio MCP server:
+// {
+// "type": "stdio",
+// "name": "my-extension",
+// "cmd": "npx",
+// "args": ["-y", "@modelcontextprotocol/server-memory"],
+// "timeout": 30
+// }
```
+
+The same endpoint handles `Builtin`, `StreamableHttp`, and `Platform` variants by switching on the `type` field.
diff --git a/tutorials/goose-tutorial/07-cli-workflows-and-automation.md b/tutorials/goose-tutorial/07-cli-workflows-and-automation.md
index 0260d33e..e587f9d6 100644
--- a/tutorials/goose-tutorial/07-cli-workflows-and-automation.md
+++ b/tutorials/goose-tutorial/07-cli-workflows-and-automation.md
@@ -20,6 +20,21 @@ This chapter focuses on making Goose reliable inside repeatable terminal workflo
- standardize diagnostics and update flows
- improve reproducibility across developer machines
+## CLI Command Map
+
+```mermaid
+flowchart LR
+ A["goose"] --> B["session\n(interactive)"]
+ A --> C["run\n(headless)"]
+ A --> D["configure\n(setup wizard)"]
+ A --> E["info\n(version + paths)"]
+ A --> F["update\n(stable/canary)"]
+ A --> G["completion\n(shell autocomplete)"]
+ B --> H["-n NAME\n--max-turns N\n--with-builtin EXT"]
+ C --> I["--text TEXT\n--instructions FILE\n--recipe NAME\n--params K=V"]
+ D --> J["provider wizard\nextension management\nmode selection"]
+```
+
## Core Commands to Operationalize
| Command | Purpose |
@@ -30,211 +45,167 @@ This chapter focuses on making Goose reliable inside repeatable terminal workflo
| `goose run` | headless/task automation mode |
| `goose update` | upgrade to stable/canary builds |
| `goose completion zsh` | shell completion for faster operation |
+| `goose session list` | list all sessions with metadata |
+| `goose session export` | export session to JSON/YAML/Markdown |
+| `goose session remove` | delete sessions by name, ID, or regex |
+| `goose session diagnostics` | generate ZIP bundle for troubleshooting |
+
+## CI Integration Example
+
+A minimal CI job using `goose run`:
+
+```yaml
+# .github/workflows/goose-task.yml
+- name: Run Goose task
+ env:
+ ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+ GOOSE_MODE: auto
+ run: |
+ goose run \
+ --instructions .goose/tasks/check-api-breaking-changes.md \
+ --max-turns 30 \
+ --no-profile \
+ --with-builtin developer
+```
-## Automation Pattern
+Key CI practices:
+- always set `--max-turns` to prevent runaway jobs
+- use `--no-profile` for a clean, reproducible extension surface
+- inject credentials from secrets, not environment files
+- check exit code: non-zero means the task failed or hit a limit
-1. pin install/update strategy
-2. verify provider credentials at runtime
-3. run bounded task with max-turn controls
-4. collect logs and outputs for review
-5. fail fast on permission or tool-surface mismatch
+## The `goose run` Command in Detail
-## Troubleshooting Baseline
+`goose run` is the primary surface for headless automation. Unlike `goose session`, it exits automatically when the task completes or the turn limit is reached:
-- run `goose info` during incident triage
-- inspect logs before retry loops
-- ensure command flags use current naming conventions
+```bash
+# Run from an instruction file
+goose run --instructions task.md --max-turns 30
-## Source References
+# Run with inline text and a specific named session for resume
+goose run --text "Generate a changelog from git log since v1.0.0" \
+ --name changelog-task \
+ --max-turns 20
-- [Goose CLI Commands](https://block.github.io/goose/docs/guides/goose-cli-commands)
-- [Updating goose](https://block.github.io/goose/docs/guides/updating-goose)
-- [Diagnostics and Reporting](https://block.github.io/goose/docs/troubleshooting/diagnostics-and-reporting)
+# Run with a recipe and parameter substitution
+goose run --recipe refactor-module \
+ --params MODULE=auth \
+ --params TARGET_VERSION=2.0 \
+ --no-profile \
+ --with-builtin developer
+```
-## Summary
+Exit codes follow Unix conventions: `0` for success, non-zero for failures including turn limit exceeded, permission denied, or provider errors.
-You now have a production-friendly CLI operating model for Goose automation.
+## Recipes for Repeatable Tasks
-Next: [Chapter 8: Production Operations and Security](08-production-operations-and-security.md)
+Goose recipes are YAML files that encode a task template with parameter slots. They let you commit standardized AI tasks to your repository and invoke them consistently:
-## Depth Expansion Playbook
+```yaml
+# .goose/recipes/extract-todos.yaml
+name: extract-todos
+description: Extract all TODO and FIXME comments from source
+parameters:
+ - name: TARGET_DIR
+ description: Directory to scan
+ default: src/
+prompt: |
+ Scan all files in {{TARGET_DIR}} for TODO and FIXME comments.
+ Produce a Markdown table with: file path, line number, comment text.
+ Sort by file path.
+```
-## Source Code Walkthrough
+Run it with:
-### `examples/frontend_tools.py`
-
-The `variant` interface in [`examples/frontend_tools.py`](https://github.com/block/goose/blob/HEAD/examples/frontend_tools.py) handles a key part of this chapter's functionality:
-
-```py
- result /= n
-
- # Return properly structured Content::Text variant
- return [
- {
- "type": "text",
- "text": str(result),
- "annotations": None, # Required field in Rust struct
- }
- ]
- except Exception as e:
- return [
- {
- "type": "text",
- "text": f"Error: {str(e)}",
- "annotations": None, # Required field in Rust struct
- }
- ]
-
-def get_tools() -> Dict[str, Any]:
- with httpx.Client() as client:
- response = client.get(
- f"{GOOSE_URL}/agent/tools",
- headers={"X-Secret-Key": SECRET_KEY},
- )
- response.raise_for_status()
- return response.json()
-
-
-def execute_enable_extension(args: Dict[str, Any]) -> List[Dict[str, Any]]:
- """
- Execute the enable_extension tool.
+```bash
+goose run --recipe .goose/recipes/extract-todos.yaml --params TARGET_DIR=lib/
```
-This interface is important because it defines how Goose Tutorial: Extensible Open-Source AI Agent for Real Engineering Work implements the patterns covered in this chapter.
-
-### `scripts/provider-error-proxy/proxy.py`
-
-The `ErrorMode` class in [`scripts/provider-error-proxy/proxy.py`](https://github.com/block/goose/blob/HEAD/scripts/provider-error-proxy/proxy.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-class ErrorMode(Enum):
- """Error injection modes."""
- NO_ERROR = 1
- CONTEXT_LENGTH = 2
- RATE_LIMIT = 3
- SERVER_ERROR = 4
-
-
-# Error responses for each provider and error type
-ERROR_CONFIGS = {
- 'openai': {
- ErrorMode.CONTEXT_LENGTH: {
- 'status': 400,
- 'body': {
- 'error': {
- 'message': "This model's maximum context length is 128000 tokens. However, your messages resulted in 150000 tokens. Please reduce the length of the messages.",
- 'type': 'invalid_request_error',
- 'code': 'context_length_exceeded'
- }
- }
- },
- ErrorMode.RATE_LIMIT: {
- 'status': 429,
- 'body': {
- 'error': {
- 'message': 'Rate limit exceeded. Please try again later.',
- 'type': 'rate_limit_error',
- 'code': 'rate_limit_exceeded'
- }
- }
-```
+## Shell Completion Setup
+
+Install shell completion once to enable tab-completion for all Goose commands and flags:
+
+```bash
+# zsh
+goose completion zsh >> ~/.zshrc && source ~/.zshrc
-This class is important because it defines how Goose Tutorial: Extensible Open-Source AI Agent for Real Engineering Work implements the patterns covered in this chapter.
-
-### `scripts/provider-error-proxy/proxy.py`
-
-The `ErrorProxy` class in [`scripts/provider-error-proxy/proxy.py`](https://github.com/block/goose/blob/HEAD/scripts/provider-error-proxy/proxy.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-class ErrorProxy:
- """HTTP proxy that can inject errors into provider responses."""
-
- def __init__(self):
- """Initialize the error proxy."""
- self.error_mode = ErrorMode.NO_ERROR
- self.error_count = 0 # Remaining errors to inject (0 = unlimited/percentage mode)
- self.error_percentage = 0.0 # Percentage of requests to error (0.0 = count mode)
- self.request_count = 0
- self.session: Optional[ClientSession] = None
- self.lock = threading.Lock()
-
- def set_error_mode(self, mode: ErrorMode, count: int = 1, percentage: float = 0.0):
- """
- Set the error injection mode.
-
- Args:
- mode: The error mode to use
- count: Number of errors to inject (default 1, 0 for unlimited)
- percentage: Percentage of requests to error (0.0-1.0, 0.0 for count mode)
- """
- with self.lock:
- self.error_mode = mode
- self.error_count = count
- self.error_percentage = percentage
-
- def should_inject_error(self) -> bool:
- """
- Determine if we should inject an error for this request.
-
+# bash
+goose completion bash >> ~/.bashrc && source ~/.bashrc
```
-This class is important because it defines how Goose Tutorial: Extensible Open-Source AI Agent for Real Engineering Work implements the patterns covered in this chapter.
+## Automation Pattern
-### `scripts/provider-error-proxy/proxy.py`
+1. pin install/update strategy (`goose update --channel stable`)
+2. verify provider credentials at runtime (`goose info`)
+3. run bounded task with max-turn controls (`--max-turns 30`)
+4. collect logs and outputs for review (session files in `~/.config/goose/sessions/`)
+5. fail fast on permission or tool-surface mismatch (non-zero exit code triggers CI failure)
-The `parse_command` function in [`scripts/provider-error-proxy/proxy.py`](https://github.com/block/goose/blob/HEAD/scripts/provider-error-proxy/proxy.py) handles a key part of this chapter's functionality:
+## Troubleshooting Baseline
-```py
+- run `goose info` during incident triage to confirm version and config path
+- inspect session logs at `~/.config/goose/sessions/` before retry loops
+- run `goose session diagnostics` to generate a ZIP bundle for deeper investigation
+- ensure command flags use current naming conventions (`goose --help` shows current surface)
+## Source References
-def parse_command(command: str) -> tuple[Optional[ErrorMode], int, float, Optional[str]]:
- """
- Parse a command string and return the error mode, count, and percentage.
+- [Goose CLI Commands](https://block.github.io/goose/docs/guides/goose-cli-commands)
+- [Updating goose](https://block.github.io/goose/docs/guides/updating-goose)
+- [Diagnostics and Reporting](https://block.github.io/goose/docs/troubleshooting/diagnostics-and-reporting)
- Args:
- command: Command string (e.g., "c", "c 3", "r 30%", "u *")
+## Summary
- Returns:
- Tuple of (mode, count, percentage, error_message)
- If error_message is not None, parsing failed
- """
- # Parse command - remove all whitespace and parse
- command_no_space = command.strip().replace(" ", "")
- if not command_no_space:
- return (None, 0, 0.0, "Empty command")
+You now have a production-friendly CLI operating model for Goose automation.
- # Get the first character (error type letter)
- error_letter = command_no_space[0].lower()
+Next: [Chapter 8: Production Operations and Security](08-production-operations-and-security.md)
- # Map letter to ErrorMode
- mode_map = {
- 'n': ErrorMode.NO_ERROR,
- 'c': ErrorMode.CONTEXT_LENGTH,
- 'r': ErrorMode.RATE_LIMIT,
- 'u': ErrorMode.SERVER_ERROR
- }
+## How These Components Connect
- if error_letter not in mode_map:
- return (None, 0, 0.0, f"Invalid command: '{error_letter}'. Use n, c, r, or u")
+```mermaid
+flowchart TD
+ A[goose run] --> B{Input source}
+ B -->|--text| C[Inline prompt]
+ B -->|--instructions file| D[Instruction file]
+ B -->|--recipe| E[Structured recipe YAML]
+ C --> F[Agent executes task]
+ D --> F
+ E --> F
+ F --> G[Output to stdout / files]
+ G --> H[CI pipeline / automation script]
+```
+## Source Code Walkthrough
+
+### `crates/goose-cli/src/cli.rs` — `goose run` and headless flags
+
+The `goose run` subcommand is the primary surface for automation. Its key flags come from `InputOptions` and `SessionOptions` defined in [`crates/goose-cli/src/cli.rs`](https://github.com/block/goose/blob/main/crates/goose-cli/src/cli.rs):
+
+```rust
+// InputOptions (for goose run)
+--instructions (-i) // path to an instruction file, or "-" for stdin
+--text (-t) // inline task text passed directly
+--recipe // named recipe or .yaml recipe file path
+--params KEY=VALUE // dynamic key-value substitutions into recipes (repeatable)
+
+// SessionOptions
+--max-turns N // hard ceiling on agent iterations (default: 1000)
+--no-profile // skip loading default extensions from profile
+--with-extension CMD // inject a stdio extension for this run only
```
-This function is important because it defines how Goose Tutorial: Extensible Open-Source AI Agent for Real Engineering Work implements the patterns covered in this chapter.
+Exit codes follow Unix conventions. In CI, check `$?` after `goose run` to detect failures including turn limit exceeded, provider errors, or permission denials.
+### `crates/goose-cli/src/commands/session.rs` — diagnostics for automation triage
-## How These Components Connect
+[`crates/goose-cli/src/commands/session.rs`](https://github.com/block/goose/blob/main/crates/goose-cli/src/commands/session.rs) exposes `handle_diagnostics()`, which generates a ZIP bundle containing session metadata, logs, and conversation history for failure triage:
-```mermaid
-flowchart TD
- A[variant]
- B[ErrorMode]
- C[ErrorProxy]
- D[parse_command]
- A --> B
- B --> C
- C --> D
+```bash
+# After a failed goose run, capture diagnostics
+goose session diagnostics --output /tmp/goose-diag-$(date +%s).zip
+
+# List recent sessions in JSON for scripted triage
+goose session list --format json | jq '.[] | select(.status == "error")'
```
+
+The `handle_session_list()` function explicitly supports `--format json` for machine consumption.
diff --git a/tutorials/goose-tutorial/08-production-operations-and-security.md b/tutorials/goose-tutorial/08-production-operations-and-security.md
index 71c978d7..78898046 100644
--- a/tutorials/goose-tutorial/08-production-operations-and-security.md
+++ b/tutorials/goose-tutorial/08-production-operations-and-security.md
@@ -20,6 +20,24 @@ This chapter turns Goose from a useful local assistant into a controlled team pl
- build incident response paths around logs and diagnostics
- establish upgrade and governance cadences
+## Production Deployment Architecture
+
+```mermaid
+flowchart TD
+ A["Developer machine"] --> B["goose (CLI or Desktop)"]
+ B --> C["~/.config/goose/config.yaml\n(provider, model, mode)"]
+ B --> D["GOOSE_ALLOWLIST\n(extension policy)"]
+ B --> E[".gooseignore\n(per-repo exclusions)"]
+ C --> F["Approved provider + model"]
+ D --> G["Allowlisted MCP commands only"]
+ E --> H["Excluded paths never in context"]
+ F --> I["Governed agent execution"]
+ G --> I
+ H --> I
+ I --> J["Session logs\n(~/.config/goose/sessions/)"]
+ J --> K["Periodic audit + incident response"]
+```
+
## Production Guardrails
| Domain | Recommended Baseline |
@@ -32,209 +50,155 @@ This chapter turns Goose from a useful local assistant into a controlled team pl
## Secure Adoption Flow
-1. define approved provider/model matrix
-2. define approved extension/tool matrix
-3. publish `.gooseignore` and session conventions
-4. run pilot with monitored repositories
-5. review incidents and tighten defaults
+1. define approved provider/model matrix (document in team wiki)
+2. define approved extension/tool matrix (encode in `GOOSE_ALLOWLIST` policy)
+3. publish `.gooseignore` template in your repo scaffold
+4. standardize `GooseMode` per environment class in team onboarding docs
+5. run pilot with monitored repositories (export sessions for review)
+6. review incidents and tighten defaults
+7. schedule quarterly policy reviews as model capabilities evolve
-## Governance Cadence
+## Responsible AI Coding (HOWTOAI.md)
-- weekly: check release notes and open security issues
-- monthly: audit permission and extension policies
-- quarterly: review provider costs, model quality, and policy drift
+Block's `HOWTOAI.md` at the repo root documents their own principles for responsible AI-assisted development with Goose:
-## Source References
+- human remains responsible for all code that ships
+- review AI-generated changes as carefully as you would any PR
+- do not use Goose to generate content that bypasses your normal review process
+- be explicit about AI assistance in commit messages and PR descriptions when it materially shaped the implementation
-- [Staying Safe with goose](https://block.github.io/goose/docs/guides/security/)
-- [goose Extension Allowlist](https://block.github.io/goose/docs/guides/allowlist)
-- [goose Governance](https://github.com/block/goose/blob/main/GOVERNANCE.md)
-- [Responsible AI-Assisted Coding Guide](https://github.com/block/goose/blob/main/HOWTOAI.md)
+These are not Goose-enforced constraints — they are team norms. The governance system (allowlists, permission modes, `.gooseignore`) enforces technical boundaries; responsible use requires complementary social and process norms.
-## Summary
+## The Allowlist System
-You now have a complete framework for running Goose with strong safety, consistency, and operational reliability.
+`GOOSE_ALLOWLIST` points to a URL or file path containing a YAML policy that restricts which extensions and providers Goose can use. This is the primary control for managed deployments where developers should not be able to add arbitrary MCP servers:
-Continue by comparing workflows in the [Crush Tutorial](../crush-tutorial/).
+```yaml
+# allowlist.yaml example
+extensions:
+ allowed_commands:
+ - "npx -y @modelcontextprotocol/server-filesystem"
+ - "npx -y @modelcontextprotocol/server-github"
+providers:
+ allowed:
+ - anthropic
+ - openai
+```
-## Depth Expansion Playbook
+Set `GOOSE_ALLOWLIST=https://internal.example.com/goose-policy.yaml` in your organization's shell profile to enforce this policy on every developer machine.
-## Source Code Walkthrough
+## Incident Response Paths
-### `scripts/provider-error-proxy/proxy.py`
-
-The `print_status` function in [`scripts/provider-error-proxy/proxy.py`](https://github.com/block/goose/blob/HEAD/scripts/provider-error-proxy/proxy.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def print_status(proxy: ErrorProxy):
- """Print the current proxy status."""
- mode, count, percentage = proxy.get_error_config()
- mode_names = {
- ErrorMode.NO_ERROR: "✅ No error (pass through)",
- ErrorMode.CONTEXT_LENGTH: "📏 Context length exceeded",
- ErrorMode.RATE_LIMIT: "⏱️ Rate limit exceeded",
- ErrorMode.SERVER_ERROR: "💥 Server error (500)"
- }
-
- print("\n" + "=" * 60)
- mode_str = mode_names.get(mode, 'Unknown')
- if mode != ErrorMode.NO_ERROR:
- if percentage > 0.0:
- mode_str += f" ({percentage*100:.0f}% of requests)"
- elif count > 0:
- mode_str += f" ({count} remaining)"
- print(f"Current mode: {mode_str}")
- print(f"Requests handled: {proxy.request_count}")
- print("=" * 60)
- print("\nCommands:")
- print(" n - No error (pass through) - permanent")
- print(" c - Context length exceeded (1 time)")
- print(" c 4 - Context length exceeded (4 times)")
- print(" c 0.3 - Context length exceeded (30% of requests)")
- print(" c 30% - Context length exceeded (30% of requests)")
- print(" c * - Context length exceeded (100% of requests)")
- print(" r - Rate limit error (1 time)")
- print(" u - Unknown server error (1 time)")
- print(" q - Quit")
-```
+When a Goose session causes an unexpected outcome:
-This function is important because it defines how Goose Tutorial: Extensible Open-Source AI Agent for Real Engineering Work implements the patterns covered in this chapter.
+1. **Capture diagnostics** — `goose session diagnostics` generates a ZIP with full conversation and tool call logs
+2. **Review the session file** — sessions are plain files in `~/.config/goose/sessions/`; export to Markdown for readable review
+3. **Identify the turn** — tool call logs show which model decision triggered the problem
+4. **Tighten the policy** — add the problematic pattern to `.gooseignore` or lower the permission mode for that repository
-### `scripts/provider-error-proxy/proxy.py`
+## Security Threat Surface
-The `stdin_reader` function in [`scripts/provider-error-proxy/proxy.py`](https://github.com/block/goose/blob/HEAD/scripts/provider-error-proxy/proxy.py) handles a key part of this chapter's functionality:
+The `SECURITY.md` at the repository root documents the known threat surface:
-```py
+| Threat | Mitigation |
+|:-------|:-----------|
+| Prompt injection via document content | Use `Approve` mode when reading external/untrusted files |
+| Tool permission bypass via malformed MCP responses | Allowlist trusted MCP commands only |
+| Credential leakage through session export | Restrict export to non-secret working directories; add `.env` to `.gooseignore` |
+| Runaway automation | Set `--max-turns` limits on all CI invocations |
+| Supply chain risk in MCP extensions | Pin extension command versions; review source before adding |
+## Upgrade Strategy
-def stdin_reader(proxy: ErrorProxy, loop):
- """Read commands from stdin in a separate thread."""
- print_status(proxy)
+```bash
+# Upgrade to latest stable
+goose update --channel stable
- while True:
- try:
- command = input("Enter command: ").strip()
+# Upgrade to canary (for early access)
+goose update --channel canary
- if command.lower() == 'q':
- print("\n🛑 Shutting down proxy...")
- # Schedule the shutdown in the event loop
- asyncio.run_coroutine_threadsafe(shutdown_server(loop), loop)
- break
+# Check current version
+goose info
+```
- # Parse the command using the shared parser
- mode, count, percentage, error_msg = parse_command(command)
+Canary builds are useful for evaluating new features before broad team rollout. The recommended pattern: one or two developers run canary in personal projects; stable is enforced in shared and production repositories via a pinned install in your team's onboarding script.
- if error_msg:
- print(f"❌ {error_msg}")
- continue
+## Team Onboarding Checklist
- # Set the error mode
- proxy.set_error_mode(mode, count, percentage)
- print_status(proxy)
+When rolling Goose out to a new team:
- except EOFError:
- # Handle Ctrl+D
- print("\n🛑 Shutting down proxy...")
- asyncio.run_coroutine_threadsafe(shutdown_server(loop), loop)
- break
-```
+- [ ] publish approved provider matrix to team wiki
+- [ ] commit a shared `.gooseignore` to all active repositories
+- [ ] set `GOOSE_ALLOWLIST` in the team shell profile
+- [ ] document the default `GooseMode` for each environment class
+- [ ] run a pilot session on a non-critical repository with logging enabled
+- [ ] review the session export and confirm no credential paths appear in context
+- [ ] define escalation path if a Goose session causes an unexpected side effect
-This function is important because it defines how Goose Tutorial: Extensible Open-Source AI Agent for Real Engineering Work implements the patterns covered in this chapter.
+## Cost Monitoring
-### `scripts/provider-error-proxy/proxy.py`
+Session logs include token usage per turn. For cost attribution:
-The `shutdown_server` function in [`scripts/provider-error-proxy/proxy.py`](https://github.com/block/goose/blob/HEAD/scripts/provider-error-proxy/proxy.py) handles a key part of this chapter's functionality:
+```bash
+# Extract token counts from all sessions
+find ~/.config/goose/sessions/ -name "*.json" | \
+ xargs jq -r '.metadata.token_usage | "\(.input_tokens) in \(.output_tokens) out"'
+```
-```py
- print("\n🛑 Shutting down proxy...")
- # Schedule the shutdown in the event loop
- asyncio.run_coroutine_threadsafe(shutdown_server(loop), loop)
- break
+For team-scale monitoring, export session JSON from each developer's machine into a shared data store and aggregate by provider + model + date. This gives you the data to make informed decisions about which model to use for which task class.
- # Parse the command using the shared parser
- mode, count, percentage, error_msg = parse_command(command)
+## Governance Cadence
- if error_msg:
- print(f"❌ {error_msg}")
- continue
+- weekly: check release notes and open security issues at `github.com/block/goose/releases`
+- monthly: audit permission and extension policies against team usage
+- quarterly: review provider costs from session logs, model quality benchmarks, and policy drift
- # Set the error mode
- proxy.set_error_mode(mode, count, percentage)
- print_status(proxy)
+## Source References
- except EOFError:
- # Handle Ctrl+D
- print("\n🛑 Shutting down proxy...")
- asyncio.run_coroutine_threadsafe(shutdown_server(loop), loop)
- break
- except Exception as e:
- logger.error(f"Error reading stdin: {e}")
+- [Staying Safe with goose](https://block.github.io/goose/docs/guides/security/)
+- [goose Extension Allowlist](https://block.github.io/goose/docs/guides/allowlist)
+- [goose Governance](https://github.com/block/goose/blob/main/GOVERNANCE.md)
+- [Responsible AI-Assisted Coding Guide](https://github.com/block/goose/blob/main/HOWTOAI.md)
+## Summary
-async def shutdown_server(loop):
- """Shutdown the server gracefully."""
- # Stop the event loop
- loop.stop()
+You now have a complete framework for running Goose with strong safety, consistency, and operational reliability.
+Continue by comparing workflows in the [Crush Tutorial](../crush-tutorial/).
-async def create_app(proxy: ErrorProxy) -> web.Application:
+## How These Components Connect
+
+```mermaid
+flowchart TD
+ A[Production Goose deployment] --> B[Policy configuration]
+ B --> C[Restrict tool permissions]
+ C --> D{Environment}
+ D -->|Dev| E[approve mode - user confirms each tool]
+ D -->|CI/automated| F[Selected tools auto-approved]
+ D -->|Untrusted content| G[deny-all or container mode]
+ F --> H[Audit log of tool calls]
+ G --> H
+ H --> I[Security review cadence]
```
-This function is important because it defines how Goose Tutorial: Extensible Open-Source AI Agent for Real Engineering Work implements the patterns covered in this chapter.
-
-### `scripts/provider-error-proxy/proxy.py`
-
-The `create_app` function in [`scripts/provider-error-proxy/proxy.py`](https://github.com/block/goose/blob/HEAD/scripts/provider-error-proxy/proxy.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-async def create_app(proxy: ErrorProxy) -> web.Application:
- """
- Create the aiohttp application.
-
- Args:
- proxy: The ErrorProxy instance
-
- Returns:
- Configured aiohttp application
- """
- app = web.Application()
-
- # Setup and teardown
- async def on_startup(app):
- await proxy.start_session()
- logger.info("🚀 Proxy session started")
-
- async def on_cleanup(app):
- await proxy.close_session()
- logger.info("🛑 Proxy session closed")
-
- app.on_startup.append(on_startup)
- app.on_cleanup.append(on_cleanup)
-
- # Route all requests through the proxy
- app.router.add_route('*', '/{path:.*}', proxy.handle_request)
-
- return app
+## Source Code Walkthrough
+
+### `crates/goose-acp/src/tools.rs` — ACP tool metadata and trust marking
+[`crates/goose-acp/src/tools.rs`](https://github.com/block/goose/blob/main/crates/goose-acp/src/tools.rs) defines the `AcpAwareToolMeta` trait used to mark tool results as ACP-compliant:
+```rust
+// Marks a CallToolResult as ACP-aware via metadata key "_goose/acp-aware"
+pub trait AcpAwareToolMeta {
+ fn with_acp_aware_meta(self) -> Self;
+ fn is_acp_aware(&self) -> bool;
+}
```
-This function is important because it defines how Goose Tutorial: Extensible Open-Source AI Agent for Real Engineering Work implements the patterns covered in this chapter.
+The metadata key `"_goose/acp-aware"` is injected at tool call result time. In production contexts, this allows the ACP server layer to distinguish between tool results that went through Goose's permission and validation pipeline versus those that bypassed it — a meaningful audit signal.
+### `crates/goose-server/src/auth.rs` — server authentication
-## How These Components Connect
+[`crates/goose-server/src/auth.rs`](https://github.com/block/goose/blob/main/crates/goose-server/src/auth.rs) implements the `X-Secret-Key` bearer token that protects every `/agent/*` and `/extensions/*` route. In team deployments, the secret key should be rotated via environment variable rather than hardcoded, and the TLS configuration in `crates/goose-server/src/tls.rs` should be enabled when the server is exposed beyond localhost.
-```mermaid
-flowchart TD
- A[print_status]
- B[stdin_reader]
- C[shutdown_server]
- D[create_app]
- A --> B
- B --> C
- C --> D
-```
+The `GOVERNANCE.md` and `HOWTOAI.md` documents at the repo root provide Block's own framework for responsible AI-assisted development — useful references when building internal governance policies for your organization's Goose usage.
diff --git a/tutorials/gpt-oss-tutorial/01-getting-started.md b/tutorials/gpt-oss-tutorial/01-getting-started.md
index 4205d060..d7f0b96e 100644
--- a/tutorials/gpt-oss-tutorial/01-getting-started.md
+++ b/tutorials/gpt-oss-tutorial/01-getting-started.md
@@ -484,26 +484,35 @@ Under the hood, `Chapter 1: Getting Started -- Understanding the Open-Source GPT
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
-## Source Walkthrough
-
-Use the following upstream sources to verify implementation details while reading this chapter:
-
-- [nanoGPT](https://github.com/karpathy/nanoGPT)
- Why it matters: authoritative reference on `nanoGPT` (github.com).
-- [minGPT](https://github.com/karpathy/minGPT)
- Why it matters: authoritative reference on `minGPT` (github.com).
-- [GPT-NeoX](https://github.com/EleutherAI/gpt-neox)
- Why it matters: authoritative reference on `GPT-NeoX` (github.com).
-- [GPT-Neo](https://github.com/EleutherAI/gpt-neo)
- Why it matters: authoritative reference on `GPT-Neo` (github.com).
-- [GPT-J](https://github.com/kingoflolz/mesh-transformer-jax)
- Why it matters: authoritative reference on `GPT-J` (github.com).
-- [Chapter 1: Getting Started](01-getting-started.md)
- Why it matters: authoritative reference on `Chapter 1: Getting Started` (01-getting-started.md).
-
-Suggested trace strategy:
-- search upstream code for `config` and `self` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+## Source Code Walkthrough
+
+### `model.py` (nanoGPT)
+
+The `GPTConfig` dataclass in [`model.py`](https://github.com/karpathy/nanoGPT/blob/master/model.py) defines the complete configuration surface for a GPT model — block size, vocab size, layer count, heads, and embedding dimensions:
+
+```python
+"""
+Full definition of a GPT Language Model, all of it in this single file.
+"""
+
+import math
+import inspect
+from dataclasses import dataclass
+
+import torch
+import torch.nn as nn
+from torch.nn import functional as F
+
+class LayerNorm(nn.Module):
+ """ LayerNorm but with an optional bias. PyTorch doesn't support simply bias=False """
+
+ def __init__(self, ndim, bias):
+ super().__init__()
+ self.weight = nn.Parameter(torch.ones(ndim))
+ self.bias = nn.Parameter(torch.zeros(ndim)) if bias else None
+```
+
+nanoGPT's entire model definition fits in a single 300-line file — making it the best starting point for understanding how GPT-2 class architectures work. The `LayerNorm` wrapper adds optional bias support that PyTorch's built-in `F.layer_norm` lacks.
## Chapter Connections
diff --git a/tutorials/gpt-oss-tutorial/02-transformer-architecture.md b/tutorials/gpt-oss-tutorial/02-transformer-architecture.md
index 0eda64db..e7fd0bdc 100644
--- a/tutorials/gpt-oss-tutorial/02-transformer-architecture.md
+++ b/tutorials/gpt-oss-tutorial/02-transformer-architecture.md
@@ -584,22 +584,31 @@ Under the hood, `Chapter 2: Transformer Architecture -- Self-Attention, Multi-He
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
-## Source Walkthrough
-
-Use the following upstream sources to verify implementation details while reading this chapter:
-
-- [nanoGPT](https://github.com/karpathy/nanoGPT)
- Why it matters: authoritative reference on `nanoGPT` (github.com).
-- [minGPT](https://github.com/karpathy/minGPT)
- Why it matters: authoritative reference on `minGPT` (github.com).
-- [GPT-NeoX](https://github.com/EleutherAI/gpt-neox)
- Why it matters: authoritative reference on `GPT-NeoX` (github.com).
-- [GPT-Neo](https://github.com/EleutherAI/gpt-neo)
- Why it matters: authoritative reference on `GPT-Neo` (github.com).
-- [GPT-J](https://github.com/kingoflolz/mesh-transformer-jax)
- Why it matters: authoritative reference on `GPT-J` (github.com).
-- [Chapter 1: Getting Started](01-getting-started.md)
- Why it matters: authoritative reference on `Chapter 1: Getting Started` (01-getting-started.md).
+## Source Code Walkthrough
+
+### `model.py` (nanoGPT)
+
+The `CausalSelfAttention` class in [`model.py`](https://github.com/karpathy/nanoGPT/blob/master/model.py) implements the core transformer self-attention with Flash Attention support:
+
+```python
+class CausalSelfAttention(nn.Module):
+
+ def __init__(self, config):
+ super().__init__()
+ assert config.n_embd % config.n_head == 0
+ # key, query, value projections for all heads, but in a batch
+ self.c_attn = nn.Linear(config.n_embd, 3 * config.n_embd, bias=config.bias)
+ # output projection
+ self.c_proj = nn.Linear(config.n_embd, config.n_embd, bias=config.bias)
+ # flash attention support check
+ self.flash = hasattr(torch.nn.functional, 'scaled_dot_product_attention')
+ if not self.flash:
+ print("WARNING: using slow attention. Flash Attention requires PyTorch >= 2.0")
+ self.register_buffer("bias", torch.tril(torch.ones(config.block_size, config.block_size))
+ .view(1, 1, config.block_size, config.block_size))
+```
+
+The fused QKV projection (`3 * n_embd`) and Flash Attention fallback show production-grade attention implementation. The causal mask is registered as a buffer to avoid reallocation on each forward pass.
Suggested trace strategy:
- search upstream code for `self` and `config` to map concrete implementation paths
diff --git a/tutorials/gpt-oss-tutorial/03-tokenization-embeddings.md b/tutorials/gpt-oss-tutorial/03-tokenization-embeddings.md
index cb239041..85825ff3 100644
--- a/tutorials/gpt-oss-tutorial/03-tokenization-embeddings.md
+++ b/tutorials/gpt-oss-tutorial/03-tokenization-embeddings.md
@@ -582,22 +582,27 @@ Under the hood, `Chapter 3: Tokenization & Embeddings -- BPE, Vocabulary Constru
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
-## Source Walkthrough
-
-Use the following upstream sources to verify implementation details while reading this chapter:
-
-- [nanoGPT](https://github.com/karpathy/nanoGPT)
- Why it matters: authoritative reference on `nanoGPT` (github.com).
-- [minGPT](https://github.com/karpathy/minGPT)
- Why it matters: authoritative reference on `minGPT` (github.com).
-- [GPT-NeoX](https://github.com/EleutherAI/gpt-neox)
- Why it matters: authoritative reference on `GPT-NeoX` (github.com).
-- [GPT-Neo](https://github.com/EleutherAI/gpt-neo)
- Why it matters: authoritative reference on `GPT-Neo` (github.com).
-- [GPT-J](https://github.com/kingoflolz/mesh-transformer-jax)
- Why it matters: authoritative reference on `GPT-J` (github.com).
-- [Chapter 1: Getting Started](01-getting-started.md)
- Why it matters: authoritative reference on `Chapter 1: Getting Started` (01-getting-started.md).
+## Source Code Walkthrough
+
+### `model.py` (nanoGPT)
+
+The token and positional embedding tables in [`model.py`](https://github.com/karpathy/nanoGPT/blob/master/model.py) are initialized as `nn.Embedding` layers inside the `GPT` class:
+
+```python
+# The transformer
+self.transformer = nn.ModuleDict(dict(
+ wte = nn.Embedding(config.vocab_size, config.n_embd),
+ wpe = nn.Embedding(config.block_size, config.n_embd),
+ drop = nn.Dropout(config.dropout),
+ h = nn.ModuleList([Block(config) for _ in range(config.n_layer)]),
+ ln_f = LayerNorm(config.n_embd, bias=config.bias),
+))
+self.lm_head = nn.Linear(config.n_embd, config.vocab_size, bias=False)
+# weight tying
+self.transformer.wte.weight = self.lm_head.weight
+```
+
+`wte` is the token embedding matrix, `wpe` is the learned positional embedding. Weight tying between `wte` and `lm_head` reduces parameter count by ~30M for GPT-2 124M and is a standard modern LLM practice.
Suggested trace strategy:
- search upstream code for `tokens` and `text` to map concrete implementation paths
diff --git a/tutorials/gpt-oss-tutorial/04-training-pipeline.md b/tutorials/gpt-oss-tutorial/04-training-pipeline.md
index 51921fe7..f721082d 100644
--- a/tutorials/gpt-oss-tutorial/04-training-pipeline.md
+++ b/tutorials/gpt-oss-tutorial/04-training-pipeline.md
@@ -635,22 +635,35 @@ Under the hood, `Chapter 4: Training Pipeline -- Data Loading, Loss Computation,
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
-## Source Walkthrough
-
-Use the following upstream sources to verify implementation details while reading this chapter:
-
-- [nanoGPT](https://github.com/karpathy/nanoGPT)
- Why it matters: authoritative reference on `nanoGPT` (github.com).
-- [minGPT](https://github.com/karpathy/minGPT)
- Why it matters: authoritative reference on `minGPT` (github.com).
-- [GPT-NeoX](https://github.com/EleutherAI/gpt-neox)
- Why it matters: authoritative reference on `GPT-NeoX` (github.com).
-- [GPT-Neo](https://github.com/EleutherAI/gpt-neo)
- Why it matters: authoritative reference on `GPT-Neo` (github.com).
-- [GPT-J](https://github.com/kingoflolz/mesh-transformer-jax)
- Why it matters: authoritative reference on `GPT-J` (github.com).
-- [Chapter 1: Getting Started](01-getting-started.md)
- Why it matters: authoritative reference on `Chapter 1: Getting Started` (01-getting-started.md).
+## Source Code Walkthrough
+
+### `train.py` (nanoGPT)
+
+The training script in [`train.py`](https://github.com/karpathy/nanoGPT/blob/master/train.py) shows the complete training loop for GPT-2 on a single GPU or multi-GPU DDP setup:
+
+```python
+# default config values designed to train a gpt2 (124M) on OpenWebText
+out_dir = 'out'
+eval_interval = 2000
+log_interval = 1
+eval_iters = 200
+eval_only = False
+always_save_checkpoint = True
+init_from = 'scratch' # 'scratch' or 'resume' or 'gpt2*'
+
+# model
+n_layer = 12
+n_head = 12
+n_embd = 768
+dropout = 0.0 # for pretraining 0 is good, for finetuning try 0.1+
+
+# adamw optimizer
+learning_rate = 6e-4 # max learning rate
+max_iters = 600000
+weight_decay = 1e-1
+```
+
+The script supports both single-GPU and `torchrun`-based DDP training. `gradient_accumulation_steps` simulates large batch sizes without requiring proportionally more GPU memory.
Suggested trace strategy:
- search upstream code for `model` and `config` to map concrete implementation paths
diff --git a/tutorials/gpt-oss-tutorial/05-attention-mechanisms.md b/tutorials/gpt-oss-tutorial/05-attention-mechanisms.md
index 11838d64..1d70137e 100644
--- a/tutorials/gpt-oss-tutorial/05-attention-mechanisms.md
+++ b/tutorials/gpt-oss-tutorial/05-attention-mechanisms.md
@@ -550,22 +550,24 @@ Under the hood, `Chapter 5: Attention Mechanisms -- Causal Masking, KV-Cache, Mu
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
-## Source Walkthrough
-
-Use the following upstream sources to verify implementation details while reading this chapter:
-
-- [nanoGPT](https://github.com/karpathy/nanoGPT)
- Why it matters: authoritative reference on `nanoGPT` (github.com).
-- [minGPT](https://github.com/karpathy/minGPT)
- Why it matters: authoritative reference on `minGPT` (github.com).
-- [GPT-NeoX](https://github.com/EleutherAI/gpt-neox)
- Why it matters: authoritative reference on `GPT-NeoX` (github.com).
-- [GPT-Neo](https://github.com/EleutherAI/gpt-neo)
- Why it matters: authoritative reference on `GPT-Neo` (github.com).
-- [GPT-J](https://github.com/kingoflolz/mesh-transformer-jax)
- Why it matters: authoritative reference on `GPT-J` (github.com).
-- [Chapter 1: Getting Started](01-getting-started.md)
- Why it matters: authoritative reference on `Chapter 1: Getting Started` (01-getting-started.md).
+## Source Code Walkthrough
+
+### `model.py` (nanoGPT)
+
+The `CausalSelfAttention.forward` method in [`model.py`](https://github.com/karpathy/nanoGPT/blob/master/model.py) shows how Q, K, V are computed and how heads are split:
+
+```python
+def forward(self, x):
+ B, T, C = x.size() # batch size, sequence length, embedding dim (n_embd)
+
+ # calculate query, key, values for all heads in batch
+ q, k, v = self.c_attn(x).split(self.n_embd, dim=2)
+ k = k.view(B, T, self.n_head, C // self.n_head).transpose(1, 2) # (B, nh, T, hs)
+ q = q.view(B, T, self.n_head, C // self.n_head).transpose(1, 2) # (B, nh, T, hs)
+ v = v.view(B, T, self.n_head, C // self.n_head).transpose(1, 2) # (B, nh, T, hs)
+```
+
+The single `c_attn` linear layer produces Q, K, V concatenated — then `.split(n_embd, dim=2)` separates them. This fused projection is more efficient than three separate linear layers. Head dimension is `n_embd // n_head`, so increasing heads reduces per-head capacity.
Suggested trace strategy:
- search upstream code for `self` and `config` to map concrete implementation paths
diff --git a/tutorials/gpt-oss-tutorial/06-scaling-distributed-training.md b/tutorials/gpt-oss-tutorial/06-scaling-distributed-training.md
index 7eacfe3c..dec97d89 100644
--- a/tutorials/gpt-oss-tutorial/06-scaling-distributed-training.md
+++ b/tutorials/gpt-oss-tutorial/06-scaling-distributed-training.md
@@ -647,22 +647,27 @@ Under the hood, `Chapter 6: Scaling & Distributed Training -- Model Parallelism,
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
-## Source Walkthrough
-
-Use the following upstream sources to verify implementation details while reading this chapter:
-
-- [nanoGPT](https://github.com/karpathy/nanoGPT)
- Why it matters: authoritative reference on `nanoGPT` (github.com).
-- [minGPT](https://github.com/karpathy/minGPT)
- Why it matters: authoritative reference on `minGPT` (github.com).
-- [GPT-NeoX](https://github.com/EleutherAI/gpt-neox)
- Why it matters: authoritative reference on `GPT-NeoX` (github.com).
-- [GPT-Neo](https://github.com/EleutherAI/gpt-neo)
- Why it matters: authoritative reference on `GPT-Neo` (github.com).
-- [GPT-J](https://github.com/kingoflolz/mesh-transformer-jax)
- Why it matters: authoritative reference on `GPT-J` (github.com).
-- [Chapter 1: Getting Started](01-getting-started.md)
- Why it matters: authoritative reference on `Chapter 1: Getting Started` (01-getting-started.md).
+## Source Code Walkthrough
+
+### `train.py` (nanoGPT)
+
+The DDP initialization block in [`train.py`](https://github.com/karpathy/nanoGPT/blob/master/train.py) demonstrates how nanoGPT scales to multi-GPU via `torchrun`:
+
+```python
+# To run with DDP on 4 gpus on 1 node, example:
+# $ torchrun --standalone --nproc_per_node=4 train.py
+
+# To run with DDP on 4 gpus across 2 nodes, example:
+# - Run on the first (master) node:
+# $ torchrun --nproc_per_node=8 --nnodes=2 --node_rank=0 --master_addr=123.456.123.456 train.py
+# - Run on the worker node:
+# $ torchrun --nproc_per_node=8 --nnodes=2 --node_rank=1 --master_addr=123.456.123.456 train.py
+
+from torch.nn.parallel import DistributedDataParallel as DDP
+from torch.distributed import init_process_group, destroy_process_group
+```
+
+`gradient_accumulation_steps = 5 * 8` effectively trains with batch size `12 * 40 = 480` tokens per step without needing 40x more GPU memory. The `bench.py` script in nanoGPT provides a simple MFU (Model FLOPs Utilization) benchmark for measuring hardware efficiency.
Suggested trace strategy:
- search upstream code for `self` and `model` to map concrete implementation paths
diff --git a/tutorials/gpt-oss-tutorial/07-fine-tuning-alignment.md b/tutorials/gpt-oss-tutorial/07-fine-tuning-alignment.md
index aa2233c8..eeb3138f 100644
--- a/tutorials/gpt-oss-tutorial/07-fine-tuning-alignment.md
+++ b/tutorials/gpt-oss-tutorial/07-fine-tuning-alignment.md
@@ -674,22 +674,20 @@ Under the hood, `Chapter 7: Fine-Tuning & Alignment -- LoRA, QLoRA, RLHF, DPO, a
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
-## Source Walkthrough
-
-Use the following upstream sources to verify implementation details while reading this chapter:
-
-- [nanoGPT](https://github.com/karpathy/nanoGPT)
- Why it matters: authoritative reference on `nanoGPT` (github.com).
-- [minGPT](https://github.com/karpathy/minGPT)
- Why it matters: authoritative reference on `minGPT` (github.com).
-- [GPT-NeoX](https://github.com/EleutherAI/gpt-neox)
- Why it matters: authoritative reference on `GPT-NeoX` (github.com).
-- [GPT-Neo](https://github.com/EleutherAI/gpt-neo)
- Why it matters: authoritative reference on `GPT-Neo` (github.com).
-- [GPT-J](https://github.com/kingoflolz/mesh-transformer-jax)
- Why it matters: authoritative reference on `GPT-J` (github.com).
-- [Chapter 1: Getting Started](01-getting-started.md)
- Why it matters: authoritative reference on `Chapter 1: Getting Started` (01-getting-started.md).
+## Source Code Walkthrough
+
+### `train.py` (nanoGPT)
+
+The fine-tuning starting point in [`train.py`](https://github.com/karpathy/nanoGPT/blob/master/train.py) is controlled by the `init_from` config variable:
+
+```python
+init_from = 'scratch' # 'scratch' or 'resume' or 'gpt2*'
+
+# model
+dropout = 0.0 # for pretraining 0 is good, for finetuning try 0.1+
+```
+
+Setting `init_from = 'gpt2'` loads pretrained GPT-2 weights and `dropout = 0.1` enables regularization for fine-tuning. The `configurator.py` script allows overriding any config via CLI arguments, making it easy to run fine-tuning experiments: `python train.py config/finetune_shakespeare.py`. The `GPT.from_pretrained` classmethod loads weights directly from Hugging Face Hub.
Suggested trace strategy:
- search upstream code for `model` and `self` to map concrete implementation paths
diff --git a/tutorials/gpt-oss-tutorial/08-production-inference.md b/tutorials/gpt-oss-tutorial/08-production-inference.md
index 1aebc46d..2eaf6754 100644
--- a/tutorials/gpt-oss-tutorial/08-production-inference.md
+++ b/tutorials/gpt-oss-tutorial/08-production-inference.md
@@ -705,22 +705,25 @@ Under the hood, `Chapter 8: Production Inference -- Quantization, Batching, Spec
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
-## Source Walkthrough
-
-Use the following upstream sources to verify implementation details while reading this chapter:
-
-- [nanoGPT](https://github.com/karpathy/nanoGPT)
- Why it matters: authoritative reference on `nanoGPT` (github.com).
-- [minGPT](https://github.com/karpathy/minGPT)
- Why it matters: authoritative reference on `minGPT` (github.com).
-- [GPT-NeoX](https://github.com/EleutherAI/gpt-neox)
- Why it matters: authoritative reference on `GPT-NeoX` (github.com).
-- [GPT-Neo](https://github.com/EleutherAI/gpt-neo)
- Why it matters: authoritative reference on `GPT-Neo` (github.com).
-- [GPT-J](https://github.com/kingoflolz/mesh-transformer-jax)
- Why it matters: authoritative reference on `GPT-J` (github.com).
-- [Chapter 1: Getting Started](01-getting-started.md)
- Why it matters: authoritative reference on `Chapter 1: Getting Started` (01-getting-started.md).
+## Source Code Walkthrough
+
+### `sample.py` (nanoGPT)
+
+The `sample.py` script in [`sample.py`](https://github.com/karpathy/nanoGPT/blob/master/sample.py) is the inference entrypoint for nanoGPT. It loads a trained checkpoint, encodes a prompt with tiktoken, and runs autoregressive generation:
+
+```python
+# sample.py usage:
+# python sample.py --out_dir=out-shakespeare
+# python sample.py --init_from=gpt2 # use pretrained GPT-2
+
+# key inference parameters:
+# num_samples = 10 # number of sequences to generate
+# max_new_tokens = 500
+# temperature = 0.8 # 1.0 = no change, < 1.0 = less random, > 1.0 = more random
+# top_k = 200 # retain only top_k tokens for sampling
+```
+
+The `@torch.no_grad()` decorator on the generation loop prevents gradient accumulation, reducing memory usage by ~50%. `torch.compile()` (PyTorch 2.0+) can be applied to the model before inference for 2-3x throughput improvement on modern GPUs.
Suggested trace strategy:
- search upstream code for `model` and `torch` to map concrete implementation paths
diff --git a/tutorials/gptme-tutorial/01-getting-started.md b/tutorials/gptme-tutorial/01-getting-started.md
index 5e2938e0..f497beaf 100644
--- a/tutorials/gptme-tutorial/01-getting-started.md
+++ b/tutorials/gptme-tutorial/01-getting-started.md
@@ -39,170 +39,168 @@ You now have gptme installed and ready for interactive local workflows.
Next: [Chapter 2: Core CLI Workflow and Prompt Patterns](02-core-cli-workflow-and-prompt-patterns.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `gptme/prompts.py`
+### `gptme/codeblock.py`
-The `get_prompt` function in [`gptme/prompts.py`](https://github.com/gptme/gptme/blob/HEAD/gptme/prompts.py) handles a key part of this chapter's functionality:
+The `Codeblock` class in [`gptme/codeblock.py`](https://github.com/gptme/gptme/blob/HEAD/gptme/codeblock.py) handles a key part of this chapter's functionality:
```py
-
-def get_prompt(
- tools: list[ToolSpec],
- tool_format: ToolFormat = "markdown",
- prompt: PromptType | str = "full",
- interactive: bool = True,
- model: str | None = None,
- workspace: Path | None = None,
- agent_path: Path | None = None,
- context_mode: ContextMode | None = None,
- context_include: list[str] | None = None,
-) -> list[Message]:
- """
- Get the initial system prompt.
-
- The prompt is assembled from several layers:
-
- 1. **Core prompt** (always included):
-
- - Base gptme identity and instructions
- - User identity/preferences (interactive only, from user config ``[user]``;
- skipped in ``--non-interactive`` since no human is present)
- - Tool descriptions (when tools are loaded, controlled by ``--tools``)
-
- 2. **Context** (controlled by ``--context``, independent of ``--non-interactive``):
-
- - ``files``: static files from project config (gptme.toml ``[prompt] files``)
- and user config (``~/.config/gptme/config.toml`` ``[prompt] files``).
- Both sources are merged and deduplicated.
- - ``cmd``: dynamic output of ``context_cmd`` in gptme.toml (project-level only,
- no user-level equivalent). Changes most often, least cacheable.
+@dataclass(frozen=True)
+class Codeblock:
+ lang: str
+ content: str
+ path: str | None = None
+ start: int | None = field(default=None, compare=False)
+ fence: str = field(default_factory=lambda: "```", compare=False, repr=False)
+
+ def __post_init__(self):
+ # init path if path is None and lang is pathy
+ if self.path is None and self.is_filename:
+ object.__setattr__(self, "path", self.lang) # frozen dataclass workaround
+
+ def to_markdown(self) -> str:
+ return f"{self.fence}{self.lang}\n{self.content}\n{self.fence}"
+
+ def to_xml(self) -> str:
+ """Converts codeblock to XML with proper escaping."""
+ # Use quoteattr for attributes to handle quotes and special chars safely
+ # Use xml_escape for content to handle <, >, & characters
+ path_attr = f" path={quoteattr(self.path)}" if self.path else ""
+ return f"<codeblock lang={quoteattr(self.lang)}{path_attr}>\n{xml_escape(self.content)}\n</codeblock>"
+
+ @classmethod
+ @trace_function(name="codeblock.from_markdown", attributes={"component": "parser"})
+ def from_markdown(cls, content: str) -> "Codeblock":
+ stripped = content.strip()
+ fence_len = 0
+
+ # Handle variable-length fences (3+ backticks)
+ start_match = re.match(r"^(`{3,})", stripped)
```
-This function is important because it defines how gptme Tutorial: Open-Source Terminal Agent for Local Tool-Driven Work implements the patterns covered in this chapter.
+This class is important because it defines how gptme Tutorial: Open-Source Terminal Agent for Local Tool-Driven Work implements the patterns covered in this chapter.
-### `gptme/prompts.py`
+### `gptme/codeblock.py`
-The `prompt_full` function in [`gptme/prompts.py`](https://github.com/gptme/gptme/blob/HEAD/gptme/prompts.py) handles a key part of this chapter's functionality:
+The `workaround` class in [`gptme/codeblock.py`](https://github.com/gptme/gptme/blob/HEAD/gptme/codeblock.py) handles a key part of this chapter's functionality:
```py
- if include_tools:
- core_msgs = list(
- prompt_full(
- interactive,
- tools,
- tool_format,
- model,
- agent_name=agent_name,
- workspace=workspace,
- )
- )
- else:
- # Full mode without tools
- # Note: skills summary is intentionally excluded here since skills
- # require tool access (e.g., `cat <path>`) to load on-demand
- core_msgs = list(
- prompt_gptme(interactive, model, agent_name, tool_format=tool_format)
- )
- if interactive:
- core_msgs.extend(prompt_user(tool_format=tool_format))
- core_msgs.extend(prompt_project(tool_format=tool_format))
- core_msgs.extend(prompt_systeminfo(workspace, tool_format=tool_format))
- core_msgs.extend(prompt_timeinfo(tool_format=tool_format))
- elif prompt == "short":
- if include_tools:
- core_msgs = list(
- prompt_short(interactive, tools, tool_format, agent_name=agent_name)
- )
- else:
- core_msgs = list(
- prompt_gptme(interactive, model, agent_name, tool_format=tool_format)
- )
+ # init path if path is None and lang is pathy
+ if self.path is None and self.is_filename:
+ object.__setattr__(self, "path", self.lang) # frozen dataclass workaround
+
+ def to_markdown(self) -> str:
+ return f"{self.fence}{self.lang}\n{self.content}\n{self.fence}"
+
+ def to_xml(self) -> str:
+ """Converts codeblock to XML with proper escaping."""
+ # Use quoteattr for attributes to handle quotes and special chars safely
+ # Use xml_escape for content to handle <, >, & characters
+ path_attr = f" path={quoteattr(self.path)}" if self.path else ""
+ return f"<codeblock lang={quoteattr(self.lang)}{path_attr}>\n{xml_escape(self.content)}\n</codeblock>"
+
+ @classmethod
+ @trace_function(name="codeblock.from_markdown", attributes={"component": "parser"})
+ def from_markdown(cls, content: str) -> "Codeblock":
+ stripped = content.strip()
+ fence_len = 0
+
+ # Handle variable-length fences (3+ backticks)
+ start_match = re.match(r"^(`{3,})", stripped)
+ if start_match:
+ fence_len = len(start_match.group(1))
+ stripped = stripped[fence_len:]
+
+ # Check for closing fence at end - only strip if fence lengths match
+ end_match = re.search(r"(`{3,})$", stripped.strip())
+ if end_match:
+ end_fence_len = len(end_match.group(1))
+ # Only strip closing fence if it matches opening fence length (CommonMark spec)
+ if fence_len == end_fence_len:
```
-This function is important because it defines how gptme Tutorial: Open-Source Terminal Agent for Local Tool-Driven Work implements the patterns covered in this chapter.
+This class is important because it defines how gptme Tutorial: Open-Source Terminal Agent for Local Tool-Driven Work implements the patterns covered in this chapter.
-### `gptme/prompts.py`
+### `scripts/demo_capture.py`
-The `prompt_short` function in [`gptme/prompts.py`](https://github.com/gptme/gptme/blob/HEAD/gptme/prompts.py) handles a key part of this chapter's functionality:
+The `check_tool` function in [`scripts/demo_capture.py`](https://github.com/gptme/gptme/blob/HEAD/scripts/demo_capture.py) handles a key part of this chapter's functionality:
```py
- if include_tools:
- core_msgs = list(
- prompt_short(interactive, tools, tool_format, agent_name=agent_name)
- )
- else:
- core_msgs = list(
- prompt_gptme(interactive, model, agent_name, tool_format=tool_format)
- )
- else:
- core_msgs = [Message("system", prompt)]
- if tools and include_tools:
- core_msgs.extend(
- prompt_tools(tools=tools, tool_format=tool_format, model=model)
- )
- # TODO: generate context_cmd outputs separately and put them last in a "dynamic context" section
- # with context known not to cache well across conversation starts, so that cache points can be set before and better utilized/changed less frequently.
- # probably together with chat history since it's also dynamic/live context.
- # as opposed to static (core/system prompt) and semi-static (workspace/project prompt, like files).
-
- # Generate workspace messages separately (if included)
- workspace_msgs = (
- list(prompt_workspace(workspace, include_context_cmd=include_context_cmd))
- if include_workspace and workspace and workspace != agent_path
- else []
- )
-
- # Agent config workspace (separate from project, only with --agent-path)
- agent_config_msgs = (
- list(
- prompt_workspace(
- agent_path,
+
+def check_tool(name: str) -> bool:
+ """Check if a tool is available."""
+ return shutil.which(name) is not None
+
+
+def check_prerequisites(modes: list[str]) -> list[str]:
+ """Check required tools and return list of missing ones."""
+ missing = []
+
+ if "terminal" in modes:
+ if not check_tool("asciinema"):
+ missing.append("asciinema (pip install asciinema)")
+ if not check_tool("gptme"):
+ missing.append("gptme (pip install gptme)")
+
+ if "screenshots" in modes or "recording" in modes:
+ try:
+ # Check if playwright is importable
+ subprocess.run(
+ [
+ sys.executable,
+ "-c",
+ "from playwright.sync_api import sync_playwright",
+ ],
+ capture_output=True,
+ check=True,
+ )
+ except (subprocess.CalledProcessError, FileNotFoundError):
+ missing.append(
+ "playwright (pip install playwright && playwright install chromium)"
```
This function is important because it defines how gptme Tutorial: Open-Source Terminal Agent for Local Tool-Driven Work implements the patterns covered in this chapter.
-### `gptme/prompts.py`
+### `scripts/demo_capture.py`
-The `prompt_gptme` function in [`gptme/prompts.py`](https://github.com/gptme/gptme/blob/HEAD/gptme/prompts.py) handles a key part of this chapter's functionality:
+The `check_prerequisites` function in [`scripts/demo_capture.py`](https://github.com/gptme/gptme/blob/HEAD/scripts/demo_capture.py) handles a key part of this chapter's functionality:
```py
- # Selective mode with no tools loaded: base prompt only
- core_msgs = list(
- prompt_gptme(interactive, model, agent_name, tool_format=tool_format)
- )
- elif prompt == "full":
- if include_tools:
- core_msgs = list(
- prompt_full(
- interactive,
- tools,
- tool_format,
- model,
- agent_name=agent_name,
- workspace=workspace,
- )
+
+
+def check_prerequisites(modes: list[str]) -> list[str]:
+ """Check required tools and return list of missing ones."""
+ missing = []
+
+ if "terminal" in modes:
+ if not check_tool("asciinema"):
+ missing.append("asciinema (pip install asciinema)")
+ if not check_tool("gptme"):
+ missing.append("gptme (pip install gptme)")
+
+ if "screenshots" in modes or "recording" in modes:
+ try:
+ # Check if playwright is importable
+ subprocess.run(
+ [
+ sys.executable,
+ "-c",
+ "from playwright.sync_api import sync_playwright",
+ ],
+ capture_output=True,
+ check=True,
)
- else:
- # Full mode without tools
- # Note: skills summary is intentionally excluded here since skills
- # require tool access (e.g., `cat <path>`) to load on-demand
- core_msgs = list(
- prompt_gptme(interactive, model, agent_name, tool_format=tool_format)
+ except (subprocess.CalledProcessError, FileNotFoundError):
+ missing.append(
+ "playwright (pip install playwright && playwright install chromium)"
)
- if interactive:
- core_msgs.extend(prompt_user(tool_format=tool_format))
- core_msgs.extend(prompt_project(tool_format=tool_format))
- core_msgs.extend(prompt_systeminfo(workspace, tool_format=tool_format))
- core_msgs.extend(prompt_timeinfo(tool_format=tool_format))
- elif prompt == "short":
- if include_tools:
- core_msgs = list(
- prompt_short(interactive, tools, tool_format, agent_name=agent_name)
+
+ if not check_tool("gptme-server"):
+ missing.append("gptme-server (pip install gptme)")
+
```
This function is important because it defines how gptme Tutorial: Open-Source Terminal Agent for Local Tool-Driven Work implements the patterns covered in this chapter.
@@ -212,11 +210,11 @@ This function is important because it defines how gptme Tutorial: Open-Source Te
```mermaid
flowchart TD
- A[get_prompt]
- B[prompt_full]
- C[prompt_short]
- D[prompt_gptme]
- E[prompt_user]
+ A[Codeblock]
+ B[workaround]
+ C[check_tool]
+ D[check_prerequisites]
+ E[capture_terminal_demo]
A --> B
B --> C
C --> D
diff --git a/tutorials/gptme-tutorial/02-core-cli-workflow-and-prompt-patterns.md b/tutorials/gptme-tutorial/02-core-cli-workflow-and-prompt-patterns.md
index c2e9a629..7bdbd376 100644
--- a/tutorials/gptme-tutorial/02-core-cli-workflow-and-prompt-patterns.md
+++ b/tutorials/gptme-tutorial/02-core-cli-workflow-and-prompt-patterns.md
@@ -37,184 +37,182 @@ You now know how to structure repeatable prompt flows and resume long-running co
Next: [Chapter 3: Tooling and Local Execution Boundaries](03-tooling-and-local-execution-boundaries.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `scripts/analyze_compression.py`
+### `gptme/message.py`
-The `create_plot` function in [`scripts/analyze_compression.py`](https://github.com/gptme/gptme/blob/HEAD/scripts/analyze_compression.py) handles a key part of this chapter's functionality:
+The `format_msgs` function in [`gptme/message.py`](https://github.com/gptme/gptme/blob/HEAD/gptme/message.py) handles a key part of this chapter's functionality:
```py
+ content += "..."
+ temp_msg = self.replace(content=content)
+ return format_msgs([temp_msg], oneline=True, highlight=highlight)[0]
+ return format_msgs([self], oneline=oneline, highlight=highlight)[0]
+
+ def print(self, oneline: bool = False, highlight: bool = True) -> None:
+ print_msg(self, oneline=oneline, highlight=highlight)
+
+ def to_toml(self) -> str:
+ """Converts a message to a TOML string, for easy editing by hand in editor to then be parsed back."""
+ flags = []
+ if self.pinned:
+ flags.append("pinned")
+ if self.hide:
+ flags.append("hide")
+ flags_toml = "\n".join(f"{flag} = true" for flag in flags)
+ # Use proper TOML array syntax with escaped strings (not Python repr)
+ if self.files:
+ escaped_files = ", ".join(f'"{escape_string(str(f))}"' for f in self.files)
+ files_toml = f"files = [{escaped_files}]"
+ else:
+ files_toml = ""
+ # Serialize file_hashes as TOML inline table with proper escaping
+ if self.file_hashes:
+ items = ", ".join(
+ f'"{escape_string(k)}" = "{escape_string(v)}"'
+ for k, v in self.file_hashes.items()
+ )
+ file_hashes_toml = f"file_hashes = {{ {items} }}"
+ else:
+ file_hashes_toml = ""
+ # Serialize metadata as TOML inline table if present
+```
+This function is important because it defines how gptme Tutorial: Open-Source Terminal Agent for Local Tool-Driven Work implements the patterns covered in this chapter.
-def create_plot(distribution: dict, output_file: str = "compression_distribution.png"):
- """Create matplotlib plot of distribution."""
- try:
- import matplotlib.pyplot as plt # type: ignore[import-not-found]
- import numpy as np # type: ignore[import-not-found]
- except ImportError:
- print("Note: Install matplotlib for plot generation: pip install matplotlib")
- return
+### `gptme/message.py`
- buckets = distribution["buckets"]
- bucket_names = list(buckets.keys())
- counts = [len(buckets[name]) for name in bucket_names]
+The `print_msg` function in [`gptme/message.py`](https://github.com/gptme/gptme/blob/HEAD/gptme/message.py) handles a key part of this chapter's functionality:
- # Create figure
- fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(14, 6))
+```py
- # Histogram
- colors = [
- "red" if i < 3 else "orange" if i < 5 else "green"
- for i in range(len(bucket_names))
- ]
- ax1.bar(range(len(bucket_names)), counts, color=colors, alpha=0.7)
- ax1.set_xlabel("Novelty Ratio")
- ax1.set_ylabel("Message Count")
- ax1.set_title("Distribution of Information Novelty")
- ax1.set_xticks(range(len(bucket_names)))
- ax1.set_xticklabels(bucket_names, rotation=45, ha="right")
- ax1.grid(axis="y", alpha=0.3)
-
- # Add classification zones
+ def print(self, oneline: bool = False, highlight: bool = True) -> None:
+ print_msg(self, oneline=oneline, highlight=highlight)
+
+ def to_toml(self) -> str:
+ """Converts a message to a TOML string, for easy editing by hand in editor to then be parsed back."""
+ flags = []
+ if self.pinned:
+ flags.append("pinned")
+ if self.hide:
+ flags.append("hide")
+ flags_toml = "\n".join(f"{flag} = true" for flag in flags)
+ # Use proper TOML array syntax with escaped strings (not Python repr)
+ if self.files:
+ escaped_files = ", ".join(f'"{escape_string(str(f))}"' for f in self.files)
+ files_toml = f"files = [{escaped_files}]"
+ else:
+ files_toml = ""
+ # Serialize file_hashes as TOML inline table with proper escaping
+ if self.file_hashes:
+ items = ", ".join(
+ f'"{escape_string(k)}" = "{escape_string(v)}"'
+ for k, v in self.file_hashes.items()
+ )
+ file_hashes_toml = f"file_hashes = {{ {items} }}"
+ else:
+ file_hashes_toml = ""
+ # Serialize metadata as TOML inline table if present
+ if self.metadata:
+ metadata_toml = _format_metadata_toml(self.metadata)
+ else:
+ metadata_toml = ""
```
This function is important because it defines how gptme Tutorial: Open-Source Terminal Agent for Local Tool-Driven Work implements the patterns covered in this chapter.
-### `scripts/analyze_compression.py`
+### `gptme/message.py`
-The `print_results_incremental` function in [`scripts/analyze_compression.py`](https://github.com/gptme/gptme/blob/HEAD/scripts/analyze_compression.py) handles a key part of this chapter's functionality:
+The `msgs_to_toml` function in [`gptme/message.py`](https://github.com/gptme/gptme/blob/HEAD/gptme/message.py) handles a key part of this chapter's functionality:
```py
-def print_results_incremental(
- results: dict, detailed: bool = False, plot: bool = False
-):
- """Print incremental compression analysis results."""
- stats = results["overall_stats"]
-
- print("=" * 80)
- print("INCREMENTAL COMPRESSION ANALYSIS RESULTS")
- print("=" * 80)
- print()
-
- # Overall statistics
- print("Overall Statistics:")
- print(f" Total conversations analyzed: {stats['total_conversations']}")
- print(f" Total messages: {stats['total_messages']}")
- print(f" Average novelty ratio: {stats['avg_novelty_ratio']:.3f}")
- print(f" Low novelty messages (ratio < 0.3): {stats['low_novelty_messages']}")
- print(f" High novelty messages (ratio > 0.7): {stats['high_novelty_messages']}")
- print()
-
- # By role statistics
- print("Information Novelty by Role:")
- for role, data in sorted(results["by_role"].items()):
- avg_ratio = data["total_ratio"] / data["count"] if data["count"] > 0 else 0
- print(f" {role:12s}: {avg_ratio:.3f} (n={data['count']:,})")
- print()
-
- # Distribution analysis
- distribution = analyze_distribution(results)
- if distribution:
-```
+def msgs_to_toml(msgs: Iterable[Message]) -> str:
+ """Converts a list of messages to a TOML string, for easy editing by hand in editor to then be parsed back."""
+ t = ""
+ for msg in msgs:
+ t += msg.to_toml().replace("[message]", "[[messages]]") + "\n\n"
-This function is important because it defines how gptme Tutorial: Open-Source Terminal Agent for Local Tool-Driven Work implements the patterns covered in this chapter.
+ return t
-### `scripts/analyze_compression.py`
-The `main` function in [`scripts/analyze_compression.py`](https://github.com/gptme/gptme/blob/HEAD/scripts/analyze_compression.py) handles a key part of this chapter's functionality:
+def _fix_toml_content(content: str) -> str:
+ """
+ Remove exactly one trailing newline that TOML multiline format adds.
+
+ TOML multiline strings (using triple quotes) add a newline before the
+ closing delimiter. This function removes that artifact while preserving
+ all other whitespace.
+ """
+ content = content.removesuffix("\n")
+ return content
-```py
+def toml_to_msgs(toml: str) -> list[Message]:
+ """
+ Converts a TOML string to a list of messages.
-def main():
- parser = argparse.ArgumentParser(
- description="Analyze compression ratios of conversation logs"
- )
- parser.add_argument(
- "--limit",
- type=int,
- default=100,
- help="Maximum number of conversations to analyze (default: 100)",
- )
- parser.add_argument(
- "--verbose", "-v", action="store_true", help="Show verbose output"
- )
- parser.add_argument(
- "--detailed", "-d", action="store_true", help="Show detailed results"
- )
- parser.add_argument(
- "--incremental",
- "-i",
- action="store_true",
- help="Use incremental compression analysis (measures marginal information contribution)",
- )
- parser.add_argument(
- "--plot",
- "-p",
- action="store_true",
- help="Generate matplotlib plot of distribution (requires matplotlib)",
- )
-
- args = parser.parse_args()
+ The string can be a whole file with multiple [[messages]].
+ """
+ t = tomlkit.parse(toml)
+ assert "messages" in t and isinstance(t["messages"], list)
+ msgs: list[dict] = t["messages"]
```
This function is important because it defines how gptme Tutorial: Open-Source Terminal Agent for Local Tool-Driven Work implements the patterns covered in this chapter.
-### `gptme/codeblock.py`
+### `gptme/message.py`
-The `Codeblock` class in [`gptme/codeblock.py`](https://github.com/gptme/gptme/blob/HEAD/gptme/codeblock.py) handles a key part of this chapter's functionality:
+The `toml_to_msgs` function in [`gptme/message.py`](https://github.com/gptme/gptme/blob/HEAD/gptme/message.py) handles a key part of this chapter's functionality:
```py
-@dataclass(frozen=True)
-class Codeblock:
- lang: str
- content: str
- path: str | None = None
- start: int | None = field(default=None, compare=False)
-
- def __post_init__(self):
- # init path if path is None and lang is pathy
- if self.path is None and self.is_filename:
- object.__setattr__(self, "path", self.lang) # frozen dataclass workaround
-
- def to_markdown(self) -> str:
- return f"```{self.lang}\n{self.content}\n```"
-
- def to_xml(self) -> str:
- """Converts codeblock to XML with proper escaping."""
- # Use quoteattr for attributes to handle quotes and special chars safely
- # Use xml_escape for content to handle <, >, & characters
- path_attr = f" path={quoteattr(self.path)}" if self.path else ""
- return f"<codeblock lang={quoteattr(self.lang)}{path_attr}>\n{xml_escape(self.content)}\n</codeblock>"
-
- @classmethod
- @trace_function(name="codeblock.from_markdown", attributes={"component": "parser"})
- def from_markdown(cls, content: str) -> "Codeblock":
- stripped = content.strip()
- fence_len = 0
-
- # Handle variable-length fences (3+ backticks)
- start_match = re.match(r"^(`{3,})", stripped)
- if start_match:
+
+def toml_to_msgs(toml: str) -> list[Message]:
+ """
+ Converts a TOML string to a list of messages.
+
+ The string can be a whole file with multiple [[messages]].
+ """
+ t = tomlkit.parse(toml)
+ assert "messages" in t and isinstance(t["messages"], list)
+ msgs: list[dict] = t["messages"]
+
+ return [
+ Message(
+ msg["role"],
+ _fix_toml_content(msg["content"]),
+ pinned=msg.get("pinned", False),
+ hide=msg.get("hide", False),
+ timestamp=isoparse(msg["timestamp"]),
+ files=[parse_file_reference(f) for f in msg.get("files", [])],
+ file_hashes=dict(msg.get("file_hashes", {})),
+ call_id=msg.get("call_id"),
+ metadata=_migrate_metadata(dict(msg["metadata"]))
+ if msg.get("metadata")
+ else None,
+ )
+ for msg in msgs
+ ]
+
+
+def msgs2dicts(msgs: list[Message]) -> list[dict]:
+ """Convert a list of Message objects to a list of dicts ready to pass to an LLM."""
```
-This class is important because it defines how gptme Tutorial: Open-Source Terminal Agent for Local Tool-Driven Work implements the patterns covered in this chapter.
+This function is important because it defines how gptme Tutorial: Open-Source Terminal Agent for Local Tool-Driven Work implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[create_plot]
- B[print_results_incremental]
- C[main]
- D[Codeblock]
- E[workaround]
+ A[format_msgs]
+ B[print_msg]
+ C[msgs_to_toml]
+ D[toml_to_msgs]
+ E[msgs2dicts]
A --> B
B --> C
C --> D
diff --git a/tutorials/gptme-tutorial/03-tooling-and-local-execution-boundaries.md b/tutorials/gptme-tutorial/03-tooling-and-local-execution-boundaries.md
index ebce5c56..c8f55047 100644
--- a/tutorials/gptme-tutorial/03-tooling-and-local-execution-boundaries.md
+++ b/tutorials/gptme-tutorial/03-tooling-and-local-execution-boundaries.md
@@ -37,184 +37,182 @@ You now understand how gptme's local tool loop works and how to control risk bou
Next: [Chapter 4: Configuration Layers and Environment Strategy](04-configuration-layers-and-environment-strategy.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `gptme/config.py`
+### `scripts/analyze_compression.py`
-The `class` class in [`gptme/config.py`](https://github.com/gptme/gptme/blob/HEAD/gptme/config.py) handles a key part of this chapter's functionality:
+The `print_distribution` function in [`scripts/analyze_compression.py`](https://github.com/gptme/gptme/blob/HEAD/scripts/analyze_compression.py) handles a key part of this chapter's functionality:
```py
-import tempfile
-from contextvars import ContextVar
-from dataclasses import (
- asdict,
- dataclass,
- field,
- replace,
-)
-from functools import lru_cache
-from pathlib import Path
-from typing import TYPE_CHECKING, cast
-
-import tomlkit
-from tomlkit import TOMLDocument
-from tomlkit.exceptions import TOMLKitError
-from typing_extensions import Self
-
-from .context.config import ContextConfig
-from .context.selector.config import ContextSelectorConfig
-from .tools import get_toolchain
-from .util import path_with_tilde
-
-if TYPE_CHECKING:
- from tomlkit.container import Container
-
- from .tools.base import ToolFormat
-
-logger = logging.getLogger(__name__)
-
-
-@dataclass
-class PluginsConfig:
+
+
+def print_distribution(distribution: dict):
+ """Print distribution as ASCII histogram."""
+ if not distribution:
+ return
+
+ print("=" * 80)
+ print("REDUNDANCY DISTRIBUTION")
+ print("=" * 80)
+ print()
+
+ buckets = distribution["buckets"]
+ total = distribution["total"]
+ max_count = max(len(v) for v in buckets.values())
+
+ print(f"Total messages analyzed: {total}")
+ print(f"Range: {distribution['min']:.3f} - {distribution['max']:.3f}")
+ print(f"Median: {distribution['median']:.3f}")
+ print()
+
+ # ASCII histogram
+ print("Distribution (novelty ratio):")
+ print()
+
+ for bucket_name, ratios in buckets.items():
+ count = len(ratios)
+ pct = (count / total * 100) if total > 0 else 0
+
+ # Create bar (max 50 chars)
+ bar_len = int((count / max_count) * 50) if max_count > 0 else 0
+ bar = "█" * bar_len
```
-This class is important because it defines how gptme Tutorial: Open-Source Terminal Agent for Local Tool-Driven Work implements the patterns covered in this chapter.
+This function is important because it defines how gptme Tutorial: Open-Source Terminal Agent for Local Tool-Driven Work implements the patterns covered in this chapter.
-### `gptme/config.py`
+### `scripts/analyze_compression.py`
-The `class` class in [`gptme/config.py`](https://github.com/gptme/gptme/blob/HEAD/gptme/config.py) handles a key part of this chapter's functionality:
+The `create_plot` function in [`scripts/analyze_compression.py`](https://github.com/gptme/gptme/blob/HEAD/scripts/analyze_compression.py) handles a key part of this chapter's functionality:
```py
-import tempfile
-from contextvars import ContextVar
-from dataclasses import (
- asdict,
- dataclass,
- field,
- replace,
-)
-from functools import lru_cache
-from pathlib import Path
-from typing import TYPE_CHECKING, cast
-
-import tomlkit
-from tomlkit import TOMLDocument
-from tomlkit.exceptions import TOMLKitError
-from typing_extensions import Self
-
-from .context.config import ContextConfig
-from .context.selector.config import ContextSelectorConfig
-from .tools import get_toolchain
-from .util import path_with_tilde
-
-if TYPE_CHECKING:
- from tomlkit.container import Container
-
- from .tools.base import ToolFormat
-
-logger = logging.getLogger(__name__)
-
-
-@dataclass
-class PluginsConfig:
+
+
+def create_plot(distribution: dict, output_file: str = "compression_distribution.png"):
+ """Create matplotlib plot of distribution."""
+ try:
+ import matplotlib.pyplot as plt # type: ignore[import-not-found]
+ import numpy as np # type: ignore[import-not-found]
+ except ImportError:
+ print("Note: Install matplotlib for plot generation: pip install matplotlib")
+ return
+
+ buckets = distribution["buckets"]
+ bucket_names = list(buckets.keys())
+ counts = [len(buckets[name]) for name in bucket_names]
+
+ # Create figure
+ fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(14, 6))
+
+ # Histogram
+ colors = [
+ "red" if i < 3 else "orange" if i < 5 else "green"
+ for i in range(len(bucket_names))
+ ]
+ ax1.bar(range(len(bucket_names)), counts, color=colors, alpha=0.7)
+ ax1.set_xlabel("Novelty Ratio")
+ ax1.set_ylabel("Message Count")
+ ax1.set_title("Distribution of Information Novelty")
+ ax1.set_xticks(range(len(bucket_names)))
+ ax1.set_xticklabels(bucket_names, rotation=45, ha="right")
+ ax1.grid(axis="y", alpha=0.3)
+
+ # Add classification zones
```
-This class is important because it defines how gptme Tutorial: Open-Source Terminal Agent for Local Tool-Driven Work implements the patterns covered in this chapter.
+This function is important because it defines how gptme Tutorial: Open-Source Terminal Agent for Local Tool-Driven Work implements the patterns covered in this chapter.
-### `gptme/config.py`
+### `scripts/analyze_compression.py`
-The `class` class in [`gptme/config.py`](https://github.com/gptme/gptme/blob/HEAD/gptme/config.py) handles a key part of this chapter's functionality:
+The `print_results_incremental` function in [`scripts/analyze_compression.py`](https://github.com/gptme/gptme/blob/HEAD/scripts/analyze_compression.py) handles a key part of this chapter's functionality:
```py
-import tempfile
-from contextvars import ContextVar
-from dataclasses import (
- asdict,
- dataclass,
- field,
- replace,
-)
-from functools import lru_cache
-from pathlib import Path
-from typing import TYPE_CHECKING, cast
-
-import tomlkit
-from tomlkit import TOMLDocument
-from tomlkit.exceptions import TOMLKitError
-from typing_extensions import Self
-
-from .context.config import ContextConfig
-from .context.selector.config import ContextSelectorConfig
-from .tools import get_toolchain
-from .util import path_with_tilde
-
-if TYPE_CHECKING:
- from tomlkit.container import Container
-
- from .tools.base import ToolFormat
-
-logger = logging.getLogger(__name__)
-
-
-@dataclass
-class PluginsConfig:
+
+
+def print_results_incremental(
+ results: dict, detailed: bool = False, plot: bool = False
+):
+ """Print incremental compression analysis results."""
+ stats = results["overall_stats"]
+
+ print("=" * 80)
+ print("INCREMENTAL COMPRESSION ANALYSIS RESULTS")
+ print("=" * 80)
+ print()
+
+ # Overall statistics
+ print("Overall Statistics:")
+ print(f" Total conversations analyzed: {stats['total_conversations']}")
+ print(f" Total messages: {stats['total_messages']}")
+ print(f" Average novelty ratio: {stats['avg_novelty_ratio']:.3f}")
+ print(f" Low novelty messages (ratio < 0.3): {stats['low_novelty_messages']}")
+ print(f" High novelty messages (ratio > 0.7): {stats['high_novelty_messages']}")
+ print()
+
+ # By role statistics
+ print("Information Novelty by Role:")
+ for role, data in sorted(results["by_role"].items()):
+ avg_ratio = data["total_ratio"] / data["count"] if data["count"] > 0 else 0
+ print(f" {role:12s}: {avg_ratio:.3f} (n={data['count']:,})")
+ print()
+
+ # Distribution analysis
+ distribution = analyze_distribution(results)
+ if distribution:
```
-This class is important because it defines how gptme Tutorial: Open-Source Terminal Agent for Local Tool-Driven Work implements the patterns covered in this chapter.
+This function is important because it defines how gptme Tutorial: Open-Source Terminal Agent for Local Tool-Driven Work implements the patterns covered in this chapter.
-### `gptme/config.py`
+### `scripts/analyze_compression.py`
-The `class` class in [`gptme/config.py`](https://github.com/gptme/gptme/blob/HEAD/gptme/config.py) handles a key part of this chapter's functionality:
+The `main` function in [`scripts/analyze_compression.py`](https://github.com/gptme/gptme/blob/HEAD/scripts/analyze_compression.py) handles a key part of this chapter's functionality:
```py
-import tempfile
-from contextvars import ContextVar
-from dataclasses import (
- asdict,
- dataclass,
- field,
- replace,
-)
-from functools import lru_cache
-from pathlib import Path
-from typing import TYPE_CHECKING, cast
-
-import tomlkit
-from tomlkit import TOMLDocument
-from tomlkit.exceptions import TOMLKitError
-from typing_extensions import Self
-
-from .context.config import ContextConfig
-from .context.selector.config import ContextSelectorConfig
-from .tools import get_toolchain
-from .util import path_with_tilde
-
-if TYPE_CHECKING:
- from tomlkit.container import Container
-
- from .tools.base import ToolFormat
-
-logger = logging.getLogger(__name__)
-
-
-@dataclass
-class PluginsConfig:
+
+
+def main():
+ parser = argparse.ArgumentParser(
+ description="Analyze compression ratios of conversation logs"
+ )
+ parser.add_argument(
+ "--limit",
+ type=int,
+ default=100,
+ help="Maximum number of conversations to analyze (default: 100)",
+ )
+ parser.add_argument(
+ "--verbose", "-v", action="store_true", help="Show verbose output"
+ )
+ parser.add_argument(
+ "--detailed", "-d", action="store_true", help="Show detailed results"
+ )
+ parser.add_argument(
+ "--incremental",
+ "-i",
+ action="store_true",
+ help="Use incremental compression analysis (measures marginal information contribution)",
+ )
+ parser.add_argument(
+ "--plot",
+ "-p",
+ action="store_true",
+ help="Generate matplotlib plot of distribution (requires matplotlib)",
+ )
+
+ args = parser.parse_args()
```
-This class is important because it defines how gptme Tutorial: Open-Source Terminal Agent for Local Tool-Driven Work implements the patterns covered in this chapter.
+This function is important because it defines how gptme Tutorial: Open-Source Terminal Agent for Local Tool-Driven Work implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[class]
- B[class]
- C[class]
- D[class]
- E[class]
+ A[print_distribution]
+ B[create_plot]
+ C[print_results_incremental]
+ D[main]
+ E[from]
A --> B
B --> C
C --> D
diff --git a/tutorials/gptme-tutorial/04-configuration-layers-and-environment-strategy.md b/tutorials/gptme-tutorial/04-configuration-layers-and-environment-strategy.md
index e58e8b9d..c9d59b98 100644
--- a/tutorials/gptme-tutorial/04-configuration-layers-and-environment-strategy.md
+++ b/tutorials/gptme-tutorial/04-configuration-layers-and-environment-strategy.md
@@ -36,184 +36,182 @@ You now have a deterministic strategy for managing gptme configuration across en
Next: [Chapter 5: Context, Lessons, and Conversation Management](05-context-lessons-and-conversation-management.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `scripts/demo_capture.py`
+### `scripts/github_bot.py`
-The `generate_summary` function in [`scripts/demo_capture.py`](https://github.com/gptme/gptme/blob/HEAD/scripts/demo_capture.py) handles a key part of this chapter's functionality:
+The `get_context` function in [`scripts/github_bot.py`](https://github.com/gptme/gptme/blob/HEAD/scripts/github_bot.py) handles a key part of this chapter's functionality:
```py
-def generate_summary(output_dir: Path, results: dict[str, list[Path | None]]) -> Path:
- """Generate a summary JSON of captured assets."""
- assets: dict[str, list[dict[str, str | int]]] = {}
-
- for mode, files in results.items():
- assets[mode] = []
- for f in files:
- if f and f.exists():
- assets[mode].append(
- {
- "name": f.name,
- "path": str(f),
- "size_bytes": f.stat().st_size,
- }
- )
-
- summary: dict[str, object] = {
- "generated_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
- "assets": assets,
- }
-
- summary_path = output_dir / "summary.json"
- with open(summary_path, "w") as fh:
- json.dump(summary, fh, indent=2)
-
- print(f"\nSummary written to: {summary_path}")
- return summary_path
-
-
-def main():
+def get_context(
+ repository: str, issue_number: int, is_pr: bool, token: str
+) -> dict[str, str]:
+ """Get context from the issue or PR with size limits to prevent token overflow."""
+ context = {}
+ ctx_dir = tempfile.mkdtemp()
+
+ if is_pr:
+ # Get PR details
+ result = run_command(
+ ["gh", "pr", "view", str(issue_number), "--repo", repository],
+ capture=True,
+ )
+ context["pr"] = truncate_content(result.stdout, MAX_CONTEXT_CHARS, "PR details")
+
+ # Get PR comments
+ result = run_command(
+ ["gh", "pr", "view", str(issue_number), "--repo", repository, "-c"],
+ capture=True,
+ )
+ context["comments"] = truncate_content(
+ result.stdout, MAX_COMMENT_CHARS, "comments"
+ )
+
+ # Get PR diff (often the largest, limit more aggressively)
+ result = run_command(
+ ["gh", "pr", "diff", str(issue_number), "--repo", repository],
+ capture=True,
+ )
+ context["diff"] = truncate_content(result.stdout, MAX_DIFF_CHARS, "diff")
```
This function is important because it defines how gptme Tutorial: Open-Source Terminal Agent for Local Tool-Driven Work implements the patterns covered in this chapter.
-### `scripts/demo_capture.py`
+### `scripts/github_bot.py`
-The `main` function in [`scripts/demo_capture.py`](https://github.com/gptme/gptme/blob/HEAD/scripts/demo_capture.py) handles a key part of this chapter's functionality:
+The `determine_action_type` function in [`scripts/github_bot.py`](https://github.com/gptme/gptme/blob/HEAD/scripts/github_bot.py) handles a key part of this chapter's functionality:
```py
-def main():
- parser = argparse.ArgumentParser(
- description="Capture gptme demos: terminal recordings, WebUI screenshots, and screen recordings."
- )
- parser.add_argument("--all", action="store_true", help="Run all capture modes")
- parser.add_argument(
- "--terminal", action="store_true", help="Record terminal demos with asciinema"
+def determine_action_type(command: str, model: str) -> str:
+ """Determine if the command requires changes or just a response."""
+ result = run_command(
+ [
+ "gptme",
+ "--non-interactive",
+ "--model",
+ model,
+ f"Determine if this command requires changes to be made or just a response. "
+ f"Respond with ONLY 'make_changes' or 'respond'. Command: {command}",
+ ],
+ capture=True,
)
- parser.add_argument(
- "--screenshots", action="store_true", help="Capture WebUI screenshots"
- )
- parser.add_argument(
- "--recording", action="store_true", help="Record WebUI interaction video"
- )
- parser.add_argument(
- "--output-dir",
- type=Path,
- default=DEFAULT_OUTPUT_DIR,
- help=f"Output directory (default: {DEFAULT_OUTPUT_DIR})",
- )
- parser.add_argument(
- "--server-url", default="http://localhost:5701", help="WebUI server URL"
- )
- parser.add_argument(
- "--list-demos", action="store_true", help="List available terminal demos"
- )
- parser.add_argument(
- "--model",
- default=None,
- help="Model to use for gptme (e.g. openrouter/anthropic/claude-sonnet-4-6)",
+
+ output = result.stdout.lower()
+ if "make_changes" in output:
+ return "make_changes"
+ return "respond"
+
+
+def run_gptme(
+ command: str,
+ context_dir: str,
+ workspace: str,
+ model: str,
+ timeout: int = 120,
+) -> bool:
+ """Run gptme with the given command and context."""
+ # Build the context file list
+ context_files = list(Path(context_dir).glob("gh-*.md"))
```
This function is important because it defines how gptme Tutorial: Open-Source Terminal Agent for Local Tool-Driven Work implements the patterns covered in this chapter.
-### `gptme/message.py`
+### `scripts/github_bot.py`
-The `UsageData` class in [`gptme/message.py`](https://github.com/gptme/gptme/blob/HEAD/gptme/message.py) handles a key part of this chapter's functionality:
+The `run_gptme` function in [`scripts/github_bot.py`](https://github.com/gptme/gptme/blob/HEAD/scripts/github_bot.py) handles a key part of this chapter's functionality:
```py
-class UsageData(TypedDict, total=False):
- """Token usage data from LLM API responses.
-
- Nested under ``usage`` in :class:`MessageMetadata` to mirror the structure
- returned by LLM provider APIs (Anthropic, OpenAI, etc.).
- """
-
- input_tokens: int
- output_tokens: int
- cache_read_tokens: int
- cache_creation_tokens: int
-
-
-class MessageMetadata(TypedDict, total=False):
- """
- Metadata stored with each message.
-
- All fields are optional for compact storage - only non-None values are serialized.
-
- Token/cost fields are populated for assistant messages when telemetry is enabled.
-
- Token counts are nested under ``usage`` to match LLM API response structure::
-
- {
- "model": "claude-sonnet",
- "cost": 0.005,
- "usage": {
- "input_tokens": 100,
- "output_tokens": 50,
- "cache_read_tokens": 80,
+def run_gptme(
+ command: str,
+ context_dir: str,
+ workspace: str,
+ model: str,
+ timeout: int = 120,
+) -> bool:
+ """Run gptme with the given command and context."""
+ # Build the context file list
+ context_files = list(Path(context_dir).glob("gh-*.md"))
+ context_args = [str(f) for f in context_files]
+
+ cmd = [
+ "gptme",
+ "--non-interactive",
+ "--model",
+ model,
+ command,
+ "<system>",
+ "The project has been cloned to the current directory.",
+ "Here is the context:",
+ *context_args,
+ "</system>",
+ "-",
+ "Write the response to 'response.md', it will be posted as a comment.",
+ ]
+
+ try:
+ result = subprocess.run(
+ cmd,
```
-This class is important because it defines how gptme Tutorial: Open-Source Terminal Agent for Local Tool-Driven Work implements the patterns covered in this chapter.
+This function is important because it defines how gptme Tutorial: Open-Source Terminal Agent for Local Tool-Driven Work implements the patterns covered in this chapter.
-### `gptme/message.py`
+### `scripts/github_bot.py`
-The `MessageMetadata` class in [`gptme/message.py`](https://github.com/gptme/gptme/blob/HEAD/gptme/message.py) handles a key part of this chapter's functionality:
+The `post_response` function in [`scripts/github_bot.py`](https://github.com/gptme/gptme/blob/HEAD/scripts/github_bot.py) handles a key part of this chapter's functionality:
```py
- """Token usage data from LLM API responses.
-
- Nested under ``usage`` in :class:`MessageMetadata` to mirror the structure
- returned by LLM provider APIs (Anthropic, OpenAI, etc.).
- """
-
- input_tokens: int
- output_tokens: int
- cache_read_tokens: int
- cache_creation_tokens: int
-
-class MessageMetadata(TypedDict, total=False):
- """
- Metadata stored with each message.
- All fields are optional for compact storage - only non-None values are serialized.
-
- Token/cost fields are populated for assistant messages when telemetry is enabled.
+def post_response(
+ repository: str, issue_number: int, workspace: str, dry_run: bool = False
+) -> None:
+ """Post the response.md as a comment."""
+ response_file = Path(workspace) / "response.md"
+ if not response_file.exists():
+ print("No response.md generated")
+ return
+
+ if dry_run:
+ print(f"[DRY RUN] Would post response:\n{response_file.read_text()}")
+ return
+
+ run_command(
+ [
+ "gh",
+ "issue",
+ "comment",
+ str(issue_number),
+ "--repo",
+ repository,
+ "--body-file",
+ str(response_file),
+ ]
+ )
- Token counts are nested under ``usage`` to match LLM API response structure::
- {
- "model": "claude-sonnet",
- "cost": 0.005,
- "usage": {
- "input_tokens": 100,
- "output_tokens": 50,
- "cache_read_tokens": 80,
- "cache_creation_tokens": 10,
- }
- }
+def commit_and_push(
+ repository: str,
+ issue_number: int,
```
-This class is important because it defines how gptme Tutorial: Open-Source Terminal Agent for Local Tool-Driven Work implements the patterns covered in this chapter.
+This function is important because it defines how gptme Tutorial: Open-Source Terminal Agent for Local Tool-Driven Work implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[generate_summary]
- B[main]
- C[UsageData]
- D[MessageMetadata]
- E[Message]
+ A[get_context]
+ B[determine_action_type]
+ C[run_gptme]
+ D[post_response]
+ E[commit_and_push]
A --> B
B --> C
C --> D
diff --git a/tutorials/gptme-tutorial/05-context-lessons-and-conversation-management.md b/tutorials/gptme-tutorial/05-context-lessons-and-conversation-management.md
index 5cd68d71..2e2a943c 100644
--- a/tutorials/gptme-tutorial/05-context-lessons-and-conversation-management.md
+++ b/tutorials/gptme-tutorial/05-context-lessons-and-conversation-management.md
@@ -36,170 +36,147 @@ You now know how to preserve quality and consistency as conversation history gro
Next: [Chapter 6: MCP, ACP, and Plugin Extensibility](06-mcp-acp-and-plugin-extensibility.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `scripts/github_bot.py`
+### `gptme/profiles.py`
-The `react_to_comment` function in [`scripts/github_bot.py`](https://github.com/gptme/gptme/blob/HEAD/scripts/github_bot.py) handles a key part of this chapter's functionality:
+The `list_profiles` function in [`gptme/profiles.py`](https://github.com/gptme/gptme/blob/HEAD/gptme/profiles.py) handles a key part of this chapter's functionality:
```py
-def react_to_comment(
- repository: str, comment_id: int, token: str, dry_run: bool = False
-) -> None:
- """Add a +1 reaction to the comment."""
- if dry_run:
- print(f"[DRY RUN] Would react to comment {comment_id}")
- return
-
- run_command(
- [
- "gh",
- "api",
- f"/repos/{repository}/issues/comments/{comment_id}/reactions",
- "-X",
- "POST",
- "-f",
- "content=+1",
- ]
- )
-
-
-# Maximum context sizes to prevent token limit issues
-MAX_CONTEXT_CHARS = 50000 # ~12.5k tokens
-MAX_DIFF_CHARS = 30000 # Diffs can be large, limit separately
-MAX_COMMENT_CHARS = 20000 # Comments can accumulate
-
-
-def truncate_content(content: str, max_chars: int, label: str = "content") -> str:
- """Truncate content to max_chars with a notice if truncated."""
- if len(content) <= max_chars:
+def list_profiles() -> dict[str, Profile]:
+ """List all available profiles (built-in and user-defined).
+
+ User profiles override built-in profiles with the same name.
+ """
+ profiles = BUILTIN_PROFILES.copy()
+ profiles.update(load_user_profiles())
+ return profiles
+
```
This function is important because it defines how gptme Tutorial: Open-Source Terminal Agent for Local Tool-Driven Work implements the patterns covered in this chapter.
-### `scripts/github_bot.py`
+### `gptme/info.py`
-The `truncate_content` function in [`scripts/github_bot.py`](https://github.com/gptme/gptme/blob/HEAD/scripts/github_bot.py) handles a key part of this chapter's functionality:
+The `class` class in [`gptme/info.py`](https://github.com/gptme/gptme/blob/HEAD/gptme/info.py) handles a key part of this chapter's functionality:
```py
+import re
+import shutil
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from . import __version__
+from .dirs import get_logs_dir
+
+
+@dataclass
+class ExtraInfo:
+ """Information about an optional dependency/extra."""
+
+ name: str
+ installed: bool
+ description: str
+ packages: list[str] = field(default_factory=list)
+
+
+@dataclass
+class InstallInfo:
+ """Information about how gptme was installed."""
+
+ method: str # pip, pipx, uv, poetry, unknown
+ editable: bool
+ path: str | None = None
-def truncate_content(content: str, max_chars: int, label: str = "content") -> str:
- """Truncate content to max_chars with a notice if truncated."""
- if len(content) <= max_chars:
- return content
- truncated = content[:max_chars]
- # Try to truncate at a newline for cleaner output
- last_newline = truncated.rfind("\n", max_chars - 500, max_chars)
- if last_newline > max_chars - 500:
- truncated = truncated[:last_newline]
- return f"{truncated}\n\n[... {label} truncated, {len(content) - len(truncated)} chars omitted ...]"
-
-
-def get_context(
- repository: str, issue_number: int, is_pr: bool, token: str
-) -> dict[str, str]:
- """Get context from the issue or PR with size limits to prevent token overflow."""
- context = {}
- ctx_dir = tempfile.mkdtemp()
-
- if is_pr:
- # Get PR details
- result = run_command(
- ["gh", "pr", "view", str(issue_number), "--repo", repository],
- capture=True,
- )
- context["pr"] = truncate_content(result.stdout, MAX_CONTEXT_CHARS, "PR details")
-
- # Get PR comments
- result = run_command(
- ["gh", "pr", "view", str(issue_number), "--repo", repository, "-c"],
+# Human-friendly descriptions for extras (optional enhancement)
+# If an extra isn't listed here, its name will be used as description
+_EXTRA_DESCRIPTIONS = {
+ "browser": "Web browsing with Playwright",
```
-This function is important because it defines how gptme Tutorial: Open-Source Terminal Agent for Local Tool-Driven Work implements the patterns covered in this chapter.
+This class is important because it defines how gptme Tutorial: Open-Source Terminal Agent for Local Tool-Driven Work implements the patterns covered in this chapter.
-### `scripts/github_bot.py`
+### `gptme/info.py`
-The `get_context` function in [`scripts/github_bot.py`](https://github.com/gptme/gptme/blob/HEAD/scripts/github_bot.py) handles a key part of this chapter's functionality:
+The `class` class in [`gptme/info.py`](https://github.com/gptme/gptme/blob/HEAD/gptme/info.py) handles a key part of this chapter's functionality:
```py
+import re
+import shutil
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from . import __version__
+from .dirs import get_logs_dir
+
+
+@dataclass
+class ExtraInfo:
+ """Information about an optional dependency/extra."""
+
+ name: str
+ installed: bool
+ description: str
+ packages: list[str] = field(default_factory=list)
-def get_context(
- repository: str, issue_number: int, is_pr: bool, token: str
-) -> dict[str, str]:
- """Get context from the issue or PR with size limits to prevent token overflow."""
- context = {}
- ctx_dir = tempfile.mkdtemp()
-
- if is_pr:
- # Get PR details
- result = run_command(
- ["gh", "pr", "view", str(issue_number), "--repo", repository],
- capture=True,
- )
- context["pr"] = truncate_content(result.stdout, MAX_CONTEXT_CHARS, "PR details")
-
- # Get PR comments
- result = run_command(
- ["gh", "pr", "view", str(issue_number), "--repo", repository, "-c"],
- capture=True,
- )
- context["comments"] = truncate_content(
- result.stdout, MAX_COMMENT_CHARS, "comments"
- )
-
- # Get PR diff (often the largest, limit more aggressively)
- result = run_command(
- ["gh", "pr", "diff", str(issue_number), "--repo", repository],
- capture=True,
- )
- context["diff"] = truncate_content(result.stdout, MAX_DIFF_CHARS, "diff")
+@dataclass
+class InstallInfo:
+ """Information about how gptme was installed."""
+
+ method: str # pip, pipx, uv, poetry, unknown
+ editable: bool
+ path: str | None = None
+
+
+# Human-friendly descriptions for extras (optional enhancement)
+# If an extra isn't listed here, its name will be used as description
+_EXTRA_DESCRIPTIONS = {
+ "browser": "Web browsing with Playwright",
```
-This function is important because it defines how gptme Tutorial: Open-Source Terminal Agent for Local Tool-Driven Work implements the patterns covered in this chapter.
+This class is important because it defines how gptme Tutorial: Open-Source Terminal Agent for Local Tool-Driven Work implements the patterns covered in this chapter.
-### `scripts/github_bot.py`
+### `gptme/info.py`
-The `determine_action_type` function in [`scripts/github_bot.py`](https://github.com/gptme/gptme/blob/HEAD/scripts/github_bot.py) handles a key part of this chapter's functionality:
+The `get_install_info` function in [`gptme/info.py`](https://github.com/gptme/gptme/blob/HEAD/gptme/info.py) handles a key part of this chapter's functionality:
```py
-def determine_action_type(command: str, model: str) -> str:
- """Determine if the command requires changes or just a response."""
- result = run_command(
- [
- "gptme",
- "--non-interactive",
- "--model",
- model,
- f"Determine if this command requires changes to be made or just a response. "
- f"Respond with ONLY 'make_changes' or 'respond'. Command: {command}",
- ],
- capture=True,
- )
-
- output = result.stdout.lower()
- if "make_changes" in output:
- return "make_changes"
- return "respond"
-
-
-def run_gptme(
- command: str,
- context_dir: str,
- workspace: str,
- model: str,
- timeout: int = 120,
-) -> bool:
- """Run gptme with the given command and context."""
- # Build the context file list
- context_files = list(Path(context_dir).glob("gh-*.md"))
+def get_install_info() -> InstallInfo:
+ """Detect how gptme was installed."""
+ try:
+ dist = importlib.metadata.distribution("gptme")
+
+ # Check installer
+ try:
+ installer = (dist.read_text("INSTALLER") or "").strip().lower()
+ except Exception:
+ installer = "unknown"
+
+ # Check if editable via direct_url.json
+ editable = False
+ path = None
+ try:
+ direct_url_text = dist.read_text("direct_url.json")
+ if direct_url_text:
+ data = json.loads(direct_url_text)
+ editable = data.get("dir_info", {}).get("editable", False)
+ url = data.get("url", "")
+ if url.startswith("file://"):
+ path = url[7:] # Strip file://
+ except Exception:
+ pass
+
+ # Also check if PathDistribution (another indicator of editable)
+ if not editable and type(dist).__name__ == "PathDistribution":
+ editable = True
+
+ # Determine method
```
This function is important because it defines how gptme Tutorial: Open-Source Terminal Agent for Local Tool-Driven Work implements the patterns covered in this chapter.
@@ -209,11 +186,11 @@ This function is important because it defines how gptme Tutorial: Open-Source Te
```mermaid
flowchart TD
- A[react_to_comment]
- B[truncate_content]
- C[get_context]
- D[determine_action_type]
- E[run_gptme]
+ A[list_profiles]
+ B[class]
+ C[class]
+ D[get_install_info]
+ E[get_installed_extras]
A --> B
B --> C
C --> D
diff --git a/tutorials/gptme-tutorial/06-mcp-acp-and-plugin-extensibility.md b/tutorials/gptme-tutorial/06-mcp-acp-and-plugin-extensibility.md
index 5680ae7e..2200bd2b 100644
--- a/tutorials/gptme-tutorial/06-mcp-acp-and-plugin-extensibility.md
+++ b/tutorials/gptme-tutorial/06-mcp-acp-and-plugin-extensibility.md
@@ -37,184 +37,182 @@ You now have an extensibility model for connecting gptme to broader tool ecosyst
Next: [Chapter 7: Automation, Server Mode, and Agent Templates](07-automation-server-mode-and-agent-templates.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `gptme/telemetry.py`
+### `scripts/generate_sounds.py`
-The `record_conversation_change` function in [`gptme/telemetry.py`](https://github.com/gptme/gptme/blob/HEAD/gptme/telemetry.py) handles a key part of this chapter's functionality:
+The `generate_bell_sound` function in [`scripts/generate_sounds.py`](https://github.com/gptme/gptme/blob/HEAD/scripts/generate_sounds.py) handles a key part of this chapter's functionality:
```py
- "record_request_duration",
- "record_tool_call",
- "record_conversation_change",
- "record_llm_request",
- "measure_tokens_per_second",
-]
-
-logger = logging.getLogger(__name__)
-
-# Type variable for generic function decoration
-F = TypeVar("F", bound=Callable[..., Any])
-
-
-def is_telemetry_enabled() -> bool:
- """Check if telemetry is enabled."""
- return _is_enabled()
-
-
-def init_telemetry(
- service_name: str = "gptme",
- enable_flask_instrumentation: bool = True,
- enable_requests_instrumentation: bool = True,
- enable_openai_instrumentation: bool = True,
- enable_anthropic_instrumentation: bool = True,
- agent_name: str | None = None,
- interactive: bool | None = None,
-) -> None:
- """Initialize OpenTelemetry tracing and metrics.
-
- Args:
- service_name: Name of the service for telemetry
- enable_flask_instrumentation: Whether to auto-instrument Flask
+
+
+def generate_bell_sound(
+ duration: float = 1.5,
+ sample_rate: int = 44100,
+ fundamental_freq: float = 800.0,
+ volume: float = 0.3,
+) -> np.ndarray:
+ """Generate a pleasant bell sound using multiple harmonics with exponential decay."""
+ t = np.linspace(0, duration, int(sample_rate * duration))
+
+ # Bell harmonics (frequency ratios based on real bell acoustics)
+ harmonics = [
+ (1.0, 1.0), # Fundamental
+ (2.76, 0.6), # First overtone
+ (5.40, 0.4), # Second overtone
+ (8.93, 0.25), # Third overtone
+ (13.34, 0.15), # Fourth overtone
+ (18.64, 0.1), # Fifth overtone
+ ]
+
+ bell_sound = np.zeros_like(t)
+
+ for freq_ratio, amplitude in harmonics:
+ freq = fundamental_freq * freq_ratio
+ sine_wave = np.sin(2 * np.pi * freq * t)
+ decay_rate = 3.0 + freq_ratio * 0.5
+ envelope = np.exp(-decay_rate * t)
+ modulation = 1 + 0.02 * np.sin(2 * np.pi * 5 * t) * envelope
+ bell_sound += amplitude * sine_wave * envelope * modulation
+
+ # Attack envelope
```
This function is important because it defines how gptme Tutorial: Open-Source Terminal Agent for Local Tool-Driven Work implements the patterns covered in this chapter.
-### `gptme/telemetry.py`
+### `scripts/generate_sounds.py`
-The `record_llm_request` function in [`gptme/telemetry.py`](https://github.com/gptme/gptme/blob/HEAD/gptme/telemetry.py) handles a key part of this chapter's functionality:
+The `generate_sawing_sound` function in [`scripts/generate_sounds.py`](https://github.com/gptme/gptme/blob/HEAD/scripts/generate_sounds.py) handles a key part of this chapter's functionality:
```py
- "record_tool_call",
- "record_conversation_change",
- "record_llm_request",
- "measure_tokens_per_second",
-]
-
-logger = logging.getLogger(__name__)
-
-# Type variable for generic function decoration
-F = TypeVar("F", bound=Callable[..., Any])
-
-
-def is_telemetry_enabled() -> bool:
- """Check if telemetry is enabled."""
- return _is_enabled()
-
-
-def init_telemetry(
- service_name: str = "gptme",
- enable_flask_instrumentation: bool = True,
- enable_requests_instrumentation: bool = True,
- enable_openai_instrumentation: bool = True,
- enable_anthropic_instrumentation: bool = True,
- agent_name: str | None = None,
- interactive: bool | None = None,
-) -> None:
- """Initialize OpenTelemetry tracing and metrics.
-
- Args:
- service_name: Name of the service for telemetry
- enable_flask_instrumentation: Whether to auto-instrument Flask
- enable_requests_instrumentation: Whether to auto-instrument requests library
+
+
+def generate_sawing_sound(
+ duration: float = 0.5,
+ sample_rate: int = 44100,
+ volume: float = 0.2,
+) -> np.ndarray:
+ """Generate a gentle whir sound for general tool use."""
+ t = np.linspace(0, duration, int(sample_rate * duration))
+
+ # Gentle whir: soft oscillating tone
+ base_freq = 300.0
+ modulation_freq = 8.0
+
+ # Create oscillating frequency
+ freq_modulation = 1 + 0.3 * np.sin(2 * np.pi * modulation_freq * t)
+ whir_sound = np.sin(2 * np.pi * base_freq * freq_modulation * t)
+
+ # Add subtle harmonics
+ whir_sound += 0.4 * np.sin(2 * np.pi * base_freq * 2 * freq_modulation * t)
+ whir_sound += 0.2 * np.sin(2 * np.pi * base_freq * 3 * freq_modulation * t)
+
+ # Smooth envelope
+ envelope = np.sin(np.pi * t / duration) * 0.8 + 0.2
+ whir_sound *= envelope
+
+ # Final envelope
+ fade_samples = int(0.05 * sample_rate)
+ final_envelope = np.ones_like(t)
+ final_envelope[:fade_samples] = np.linspace(0, 1, fade_samples)
+ final_envelope[-fade_samples:] = np.linspace(1, 0, fade_samples)
+
```
This function is important because it defines how gptme Tutorial: Open-Source Terminal Agent for Local Tool-Driven Work implements the patterns covered in this chapter.
-### `gptme/telemetry.py`
+### `scripts/generate_sounds.py`
-The `measure_tokens_per_second` function in [`gptme/telemetry.py`](https://github.com/gptme/gptme/blob/HEAD/gptme/telemetry.py) handles a key part of this chapter's functionality:
+The `generate_drilling_sound` function in [`scripts/generate_sounds.py`](https://github.com/gptme/gptme/blob/HEAD/scripts/generate_sounds.py) handles a key part of this chapter's functionality:
```py
- "record_conversation_change",
- "record_llm_request",
- "measure_tokens_per_second",
-]
-
-logger = logging.getLogger(__name__)
-
-# Type variable for generic function decoration
-F = TypeVar("F", bound=Callable[..., Any])
-
-
-def is_telemetry_enabled() -> bool:
- """Check if telemetry is enabled."""
- return _is_enabled()
-
-
-def init_telemetry(
- service_name: str = "gptme",
- enable_flask_instrumentation: bool = True,
- enable_requests_instrumentation: bool = True,
- enable_openai_instrumentation: bool = True,
- enable_anthropic_instrumentation: bool = True,
- agent_name: str | None = None,
- interactive: bool | None = None,
-) -> None:
- """Initialize OpenTelemetry tracing and metrics.
-
- Args:
- service_name: Name of the service for telemetry
- enable_flask_instrumentation: Whether to auto-instrument Flask
- enable_requests_instrumentation: Whether to auto-instrument requests library
- enable_openai_instrumentation: Whether to auto-instrument OpenAI
+
+
+def generate_drilling_sound(
+ duration: float = 0.4,
+ sample_rate: int = 44100,
+ volume: float = 0.25,
+) -> np.ndarray:
+ """Generate a soft buzz sound for alternative general tool use."""
+ t = np.linspace(0, duration, int(sample_rate * duration))
+
+ # Soft buzz: steady tone with slight vibrato
+ buzz_freq = 400.0
+ vibrato_freq = 6.0
+ vibrato_depth = 0.1
+
+ # Create vibrato
+ vibrato = 1 + vibrato_depth * np.sin(2 * np.pi * vibrato_freq * t)
+ buzz_sound = np.sin(2 * np.pi * buzz_freq * vibrato * t)
+
+ # Add harmonics for warmth
+ buzz_sound += 0.3 * np.sin(2 * np.pi * buzz_freq * 2 * vibrato * t)
+ buzz_sound += 0.1 * np.sin(2 * np.pi * buzz_freq * 3 * vibrato * t)
+
+ # Smooth envelope
+ envelope = np.sin(np.pi * t / duration) * 0.9 + 0.1
+ buzz_sound *= envelope
+
+ # Final envelope
+ fade_samples = int(0.03 * sample_rate)
+ final_envelope = np.ones_like(t)
+ final_envelope[:fade_samples] = np.linspace(0, 1, fade_samples)
+ final_envelope[-fade_samples:] = np.linspace(1, 0, fade_samples)
```
This function is important because it defines how gptme Tutorial: Open-Source Terminal Agent for Local Tool-Driven Work implements the patterns covered in this chapter.
-### `gptme/info.py`
+### `scripts/generate_sounds.py`
-The `class` class in [`gptme/info.py`](https://github.com/gptme/gptme/blob/HEAD/gptme/info.py) handles a key part of this chapter's functionality:
+The `generate_page_turn_sound` function in [`scripts/generate_sounds.py`](https://github.com/gptme/gptme/blob/HEAD/scripts/generate_sounds.py) handles a key part of this chapter's functionality:
```py
-import re
-import shutil
-from dataclasses import dataclass, field
-from pathlib import Path
-
-from . import __version__
-from .dirs import get_logs_dir
-@dataclass
-class ExtraInfo:
- """Information about an optional dependency/extra."""
+def generate_page_turn_sound(
+ duration: float = 0.6,
+ sample_rate: int = 44100,
+ volume: float = 0.25,
+) -> np.ndarray:
+ """Generate a soft whoosh sound for read operations."""
+ t = np.linspace(0, duration, int(sample_rate * duration))
- name: str
- installed: bool
- description: str
- packages: list[str] = field(default_factory=list)
+ # Soft whoosh: frequency sweep from low to high
+ start_freq = 200.0
+ end_freq = 800.0
+ # Create frequency sweep
+ freq_sweep = start_freq + (end_freq - start_freq) * (t / duration)
+ whoosh_sound = np.sin(2 * np.pi * freq_sweep * t)
-@dataclass
-class InstallInfo:
- """Information about how gptme was installed."""
+ # Add subtle harmonics
+ whoosh_sound += 0.3 * np.sin(2 * np.pi * freq_sweep * 2 * t)
- method: str # pip, pipx, uv, poetry, unknown
- editable: bool
- path: str | None = None
+ # Smooth envelope that peaks in the middle
+ envelope = np.sin(np.pi * t / duration) * np.exp(-2 * t)
+ whoosh_sound *= envelope
+ # Final envelope
+ fade_samples = int(0.05 * sample_rate)
+ final_envelope = np.ones_like(t)
+ final_envelope[:fade_samples] = np.linspace(0, 1, fade_samples)
+ final_envelope[-fade_samples:] = np.linspace(1, 0, fade_samples)
-# Human-friendly descriptions for extras (optional enhancement)
-# If an extra isn't listed here, its name will be used as description
-_EXTRA_DESCRIPTIONS = {
- "browser": "Web browsing with Playwright",
+ whoosh_sound *= final_envelope
```
-This class is important because it defines how gptme Tutorial: Open-Source Terminal Agent for Local Tool-Driven Work implements the patterns covered in this chapter.
+This function is important because it defines how gptme Tutorial: Open-Source Terminal Agent for Local Tool-Driven Work implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[record_conversation_change]
- B[record_llm_request]
- C[measure_tokens_per_second]
- D[class]
- E[class]
+ A[generate_bell_sound]
+ B[generate_sawing_sound]
+ C[generate_drilling_sound]
+ D[generate_page_turn_sound]
+ E[generate_seashell_click_sound]
A --> B
B --> C
C --> D
diff --git a/tutorials/gptme-tutorial/07-automation-server-mode-and-agent-templates.md b/tutorials/gptme-tutorial/07-automation-server-mode-and-agent-templates.md
index 730802ae..e5a1d8ba 100644
--- a/tutorials/gptme-tutorial/07-automation-server-mode-and-agent-templates.md
+++ b/tutorials/gptme-tutorial/07-automation-server-mode-and-agent-templates.md
@@ -33,170 +33,168 @@ You now have pathways to operationalize gptme beyond an individual interactive s
Next: [Chapter 8: Production Operations and Security](08-production-operations-and-security.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `scripts/generate_sounds.py`
+### `gptme/init.py`
-The `save_bell_sound` function in [`scripts/generate_sounds.py`](https://github.com/gptme/gptme/blob/HEAD/scripts/generate_sounds.py) handles a key part of this chapter's functionality:
+The `init_logging` function in [`gptme/init.py`](https://github.com/gptme/gptme/blob/HEAD/gptme/init.py) handles a key part of this chapter's functionality:
```py
-def save_bell_sound(output_path: Path, **kwargs) -> None:
- """Generate and save a bell sound to a file."""
- bell_sound = generate_bell_sound(**kwargs)
- sf.write(output_path, bell_sound, 44100)
- print(f"Bell sound saved to: {output_path}")
-
+def init_logging(verbose):
+ handler = RichHandler() # show_time=False
+ logging.basicConfig(
+ level=logging.DEBUG if verbose else logging.INFO,
+ format="%(message)s",
+ datefmt="[%X]",
+ handlers=[handler],
+ force=True, # Override any previous logging configuration
+ )
+
+ # anthropic spams debug logs for every request
+ logging.getLogger("anthropic").setLevel(logging.INFO)
+ logging.getLogger("openai").setLevel(logging.INFO)
+ # set httpx logging to WARNING
+ logging.getLogger("httpx").setLevel(logging.WARNING)
+ logging.getLogger("httpcore").setLevel(logging.WARNING)
+
+ # Apply debouncing filter for OpenTelemetry connection errors
+ # This shows the first error, then suppresses duplicates for 5 minutes
+ # Prevents spam while still alerting users to telemetry issues
+ # Uses singleton filter to share state with setup_telemetry() filters
+ try:
+ from .util._telemetry import get_connection_error_filter
-def play_sound(audio_data: np.ndarray, sample_rate: int = 44100) -> None:
- """Play the sound using the system's default audio player."""
- # Create a temporary file
- with tempfile.NamedTemporaryFile(suffix=".wav", delete=False) as tmp_file:
- tmp_path = tmp_file.name
+ otel_filter = get_connection_error_filter(cooldown_seconds=300.0)
+ logging.getLogger("opentelemetry").addFilter(otel_filter)
+ except ImportError:
+ # OpenTelemetry not installed, no need for filter
+ pass
- try:
- # Save to temporary file
- sf.write(tmp_path, audio_data, sample_rate)
-
- # Try to play using different system commands
- play_commands = [
- ["afplay", tmp_path], # macOS
- ["aplay", tmp_path], # Linux (ALSA)
- ["paplay", tmp_path], # Linux (PulseAudio)
- ["play", tmp_path], # SoX
- ]
-
- for cmd in play_commands:
- if shutil.which(cmd[0]):
- try:
- subprocess.run(cmd, check=True, capture_output=True)
- return
```
This function is important because it defines how gptme Tutorial: Open-Source Terminal Agent for Local Tool-Driven Work implements the patterns covered in this chapter.
-### `scripts/generate_sounds.py`
+### `gptme/dirs.py`
-The `play_sound` function in [`scripts/generate_sounds.py`](https://github.com/gptme/gptme/blob/HEAD/scripts/generate_sounds.py) handles a key part of this chapter's functionality:
+The `get_config_dir` function in [`gptme/dirs.py`](https://github.com/gptme/gptme/blob/HEAD/gptme/dirs.py) handles a key part of this chapter's functionality:
```py
-def play_sound(audio_data: np.ndarray, sample_rate: int = 44100) -> None:
- """Play the sound using the system's default audio player."""
- # Create a temporary file
- with tempfile.NamedTemporaryFile(suffix=".wav", delete=False) as tmp_file:
- tmp_path = tmp_file.name
+def get_config_dir() -> Path:
+ return Path(user_config_dir("gptme"))
- try:
- # Save to temporary file
- sf.write(tmp_path, audio_data, sample_rate)
-
- # Try to play using different system commands
- play_commands = [
- ["afplay", tmp_path], # macOS
- ["aplay", tmp_path], # Linux (ALSA)
- ["paplay", tmp_path], # Linux (PulseAudio)
- ["play", tmp_path], # SoX
- ]
-
- for cmd in play_commands:
- if shutil.which(cmd[0]):
- try:
- subprocess.run(cmd, check=True, capture_output=True)
- return
- except subprocess.CalledProcessError:
- continue
-
- print(
- "Could not find a suitable audio player. Audio saved to temporary file:",
- tmp_path,
- )
+
+def get_readline_history_file() -> Path:
+ return get_data_dir() / "history"
+
+
+def get_pt_history_file() -> Path:
+ return get_data_dir() / "history.pt"
+
+
+def get_data_dir() -> Path:
+ # used in testing, so must take precedence
+ if "XDG_DATA_HOME" in os.environ:
+ return Path(os.environ["XDG_DATA_HOME"]) / "gptme"
+
+ # just a workaround for me personally
+ old = Path("~/.local/share/gptme").expanduser()
+ if old.exists():
+ return old
+
+ return Path(user_data_dir("gptme"))
+
+
+def get_logs_dir() -> Path:
+ """Get the path for **conversation logs** (not to be confused with the logger file)"""
+ if "GPTME_LOGS_HOME" in os.environ:
+ path = Path(os.environ["GPTME_LOGS_HOME"])
+ else:
```
This function is important because it defines how gptme Tutorial: Open-Source Terminal Agent for Local Tool-Driven Work implements the patterns covered in this chapter.
-### `scripts/generate_sounds.py`
+### `gptme/dirs.py`
-The `generate_all_sounds` function in [`scripts/generate_sounds.py`](https://github.com/gptme/gptme/blob/HEAD/scripts/generate_sounds.py) handles a key part of this chapter's functionality:
+The `get_readline_history_file` function in [`gptme/dirs.py`](https://github.com/gptme/gptme/blob/HEAD/gptme/dirs.py) handles a key part of this chapter's functionality:
```py
-def generate_all_sounds(output_dir: Path):
- """Generate all tool sounds and save them to the output directory."""
- output_dir.mkdir(parents=True, exist_ok=True)
+def get_readline_history_file() -> Path:
+ return get_data_dir() / "history"
- sounds: dict[str, SoundGenerator] = {
- "bell.wav": generate_bell_sound,
- "sawing.wav": generate_sawing_sound,
- "drilling.wav": generate_drilling_sound,
- "page_turn.wav": generate_page_turn_sound,
- "seashell_click.wav": generate_seashell_click_sound,
- "camera_shutter.wav": generate_camera_shutter_sound,
- "file_write.wav": generate_file_write_sound,
- "chime.wav": generate_chime_sound,
- }
- for filename, generator in sounds.items():
- sound_data = generator()
- output_path = output_dir / filename
- sf.write(output_path, sound_data, 44100)
- print(f"Generated {filename}")
+def get_pt_history_file() -> Path:
+ return get_data_dir() / "history.pt"
-SRC_DIR = Path(__file__).parent.resolve()
+def get_data_dir() -> Path:
+ # used in testing, so must take precedence
+ if "XDG_DATA_HOME" in os.environ:
+ return Path(os.environ["XDG_DATA_HOME"]) / "gptme"
+ # just a workaround for me personally
+ old = Path("~/.local/share/gptme").expanduser()
+ if old.exists():
+ return old
+
+ return Path(user_data_dir("gptme"))
+
+
+def get_logs_dir() -> Path:
+ """Get the path for **conversation logs** (not to be confused with the logger file)"""
+ if "GPTME_LOGS_HOME" in os.environ:
+ path = Path(os.environ["GPTME_LOGS_HOME"])
+ else:
+ path = get_data_dir() / "logs"
+ path.mkdir(parents=True, exist_ok=True)
+ return path
-def main():
- parser = argparse.ArgumentParser(description="Generate tool sounds for gptme")
- parser.add_argument(
- "-o",
- "--output",
```
This function is important because it defines how gptme Tutorial: Open-Source Terminal Agent for Local Tool-Driven Work implements the patterns covered in this chapter.
-### `scripts/generate_sounds.py`
+### `gptme/dirs.py`
-The `main` function in [`scripts/generate_sounds.py`](https://github.com/gptme/gptme/blob/HEAD/scripts/generate_sounds.py) handles a key part of this chapter's functionality:
+The `get_pt_history_file` function in [`gptme/dirs.py`](https://github.com/gptme/gptme/blob/HEAD/gptme/dirs.py) handles a key part of this chapter's functionality:
```py
- # This creates the varying, organic amplitude swings
-
- # Primary beating pair (main beat)
- beat_freq1 = 4.2 # Hz
- freq1a = fundamental_freq - beat_freq1 / 2
- freq1b = fundamental_freq + beat_freq1 / 2
- beat_wave1 = (np.sin(2 * np.pi * freq1a * t) + np.sin(2 * np.pi * freq1b * t)) * 0.4
-
- # Secondary beating pair (creates variation in beat intensity)
- beat_freq2 = 6.8 # Hz - different beat rate
- freq2a = fundamental_freq - beat_freq2 / 2
- freq2b = fundamental_freq + beat_freq2 / 2
- beat_wave2 = (np.sin(2 * np.pi * freq2a * t) + np.sin(2 * np.pi * freq2b * t)) * 0.3
-
- # Third beating pair (subtle, adds complexity)
- beat_freq3 = 3.1 # Hz - slower beat
- freq3a = fundamental_freq - beat_freq3 / 2
- freq3b = fundamental_freq + beat_freq3 / 2
- beat_wave3 = (np.sin(2 * np.pi * freq3a * t) + np.sin(2 * np.pi * freq3b * t)) * 0.2
-
- # Combine all beating patterns - this creates varying intensity!
- fundamental_wave = beat_wave1 + beat_wave2 + beat_wave3
-
- # Add the main overtone at 2.61x with slower decay
- overtone_freq = fundamental_freq * 2.61
- overtone_decay = np.exp(-2.2 * t) # Slower decay for longer ring
- overtone_wave = 0.3 * np.sin(2 * np.pi * overtone_freq * t) * overtone_decay
-
- # Minimal additional harmonics for cleaner sound
- harm3 = 0.08 * np.sin(2 * np.pi * fundamental_freq * 1.5 * t) * np.exp(-2.8 * t)
-
- # Combine components
+
+
+def get_pt_history_file() -> Path:
+ return get_data_dir() / "history.pt"
+
+
+def get_data_dir() -> Path:
+ # used in testing, so must take precedence
+ if "XDG_DATA_HOME" in os.environ:
+ return Path(os.environ["XDG_DATA_HOME"]) / "gptme"
+
+ # just a workaround for me personally
+ old = Path("~/.local/share/gptme").expanduser()
+ if old.exists():
+ return old
+
+ return Path(user_data_dir("gptme"))
+
+
+def get_logs_dir() -> Path:
+ """Get the path for **conversation logs** (not to be confused with the logger file)"""
+ if "GPTME_LOGS_HOME" in os.environ:
+ path = Path(os.environ["GPTME_LOGS_HOME"])
+ else:
+ path = get_data_dir() / "logs"
+ path.mkdir(parents=True, exist_ok=True)
+ return path
+
+
+def get_project_gptme_dir() -> Path | None:
+ """
+ Walks up the directory tree from the working dir to find the project root,
```
This function is important because it defines how gptme Tutorial: Open-Source Terminal Agent for Local Tool-Driven Work implements the patterns covered in this chapter.
@@ -206,11 +204,11 @@ This function is important because it defines how gptme Tutorial: Open-Source Te
```mermaid
flowchart TD
- A[save_bell_sound]
- B[play_sound]
- C[generate_all_sounds]
- D[main]
- E[TTSBackendLoader]
+ A[init_logging]
+ B[get_config_dir]
+ C[get_readline_history_file]
+ D[get_pt_history_file]
+ E[get_data_dir]
A --> B
B --> C
C --> D
diff --git a/tutorials/gptme-tutorial/08-production-operations-and-security.md b/tutorials/gptme-tutorial/08-production-operations-and-security.md
index f06545fd..0f86ac8f 100644
--- a/tutorials/gptme-tutorial/08-production-operations-and-security.md
+++ b/tutorials/gptme-tutorial/08-production-operations-and-security.md
@@ -29,170 +29,168 @@ Production gptme workflows require clear policy on tool permissions, secret hand
You now have a security and operations baseline for running gptme in production environments.
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `scripts/convert_convo.py`
+### `gptme/telemetry.py`
-The `convert_conversation` function in [`scripts/convert_convo.py`](https://github.com/gptme/gptme/blob/HEAD/scripts/convert_convo.py) handles a key part of this chapter's functionality:
+The `init_telemetry` function in [`gptme/telemetry.py`](https://github.com/gptme/gptme/blob/HEAD/gptme/telemetry.py) handles a key part of this chapter's functionality:
```py
-
-
-def convert_conversation(
- jsonl_path: str,
- output_dir: str | None = None,
- verbose: bool = False,
- filename_format: str = "{index:04d}-{role}.md",
-) -> None:
- """Convert a conversation.jsonl file to individual markdown files.
-
- Args:
- jsonl_path: Path to the conversation.jsonl file
- output_dir: Directory to write markdown files to (default: markdown/ next to input)
- verbose: Whether to print progress messages
- filename_format: Format string for filenames. Available variables:
- {index}: Message number
- {role}: Message role
- {timestamp}: Message timestamp
- """
- input_path = Path(jsonl_path)
- if not input_path.exists():
- print(f"Error: Input file not found: {jsonl_path}")
- sys.exit(1)
-
- # If no output dir specified, create one next to the input file
- output_path = Path(output_dir) if output_dir else input_path.parent / "markdown"
-
- # Create output directory if it doesn't exist
- output_path.mkdir(parents=True, exist_ok=True)
-
- if verbose:
- print(f"Converting {jsonl_path} to markdown files in {output_path}")
+ set_conversation_context,
+)
+from .util._telemetry import init_telemetry as _init
+from .util._telemetry import is_telemetry_enabled as _is_enabled
+from .util._telemetry import shutdown_telemetry as _shutdown
+
+# Re-export conversation context functions for use by other modules
+__all__ = [
+ "set_conversation_context",
+ "get_conversation_context",
+ "clear_conversation_context",
+ "is_telemetry_enabled",
+ "init_telemetry",
+ "shutdown_telemetry",
+ "trace_function",
+ "record_tokens",
+ "record_request_duration",
+ "record_tool_call",
+ "record_conversation_change",
+ "record_llm_request",
+ "measure_tokens_per_second",
+]
+
+logger = logging.getLogger(__name__)
+
+# Type variable for generic function decoration
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def is_telemetry_enabled() -> bool:
+ """Check if telemetry is enabled."""
+ return _is_enabled()
```
This function is important because it defines how gptme Tutorial: Open-Source Terminal Agent for Local Tool-Driven Work implements the patterns covered in this chapter.
-### `scripts/convert_convo.py`
+### `gptme/telemetry.py`
-The `main` function in [`scripts/convert_convo.py`](https://github.com/gptme/gptme/blob/HEAD/scripts/convert_convo.py) handles a key part of this chapter's functionality:
+The `shutdown_telemetry` function in [`gptme/telemetry.py`](https://github.com/gptme/gptme/blob/HEAD/gptme/telemetry.py) handles a key part of this chapter's functionality:
```py
+from .util._telemetry import init_telemetry as _init
+from .util._telemetry import is_telemetry_enabled as _is_enabled
+from .util._telemetry import shutdown_telemetry as _shutdown
+
+# Re-export conversation context functions for use by other modules
+__all__ = [
+ "set_conversation_context",
+ "get_conversation_context",
+ "clear_conversation_context",
+ "is_telemetry_enabled",
+ "init_telemetry",
+ "shutdown_telemetry",
+ "trace_function",
+ "record_tokens",
+ "record_request_duration",
+ "record_tool_call",
+ "record_conversation_change",
+ "record_llm_request",
+ "measure_tokens_per_second",
+]
+
+logger = logging.getLogger(__name__)
+
+# Type variable for generic function decoration
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def is_telemetry_enabled() -> bool:
+ """Check if telemetry is enabled."""
+ return _is_enabled()
-def main() -> None:
- if len(sys.argv) < 2:
- print("""Usage: convert_convo.py <conversation.jsonl> [options]
-
-Options:
- [output_dir] Directory to write markdown files to
- -v, --verbose Show progress messages
- -f, --format FORMAT Custom filename format. Available variables:
- {index}: Message number (e.g. 0001)
- {role}: Message role (e.g. user)
- {timestamp}: Message timestamp (e.g. 20250506-192832)
- Default: {index:04d}-{role}.md""")
- sys.exit(1)
-
- # Parse arguments
- jsonl_path = sys.argv[1]
- args = sys.argv[2:]
-
- output_dir: str | None = None
- verbose = False
- filename_format = "{index:04d}-{role}.md"
-
- while args:
- arg = args.pop(0)
- if arg in ["-v", "--verbose"]:
- verbose = True
- elif arg in ["-f", "--format"]:
- if not args:
- print("Error: --format requires a format string")
- sys.exit(1)
```
This function is important because it defines how gptme Tutorial: Open-Source Terminal Agent for Local Tool-Driven Work implements the patterns covered in this chapter.
-### `scripts/reduce_context.py`
+### `gptme/telemetry.py`
-The `remove_thinking_sections` function in [`scripts/reduce_context.py`](https://github.com/gptme/gptme/blob/HEAD/scripts/reduce_context.py) handles a key part of this chapter's functionality:
+The `trace_function` function in [`gptme/telemetry.py`](https://github.com/gptme/gptme/blob/HEAD/gptme/telemetry.py) handles a key part of this chapter's functionality:
```py
-
-
-def remove_thinking_sections(content):
- """Remove <think>...</think> sections from content."""
- # Fix incomplete thinking sections (no closing tag)
- if "<think>" in content and "</think>" not in content:
- content = re.sub(
- r"<think>.*?$", "[incomplete thinking removed]", content, flags=re.DOTALL
- )
-
- # Remove normal thinking sections
- content = re.sub(
- r"<think>.*?</think>", "[thinking removed]", content, flags=re.DOTALL
- )
-
- return content
-
-
-def simplify_workspace_context(content):
- """Simplify workspace context in system messages."""
- if "# Workspace Context" in content:
- return re.sub(
- r"# Workspace Context.*?$",
- "[workspace context removed]",
- content,
- flags=re.DOTALL,
- )
- return content
-
-
-def simplify_file_contents_in_errors(content):
- """Simplify file content displays in error messages."""
+ "init_telemetry",
+ "shutdown_telemetry",
+ "trace_function",
+ "record_tokens",
+ "record_request_duration",
+ "record_tool_call",
+ "record_conversation_change",
+ "record_llm_request",
+ "measure_tokens_per_second",
+]
+
+logger = logging.getLogger(__name__)
+
+# Type variable for generic function decoration
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def is_telemetry_enabled() -> bool:
+ """Check if telemetry is enabled."""
+ return _is_enabled()
+
+
+def init_telemetry(
+ service_name: str = "gptme",
+ enable_flask_instrumentation: bool = True,
+ enable_requests_instrumentation: bool = True,
+ enable_openai_instrumentation: bool = True,
+ enable_anthropic_instrumentation: bool = True,
+ agent_name: str | None = None,
+ interactive: bool | None = None,
+) -> None:
+ """Initialize OpenTelemetry tracing and metrics.
```
This function is important because it defines how gptme Tutorial: Open-Source Terminal Agent for Local Tool-Driven Work implements the patterns covered in this chapter.
-### `scripts/reduce_context.py`
+### `gptme/telemetry.py`
-The `simplify_workspace_context` function in [`scripts/reduce_context.py`](https://github.com/gptme/gptme/blob/HEAD/scripts/reduce_context.py) handles a key part of this chapter's functionality:
+The `record_tokens` function in [`gptme/telemetry.py`](https://github.com/gptme/gptme/blob/HEAD/gptme/telemetry.py) handles a key part of this chapter's functionality:
```py
+ "shutdown_telemetry",
+ "trace_function",
+ "record_tokens",
+ "record_request_duration",
+ "record_tool_call",
+ "record_conversation_change",
+ "record_llm_request",
+ "measure_tokens_per_second",
+]
+
+logger = logging.getLogger(__name__)
+
+# Type variable for generic function decoration
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def is_telemetry_enabled() -> bool:
+ """Check if telemetry is enabled."""
+ return _is_enabled()
+
+
+def init_telemetry(
+ service_name: str = "gptme",
+ enable_flask_instrumentation: bool = True,
+ enable_requests_instrumentation: bool = True,
+ enable_openai_instrumentation: bool = True,
+ enable_anthropic_instrumentation: bool = True,
+ agent_name: str | None = None,
+ interactive: bool | None = None,
+) -> None:
+ """Initialize OpenTelemetry tracing and metrics.
-
-def simplify_workspace_context(content):
- """Simplify workspace context in system messages."""
- if "# Workspace Context" in content:
- return re.sub(
- r"# Workspace Context.*?$",
- "[workspace context removed]",
- content,
- flags=re.DOTALL,
- )
- return content
-
-
-def simplify_file_contents_in_errors(content):
- """Simplify file content displays in error messages."""
- if "Here are the actual file contents:" in content:
- return re.sub(
- r"(Error during execution:.*?\n)Here are the actual file contents:.*?$",
- r"\1[file contents removed]",
- content,
- flags=re.DOTALL,
- )
- return content
-
-
-def simplify_failed_patches(content):
- """Simplify failed patch blocks in messages."""
- if "Patch failed:" in content:
- return re.sub(
- r"(Patch failed:.*?\n)```.*?```",
- r"\1[failed patch content removed]",
```
This function is important because it defines how gptme Tutorial: Open-Source Terminal Agent for Local Tool-Driven Work implements the patterns covered in this chapter.
@@ -202,11 +200,11 @@ This function is important because it defines how gptme Tutorial: Open-Source Te
```mermaid
flowchart TD
- A[convert_conversation]
- B[main]
- C[remove_thinking_sections]
- D[simplify_workspace_context]
- E[simplify_file_contents_in_errors]
+ A[init_telemetry]
+ B[shutdown_telemetry]
+ C[trace_function]
+ D[record_tokens]
+ E[record_request_duration]
A --> B
B --> C
C --> D
diff --git a/tutorials/hapi-tutorial/01-getting-started.md b/tutorials/hapi-tutorial/01-getting-started.md
index 1179c5f8..1c19fb6a 100644
--- a/tutorials/hapi-tutorial/01-getting-started.md
+++ b/tutorials/hapi-tutorial/01-getting-started.md
@@ -78,21 +78,6 @@ Under the hood, `Chapter 1: Getting Started` usually follows a repeatable contro
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
-## Source Walkthrough
-
-Use the following upstream sources to verify implementation details while reading this chapter:
-
-- [HAPI Repository](https://github.com/tiann/hapi)
- Why it matters: authoritative reference on `HAPI Repository` (github.com).
-- [HAPI Releases](https://github.com/tiann/hapi/releases)
- Why it matters: authoritative reference on `HAPI Releases` (github.com).
-- [HAPI Docs](https://hapi.run)
- Why it matters: authoritative reference on `HAPI Docs` (hapi.run).
-
-Suggested trace strategy:
-- search upstream code for `hapi` and `install` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
-
## Chapter Connections
- [Tutorial Index](README.md)
@@ -100,8 +85,6 @@ Suggested trace strategy:
- [Main Catalog](../../README.md#-tutorial-catalog)
- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `web/vite.config.ts`
@@ -145,125 +128,125 @@ export default defineConfig({
This function is important because it defines how HAPI Tutorial: Remote Control for Local AI Coding Sessions implements the patterns covered in this chapter.
-### `web/src/App.tsx`
+### `web/src/router.tsx`
-The `App` function in [`web/src/App.tsx`](https://github.com/tiann/hapi/blob/HEAD/web/src/App.tsx) handles a key part of this chapter's functionality:
+The `BackIcon` function in [`web/src/router.tsx`](https://github.com/tiann/hapi/blob/HEAD/web/src/router.tsx) handles a key part of this chapter's functionality:
```tsx
-import { Outlet, useLocation, useMatchRoute, useRouter } from '@tanstack/react-router'
-import { useQueryClient } from '@tanstack/react-query'
-import { getTelegramWebApp, isTelegramApp } from '@/hooks/useTelegram'
-import { initializeTheme } from '@/hooks/useTheme'
-import { useAuth } from '@/hooks/useAuth'
-import { useAuthSource } from '@/hooks/useAuthSource'
-import { useServerUrl } from '@/hooks/useServerUrl'
-import { useSSE } from '@/hooks/useSSE'
-import { useSyncingState } from '@/hooks/useSyncingState'
-import { usePushNotifications } from '@/hooks/usePushNotifications'
-import { useVisibilityReporter } from '@/hooks/useVisibilityReporter'
-import { queryKeys } from '@/lib/query-keys'
-import { AppContextProvider } from '@/lib/app-context'
-import { fetchLatestMessages } from '@/lib/message-window-store'
-import { useAppGoBack } from '@/hooks/useAppGoBack'
-import { useTranslation } from '@/lib/use-translation'
-import { VoiceProvider } from '@/lib/voice-context'
-import { requireHubUrlForLogin } from '@/lib/runtime-config'
-import { LoginPrompt } from '@/components/LoginPrompt'
-import { InstallPrompt } from '@/components/InstallPrompt'
-import { OfflineBanner } from '@/components/OfflineBanner'
-import { SyncingBanner } from '@/components/SyncingBanner'
-import { ReconnectingBanner } from '@/components/ReconnectingBanner'
-import { VoiceErrorBanner } from '@/components/VoiceErrorBanner'
-import { LoadingState } from '@/components/LoadingState'
-import { ToastContainer } from '@/components/ToastContainer'
-import { ToastProvider, useToast } from '@/lib/toast-context'
-import type { SyncEvent } from '@/types/api'
-
-type ToastEvent = Extract<SyncEvent, { type: 'toast' }>
-
-const REQUIRE_SERVER_URL = requireHubUrlForLogin()
+import SettingsPage from '@/routes/settings'
+
+function BackIcon(props: { className?: string }) {
+ return (
+ <svg
+ xmlns="http://www.w3.org/2000/svg"
+ width="20"
+ height="20"
+ viewBox="0 0 24 24"
+ fill="none"
+ stroke="currentColor"
+ strokeWidth="2"
+ strokeLinecap="round"
+ strokeLinejoin="round"
+ className={props.className}
+ >
+ <polyline points="15 18 9 12 15 6" />
+ </svg>
+ )
+}
+
+function PlusIcon(props: { className?: string }) {
+ return (
+ <svg
+ xmlns="http://www.w3.org/2000/svg"
+ width="24"
+ height="24"
+ viewBox="0 0 24 24"
+ fill="none"
+ stroke="currentColor"
+ strokeWidth="2"
+ strokeLinecap="round"
```
This function is important because it defines how HAPI Tutorial: Remote Control for Local AI Coding Sessions implements the patterns covered in this chapter.
-### `web/src/App.tsx`
+### `web/src/router.tsx`
-The `AppInner` function in [`web/src/App.tsx`](https://github.com/tiann/hapi/blob/HEAD/web/src/App.tsx) handles a key part of this chapter's functionality:
+The `PlusIcon` function in [`web/src/router.tsx`](https://github.com/tiann/hapi/blob/HEAD/web/src/router.tsx) handles a key part of this chapter's functionality:
```tsx
+}
+
+function PlusIcon(props: { className?: string }) {
return (
- <ToastProvider>
- <AppInner />
- </ToastProvider>
+ <svg
+ xmlns="http://www.w3.org/2000/svg"
+ width="24"
+ height="24"
+ viewBox="0 0 24 24"
+ fill="none"
+ stroke="currentColor"
+ strokeWidth="2"
+ strokeLinecap="round"
+ strokeLinejoin="round"
+ className={props.className}
+ >
+ <line x1="12" y1="5" x2="12" y2="19" />
+ <line x1="5" y1="12" x2="19" y2="12" />
+ </svg>
)
}
-function AppInner() {
- const { t } = useTranslation()
- const { serverUrl, baseUrl, setServerUrl, clearServerUrl } = useServerUrl()
- const { authSource, isLoading: isAuthSourceLoading, setAccessToken } = useAuthSource(baseUrl)
- const { token, api, isLoading: isAuthLoading, error: authError, needsBinding, bind } = useAuth(authSource, baseUrl)
- const goBack = useAppGoBack()
- const pathname = useLocation({ select: (location) => location.pathname })
- const matchRoute = useMatchRoute()
- const router = useRouter()
- const { addToast } = useToast()
-
- useEffect(() => {
- const tg = getTelegramWebApp()
- tg?.ready()
- tg?.expand()
- initializeTheme()
- }, [])
-
- useEffect(() => {
- const preventDefault = (event: Event) => {
- event.preventDefault()
- }
-
- const onWheel = (event: WheelEvent) => {
- if (event.ctrlKey) {
+function SettingsIcon(props: { className?: string }) {
+ return (
+ <svg
+ xmlns="http://www.w3.org/2000/svg"
+ width="20"
+ height="20"
+ viewBox="0 0 24 24"
+ fill="none"
+ stroke="currentColor"
+ strokeWidth="2"
```
This function is important because it defines how HAPI Tutorial: Remote Control for Local AI Coding Sessions implements the patterns covered in this chapter.
-### `hub/scripts/cleanup-sessions.ts`
+### `web/src/router.tsx`
-The `formatDate` function in [`hub/scripts/cleanup-sessions.ts`](https://github.com/tiann/hapi/blob/HEAD/hub/scripts/cleanup-sessions.ts) handles a key part of this chapter's functionality:
+The `SettingsIcon` function in [`web/src/router.tsx`](https://github.com/tiann/hapi/blob/HEAD/web/src/router.tsx) handles a key part of this chapter's functionality:
-```ts
+```tsx
+}
-// Format timestamp as human-readable date
-function formatDate(timestamp: number): string {
- const date = new Date(timestamp)
- return date.toLocaleDateString('en-US', {
- month: 'short',
- day: 'numeric',
- year: 'numeric'
- })
+function SettingsIcon(props: { className?: string }) {
+ return (
+ <svg
+ xmlns="http://www.w3.org/2000/svg"
+ width="20"
+ height="20"
+ viewBox="0 0 24 24"
+ fill="none"
+ stroke="currentColor"
+ strokeWidth="2"
+ strokeLinecap="round"
+ strokeLinejoin="round"
+ className={props.className}
+ >
+ <circle cx="12" cy="12" r="3" />
+ <path d="M19.4 15a1.65 1.65 0 0 0 .33 1.82l.06.06a2 2 0 0 1 0 2.83 2 2 0 0 1-2.83 0l-.06-.06a1.65 1.65 0 0 0-1.82-.33 1.65 1.65 0 0 0-1 1.51V21a2 2 0 0 1-2 2 2 2 0 0 1-2-2v-.09A1.65 1.65 0 0 0 9 19.4a1.65 1.65 0 0 0-1.82.33l-.06.06a2 2 0 0 1-2.83 0 2 2 0 0 1 0-2.83l.06-.06a1.65 1.65 0 0 0 .33-1.82 1.65 1.65 0 0 0-1.51-1H3a2 2 0 0 1-2-2 2 2 0 0 1 2-2h.09A1.65 1.65 0 0 0 4.6 9a1.65 1.65 0 0 0-.33-1.82l-.06-.06a2 2 0 0 1 0-2.83 2 2 0 0 1 2.83 0l.06.06a1.65 1.65 0 0 0 1.82.33H9a1.65 1.65 0 0 0 1-1.51V3a2 2 0 0 1 2-2 2 2 0 0 1 2 2v.09a1.65 1.65 0 0 0 1 1.51 1.65 1.65 0 0 0 1.82-.33l.06-.06a2 2 0 0 1 2.83 0 2 2 0 0 1 0 2.83l-.06.06a1.65 1.65 0 0 0-.33 1.82V9a1.65 1.65 0 0 0 1.51 1H21a2 2 0 0 1 2 2 2 2 0 0 1-2 2h-.09a1.65 1.65 0 0 0-1.51 1z" />
+ </svg>
+ )
}
-// Truncate string to max length with ellipsis
-function truncate(str: string, maxLen: number): string {
- if (str.length <= maxLen) return str
- return str.slice(0, maxLen - 3) + '...'
+function getMachineTitle(machine: Machine): string {
+ if (machine.metadata?.displayName) return machine.metadata.displayName
+ if (machine.metadata?.host) return machine.metadata.host
+ return machine.id.slice(0, 8)
}
-// Extract text from user message content
-function extractUserText(content: unknown): string | null {
- if (!content || typeof content !== 'object') return null
- const c = content as Record<string, unknown>
- if (c.role !== 'user') return null
- const inner = c.content
- // Handle { content: { type: 'text', text: '...' } }
- if (inner && typeof inner === 'object') {
- const textObj = inner as Record<string, unknown>
- if (textObj.type === 'text' && typeof textObj.text === 'string') {
- return textObj.text
- }
- }
- // Handle { content: '...' } (string)
- if (typeof inner === 'string') {
+function SessionsPage() {
+ const { api } = useAppContext()
+ const navigate = useNavigate()
+ const pathname = useLocation({ select: location => location.pathname })
```
This function is important because it defines how HAPI Tutorial: Remote Control for Local AI Coding Sessions implements the patterns covered in this chapter.
@@ -274,10 +257,10 @@ This function is important because it defines how HAPI Tutorial: Remote Control
```mermaid
flowchart TD
A[getVendorChunkName]
- B[App]
- C[AppInner]
- D[formatDate]
- E[truncate]
+ B[BackIcon]
+ C[PlusIcon]
+ D[SettingsIcon]
+ E[getMachineTitle]
A --> B
B --> C
C --> D
diff --git a/tutorials/hapi-tutorial/02-system-architecture.md b/tutorials/hapi-tutorial/02-system-architecture.md
index 8ddc55b1..d76fff00 100644
--- a/tutorials/hapi-tutorial/02-system-architecture.md
+++ b/tutorials/hapi-tutorial/02-system-architecture.md
@@ -72,21 +72,6 @@ Under the hood, `Chapter 2: System Architecture` usually follows a repeatable co
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
-## Source Walkthrough
-
-Use the following upstream sources to verify implementation details while reading this chapter:
-
-- [HAPI Repository](https://github.com/tiann/hapi)
- Why it matters: authoritative reference on `HAPI Repository` (github.com).
-- [HAPI Releases](https://github.com/tiann/hapi/releases)
- Why it matters: authoritative reference on `HAPI Releases` (github.com).
-- [HAPI Docs](https://hapi.run)
- Why it matters: authoritative reference on `HAPI Docs` (hapi.run).
-
-Suggested trace strategy:
-- search upstream code for `graph` and `HAPI` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
-
## Chapter Connections
- [Tutorial Index](README.md)
@@ -95,170 +80,168 @@ Suggested trace strategy:
- [Main Catalog](../../README.md#-tutorial-catalog)
- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `hub/scripts/cleanup-sessions.ts`
-
-The `parseArgs` function in [`hub/scripts/cleanup-sessions.ts`](https://github.com/tiann/hapi/blob/HEAD/hub/scripts/cleanup-sessions.ts) handles a key part of this chapter's functionality:
-
-```ts
-
-// Parse command line arguments
-function parseArgs(): { minMessages: number | null; pathPattern: string | null; messagePattern: string | null; orphaned: boolean; force: boolean; help: boolean } {
- const args = process.argv.slice(2)
- let minMessages: number | null = null
- let pathPattern: string | null = null
- let messagePattern: string | null = null
- let orphaned = false
- let force = false
- let help = false
-
- for (const arg of args) {
- if (arg === '--help' || arg === '-h') {
- help = true
- } else if (arg === '--force' || arg === '-f') {
- force = true
- } else if (arg === '--orphaned') {
- orphaned = true
- } else if (arg.startsWith('--min-messages=')) {
- const value = parseInt(arg.split('=')[1], 10)
- if (isNaN(value) || value < 0) {
- console.error('Error: --min-messages must be a non-negative integer')
- process.exit(1)
- }
- minMessages = value
- } else if (arg.startsWith('--path=')) {
- pathPattern = arg.split('=').slice(1).join('=') // Handle paths with '='
- } else if (arg.startsWith('--message=')) {
- messagePattern = arg.split('=').slice(1).join('=').toLowerCase()
- } else {
- console.error(`Unknown argument: ${arg}`)
- console.error('Use --help for usage information')
+### `web/src/router.tsx`
+
+The `SessionsIndexPage` function in [`web/src/router.tsx`](https://github.com/tiann/hapi/blob/HEAD/web/src/router.tsx) handles a key part of this chapter's functionality:
+
+```tsx
+}
+
+function SessionsIndexPage() {
+ return null
+}
+
+function SessionPage() {
+ const { api } = useAppContext()
+ const { t } = useTranslation()
+ const goBack = useAppGoBack()
+ const navigate = useNavigate()
+ const queryClient = useQueryClient()
+ const { addToast } = useToast()
+ const { sessionId } = useParams({ from: '/sessions/$sessionId' })
+ const {
+ session,
+ refetch: refetchSession,
+ } = useSession(api, sessionId)
+ const {
+ messages,
+ warning: messagesWarning,
+ isLoading: messagesLoading,
+ isLoadingMore: messagesLoadingMore,
+ hasMore: messagesHasMore,
+ loadMore: loadMoreMessages,
+ refetch: refetchMessages,
+ pendingCount,
+ messagesVersion,
+ flushPending,
+ setAtBottom,
+ } = useMessages(api, sessionId)
+ const {
```
This function is important because it defines how HAPI Tutorial: Remote Control for Local AI Coding Sessions implements the patterns covered in this chapter.
-### `hub/scripts/cleanup-sessions.ts`
+### `web/src/router.tsx`
+
+The `SessionPage` function in [`web/src/router.tsx`](https://github.com/tiann/hapi/blob/HEAD/web/src/router.tsx) handles a key part of this chapter's functionality:
-The `getDbPath` function in [`hub/scripts/cleanup-sessions.ts`](https://github.com/tiann/hapi/blob/HEAD/hub/scripts/cleanup-sessions.ts) handles a key part of this chapter's functionality:
+```tsx
+}
+
+function SessionPage() {
+ const { api } = useAppContext()
+ const { t } = useTranslation()
+ const goBack = useAppGoBack()
+ const navigate = useNavigate()
+ const queryClient = useQueryClient()
+ const { addToast } = useToast()
+ const { sessionId } = useParams({ from: '/sessions/$sessionId' })
+ const {
+ session,
+ refetch: refetchSession,
+ } = useSession(api, sessionId)
+ const {
+ messages,
+ warning: messagesWarning,
+ isLoading: messagesLoading,
+ isLoadingMore: messagesLoadingMore,
+ hasMore: messagesHasMore,
+ loadMore: loadMoreMessages,
+ refetch: refetchMessages,
+ pendingCount,
+ messagesVersion,
+ flushPending,
+ setAtBottom,
+ } = useMessages(api, sessionId)
+ const {
+ sendMessage,
+ retryMessage,
+ isSending,
+ } = useSendMessage(api, sessionId, {
+```
+
+This function is important because it defines how HAPI Tutorial: Remote Control for Local AI Coding Sessions implements the patterns covered in this chapter.
+
+### `web/src/router.tsx`
-```ts
+The `SessionDetailRoute` function in [`web/src/router.tsx`](https://github.com/tiann/hapi/blob/HEAD/web/src/router.tsx) handles a key part of this chapter's functionality:
-// Get database path (same logic as configuration.ts)
-function getDbPath(): string {
- if (process.env.DB_PATH) {
- return process.env.DB_PATH.replace(/^~/, homedir())
- }
- const dataDir = process.env.HAPI_HOME
- ? process.env.HAPI_HOME.replace(/^~/, homedir())
- : join(homedir(), '.hapi')
- return join(dataDir, 'hapi.db')
+```tsx
}
-// Session info for display
-interface SessionInfo {
- id: string
- title: string | null
- firstUserMessage: string | null
- path: string | null
- updatedAt: number
- messageCount: number
+function SessionDetailRoute() {
+ const pathname = useLocation({ select: location => location.pathname })
+ const { sessionId } = useParams({ from: '/sessions/$sessionId' })
+ const basePath = `/sessions/${sessionId}`
+ const isChat = pathname === basePath || pathname === `${basePath}/`
+
+ return isChat ? <SessionPage /> : <Outlet />
}
-// Query sessions with message counts
-function querySessions(db: Database): SessionInfo[] {
- // Get basic session info
- const sessionRows = db.query<
- { id: string; metadata: string | null; updated_at: number; message_count: number },
- []
- >(`
- SELECT
- s.id,
- s.metadata,
+function NewSessionPage() {
+ const { api } = useAppContext()
+ const navigate = useNavigate()
+ const goBack = useAppGoBack()
+ const queryClient = useQueryClient()
+ const { machines, isLoading: machinesLoading, error: machinesError } = useMachines(api, true)
+ const { t } = useTranslation()
+
+ const handleCancel = useCallback(() => {
+ navigate({ to: '/sessions' })
+ }, [navigate])
+
+ const handleSuccess = useCallback((sessionId: string) => {
+ void queryClient.invalidateQueries({ queryKey: queryKeys.sessions })
+ // Replace current page with /sessions to clear spawn flow from history
+ navigate({ to: '/sessions', replace: true })
+ // Then navigate to new session
+ requestAnimationFrame(() => {
+ navigate({
+ to: '/sessions/$sessionId',
+ params: { sessionId },
```
This function is important because it defines how HAPI Tutorial: Remote Control for Local AI Coding Sessions implements the patterns covered in this chapter.
-### `hub/scripts/cleanup-sessions.ts`
-
-The `querySessions` function in [`hub/scripts/cleanup-sessions.ts`](https://github.com/tiann/hapi/blob/HEAD/hub/scripts/cleanup-sessions.ts) handles a key part of this chapter's functionality:
-
-```ts
-
-// Query sessions with message counts
-function querySessions(db: Database): SessionInfo[] {
- // Get basic session info
- const sessionRows = db.query<
- { id: string; metadata: string | null; updated_at: number; message_count: number },
- []
- >(`
- SELECT
- s.id,
- s.metadata,
- s.updated_at,
- COUNT(m.id) as message_count
- FROM sessions s
- LEFT JOIN messages m ON m.session_id = s.id
- GROUP BY s.id
- `).all()
-
- // Get all messages for processing
- const messageRows = db.query<
- { session_id: string; content: string; seq: number },
- []
- >(`
- SELECT session_id, content, seq
- FROM messages
- ORDER BY session_id, seq
- `).all()
-
- // Group messages by session
- const messagesBySession = new Map<string, { content: string; seq: number }[]>()
- for (const msg of messageRows) {
- const list = messagesBySession.get(msg.session_id) ?? []
-```
+### `web/src/router.tsx`
-This function is important because it defines how HAPI Tutorial: Remote Control for Local AI Coding Sessions implements the patterns covered in this chapter.
+The `NewSessionPage` function in [`web/src/router.tsx`](https://github.com/tiann/hapi/blob/HEAD/web/src/router.tsx) handles a key part of this chapter's functionality:
-### `hub/scripts/cleanup-sessions.ts`
-
-The `filterSessions` function in [`hub/scripts/cleanup-sessions.ts`](https://github.com/tiann/hapi/blob/HEAD/hub/scripts/cleanup-sessions.ts) handles a key part of this chapter's functionality:
-
-```ts
-
-// Filter sessions based on criteria
-function filterSessions(
- sessions: SessionInfo[],
- minMessages: number | null,
- pathPattern: string | null,
- messagePattern: string | null,
- orphaned: boolean
-): SessionInfo[] {
- let filtered = sessions
-
- // Filter by message count if specified
- if (minMessages !== null) {
- filtered = filtered.filter(s => s.messageCount < minMessages)
- }
-
- // Filter by path pattern if specified
- if (pathPattern !== null) {
- const glob = new Bun.Glob(pathPattern)
- filtered = filtered.filter(s => {
- if (!s.path) return false
- return glob.match(s.path)
- })
- }
+```tsx
+}
- // Filter by first message pattern (case-insensitive fuzzy match)
- if (messagePattern !== null) {
- filtered = filtered.filter(s => {
- if (!s.firstUserMessage) return false
- return s.firstUserMessage.toLowerCase().includes(messagePattern)
+function NewSessionPage() {
+ const { api } = useAppContext()
+ const navigate = useNavigate()
+ const goBack = useAppGoBack()
+ const queryClient = useQueryClient()
+ const { machines, isLoading: machinesLoading, error: machinesError } = useMachines(api, true)
+ const { t } = useTranslation()
+
+ const handleCancel = useCallback(() => {
+ navigate({ to: '/sessions' })
+ }, [navigate])
+
+ const handleSuccess = useCallback((sessionId: string) => {
+ void queryClient.invalidateQueries({ queryKey: queryKeys.sessions })
+ // Replace current page with /sessions to clear spawn flow from history
+ navigate({ to: '/sessions', replace: true })
+ // Then navigate to new session
+ requestAnimationFrame(() => {
+ navigate({
+ to: '/sessions/$sessionId',
+ params: { sessionId },
+ })
})
- }
+ }, [navigate, queryClient])
+
+ return (
+ <div className="flex h-full min-h-0 flex-col">
+ <div className="flex items-center gap-2 border-b border-[var(--app-border)] bg-[var(--app-bg)] p-3 pt-[calc(0.75rem+env(safe-area-inset-top))]">
+ {!isTelegramApp() && (
+ <button
```
This function is important because it defines how HAPI Tutorial: Remote Control for Local AI Coding Sessions implements the patterns covered in this chapter.
@@ -268,11 +251,11 @@ This function is important because it defines how HAPI Tutorial: Remote Control
```mermaid
flowchart TD
- A[parseArgs]
- B[getDbPath]
- C[querySessions]
- D[filterSessions]
- E[displaySessions]
+ A[SessionsIndexPage]
+ B[SessionPage]
+ C[SessionDetailRoute]
+ D[NewSessionPage]
+ E[createAppRouter]
A --> B
B --> C
C --> D
diff --git a/tutorials/hapi-tutorial/03-session-lifecycle-and-handoff.md b/tutorials/hapi-tutorial/03-session-lifecycle-and-handoff.md
index fb3e5b8f..866dc604 100644
--- a/tutorials/hapi-tutorial/03-session-lifecycle-and-handoff.md
+++ b/tutorials/hapi-tutorial/03-session-lifecycle-and-handoff.md
@@ -70,21 +70,6 @@ Under the hood, `Chapter 3: Session Lifecycle and Handoff` usually follows a rep
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
-## Source Walkthrough
-
-Use the following upstream sources to verify implementation details while reading this chapter:
-
-- [HAPI Repository](https://github.com/tiann/hapi)
- Why it matters: authoritative reference on `HAPI Repository` (github.com).
-- [HAPI Releases](https://github.com/tiann/hapi/releases)
- Why it matters: authoritative reference on `HAPI Releases` (github.com).
-- [HAPI Docs](https://hapi.run)
- Why it matters: authoritative reference on `HAPI Docs` (hapi.run).
-
-Suggested trace strategy:
-- search upstream code for `graph` and `Start` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
-
## Chapter Connections
- [Tutorial Index](README.md)
@@ -93,170 +78,168 @@ Suggested trace strategy:
- [Main Catalog](../../README.md#-tutorial-catalog)
- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `hub/scripts/cleanup-sessions.ts`
-The `deleteSessions` function in [`hub/scripts/cleanup-sessions.ts`](https://github.com/tiann/hapi/blob/HEAD/hub/scripts/cleanup-sessions.ts) handles a key part of this chapter's functionality:
+The `formatDate` function in [`hub/scripts/cleanup-sessions.ts`](https://github.com/tiann/hapi/blob/HEAD/hub/scripts/cleanup-sessions.ts) handles a key part of this chapter's functionality:
```ts
-// Delete sessions by IDs
-function deleteSessions(db: Database, ids: string[]): number {
- if (ids.length === 0) return 0
+// Format timestamp as human-readable date
+function formatDate(timestamp: number): string {
+ const date = new Date(timestamp)
+ return date.toLocaleDateString('en-US', {
+ month: 'short',
+ day: 'numeric',
+ year: 'numeric'
+ })
+}
- const placeholders = ids.map(() => '?').join(', ')
- db.run(`DELETE FROM sessions WHERE id IN (${placeholders})`, ids)
- return ids.length
+// Truncate string to max length with ellipsis
+function truncate(str: string, maxLen: number): string {
+ if (str.length <= maxLen) return str
+ return str.slice(0, maxLen - 3) + '...'
}
-// Main function
-async function main(): Promise<void> {
- const { minMessages, pathPattern, messagePattern, orphaned, force, help } = parseArgs()
-
- if (help) {
- console.log(`
-Usage: bun run hub/scripts/cleanup-sessions.ts [options]
-
-Options:
- --min-messages=N Delete sessions with fewer than N messages (default: 5)
- --path=PATTERN Delete sessions matching path pattern (glob supported)
- --message=PATTERN Delete sessions whose first message contains PATTERN (case-insensitive)
- --orphaned Delete sessions whose path no longer exists
- --force Skip confirmation prompt
- --help Show this help message
-
-Filtering logic:
- - Only --min-messages: Delete sessions with message count < N
- - Only --path: Delete ALL sessions matching the path pattern
- - Only --message: Delete sessions whose first user message contains the pattern
- - Only --orphaned: Delete sessions whose path does not exist on filesystem
- - Multiple filters: Delete sessions matching ALL conditions (AND)
+// Extract text from user message content
+function extractUserText(content: unknown): string | null {
+ if (!content || typeof content !== 'object') return null
+ const c = content as Record<string, unknown>
+ if (c.role !== 'user') return null
+ const inner = c.content
+ // Handle { content: { type: 'text', text: '...' } }
+ if (inner && typeof inner === 'object') {
+ const textObj = inner as Record<string, unknown>
+ if (textObj.type === 'text' && typeof textObj.text === 'string') {
+ return textObj.text
+ }
+ }
+ // Handle { content: '...' } (string)
+ if (typeof inner === 'string') {
```
This function is important because it defines how HAPI Tutorial: Remote Control for Local AI Coding Sessions implements the patterns covered in this chapter.
### `hub/scripts/cleanup-sessions.ts`
-The `main` function in [`hub/scripts/cleanup-sessions.ts`](https://github.com/tiann/hapi/blob/HEAD/hub/scripts/cleanup-sessions.ts) handles a key part of this chapter's functionality:
+The `truncate` function in [`hub/scripts/cleanup-sessions.ts`](https://github.com/tiann/hapi/blob/HEAD/hub/scripts/cleanup-sessions.ts) handles a key part of this chapter's functionality:
```ts
-// Main function
-async function main(): Promise<void> {
- const { minMessages, pathPattern, messagePattern, orphaned, force, help } = parseArgs()
-
- if (help) {
- console.log(`
-Usage: bun run hub/scripts/cleanup-sessions.ts [options]
-
-Options:
- --min-messages=N Delete sessions with fewer than N messages (default: 5)
- --path=PATTERN Delete sessions matching path pattern (glob supported)
- --message=PATTERN Delete sessions whose first message contains PATTERN (case-insensitive)
- --orphaned Delete sessions whose path no longer exists
- --force Skip confirmation prompt
- --help Show this help message
-
-Filtering logic:
- - Only --min-messages: Delete sessions with message count < N
- - Only --path: Delete ALL sessions matching the path pattern
- - Only --message: Delete sessions whose first user message contains the pattern
- - Only --orphaned: Delete sessions whose path does not exist on filesystem
- - Multiple filters: Delete sessions matching ALL conditions (AND)
-
-Examples:
- bun run hub/scripts/cleanup-sessions.ts
- bun run hub/scripts/cleanup-sessions.ts --min-messages=3
- bun run hub/scripts/cleanup-sessions.ts --path="/tmp/*"
- bun run hub/scripts/cleanup-sessions.ts --message="hello"
- bun run hub/scripts/cleanup-sessions.ts --orphaned
- bun run hub/scripts/cleanup-sessions.ts --orphaned --min-messages=5 --force
-`)
+// Truncate string to max length with ellipsis
+function truncate(str: string, maxLen: number): string {
+ if (str.length <= maxLen) return str
+ return str.slice(0, maxLen - 3) + '...'
+}
+
+// Extract text from user message content
+function extractUserText(content: unknown): string | null {
+ if (!content || typeof content !== 'object') return null
+ const c = content as Record<string, unknown>
+ if (c.role !== 'user') return null
+ const inner = c.content
+ // Handle { content: { type: 'text', text: '...' } }
+ if (inner && typeof inner === 'object') {
+ const textObj = inner as Record<string, unknown>
+ if (textObj.type === 'text' && typeof textObj.text === 'string') {
+ return textObj.text
+ }
+ }
+ // Handle { content: '...' } (string)
+ if (typeof inner === 'string') {
+ return inner
+ }
+ return null
+}
+
+// Parse command line arguments
+function parseArgs(): { minMessages: number | null; pathPattern: string | null; messagePattern: string | null; orphaned: boolean; force: boolean; help: boolean } {
+ const args = process.argv.slice(2)
+ let minMessages: number | null = null
+ let pathPattern: string | null = null
```
This function is important because it defines how HAPI Tutorial: Remote Control for Local AI Coding Sessions implements the patterns covered in this chapter.
### `hub/scripts/cleanup-sessions.ts`
-The `SessionInfo` interface in [`hub/scripts/cleanup-sessions.ts`](https://github.com/tiann/hapi/blob/HEAD/hub/scripts/cleanup-sessions.ts) handles a key part of this chapter's functionality:
+The `extractUserText` function in [`hub/scripts/cleanup-sessions.ts`](https://github.com/tiann/hapi/blob/HEAD/hub/scripts/cleanup-sessions.ts) handles a key part of this chapter's functionality:
```ts
-// Session info for display
-interface SessionInfo {
- id: string
- title: string | null
- firstUserMessage: string | null
- path: string | null
- updatedAt: number
- messageCount: number
+// Extract text from user message content
+function extractUserText(content: unknown): string | null {
+ if (!content || typeof content !== 'object') return null
+ const c = content as Record<string, unknown>
+ if (c.role !== 'user') return null
+ const inner = c.content
+ // Handle { content: { type: 'text', text: '...' } }
+ if (inner && typeof inner === 'object') {
+ const textObj = inner as Record<string, unknown>
+ if (textObj.type === 'text' && typeof textObj.text === 'string') {
+ return textObj.text
+ }
+ }
+ // Handle { content: '...' } (string)
+ if (typeof inner === 'string') {
+ return inner
+ }
+ return null
}
-// Query sessions with message counts
-function querySessions(db: Database): SessionInfo[] {
- // Get basic session info
- const sessionRows = db.query<
- { id: string; metadata: string | null; updated_at: number; message_count: number },
- []
- >(`
- SELECT
- s.id,
- s.metadata,
- s.updated_at,
- COUNT(m.id) as message_count
- FROM sessions s
- LEFT JOIN messages m ON m.session_id = s.id
- GROUP BY s.id
- `).all()
-
- // Get all messages for processing
- const messageRows = db.query<
- { session_id: string; content: string; seq: number },
- []
+// Parse command line arguments
+function parseArgs(): { minMessages: number | null; pathPattern: string | null; messagePattern: string | null; orphaned: boolean; force: boolean; help: boolean } {
+ const args = process.argv.slice(2)
+ let minMessages: number | null = null
+ let pathPattern: string | null = null
+ let messagePattern: string | null = null
+ let orphaned = false
+ let force = false
+ let help = false
+
+ for (const arg of args) {
```
-This interface is important because it defines how HAPI Tutorial: Remote Control for Local AI Coding Sessions implements the patterns covered in this chapter.
-
-### `web/src/router.tsx`
-
-The `BackIcon` function in [`web/src/router.tsx`](https://github.com/tiann/hapi/blob/HEAD/web/src/router.tsx) handles a key part of this chapter's functionality:
-
-```tsx
-import SettingsPage from '@/routes/settings'
-
-function BackIcon(props: { className?: string }) {
- return (
- <svg
- xmlns="http://www.w3.org/2000/svg"
- width="20"
- height="20"
- viewBox="0 0 24 24"
- fill="none"
- stroke="currentColor"
- strokeWidth="2"
- strokeLinecap="round"
- strokeLinejoin="round"
- className={props.className}
- >
- <polyline points="15 18 9 12 15 6" />
- </svg>
- )
-}
+This function is important because it defines how HAPI Tutorial: Remote Control for Local AI Coding Sessions implements the patterns covered in this chapter.
+
+### `hub/scripts/cleanup-sessions.ts`
+
+The `parseArgs` function in [`hub/scripts/cleanup-sessions.ts`](https://github.com/tiann/hapi/blob/HEAD/hub/scripts/cleanup-sessions.ts) handles a key part of this chapter's functionality:
+
+```ts
-function PlusIcon(props: { className?: string }) {
- return (
- <svg
- xmlns="http://www.w3.org/2000/svg"
- width="24"
- height="24"
- viewBox="0 0 24 24"
- fill="none"
- stroke="currentColor"
- strokeWidth="2"
- strokeLinecap="round"
+// Parse command line arguments
+function parseArgs(): { minMessages: number | null; pathPattern: string | null; messagePattern: string | null; orphaned: boolean; force: boolean; help: boolean } {
+ const args = process.argv.slice(2)
+ let minMessages: number | null = null
+ let pathPattern: string | null = null
+ let messagePattern: string | null = null
+ let orphaned = false
+ let force = false
+ let help = false
+
+ for (const arg of args) {
+ if (arg === '--help' || arg === '-h') {
+ help = true
+ } else if (arg === '--force' || arg === '-f') {
+ force = true
+ } else if (arg === '--orphaned') {
+ orphaned = true
+ } else if (arg.startsWith('--min-messages=')) {
+ const value = parseInt(arg.split('=')[1], 10)
+ if (isNaN(value) || value < 0) {
+ console.error('Error: --min-messages must be a non-negative integer')
+ process.exit(1)
+ }
+ minMessages = value
+ } else if (arg.startsWith('--path=')) {
+ pathPattern = arg.split('=').slice(1).join('=') // Handle paths with '='
+ } else if (arg.startsWith('--message=')) {
+ messagePattern = arg.split('=').slice(1).join('=').toLowerCase()
+ } else {
+ console.error(`Unknown argument: ${arg}`)
+ console.error('Use --help for usage information')
```
This function is important because it defines how HAPI Tutorial: Remote Control for Local AI Coding Sessions implements the patterns covered in this chapter.
@@ -266,11 +249,11 @@ This function is important because it defines how HAPI Tutorial: Remote Control
```mermaid
flowchart TD
- A[deleteSessions]
- B[main]
- C[SessionInfo]
- D[BackIcon]
- E[PlusIcon]
+ A[formatDate]
+ B[truncate]
+ C[extractUserText]
+ D[parseArgs]
+ E[getDbPath]
A --> B
B --> C
C --> D
diff --git a/tutorials/hapi-tutorial/04-remote-access-and-networking.md b/tutorials/hapi-tutorial/04-remote-access-and-networking.md
index a262b13d..4b2d6831 100644
--- a/tutorials/hapi-tutorial/04-remote-access-and-networking.md
+++ b/tutorials/hapi-tutorial/04-remote-access-and-networking.md
@@ -68,17 +68,6 @@ Under the hood, `Chapter 4: Remote Access and Networking` usually follows a repe
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
-## Source Walkthrough
-
-Use the following upstream sources to verify implementation details while reading this chapter:
-
-- [HAPI Repository](https://github.com/tiann/hapi)
- Why it matters: authoritative reference on `HAPI Repository` (github.com).
-- [HAPI Releases](https://github.com/tiann/hapi/releases)
- Why it matters: authoritative reference on `HAPI Releases` (github.com).
-- [HAPI Docs](https://hapi.run)
- Why it matters: authoritative reference on `HAPI Docs` (hapi.run).
-
## Chapter Connections
- [Tutorial Index](README.md)
@@ -87,170 +76,168 @@ Use the following upstream sources to verify implementation details while readin
- [Main Catalog](../../README.md#-tutorial-catalog)
- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `web/src/router.tsx`
-
-The `SessionsPage` function in [`web/src/router.tsx`](https://github.com/tiann/hapi/blob/HEAD/web/src/router.tsx) handles a key part of this chapter's functionality:
-
-```tsx
-}
-
-function SessionsPage() {
- const { api } = useAppContext()
- const navigate = useNavigate()
- const pathname = useLocation({ select: location => location.pathname })
- const matchRoute = useMatchRoute()
- const { t } = useTranslation()
- const { sessions, isLoading, error, refetch } = useSessions(api)
-
- const handleRefresh = useCallback(() => {
- void refetch()
- }, [refetch])
-
- const projectCount = new Set(sessions.map(s => s.metadata?.worktree?.basePath ?? s.metadata?.path ?? 'Other')).size
- const sessionMatch = matchRoute({ to: '/sessions/$sessionId', fuzzy: true })
- const selectedSessionId = sessionMatch && sessionMatch.sessionId !== 'new' ? sessionMatch.sessionId : null
- const isSessionsIndex = pathname === '/sessions' || pathname === '/sessions/'
-
- return (
- <div className="flex h-full min-h-0">
- <div
- className={`${isSessionsIndex ? 'flex' : 'hidden lg:flex'} w-full lg:w-[420px] xl:w-[480px] shrink-0 flex-col bg-[var(--app-bg)] lg:border-r lg:border-[var(--app-divider)]`}
- >
- <div className="bg-[var(--app-bg)] pt-[env(safe-area-inset-top)]">
- <div className="mx-auto w-full max-w-content flex items-center justify-between px-3 py-2">
- <div className="text-xs text-[var(--app-hint)]">
- {t('sessions.count', { n: sessions.length, m: projectCount })}
- </div>
- <div className="flex items-center gap-2">
- <button
- type="button"
+### `hub/scripts/cleanup-sessions.ts`
+
+The `filterSessions` function in [`hub/scripts/cleanup-sessions.ts`](https://github.com/tiann/hapi/blob/HEAD/hub/scripts/cleanup-sessions.ts) handles a key part of this chapter's functionality:
+
+```ts
+
+// Filter sessions based on criteria
+function filterSessions(
+ sessions: SessionInfo[],
+ minMessages: number | null,
+ pathPattern: string | null,
+ messagePattern: string | null,
+ orphaned: boolean
+): SessionInfo[] {
+ let filtered = sessions
+
+ // Filter by message count if specified
+ if (minMessages !== null) {
+ filtered = filtered.filter(s => s.messageCount < minMessages)
+ }
+
+ // Filter by path pattern if specified
+ if (pathPattern !== null) {
+ const glob = new Bun.Glob(pathPattern)
+ filtered = filtered.filter(s => {
+ if (!s.path) return false
+ return glob.match(s.path)
+ })
+ }
+
+ // Filter by first message pattern (case-insensitive fuzzy match)
+ if (messagePattern !== null) {
+ filtered = filtered.filter(s => {
+ if (!s.firstUserMessage) return false
+ return s.firstUserMessage.toLowerCase().includes(messagePattern)
+ })
+ }
```
This function is important because it defines how HAPI Tutorial: Remote Control for Local AI Coding Sessions implements the patterns covered in this chapter.
-### `web/src/router.tsx`
-
-The `SessionsIndexPage` function in [`web/src/router.tsx`](https://github.com/tiann/hapi/blob/HEAD/web/src/router.tsx) handles a key part of this chapter's functionality:
-
-```tsx
-}
-
-function SessionsIndexPage() {
- return null
-}
-
-function SessionPage() {
- const { api } = useAppContext()
- const { t } = useTranslation()
- const goBack = useAppGoBack()
- const navigate = useNavigate()
- const queryClient = useQueryClient()
- const { addToast } = useToast()
- const { sessionId } = useParams({ from: '/sessions/$sessionId' })
- const {
- session,
- refetch: refetchSession,
- } = useSession(api, sessionId)
- const {
- messages,
- warning: messagesWarning,
- isLoading: messagesLoading,
- isLoadingMore: messagesLoadingMore,
- hasMore: messagesHasMore,
- loadMore: loadMoreMessages,
- refetch: refetchMessages,
- pendingCount,
- messagesVersion,
- flushPending,
- setAtBottom,
- } = useMessages(api, sessionId)
- const {
+### `hub/scripts/cleanup-sessions.ts`
+
+The `displaySessions` function in [`hub/scripts/cleanup-sessions.ts`](https://github.com/tiann/hapi/blob/HEAD/hub/scripts/cleanup-sessions.ts) handles a key part of this chapter's functionality:
+
+```ts
+
+// Display sessions in a table format
+function displaySessions(sessions: SessionInfo[]): void {
+ if (sessions.length === 0) {
+ console.log('No sessions match the criteria.')
+ return
+ }
+
+ // Fixed column widths for readability
+ const dateWidth = 12
+ const countWidth = 4
+ const titleWidth = 25
+ const messageWidth = 30
+ const pathWidth = 30
+
+ // Header
+ const header = [
+ 'Updated'.padEnd(dateWidth),
+ 'Msgs'.padStart(countWidth),
+ 'Title'.padEnd(titleWidth),
+ 'First Message'.padEnd(messageWidth),
+ 'Path'.padEnd(pathWidth),
+ ].join(' | ')
+ console.log(header)
+ console.log('-'.repeat(header.length))
+
+ // Rows
+ for (const s of sessions) {
+ const updated = formatDate(s.updatedAt)
+ const title = truncate(s.title ?? '(no title)', titleWidth)
+ const firstMsg = truncate(s.firstUserMessage ?? '(no message)', messageWidth)
+ const path = truncate(s.path ?? '', pathWidth)
```
This function is important because it defines how HAPI Tutorial: Remote Control for Local AI Coding Sessions implements the patterns covered in this chapter.
-### `web/src/router.tsx`
-
-The `SessionPage` function in [`web/src/router.tsx`](https://github.com/tiann/hapi/blob/HEAD/web/src/router.tsx) handles a key part of this chapter's functionality:
-
-```tsx
+### `hub/scripts/cleanup-sessions.ts`
+
+The `confirm` function in [`hub/scripts/cleanup-sessions.ts`](https://github.com/tiann/hapi/blob/HEAD/hub/scripts/cleanup-sessions.ts) handles a key part of this chapter's functionality:
+
+```ts
+ * --message=PATTERN Delete sessions whose first message contains PATTERN (case-insensitive)
+ * --orphaned Delete sessions whose path no longer exists
+ * --force Skip confirmation prompt
+ * --help Show this help message
+ *
+ * Examples:
+ * bun run hub/scripts/cleanup-sessions.ts
+ * bun run hub/scripts/cleanup-sessions.ts --min-messages=3
+ * bun run hub/scripts/cleanup-sessions.ts --path="/tmp/*"
+ * bun run hub/scripts/cleanup-sessions.ts --message="hello"
+ * bun run hub/scripts/cleanup-sessions.ts --orphaned
+ * bun run hub/scripts/cleanup-sessions.ts --orphaned --min-messages=5 --force
+ */
+
+import { Database } from 'bun:sqlite'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { existsSync } from 'node:fs'
+
+// Format timestamp as human-readable date
+function formatDate(timestamp: number): string {
+ const date = new Date(timestamp)
+ return date.toLocaleDateString('en-US', {
+ month: 'short',
+ day: 'numeric',
+ year: 'numeric'
+ })
}
-function SessionPage() {
- const { api } = useAppContext()
- const { t } = useTranslation()
- const goBack = useAppGoBack()
- const navigate = useNavigate()
- const queryClient = useQueryClient()
- const { addToast } = useToast()
- const { sessionId } = useParams({ from: '/sessions/$sessionId' })
- const {
- session,
- refetch: refetchSession,
- } = useSession(api, sessionId)
- const {
- messages,
- warning: messagesWarning,
- isLoading: messagesLoading,
- isLoadingMore: messagesLoadingMore,
- hasMore: messagesHasMore,
- loadMore: loadMoreMessages,
- refetch: refetchMessages,
- pendingCount,
- messagesVersion,
- flushPending,
- setAtBottom,
- } = useMessages(api, sessionId)
- const {
- sendMessage,
- retryMessage,
- isSending,
- } = useSendMessage(api, sessionId, {
+// Truncate string to max length with ellipsis
+function truncate(str: string, maxLen: number): string {
+ if (str.length <= maxLen) return str
```
This function is important because it defines how HAPI Tutorial: Remote Control for Local AI Coding Sessions implements the patterns covered in this chapter.
-### `web/src/router.tsx`
+### `hub/scripts/cleanup-sessions.ts`
-The `SessionDetailRoute` function in [`web/src/router.tsx`](https://github.com/tiann/hapi/blob/HEAD/web/src/router.tsx) handles a key part of this chapter's functionality:
+The `deleteSessions` function in [`hub/scripts/cleanup-sessions.ts`](https://github.com/tiann/hapi/blob/HEAD/hub/scripts/cleanup-sessions.ts) handles a key part of this chapter's functionality:
-```tsx
-}
+```ts
-function SessionDetailRoute() {
- const pathname = useLocation({ select: location => location.pathname })
- const { sessionId } = useParams({ from: '/sessions/$sessionId' })
- const basePath = `/sessions/${sessionId}`
- const isChat = pathname === basePath || pathname === `${basePath}/`
+// Delete sessions by IDs
+function deleteSessions(db: Database, ids: string[]): number {
+ if (ids.length === 0) return 0
- return isChat ? <SessionPage /> : <Outlet />
+ const placeholders = ids.map(() => '?').join(', ')
+ db.run(`DELETE FROM sessions WHERE id IN (${placeholders})`, ids)
+ return ids.length
}
-function NewSessionPage() {
- const { api } = useAppContext()
- const navigate = useNavigate()
- const goBack = useAppGoBack()
- const queryClient = useQueryClient()
- const { machines, isLoading: machinesLoading, error: machinesError } = useMachines(api, true)
- const { t } = useTranslation()
-
- const handleCancel = useCallback(() => {
- navigate({ to: '/sessions' })
- }, [navigate])
-
- const handleSuccess = useCallback((sessionId: string) => {
- void queryClient.invalidateQueries({ queryKey: queryKeys.sessions })
- // Replace current page with /sessions to clear spawn flow from history
- navigate({ to: '/sessions', replace: true })
- // Then navigate to new session
- requestAnimationFrame(() => {
- navigate({
- to: '/sessions/$sessionId',
- params: { sessionId },
+// Main function
+async function main(): Promise<void> {
+ const { minMessages, pathPattern, messagePattern, orphaned, force, help } = parseArgs()
+
+ if (help) {
+ console.log(`
+Usage: bun run hub/scripts/cleanup-sessions.ts [options]
+
+Options:
+ --min-messages=N Delete sessions with fewer than N messages (default: 5)
+ --path=PATTERN Delete sessions matching path pattern (glob supported)
+ --message=PATTERN Delete sessions whose first message contains PATTERN (case-insensitive)
+ --orphaned Delete sessions whose path no longer exists
+ --force Skip confirmation prompt
+ --help Show this help message
+
+Filtering logic:
+ - Only --min-messages: Delete sessions with message count < N
+ - Only --path: Delete ALL sessions matching the path pattern
+ - Only --message: Delete sessions whose first user message contains the pattern
+ - Only --orphaned: Delete sessions whose path does not exist on filesystem
+ - Multiple filters: Delete sessions matching ALL conditions (AND)
```
This function is important because it defines how HAPI Tutorial: Remote Control for Local AI Coding Sessions implements the patterns covered in this chapter.
@@ -260,11 +247,11 @@ This function is important because it defines how HAPI Tutorial: Remote Control
```mermaid
flowchart TD
- A[SessionsPage]
- B[SessionsIndexPage]
- C[SessionPage]
- D[SessionDetailRoute]
- E[NewSessionPage]
+ A[filterSessions]
+ B[displaySessions]
+ C[confirm]
+ D[deleteSessions]
+ E[main]
A --> B
B --> C
C --> D
diff --git a/tutorials/hapi-tutorial/05-permissions-and-approval-workflow.md b/tutorials/hapi-tutorial/05-permissions-and-approval-workflow.md
index c930808e..b5ac0fc7 100644
--- a/tutorials/hapi-tutorial/05-permissions-and-approval-workflow.md
+++ b/tutorials/hapi-tutorial/05-permissions-and-approval-workflow.md
@@ -68,17 +68,6 @@ Under the hood, `Chapter 5: Permissions and Approval Workflow` usually follows a
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
-## Source Walkthrough
-
-Use the following upstream sources to verify implementation details while reading this chapter:
-
-- [HAPI Repository](https://github.com/tiann/hapi)
- Why it matters: authoritative reference on `HAPI Repository` (github.com).
-- [HAPI Releases](https://github.com/tiann/hapi/releases)
- Why it matters: authoritative reference on `HAPI Releases` (github.com).
-- [HAPI Docs](https://hapi.run)
- Why it matters: authoritative reference on `HAPI Docs` (hapi.run).
-
## Chapter Connections
- [Tutorial Index](README.md)
@@ -87,145 +76,168 @@ Use the following upstream sources to verify implementation details while readin
- [Main Catalog](../../README.md#-tutorial-catalog)
- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `web/src/router.tsx`
+### `cli/src/persistence.ts`
+
+The `readSettings` function in [`cli/src/persistence.ts`](https://github.com/tiann/hapi/blob/HEAD/cli/src/persistence.ts) handles a key part of this chapter's functionality:
-The `Register` interface in [`web/src/router.tsx`](https://github.com/tiann/hapi/blob/HEAD/web/src/router.tsx) handles a key part of this chapter's functionality:
+```ts
+}
+
+export async function readSettings(): Promise<Settings> {
+ if (!existsSync(configuration.settingsFile)) {
+ return { ...defaultSettings }
+ }
+
+ try {
+ const content = await readFile(configuration.settingsFile, 'utf8')
+ return JSON.parse(content)
+ } catch {
+ return { ...defaultSettings }
+ }
+}
-```tsx
+export async function writeSettings(settings: Settings): Promise<void> {
+ if (!existsSync(configuration.happyHomeDir)) {
+ await mkdir(configuration.happyHomeDir, { recursive: true })
+ }
-declare module '@tanstack/react-router' {
- interface Register {
- router: AppRouter
- }
+ await writeFile(configuration.settingsFile, JSON.stringify(settings, null, 2))
}
+/**
+ * Atomically update settings with multi-process safety via file locking
+ * @param updater Function that takes current settings and returns updated settings
+ * @returns The updated settings
+ */
+export async function updateSettings(
+ updater: (current: Settings) => Settings | Promise<Settings>
+): Promise<Settings> {
+ // Timing constants
```
-This interface is important because it defines how HAPI Tutorial: Remote Control for Local AI Coding Sessions implements the patterns covered in this chapter.
+This function is important because it defines how HAPI Tutorial: Remote Control for Local AI Coding Sessions implements the patterns covered in this chapter.
-### `hub/src/index.ts`
+### `cli/src/persistence.ts`
-The `formatSource` function in [`hub/src/index.ts`](https://github.com/tiann/hapi/blob/HEAD/hub/src/index.ts) handles a key part of this chapter's functionality:
+The `writeSettings` function in [`cli/src/persistence.ts`](https://github.com/tiann/hapi/blob/HEAD/cli/src/persistence.ts) handles a key part of this chapter's functionality:
```ts
-
-/** Format config source for logging */
-function formatSource(source: ConfigSource | 'generated'): string {
- switch (source) {
- case 'env':
- return 'environment'
- case 'file':
- return 'settings.json'
- case 'default':
- return 'default'
- case 'generated':
- return 'generated'
- }
}
-type RelayFlagSource = 'default' | '--relay' | '--no-relay'
+export async function writeSettings(settings: Settings): Promise<void> {
+ if (!existsSync(configuration.happyHomeDir)) {
+ await mkdir(configuration.happyHomeDir, { recursive: true })
+ }
-function resolveRelayFlag(args: string[]): { enabled: boolean; source: RelayFlagSource } {
- let enabled = false
- let source: RelayFlagSource = 'default'
+ await writeFile(configuration.settingsFile, JSON.stringify(settings, null, 2))
+}
- for (const arg of args) {
- if (arg === '--relay') {
- enabled = true
- source = '--relay'
- } else if (arg === '--no-relay') {
- enabled = false
- source = '--no-relay'
- }
- }
+/**
+ * Atomically update settings with multi-process safety via file locking
+ * @param updater Function that takes current settings and returns updated settings
+ * @returns The updated settings
+ */
+export async function updateSettings(
+ updater: (current: Settings) => Settings | Promise<Settings>
+): Promise<Settings> {
+ // Timing constants
+ const LOCK_RETRY_INTERVAL_MS = 100; // How long to wait between lock attempts
+ const MAX_LOCK_ATTEMPTS = 50; // Maximum number of attempts (5 seconds total)
+ const STALE_LOCK_TIMEOUT_MS = 10000; // Consider lock stale after 10 seconds
+
+ if (!existsSync(configuration.happyHomeDir)) {
+ await mkdir(configuration.happyHomeDir, { recursive: true });
+ }
+
+ const lockFile = configuration.settingsFile + '.lock';
+ const tmpFile = configuration.settingsFile + '.tmp';
+ let fileHandle;
+ let attempts = 0;
- return { enabled, source }
```
This function is important because it defines how HAPI Tutorial: Remote Control for Local AI Coding Sessions implements the patterns covered in this chapter.
-### `hub/src/index.ts`
+### `cli/src/persistence.ts`
-The `resolveRelayFlag` function in [`hub/src/index.ts`](https://github.com/tiann/hapi/blob/HEAD/hub/src/index.ts) handles a key part of this chapter's functionality:
+The `updateSettings` function in [`cli/src/persistence.ts`](https://github.com/tiann/hapi/blob/HEAD/cli/src/persistence.ts) handles a key part of this chapter's functionality:
```ts
-type RelayFlagSource = 'default' | '--relay' | '--no-relay'
-
-function resolveRelayFlag(args: string[]): { enabled: boolean; source: RelayFlagSource } {
- let enabled = false
- let source: RelayFlagSource = 'default'
-
- for (const arg of args) {
- if (arg === '--relay') {
- enabled = true
- source = '--relay'
- } else if (arg === '--no-relay') {
- enabled = false
- source = '--no-relay'
- }
- }
-
- return { enabled, source }
-}
-
-function normalizeOrigin(value: string): string {
- const trimmed = value.trim()
- if (!trimmed) {
- return ''
- }
+ * @returns The updated settings
+ */
+export async function updateSettings(
+ updater: (current: Settings) => Settings | Promise<Settings>
+): Promise<Settings> {
+ // Timing constants
+ const LOCK_RETRY_INTERVAL_MS = 100; // How long to wait between lock attempts
+ const MAX_LOCK_ATTEMPTS = 50; // Maximum number of attempts (5 seconds total)
+ const STALE_LOCK_TIMEOUT_MS = 10000; // Consider lock stale after 10 seconds
+
+ if (!existsSync(configuration.happyHomeDir)) {
+ await mkdir(configuration.happyHomeDir, { recursive: true });
+ }
+
+ const lockFile = configuration.settingsFile + '.lock';
+ const tmpFile = configuration.settingsFile + '.tmp';
+ let fileHandle;
+ let attempts = 0;
+
+ // Acquire exclusive lock with retries
+ while (attempts < MAX_LOCK_ATTEMPTS) {
try {
- return new URL(trimmed).origin
- } catch {
- return trimmed
- }
-}
-
-function normalizeOrigins(origins: string[]): string[] {
+ // 'wx' = create exclusively, fail if exists (cross-platform compatible)
+ fileHandle = await open(lockFile, 'wx');
+ break;
+ } catch (err: any) {
+ if (err.code === 'EEXIST') {
+ // Lock file exists, wait and retry
+ attempts++;
+ await new Promise(resolve => setTimeout(resolve, LOCK_RETRY_INTERVAL_MS));
+
+ // Check for stale lock
```
This function is important because it defines how HAPI Tutorial: Remote Control for Local AI Coding Sessions implements the patterns covered in this chapter.
-### `hub/src/index.ts`
+### `cli/src/persistence.ts`
-The `normalizeOrigin` function in [`hub/src/index.ts`](https://github.com/tiann/hapi/blob/HEAD/hub/src/index.ts) handles a key part of this chapter's functionality:
+The `writeCredentialsDataKey` function in [`cli/src/persistence.ts`](https://github.com/tiann/hapi/blob/HEAD/cli/src/persistence.ts) handles a key part of this chapter's functionality:
```ts
+//
+
+export async function writeCredentialsDataKey(credentials: { publicKey: Uint8Array, machineKey: Uint8Array, token: string }): Promise<void> {
+ if (!existsSync(configuration.happyHomeDir)) {
+ await mkdir(configuration.happyHomeDir, { recursive: true })
+ }
+ await writeFile(configuration.privateKeyFile, JSON.stringify({
+ encryption: { publicKey: Buffer.from(credentials.publicKey).toString('base64'), machineKey: Buffer.from(credentials.machineKey).toString('base64') },
+ token: credentials.token
+ }, null, 2));
}
-function normalizeOrigin(value: string): string {
- const trimmed = value.trim()
- if (!trimmed) {
- return ''
- }
- try {
- return new URL(trimmed).origin
- } catch {
- return trimmed
- }
+export async function clearCredentials(): Promise<void> {
+ if (existsSync(configuration.privateKeyFile)) {
+ await unlink(configuration.privateKeyFile);
+ }
}
-function normalizeOrigins(origins: string[]): string[] {
- const normalized = origins
- .map(normalizeOrigin)
- .filter(Boolean)
- if (normalized.includes('*')) {
- return ['*']
- }
- return Array.from(new Set(normalized))
+export async function clearMachineId(): Promise<void> {
+ await updateSettings(settings => ({
+ ...settings,
+ machineId: undefined
+ }));
}
-function mergeCorsOrigins(base: string[], extra: string[]): string[] {
- if (base.includes('*') || extra.includes('*')) {
- return ['*']
- }
- const merged = new Set<string>()
- for (const origin of base) {
- merged.add(origin)
- }
+/**
+ * Read runner state from local file
+ */
+export async function readRunnerState(): Promise<RunnerLocallyPersistedState | null> {
+ try {
+ if (!existsSync(configuration.runnerStateFile)) {
+ return null;
```
This function is important because it defines how HAPI Tutorial: Remote Control for Local AI Coding Sessions implements the patterns covered in this chapter.
@@ -235,11 +247,11 @@ This function is important because it defines how HAPI Tutorial: Remote Control
```mermaid
flowchart TD
- A[Register]
- B[formatSource]
- C[resolveRelayFlag]
- D[normalizeOrigin]
- E[normalizeOrigins]
+ A[readSettings]
+ B[writeSettings]
+ C[updateSettings]
+ D[writeCredentialsDataKey]
+ E[clearCredentials]
A --> B
B --> C
C --> D
diff --git a/tutorials/hapi-tutorial/06-pwa-telegram-and-extensions.md b/tutorials/hapi-tutorial/06-pwa-telegram-and-extensions.md
index 70db70ed..9f940bed 100644
--- a/tutorials/hapi-tutorial/06-pwa-telegram-and-extensions.md
+++ b/tutorials/hapi-tutorial/06-pwa-telegram-and-extensions.md
@@ -64,17 +64,6 @@ Under the hood, `Chapter 6: PWA, Telegram, and Extensions` usually follows a rep
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
-## Source Walkthrough
-
-Use the following upstream sources to verify implementation details while reading this chapter:
-
-- [HAPI Repository](https://github.com/tiann/hapi)
- Why it matters: authoritative reference on `HAPI Repository` (github.com).
-- [HAPI Releases](https://github.com/tiann/hapi/releases)
- Why it matters: authoritative reference on `HAPI Releases` (github.com).
-- [HAPI Docs](https://hapi.run)
- Why it matters: authoritative reference on `HAPI Docs` (hapi.run).
-
## Chapter Connections
- [Tutorial Index](README.md)
@@ -83,183 +72,182 @@ Use the following upstream sources to verify implementation details while readin
- [Main Catalog](../../README.md#-tutorial-catalog)
- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `hub/src/index.ts`
+### `cli/src/persistence.ts`
-The `main` function in [`hub/src/index.ts`](https://github.com/tiann/hapi/blob/HEAD/hub/src/index.ts) handles a key part of this chapter's functionality:
+The `readRunnerState` function in [`cli/src/persistence.ts`](https://github.com/tiann/hapi/blob/HEAD/cli/src/persistence.ts) handles a key part of this chapter's functionality:
```ts
-let tunnelManager: TunnelManager | null = null
-
-async function main() {
- console.log('HAPI Hub starting...')
-
- // Load configuration (async - loads from env/file with persistence)
- const relayApiDomain = process.env.HAPI_RELAY_API || 'relay.hapi.run'
- const relayFlag = resolveRelayFlag(process.argv)
- const officialWebUrl = process.env.HAPI_OFFICIAL_WEB_URL || 'https://app.hapi.run'
- const config = await createConfiguration()
- const baseCorsOrigins = normalizeOrigins(config.corsOrigins)
- const relayCorsOrigin = normalizeOrigin(officialWebUrl)
- const corsOrigins = relayFlag.enabled
- ? mergeCorsOrigins(baseCorsOrigins, relayCorsOrigin ? [relayCorsOrigin] : [])
- : baseCorsOrigins
-
- // Display CLI API token information
- if (config.cliApiTokenIsNew) {
- console.log('')
- console.log('='.repeat(70))
- console.log(' NEW CLI_API_TOKEN GENERATED')
- console.log('='.repeat(70))
- console.log('')
- console.log(` Token: ${config.cliApiToken}`)
- console.log('')
- console.log(` Saved to: ${config.settingsFile}`)
- console.log('')
- console.log('='.repeat(70))
- console.log('')
- } else {
- console.log(`[Hub] CLI_API_TOKEN: loaded from ${formatSource(config.sources.cliApiToken)}`)
+ * Read runner state from local file
+ */
+export async function readRunnerState(): Promise<RunnerLocallyPersistedState | null> {
+ try {
+ if (!existsSync(configuration.runnerStateFile)) {
+ return null;
}
+ const content = await readFile(configuration.runnerStateFile, 'utf-8');
+ return JSON.parse(content) as RunnerLocallyPersistedState;
+ } catch (error) {
+ // State corrupted somehow :(
+ console.error(`[PERSISTENCE] Runner state file corrupted: ${configuration.runnerStateFile}`, error);
+ return null;
+ }
+}
+
+/**
+ * Write runner state to local file (synchronously for atomic operation)
+ */
+export function writeRunnerState(state: RunnerLocallyPersistedState): void {
+ writeFileSync(configuration.runnerStateFile, JSON.stringify(state, null, 2), 'utf-8');
+}
+
+/**
+ * Clean up runner state file and lock file
+ */
+export async function clearRunnerState(): Promise<void> {
+ if (existsSync(configuration.runnerStateFile)) {
+ await unlink(configuration.runnerStateFile);
+ }
+ // Also clean up lock file if it exists (for stale cleanup)
+ if (existsSync(configuration.runnerLockFile)) {
```
This function is important because it defines how HAPI Tutorial: Remote Control for Local AI Coding Sessions implements the patterns covered in this chapter.
-### `shared/src/voice.ts`
+### `cli/src/persistence.ts`
-The `engineering` class in [`shared/src/voice.ts`](https://github.com/tiann/hapi/blob/HEAD/shared/src/voice.ts) handles a key part of this chapter's functionality:
+The `writeRunnerState` function in [`cli/src/persistence.ts`](https://github.com/tiann/hapi/blob/HEAD/cli/src/persistence.ts) handles a key part of this chapter's functionality:
```ts
-You are Hapi Voice Assistant. You bridge voice communication between users and their AI coding agents in the Hapi ecosystem.
-
-You are friendly, proactive, and highly intelligent with a world-class engineering background. Your approach is warm, witty, and relaxed, balancing professionalism with an approachable vibe.
-
-# Environment Overview
-
-Hapi is a multi-agent development platform supporting:
-- **Claude Code** - Anthropic's coding assistant (primary)
-- **Codex** - OpenAI's coding agent
-- **Gemini** - Google's coding agent
-
-Users control these agents through the Hapi web interface or Telegram Mini App. You serve as the voice interface to whichever agent is currently active.
-
-# How Context Updates Work
-
-You receive automatic context updates when:
-- A session becomes focused (you see the full session history)
-- The agent sends messages or uses tools
-- Permission requests arrive
-- The agent finishes working (ready event)
-
-These updates appear as system messages. You do NOT need to poll or ask for updates. Simply wait for them and summarize when relevant.
-
-# Tools
+ * Write runner state to local file (synchronously for atomic operation)
+ */
+export function writeRunnerState(state: RunnerLocallyPersistedState): void {
+ writeFileSync(configuration.runnerStateFile, JSON.stringify(state, null, 2), 'utf-8');
+}
-## messageCodingAgent
-Send user requests to the active coding agent.
+/**
+ * Clean up runner state file and lock file
+ */
+export async function clearRunnerState(): Promise<void> {
+ if (existsSync(configuration.runnerStateFile)) {
+ await unlink(configuration.runnerStateFile);
+ }
+ // Also clean up lock file if it exists (for stale cleanup)
+ if (existsSync(configuration.runnerLockFile)) {
+ try {
+ await unlink(configuration.runnerLockFile);
+ } catch {
+ // Lock file might be held by running runner, ignore error
+ }
+ }
+}
-When to use:
-- User says "ask Claude to..." or "have it..."
-- Any coding, file, or development request
-- User wants to continue a task
+/**
+ * Acquire an exclusive lock file for the runner.
+ * The lock file proves the runner is running and prevents multiple instances.
+ * Returns the file handle to hold for the runner's lifetime, or null if locked.
+ */
+export async function acquireRunnerLock(
+ maxAttempts: number = 5,
+ delayIncrementMs: number = 200
+): Promise<FileHandle | null> {
```
-This class is important because it defines how HAPI Tutorial: Remote Control for Local AI Coding Sessions implements the patterns covered in this chapter.
+This function is important because it defines how HAPI Tutorial: Remote Control for Local AI Coding Sessions implements the patterns covered in this chapter.
-### `shared/src/voice.ts`
+### `cli/src/persistence.ts`
-The `buildVoiceAgentConfig` function in [`shared/src/voice.ts`](https://github.com/tiann/hapi/blob/HEAD/shared/src/voice.ts) handles a key part of this chapter's functionality:
+The `clearRunnerState` function in [`cli/src/persistence.ts`](https://github.com/tiann/hapi/blob/HEAD/cli/src/persistence.ts) handles a key part of this chapter's functionality:
```ts
- * Used by both server-side auto-creation and client-side configuration.
+ * Clean up runner state file and lock file
*/
-export function buildVoiceAgentConfig(): VoiceAgentConfig {
- return {
- name: VOICE_AGENT_NAME,
- conversation_config: {
- agent: {
- first_message: VOICE_FIRST_MESSAGE,
- language: 'en',
- prompt: {
- prompt: VOICE_SYSTEM_PROMPT,
- llm: 'gemini-2.5-flash',
- temperature: 0.7,
- max_tokens: 1024,
- tools: VOICE_TOOLS
- }
- },
- turn: {
- turn_timeout: 30.0,
- silence_end_call_timeout: 600.0
- },
- tts: {
- voice_id: 'cgSgspJ2msm6clMCkdW9', // Jessica
- model_id: 'eleven_flash_v2',
- speed: 1.1
- }
- },
- // Enable runtime overrides for language selection
- // See: https://elevenlabs.io/docs/agents-platform/customization/personalization/overrides
- platform_settings: {
- overrides: {
- conversation_config_override: {
+export async function clearRunnerState(): Promise<void> {
+ if (existsSync(configuration.runnerStateFile)) {
+ await unlink(configuration.runnerStateFile);
+ }
+ // Also clean up lock file if it exists (for stale cleanup)
+ if (existsSync(configuration.runnerLockFile)) {
+ try {
+ await unlink(configuration.runnerLockFile);
+ } catch {
+ // Lock file might be held by running runner, ignore error
+ }
+ }
+}
+
+/**
+ * Acquire an exclusive lock file for the runner.
+ * The lock file proves the runner is running and prevents multiple instances.
+ * Returns the file handle to hold for the runner's lifetime, or null if locked.
+ */
+export async function acquireRunnerLock(
+ maxAttempts: number = 5,
+ delayIncrementMs: number = 200
+): Promise<FileHandle | null> {
+ for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+ try {
+ // 'wx' ensures we only create if it doesn't exist (atomic lock acquisition)
+ const fileHandle = await open(configuration.runnerLockFile, 'wx');
+ // Write PID to lock file for debugging
+ await fileHandle.writeFile(String(process.pid));
+ return fileHandle;
```
This function is important because it defines how HAPI Tutorial: Remote Control for Local AI Coding Sessions implements the patterns covered in this chapter.
-### `shared/src/voice.ts`
+### `cli/src/persistence.ts`
-The `or` interface in [`shared/src/voice.ts`](https://github.com/tiann/hapi/blob/HEAD/shared/src/voice.ts) handles a key part of this chapter's functionality:
+The `acquireRunnerLock` function in [`cli/src/persistence.ts`](https://github.com/tiann/hapi/blob/HEAD/cli/src/persistence.ts) handles a key part of this chapter's functionality:
```ts
-/**
- * Shared voice assistant configuration for ElevenLabs ConvAI.
- *
- * This module provides the unified configuration for the Hapi Voice Assistant,
- * ensuring consistency between server-side auto-creation and client-side usage.
+ * Returns the file handle to hold for the runner's lifetime, or null if locked.
*/
-
-export const ELEVENLABS_API_BASE = 'https://api.elevenlabs.io/v1'
-export const VOICE_AGENT_NAME = 'Hapi Voice Assistant'
-
-export const VOICE_SYSTEM_PROMPT = `# Identity
-
-You are Hapi Voice Assistant. You bridge voice communication between users and their AI coding agents in the Hapi ecosystem.
-
-You are friendly, proactive, and highly intelligent with a world-class engineering background. Your approach is warm, witty, and relaxed, balancing professionalism with an approachable vibe.
-
-# Environment Overview
-
-Hapi is a multi-agent development platform supporting:
-- **Claude Code** - Anthropic's coding assistant (primary)
-- **Codex** - OpenAI's coding agent
-- **Gemini** - Google's coding agent
-
-Users control these agents through the Hapi web interface or Telegram Mini App. You serve as the voice interface to whichever agent is currently active.
-
-# How Context Updates Work
-
-You receive automatic context updates when:
-- A session becomes focused (you see the full session history)
-- The agent sends messages or uses tools
-- Permission requests arrive
+export async function acquireRunnerLock(
+ maxAttempts: number = 5,
+ delayIncrementMs: number = 200
+): Promise<FileHandle | null> {
+ for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+ try {
+ // 'wx' ensures we only create if it doesn't exist (atomic lock acquisition)
+ const fileHandle = await open(configuration.runnerLockFile, 'wx');
+ // Write PID to lock file for debugging
+ await fileHandle.writeFile(String(process.pid));
+ return fileHandle;
+ } catch (error: any) {
+ if (error.code === 'EEXIST') {
+ // Lock file exists, check if process is still running
+ try {
+ const lockPid = readFileSync(configuration.runnerLockFile, 'utf-8').trim();
+ if (lockPid && !isNaN(Number(lockPid))) {
+ if (!isProcessAlive(Number(lockPid))) {
+ // Process doesn't exist, remove stale lock
+ unlinkSync(configuration.runnerLockFile);
+ continue; // Retry acquisition
+ }
+ }
+ } catch {
+ // Can't read lock file, might be corrupted
+ }
+ }
+
+ if (attempt === maxAttempts) {
+ return null;
```
-This interface is important because it defines how HAPI Tutorial: Remote Control for Local AI Coding Sessions implements the patterns covered in this chapter.
+This function is important because it defines how HAPI Tutorial: Remote Control for Local AI Coding Sessions implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[main]
- B[engineering]
- C[buildVoiceAgentConfig]
- D[or]
- E[to]
+ A[readRunnerState]
+ B[writeRunnerState]
+ C[clearRunnerState]
+ D[acquireRunnerLock]
+ E[releaseRunnerLock]
A --> B
B --> C
C --> D
diff --git a/tutorials/hapi-tutorial/07-configuration-and-security.md b/tutorials/hapi-tutorial/07-configuration-and-security.md
index 0f232077..507ddb3d 100644
--- a/tutorials/hapi-tutorial/07-configuration-and-security.md
+++ b/tutorials/hapi-tutorial/07-configuration-and-security.md
@@ -68,17 +68,6 @@ Under the hood, `Chapter 7: Configuration and Security` usually follows a repeat
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
-## Source Walkthrough
-
-Use the following upstream sources to verify implementation details while reading this chapter:
-
-- [HAPI Repository](https://github.com/tiann/hapi)
- Why it matters: authoritative reference on `HAPI Repository` (github.com).
-- [HAPI Releases](https://github.com/tiann/hapi/releases)
- Why it matters: authoritative reference on `HAPI Releases` (github.com).
-- [HAPI Docs](https://hapi.run)
- Why it matters: authoritative reference on `HAPI Docs` (hapi.run).
-
## Chapter Connections
- [Tutorial Index](README.md)
@@ -87,15 +76,26 @@ Use the following upstream sources to verify implementation details while readin
- [Main Catalog](../../README.md#-tutorial-catalog)
- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `cli/src/persistence.ts`
-The `readSettings` function in [`cli/src/persistence.ts`](https://github.com/tiann/hapi/blob/HEAD/cli/src/persistence.ts) handles a key part of this chapter's functionality:
+The `RunnerLocallyPersistedState` interface in [`cli/src/persistence.ts`](https://github.com/tiann/hapi/blob/HEAD/cli/src/persistence.ts) handles a key part of this chapter's functionality:
```ts
+ * This is written to disk by the runner to track its local process state
+ */
+export interface RunnerLocallyPersistedState {
+ pid: number;
+ httpPort: number;
+ startTime: string;
+ startedWithCliVersion: string;
+ startedWithCliMtimeMs?: number;
+ startedWithApiUrl?: string;
+ startedWithMachineId?: string;
+ startedWithCliApiTokenHash?: string;
+ lastHeartbeat?: string;
+ runnerLogPath?: string;
}
export async function readSettings(): Promise<Settings> {
@@ -115,142 +115,129 @@ export async function writeSettings(settings: Settings): Promise<void> {
if (!existsSync(configuration.happyHomeDir)) {
await mkdir(configuration.happyHomeDir, { recursive: true })
}
-
- await writeFile(configuration.settingsFile, JSON.stringify(settings, null, 2))
-}
-
-/**
- * Atomically update settings with multi-process safety via file locking
- * @param updater Function that takes current settings and returns updated settings
- * @returns The updated settings
- */
-export async function updateSettings(
- updater: (current: Settings) => Settings | Promise<Settings>
-): Promise<Settings> {
- // Timing constants
```
-This function is important because it defines how HAPI Tutorial: Remote Control for Local AI Coding Sessions implements the patterns covered in this chapter.
-
-### `cli/src/persistence.ts`
-
-The `writeSettings` function in [`cli/src/persistence.ts`](https://github.com/tiann/hapi/blob/HEAD/cli/src/persistence.ts) handles a key part of this chapter's functionality:
-
-```ts
-}
-
-export async function writeSettings(settings: Settings): Promise<void> {
- if (!existsSync(configuration.happyHomeDir)) {
- await mkdir(configuration.happyHomeDir, { recursive: true })
- }
-
- await writeFile(configuration.settingsFile, JSON.stringify(settings, null, 2))
-}
-
-/**
- * Atomically update settings with multi-process safety via file locking
- * @param updater Function that takes current settings and returns updated settings
- * @returns The updated settings
- */
-export async function updateSettings(
- updater: (current: Settings) => Settings | Promise<Settings>
-): Promise<Settings> {
- // Timing constants
- const LOCK_RETRY_INTERVAL_MS = 100; // How long to wait between lock attempts
- const MAX_LOCK_ATTEMPTS = 50; // Maximum number of attempts (5 seconds total)
- const STALE_LOCK_TIMEOUT_MS = 10000; // Consider lock stale after 10 seconds
-
- if (!existsSync(configuration.happyHomeDir)) {
- await mkdir(configuration.happyHomeDir, { recursive: true });
- }
-
- const lockFile = configuration.settingsFile + '.lock';
- const tmpFile = configuration.settingsFile + '.tmp';
- let fileHandle;
- let attempts = 0;
-
+This interface is important because it defines how HAPI Tutorial: Remote Control for Local AI Coding Sessions implements the patterns covered in this chapter.
+
+### `web/src/App.tsx`
+
+The `App` function in [`web/src/App.tsx`](https://github.com/tiann/hapi/blob/HEAD/web/src/App.tsx) handles a key part of this chapter's functionality:
+
+```tsx
+import { Outlet, useLocation, useMatchRoute, useRouter } from '@tanstack/react-router'
+import { useQueryClient } from '@tanstack/react-query'
+import { getTelegramWebApp, isTelegramApp } from '@/hooks/useTelegram'
+import { initializeTheme } from '@/hooks/useTheme'
+import { useAuth } from '@/hooks/useAuth'
+import { useAuthSource } from '@/hooks/useAuthSource'
+import { useServerUrl } from '@/hooks/useServerUrl'
+import { useSSE } from '@/hooks/useSSE'
+import { useSyncingState } from '@/hooks/useSyncingState'
+import { usePushNotifications } from '@/hooks/usePushNotifications'
+import { useVisibilityReporter } from '@/hooks/useVisibilityReporter'
+import { queryKeys } from '@/lib/query-keys'
+import { AppContextProvider } from '@/lib/app-context'
+import { fetchLatestMessages } from '@/lib/message-window-store'
+import { useAppGoBack } from '@/hooks/useAppGoBack'
+import { useTranslation } from '@/lib/use-translation'
+import { VoiceProvider } from '@/lib/voice-context'
+import { requireHubUrlForLogin } from '@/lib/runtime-config'
+import { LoginPrompt } from '@/components/LoginPrompt'
+import { InstallPrompt } from '@/components/InstallPrompt'
+import { OfflineBanner } from '@/components/OfflineBanner'
+import { SyncingBanner } from '@/components/SyncingBanner'
+import { ReconnectingBanner } from '@/components/ReconnectingBanner'
+import { VoiceErrorBanner } from '@/components/VoiceErrorBanner'
+import { LoadingState } from '@/components/LoadingState'
+import { ToastContainer } from '@/components/ToastContainer'
+import { ToastProvider, useToast } from '@/lib/toast-context'
+import type { SyncEvent } from '@/types/api'
+
+type ToastEvent = Extract<SyncEvent, { type: 'toast' }>
+
+const REQUIRE_SERVER_URL = requireHubUrlForLogin()
```
This function is important because it defines how HAPI Tutorial: Remote Control for Local AI Coding Sessions implements the patterns covered in this chapter.
-### `cli/src/persistence.ts`
-
-The `updateSettings` function in [`cli/src/persistence.ts`](https://github.com/tiann/hapi/blob/HEAD/cli/src/persistence.ts) handles a key part of this chapter's functionality:
+### `web/src/App.tsx`
-```ts
- * @returns The updated settings
- */
-export async function updateSettings(
- updater: (current: Settings) => Settings | Promise<Settings>
-): Promise<Settings> {
- // Timing constants
- const LOCK_RETRY_INTERVAL_MS = 100; // How long to wait between lock attempts
- const MAX_LOCK_ATTEMPTS = 50; // Maximum number of attempts (5 seconds total)
- const STALE_LOCK_TIMEOUT_MS = 10000; // Consider lock stale after 10 seconds
+The `AppInner` function in [`web/src/App.tsx`](https://github.com/tiann/hapi/blob/HEAD/web/src/App.tsx) handles a key part of this chapter's functionality:
- if (!existsSync(configuration.happyHomeDir)) {
- await mkdir(configuration.happyHomeDir, { recursive: true });
- }
+```tsx
+ return (
+ <ToastProvider>
+ <AppInner />
+ </ToastProvider>
+ )
+}
- const lockFile = configuration.settingsFile + '.lock';
- const tmpFile = configuration.settingsFile + '.tmp';
- let fileHandle;
- let attempts = 0;
-
- // Acquire exclusive lock with retries
- while (attempts < MAX_LOCK_ATTEMPTS) {
- try {
- // 'wx' = create exclusively, fail if exists (cross-platform compatible)
- fileHandle = await open(lockFile, 'wx');
- break;
- } catch (err: any) {
- if (err.code === 'EEXIST') {
- // Lock file exists, wait and retry
- attempts++;
- await new Promise(resolve => setTimeout(resolve, LOCK_RETRY_INTERVAL_MS));
-
- // Check for stale lock
+function AppInner() {
+ const { t } = useTranslation()
+ const { serverUrl, baseUrl, setServerUrl, clearServerUrl } = useServerUrl()
+ const { authSource, isLoading: isAuthSourceLoading, setAccessToken } = useAuthSource(baseUrl)
+ const { token, api, isLoading: isAuthLoading, error: authError, needsBinding, bind } = useAuth(authSource, baseUrl)
+ const goBack = useAppGoBack()
+ const pathname = useLocation({ select: (location) => location.pathname })
+ const matchRoute = useMatchRoute()
+ const router = useRouter()
+ const { addToast } = useToast()
+
+ useEffect(() => {
+ const tg = getTelegramWebApp()
+ tg?.ready()
+ tg?.expand()
+ initializeTheme()
+ }, [])
+
+ useEffect(() => {
+ const preventDefault = (event: Event) => {
+ event.preventDefault()
+ }
+
+ const onWheel = (event: WheelEvent) => {
+ if (event.ctrlKey) {
```
This function is important because it defines how HAPI Tutorial: Remote Control for Local AI Coding Sessions implements the patterns covered in this chapter.
-### `cli/src/persistence.ts`
+### `hub/src/index.ts`
-The `writeCredentialsDataKey` function in [`cli/src/persistence.ts`](https://github.com/tiann/hapi/blob/HEAD/cli/src/persistence.ts) handles a key part of this chapter's functionality:
+The `formatSource` function in [`hub/src/index.ts`](https://github.com/tiann/hapi/blob/HEAD/hub/src/index.ts) handles a key part of this chapter's functionality:
```ts
-//
-export async function writeCredentialsDataKey(credentials: { publicKey: Uint8Array, machineKey: Uint8Array, token: string }): Promise<void> {
- if (!existsSync(configuration.happyHomeDir)) {
- await mkdir(configuration.happyHomeDir, { recursive: true })
- }
- await writeFile(configuration.privateKeyFile, JSON.stringify({
- encryption: { publicKey: Buffer.from(credentials.publicKey).toString('base64'), machineKey: Buffer.from(credentials.machineKey).toString('base64') },
- token: credentials.token
- }, null, 2));
+/** Format config source for logging */
+function formatSource(source: ConfigSource | 'generated'): string {
+ switch (source) {
+ case 'env':
+ return 'environment'
+ case 'file':
+ return 'settings.json'
+ case 'default':
+ return 'default'
+ case 'generated':
+ return 'generated'
+ }
}
-export async function clearCredentials(): Promise<void> {
- if (existsSync(configuration.privateKeyFile)) {
- await unlink(configuration.privateKeyFile);
- }
-}
+type RelayFlagSource = 'default' | '--relay' | '--no-relay'
-export async function clearMachineId(): Promise<void> {
- await updateSettings(settings => ({
- ...settings,
- machineId: undefined
- }));
-}
+function resolveRelayFlag(args: string[]): { enabled: boolean; source: RelayFlagSource } {
+ let enabled = false
+ let source: RelayFlagSource = 'default'
-/**
- * Read runner state from local file
- */
-export async function readRunnerState(): Promise<RunnerLocallyPersistedState | null> {
- try {
- if (!existsSync(configuration.runnerStateFile)) {
- return null;
+ for (const arg of args) {
+ if (arg === '--relay') {
+ enabled = true
+ source = '--relay'
+ } else if (arg === '--no-relay') {
+ enabled = false
+ source = '--no-relay'
+ }
+ }
+
+ return { enabled, source }
```
This function is important because it defines how HAPI Tutorial: Remote Control for Local AI Coding Sessions implements the patterns covered in this chapter.
@@ -260,11 +247,11 @@ This function is important because it defines how HAPI Tutorial: Remote Control
```mermaid
flowchart TD
- A[readSettings]
- B[writeSettings]
- C[updateSettings]
- D[writeCredentialsDataKey]
- E[clearCredentials]
+ A[RunnerLocallyPersistedState]
+ B[App]
+ C[AppInner]
+ D[formatSource]
+ E[resolveRelayFlag]
A --> B
B --> C
C --> D
diff --git a/tutorials/hapi-tutorial/08-production-operations.md b/tutorials/hapi-tutorial/08-production-operations.md
index 3df83bfd..df15d472 100644
--- a/tutorials/hapi-tutorial/08-production-operations.md
+++ b/tutorials/hapi-tutorial/08-production-operations.md
@@ -72,17 +72,6 @@ Under the hood, `Chapter 8: Production Operations` usually follows a repeatable
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
-## Source Walkthrough
-
-Use the following upstream sources to verify implementation details while reading this chapter:
-
-- [HAPI Repository](https://github.com/tiann/hapi)
- Why it matters: authoritative reference on `HAPI Repository` (github.com).
-- [HAPI Releases](https://github.com/tiann/hapi/releases)
- Why it matters: authoritative reference on `HAPI Releases` (github.com).
-- [HAPI Docs](https://hapi.run)
- Why it matters: authoritative reference on `HAPI Docs` (hapi.run).
-
## Chapter Connections
- [Tutorial Index](README.md)
@@ -90,184 +79,182 @@ Use the following upstream sources to verify implementation details while readin
- [Main Catalog](../../README.md#-tutorial-catalog)
- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `cli/src/persistence.ts`
+### `hub/src/index.ts`
-The `readRunnerState` function in [`cli/src/persistence.ts`](https://github.com/tiann/hapi/blob/HEAD/cli/src/persistence.ts) handles a key part of this chapter's functionality:
+The `normalizeOrigins` function in [`hub/src/index.ts`](https://github.com/tiann/hapi/blob/HEAD/hub/src/index.ts) handles a key part of this chapter's functionality:
```ts
- * Read runner state from local file
- */
-export async function readRunnerState(): Promise<RunnerLocallyPersistedState | null> {
- try {
- if (!existsSync(configuration.runnerStateFile)) {
- return null;
+}
+
+function normalizeOrigins(origins: string[]): string[] {
+ const normalized = origins
+ .map(normalizeOrigin)
+ .filter(Boolean)
+ if (normalized.includes('*')) {
+ return ['*']
}
- const content = await readFile(configuration.runnerStateFile, 'utf-8');
- return JSON.parse(content) as RunnerLocallyPersistedState;
- } catch (error) {
- // State corrupted somehow :(
- console.error(`[PERSISTENCE] Runner state file corrupted: ${configuration.runnerStateFile}`, error);
- return null;
- }
+ return Array.from(new Set(normalized))
}
-/**
- * Write runner state to local file (synchronously for atomic operation)
- */
-export function writeRunnerState(state: RunnerLocallyPersistedState): void {
- writeFileSync(configuration.runnerStateFile, JSON.stringify(state, null, 2), 'utf-8');
+function mergeCorsOrigins(base: string[], extra: string[]): string[] {
+ if (base.includes('*') || extra.includes('*')) {
+ return ['*']
+ }
+ const merged = new Set<string>()
+ for (const origin of base) {
+ merged.add(origin)
+ }
+ for (const origin of extra) {
+ merged.add(origin)
+ }
+ return Array.from(merged)
}
-/**
- * Clean up runner state file and lock file
- */
-export async function clearRunnerState(): Promise<void> {
- if (existsSync(configuration.runnerStateFile)) {
- await unlink(configuration.runnerStateFile);
- }
- // Also clean up lock file if it exists (for stale cleanup)
- if (existsSync(configuration.runnerLockFile)) {
+let syncEngine: SyncEngine | null = null
+let happyBot: HappyBot | null = null
+let webServer: BunServer<WebSocketData> | null = null
+let sseManager: SSEManager | null = null
+let visibilityTracker: VisibilityTracker | null = null
+let notificationHub: NotificationHub | null = null
```
This function is important because it defines how HAPI Tutorial: Remote Control for Local AI Coding Sessions implements the patterns covered in this chapter.
-### `cli/src/persistence.ts`
+### `hub/src/index.ts`
-The `writeRunnerState` function in [`cli/src/persistence.ts`](https://github.com/tiann/hapi/blob/HEAD/cli/src/persistence.ts) handles a key part of this chapter's functionality:
+The `mergeCorsOrigins` function in [`hub/src/index.ts`](https://github.com/tiann/hapi/blob/HEAD/hub/src/index.ts) handles a key part of this chapter's functionality:
```ts
- * Write runner state to local file (synchronously for atomic operation)
- */
-export function writeRunnerState(state: RunnerLocallyPersistedState): void {
- writeFileSync(configuration.runnerStateFile, JSON.stringify(state, null, 2), 'utf-8');
}
-/**
- * Clean up runner state file and lock file
- */
-export async function clearRunnerState(): Promise<void> {
- if (existsSync(configuration.runnerStateFile)) {
- await unlink(configuration.runnerStateFile);
- }
- // Also clean up lock file if it exists (for stale cleanup)
- if (existsSync(configuration.runnerLockFile)) {
- try {
- await unlink(configuration.runnerLockFile);
- } catch {
- // Lock file might be held by running runner, ignore error
+function mergeCorsOrigins(base: string[], extra: string[]): string[] {
+ if (base.includes('*') || extra.includes('*')) {
+ return ['*']
}
- }
+ const merged = new Set<string>()
+ for (const origin of base) {
+ merged.add(origin)
+ }
+ for (const origin of extra) {
+ merged.add(origin)
+ }
+ return Array.from(merged)
}
-/**
- * Acquire an exclusive lock file for the runner.
- * The lock file proves the runner is running and prevents multiple instances.
- * Returns the file handle to hold for the runner's lifetime, or null if locked.
- */
-export async function acquireRunnerLock(
- maxAttempts: number = 5,
- delayIncrementMs: number = 200
-): Promise<FileHandle | null> {
+let syncEngine: SyncEngine | null = null
+let happyBot: HappyBot | null = null
+let webServer: BunServer<WebSocketData> | null = null
+let sseManager: SSEManager | null = null
+let visibilityTracker: VisibilityTracker | null = null
+let notificationHub: NotificationHub | null = null
+let tunnelManager: TunnelManager | null = null
+
+async function main() {
+ console.log('HAPI Hub starting...')
+
+ // Load configuration (async - loads from env/file with persistence)
+ const relayApiDomain = process.env.HAPI_RELAY_API || 'relay.hapi.run'
+ const relayFlag = resolveRelayFlag(process.argv)
+ const officialWebUrl = process.env.HAPI_OFFICIAL_WEB_URL || 'https://app.hapi.run'
+ const config = await createConfiguration()
```
This function is important because it defines how HAPI Tutorial: Remote Control for Local AI Coding Sessions implements the patterns covered in this chapter.
-### `cli/src/persistence.ts`
+### `hub/src/index.ts`
-The `clearRunnerState` function in [`cli/src/persistence.ts`](https://github.com/tiann/hapi/blob/HEAD/cli/src/persistence.ts) handles a key part of this chapter's functionality:
+The `main` function in [`hub/src/index.ts`](https://github.com/tiann/hapi/blob/HEAD/hub/src/index.ts) handles a key part of this chapter's functionality:
```ts
- * Clean up runner state file and lock file
- */
-export async function clearRunnerState(): Promise<void> {
- if (existsSync(configuration.runnerStateFile)) {
- await unlink(configuration.runnerStateFile);
- }
- // Also clean up lock file if it exists (for stale cleanup)
- if (existsSync(configuration.runnerLockFile)) {
- try {
- await unlink(configuration.runnerLockFile);
- } catch {
- // Lock file might be held by running runner, ignore error
+let tunnelManager: TunnelManager | null = null
+
+async function main() {
+ console.log('HAPI Hub starting...')
+
+ // Load configuration (async - loads from env/file with persistence)
+ const relayApiDomain = process.env.HAPI_RELAY_API || 'relay.hapi.run'
+ const relayFlag = resolveRelayFlag(process.argv)
+ const officialWebUrl = process.env.HAPI_OFFICIAL_WEB_URL || 'https://app.hapi.run'
+ const config = await createConfiguration()
+ const baseCorsOrigins = normalizeOrigins(config.corsOrigins)
+ const relayCorsOrigin = normalizeOrigin(officialWebUrl)
+ const corsOrigins = relayFlag.enabled
+ ? mergeCorsOrigins(baseCorsOrigins, relayCorsOrigin ? [relayCorsOrigin] : [])
+ : baseCorsOrigins
+
+ // Display CLI API token information
+ if (config.cliApiTokenIsNew) {
+ console.log('')
+ console.log('='.repeat(70))
+ console.log(' NEW CLI_API_TOKEN GENERATED')
+ console.log('='.repeat(70))
+ console.log('')
+ console.log(` Token: ${config.cliApiToken}`)
+ console.log('')
+ console.log(` Saved to: ${config.settingsFile}`)
+ console.log('')
+ console.log('='.repeat(70))
+ console.log('')
+ } else {
+ console.log(`[Hub] CLI_API_TOKEN: loaded from ${formatSource(config.sources.cliApiToken)}`)
}
- }
-}
-
-/**
- * Acquire an exclusive lock file for the runner.
- * The lock file proves the runner is running and prevents multiple instances.
- * Returns the file handle to hold for the runner's lifetime, or null if locked.
- */
-export async function acquireRunnerLock(
- maxAttempts: number = 5,
- delayIncrementMs: number = 200
-): Promise<FileHandle | null> {
- for (let attempt = 1; attempt <= maxAttempts; attempt++) {
- try {
- // 'wx' ensures we only create if it doesn't exist (atomic lock acquisition)
- const fileHandle = await open(configuration.runnerLockFile, 'wx');
- // Write PID to lock file for debugging
- await fileHandle.writeFile(String(process.pid));
- return fileHandle;
```
This function is important because it defines how HAPI Tutorial: Remote Control for Local AI Coding Sessions implements the patterns covered in this chapter.
-### `cli/src/persistence.ts`
+### `shared/src/voice.ts`
-The `acquireRunnerLock` function in [`cli/src/persistence.ts`](https://github.com/tiann/hapi/blob/HEAD/cli/src/persistence.ts) handles a key part of this chapter's functionality:
+The `engineering` class in [`shared/src/voice.ts`](https://github.com/tiann/hapi/blob/HEAD/shared/src/voice.ts) handles a key part of this chapter's functionality:
```ts
- * Returns the file handle to hold for the runner's lifetime, or null if locked.
- */
-export async function acquireRunnerLock(
- maxAttempts: number = 5,
- delayIncrementMs: number = 200
-): Promise<FileHandle | null> {
- for (let attempt = 1; attempt <= maxAttempts; attempt++) {
- try {
- // 'wx' ensures we only create if it doesn't exist (atomic lock acquisition)
- const fileHandle = await open(configuration.runnerLockFile, 'wx');
- // Write PID to lock file for debugging
- await fileHandle.writeFile(String(process.pid));
- return fileHandle;
- } catch (error: any) {
- if (error.code === 'EEXIST') {
- // Lock file exists, check if process is still running
- try {
- const lockPid = readFileSync(configuration.runnerLockFile, 'utf-8').trim();
- if (lockPid && !isNaN(Number(lockPid))) {
- if (!isProcessAlive(Number(lockPid))) {
- // Process doesn't exist, remove stale lock
- unlinkSync(configuration.runnerLockFile);
- continue; // Retry acquisition
- }
- }
- } catch {
- // Can't read lock file, might be corrupted
- }
- }
-
- if (attempt === maxAttempts) {
- return null;
+You are Hapi Voice Assistant. You bridge voice communication between users and their AI coding agents in the Hapi ecosystem.
+
+You are friendly, proactive, and highly intelligent with a world-class engineering background. Your approach is warm, witty, and relaxed, balancing professionalism with an approachable vibe.
+
+# Environment Overview
+
+Hapi is a multi-agent development platform supporting:
+- **Claude Code** - Anthropic's coding assistant (primary)
+- **Codex** - OpenAI's coding agent
+- **Gemini** - Google's coding agent
+
+Users control these agents through the Hapi web interface or Telegram Mini App. You serve as the voice interface to whichever agent is currently active.
+
+# How Context Updates Work
+
+You receive automatic context updates when:
+- A session becomes focused (you see the full session history)
+- The agent sends messages or uses tools
+- Permission requests arrive
+- The agent finishes working (ready event)
+
+These updates appear as system messages. You do NOT need to poll or ask for updates. Simply wait for them and summarize when relevant.
+
+# Tools
+
+## messageCodingAgent
+Send user requests to the active coding agent.
+
+When to use:
+- User says "ask Claude to..." or "have it..."
+- Any coding, file, or development request
+- User wants to continue a task
```
-This function is important because it defines how HAPI Tutorial: Remote Control for Local AI Coding Sessions implements the patterns covered in this chapter.
+This class is important because it defines how HAPI Tutorial: Remote Control for Local AI Coding Sessions implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[readRunnerState]
- B[writeRunnerState]
- C[clearRunnerState]
- D[acquireRunnerLock]
- E[releaseRunnerLock]
+ A[normalizeOrigins]
+ B[mergeCorsOrigins]
+ C[main]
+ D[engineering]
+ E[buildVoiceAgentConfig]
A --> B
B --> C
C --> D
diff --git a/tutorials/haystack-tutorial/02-document-stores.md b/tutorials/haystack-tutorial/02-document-stores.md
index bc2d2450..2ad8f9da 100644
--- a/tutorials/haystack-tutorial/02-document-stores.md
+++ b/tutorials/haystack-tutorial/02-document-stores.md
@@ -32,7 +32,7 @@ A document store in Haystack is a component that stores and manages your documen
- **Updates**: Adding, modifying, and deleting documents
```python
-from haystack.document_stores import InMemoryDocumentStore
+from haystack.document_stores.in_memory import InMemoryDocumentStore
# Create a simple in-memory document store
document_store = InMemoryDocumentStore()
@@ -53,7 +53,7 @@ document_store.write_documents(documents)
Perfect for development, testing, and small datasets:
```python
-from haystack.document_stores import InMemoryDocumentStore
+from haystack.document_stores.in_memory import InMemoryDocumentStore
# Create in-memory store
document_store = InMemoryDocumentStore()
@@ -82,7 +82,7 @@ document_store.write_documents(documents)
Production-ready with advanced search capabilities:
```python
-from haystack.document_stores import ElasticsearchDocumentStore
+from haystack_integrations.document_stores.elasticsearch import ElasticsearchDocumentStore
# Connect to Elasticsearch
document_store = ElasticsearchDocumentStore(
@@ -114,7 +114,7 @@ document_store = ElasticsearchDocumentStore(
Cloud-native vector database for large-scale deployments:
```python
-from haystack.document_stores import PineconeDocumentStore
+from haystack_integrations.document_stores.pinecone import PineconeDocumentStore
# Initialize Pinecone
document_store = PineconeDocumentStore(
@@ -143,7 +143,7 @@ document_store = PineconeDocumentStore(
Graph-based vector database with advanced features:
```python
-from haystack.document_stores import WeaviateDocumentStore
+from haystack_integrations.document_stores.weaviate import WeaviateDocumentStore
# Connect to Weaviate
document_store = WeaviateDocumentStore(
@@ -213,7 +213,7 @@ documents = [
### Document Preprocessing
```python
-from haystack.nodes import PreProcessor
+from haystack.components.preprocessors import DocumentSplitter # Haystack 2.x: PreProcessor replaced by DocumentSplitter
# Text preprocessing
preprocessor = PreProcessor(
@@ -545,6 +545,22 @@ Ready to explore retrieval techniques? Let's dive into [Chapter 3: Retrievers &
*What's your preferred document store for different use cases?* 📚
+## Document Store Architecture
+
+```mermaid
+flowchart TD
+ A[Haystack Pipeline] --> B{Document Store type}
+ B -->|Development| C[InMemoryDocumentStore]
+ B -->|Production search| D[ElasticsearchDocumentStore]
+ B -->|Vector search cloud| E[PineconeDocumentStore]
+ B -->|OSS vector search| F[WeaviateDocumentStore]
+ C --> G[write_documents / filter_documents]
+ D --> G
+ E --> G
+ F --> G
+ G --> H[Retriever component reads from store]
+```
+
## What Problem Does This Solve?
Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for `document_store`, `documents`, `query` so behavior stays predictable as complexity grows.
diff --git a/tutorials/haystack-tutorial/03-retrievers-search.md b/tutorials/haystack-tutorial/03-retrievers-search.md
index 30d7e651..9684bee7 100644
--- a/tutorials/haystack-tutorial/03-retrievers-search.md
+++ b/tutorials/haystack-tutorial/03-retrievers-search.md
@@ -681,6 +681,23 @@ With retrieval mastered, you're ready to:
**Ready to integrate LLMs with your search system? Continue to [Chapter 4: Generators & LLMs](04-generators-llms.md)!** 🚀
+## Retrieval Architecture
+
+```mermaid
+flowchart TD
+ A[Query] --> B{Retrieval strategy}
+ B -->|Keyword| C[BM25Retriever]
+ B -->|Semantic| D[EmbeddingRetriever]
+ B -->|Hybrid| E[BM25 + Embedding join]
+ C --> F[InMemoryDocumentStore BM25]
+ D --> G[Vector-indexed document store]
+ E --> F
+ E --> G
+ F --> H[Top-k documents]
+ G --> H
+ H --> I[Generator / downstream component]
+```
+
## What Problem Does This Solve?
Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for `self`, `query`, `retriever` so behavior stays predictable as complexity grows.
diff --git a/tutorials/haystack-tutorial/04-generators-llms.md b/tutorials/haystack-tutorial/04-generators-llms.md
index 9001e40f..63b5dd0e 100644
--- a/tutorials/haystack-tutorial/04-generators-llms.md
+++ b/tutorials/haystack-tutorial/04-generators-llms.md
@@ -759,6 +759,21 @@ With LLM integration complete, you're ready to:
**Ready to build complex search workflows? Continue to [Chapter 5: Pipelines & Workflows](05-pipelines-workflows.md)!** 🚀
+## Generator Pipeline
+
+```mermaid
+flowchart TD
+ A[PromptBuilder] --> B[Generator]
+ B --> C{Provider}
+ C -->|OpenAI| D[OpenAIGenerator]
+ C -->|Anthropic| E[AnthropicGenerator]
+ C -->|Local| F[HuggingFaceLocalGenerator]
+ D --> G[Generated answer]
+ E --> G
+ F --> G
+ G --> H[Pipeline output]
+```
+
## What Problem Does This Solve?
Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for `self`, `query`, `responses` so behavior stays predictable as complexity grows.
diff --git a/tutorials/haystack-tutorial/05-pipelines-workflows.md b/tutorials/haystack-tutorial/05-pipelines-workflows.md
index 6c85377d..2cbcd62c 100644
--- a/tutorials/haystack-tutorial/05-pipelines-workflows.md
+++ b/tutorials/haystack-tutorial/05-pipelines-workflows.md
@@ -855,6 +855,20 @@ With advanced pipelines mastered, you're ready to:
**Ready to evaluate and optimize your search systems? Continue to [Chapter 6: Evaluation & Optimization](06-evaluation-optimization.md)!** 🚀
+## Pipeline Execution
+
+```mermaid
+flowchart TD
+ A[Pipeline.add_component] --> B[Connect components]
+ B --> C[pipeline.connect output to input]
+ C --> D[pipeline.run inputs]
+ D --> E[Topological execution order]
+ E --> F[Each component receives inputs]
+ F --> G[Component produces outputs]
+ G --> H[Outputs passed to connected components]
+ H --> I[Final pipeline result dict]
+```
+
## What Problem Does This Solve?
Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for `self`, `query`, `pipeline` so behavior stays predictable as complexity grows.
diff --git a/tutorials/haystack-tutorial/06-evaluation-optimization.md b/tutorials/haystack-tutorial/06-evaluation-optimization.md
index 2b3069a6..ac39f9ed 100644
--- a/tutorials/haystack-tutorial/06-evaluation-optimization.md
+++ b/tutorials/haystack-tutorial/06-evaluation-optimization.md
@@ -922,6 +922,22 @@ With evaluation and optimization mastered, you're ready to:
**Ready to build custom Haystack components? Continue to [Chapter 7: Custom Components](07-custom-components.md)!** 🚀
+## Evaluation Flow
+
+```mermaid
+flowchart TD
+ A[Evaluation dataset] --> B[Run pipeline on each sample]
+ B --> C[Collect predictions]
+ C --> D[Metrics computation]
+ D --> E{Metric type}
+ E -->|Retrieval| F[Recall@k, MRR, NDCG]
+ E -->|Generation| G[EM, F1, ROUGE]
+ E -->|End-to-end RAG| H[Answer correctness]
+ F --> I[Evaluation report]
+ G --> I
+ H --> I
+```
+
## What Problem Does This Solve?
Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for `self`, `results`, `query` so behavior stays predictable as complexity grows.
diff --git a/tutorials/haystack-tutorial/07-custom-components.md b/tutorials/haystack-tutorial/07-custom-components.md
index ac45a572..80094b30 100644
--- a/tutorials/haystack-tutorial/07-custom-components.md
+++ b/tutorials/haystack-tutorial/07-custom-components.md
@@ -1149,6 +1149,20 @@ With custom components mastered, you're ready for:
*Congratulations! You've now completed the comprehensive Haystack tutorial with 8 full chapters covering everything from basic search to advanced custom components. You have the knowledge and skills to build sophisticated search systems and extend Haystack for specialized use cases.*
+## Custom Component Architecture
+
+```mermaid
+flowchart TD
+ A[Custom component class] --> B[Decorate with @component]
+ B --> C[Define run method]
+ C --> D[Annotate inputs with Input type]
+ C --> E[Annotate outputs with Output type]
+ D --> F[Component registered in pipeline]
+ E --> F
+ F --> G[Pipeline.add_component]
+ G --> H[Connected to other components]
+```
+
## What Problem Does This Solve?
Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for `self`, `content`, `text` so behavior stays predictable as complexity grows.
diff --git a/tutorials/haystack-tutorial/08-production-deployment.md b/tutorials/haystack-tutorial/08-production-deployment.md
index f0f52d80..bfb79f8d 100644
--- a/tutorials/haystack-tutorial/08-production-deployment.md
+++ b/tutorials/haystack-tutorial/08-production-deployment.md
@@ -1121,6 +1121,21 @@ You've successfully mastered production deployment of Haystack applications!
*Your journey with intelligent search systems has equipped you to build the next generation of AI-powered search applications that can serve millions of users reliably and efficiently.*
+## Production Deployment
+
+```mermaid
+flowchart TD
+ A[Haystack pipeline] --> B[pipeline.to_dict serialization]
+ B --> C[Store pipeline YAML/JSON]
+ C --> D[Deploy as REST API]
+ D --> E{Deployment target}
+ E -->|Docker| F[Container with Hayhooks]
+ E -->|Cloud| G[Managed service]
+ F --> H[POST /api/v1/run endpoint]
+ G --> H
+ H --> I[Execute pipeline on request]
+```
+
## What Problem Does This Solve?
Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for `self`, `search`, `status` so behavior stays predictable as complexity grows.
diff --git a/tutorials/hermes-agent-tutorial/01-getting-started.md b/tutorials/hermes-agent-tutorial/01-getting-started.md
new file mode 100644
index 00000000..f7c4e8c9
--- /dev/null
+++ b/tutorials/hermes-agent-tutorial/01-getting-started.md
@@ -0,0 +1,392 @@
+---
+layout: default
+title: "Chapter 1: Getting Started"
+nav_order: 1
+parent: Hermes Agent Tutorial
+format_version: v2
+why: "Every minute spent wrestling with installation is a minute not spent understanding what makes Hermes architecturally different from every other agent framework. This chapter eliminates that friction and establishes the mental model you will need for the rest of the tutorial."
+mental_model: "Hermes is a long-running process that owns a ~/.hermes/ directory the way a database owns its data directory — everything important (memories, skills, sessions, config) lives there, and the TUI is just one of many entry points into that persistent state."
+learning_outcomes:
+ - Install Hermes Agent via the curl installer or from source with uv
+ - Run the hermes setup wizard and understand every prompt it asks
+ - Navigate the ~/.hermes/ directory layout and know what each file does
+ - Start a first conversation and observe memory and skill files being created
+ - Run hermes claw migrate to import an existing OpenClaw configuration
+snapshot:
+ source_repo: https://github.com/nousresearch/hermes-agent
+ stars: 65972
+ language: Python
+ license: MIT
+chapter_map:
+ - cli.py
+ - hermes_cli/setup.py
+ - hermes_cli/agent/memory_manager.py
+ - hermes_cli/agent/skill_utils.py
+sources:
+ - https://github.com/nousresearch/hermes-agent
+---
+
+# Chapter 1: Getting Started
+
+## What Problem Does This Solve?
+
+Most AI agent frameworks are session-scoped: you start them, they run, you stop them, and nothing persists. The next conversation starts from a blank slate. This is fine for demos and experiments, but it is useless as a genuine personal assistant — one that remembers your projects, knows your preferences, and gets better at helping you over time.
+
+Hermes Agent solves the blank-slate problem by making persistence the default, not the exception. The `~/.hermes/` directory is the agent's brain. It accumulates episodic memories from every session, semantic facts in `MEMORY.md` and `USER.md`, and procedural knowledge in `SKILL.md` files that the agent writes and improves autonomously. When you open the TUI tomorrow, it knows what you were working on today.
+
+This chapter walks you through installation, the setup wizard, the directory layout, and your first conversation — building the foundation for everything that follows.
+
+---
+
+## System Requirements
+
+| Requirement | Minimum | Recommended |
+|---|---|---|
+| Python | 3.11 | 3.12 |
+| Package manager | pip | uv (10-100x faster) |
+| OS | Linux / macOS | Linux (full backend support) |
+| RAM | 4 GB | 16 GB (for local model backends) |
+| Docker | Optional | Required for Docker terminal backend |
+| SQLite | 3.35+ (FTS5) | Bundled with Python 3.11+ |
+
+Hermes uses `uv` for dependency management. The curl installer handles this automatically; from-source installs should install `uv` first.
+
+---
+
+## Installation
+
+### Option A: One-Line Installer (Recommended)
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/nousresearch/hermes-agent/main/install.sh | bash
+```
+
+The installer:
+1. Detects your OS and architecture
+2. Installs `uv` if not present
+3. Clones the repository to `~/.hermes-agent/`
+4. Creates a virtual environment with `uv venv`
+5. Installs all dependencies with `uv pip install -e .`
+6. Adds the `hermes` command to your PATH via a shell wrapper
+
+Verify the installation:
+
+```bash
+hermes --version
+# hermes-agent 0.x.x (NousResearch)
+```
+
+### Option B: From Source
+
+```bash
+# Prerequisites
+pip install uv # or: brew install uv
+
+# Clone and install
+git clone https://github.com/nousresearch/hermes-agent.git
+cd hermes-agent
+uv venv
+source .venv/bin/activate
+uv pip install -e .
+
+# Verify
+hermes --version
+```
+
+### Option C: Nix
+
+```bash
+nix develop # enters the devshell defined in flake.nix
+```
+
+The Nix flake pins all dependencies, making this the most reproducible option for development.
+
+---
+
+## The Setup Wizard
+
+Running `hermes setup` launches an interactive wizard that writes `~/.hermes/config.yaml`. You only need to run it once; you can re-run it any time to change settings.
+
+```bash
+hermes setup
+```
+
+```
+╔═══════════════════════════════════════════╗
+║ Hermes Agent Setup Wizard ║
+╚═══════════════════════════════════════════╝
+
+[1/6] Primary LLM provider
+ > openai / anthropic / together / openrouter / local
+ Choice: openai
+
+[2/6] API key for openai
+ Key: sk-...
+
+[3/6] Default model
+ > gpt-4o / gpt-4-turbo / gpt-3.5-turbo / custom
+ Choice: gpt-4o
+
+[4/6] Terminal backend
+ > local / docker / ssh / daytona / singularity / modal
+ Choice: local
+
+[5/6] Enable messaging gateway? (y/n): y
+ Platforms to enable (comma-separated):
+ telegram, discord, slack, ...
+
+[6/6] Agent persona name (default: Hermes): Hermes
+
+Setup complete. Config written to ~/.hermes/config.yaml
+Run 'hermes' to start.
+```
+
+### What the Wizard Configures
+
+| Wizard Step | Config Key | Effect |
+|---|---|---|
+| Primary provider | `llm.provider` | Default API endpoint for all completions |
+| API key | `llm.api_key` | Stored in config (or env var `HERMES_API_KEY`) |
+| Default model | `llm.model` | Base model; smart routing can override per-request |
+| Terminal backend | `execution.backend` | Where shell commands run (local, Docker, SSH, etc.) |
+| Gateway platforms | `gateway.enabled` | Which messaging platforms to activate |
+| Persona name | `agent.persona` | Name used in SOUL.md and TUI header |
+
+---
+
+## The `~/.hermes/` Directory Layout
+
+After setup and a first conversation, the directory looks like this:
+
+```
+~/.hermes/
+├── config.yaml # Master configuration (written by hermes setup)
+├── SOUL.md # Agent persona definition (editable)
+├── MEMORY.md # Semantic long-term memory (agent-written)
+├── USER.md # User model (agent-written via Honcho dialectic)
+├── AGENTS.md # (Optional) multi-agent context instructions
+├── hermes.md # (Optional) project/context file injected into prompts
+│
+├── skills/ # Procedural memory — SKILL.md files
+│ ├── git_workflow.md
+│ ├── python_debug.md
+│ └── ...
+│
+├── sessions/ # Episodic memory — SQLite FTS5 database
+│ └── sessions.db
+│
+├── logs/ # Structured logs per session
+│ └── session_<timestamp>.jsonl
+│
+├── trajectories/ # RL training data (Atropos format)
+│ └── traj_<timestamp>.jsonl
+│
+└── .credentials/ # Encrypted gateway credentials
+ ├── telegram.enc
+ └── discord.enc
+```
+
+### Key Files Explained
+
+**`SOUL.md`** — The agent's persona. Hermes reads this at the start of every prompt. Edit it to change the agent's name, writing style, areas of expertise, or constraints. This is the primary customization lever for individual users.
+
+**`MEMORY.md`** — Declarative long-term memory. The agent writes facts here autonomously when `memory_manager.py` decides a memory nudge is warranted. Examples: your preferred programming language, ongoing projects, important dates.
+
+**`USER.md`** — A model of you, the user. Written by the Honcho dialectic system which infers your goals, communication style, and knowledge level from conversation patterns.
+
+**`skills/`** — Directory of `SKILL.md` files. Each file is a proceduralized workflow the agent discovered was worth crystallizing. The agent both creates and improves these files autonomously.
+
+**`sessions/sessions.db`** — FTS5 SQLite database storing compressed summaries of past sessions. When you ask about something from weeks ago, `context_engine.py` performs a full-text search here and injects the relevant summary into your prompt.
+
+---
+
+## First Conversation
+
+```bash
+hermes
+```
+
+The curses TUI opens. Type your first message:
+
+```
+You: Hello! I'm starting a new Python project for data pipeline automation.
+
+Hermes: Great to meet you! A data pipeline automation project — tell me more
+ about the data sources you're working with and what kind of
+ transformations you need...
+
+ [Hermes is forming a memory about your new project...]
+```
+
+In the background, several things happen on the first substantive exchange:
+
+```
+Session Start
+ │
+ ▼
+context_engine.py ──► searches sessions.db (empty on first run)
+ │
+ ▼
+prompt_builder.py ──► assembles: SOUL.md + empty memories + no skills
+ │
+ ▼
+LLM call ──► response streamed to TUI
+ │
+ ▼
+memory_manager.py ──► evaluates: should a MEMORY.md write be triggered?
+ │ (yes: new project mentioned)
+ ▼
+MEMORY.md updated: "User started a Python data pipeline project on 2026-04-12"
+ │
+ ▼
+session recorded ──► sessions.db gets summary entry
+```
+
+---
+
+## OpenClaw Migration
+
+If you used OpenClaw (Hermes's predecessor), you can import your entire history:
+
+```bash
+hermes claw migrate
+```
+
+```
+OpenClaw Migration Tool
+=======================
+Detected ~/.openclaw/ directory.
+
+Found:
+ - 847 session records
+ - 23 skill files
+ - MEMORY.md (12 KB)
+ - USER.md (4 KB)
+ - config.yaml
+
+Migrating...
+ ✓ Sessions imported to ~/.hermes/sessions/sessions.db
+ ✓ Skills copied to ~/.hermes/skills/
+ ✓ MEMORY.md merged
+ ✓ USER.md merged
+ ✓ Config values translated
+
+Migration complete. Your OpenClaw history is now available in Hermes.
+```
+
+The migration tool handles:
+- Schema translation from OpenClaw's session format to Hermes's FTS5 schema
+- Skill file compatibility (format is identical — SKILL.md is shared between projects)
+- MEMORY.md merging (deduplication by semantic similarity)
+- Config key mapping (OpenClaw config keys → Hermes config keys)
+
+---
+
+## CLI Command Reference
+
+```bash
+hermes # Launch TUI (default)
+hermes setup # Re-run setup wizard
+hermes claw migrate # Import OpenClaw data
+hermes cron list # Show scheduled jobs
+hermes cron add <spec> # Add a cron job
+hermes gateway status # Show gateway connection states
+hermes skills list # List all SKILL.md files
+hermes skills show <name> # Display a skill
+hermes version # Print version info
+hermes --help # Full help text
+```
+
+---
+
+## Architecture Flow: From Install to First Token
+
+```mermaid
+flowchart TD
+ A[curl install.sh] --> B[uv venv + dependencies]
+ B --> C[hermes setup wizard]
+ C --> D[~/.hermes/config.yaml written]
+ D --> E[hermes command]
+ E --> F[cli.py parses args]
+ F --> G{command?}
+ G -->|no args| H[hermes_cli/tui.py — curses loop]
+ G -->|setup| I[hermes_cli/setup.py]
+ G -->|claw migrate| J[hermes_cli/migration/claw.py]
+ H --> K[user types message]
+ K --> L[context_engine.py]
+ L --> M[sessions.db FTS5 search]
+ M --> N[prompt_builder.py]
+ N --> O[LLM API call]
+ O --> P[response streamed to TUI]
+ P --> Q[memory_manager.py — nudge evaluation]
+ Q --> R{nudge needed?}
+ R -->|yes| S[MEMORY.md / USER.md updated]
+ R -->|no| T[session recorded to sessions.db]
+ S --> T
+```
+
+---
+
+## Directory Initialization Flow
+
+```mermaid
+sequenceDiagram
+ participant User
+ participant CLI as cli.py
+ participant Setup as setup.py
+ participant FS as ~/.hermes/
+
+ User->>CLI: hermes setup
+ CLI->>Setup: run_wizard()
+ Setup->>User: prompt: provider, API key, model, backend
+ User->>Setup: answers
+ Setup->>FS: mkdir ~/.hermes/
+ Setup->>FS: write config.yaml
+ Setup->>FS: write SOUL.md (default persona)
+ Setup->>FS: mkdir skills/, sessions/, logs/, trajectories/
+ Setup->>FS: initialize sessions.db (FTS5 schema)
+ Setup-->>User: "Setup complete. Run 'hermes' to start."
+```
+
+---
+
+## Environment Variables
+
+For CI/CD, Docker, or scripting use cases, every config value can be overridden with environment variables:
+
+```bash
+export HERMES_API_KEY="sk-..."
+export HERMES_MODEL="gpt-4o"
+export HERMES_PROVIDER="openai"
+export HERMES_BACKEND="docker"
+export HERMES_HOME="/custom/path/.hermes" # Override ~/.hermes location
+```
+
+Environment variables always take precedence over `config.yaml`.
+
+---
+
+## Troubleshooting
+
+| Symptom | Likely Cause | Fix |
+|---|---|---|
+| `hermes: command not found` | Shell wrapper not in PATH | Re-run installer or add `~/.hermes-agent/.venv/bin` to PATH |
+| `FTS5 not available` | Old SQLite bundled with Python | Upgrade to Python 3.11+ |
+| `API key invalid` | Wrong key in config | Run `hermes setup` again |
+| `curses import error` | Windows without WSL | Use WSL2 or Docker on Windows |
+| `Port already in use` | Gateway server conflict | Change `gateway.port` in config.yaml |
+| Setup wizard hangs | Slow API key validation | Press Ctrl+C and check network |
+
+---
+
+## Chapter Summary
+
+| Concept | Key Takeaway |
+|---|---|
+| Installation | One-line curl installer; uv manages dependencies |
+| Setup wizard | Writes ~/.hermes/config.yaml; six prompts cover all essential config |
+| ~/.hermes/ layout | Persistent state directory: SOUL.md, MEMORY.md, USER.md, skills/, sessions/ |
+| First conversation | memory_manager.py autonomously decides when to write MEMORY.md |
+| OpenClaw migration | `hermes claw migrate` imports sessions, skills, memories, and config |
+| CLI commands | `hermes`, `hermes setup`, `hermes claw migrate`, `hermes cron`, `hermes gateway` |
+| Env vars | All config overridable via HERMES_* environment variables |
diff --git a/tutorials/hermes-agent-tutorial/02-tui-and-conversation-interface.md b/tutorials/hermes-agent-tutorial/02-tui-and-conversation-interface.md
new file mode 100644
index 00000000..32e5905c
--- /dev/null
+++ b/tutorials/hermes-agent-tutorial/02-tui-and-conversation-interface.md
@@ -0,0 +1,432 @@
+---
+layout: default
+title: "Chapter 2: The TUI and Conversation Interface"
+nav_order: 2
+parent: Hermes Agent Tutorial
+format_version: v2
+why: "The TUI is the daily driver for most Hermes users. Understanding its layout, slash commands, and persona system turns a basic chat window into a precision tool that surfaces memory, manages context size, and reveals what the agent is doing internally."
+mental_model: "The Hermes TUI is a stateful terminal application, not a simple readline loop — it maintains a live view of context window usage, session state, and agent status, and its slash commands are first-class operations that reach directly into the agent's memory and session machinery."
+learning_outcomes:
+ - Navigate the curses TUI layout: input area, message history, status bar, and sidebar
+ - Use all slash commands (/new /reset /retry /compress /usage /insights) effectively
+ - Customize agent behavior by editing SOUL.md, hermes.md, and AGENTS.md
+ - Create and switch between named personas using the skin system
+ - Understand context file injection order and how it affects prompt construction
+snapshot:
+ source_repo: https://github.com/nousresearch/hermes-agent
+ stars: 65972
+ language: Python
+ license: MIT
+chapter_map:
+ - hermes_cli/tui.py
+ - hermes_cli/commands/slash_commands.py
+ - hermes_cli/agent/prompt_builder.py
+sources:
+ - https://github.com/nousresearch/hermes-agent
+---
+
+# Chapter 2: The TUI and Conversation Interface
+
+## What Problem Does This Solve?
+
+A conversational AI that runs forever and accumulates memory creates a new set of problems: how do you manage context window overflow when a session gets long? How do you start fresh without losing what you have? How do you inspect what the agent actually knows about you? How do you give it a different personality for different workflows?
+
+Hermes solves these with a purpose-built terminal UI that exposes session management, context window metering, and persona switching as first-class operations — not hidden debug commands, but visible, keyboard-accessible features you use every day.
+
+---
+
+## TUI Layout Overview
+
+When you run `hermes`, the curses-based TUI fills your terminal:
+
+```
+╔══════════════════════════════════════════════════════════════════╗
+║ Hermes [gpt-4o | local | session: research-2026-04-12] ║
+║ Context: ████████████░░░░░░░░ 47% (9,420 / 20,000 tokens) ║
+╠══════════════════════════════════════════════════════════════════╣
+║ ║
+║ [12:34] You: Can you summarize what we discussed yesterday ║
+║ about the ETL pipeline? ║
+║ ║
+║ [12:34] Hermes: From yesterday's session (Apr 11), you were ║
+║ working on a Python ETL pipeline with three stages... ║
+║ ║
+║ [12:35] You: What skills do you have for that? ║
+║ ║
+║ [12:35] Hermes: I have a skill: python_etl_patterns.md which ║
+║ covers... ║
+║ ║
+╠══════════════════════════════════════════════════════════════════╣
+║ > _ ║
+╠══════════════════════════════════════════════════════════════════╣
+║ [/new] [/reset] [/retry] [/compress] [/usage] [/insights] ║
+╚══════════════════════════════════════════════════════════════════╝
+```
+
+### UI Regions
+
+| Region | Description | Keybindings |
+|---|---|---|
+| Header bar | Session name, model, backend | Read-only |
+| Context meter | Token usage % of context window | Read-only |
+| Message history | Scrollable conversation | ↑/↓, PgUp/PgDn |
+| Input area | Multiline text entry | Enter to send, Shift+Enter for newline |
+| Command bar | Clickable slash commands | Click or type /command |
+| Status line | Agent state (thinking / streaming / idle) | Read-only |
+
+---
+
+## Slash Commands
+
+Slash commands are typed into the input area (or clicked in the command bar) and trigger operations that reach directly into the agent's session and memory machinery.
+
+### `/new` — Start a New Session
+
+```
+> /new
+```
+
+Creates a new session entry in `sessions.db`, resets the in-memory conversation history, and writes a summary of the current session before clearing. The agent's memories (MEMORY.md, USER.md, skills) persist — only the active conversation window is cleared.
+
+```
+Session "research-2026-04-12" saved to memory.
+Starting new session...
+```
+
+Use `/new` when a conversation topic has concluded and you want a clean context window without losing the memory of what happened.
+
+### `/reset` — Hard Reset
+
+```
+> /reset
+```
+
+Clears the active conversation window without saving a session summary. Use this when you want to abandon the current exchange entirely — for example, if you went down a wrong path and want to restart without poisoning the session history.
+
+**Note:** `/reset` does not delete MEMORY.md or USER.md entries. It only clears the current conversation buffer.
+
+### `/retry` — Retry Last Response
+
+```
+> /retry
+```
+
+Re-submits the last user message to the LLM, discarding the previous response. Useful when the response was cut off, hit a timeout, or was simply unsatisfactory. The prompt is rebuilt from scratch, so if memory has been updated since the last send, the retry will include those updates.
+
+### `/compress` — Compress Context
+
+```
+> /compress
+```
+
+Triggers an in-place context compression operation:
+
+1. `context_engine.py` calls the LLM with a summarization prompt over the current conversation history
+2. The raw message history is replaced with the LLM-generated summary
+3. The context meter drops significantly (typically 60-80% reduction)
+4. Conversation continues with the compressed summary as the new baseline
+
+This is the key operation for long-running sessions. Use it proactively when the context meter approaches 80% to avoid hitting the model's limit.
+
+```
+Compressing 18,400 tokens → 3,200 token summary...
+Context: ████░░░░░░░░░░░░░░░░ 16%
+```
+
+### `/usage` — Token Usage Report
+
+```
+> /usage
+```
+
+Displays a detailed breakdown of current context window utilization:
+
+```
+Context Window Usage Report
+═══════════════════════════
+Model context limit: 128,000 tokens
+System prompt: 1,847 tokens (SOUL.md + injected memories + skills)
+Conversation history: 9,420 tokens
+ ├─ User messages: 4,210 tokens
+ └─ Assistant messages: 5,210 tokens
+Available: 116,733 tokens
+
+Session cost (est.): $0.0847
+Total session cost: $1.23
+```
+
+### `/insights` — Memory and Session Insights
+
+```
+> /insights
+```
+
+Shows what the agent currently knows about you and the session:
+
+```
+Hermes Insights
+═══════════════
+Active session: research-2026-04-12 (started 47 min ago)
+Sessions in memory: 847
+Skills loaded: 7
+
+MEMORY.md entries:
+ - Python / data engineering background
+ - Prefers concise explanations with code examples
+ - Working on ETL pipeline project (started 2026-04-11)
+ - Uses VS Code + Neovim
+
+USER.md model:
+ - Communication style: technical, direct
+ - Expertise level: senior engineer
+ - Primary interests: data engineering, ML infrastructure
+
+Active skills:
+ - python_etl_patterns.md
+ - git_workflow.md
+ - docker_compose_patterns.md
+```
+
+---
+
+## SOUL.md — The Persona Definition
+
+`~/.hermes/SOUL.md` is injected at the top of every system prompt. It defines who the agent is. The default persona is Hermes — a knowledgeable, concise, technically-grounded assistant — but you can rewrite it entirely.
+
+```markdown
+# Hermes
+
+You are Hermes, a highly capable personal AI agent created by NousResearch.
+You are running on the user's local machine with access to their file system,
+terminal, and memory system.
+
+## Core Traits
+- Technically precise but not pedantic
+- Proactively suggest improvements, not just answer questions
+- Remember context across sessions — you have persistent memory
+- When uncertain, say so clearly and offer to research further
+
+## Current Context
+You have access to the following memory files:
+- MEMORY.md: long-term facts about the user and their work
+- USER.md: a model of the user's communication style and expertise
+- Active skills: see SKILL.md files loaded in this session
+
+## Constraints
+- Never fabricate information you don't have
+- When executing commands, explain what you are about to do first
+- Ask for confirmation before deleting files or making irreversible changes
+```
+
+SOUL.md is plain Markdown. You can add any instructions, constraints, or personality traits. Some users maintain multiple SOUL.md files and symlink between them.
+
+---
+
+## Context Files: hermes.md and AGENTS.md
+
+Beyond SOUL.md, two additional context files can be injected into prompts:
+
+### `~/.hermes/hermes.md`
+
+A freeform context file for project-specific or user-specific context that doesn't belong in MEMORY.md. Examples:
+
+```markdown
+# Current Project Context
+
+Working on: data-pipeline-v2
+Location: ~/projects/data-pipeline/
+Stack: Python 3.12, Apache Airflow 2.8, PostgreSQL 15, dbt
+
+## Important Notes
+- Production DB is read-only from this machine
+- Use the staging environment (staging.db) for testing
+- Deploy via: ./scripts/deploy.sh --env staging
+```
+
+### `~/.hermes/AGENTS.md`
+
+Used in multi-agent setups to define how Hermes should interact with other agents via the ACP protocol. Also used to define tool access policies:
+
+```markdown
+# Agent Configuration
+
+## Tool Access
+- file_read: unrestricted
+- file_write: ~/projects/** only
+- shell_exec: confirm before running
+- web_search: unrestricted
+
+## Sub-Agent Policy
+- Max 3 concurrent subagents
+- Subagents inherit read permissions, not write
+```
+
+---
+
+## Context File Injection Order
+
+Understanding the order in which context files are assembled into the final prompt is critical for knowing which instructions take precedence:
+
+```mermaid
+flowchart TD
+ A[prompt_builder.py starts] --> B[1. SOUL.md — base persona]
+ B --> C[2. MEMORY.md entries — long-term facts]
+ C --> D[3. USER.md entries — user model]
+ D --> E[4. Relevant SKILL.md files — procedural knowledge]
+ E --> F[5. hermes.md — project context]
+ F --> G[6. AGENTS.md — tool/agent policy]
+ G --> H[7. FTS5 session summaries — episodic memory]
+ H --> I[8. Active conversation history]
+ I --> J[Final assembled prompt → LLM]
+```
+
+Items earlier in the chain are in the system prompt position; later items appear closer to the conversation. If two instructions conflict, the later one (closer to the conversation) generally takes precedence with most LLMs.
+
+---
+
+## The Skin / Persona System
+
+Hermes supports named personas ("skins") that let you switch between different SOUL.md configurations without manually editing files.
+
+### Creating a Skin
+
+```bash
+# Create a new persona
+hermes skin create research
+# Opens SOUL.md in your $EDITOR
+# Saved as ~/.hermes/skins/research/SOUL.md
+```
+
+### Listing Skins
+
+```bash
+hermes skin list
+# Default (active)
+# research
+# coding-assistant
+# creative-writer
+```
+
+### Switching Skins
+
+```bash
+hermes skin use research
+# Persona switched to "research"
+# Restart hermes to apply
+```
+
+### Skin Directory Structure
+
+```
+~/.hermes/skins/
+├── research/
+│ ├── SOUL.md # Research-focused persona
+│ └── hermes.md # Research project context
+├── coding-assistant/
+│ ├── SOUL.md # Terse, code-first persona
+│ └── hermes.md # Codebase context
+└── creative-writer/
+ └── SOUL.md # Creative, expansive persona
+```
+
+Each skin directory can override any context file. Files not present in the skin directory fall back to the defaults in `~/.hermes/`.
+
+---
+
+## Keyboard Shortcuts
+
+| Key | Action |
+|---|---|
+| Enter | Send message |
+| Shift+Enter | Insert newline in input |
+| ↑ / ↓ | Scroll message history |
+| PgUp / PgDn | Scroll by page |
+| Ctrl+C | Exit Hermes |
+| Ctrl+L | Clear screen (redraw) |
+| Ctrl+R | Retry last message (/retry) |
+| Ctrl+N | New session (/new) |
+| Tab | Autocomplete slash command |
+| Esc | Cancel current input |
+
+---
+
+## TUI Interaction Flow
+
+```mermaid
+sequenceDiagram
+ participant User
+ participant TUI as tui.py
+ participant Cmd as slash_commands.py
+ participant Agent as prompt_builder.py
+ participant LLM as LLM API
+
+ User->>TUI: types /compress
+ TUI->>Cmd: dispatch("/compress")
+ Cmd->>Agent: compress_context(history)
+ Agent->>LLM: summarization call
+ LLM-->>Agent: compressed summary
+ Agent-->>TUI: update conversation buffer
+ TUI-->>User: context meter drops to 16%
+
+ User->>TUI: types regular message
+ TUI->>Agent: build_prompt(message)
+ Agent->>Agent: inject SOUL + memories + skills
+ Agent->>LLM: completion call
+ LLM-->>TUI: streaming response
+ TUI-->>User: response displayed token-by-token
+```
+
+---
+
+## Multi-Line Input and Code Blocks
+
+The TUI supports multi-line input for pasting code snippets or longer prompts:
+
+```
+> Please review this Python function:
+[Shift+Enter]
+def process_data(df):
+ return df.dropna().groupby('category').agg({'value': 'sum'})
+[Shift+Enter]
+Does it handle edge cases correctly?
+[Enter to send]
+```
+
+Code in responses is syntax-highlighted using curses color pairs when the terminal supports 256 colors.
+
+---
+
+## Session Naming
+
+Sessions are automatically named by date and topic:
+
+```
+session-2026-04-12-data-pipeline
+session-2026-04-11-debugging
+session-2026-04-10-setup
+```
+
+The topic portion is inferred by `context_engine.py` from the first few messages of the session. You can rename a session manually:
+
+```bash
+hermes session rename session-2026-04-12 "etl-pipeline-design"
+```
+
+---
+
+## Chapter Summary
+
+| Concept | Key Takeaway |
+|---|---|
+| TUI layout | Header, context meter, message history, input area, command bar |
+| /new | Saves current session summary, clears window, starts fresh |
+| /reset | Clears window without saving; does not affect persistent memories |
+| /retry | Rebuilds and resends last message; picks up any new memory updates |
+| /compress | LLM-powered in-place summarization; reduces context by 60-80% |
+| /usage | Detailed token breakdown and session cost estimate |
+| /insights | Shows current MEMORY.md, USER.md, and active skills |
+| SOUL.md | Top-of-prompt persona definition; fully editable Markdown |
+| hermes.md | Project-specific context injected after SOUL.md |
+| AGENTS.md | Tool access policies and multi-agent configuration |
+| Skin system | Named persona sets; switch with `hermes skin use <name>` |
+| Context order | SOUL → MEMORY → USER → SKILL → hermes.md → AGENTS.md → FTS5 → history |
diff --git a/tutorials/hermes-agent-tutorial/03-agent-core-prompt-context-routing.md b/tutorials/hermes-agent-tutorial/03-agent-core-prompt-context-routing.md
new file mode 100644
index 00000000..29882e84
--- /dev/null
+++ b/tutorials/hermes-agent-tutorial/03-agent-core-prompt-context-routing.md
@@ -0,0 +1,437 @@
+---
+layout: default
+title: "Chapter 3: Agent Core — Prompt Building, Context Engine, and Model Routing"
+nav_order: 3
+parent: Hermes Agent Tutorial
+format_version: v2
+why: "The agent core is the engine behind every response. Understanding how prompt_builder.py assembles context, how context_engine.py manages the knowledge retrieval pipeline, and how smart_model_routing.py selects and fails over between providers lets you debug slow responses, optimize costs, and build reliable multi-provider setups."
+mental_model: "Every LLM call in Hermes is not a raw API request — it is the output of a layered assembly pipeline that pulls from five distinct knowledge sources, routes through a credential pool with automatic failover, and caches aggressively to minimize cost and latency."
+learning_outcomes:
+ - Trace the full path from user input to LLM call through prompt_builder.py and context_engine.py
+ - Understand the five context sources assembled for each prompt
+ - Configure smart_model_routing.py for multi-provider failover and cost optimization
+ - Use credential_pool.py to manage multiple API keys with automatic rotation
+ - Enable and tune prompt caching to reduce token costs on repeated context
+snapshot:
+ source_repo: https://github.com/nousresearch/hermes-agent
+ stars: 65972
+ language: Python
+ license: MIT
+chapter_map:
+ - hermes_cli/agent/prompt_builder.py
+ - hermes_cli/agent/context_engine.py
+ - hermes_cli/agent/smart_routing.py
+ - hermes_cli/agent/credential_pool.py
+sources:
+ - https://github.com/nousresearch/hermes-agent
+---
+
+# Chapter 3: Agent Core — Prompt Building, Context Engine, and Model Routing
+
+## What Problem Does This Solve?
+
+LLM API calls look simple from the outside — send a string, get a string back. But a production agent needs to solve three harder problems:
+
+1. **What context goes in the prompt?** A naive agent includes the full conversation history until it overflows. Hermes instead selects the most relevant episodic memories, injects only the applicable skills, and compresses aggressively — so the context window is always used for signal, not noise.
+
+2. **Which model and provider should handle this request?** Different requests have different cost/quality tradeoffs. A quick lookup should route to a fast, cheap model. A complex coding task should go to the most capable one. If the primary provider is down or rate-limited, the agent should fail over automatically, not crash.
+
+3. **How do you avoid paying for the same tokens over and over?** The SOUL.md + MEMORY.md system prompt is nearly identical across all calls in a session. Prompt caching (supported by Anthropic's API and others) can eliminate most of that cost — but only if the cache prefix is stable.
+
+The agent core — `prompt_builder.py`, `context_engine.py`, `smart_routing.py`, and `credential_pool.py` — solves all three.
+
+---
+
+## Module Responsibilities
+
+| Module | Responsibility |
+|---|---|
+| `prompt_builder.py` | Assembles the final prompt from all context sources |
+| `context_engine.py` | Retrieves and ranks relevant episodic memories via FTS5 |
+| `smart_routing.py` | Selects the optimal model/provider per request |
+| `credential_pool.py` | Manages multiple API keys with rotation and failover |
+
+---
+
+## prompt_builder.py — The Assembly Pipeline
+
+`prompt_builder.py` is called once per user message. It produces a fully assembled prompt ready for the LLM API.
+
+### Context Sources (in assembly order)
+
+```python
+# hermes_cli/agent/prompt_builder.py (structure)
+
+class PromptBuilder:
+ def build(self, user_message: str, session_history: list) -> Prompt:
+ """
+ Assemble a complete prompt from all context sources.
+ Returns a Prompt with system_prompt, messages list, and metadata.
+ """
+ system_parts = []
+
+ # 1. Base persona
+ system_parts.append(self._load_soul()) # SOUL.md
+
+ # 2. Long-term semantic memory
+ system_parts.append(self._load_memory()) # MEMORY.md
+ system_parts.append(self._load_user_model()) # USER.md
+
+ # 3. Procedural memory — only relevant skills
+ relevant_skills = self.skill_utils.select_relevant(
+ user_message, session_history
+ )
+ system_parts.append(self._format_skills(relevant_skills))
+
+ # 4. Project context
+ if (hermes_md := self._load_hermes_md()):
+ system_parts.append(hermes_md)
+
+ # 5. Episodic memory — FTS5 search results
+ episodic = self.context_engine.retrieve(user_message)
+ if episodic:
+ system_parts.append(self._format_episodic(episodic))
+
+ system_prompt = "\n\n---\n\n".join(filter(None, system_parts))
+
+ return Prompt(
+ system=system_prompt,
+ messages=session_history + [{"role": "user", "content": user_message}],
+ model=self.router.select(user_message),
+ cache_prefix_length=len(system_prompt), # hint for caching
+ )
+```
+
+### Skill Relevance Selection
+
+Not all SKILL.md files are injected into every prompt. `skill_utils.select_relevant()` uses a lightweight TF-IDF-style scoring against the current message and recent conversation turns to select only the top-k skills most likely to be useful:
+
+```python
+# hermes_cli/agent/skill_utils.py (structure)
+
+def select_relevant(
+ message: str,
+ history: list,
+ top_k: int = 3,
+ threshold: float = 0.15
+) -> list[Skill]:
+ """
+ Returns top_k skills whose content overlaps with the current context.
+ Skills below the threshold score are excluded even if they're in top_k.
+ """
+ query_tokens = tokenize(message + " ".join(m["content"] for m in history[-5:]))
+ scored = [
+ (skill, tfidf_overlap(query_tokens, skill.tokens))
+ for skill in self.all_skills
+ ]
+ return [
+ skill for skill, score in sorted(scored, key=lambda x: -x[1])
+ if score >= threshold
+ ][:top_k]
+```
+
+This keeps the prompt tight — if you have 50 SKILL.md files, a question about Python debugging won't inject the skills about Docker networking or Terraform.
+
+---
+
+## context_engine.py — Episodic Memory Retrieval
+
+`context_engine.py` is responsible for the episodic memory layer: searching past session summaries and injecting the most relevant fragments into the current prompt.
+
+### FTS5 Search Pipeline
+
+```python
+# hermes_cli/agent/context_engine.py (structure)
+
+class ContextEngine:
+ def retrieve(self, query: str, max_results: int = 5) -> list[MemoryFragment]:
+ """
+ Search sessions.db using FTS5 for sessions relevant to the query.
+ Returns up to max_results summarized session fragments.
+ """
+ # 1. FTS5 full-text search
+ raw_results = self.db.execute(
+ """
+ SELECT session_id, summary, relevance_score, created_at
+ FROM sessions_fts
+ WHERE sessions_fts MATCH ?
+ ORDER BY rank
+ LIMIT ?
+ """,
+ (fts5_escape(query), max_results * 3) # over-fetch for re-ranking
+ ).fetchall()
+
+ # 2. Re-rank by recency * relevance
+ reranked = [
+ MemoryFragment(
+ session_id=r["session_id"],
+ summary=r["summary"],
+ score=r["relevance_score"] * recency_weight(r["created_at"]),
+ age_days=days_ago(r["created_at"])
+ )
+ for r in raw_results
+ ]
+ reranked.sort(key=lambda x: -x.score)
+
+ return reranked[:max_results]
+```
+
+### Session Summary Schema (sessions.db)
+
+```sql
+-- sessions table
+CREATE VIRTUAL TABLE sessions_fts USING fts5(
+ session_id UNINDEXED,
+ summary, -- LLM-generated summary, indexed
+ tags, -- comma-separated topic tags, indexed
+ created_at UNINDEXED,
+ relevance_score UNINDEXED
+);
+
+-- The summary column is what FTS5 searches.
+-- Summaries are written by memory_manager.py at session end,
+-- using an LLM call to condense the session to 200-500 words.
+```
+
+### Recency Weighting
+
+Recent sessions get a boost over older ones at equal relevance:
+
+```
+score = fts5_rank * recency_weight
+
+recency_weight:
+ - Last 7 days: 2.0
+ - 7–30 days: 1.5
+ - 30–90 days: 1.0
+ - 90+ days: 0.7
+```
+
+This prevents the agent from always surfacing very old sessions when recent ones are equally relevant.
+
+---
+
+## smart_routing.py — Model Selection
+
+`smart_routing.py` selects the model for each request based on a combination of request characteristics, configured routing rules, and provider availability.
+
+### Routing Decision Tree
+
+```mermaid
+flowchart TD
+ A[incoming request] --> B{explicit model requested?}
+ B -->|yes| C[use specified model]
+ B -->|no| D{classify request type}
+ D --> E{simple lookup / short?}
+ E -->|yes| F[fast_model: gpt-4o-mini / claude-haiku]
+ E -->|no| G{requires code execution?}
+ G -->|yes| H[code_model: gpt-4o / claude-sonnet]
+ G -->|no| I{long document analysis?}
+ I -->|yes| J[long_context_model: claude-3.5-sonnet]
+ I -->|no| K[default_model from config]
+ F --> L[credential_pool.get_credential]
+ H --> L
+ J --> L
+ K --> L
+ C --> L
+ L --> M{credential available?}
+ M -->|yes| N[make API call]
+ M -->|no| O[failover to next provider]
+ O --> L
+ N --> P{success?}
+ P -->|yes| Q[return response]
+ P -->|rate limit| R[exponential backoff + retry]
+ P -->|error| O
+ R --> N
+```
+
+### Routing Configuration
+
+```yaml
+# ~/.hermes/config.yaml
+
+llm:
+ routing:
+ default_model: "gpt-4o"
+ fast_model: "gpt-4o-mini"
+ code_model: "gpt-4o"
+ long_context_model: "claude-3-5-sonnet-20241022"
+
+ rules:
+ - condition: "token_estimate < 500 and not requires_tools"
+ model: fast_model
+ - condition: "has_code_block or requires_shell_execution"
+ model: code_model
+ - condition: "token_estimate > 50000"
+ model: long_context_model
+
+ providers:
+ - name: openai
+ priority: 1
+ models: [gpt-4o, gpt-4o-mini, gpt-4-turbo]
+ - name: anthropic
+ priority: 2
+ models: [claude-3-5-sonnet-20241022, claude-3-haiku-20240307]
+ - name: together
+ priority: 3
+ models: [meta-llama/Llama-3.3-70b-Instruct-Turbo]
+ - name: local
+ priority: 4
+ models: [hermes-3-llama-3.1-8b]
+ endpoint: "http://localhost:11434/v1"
+```
+
+---
+
+## credential_pool.py — Multi-Key Management
+
+`credential_pool.py` manages a pool of API credentials, enabling key rotation (to stay under per-key rate limits) and provider failover (to survive provider outages).
+
+### Pool Configuration
+
+```yaml
+# ~/.hermes/config.yaml
+
+credentials:
+ openai:
+ keys:
+ - key: "sk-proj-abc..."
+ weight: 1.0
+ max_rpm: 500
+ - key: "sk-proj-def..."
+ weight: 1.0
+ max_rpm: 500
+ rotation_strategy: "round_robin" # or "least_loaded"
+
+ anthropic:
+ keys:
+ - key: "sk-ant-..."
+ weight: 1.0
+ rotation_strategy: "least_loaded"
+```
+
+### How Key Selection Works
+
+```python
+# hermes_cli/agent/credential_pool.py (structure)
+
+class CredentialPool:
+ def get_credential(self, provider: str, model: str) -> Credential:
+ """
+ Returns the best available credential for this provider.
+ Raises NoCredentialAvailable if all keys are exhausted/failed.
+ """
+ available = [
+ c for c in self.pool[provider]
+ if not c.is_rate_limited() and not c.is_failed()
+ ]
+ if not available:
+ raise NoCredentialAvailable(provider)
+
+ if self.config.rotation_strategy == "round_robin":
+ return available[self._next_index % len(available)]
+ elif self.config.rotation_strategy == "least_loaded":
+ return min(available, key=lambda c: c.current_rpm)
+
+ def mark_rate_limited(self, credential: Credential, retry_after: int):
+ """Called when a 429 response is received."""
+ credential.rate_limited_until = time.time() + retry_after
+
+ def mark_failed(self, credential: Credential, error: Exception):
+ """Called on non-recoverable error. Removes key from rotation."""
+ credential.failed = True
+ self._alert(f"Credential {credential.key[:8]}... failed: {error}")
+```
+
+---
+
+## Prompt Caching
+
+The system prompt assembled by `prompt_builder.py` — which includes SOUL.md, MEMORY.md, USER.md, and skills — is typically 1,500–4,000 tokens. For providers that support prompt caching (Anthropic, some OpenAI configs), Hermes sends a cache-control header on the system prompt to eliminate recomputation costs for repeated calls in the same session.
+
+### How Cache Stability Is Maintained
+
+The cache prefix is only effective if it doesn't change between calls. `prompt_builder.py` ensures this by:
+
+1. Ordering all context sources deterministically (SOUL → MEMORY → USER → SKILLS in alphabetical order)
+2. Never including timestamps or session IDs in the system prompt (these go in the first user message)
+3. Using a dirty-flag mechanism: the system prompt is only rebuilt when MEMORY.md or USER.md has changed
+
+```python
+# hermes_cli/agent/prompt_builder.py (cache logic)
+
+def build(self, message: str, history: list) -> Prompt:
+ if self._system_dirty or not self._cached_system:
+ self._cached_system = self._assemble_system()
+ self._system_dirty = False
+
+ # Cache prefix is the full system prompt.
+ # Only the messages list changes between calls.
+ return Prompt(
+ system=self._cached_system,
+ messages=history + [{"role": "user", "content": message}],
+ cache_control={"type": "ephemeral"} # Anthropic API header
+ )
+```
+
+On Anthropic's API with prompt caching enabled, a typical Hermes session saves approximately 40-60% of input token costs.
+
+---
+
+## Error Handling and Resilience
+
+```mermaid
+sequenceDiagram
+ participant PB as prompt_builder.py
+ participant Router as smart_routing.py
+ participant Pool as credential_pool.py
+ participant API as LLM API
+
+ PB->>Router: select_model(request)
+ Router->>Pool: get_credential(provider, model)
+ Pool-->>Router: credential_A
+ Router->>API: POST /v1/chat/completions
+ API-->>Router: 429 Too Many Requests (retry-after: 30s)
+ Router->>Pool: mark_rate_limited(credential_A, 30)
+ Router->>Pool: get_credential(provider, model)
+ Pool-->>Router: credential_B (different key)
+ Router->>API: POST /v1/chat/completions
+ API-->>Router: 500 Internal Server Error
+ Router->>Pool: mark_failed(credential_B)
+ Router->>Router: failover to next provider (anthropic)
+ Router->>Pool: get_credential(anthropic, fallback_model)
+ Pool-->>Router: credential_C
+ Router->>API: POST /v1/messages
+ API-->>Router: 200 OK
+ Router-->>PB: response
+```
+
+---
+
+## Performance Tuning
+
+| Config Key | Default | Effect |
+|---|---|---|
+| `llm.routing.fast_model` | gpt-4o-mini | Used for simple/short requests |
+| `llm.stream` | true | Token-by-token streaming in TUI |
+| `llm.cache_system_prompt` | true | Prompt caching (Anthropic/compatible) |
+| `context_engine.max_results` | 5 | Max episodic memories per prompt |
+| `context_engine.recency_bias` | 1.5 | Multiplier for recent session scores |
+| `skill_utils.top_k` | 3 | Max skills injected per prompt |
+| `skill_utils.threshold` | 0.15 | Minimum TF-IDF overlap to inject |
+| `credential_pool.rotation` | round_robin | Key rotation strategy |
+| `credential_pool.retry_budget` | 3 | Max retries before failover |
+
+---
+
+## Chapter Summary
+
+| Module | Key Takeaway |
+|---|---|
+| prompt_builder.py | Five-source assembly pipeline: SOUL → MEMORY → USER → SKILL → EPISODIC |
+| context_engine.py | FTS5 full-text search over session summaries + recency re-ranking |
+| skill_utils.py | TF-IDF skill selection — only injects skills relevant to current message |
+| smart_routing.py | Rule-based model selection by request type + provider priority failover |
+| credential_pool.py | Multi-key rotation with rate-limit tracking and failed-key removal |
+| Prompt caching | System prompt cached across calls; dirty flag prevents unnecessary rebuilds |
+| Error resilience | 429 → key rotation → provider failover; full audit trail in logs |
diff --git a/tutorials/hermes-agent-tutorial/04-memory-skills-learning-loop.md b/tutorials/hermes-agent-tutorial/04-memory-skills-learning-loop.md
new file mode 100644
index 00000000..99300567
--- /dev/null
+++ b/tutorials/hermes-agent-tutorial/04-memory-skills-learning-loop.md
@@ -0,0 +1,621 @@
+---
+layout: default
+title: "Chapter 4: Memory, Skills, and the Learning Loop"
+nav_order: 4
+parent: Hermes Agent Tutorial
+format_version: v2
+why: "Memory and skills are what separate Hermes from a stateless chatbot wrapper. This chapter explains the three-layer memory architecture, how the agent autonomously decides when to write and improve memories, and how the closed learning loop turns real conversations into self-improving procedural knowledge."
+mental_model: "Think of Hermes's memory as three filing systems working in parallel: a searchable archive of past sessions (episodic), a set of declarative fact sheets about you and your world (semantic), and a library of how-to guides the agent has written for itself (procedural). The agent reads all three on every turn and writes to them whenever it judges it worthwhile."
+learning_outcomes:
+ - Explain the three memory layers and when each one is used
+ - Understand how memory_manager.py decides when to trigger MEMORY.md and USER.md writes
+ - Query and inspect the FTS5 session database
+ - Read and write SKILL.md files manually and understand the autonomous creation/improvement cycle
+ - Configure Honcho user modeling and understand what USER.md contains
+ - Understand agentskills.io as a community skill distribution channel
+snapshot:
+ source_repo: https://github.com/nousresearch/hermes-agent
+ stars: 65972
+ language: Python
+ license: MIT
+chapter_map:
+ - hermes_cli/agent/memory_manager.py
+ - hermes_cli/agent/skill_utils.py
+ - hermes_cli/agent/context_engine.py
+ - hermes_cli/sessions/sessions.db
+sources:
+ - https://github.com/nousresearch/hermes-agent
+---
+
+# Chapter 4: Memory, Skills, and the Learning Loop
+
+## What Problem Does This Solve?
+
+A personal AI agent faces a fundamental tension: it needs to remember enormous amounts of context to be genuinely useful, but LLM context windows are finite and expensive. Naively keeping everything in the prompt doesn't scale. Throwing everything away between sessions makes the agent forget-prone and frustrating.
+
+Hermes resolves this tension with a three-layer memory architecture that stores different types of knowledge in the form best suited to their retrieval patterns:
+
+- **Episodic memory** is searchable by content — you retrieve it when you need to recall what happened
+- **Semantic memory** is always-available facts — injected into every prompt because they're always relevant
+- **Procedural memory** is skills — injected selectively when the agent recognizes a task it has proceduralized
+
+The result is an agent that uses its context window efficiently: only the most relevant episodic fragments, only the applicable skills, but always the core user model and preferences.
+
+---
+
+## The Three Memory Layers
+
+```mermaid
+graph TD
+ subgraph Episodic["Episodic Memory (sessions.db)"]
+ E1[Session summaries — FTS5 SQLite]
+ E2[LLM-generated 200-500 word summaries]
+ E3[Written at session end by memory_manager.py]
+ E4[Retrieved by context_engine.py via FTS5 search]
+ end
+
+ subgraph Semantic["Semantic Memory (MEMORY.md / USER.md)"]
+ S1[MEMORY.md — long-term facts about work/projects]
+ S2[USER.md — user model: style, expertise, goals]
+ S3[Written autonomously by memory_manager.py nudges]
+ S4[Injected into EVERY prompt via prompt_builder.py]
+ S5[Honcho dialectic updates USER.md continuously]
+ end
+
+ subgraph Procedural["Procedural Memory (SKILL.md files)"]
+ P1[SKILL.md files in ~/.hermes/skills/]
+ P2[Created by agent when complex task is completed]
+ P3[Self-improved by agent when used and found lacking]
+ P4[Injected selectively by skill_utils.select_relevant]
+ P5[Shareable via agentskills.io hub]
+ end
+
+ Episodic --> PromptBuilder[prompt_builder.py]
+ Semantic --> PromptBuilder
+ Procedural --> PromptBuilder
+ PromptBuilder --> LLM[LLM Call]
+```
+
+---
+
+## Episodic Memory: FTS5 Session Search
+
+### How Sessions Are Stored
+
+At the end of every conversation (triggered by `/new`, graceful exit, or a configurable inactivity timeout), `memory_manager.py` calls the LLM to produce a compact summary of the session:
+
+```python
+# hermes_cli/agent/memory_manager.py (session summary flow)
+
+async def summarize_and_store(self, session: Session):
+ """
+ Called when a session ends. Generates an LLM summary and
+ stores it in sessions.db for future FTS5 retrieval.
+ """
+ summary_prompt = f"""
+ Summarize this conversation in 200-400 words.
+ Focus on: decisions made, facts established, tasks completed,
+ and any important context that would help recall this session.
+
+ Conversation:
+ {session.format_for_summary()}
+ """
+ summary = await self.llm.complete(summary_prompt, model=self.fast_model)
+
+ # Extract topic tags for additional FTS5 signal
+ tags = await self.extract_tags(summary)
+
+ self.db.execute(
+ """
+ INSERT INTO sessions_fts(session_id, summary, tags, created_at, relevance_score)
+ VALUES (?, ?, ?, ?, 1.0)
+ """,
+ (session.id, summary, ",".join(tags), session.created_at)
+ )
+```
+
+### Querying Sessions Directly
+
+You can query the sessions database directly:
+
+```bash
+# List recent sessions
+hermes session list --limit 10
+
+# Search sessions by content
+hermes session search "ETL pipeline"
+
+# Show a specific session summary
+hermes session show session-2026-04-11-debugging
+
+# Export all session summaries
+hermes session export --format json > sessions_backup.json
+```
+
+Or query the SQLite database directly:
+
+```bash
+sqlite3 ~/.hermes/sessions/sessions.db \
+ "SELECT session_id, substr(summary, 1, 100) FROM sessions_fts
+ WHERE sessions_fts MATCH 'ETL pipeline'
+ ORDER BY rank LIMIT 5;"
+```
+
+### FTS5 Schema
+
+```sql
+CREATE VIRTUAL TABLE sessions_fts USING fts5(
+ session_id UNINDEXED, -- not searched, just stored
+ summary, -- main search field
+ tags, -- topic tags for boosting
+ created_at UNINDEXED,
+ relevance_score UNINDEXED,
+
+ -- FTS5 options
+ tokenize = "unicode61", -- handles unicode, punctuation
+ content = sessions_raw, -- content table for snippet generation
+ content_rowid = id
+);
+
+-- The raw sessions table (content store)
+CREATE TABLE sessions_raw (
+ id INTEGER PRIMARY KEY,
+ session_id TEXT UNIQUE,
+ summary TEXT,
+ tags TEXT,
+ created_at REAL,
+ relevance_score REAL DEFAULT 1.0,
+ message_count INTEGER,
+ token_count INTEGER
+);
+```
+
+---
+
+## Semantic Memory: MEMORY.md and USER.md
+
+### memory_manager.py — The Nudge System
+
+The most distinctive aspect of Hermes's memory system is that the agent decides autonomously when to update its own semantic memory. It doesn't ask you to save facts — it infers when a fact is worth saving and writes it without interrupting the conversation.
+
+This is implemented via "nudge evaluation" — a lightweight classifier that runs after each assistant response:
+
+```python
+# hermes_cli/agent/memory_manager.py (nudge evaluation)
+
+NUDGE_TRIGGERS = [
+ # Pattern: agent should write to MEMORY.md
+ "user mentioned a new project",
+ "user stated a preference",
+ "important date or deadline mentioned",
+ "technology choice made",
+ "architecture decision recorded",
+ "new person mentioned with context",
+]
+
+USER_NUDGE_TRIGGERS = [
+ # Pattern: agent should update USER.md
+ "user corrected the agent's assumption about expertise",
+ "user communication style shift detected",
+ "user expressed frustration with response style",
+ "user demonstrated knowledge in new domain",
+]
+
+async def evaluate_nudge(
+ self,
+ user_message: str,
+ assistant_response: str,
+ recent_history: list
+) -> NudgeDecision:
+ """
+ Lightweight LLM call to determine if a memory write is warranted.
+ Uses a fast model (e.g., gpt-4o-mini) to keep latency low.
+ """
+ prompt = f"""
+ Based on this exchange, should the agent update its long-term memory?
+
+ User: {user_message}
+ Assistant: {assistant_response[:500]}
+
+ Respond with JSON:
+ {{
+ "memory_write": boolean,
+ "user_write": boolean,
+ "memory_entry": "string or null",
+ "user_entry": "string or null",
+ "reasoning": "brief explanation"
+ }}
+ """
+ result = await self.llm.complete_json(prompt, model=self.fast_model)
+ return NudgeDecision(**result)
+```
+
+### What Gets Written to MEMORY.md
+
+MEMORY.md is a human-readable Markdown file that the agent appends to and reorganizes:
+
+```markdown
+# Long-Term Memory
+
+## Projects
+- **data-pipeline-v2**: Python ETL project, started 2026-04-11. Using Apache Airflow 2.8, PostgreSQL 15, dbt. Location: ~/projects/data-pipeline/
+- **hermes-agent-fork**: Contributing to NousResearch/hermes-agent. Focus: improving FTS5 search ranking.
+
+## Preferences
+- Prefers concise explanations with working code examples over theoretical exposition
+- Uses VS Code as primary editor, Neovim for quick edits
+- Prefer Python type hints in all new code
+- Dark mode terminals only
+
+## Technology Context
+- Primary language: Python 3.12
+- Database of choice: PostgreSQL for production, SQLite for local tooling
+- Infrastructure: Docker + Kubernetes, deployed to AWS EKS
+
+## Important Dates
+- Project deadline: data-pipeline-v2 demo on 2026-05-01
+```
+
+### What Gets Written to USER.md
+
+USER.md is maintained by the Honcho dialectic system and tracks the user model:
+
+```markdown
+# User Model
+
+## Communication Style
+- Technical, direct, no filler phrases
+- Prefers bullet points over prose for lists
+- Appreciates when agent admits uncertainty
+- Dislikes over-explanation of things they clearly know
+
+## Expertise Level
+- Senior software engineer (8+ years)
+- Expert: Python, data engineering, SQL
+- Proficient: DevOps, Kubernetes, Terraform
+- Learning: ML infrastructure, RL training pipelines
+
+## Interaction Patterns
+- Usually works in evening sessions (18:00–23:00 UTC)
+- Asks focused questions; rarely needs prompting for context
+- Prefers to see reasoning process for complex decisions
+- Occasionally frustration with overly cautious responses
+
+## Goals
+- Build a production-grade data platform
+- Contribute to open-source AI tooling
+- Learn RL training pipeline design
+```
+
+---
+
+## Honcho Dialectic User Modeling
+
+Honcho is an external service integrated with Hermes for dialectic user modeling — a technique where the user model is refined through an ongoing implicit dialogue between what the agent infers and what the user's behavior confirms or contradicts.
+
+```mermaid
+sequenceDiagram
+ participant User
+ participant Hermes as Hermes (hermes_cli)
+ participant MemMgr as memory_manager.py
+ participant Honcho as Honcho Service
+
+ User->>Hermes: message (showing technical expertise)
+ Hermes->>MemMgr: evaluate_nudge(message, response)
+ MemMgr->>Honcho: update_user_model(observation)
+ Honcho-->>MemMgr: updated_user_state
+ MemMgr->>MemMgr: write to USER.md if significant change
+
+ Note over Honcho: Honcho maintains a probabilistic user model
+ Note over Honcho: Updated after every interaction
+ Note over MemMgr: Only writes USER.md when change exceeds threshold
+```
+
+Honcho can be configured in `config.yaml`:
+
+```yaml
+honcho:
+ enabled: true
+ endpoint: "https://api.honcho.dev/v1"
+ api_key: "hk-..."
+ sync_interval: 10 # sync USER.md every N interactions
+ local_fallback: true # use local heuristics if Honcho is unavailable
+```
+
+---
+
+## Procedural Memory: SKILL.md Files
+
+### SKILL.md Format
+
+Each skill file is a structured Markdown document with a defined schema:
+
+```markdown
+---
+skill_id: python_etl_patterns
+created: 2026-04-11
+last_improved: 2026-04-12
+improvement_count: 3
+trigger_phrases: ["etl", "data pipeline", "extract transform load", "airflow"]
+confidence: 0.87
+---
+
+# Skill: Python ETL Patterns
+
+## When to Use This Skill
+Use this skill when the user is working on data extraction, transformation,
+or loading tasks in Python.
+
+## Pattern: Idempotent Airflow DAG
+
+```python
+from airflow import DAG
+from airflow.operators.python import PythonOperator
+from datetime import datetime, timedelta
+
+def idempotent_etl(**context):
+ execution_date = context['execution_date']
+ # Use execution_date to ensure idempotency
+ process_for_date(execution_date)
+
+dag = DAG(
+ 'etl_pipeline',
+ start_date=datetime(2026, 1, 1),
+ schedule_interval='@daily',
+ catchup=False, # Important: prevent historical backfill
+ max_active_runs=1 # Prevent concurrent runs
+)
+```
+
+## Common Pitfalls
+1. Not handling idempotency — always parameterize by execution date
+2. Missing error handling on external API calls — use try/except + retries
+3. Missing logging — use Airflow's built-in task logging
+4. Not testing DAGs locally — use `airflow dags test` before deployment
+
+## Improvement Notes
+- v1: Basic DAG template
+- v2: Added idempotency pattern after user hit duplicate data bug
+- v3: Added local testing guidance after user asked about testing
+```
+
+### Autonomous Skill Creation
+
+The agent creates a new skill file when it detects it has provided a complex, reusable workflow. This is triggered by `skill_utils.py`'s post-response analysis:
+
+```python
+# hermes_cli/agent/skill_utils.py (skill creation flow)
+
+async def evaluate_skill_creation(
+ self,
+ user_message: str,
+ assistant_response: str,
+ response_length: int,
+ tool_calls_made: list
+) -> SkillCreationDecision:
+ """
+ Decide if this interaction warrants creating a new SKILL.md.
+
+ Heuristics:
+ - Response contained a reusable code pattern
+ - Multiple tool calls were orchestrated in a non-obvious way
+ - User asked about a general pattern (not a one-off)
+ - Response is long (>500 tokens) and structured
+ """
+ if response_length < 200:
+ return SkillCreationDecision(create=False)
+
+ # Check against existing skills to avoid duplication
+ similar = self.find_similar_skill(user_message, threshold=0.8)
+ if similar:
+ # Improve existing skill instead of creating new one
+ return SkillCreationDecision(
+ create=False,
+ improve=similar,
+ improvement_type="extend"
+ )
+
+ # Ask LLM to evaluate and optionally generate the skill
+ decision = await self.llm.complete_json(
+ self._skill_creation_prompt(user_message, assistant_response),
+ model=self.fast_model
+ )
+
+ if decision["create"]:
+ await self._write_skill(decision["skill_content"])
+
+ return SkillCreationDecision(**decision)
+```
+
+### Autonomous Skill Improvement
+
+When an existing skill is used and the agent finds it lacking or outdated, it can improve the skill in-place:
+
+```python
+# hermes_cli/agent/skill_utils.py (skill improvement)
+
+async def improve_skill(
+ self,
+ skill: Skill,
+ improvement_context: str
+) -> bool:
+ """
+ Called when agent used a skill but found it needed updating.
+ Rewrites the skill with improvements and bumps improvement_count.
+ """
+ improved_content = await self.llm.complete(
+ f"""
+ Improve this skill based on the following context:
+
+ Context: {improvement_context}
+
+ Current skill:
+ {skill.content}
+
+ Produce an improved version that:
+ 1. Fixes any issues discovered in context
+ 2. Adds the new pattern/insight from context
+ 3. Updates the improvement notes section
+ 4. Increments improvement_count in frontmatter
+ """,
+ model=self.capable_model
+ )
+
+ # Write atomically
+ tmp_path = skill.path.with_suffix('.tmp')
+ tmp_path.write_text(improved_content)
+ tmp_path.rename(skill.path)
+
+ skill.improvement_count += 1
+ return True
+```
+
+---
+
+## agentskills.io — The Community Skills Hub
+
+Hermes integrates with [agentskills.io](https://agentskills.io), a community platform for sharing SKILL.md files between users.
+
+### Publishing a Skill
+
+```bash
+# Publish a skill to agentskills.io
+hermes skills publish python_etl_patterns
+
+# Output:
+# Skill published: https://agentskills.io/skills/python_etl_patterns
+# Stars: 0 Downloads: 0
+```
+
+### Installing Community Skills
+
+```bash
+# Search for skills
+hermes skills search "kubernetes deployment"
+
+# Install a skill
+hermes skills install kubernetes-deployment-patterns
+
+# List installed skills
+hermes skills list
+```
+
+### Skill Metadata for Discovery
+
+```yaml
+# SKILL.md frontmatter for agentskills.io submission
+---
+skill_id: python_etl_patterns
+author: johnxie
+version: "1.3.0"
+tags: [python, etl, airflow, data-engineering]
+description: "Battle-tested patterns for Python ETL pipelines with Airflow"
+requires_tools: [file_read, shell_exec]
+tested_with: [gpt-4o, claude-3-5-sonnet, hermes-3-llama-3.1-70b]
+license: MIT
+---
+```
+
+---
+
+## Memory Architecture Flow
+
+```mermaid
+flowchart LR
+ subgraph Input
+ UM[User Message]
+ end
+
+ subgraph Retrieval
+ FTS[FTS5 Search\nsessions.db]
+ SK[Skill Selection\nskill_utils.py]
+ MM[MEMORY.md read]
+ UM2[USER.md read]
+ end
+
+ subgraph Assembly
+ PB[prompt_builder.py]
+ end
+
+ subgraph LLM
+ API[LLM Call]
+ RESP[Response]
+ end
+
+ subgraph PostProcess["Post-Processing"]
+ NE[Nudge Evaluator\nmemory_manager.py]
+ SE[Session End\nSummarizer]
+ SCR[Skill Creator\nskill_utils.py]
+ end
+
+ subgraph Storage
+ SDB[(sessions.db\nFTS5)]
+ MEMD[MEMORY.md]
+ USERD[USER.md]
+ SKILLF[skills/*.md]
+ end
+
+ UM --> FTS
+ UM --> SK
+ MM --> PB
+ UM2 --> PB
+ FTS --> PB
+ SK --> PB
+ PB --> API
+ API --> RESP
+ RESP --> NE
+ RESP --> SCR
+ RESP --> SE
+ NE -->|fact worth saving| MEMD
+ NE -->|user model update| USERD
+ SE -->|session end| SDB
+ SCR -->|new reusable pattern| SKILLF
+```
+
+---
+
+## Memory Configuration
+
+```yaml
+# ~/.hermes/config.yaml
+
+memory:
+ episodic:
+ max_results: 5 # Max session fragments per prompt
+ recency_weight:
+ 7_days: 2.0
+ 30_days: 1.5
+ 90_days: 1.0
+ older: 0.7
+ summary_model: "gpt-4o-mini" # Fast model for session summarization
+
+ semantic:
+ max_memory_entries: 100 # Trim MEMORY.md when it exceeds this
+ max_user_entries: 50 # Trim USER.md when it exceeds this
+ honcho_enabled: true
+
+ procedural:
+ skills_dir: "~/.hermes/skills"
+ max_skills_injected: 3
+ relevance_threshold: 0.15
+ auto_create: true # Allow autonomous skill creation
+ auto_improve: true # Allow autonomous skill improvement
+ agentskills_sync: false # Auto-sync with agentskills.io
+```
+
+---
+
+## Chapter Summary
+
+| Concept | Key Takeaway |
+|---|---|
+| Episodic memory | FTS5 SQLite session summaries; searched by content + recency on every prompt |
+| Semantic memory | MEMORY.md (facts) + USER.md (user model); always injected, agent-written |
+| Procedural memory | SKILL.md files; selectively injected by TF-IDF; autonomously created and improved |
+| memory_manager.py | Evaluates after every response whether a memory nudge is warranted |
+| Nudge system | Lightweight LLM classifier using fast model; runs asynchronously |
+| Session summarization | LLM generates 200-500 word summary at session end; stored in FTS5 |
+| Honcho dialectic | External service for probabilistic user modeling; falls back to local heuristics |
+| Skill creation | Triggered when agent provides a complex reusable pattern |
+| Skill improvement | Agent rewrites skill file when it finds the current version lacking |
+| agentskills.io | Community skill hub; install/publish via `hermes skills` commands |
diff --git a/tutorials/hermes-agent-tutorial/05-messaging-gateway.md b/tutorials/hermes-agent-tutorial/05-messaging-gateway.md
new file mode 100644
index 00000000..9edeb25d
--- /dev/null
+++ b/tutorials/hermes-agent-tutorial/05-messaging-gateway.md
@@ -0,0 +1,497 @@
+---
+layout: default
+title: "Chapter 5: The Messaging Gateway"
+nav_order: 5
+parent: Hermes Agent Tutorial
+format_version: v2
+why: "The messaging gateway is what transforms Hermes from a local TUI tool into a persistent personal AI available on any device or platform you already use. Understanding its architecture lets you add platforms, debug delivery failures, and build production-grade integrations without reinventing the wheel."
+mental_model: "The gateway is a single message bus with pluggable platform adapters on one end and the Hermes agent core on the other. Every platform — Telegram, Discord, Slack, or a raw webhook — delivers its messages into the same normalized event queue, where session routing ensures each user and platform has isolated memory context."
+learning_outcomes:
+ - Understand the gateway's internal message bus and session routing architecture
+ - Configure and pair any of the 20+ supported messaging platforms
+ - Understand delivery pipeline stages from raw platform event to agent response
+ - Set up the OpenAI-compatible API server mode for programmatic access
+ - Debug common gateway failures using gateway logs and status commands
+snapshot:
+ source_repo: https://github.com/nousresearch/hermes-agent
+ stars: 65972
+ language: Python
+ license: MIT
+chapter_map:
+ - hermes_cli/gateway/
+ - hermes_cli/gateway/telegram.py
+ - hermes_cli/gateway/discord.py
+ - hermes_cli/gateway/api_server.py
+ - hermes_cli/gateway/session_router.py
+sources:
+ - https://github.com/nousresearch/hermes-agent
+---
+
+# Chapter 5: The Messaging Gateway
+
+## What Problem Does This Solve?
+
+A personal AI agent that only works when you're sitting at a terminal is a limited tool. Most productive moments happen in motion — on a phone, in a chat app, in an email thread. Hermes's messaging gateway solves this by bringing the full agent experience — persistent memory, skill execution, tool use — to any platform you already use.
+
+The challenge is not just supporting many platforms; it's doing so without fragmenting the agent's memory. A message sent from Telegram and a message sent from Discord should feel like parts of the same continuous conversation, not isolated sessions with different agents. The gateway's session routing system ensures this.
+
+---
+
+## Supported Platforms
+
+| Category | Platforms |
+|---|---|
+| Consumer messaging | Telegram, WhatsApp, Signal, SMS |
+| Team communication | Slack, Discord, Mattermost |
+| Email | SMTP/IMAP (any email provider) |
+| Federated / open | Matrix (Element) |
+| Enterprise Asian platforms | Feishu (Lark), DingTalk, WeCom (Enterprise WeChat), Weixin |
+| Smart home | Home Assistant |
+| Programmatic | Webhook (generic HTTP), OpenAI-compatible API server |
+
+Total: 20+ platform adapters.
+
+---
+
+## Gateway Architecture
+
+```mermaid
+flowchart TD
+ subgraph Platforms
+ TG[Telegram]
+ DC[Discord]
+ SL[Slack]
+ WA[WhatsApp]
+ SI[Signal]
+ EM[Email]
+ MX[Matrix]
+ WH[Webhook]
+ API[API Server]
+ OT[... 11 more]
+ end
+
+ subgraph Gateway["hermes_cli/gateway/"]
+ direction TB
+ TGA[telegram.py\nadapter]
+ DCA[discord.py\nadapter]
+ SLA[slack.py\nadapter]
+ WHA[whatsapp.py\nadapter]
+ SIA[signal.py\nadapter]
+ EMA[email.py\nadapter]
+ MXA[matrix.py\nadapter]
+ WHA2[webhook.py\nadapter]
+ APIA[api_server.py\nadapter]
+ end
+
+ subgraph Core
+ BUS[Message Bus\nasync queue]
+ SR[session_router.py\nplatform+user → session_id]
+ AGENT[Agent Core\nprompt_builder + LLM]
+ DEL[Delivery Pipeline\nformat + retry + ack]
+ end
+
+ TG --> TGA --> BUS
+ DC --> DCA --> BUS
+ SL --> SLA --> BUS
+ WA --> WHA --> BUS
+ SI --> SIA --> BUS
+ EM --> EMA --> BUS
+ MX --> MXA --> BUS
+ WH --> WHA2 --> BUS
+ API --> APIA --> BUS
+
+ BUS --> SR --> AGENT --> DEL
+ DEL -->|formatted response| TGA
+ DEL -->|formatted response| DCA
+ DEL -->|formatted response| SLA
+```
+
+---
+
+## The Normalized Message Event
+
+All platform adapters convert their native message format into a unified `GatewayMessage` object before queuing:
+
+```python
+# hermes_cli/gateway/types.py
+
+@dataclass
+class GatewayMessage:
+ # Identity
+ platform: str # "telegram", "discord", "slack", etc.
+ platform_user_id: str # platform-native user identifier
+ platform_chat_id: str # channel/room/thread identifier
+
+ # Content
+ content: str # normalized text content
+ attachments: list[Attachment] # files, images, voice notes
+
+ # Metadata
+ timestamp: float # unix timestamp
+ message_id: str # platform-native message ID (for threading)
+ reply_to: str | None # if this is a reply to another message
+
+ # Routing
+ session_id: str | None # set by session_router.py
+ user_profile: UserProfile | None # set by session_router.py
+```
+
+---
+
+## Session Routing
+
+`session_router.py` maps each incoming message to the correct Hermes session. This is the mechanism that ensures cross-platform memory continuity.
+
+```python
+# hermes_cli/gateway/session_router.py (structure)
+
+class SessionRouter:
+ def route(self, message: GatewayMessage) -> RoutedMessage:
+ """
+ Determine the session_id for this message.
+
+ Routing logic:
+ 1. Check if (platform, platform_user_id) is paired with a Hermes user
+ 2. If paired, use the user's primary session_id
+ 3. If not paired, create an anonymous session for this platform+user combo
+ 4. If pairing_required=true and not paired, drop the message
+ """
+ pairing = self.pairing_db.lookup(
+ platform=message.platform,
+ platform_user_id=message.platform_user_id
+ )
+
+ if pairing:
+ session_id = pairing.hermes_user_id
+ user_profile = pairing.user_profile
+ elif self.config.require_pairing:
+ return RoutedMessage(drop=True, reason="unpaired_user")
+ else:
+ session_id = f"anon_{message.platform}_{message.platform_user_id}"
+ user_profile = None
+
+ return RoutedMessage(
+ message=message,
+ session_id=session_id,
+ user_profile=user_profile,
+ drop=False
+ )
+```
+
+### Cross-Platform Memory Continuity
+
+When a user is paired (linked to a Hermes identity), their session_id is their Hermes user ID — the same ID used by the TUI. This means:
+
+- A conversation started in the TUI can be continued on Telegram
+- Skills created via the TUI are available when messaging from Discord
+- MEMORY.md and USER.md are shared across all platforms
+- `/insights` from Telegram shows the same memory as `/insights` in the TUI
+
+---
+
+## Platform Configuration
+
+Each platform is enabled and configured in `~/.hermes/config.yaml`:
+
+```yaml
+gateway:
+ enabled: true
+ port: 8080 # Port for webhook receivers and API server
+ require_pairing: true # Reject messages from unpaired users
+
+ platforms:
+ telegram:
+ enabled: true
+ token: "7123456789:AAF..."
+ webhook_url: "https://yourserver.com/hermes/telegram"
+ allowed_user_ids: [123456789] # Optional allowlist
+
+ discord:
+ enabled: true
+ bot_token: "MTIz..."
+ guild_ids: [1234567890123456789] # Optional server allowlist
+
+ slack:
+ enabled: true
+ bot_token: "xoxb-..."
+ app_token: "xapp-..." # For Socket Mode (no public URL needed)
+
+ whatsapp:
+ enabled: false # Requires Meta Business API approval
+ phone_number_id: "..."
+ access_token: "..."
+
+ signal:
+ enabled: true
+ signal_cli_path: "/usr/local/bin/signal-cli"
+ phone_number: "+15555551234"
+
+ email:
+ enabled: true
+ smtp_host: "smtp.gmail.com"
+ smtp_port: 587
+ imap_host: "imap.gmail.com"
+ username: "you@gmail.com"
+ password: "app-specific-password"
+ check_interval: 60 # seconds between IMAP polls
+
+ matrix:
+ enabled: false
+ homeserver: "https://matrix.org"
+ access_token: "syt_..."
+ room_ids: ["!roomid:matrix.org"]
+
+ webhook:
+ enabled: true
+ path: "/hermes/webhook"
+ secret: "your-webhook-secret"
+```
+
+---
+
+## Platform Driver Deep Dives
+
+### Telegram Adapter
+
+```python
+# hermes_cli/gateway/telegram.py (structure)
+
+class TelegramAdapter:
+ async def start_webhook(self):
+ """Register webhook with Telegram and start aiohttp server."""
+ await self.bot.set_webhook(
+ url=f"{self.config.webhook_url}/telegram",
+ secret_token=self.config.secret
+ )
+
+ async def handle_update(self, update: dict) -> GatewayMessage | None:
+ """Convert Telegram update to GatewayMessage."""
+ msg = update.get("message") or update.get("callback_query", {}).get("message")
+ if not msg:
+ return None
+
+ return GatewayMessage(
+ platform="telegram",
+ platform_user_id=str(msg["from"]["id"]),
+ platform_chat_id=str(msg["chat"]["id"]),
+ content=msg.get("text", ""),
+ attachments=self._extract_attachments(msg),
+ timestamp=msg["date"],
+ message_id=str(msg["message_id"]),
+ )
+
+ async def send_response(self, chat_id: str, text: str):
+ """Send response, splitting at 4096 char Telegram limit."""
+ for chunk in split_message(text, 4096):
+ await self.bot.send_message(
+ chat_id=chat_id,
+ text=chunk,
+ parse_mode="Markdown"
+ )
+```
+
+### Signal Adapter
+
+Signal integration uses `signal-cli` — a command-line Java application that interfaces with Signal's native protocol:
+
+```python
+# hermes_cli/gateway/signal.py (structure)
+
+class SignalAdapter:
+ async def start_daemon(self):
+ """Start signal-cli in daemon mode for JSON-RPC communication."""
+ self.process = await asyncio.create_subprocess_exec(
+ self.config.signal_cli_path,
+ "--output=json",
+ "daemon",
+ "--socket", "/tmp/signal-cli.sock",
+ stdout=asyncio.subprocess.PIPE,
+ )
+
+ async def listen(self):
+ """Read JSON messages from signal-cli stdout."""
+ async for line in self.process.stdout:
+ event = json.loads(line)
+ if event.get("type") == "receive":
+ yield self._parse_message(event)
+```
+
+### Email Adapter
+
+```python
+# hermes_cli/gateway/email.py (structure)
+
+class EmailAdapter:
+ async def poll_inbox(self):
+ """Poll IMAP inbox for new messages."""
+ with imaplib.IMAP4_SSL(self.config.imap_host) as imap:
+ imap.login(self.config.username, self.config.password)
+ imap.select("INBOX")
+ _, message_nums = imap.search(None, "UNSEEN")
+
+ for num in message_nums[0].split():
+ _, data = imap.fetch(num, "(RFC822)")
+ msg = email.message_from_bytes(data[0][1])
+ yield self._parse_email(msg)
+ imap.store(num, "+FLAGS", "\\Seen")
+```
+
+---
+
+## The Delivery Pipeline
+
+After the agent generates a response, the delivery pipeline handles formatting, chunking, and reliable delivery:
+
+```mermaid
+sequenceDiagram
+ participant Agent as Agent Core
+ participant DP as Delivery Pipeline
+ participant FMT as Platform Formatter
+ participant Adapter as Platform Adapter
+ participant Platform as Platform API
+
+ Agent-->>DP: response_text
+ DP->>FMT: format(response, platform="telegram")
+ FMT-->>DP: formatted_chunks[]
+
+ loop For each chunk
+ DP->>Adapter: send_chunk(chunk)
+ Adapter->>Platform: API call
+
+ alt Success
+ Platform-->>Adapter: 200 OK
+ Adapter-->>DP: ack
+ else Rate limited
+ Platform-->>Adapter: 429
+ Adapter->>Adapter: wait retry_after
+ Adapter->>Platform: retry
+ else Error
+ Platform-->>Adapter: 5xx
+ Adapter-->>DP: error
+ DP->>DP: exponential backoff
+ DP->>Adapter: retry (max 3)
+ end
+ end
+
+ DP-->>Agent: delivery_complete
+```
+
+### Platform-Specific Formatting
+
+Each platform has different constraints (message length, Markdown support, file size limits):
+
+| Platform | Max Message Length | Markdown Support | File Upload |
+|---|---|---|---|
+| Telegram | 4,096 chars | MarkdownV2 | 50 MB |
+| Discord | 2,000 chars | Discord Markdown | 25 MB |
+| Slack | 40,000 chars | mrkdwn | 1 GB |
+| WhatsApp | 65,536 chars | None (plain text) | 16 MB |
+| Signal | None | None (plain text) | 100 MB |
+| Email | Unlimited | HTML | Unlimited |
+| Matrix | Unlimited | HTML + Markdown | 100 MB |
+
+The `PlatformFormatter` class converts the agent's Markdown output to each platform's native format, handles splitting at sentence/paragraph boundaries for platforms with limits, and falls back to plain text when rich formatting isn't supported.
+
+---
+
+## Pairing and Security
+
+Pairing links a platform identity (e.g., a Telegram user ID) to a Hermes user identity. This ensures:
+
+1. Only authorized users can access the agent
+2. All platforms share the same memory and session state
+3. Anonymous users can be blocked (`require_pairing: true`)
+
+### Pairing Flow
+
+```bash
+# In the TUI, generate a pairing code
+> /pair telegram
+Pairing code: HERMES-7X4K-QR2P
+Valid for: 15 minutes
+
+# Send the code to the Hermes bot on Telegram:
+# /pair HERMES-7X4K-QR2P
+
+# TUI confirms:
+Telegram user @username (ID: 123456789) paired successfully.
+All future messages from this user will share your session.
+```
+
+The pairing code is a time-limited token stored in `~/.hermes/.credentials/pairing.db`. After pairing, the platform user ID is permanently associated with the Hermes user's session namespace.
+
+---
+
+## OpenAI-Compatible API Server Mode
+
+`api_server.py` exposes an OpenAI-compatible REST API, enabling programmatic access to Hermes from any tool or library that supports the OpenAI SDK:
+
+```bash
+# Start the API server
+hermes gateway api-server --port 8080
+
+# Use with the OpenAI Python SDK
+```
+
+```python
+from openai import OpenAI
+
+client = OpenAI(
+ base_url="http://localhost:8080/v1",
+ api_key="hermes-local" # any non-empty string
+)
+
+response = client.chat.completions.create(
+ model="hermes", # model name is ignored; uses configured model
+ messages=[
+ {"role": "user", "content": "What were we discussing yesterday?"}
+ ]
+)
+# Response includes episodic memory just like the TUI
+```
+
+The API server:
+- Implements `/v1/chat/completions` (streaming and non-streaming)
+- Implements `/v1/models` (returns available configured models)
+- Shares the same session namespace as the TUI and gateway (pass `session_id` in the request metadata to control which session to use)
+- Logs all API calls to `~/.hermes/logs/api_access.jsonl`
+
+---
+
+## Monitoring Gateway Health
+
+```bash
+# Check all platform connection states
+hermes gateway status
+
+# Output:
+Gateway Status
+══════════════
+telegram: ✓ Connected (last message: 2 min ago)
+discord: ✓ Connected (last message: 1 hour ago)
+slack: ✗ Error (connection refused — check bot token)
+signal: ✓ Connected (last message: 5 min ago)
+email: ✓ Connected (polling every 60s)
+api_server: ✓ Running (port 8080, 3 active connections)
+
+# View gateway logs
+hermes gateway logs --platform telegram --last 50
+
+# Reconnect a failed platform
+hermes gateway reconnect slack
+```
+
+---
+
+## Chapter Summary
+
+| Concept | Key Takeaway |
+|---|---|
+| Message bus | All platforms normalize to GatewayMessage; async queue decouples ingestion from processing |
+| Session routing | Platform+user → Hermes session_id; enables cross-platform memory continuity |
+| Pairing | Time-limited code links platform identity to Hermes identity; controls memory sharing |
+| Platform adapters | 20+ adapters in hermes_cli/gateway/; each handles platform-specific auth and formatting |
+| Delivery pipeline | Format → chunk → send → retry; platform-aware length limits and Markdown conversion |
+| API server mode | OpenAI-compatible /v1/chat/completions; programmatic access with session awareness |
+| require_pairing | Config flag to block unpaired users; important for public-facing deployments |
+| Cross-platform memory | All paired platforms share MEMORY.md, USER.md, sessions.db, and skills |
diff --git a/tutorials/hermes-agent-tutorial/06-cron-subagents-automation.md b/tutorials/hermes-agent-tutorial/06-cron-subagents-automation.md
new file mode 100644
index 00000000..78b62fc9
--- /dev/null
+++ b/tutorials/hermes-agent-tutorial/06-cron-subagents-automation.md
@@ -0,0 +1,499 @@
+---
+layout: default
+title: "Chapter 6: Cron Scheduling, Subagents, and Automation"
+nav_order: 6
+parent: Hermes Agent Tutorial
+format_version: v2
+why: "An AI agent that only responds to messages is reactive. Hermes's cron scheduler and subagent system make it proactive — it can run scheduled tasks, spawn parallel agents for complex workflows, and execute code in isolated environments without any user present."
+mental_model: "The cron scheduler is like a crontab that knows how to spawn Hermes agents instead of shell scripts. Each scheduled job can be a simple prompt, a multi-step workflow, or a full subagent with its own execution context and tool access — all orchestrated by the same memory system that powers your interactive sessions."
+learning_outcomes:
+ - Create, list, and manage cron jobs with the hermes cron CLI
+ - Understand how scheduler.py executes jobs and writes results to memory
+ - Spawn subagents for parallel task execution via model_tools.py
+ - Configure and use all six terminal backends for isolated code execution
+ - Build a batch automation pipeline using batch_runner.py
+snapshot:
+ source_repo: https://github.com/nousresearch/hermes-agent
+ stars: 65972
+ language: Python
+ license: MIT
+chapter_map:
+ - hermes_cli/cron/scheduler.py
+ - hermes_cli/cron/jobs/
+ - hermes_cli/environments/batch_runner.py
+ - hermes_cli/agent/model_tools.py
+sources:
+ - https://github.com/nousresearch/hermes-agent
+---
+
+# Chapter 6: Cron Scheduling, Subagents, and Automation
+
+## What Problem Does This Solve?
+
+Most agent frameworks require a human to be present to get work done. Hermes is designed to work asynchronously — running scheduled tasks while you sleep, parallelizing multi-step workflows with subagents, and executing code in isolated containers without manual setup.
+
+This chapter covers three related automation systems:
+
+1. **Cron scheduling** — run agent prompts on a time-based schedule
+2. **Subagent spawning** — parallelize tasks by spawning isolated agent instances via Python RPC
+3. **Terminal backends** — six execution environments for isolated, reproducible code execution
+
+---
+
+## Cron Scheduling
+
+### Core Concepts
+
+A Hermes cron job is a combination of:
+- A cron expression (schedule)
+- A prompt template (what the agent should do)
+- An optional context file or memory namespace
+- Output routing (where results go: memory, file, gateway notification)
+
+```bash
+# Add a daily standup summarizer
+hermes cron add \
+ --schedule "0 9 * * 1-5" \
+ --prompt "Review my MEMORY.md and generate a standup summary of active projects" \
+ --output "notify:telegram" \
+ --name "daily-standup"
+
+# Add a weekly memory cleanup
+hermes cron add \
+ --schedule "0 0 * * 0" \
+ --prompt "Review MEMORY.md and remove stale or completed items. Update relevance." \
+ --output "memory" \
+ --name "weekly-memory-cleanup"
+
+# Add an hourly monitoring job
+hermes cron add \
+ --schedule "0 * * * *" \
+ --prompt "Check if any of my GitHub notifications require response" \
+ --output "notify:telegram,discord" \
+ --name "github-monitor"
+```
+
+### Cron CLI Commands
+
+```bash
+hermes cron list # Show all scheduled jobs
+hermes cron show <name> # Show job details
+hermes cron run <name> # Run a job immediately (manual trigger)
+hermes cron pause <name> # Pause a job
+hermes cron resume <name> # Resume a paused job
+hermes cron remove <name> # Delete a job
+hermes cron logs <name> # Show recent job execution logs
+hermes cron history # Show all job executions
+```
+
+```bash
+# Example: hermes cron list output
+Job Name Schedule Status Last Run Next Run
+────────────────────────────────────────────────────────────────────────────────
+daily-standup 0 9 * * 1-5 active 2026-04-11 09:00 2026-04-14 09:00
+weekly-memory-cleanup 0 0 * * 0 active 2026-04-07 00:00 2026-04-14 00:00
+github-monitor 0 * * * * active 2026-04-12 08:00 2026-04-12 09:00
+project-report 0 18 * * 5 paused 2026-04-05 18:00 —
+```
+
+---
+
+## How the Scheduler Works
+
+```mermaid
+flowchart TD
+ A[scheduler.py starts\nwith hermes daemon] --> B[load jobs from cron.db]
+ B --> C[APScheduler: schedule all active jobs]
+ C --> D{time trigger fires?}
+ D -->|yes| E[load job config]
+ E --> F[build execution context]
+ F --> G{backend type?}
+ G -->|local| H[execute in main process]
+ G -->|docker| I[spawn Docker container]
+ G -->|subagent| J[spawn subagent via model_tools.py]
+ H --> K[build prompt from template]
+ I --> K
+ J --> L[subagent runs full agent loop]
+ K --> M[LLM call]
+ M --> N[process response]
+ N --> O{output routing?}
+ O -->|memory| P[write to MEMORY.md]
+ O -->|notify:telegram| Q[send via gateway]
+ O -->|notify:discord| Q
+ O -->|file| R[write to output file]
+ O -->|log only| S[write to cron logs]
+ P --> T[log execution to cron.db]
+ Q --> T
+ R --> T
+ S --> T
+ T --> D
+```
+
+### scheduler.py Internals
+
+```python
+# hermes_cli/cron/scheduler.py (structure)
+
+class HermesCronScheduler:
+ def __init__(self, config: Config):
+ self.scheduler = AsyncIOScheduler(timezone="UTC")
+ self.job_store = JobStore("~/.hermes/cron.db")
+
+ async def start(self):
+ """Load all active jobs and start APScheduler."""
+ for job in self.job_store.list_active():
+ self.scheduler.add_job(
+ self._execute_job,
+ CronTrigger.from_crontab(job.schedule),
+ args=[job],
+ id=job.name,
+ misfire_grace_time=300 # 5-minute grace period for missed fires
+ )
+ self.scheduler.start()
+
+ async def _execute_job(self, job: CronJob):
+ """Execute a single scheduled job."""
+ start_time = time.time()
+ try:
+ context = await self._build_context(job)
+ result = await self._run_agent(job.prompt_template, context)
+ await self._route_output(job, result)
+
+ self.job_store.record_execution(
+ job_id=job.id,
+ status="success",
+ duration=time.time() - start_time,
+ output_preview=result[:200]
+ )
+ except Exception as e:
+ self.job_store.record_execution(
+ job_id=job.id,
+ status="error",
+ error=str(e),
+ duration=time.time() - start_time
+ )
+ if job.notify_on_failure:
+ await self.gateway.send(job.failure_notify_platform, str(e))
+```
+
+---
+
+## Subagents
+
+Subagents are isolated Hermes instances spawned by the primary agent to parallelize complex tasks. They communicate with the parent via Python RPC.
+
+### When to Use Subagents
+
+| Use Case | Description |
+|---|---|
+| Parallel research | Spawn 3 subagents to research different aspects of a topic simultaneously |
+| Large-scale code review | Spawn one subagent per file in a directory |
+| Multi-environment testing | Run the same test across different Docker environments in parallel |
+| Batch data processing | Distribute a dataset across subagents for parallel processing |
+
+### Spawning Subagents via model_tools.py
+
+```python
+# hermes_cli/agent/model_tools.py (subagent tool)
+
+@tool(name="spawn_subagent")
+async def spawn_subagent(
+ prompt: str,
+ context_files: list[str] = None,
+ backend: str = "local",
+ max_iterations: int = 10,
+ timeout: int = 300,
+) -> SubagentResult:
+ """
+ Spawn an isolated Hermes subagent to complete a specific task.
+
+ Args:
+ prompt: The task for the subagent to complete
+ context_files: List of file paths to include in the subagent's context
+ backend: Execution backend (local/docker/ssh/daytona/modal/singularity)
+ max_iterations: Maximum agent loop iterations
+ timeout: Maximum execution time in seconds
+
+ Returns:
+ SubagentResult with output, tool_calls, and exit_status
+ """
+ subagent = HermesSubagent(
+ prompt=prompt,
+ context_files=context_files or [],
+ backend=backend,
+ session_id=f"subagent_{uuid4().hex[:8]}",
+ parent_session_id=get_current_session_id()
+ )
+
+ return await subagent.run(
+ max_iterations=max_iterations,
+ timeout=timeout
+ )
+```
+
+### Subagent Spawning Example
+
+From an interactive session:
+
+```
+You: I need to review the architecture of this Python project for security issues.
+ The project is in ~/projects/data-pipeline/. It has about 40 Python files.
+
+Hermes: I'll spawn a subagent for each module directory to parallelize this review.
+
+[Hermes spawns 4 subagents, one per module directory]
+
+Subagent 1 (ingestion/): Reviewing 8 files...
+Subagent 2 (transformation/): Reviewing 12 files...
+Subagent 3 (storage/): Reviewing 11 files...
+Subagent 4 (api/): Reviewing 9 files...
+
+[All 4 complete in ~45 seconds instead of ~180 seconds sequentially]
+
+Security Review Summary:
+========================
+Critical (1): SQL injection risk in storage/db.py:147 — unsanitized user input
+High (3): Hardcoded credentials in ingestion/config.py (3 instances)
+Medium (5): Missing input validation on API endpoints
+...
+```
+
+---
+
+## batch_runner.py — Batch Automation
+
+`batch_runner.py` enables high-throughput automation over large datasets or file collections:
+
+```python
+# hermes_cli/environments/batch_runner.py (structure)
+
+class BatchRunner:
+ async def run(
+ self,
+ items: list[Any],
+ prompt_template: str,
+ concurrency: int = 5,
+ backend: str = "local",
+ output_file: str | None = None
+ ) -> BatchResult:
+ """
+ Run the agent on each item in parallel with concurrency limit.
+
+ Template variables available: {item}, {index}, {total}
+ """
+ semaphore = asyncio.Semaphore(concurrency)
+ results = []
+
+ async def process_item(index: int, item: Any):
+ async with semaphore:
+ prompt = prompt_template.format(
+ item=item,
+ index=index,
+ total=len(items)
+ )
+ result = await self.agent.run_once(prompt, backend=backend)
+ return BatchItemResult(index=index, item=item, output=result)
+
+ tasks = [process_item(i, item) for i, item in enumerate(items)]
+ results = await asyncio.gather(*tasks, return_exceptions=True)
+
+ if output_file:
+ self._write_results(output_file, results)
+
+ return BatchResult(results=results, total=len(items))
+```
+
+### CLI Usage
+
+```bash
+# Process a list of URLs
+hermes batch run \
+ --input urls.txt \
+ --prompt "Summarize the content at this URL: {item}" \
+ --concurrency 5 \
+ --output summaries.jsonl
+
+# Process files in a directory
+hermes batch run \
+ --input "~/projects/data-pipeline/**/*.py" \
+ --prompt "Review this Python file for code quality issues:\n{item}" \
+ --backend docker \
+ --output code_review.jsonl
+```
+
+---
+
+## Terminal Backends
+
+Hermes supports six terminal backends for code execution. The backend determines where shell commands run when the agent uses the `shell_exec` tool.
+
+```mermaid
+graph TD
+ subgraph Backends["Terminal Backends (hermes_cli/environments/)"]
+ LB[local\nDirect subprocess\non host machine]
+ DB[docker\nIsolated container\nper session]
+ SB[ssh\nRemote host\nvia SSH]
+ DYB[daytona\nHibernating cloud\nworkspace]
+ SGB[singularity\nHPC container\n.sif images]
+ MB[modal\nServerless GPU/CPU\ncloud execution]
+ end
+```
+
+### Backend Configuration and Use Cases
+
+| Backend | Config Key | Best For |
+|---|---|---|
+| `local` | `execution.backend: local` | Development; direct access to host filesystem |
+| `docker` | `execution.backend: docker` | Isolation; reproducibility; dependency management |
+| `ssh` | `execution.backend: ssh` | Remote servers; production environments |
+| `daytona` | `execution.backend: daytona` | Cost efficiency; hibernating cloud workspaces |
+| `singularity` | `execution.backend: singularity` | HPC clusters; rootless containers |
+| `modal` | `execution.backend: modal` | GPU workloads; serverless scaling; ML training |
+
+### Docker Backend
+
+```yaml
+# config.yaml
+execution:
+ backend: docker
+ docker:
+ image: "python:3.12-slim"
+ volumes:
+ - "~/projects:/workspace:rw"
+ environment:
+ - "PYTHONPATH=/workspace"
+ auto_remove: true # Container removed after each session
+ memory_limit: "2g"
+ cpu_limit: 2.0
+```
+
+The Docker backend creates a fresh container for each agent session, mounts specified volumes, and destroys the container on session end. This provides strong isolation without persistent state between sessions.
+
+### SSH Backend
+
+```yaml
+execution:
+ backend: ssh
+ ssh:
+ host: "myserver.example.com"
+ port: 22
+ username: "deploy"
+ key_path: "~/.ssh/id_ed25519"
+ working_dir: "/home/deploy/hermes-workspace"
+ multiplexing: true # Reuse SSH connection (faster)
+```
+
+### Daytona Backend
+
+Daytona workspaces hibernate when not in use and wake up automatically when needed. This makes them cost-effective for agents that run sporadically:
+
+```yaml
+execution:
+ backend: daytona
+ daytona:
+ server_url: "https://app.daytona.io"
+ api_key: "dyt-..."
+ workspace_id: "hermes-workspace-01"
+ auto_start: true # Wake workspace automatically on use
+```
+
+### Modal Backend
+
+Modal is the only backend with native GPU support, making it the right choice for ML workloads:
+
+```yaml
+execution:
+ backend: modal
+ modal:
+ token_id: "ak-..."
+ token_secret: "as-..."
+ gpu: "A10G" # null for CPU-only
+ timeout: 3600 # seconds
+ image: "python:3.12"
+ packages: ["torch", "transformers"]
+```
+
+---
+
+## Backend Selection Flow
+
+```mermaid
+sequenceDiagram
+ participant Agent
+ participant Router as smart_routing.py
+ participant Backend as Terminal Backend
+ participant Exec as Execution Environment
+
+ Agent->>Router: execute_command(cmd, task_context)
+ Router->>Router: evaluate backend rules
+
+ alt task requires GPU
+ Router->>Backend: use modal backend
+ Backend->>Exec: Modal.run(cmd, gpu="A10G")
+ else task needs isolation
+ Router->>Backend: use docker backend
+ Backend->>Exec: docker run --rm python:3.12 cmd
+ else task on remote server
+ Router->>Backend: use ssh backend
+ Backend->>Exec: ssh user@host "cmd"
+ else default
+ Router->>Backend: use local backend
+ Backend->>Exec: subprocess.run(cmd)
+ end
+
+ Exec-->>Backend: stdout, stderr, exit_code
+ Backend-->>Agent: ExecutionResult
+```
+
+---
+
+## Automation Patterns
+
+### Pattern 1: Daily Briefing
+
+```bash
+hermes cron add \
+ --schedule "0 8 * * *" \
+ --prompt "Generate my daily briefing: summarize yesterday's session highlights from MEMORY.md, list today's known deadlines, and suggest 3 priority tasks" \
+ --output "notify:telegram" \
+ --name "daily-briefing"
+```
+
+### Pattern 2: Repository Monitor
+
+```bash
+hermes cron add \
+ --schedule "*/30 * * * *" \
+ --prompt "Check GitHub notifications for @mentioned issues in NousResearch/hermes-agent. Summarize any requiring response." \
+ --output "notify:slack:#dev-alerts,log" \
+ --name "github-monitor"
+```
+
+### Pattern 3: Automated Code Review
+
+```bash
+# Watch a directory for new pull requests and auto-review
+hermes cron add \
+ --schedule "*/5 * * * *" \
+ --prompt "Check for new unreviewed PRs in ~/projects/data-pipeline. For any new ones, spawn a subagent to perform security and quality review." \
+ --backend docker \
+ --output "file:~/reviews/pr_reviews.md" \
+ --name "pr-auto-review"
+```
+
+---
+
+## Chapter Summary
+
+| Concept | Key Takeaway |
+|---|---|
+| Cron scheduler | APScheduler-based; jobs are prompts with schedule, context, and output routing |
+| Job output routing | Results go to memory, file, gateway notification, or log depending on config |
+| Subagent spawning | spawn_subagent tool in model_tools.py; isolated Hermes instances for parallel work |
+| batch_runner.py | Async batch processing with concurrency limit; processes lists or file globs |
+| local backend | Direct subprocess; fastest, no isolation |
+| docker backend | Isolated container per session; auto-removed; volume-mounted |
+| ssh backend | Remote execution; multiplexed connections for efficiency |
+| daytona backend | Hibernating cloud workspaces; cost-effective for sporadic use |
+| singularity backend | HPC clusters; rootless containers; .sif image support |
+| modal backend | Serverless GPU/CPU; best for ML workloads |
diff --git a/tutorials/hermes-agent-tutorial/07-rl-training-trajectory.md b/tutorials/hermes-agent-tutorial/07-rl-training-trajectory.md
new file mode 100644
index 00000000..b9b5c4ce
--- /dev/null
+++ b/tutorials/hermes-agent-tutorial/07-rl-training-trajectory.md
@@ -0,0 +1,535 @@
+---
+layout: default
+title: "Chapter 7: RL Training and Trajectory Generation"
+nav_order: 7
+parent: Hermes Agent Tutorial
+format_version: v2
+why: "Hermes is not just a user of NousResearch models — it is a data generator for them. The trajectory recording system and Atropos integration create a closed loop where every real interaction can improve the next version of the model. Understanding this system matters both for contributing to NousResearch's models and for running your own RL training pipelines."
+mental_model: "trajectory.py is a silent observer attached to every agent loop iteration. It records tool calls, reasoning steps, and outcomes in a structured format that Atropos — NousResearch's RL training framework — can consume directly. Real Hermes usage generates real training data."
+learning_outcomes:
+ - Understand how trajectory.py records agent interactions in Atropos format
+ - Configure trajectory recording and understand what gets captured
+ - Understand the five benchmark environments included with Hermes
+ - Explain how tool-call parsers support multi-model RL training across different model families
+ - Run the data generation pipeline end-to-end for a local RL fine-tuning workflow
+snapshot:
+ source_repo: https://github.com/nousresearch/hermes-agent
+ stars: 65972
+ language: Python
+ license: MIT
+chapter_map:
+ - hermes_cli/agent/trajectory.py
+ - hermes_cli/environments/hermes_swe_env/
+ - hermes_cli/environments/tblite/
+ - hermes_cli/environments/terminalbench_2/
+ - hermes_cli/environments/yc_bench/
+ - hermes_cli/environments/batch_runner.py
+sources:
+ - https://github.com/nousresearch/hermes-agent
+---
+
+# Chapter 7: RL Training and Trajectory Generation
+
+## What Problem Does This Solve?
+
+Modern LLM fine-tuning — especially via reinforcement learning from human or environment feedback — requires high-quality behavioral trajectories: recordings of what an agent did, step by step, including reasoning, tool calls, and outcomes. These trajectories are expensive to generate synthetically and hard to collect at scale.
+
+Hermes solves this by turning every production interaction into a potential training example. `trajectory.py` records a complete trace of each agent loop iteration — the prompt, the reasoning, every tool call, and the final response — in the Atropos RL format that NousResearch uses for fine-tuning. If you use Hermes daily, you're continuously generating training data for the very models that power it.
+
+---
+
+## The Closed Learning Loop
+
+```mermaid
+flowchart LR
+ subgraph Usage["Daily Hermes Usage"]
+ TUI[TUI / Gateway\nUser Interactions]
+ CRON[Cron Jobs\nAutomated Tasks]
+ BENCH[Benchmark\nEnvironments]
+ end
+
+ subgraph Recording["trajectory.py"]
+ TRAJ[Trajectory Recorder\nrecords per-turn traces]
+ ATROP[Atropos Formatter\nconverts to RL format]
+ end
+
+ subgraph Storage["~/.hermes/trajectories/"]
+ TJSONL[traj_*.jsonl\nAtropos format]
+ end
+
+ subgraph Training["RL Training Pipeline"]
+ FILTER[Quality Filter\nreward scoring]
+ ATROPOS[Atropos\nRL Framework]
+ FINETUNE[Fine-tuned Model\nnext version]
+ end
+
+ TUI --> TRAJ
+ CRON --> TRAJ
+ BENCH --> TRAJ
+ TRAJ --> ATROP
+ ATROP --> TJSONL
+ TJSONL --> FILTER
+ FILTER --> ATROPOS
+ ATROPOS --> FINETUNE
+ FINETUNE -->|improved model| TUI
+```
+
+---
+
+## trajectory.py — The Recorder
+
+`trajectory.py` is attached to the agent's core loop as an observer. It records a structured trace of every turn without affecting the agent's behavior.
+
+### What Gets Recorded
+
+```python
+# hermes_cli/agent/trajectory.py (data structures)
+
+@dataclass
+class TurnTrace:
+ """A single turn in an agent trajectory."""
+
+ # Context
+ session_id: str
+ turn_index: int
+ timestamp: float
+ model: str
+ provider: str
+
+ # Input
+ prompt_tokens: int
+ system_prompt_hash: str # For deduplication; not the full prompt
+ user_message: str
+ conversation_history_length: int
+
+ # Agent reasoning (if chain-of-thought is enabled)
+ reasoning: str | None
+
+ # Tool calls (may be multiple per turn)
+ tool_calls: list[ToolCall]
+
+ # Output
+ assistant_response: str
+ completion_tokens: int
+
+ # Outcome signals (filled in post-turn)
+ user_feedback: str | None # explicit feedback if user gave it
+ task_completed: bool | None # set by environment for benchmark tasks
+ reward: float | None # set by reward model or environment
+
+
+@dataclass
+class ToolCall:
+ tool_name: str
+ arguments: dict
+ result: str | None
+ error: str | None
+ duration_ms: float
+ success: bool
+```
+
+### Recording a Trajectory
+
+```python
+# hermes_cli/agent/trajectory.py (recording flow)
+
+class TrajectoryRecorder:
+ def __init__(self, config: Config):
+ self.enabled = config.trajectory.enabled
+ self.output_dir = Path(config.trajectory.output_dir)
+ self.current_trajectory: list[TurnTrace] = []
+
+ def record_turn(
+ self,
+ user_message: str,
+ reasoning: str | None,
+ tool_calls: list[ToolCall],
+ assistant_response: str,
+ model_info: ModelInfo,
+ token_counts: TokenCounts
+ ) -> TurnTrace:
+ """Record a single turn. Called after each agent response."""
+ if not self.enabled:
+ return None
+
+ trace = TurnTrace(
+ session_id=self.session_id,
+ turn_index=len(self.current_trajectory),
+ timestamp=time.time(),
+ model=model_info.model,
+ provider=model_info.provider,
+ prompt_tokens=token_counts.prompt,
+ system_prompt_hash=hash_system_prompt(self.current_system_prompt),
+ user_message=user_message,
+ conversation_history_length=len(self.history),
+ reasoning=reasoning,
+ tool_calls=tool_calls,
+ assistant_response=assistant_response,
+ completion_tokens=token_counts.completion,
+ )
+
+ self.current_trajectory.append(trace)
+ return trace
+
+ def finalize(self, session_outcome: SessionOutcome):
+ """Write the complete trajectory to disk at session end."""
+ trajectory = Trajectory(
+ session_id=self.session_id,
+ turns=self.current_trajectory,
+ outcome=session_outcome,
+ format_version="atropos-v1"
+ )
+
+ output_path = self.output_dir / f"traj_{self.session_id}.jsonl"
+ with open(output_path, "w") as f:
+ for turn in trajectory.turns:
+ f.write(json.dumps(asdict(turn)) + "\n")
+```
+
+---
+
+## Atropos Format
+
+Atropos is NousResearch's RL training framework. The trajectory format it consumes is a JSONL file where each line is a turn trace:
+
+```jsonl
+{"session_id": "sess_abc123", "turn_index": 0, "model": "gpt-4o", "user_message": "Can you help me debug this Python function?", "reasoning": "The user has a Python debugging question. I should ask to see the code.", "tool_calls": [], "assistant_response": "I'd be happy to help debug your Python function. Could you share the code?", "prompt_tokens": 1847, "completion_tokens": 23, "reward": null}
+{"session_id": "sess_abc123", "turn_index": 1, "model": "gpt-4o", "user_message": "def process(df):\n return df.groupby('a').sum()", "reasoning": "Simple groupby operation. The issue might be NaN handling or column types.", "tool_calls": [{"tool_name": "shell_exec", "arguments": {"command": "python3 -c \"import pandas as pd; df = pd.DataFrame({'a': [1,1,2], 'b': [None, 2, 3]}); print(df.groupby('a').sum())\"}"}, "result": " b\na \n1 2.0\n2 3.0", "success": true, "duration_ms": 234}], "assistant_response": "The function looks correct for basic aggregation. However, note that NaN values are silently dropped by groupby().sum()...", "prompt_tokens": 2103, "completion_tokens": 187, "reward": 1.0}
+```
+
+### Trajectory Configuration
+
+```yaml
+# ~/.hermes/config.yaml
+
+trajectory:
+ enabled: true
+ output_dir: "~/.hermes/trajectories"
+
+ # What to record
+ record_reasoning: true # Include chain-of-thought if available
+ record_tool_calls: true # Include all tool call arguments and results
+ record_system_prompt: false # Exclude for privacy (hash only)
+
+ # Quality filtering
+ min_turn_count: 2 # Skip single-turn sessions
+ require_tool_calls: false # Include even non-tool-using sessions
+
+ # Reward signals
+ reward_model: null # Path to local reward model, or null for human feedback only
+
+ # Upload
+ auto_upload: false # Upload to NousResearch if true
+ upload_endpoint: "https://training.nousresearch.com/trajectories"
+ upload_api_key: "nk-..."
+```
+
+---
+
+## Benchmark Environments
+
+Hermes ships with four benchmark environments designed to generate high-quality training trajectories for specific skill domains.
+
+### Overview
+
+| Environment | Location | Tests | Domain |
+|---|---|---|---|
+| hermes_swe_env | environments/hermes_swe_env/ | Software engineering tasks | Code editing, bug fixing, PR review |
+| tblite | environments/tblite/ | Terminal-based tasks | Shell scripting, file manipulation, system admin |
+| terminalbench_2 | environments/terminalbench_2/ | Terminal reasoning | Complex multi-step terminal workflows |
+| yc_bench | environments/yc_bench/ | Business/startup tasks | Research, analysis, document generation |
+
+### hermes_swe_env — Software Engineering Benchmark
+
+Based on SWE-bench methodology, `hermes_swe_env` presents the agent with real-world software engineering tasks:
+
+```python
+# hermes_cli/environments/hermes_swe_env/__init__.py (structure)
+
+class HermesSWEEnv:
+ """
+ Software engineering benchmark environment.
+
+ Each task is a GitHub issue + repository snapshot.
+ The agent must produce a patch that resolves the issue.
+ Success is measured by automated test suite pass rate.
+ """
+
+ async def run_task(self, task: SWETask) -> TaskResult:
+ """
+ Set up a Docker container with the task's repository,
+ present the issue to the agent, and evaluate the result.
+ """
+ container = await self._setup_container(task.repo_snapshot)
+
+ prompt = f"""
+ You are working on the following GitHub issue:
+
+ Repository: {task.repo}
+ Issue #{task.issue_number}: {task.issue_title}
+
+ {task.issue_body}
+
+ Please resolve this issue by editing the relevant files.
+ """
+
+ result = await self.agent.run(
+ prompt=prompt,
+ backend="docker",
+ container=container,
+ max_iterations=20
+ )
+
+ test_pass_rate = await self._run_tests(container)
+
+ return TaskResult(
+ task_id=task.id,
+ success=test_pass_rate > 0.9,
+ test_pass_rate=test_pass_rate,
+ patch=await self._extract_patch(container),
+ trajectory=result.trajectory
+ )
+```
+
+### tblite — Terminal Benchmark Lite
+
+A collection of terminal-focused tasks ranging from simple file operations to complex shell scripting challenges:
+
+```python
+# hermes_cli/environments/tblite/__init__.py (structure)
+
+TASK_CATEGORIES = {
+ "file_ops": [
+ "Find all Python files modified in the last 24 hours",
+ "Create a directory structure for a new Python package",
+ "Extract specific lines from multiple log files",
+ ],
+ "shell_scripting": [
+ "Write a bash script to monitor disk usage and alert when > 90%",
+ "Parse a CSV file and output statistics",
+ "Create a backup script with rotation",
+ ],
+ "system_admin": [
+ "Set up a cron job to run a Python script daily",
+ "Configure environment variables for a Python project",
+ "Debug a failing systemd service",
+ ]
+}
+```
+
+### terminalbench_2 — Advanced Terminal Reasoning
+
+`terminalbench_2` focuses on multi-step terminal workflows that require planning and state management:
+
+```python
+# hermes_cli/environments/terminalbench_2/__init__.py (structure)
+
+class TerminalBench2:
+ """
+ Advanced terminal benchmark with longer-horizon tasks.
+ Evaluates ability to maintain state across many steps,
+ recover from errors, and use terminal tools efficiently.
+ """
+ pass
+```
+
+### yc_bench — Business Task Benchmark
+
+Evaluates the agent's ability to perform business and startup-related tasks:
+
+```python
+# hermes_cli/environments/yc_bench/__init__.py (structure)
+
+TASK_TYPES = [
+ "market_research", # Research a market and produce a report
+ "competitor_analysis", # Analyze competitors and create comparison matrix
+ "technical_spec", # Write a technical specification document
+ "financial_model", # Build a simple financial model in a spreadsheet
+ "user_interview_analysis", # Analyze interview transcripts for themes
+]
+```
+
+---
+
+## Tool-Call Parsers for Multi-Model RL
+
+One of Hermes's most technically sophisticated features is its ability to generate RL training data from multiple model families. Different models use different tool-call formats, and `trajectory.py` includes parsers for each:
+
+```python
+# hermes_cli/agent/trajectory.py (tool call parsers)
+
+class ToolCallParser:
+ """
+ Parse tool calls from different model families into
+ a unified ToolCall format for trajectory recording.
+ """
+
+ @staticmethod
+ def parse(response: str, model_family: str) -> list[ToolCall]:
+ parser = {
+ "hermes": ToolCallParser._parse_hermes, # Hermes function calling
+ "deepseek": ToolCallParser._parse_deepseek, # DeepSeek tool use
+ "qwen": ToolCallParser._parse_qwen, # Qwen tool calls
+ "glm": ToolCallParser._parse_glm, # GLM function calls
+ "llama": ToolCallParser._parse_llama, # Llama tool use
+ "kimi": ToolCallParser._parse_kimi, # Kimi (Moonshot) tools
+ "mistral": ToolCallParser._parse_mistral, # Mistral tool calls
+ }.get(model_family, ToolCallParser._parse_openai)
+
+ return parser(response)
+
+ @staticmethod
+ def _parse_hermes(response: str) -> list[ToolCall]:
+ """Parse Hermes function calling format."""
+ # Hermes uses XML-like tags: <tool_call>...</tool_call>
+ calls = []
+ for match in re.finditer(r'<tool_call>(.*?)</tool_call>', response, re.DOTALL):
+ try:
+ call_data = json.loads(match.group(1))
+ calls.append(ToolCall(
+ tool_name=call_data["name"],
+ arguments=call_data.get("arguments", {})
+ ))
+ except json.JSONDecodeError:
+ pass
+ return calls
+
+ @staticmethod
+ def _parse_deepseek(response: str) -> list[ToolCall]:
+ """Parse DeepSeek tool use format."""
+ # DeepSeek uses a different JSON structure
+ ...
+```
+
+### Model Family Support Matrix
+
+| Model Family | Tool Format | Reasoning Format | Notes |
+|---|---|---|---|
+| Hermes (NousResearch) | XML tags: `<tool_call>` | `<reasoning>` | Native format |
+| DeepSeek | JSON in `<tool_call>` | `<think>` | R1-style reasoning |
+| Qwen | OpenAI-compatible JSON | Optional `<think>` | Qwen2.5 family |
+| GLM | Function call JSON | Not exposed | GLM-4 family |
+| Llama | OpenAI-compatible | Optional chain | Llama 3.x family |
+| Kimi (Moonshot) | OpenAI-compatible | `<think>` | k1.5 family |
+| Mistral | OpenAI-compatible | Not exposed | Mistral/Mixtral |
+| OpenAI (fallback) | Standard function calling | Not exposed | GPT-4o family |
+
+---
+
+## Running the Data Generation Pipeline
+
+### Generate Trajectories from Benchmarks
+
+```bash
+# Run hermes_swe_env benchmark and generate trajectories
+hermes bench run hermes_swe_env \
+ --model "gpt-4o" \
+ --tasks 50 \
+ --output ~/.hermes/trajectories/swe_bench_run_1/
+
+# Run tblite benchmark
+hermes bench run tblite \
+ --model "meta-llama/Llama-3.3-70b-Instruct-Turbo" \
+ --tasks 100 \
+ --backend docker \
+ --concurrency 5 \
+ --output ~/.hermes/trajectories/tblite_run_1/
+```
+
+### Filter and Score Trajectories
+
+```bash
+# Score trajectories with a reward model
+hermes traj score \
+ --input ~/.hermes/trajectories/swe_bench_run_1/ \
+ --reward-model ~/models/reward_model.ckpt \
+ --output ~/.hermes/trajectories/scored/
+
+# Filter to high-quality trajectories
+hermes traj filter \
+ --input ~/.hermes/trajectories/scored/ \
+ --min-reward 0.7 \
+ --min-turns 3 \
+ --output ~/.hermes/trajectories/filtered/
+
+# Convert to Atropos training format
+hermes traj export \
+ --input ~/.hermes/trajectories/filtered/ \
+ --format atropos-v1 \
+ --output ~/training_data/hermes_trajectories.jsonl
+```
+
+### Upload to NousResearch
+
+```bash
+# Upload high-quality trajectories to contribute to model training
+hermes traj upload \
+ --input ~/.hermes/trajectories/filtered/ \
+ --endpoint https://training.nousresearch.com/trajectories \
+ --api-key $NOUSRESEARCH_API_KEY
+```
+
+---
+
+## Data Generation Pipeline Architecture
+
+```mermaid
+sequenceDiagram
+ participant Env as Benchmark Environment
+ participant Agent as Hermes Agent
+ participant Traj as trajectory.py
+ participant FS as ~/.hermes/trajectories/
+ participant Atropos as Atropos RL
+
+ Env->>Agent: present task
+
+ loop Agent loop (max_iterations)
+ Agent->>Agent: build prompt
+ Agent->>Agent: call LLM
+ Agent->>Agent: parse tool calls
+ Agent->>Env: execute tool calls
+ Env-->>Agent: tool results
+ Traj->>Traj: record TurnTrace
+ end
+
+ Env->>Traj: session_outcome (pass/fail + reward)
+ Traj->>Traj: finalize trajectory
+ Traj->>FS: write traj_*.jsonl
+
+ Note over FS: Quality filtering step
+ FS->>Atropos: high-quality trajectories
+ Atropos->>Atropos: RL training update
+ Atropos-->>Agent: improved policy (next model version)
+```
+
+---
+
+## Reward Signals
+
+Trajectories become useful for RL training only when they have reward signals. Hermes supports three reward sources:
+
+| Reward Source | When Available | Quality |
+|---|---|---|
+| Environment feedback | Benchmark runs (automated test pass/fail) | High — ground truth |
+| User explicit feedback | User rates response with 👍/👎 in TUI | High — human judgment |
+| Reward model | Configured local or API reward model | Medium — depends on model quality |
+| Implicit signal | Session length, skill creation events, memory writes | Low — correlational |
+
+For production use, the most valuable trajectories come from benchmark runs where success is objectively measurable. Interactive session trajectories are valuable when users provide explicit feedback.
+
+---
+
+## Chapter Summary
+
+| Concept | Key Takeaway |
+|---|---|
+| trajectory.py | Silent observer on agent loop; records every turn in Atropos format |
+| Atropos format | JSONL; one line per turn; includes reasoning, tool calls, outcomes, rewards |
+| Closed loop | Daily usage → trajectories → Atropos training → improved models → daily usage |
+| hermes_swe_env | SWE-bench-style software engineering tasks; Docker-isolated; evaluated by tests |
+| tblite | Terminal task benchmark; shell scripting, file ops, system admin |
+| terminalbench_2 | Long-horizon terminal reasoning tasks |
+| yc_bench | Business task benchmark; research, analysis, document generation |
+| Tool-call parsers | Unified parser for 7+ model families; enables multi-model RL training |
+| Reward signals | Environment feedback (best), user feedback, reward model, implicit signals |
+| Upload workflow | Filter → score → export → upload to NousResearch training endpoint |
diff --git a/tutorials/hermes-agent-tutorial/08-acp-mcp-migration-ecosystem.md b/tutorials/hermes-agent-tutorial/08-acp-mcp-migration-ecosystem.md
new file mode 100644
index 00000000..45ffd777
--- /dev/null
+++ b/tutorials/hermes-agent-tutorial/08-acp-mcp-migration-ecosystem.md
@@ -0,0 +1,668 @@
+---
+layout: default
+title: "Chapter 8: ACP, MCP, Migration, and Ecosystem"
+nav_order: 8
+parent: Hermes Agent Tutorial
+format_version: v2
+why: "Hermes is not an island. Understanding how it participates in multi-agent networks via ACP, exposes itself as an MCP server, integrates with the agentskills.io ecosystem, and deploys reproducibly via Nix and Docker is essential for building production systems and contributing back to the project."
+mental_model: "Hermes at the edges: ACP makes Hermes a node in a multi-agent network; MCP makes Hermes's capabilities available to any MCP client; agentskills.io makes Hermes's learned skills portable; and Nix/Docker make Hermes's deployment reproducible across any machine."
+learning_outcomes:
+ - Understand the Agent Communication Protocol and configure Hermes's ACP server
+ - Set up Hermes as an MCP server for use with Claude Desktop or other MCP clients
+ - Migrate from OpenClaw with hermes claw migrate
+ - Deploy Hermes with Docker Compose or Nix for reproducible production setups
+ - Contribute skills to agentskills.io and understand the project's contribution workflow
+snapshot:
+ source_repo: https://github.com/nousresearch/hermes-agent
+ stars: 65972
+ language: Python
+ license: MIT
+chapter_map:
+ - hermes_cli/acp_adapter/
+ - hermes_cli/acp_adapter/server.py
+ - hermes_cli/gateway/mcp_serve.py
+ - hermes_cli/migration/claw.py
+ - flake.nix
+ - docker-compose.yml
+sources:
+ - https://github.com/nousresearch/hermes-agent
+---
+
+# Chapter 8: ACP, MCP, Migration, and Ecosystem
+
+## What Problem Does This Solve?
+
+Single-agent systems have fundamental limitations: they can only do one thing at a time, they're bottlenecked by one model's capabilities, and they're isolated from other agents that might have complementary skills. Hermes addresses this through two complementary protocols:
+
+- **ACP (Agent Communication Protocol)** makes Hermes a node in a multi-agent network — it can receive tasks from orchestrator agents, spawn peer agents, and report results back through a standardized interface.
+- **MCP (Model Context Protocol)** makes Hermes's memory, skills, and execution capabilities available to any MCP-compatible client, including Claude Desktop.
+
+Together with the agentskills.io ecosystem and reproducible deployment options, these integrations position Hermes as a building block in larger AI systems rather than a standalone tool.
+
+---
+
+## ACP — Agent Communication Protocol
+
+### What Is ACP?
+
+The Agent Communication Protocol is an emerging standard for agent-to-agent communication. It defines how agents advertise their capabilities, accept task requests, stream results, and report completion. Hermes implements ACP via the `acp_adapter/` module, which exposes an HTTP/SSE server that any ACP-compatible orchestrator can call.
+
+### ACP Server Architecture
+
+```mermaid
+flowchart TD
+ subgraph External["External Orchestrators"]
+ ORCH1[Orchestrator Agent\ne.g. MetaGPT]
+ ORCH2[Orchestrator Agent\ne.g. AutoGen]
+ ORCH3[Custom Orchestrator]
+ end
+
+ subgraph ACP["hermes_cli/acp_adapter/"]
+ SRV[server.py\nHTTP/SSE server]
+ CAPS[capabilities.py\nCapability registry]
+ TASK[task_handler.py\nTask lifecycle]
+ AUTH[auth.py\nAPI key validation]
+ end
+
+ subgraph HermesCore["Hermes Core"]
+ AGENT[Agent Loop\nprompt_builder + LLM]
+ MEM[Memory System]
+ TOOLS[Tool Execution]
+ end
+
+ ORCH1 -->|POST /agents/hermes/tasks| SRV
+ ORCH2 -->|POST /agents/hermes/tasks| SRV
+ ORCH3 -->|GET /agents/hermes/capabilities| CAPS
+ SRV --> AUTH
+ AUTH --> TASK
+ TASK --> AGENT
+ AGENT --> MEM
+ AGENT --> TOOLS
+ TASK -->|SSE stream| ORCH1
+ TASK -->|SSE stream| ORCH2
+```
+
+### ACP Server Configuration
+
+```yaml
+# ~/.hermes/config.yaml
+
+acp:
+ enabled: true
+ host: "0.0.0.0"
+ port: 8765
+
+ auth:
+ api_keys:
+ - key: "acp-key-abc123"
+ name: "orchestrator-1"
+ permissions: [tasks, capabilities, status]
+ require_auth: true
+
+ capabilities:
+ # Which Hermes capabilities to expose via ACP
+ expose_memory: true # Allow reading MEMORY.md / USER.md
+ expose_skills: true # Allow reading and executing skills
+ expose_shell: false # Shell execution (disabled by default for security)
+ expose_gateway: false # Messaging gateway (disabled by default)
+
+ rate_limits:
+ requests_per_minute: 60
+ max_concurrent_tasks: 3
+```
+
+### ACP Capability Discovery
+
+An orchestrator can discover Hermes's capabilities before assigning tasks:
+
+```bash
+curl http://localhost:8765/agents/hermes/capabilities \
+ -H "Authorization: Bearer acp-key-abc123"
+```
+
+```json
+{
+ "agent_id": "hermes",
+ "version": "0.4.2",
+ "display_name": "Hermes Agent",
+ "description": "Self-hosted personal AI agent with persistent memory and skill system",
+ "capabilities": [
+ {
+ "id": "chat",
+ "description": "General-purpose conversation with full memory access",
+ "input_schema": {"type": "object", "properties": {"message": {"type": "string"}}},
+ "output_schema": {"type": "object", "properties": {"response": {"type": "string"}}}
+ },
+ {
+ "id": "skill_execution",
+ "description": "Execute a named skill from the skill library",
+ "input_schema": {"type": "object", "properties": {"skill_id": {"type": "string"}, "context": {"type": "string"}}}
+ },
+ {
+ "id": "memory_query",
+ "description": "Query episodic or semantic memory",
+ "input_schema": {"type": "object", "properties": {"query": {"type": "string"}, "layer": {"type": "string", "enum": ["episodic", "semantic", "procedural"]}}}
+ }
+ ]
+}
+```
+
+### Sending a Task to Hermes via ACP
+
+```python
+import requests
+import json
+
+# Assign a task to Hermes from an orchestrator
+response = requests.post(
+ "http://localhost:8765/agents/hermes/tasks",
+ headers={"Authorization": "Bearer acp-key-abc123"},
+ json={
+ "task_id": "task-001",
+ "capability": "chat",
+ "input": {
+ "message": "Summarize the current state of the data-pipeline-v2 project from your memory."
+ },
+ "stream": True # Request SSE streaming
+ },
+ stream=True
+)
+
+# Consume the SSE stream
+for line in response.iter_lines():
+ if line.startswith(b"data:"):
+ event = json.loads(line[5:])
+ if event["type"] == "token":
+ print(event["content"], end="", flush=True)
+ elif event["type"] == "complete":
+ print("\nTask complete.")
+ break
+```
+
+### ACP Task Lifecycle
+
+```mermaid
+sequenceDiagram
+ participant Orch as Orchestrator
+ participant ACP as acp_adapter/server.py
+ participant TH as task_handler.py
+ participant Agent as Hermes Agent
+
+ Orch->>ACP: POST /agents/hermes/tasks
+ ACP->>ACP: validate API key
+ ACP->>TH: create_task(task_request)
+ TH-->>Orch: 202 Accepted {task_id}
+
+ TH->>Agent: run(capability, input)
+
+ loop streaming
+ Agent-->>TH: partial response token
+ TH-->>Orch: SSE event {type: "token", content: "..."}
+ end
+
+ Agent-->>TH: complete response
+ TH->>TH: record trajectory
+ TH-->>Orch: SSE event {type: "complete", result: {...}}
+
+ Orch->>ACP: GET /agents/hermes/tasks/{task_id}
+ ACP-->>Orch: task status and full result
+```
+
+---
+
+## MCP — Model Context Protocol
+
+### What Is MCP?
+
+The Model Context Protocol is Anthropic's open standard for giving AI assistants access to external tools and data sources. By running `hermes gateway mcp-serve`, Hermes exposes its memory system, skill library, and execution capabilities as an MCP server that any MCP-compatible client can connect to — including Claude Desktop.
+
+### Starting the MCP Server
+
+```bash
+# Start Hermes as an MCP server
+hermes gateway mcp-serve --port 3001
+
+# Or run in the background
+hermes gateway mcp-serve --port 3001 &
+```
+
+### Connecting Claude Desktop to Hermes
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+ "mcpServers": {
+ "hermes": {
+ "command": "hermes",
+ "args": ["gateway", "mcp-serve", "--stdio"],
+ "env": {
+ "HERMES_HOME": "/Users/yourname/.hermes"
+ }
+ }
+ }
+}
+```
+
+### Exposed MCP Tools
+
+```python
+# hermes_cli/gateway/mcp_serve.py (tool definitions)
+
+MCP_TOOLS = [
+ {
+ "name": "hermes_memory_search",
+ "description": "Search Hermes's episodic memory for relevant past sessions",
+ "input_schema": {
+ "type": "object",
+ "properties": {
+ "query": {"type": "string", "description": "Search query"},
+ "max_results": {"type": "integer", "default": 5}
+ },
+ "required": ["query"]
+ }
+ },
+ {
+ "name": "hermes_skill_list",
+ "description": "List all skills in the Hermes skill library",
+ "input_schema": {"type": "object", "properties": {}}
+ },
+ {
+ "name": "hermes_skill_get",
+ "description": "Retrieve the full content of a named skill",
+ "input_schema": {
+ "type": "object",
+ "properties": {
+ "skill_id": {"type": "string"}
+ },
+ "required": ["skill_id"]
+ }
+ },
+ {
+ "name": "hermes_chat",
+ "description": "Send a message to the Hermes agent (with full memory access)",
+ "input_schema": {
+ "type": "object",
+ "properties": {
+ "message": {"type": "string"},
+ "session_id": {"type": "string", "description": "Optional: continue an existing session"}
+ },
+ "required": ["message"]
+ }
+ }
+]
+```
+
+### mcp_serve.py Architecture
+
+```mermaid
+flowchart TD
+ subgraph MCPClients["MCP Clients"]
+ CD[Claude Desktop]
+ CC[Claude Code]
+ CUSTOM[Custom MCP Client]
+ end
+
+ subgraph MCPServer["hermes_cli/gateway/mcp_serve.py"]
+ PROTO[MCP Protocol Handler\nJSON-RPC / stdio / SSE]
+ TOOLS[Tool Registry\nhermes_memory_search\nhermes_skill_list\nhermes_skill_get\nhermes_chat]
+ EXEC[Tool Executor]
+ end
+
+ subgraph HermesCore["Hermes Core"]
+ CE[context_engine.py\nFTS5 search]
+ SK[skill_utils.py\nSkill library]
+ AG[Agent Core\nfull chat loop]
+ end
+
+ CD -->|stdio| PROTO
+ CC -->|stdio| PROTO
+ CUSTOM -->|SSE| PROTO
+ PROTO --> TOOLS
+ TOOLS --> EXEC
+ EXEC --> CE
+ EXEC --> SK
+ EXEC --> AG
+```
+
+---
+
+## OpenClaw Migration
+
+`hermes claw migrate` is the comprehensive migration tool for users coming from OpenClaw (Hermes's predecessor).
+
+### Migration Flow
+
+```mermaid
+flowchart TD
+ A[hermes claw migrate] --> B[detect ~/.openclaw/]
+ B --> C{found?}
+ C -->|no| D[error: ~/.openclaw not found]
+ C -->|yes| E[inventory OpenClaw data]
+ E --> F[show migration preview to user]
+ F --> G{user confirms?}
+ G -->|no| H[exit]
+ G -->|yes| I[migrate sessions]
+ I --> J[migrate skills]
+ J --> K[merge MEMORY.md]
+ K --> L[merge USER.md]
+ L --> M[translate config.yaml]
+ M --> N[verify migration integrity]
+ N --> O{issues found?}
+ O -->|yes| P[show issues, offer fixes]
+ O -->|no| Q[migration complete]
+ P --> Q
+```
+
+### Migration Details
+
+```bash
+hermes claw migrate --dry-run # Preview what would be migrated
+hermes claw migrate # Perform migration
+hermes claw migrate --keep-source # Don't move files, just copy
+```
+
+**Sessions:** OpenClaw's session format is translated to Hermes's FTS5 schema. The session content is re-summarized if the original summary doesn't meet Hermes's minimum quality threshold.
+
+**Skills:** SKILL.md format is identical between OpenClaw and Hermes — files are copied directly.
+
+**MEMORY.md merging:** If both `~/.openclaw/MEMORY.md` and `~/.hermes/MEMORY.md` exist, a semantic deduplication pass removes duplicate facts before merging.
+
+**Config translation:**
+
+| OpenClaw Key | Hermes Equivalent |
+|---|---|
+| `model.primary` | `llm.model` |
+| `model.api_key` | `llm.api_key` |
+| `execution.mode` | `execution.backend` |
+| `memory.episodic.enabled` | `memory.episodic.enabled` |
+| `plugins.telegram` | `gateway.platforms.telegram` |
+
+---
+
+## Production Deployment
+
+### Docker Compose
+
+```yaml
+# docker-compose.yml (reference)
+
+version: "3.9"
+
+services:
+ hermes:
+ image: nousresearch/hermes-agent:latest
+ # Or build from source:
+ # build: .
+
+ volumes:
+ - ~/.hermes:/home/hermes/.hermes # Persist all state
+ - ~/.ssh:/home/hermes/.ssh:ro # For SSH backend
+
+ environment:
+ - HERMES_API_KEY=${HERMES_API_KEY}
+ - HERMES_HOME=/home/hermes/.hermes
+
+ ports:
+ - "8080:8080" # Gateway API server
+ - "8765:8765" # ACP server
+ - "3001:3001" # MCP server
+
+ restart: unless-stopped
+
+ # For Docker-in-Docker (Docker terminal backend inside Docker)
+ # volumes:
+ # - /var/run/docker.sock:/var/run/docker.sock
+
+ # Optional: Honcho user modeling service
+ honcho:
+ image: nousresearch/honcho:latest
+ environment:
+ - DATABASE_URL=postgresql://honcho:honcho@postgres/honcho
+ depends_on:
+ - postgres
+
+ postgres:
+ image: postgres:16
+ environment:
+ - POSTGRES_USER=honcho
+ - POSTGRES_PASSWORD=honcho
+ - POSTGRES_DB=honcho
+ volumes:
+ - postgres_data:/var/lib/postgresql/data
+
+volumes:
+ postgres_data:
+```
+
+```bash
+# Deploy
+docker compose up -d
+
+# Check status
+docker compose ps
+
+# View logs
+docker compose logs -f hermes
+
+# Update
+docker compose pull && docker compose up -d
+```
+
+### Nix
+
+For maximum reproducibility, Hermes ships with a `flake.nix` that pins every dependency:
+
+```bash
+# Enter development shell
+nix develop
+
+# Build the package
+nix build
+
+# Run directly
+nix run github:nousresearch/hermes-agent
+
+# Install to system profile
+nix profile install github:nousresearch/hermes-agent
+```
+
+The Nix flake provides:
+- A reproducible development environment (exact Python version, all dependencies)
+- A derivation for building Hermes as a Nix package
+- NixOS module for declarative system-level deployment
+
+```nix
+# NixOS module usage example
+{
+ services.hermes-agent = {
+ enable = true;
+ hermesHome = "/var/lib/hermes";
+ user = "hermes-agent";
+
+ settings = {
+ llm.provider = "openai";
+ llm.model = "gpt-4o";
+ gateway.platforms.telegram.enabled = true;
+ };
+
+ secrets = {
+ apiKeyFile = config.age.secrets.hermes-api-key.path;
+ };
+ };
+}
+```
+
+---
+
+## agentskills.io Integration
+
+`agentskills.io` is the community platform for sharing SKILL.md files. Hermes has first-class integration:
+
+```bash
+# Search for skills
+hermes skills search "kubernetes deployment"
+
+# Install a community skill
+hermes skills install kubernetes-deployment-patterns
+
+# Publish your skill
+hermes skills publish python_etl_patterns \
+ --description "Battle-tested Python ETL patterns for Airflow" \
+ --tags "python,etl,airflow,data-engineering"
+
+# Update a published skill
+hermes skills publish python_etl_patterns --update
+
+# Rate a skill
+hermes skills rate kubernetes-deployment-patterns --stars 5
+```
+
+### Skill Publication Requirements
+
+To publish to agentskills.io, a skill must:
+1. Have complete YAML frontmatter (skill_id, description, tags, tested_with)
+2. Include a "When to Use This Skill" section
+3. Include at least one concrete code example
+4. Not contain sensitive information (API keys, personal data)
+5. Be under 50KB
+
+---
+
+## Contributing to Hermes Agent
+
+### Repository Structure for Contributors
+
+```
+hermes-agent/
+├── hermes_cli/ # Main package
+│ ├── agent/ # Core agent logic
+│ ├── gateway/ # Platform adapters
+│ ├── cron/ # Scheduler
+│ ├── environments/ # Benchmarks and execution
+│ └── acp_adapter/ # ACP server
+├── tests/ # Test suite
+│ ├── unit/
+│ ├── integration/
+│ └── benchmarks/
+├── docs/ # Documentation
+├── flake.nix # Nix flake
+├── docker-compose.yml # Docker Compose
+└── pyproject.toml # Python package config
+```
+
+### Development Setup
+
+```bash
+git clone https://github.com/nousresearch/hermes-agent.git
+cd hermes-agent
+
+# With Nix (recommended)
+nix develop
+
+# With uv
+uv venv && source .venv/bin/activate
+uv pip install -e ".[dev]"
+
+# Run tests
+pytest tests/unit/
+pytest tests/integration/ # Requires API keys in environment
+
+# Run a specific benchmark
+python -m hermes_cli.environments.tblite --tasks 10 --model gpt-4o-mini
+```
+
+### Adding a New Gateway Platform
+
+```python
+# hermes_cli/gateway/myplatform.py
+
+from hermes_cli.gateway.base import BaseAdapter, GatewayMessage
+
+class MyPlatformAdapter(BaseAdapter):
+ """Adapter for MyPlatform messaging service."""
+
+ platform_name = "myplatform"
+
+ async def start(self):
+ """Initialize the platform connection."""
+ ...
+
+ async def handle_incoming(self, raw_event: dict) -> GatewayMessage | None:
+ """Convert platform-native event to GatewayMessage."""
+ ...
+
+ async def send_response(self, chat_id: str, text: str, **kwargs):
+ """Send a response to the platform."""
+ ...
+
+ async def stop(self):
+ """Clean up the connection."""
+ ...
+```
+
+Then register in `hermes_cli/gateway/__init__.py`:
+
+```python
+ADAPTERS = {
+ # ...existing adapters...
+ "myplatform": MyPlatformAdapter,
+}
+```
+
+---
+
+## Ecosystem Summary
+
+```mermaid
+graph TD
+ subgraph Hermes["Hermes Agent Core"]
+ CORE[Agent Loop\nMemory + Skills]
+ end
+
+ subgraph Protocols["Protocol Integrations"]
+ ACP[ACP Server\nacp_adapter/\nMulti-agent networks]
+ MCP[MCP Server\nmcp_serve.py\nClaude Desktop / Code]
+ end
+
+ subgraph Community["Community"]
+ SKILLS[agentskills.io\nSkill Hub]
+ GH[GitHub\nContributions]
+ end
+
+ subgraph Deploy["Deployment"]
+ DOCKER[Docker Compose\nProduction deploy]
+ NIX[Nix Flake\nReproducible dev + deploy]
+ NIXOS[NixOS Module\nDeclarative system config]
+ end
+
+ subgraph Migration["Migration"]
+ CLAW[hermes claw migrate\nOpenClaw → Hermes]
+ end
+
+ CORE <--> ACP
+ CORE <--> MCP
+ CORE <--> SKILLS
+ CORE --> GH
+ CORE --> DOCKER
+ CORE --> NIX
+ NIX --> NIXOS
+ CLAW --> CORE
+```
+
+---
+
+## Chapter Summary
+
+| Concept | Key Takeaway |
+|---|---|
+| ACP server | HTTP/SSE server in acp_adapter/; exposes Hermes to multi-agent orchestrators |
+| ACP capabilities | Capability discovery endpoint; orchestrators can query what Hermes can do |
+| MCP server | mcp_serve.py; exposes memory search, skill library, and chat to MCP clients |
+| Claude Desktop | Connect via mcpServers config; use Hermes memory from Claude chat |
+| MCP tools | hermes_memory_search, hermes_skill_list, hermes_skill_get, hermes_chat |
+| OpenClaw migration | hermes claw migrate; handles sessions, skills, MEMORY.md, USER.md, config |
+| Docker Compose | Production deployment; volume-mounts ~/.hermes; runs gateway + ACP + MCP |
+| Nix flake | Reproducible dev and deploy; NixOS module for declarative system config |
+| agentskills.io | Community skill hub; publish/install/rate skills via hermes skills commands |
+| Contributing | Add platform adapters by implementing BaseAdapter; register in gateway/__init__.py |
diff --git a/tutorials/hermes-agent-tutorial/README.md b/tutorials/hermes-agent-tutorial/README.md
new file mode 100644
index 00000000..5944ecb4
--- /dev/null
+++ b/tutorials/hermes-agent-tutorial/README.md
@@ -0,0 +1,146 @@
+---
+layout: default
+title: Hermes Agent Tutorial
+nav_order: 42
+has_children: true
+format_version: v2
+source_repo: https://github.com/nousresearch/hermes-agent
+categories: [ai-agents, personal-ai, multi-platform, rl-training]
+related_tutorials:
+ - openclaw-tutorial
+ - mem0-tutorial
+ - taskade-tutorial
+ - agno-tutorial
+last_updated: 2026-04-12
+---
+
+# Hermes Agent Tutorial
+
+**NousResearch's self-hosted personal AI agent with persistent memory, autonomous skill creation, 20+ platform gateway, and a closed reinforcement-learning loop that turns every conversation into fine-tuning data.**
+
+---
+
+## What Is Hermes Agent?
+
+Hermes Agent is the successor to OpenClaw — NousResearch's production-grade, self-hosted personal AI agent designed to run 24/7 on your own hardware or cloud infrastructure. With 65,972 GitHub stars and an MIT license, it represents the current state of the art in open-source agent frameworks that combine a richly layered memory system, a multi-platform messaging gateway, and a reinforcement-learning pipeline that continuously improves the underlying models through real usage.
+
+Unlike ephemeral chatbot wrappers, Hermes is built around three design principles:
+
+1. **Continuity** — sessions persist, memories accumulate, skills compound. The agent you run today is smarter than the one you ran last week.
+2. **Reach** — one agent, 20+ platforms. Whether you message through Telegram, Discord, Slack, WhatsApp, Signal, Email, Matrix, Feishu, DingTalk, or a raw webhook, the same memory and skill set is available.
+3. **Closed learning** — every real interaction is a potential training example. `trajectory.py` records tool calls and outcomes in Atropos RL format; those trajectories can be fed directly into NousResearch's fine-tuning pipeline to improve future model behavior.
+
+---
+
+## Who Should Read This Tutorial
+
+| Audience | What You Will Get |
+|---|---|
+| Individual developers | A self-hosted AI assistant with memory that actually persists across sessions |
+| Platform builders | A messaging gateway you can point at any of 20+ chat platforms with a single config |
+| ML researchers | A live data-generation pipeline producing Atropos-format RL trajectories from real agent interactions |
+| DevOps / infra engineers | Six swappable terminal backends (local, Docker, SSH, Daytona, Singularity, Modal) for isolated task execution |
+| OpenClaw users | A clear migration path: `hermes claw migrate` imports your memories, skills, and config |
+
+---
+
+## Architecture at a Glance
+
+```
+cli.py
+└── hermes_cli/
+ ├── agent/ # LLM core
+ │ ├── prompt_builder.py
+ │ ├── context_engine.py
+ │ ├── memory_manager.py
+ │ ├── skill_utils.py
+ │ ├── trajectory.py
+ │ └── smart_routing.py
+ ├── gateway/ # 20+ platform messaging
+ │ ├── telegram.py
+ │ ├── discord.py
+ │ ├── slack.py
+ │ ├── whatsapp.py
+ │ ├── signal.py
+ │ ├── email.py
+ │ ├── matrix.py
+ │ ├── api_server.py
+ │ └── ...
+ ├── cron/ # Scheduler + jobs
+ │ ├── scheduler.py
+ │ └── jobs/
+ ├── environments/ # RL training, benchmarks, subagents
+ │ ├── hermes_swe_env/
+ │ ├── tblite/
+ │ └── batch_runner.py
+ └── acp_adapter/ # Agent Communication Protocol server
+```
+
+---
+
+## Three Memory Layers
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ Memory Architecture │
+├──────────────┬──────────────────┬───────────────────────┤
+│ Episodic │ Semantic │ Procedural │
+│ │ │ │
+│ FTS5 SQLite │ MEMORY.md │ SKILL.md files │
+│ session │ USER.md │ (auto-created and │
+│ search + │ Honcho user │ self-improved by │
+│ LLM summary │ modeling │ the agent) │
+│ injection │ (dialectic) │ │
+└──────────────┴──────────────────┴───────────────────────┘
+```
+
+---
+
+## Chapters in This Tutorial
+
+| Chapter | Title | Key Topics |
+|---|---|---|
+| 1 | [Getting Started](./01-getting-started.md) | Install, `hermes setup`, `~/.hermes/` layout, first conversation, OpenClaw migration |
+| 2 | [The TUI and Conversation Interface](./02-tui-and-conversation-interface.md) | curses UI, slash commands, SOUL.md persona, context files, skin system |
+| 3 | [Agent Core: Prompt Building, Context Engine, Model Routing](./03-agent-core-prompt-context-routing.md) | prompt_builder.py, context_engine.py, smart_model_routing.py, credential_pool.py |
+| 4 | [Memory, Skills, and the Learning Loop](./04-memory-skills-learning-loop.md) | Three memory layers, memory_manager.py, FTS5, Honcho, SKILL.md, agentskills.io |
+| 5 | [The Messaging Gateway](./05-messaging-gateway.md) | 20+ platform drivers, session routing, delivery pipeline, API server mode |
+| 6 | [Cron Scheduling, Subagents, and Automation](./06-cron-subagents-automation.md) | scheduler.py, cron commands, subagent spawning, terminal backends |
+| 7 | [RL Training and Trajectory Generation](./07-rl-training-trajectory.md) | trajectory.py, Atropos, benchmark envs, tool-call parsers, data pipeline |
+| 8 | [ACP, MCP, Migration, and Ecosystem](./08-acp-mcp-migration-ecosystem.md) | ACP server, MCP integration, agentskills.io, OpenClaw migration, Nix/Docker deploy |
+
+---
+
+## Quick-Start (TL;DR)
+
+```bash
+# Install
+curl -fsSL https://raw.githubusercontent.com/nousresearch/hermes-agent/main/install.sh | bash
+
+# Run setup wizard
+hermes setup
+
+# Start the TUI
+hermes
+```
+
+---
+
+## Key Differentiators vs Other Agent Frameworks
+
+| Feature | Hermes Agent | LangChain | AutoGPT | CrewAI |
+|---|---|---|---|---|
+| Persistent episodic memory (FTS5) | Yes | Plugin-dependent | Partial | No |
+| Autonomous skill creation | Yes | No | No | No |
+| 20+ platform gateway | Yes | No | No | No |
+| RL trajectory generation | Yes | No | No | No |
+| Closed fine-tuning loop | Yes | No | No | No |
+| Self-hosted, MIT license | Yes | Yes | AGPL | MIT |
+| Six terminal backends | Yes | No | No | No |
+| ACP multi-agent protocol | Yes | No | No | No |
+
+---
+
+## License and Attribution
+
+Hermes Agent is released under the [MIT License](https://github.com/nousresearch/hermes-agent/blob/main/LICENSE) by NousResearch. This tutorial is an independent educational resource; it is not officially affiliated with NousResearch.
diff --git a/tutorials/huggingface-tutorial/01-getting-started.md b/tutorials/huggingface-tutorial/01-getting-started.md
index c472ee70..67a35f76 100644
--- a/tutorials/huggingface-tutorial/01-getting-started.md
+++ b/tutorials/huggingface-tutorial/01-getting-started.md
@@ -11,6 +11,18 @@ Welcome to the world of state-of-the-art AI with HuggingFace Transformers! If yo
## What Makes Transformers Special?
+```mermaid
+flowchart LR
+ A[Task description] --> B[pipeline]
+ B --> C{Task type}
+ C -->|text-classification| D[AutoModel + tokenizer]
+ C -->|text-generation| E[AutoModelForCausalLM]
+ C -->|question-answering| F[AutoModelForQA]
+ D --> G[Prediction]
+ E --> G
+ F --> G
+```
+
Transformers revolutionizes AI development by:
- **100,000+ Pre-trained Models** - Ready-to-use AI for any task
- **Simple APIs** - Just a few lines of code to add AI capabilities
diff --git a/tutorials/huggingface-tutorial/02-text-classification.md b/tutorials/huggingface-tutorial/02-text-classification.md
index 0cd2dc24..70487c55 100644
--- a/tutorials/huggingface-tutorial/02-text-classification.md
+++ b/tutorials/huggingface-tutorial/02-text-classification.md
@@ -14,6 +14,16 @@ Welcome back! Now that you understand the basics of HuggingFace Transformers, le
## Understanding Text Classification
+```mermaid
+flowchart LR
+ A[Raw text] --> B[AutoTokenizer.from_pretrained]
+ B --> C[input_ids attention_mask]
+ C --> D[AutoModelForSequenceClassification]
+ D --> E[logits]
+ E --> F[softmax]
+ F --> G[label + score]
+```
+
### What is Text Classification?
Text classification is the process of categorizing text documents into predefined classes or categories. It's one of the fundamental tasks in natural language processing and has applications in:
diff --git a/tutorials/huggingface-tutorial/03-text-generation.md b/tutorials/huggingface-tutorial/03-text-generation.md
index 05256edf..aab7bbee 100644
--- a/tutorials/huggingface-tutorial/03-text-generation.md
+++ b/tutorials/huggingface-tutorial/03-text-generation.md
@@ -14,6 +14,20 @@ Welcome to **Chapter 3: Text Generation**. In this part of **HuggingFace Transfo
## 🎯 Overview
+```mermaid
+flowchart LR
+ A[Prompt text] --> B[tokenizer encode]
+ B --> C[input_ids]
+ C --> D[model.generate]
+ D --> E{Decode strategy}
+ E -->|greedy| F[argmax per step]
+ E -->|sampling| G[temperature + top_p]
+ E -->|beam search| H[beam_width candidates]
+ F --> I[output text]
+ G --> I
+ H --> I
+```
+
This chapter explores text generation capabilities in HuggingFace Transformers, covering everything from creative writing to code generation and conversational AI. You'll learn to use and fine-tune models like GPT, T5, and other generative architectures.
## 📝 Understanding Text Generation
diff --git a/tutorials/huggingface-tutorial/04-question-answering.md b/tutorials/huggingface-tutorial/04-question-answering.md
index 6093beea..94dab731 100644
--- a/tutorials/huggingface-tutorial/04-question-answering.md
+++ b/tutorials/huggingface-tutorial/04-question-answering.md
@@ -14,6 +14,16 @@ Welcome to **Chapter 4: Question Answering**. In this part of **HuggingFace Tran
## 🎯 Overview
+```mermaid
+flowchart LR
+ A[Question + Context] --> B[tokenizer question context]
+ B --> C[input_ids token_type_ids]
+ C --> D[AutoModelForQA]
+ D --> E[start_logits end_logits]
+ E --> F[argmax span]
+ F --> G[Answer text]
+```
+
This chapter covers question answering (QA) systems using HuggingFace Transformers. You'll learn to build extractive and generative QA models, create custom knowledge bases, and deploy QA systems that can answer questions from your own documents.
## ❓ Types of Question Answering
diff --git a/tutorials/huggingface-tutorial/05-named-entity-recognition.md b/tutorials/huggingface-tutorial/05-named-entity-recognition.md
index 65dec4c4..aaf6a5e8 100644
--- a/tutorials/huggingface-tutorial/05-named-entity-recognition.md
+++ b/tutorials/huggingface-tutorial/05-named-entity-recognition.md
@@ -14,6 +14,16 @@ Welcome to **Chapter 5: Named Entity Recognition**. In this part of **HuggingFac
## 🎯 Overview
+```mermaid
+flowchart LR
+ A[Text] --> B[tokenizer word-piece]
+ B --> C[subword tokens]
+ C --> D[AutoModelForTokenClassification]
+ D --> E[per-token logits]
+ E --> F[BIO label decode]
+ F --> G[Named entities list]
+```
+
This chapter covers Named Entity Recognition (NER) using HuggingFace Transformers. You'll learn to identify and classify named entities like persons, organizations, locations, dates, and more from text, and build applications that extract structured information from unstructured data.
## 🏷️ Understanding Named Entities
diff --git a/tutorials/huggingface-tutorial/06-translation-multilingual.md b/tutorials/huggingface-tutorial/06-translation-multilingual.md
index 9c9718d0..6861e533 100644
--- a/tutorials/huggingface-tutorial/06-translation-multilingual.md
+++ b/tutorials/huggingface-tutorial/06-translation-multilingual.md
@@ -14,6 +14,16 @@ Welcome to **Chapter 6: Translation & Multilingual Models**. In this part of **H
## 🎯 Overview
+```mermaid
+flowchart LR
+ A[Source text] --> B[MarianTokenizer]
+ B --> C[source token ids]
+ C --> D[MarianMTModel.generate]
+ D --> E[target token ids]
+ E --> F[tokenizer.decode]
+ F --> G[Translated text]
+```
+
This chapter covers machine translation and multilingual language models using HuggingFace Transformers. You'll learn to build translation systems, work with multilingual models, and create applications that operate across multiple languages.
## 🌐 Machine Translation
diff --git a/tutorials/huggingface-tutorial/07-fine-tuning.md b/tutorials/huggingface-tutorial/07-fine-tuning.md
index e6996a14..28e14ad7 100644
--- a/tutorials/huggingface-tutorial/07-fine-tuning.md
+++ b/tutorials/huggingface-tutorial/07-fine-tuning.md
@@ -14,6 +14,18 @@ Welcome to **Chapter 7: Fine-tuning Models**. In this part of **HuggingFace Tran
## 🎯 Overview
+```mermaid
+flowchart TD
+ A[Pre-trained checkpoint] --> B[Load with AutoModel]
+ B --> C[Add task head]
+ C --> D[Trainer / training loop]
+ D --> E[Forward pass + loss]
+ E --> F[Backprop + optimizer]
+ F --> G[Checkpoint save]
+ G --> H[Evaluation on val set]
+ H --> I[Best checkpoint]
+```
+
This chapter covers fine-tuning techniques for adapting pre-trained Transformer models to specific tasks and domains. You'll learn to customize models for better performance on your data while avoiding common pitfalls.
## 🏗️ Fine-tuning Fundamentals
diff --git a/tutorials/huggingface-tutorial/08-production-deployment.md b/tutorials/huggingface-tutorial/08-production-deployment.md
index 774ea776..021ab3ed 100644
--- a/tutorials/huggingface-tutorial/08-production-deployment.md
+++ b/tutorials/huggingface-tutorial/08-production-deployment.md
@@ -14,6 +14,18 @@ Welcome to **Chapter 8: Production Deployment**. In this part of **HuggingFace T
## 🎯 Overview
+```mermaid
+flowchart LR
+ A[Fine-tuned model] --> B{Export format}
+ B -->|ONNX| C[onnxruntime inference]
+ B -->|TorchScript| D[torch.jit.trace]
+ B -->|Optimized| E[optimum library]
+ C --> F[REST API endpoint]
+ D --> F
+ E --> F
+ F --> G[Client requests]
+```
+
This chapter covers production deployment strategies for Transformer models, including optimization techniques, scaling approaches, monitoring, and operational best practices for running AI models in production environments.
## 🚀 Model Optimization for Production
diff --git a/tutorials/humanlayer-tutorial/01-getting-started.md b/tutorials/humanlayer-tutorial/01-getting-started.md
index eb0920be..f6ebcc26 100644
--- a/tutorials/humanlayer-tutorial/01-getting-started.md
+++ b/tutorials/humanlayer-tutorial/01-getting-started.md
@@ -36,169 +36,167 @@ You now have a clear starting point for learning the active and legacy parts of
Next: [Chapter 2: Architecture and Monorepo Layout](02-architecture-and-monorepo-layout.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `hack/visualize.ts`
-
-The `getTypeColor` function in [`hack/visualize.ts`](https://github.com/humanlayer/humanlayer/blob/HEAD/hack/visualize.ts) handles a key part of this chapter's functionality:
-
-```ts
-};
-
-function getTypeColor(type: string): string {
- switch (type) {
- case 'system':
- return colors.magenta;
- case 'user':
- return colors.blue;
- case 'assistant':
- return colors.green;
- case 'tool_use':
- return colors.cyan;
- case 'tool_result':
- return colors.yellow;
- case 'message':
- return colors.dim;
- case 'text':
- return colors.reset;
- default:
- return colors.reset;
- }
-}
+### `claudecode-go/client.go`
-function _formatHeader(json: any, lineNumber: number): string {
- const type = json.type || 'unknown';
- const typeColor = getTypeColor(type);
+The `isClosedPipeError` function in [`claudecode-go/client.go`](https://github.com/humanlayer/humanlayer/blob/HEAD/claudecode-go/client.go) handles a key part of this chapter's functionality:
- let header = `${colors.dim}--- Line ${lineNumber} ${typeColor}[${type.toUpperCase()}]${colors.reset}`;
+```go
+)
- // Add context based on type
- if (json.message?.role) {
- header += ` ${colors.dim}(${json.message.role})${colors.reset}`;
-```
-
-This function is important because it defines how HumanLayer Tutorial: Context Engineering and Human-Governed Coding Agents implements the patterns covered in this chapter.
+// isClosedPipeError checks if an error is due to a closed pipe (expected when process exits)
+func isClosedPipeError(err error) bool {
+ if err == nil {
+ return false
+ }
-### `hack/visualize.ts`
+ // Check for common closed pipe error patterns
+ errStr := err.Error()
+ if strings.Contains(errStr, "file already closed") ||
+ strings.Contains(errStr, "broken pipe") ||
+ strings.Contains(errStr, "use of closed network connection") {
+ return true
+ }
-The `_formatHeader` function in [`hack/visualize.ts`](https://github.com/humanlayer/humanlayer/blob/HEAD/hack/visualize.ts) handles a key part of this chapter's functionality:
+ // Check for syscall errors indicating closed pipe
+ var syscallErr *os.SyscallError
+ if errors.As(err, &syscallErr) {
+ return syscallErr.Err == syscall.EPIPE || syscallErr.Err == syscall.EBADF
+ }
-```ts
+ // Check for EOF (which can happen when pipe closes)
+ return errors.Is(err, io.EOF)
}
-function _formatHeader(json: any, lineNumber: number): string {
- const type = json.type || 'unknown';
- const typeColor = getTypeColor(type);
+// Client provides methods to interact with the Claude Code SDK
+type Client struct {
+ claudePath string
+}
- let header = `${colors.dim}--- Line ${lineNumber} ${typeColor}[${type.toUpperCase()}]${colors.reset}`;
+// shouldSkipPath checks if a path should be skipped during search
+```
- // Add context based on type
- if (json.message?.role) {
- header += ` ${colors.dim}(${json.message.role})${colors.reset}`;
- }
+This function is important because it defines how HumanLayer Tutorial: Context Engineering and Human-Governed Coding Agents implements the patterns covered in this chapter.
- if (json.message?.content?.[0]?.name) {
- header += ` ${colors.cyan}${json.message.content[0].name}${colors.reset}`;
- }
+### `claudecode-go/client.go`
- if (json.name) {
- header += ` ${colors.cyan}${json.name}${colors.reset}`;
- }
+The `shouldSkipPath` function in [`claudecode-go/client.go`](https://github.com/humanlayer/humanlayer/blob/HEAD/claudecode-go/client.go) handles a key part of this chapter's functionality:
- if (json.subtype) {
- header += ` ${colors.dim}${json.subtype}${colors.reset}`;
- }
+```go
+}
- return `${header} ${colors.dim}---${colors.reset}`;
+// shouldSkipPath checks if a path should be skipped during search
+func shouldSkipPath(path string) bool {
+ // Skip node_modules directories
+ if strings.Contains(path, "/node_modules/") {
+ return true
+ }
+ // Skip backup files
+ if strings.HasSuffix(path, ".bak") {
+ return true
+ }
+ return false
}
-function _colorizeJson(obj: any, indent = 0, path: string[] = []): string {
- const spaces = ' '.repeat(indent);
+// ShouldSkipPath checks if a path should be skipped during search (exported version)
+func ShouldSkipPath(path string) bool {
+ return shouldSkipPath(path)
+}
- if (obj === null) return `${colors.dim}null${colors.reset}`;
+// NewClient creates a new Claude Code client
+func NewClient() (*Client, error) {
+ // First try standard PATH
+ path, err := exec.LookPath("claude")
+ if err == nil && !shouldSkipPath(path) {
+ return &Client{claudePath: path}, nil
+ }
+
+ // Try common installation paths
+ commonPaths := []string{
+ filepath.Join(os.Getenv("HOME"), ".claude/local/claude"), // Add Claude's own directory
+ filepath.Join(os.Getenv("HOME"), ".npm/bin/claude"),
```
This function is important because it defines how HumanLayer Tutorial: Context Engineering and Human-Governed Coding Agents implements the patterns covered in this chapter.
-### `hack/visualize.ts`
+### `claudecode-go/client.go`
+
+The `ShouldSkipPath` function in [`claudecode-go/client.go`](https://github.com/humanlayer/humanlayer/blob/HEAD/claudecode-go/client.go) handles a key part of this chapter's functionality:
-The `_colorizeJson` function in [`hack/visualize.ts`](https://github.com/humanlayer/humanlayer/blob/HEAD/hack/visualize.ts) handles a key part of this chapter's functionality:
+```go
+}
-```ts
+// ShouldSkipPath checks if a path should be skipped during search (exported version)
+func ShouldSkipPath(path string) bool {
+ return shouldSkipPath(path)
}
-function _colorizeJson(obj: any, indent = 0, path: string[] = []): string {
- const spaces = ' '.repeat(indent);
-
- if (obj === null) return `${colors.dim}null${colors.reset}`;
- if (typeof obj === 'boolean') return `${colors.yellow}${obj}${colors.reset}`;
- if (typeof obj === 'number') return `${colors.cyan}${obj}${colors.reset}`;
- if (typeof obj === 'string') {
- // Truncate very long strings
- if (obj.length > 200) {
- return `${colors.green}"${obj.substring(0, 197)}..."${colors.reset}`;
- }
- return `${colors.green}"${obj}"${colors.reset}`;
- }
-
- if (Array.isArray(obj)) {
- if (obj.length === 0) return '[]';
-
- // For content arrays, show summary
- if (path.includes('content') && obj.length > 3) {
- const summary = obj.slice(0, 2).map((item) => _colorizeJson(item, indent + 1, [...path]));
- return `[\n${summary.join(',\n')},\n${spaces} ${colors.dim}... ${obj.length - 2} more items${colors.reset}\n${spaces}]`;
- }
-
- const items = obj.map((item) => `${spaces} ${_colorizeJson(item, indent + 1, [...path])}`);
- return `[\n${items.join(',\n')}\n${spaces}]`;
- }
-
- if (typeof obj === 'object') {
- const keys = Object.keys(obj);
- if (keys.length === 0) return '{}';
+// NewClient creates a new Claude Code client
+func NewClient() (*Client, error) {
+ // First try standard PATH
+ path, err := exec.LookPath("claude")
+ if err == nil && !shouldSkipPath(path) {
+ return &Client{claudePath: path}, nil
+ }
+
+ // Try common installation paths
+ commonPaths := []string{
+ filepath.Join(os.Getenv("HOME"), ".claude/local/claude"), // Add Claude's own directory
+ filepath.Join(os.Getenv("HOME"), ".npm/bin/claude"),
+ filepath.Join(os.Getenv("HOME"), ".bun/bin/claude"),
+ filepath.Join(os.Getenv("HOME"), ".local/bin/claude"),
+ "/usr/local/bin/claude",
+ "/opt/homebrew/bin/claude",
+ }
+
+ for _, candidatePath := range commonPaths {
+ if shouldSkipPath(candidatePath) {
+ continue
+ }
+ if _, err := os.Stat(candidatePath); err == nil {
+ // Verify it's executable
+ if err := isExecutable(candidatePath); err == nil {
```
This function is important because it defines how HumanLayer Tutorial: Context Engineering and Human-Governed Coding Agents implements the patterns covered in this chapter.
-### `hack/visualize.ts`
+### `claudecode-go/client.go`
-The `formatTodoList` function in [`hack/visualize.ts`](https://github.com/humanlayer/humanlayer/blob/HEAD/hack/visualize.ts) handles a key part of this chapter's functionality:
+The `NewClient` function in [`claudecode-go/client.go`](https://github.com/humanlayer/humanlayer/blob/HEAD/claudecode-go/client.go) handles a key part of this chapter's functionality:
-```ts
+```go
}
-function formatTodoList(todos: any[]): string {
- let output = `📋 ${colors.bright}${colors.cyan}Todo List Update${colors.reset}\n`;
-
- const statusColors = {
- completed: colors.dim + colors.green,
- in_progress: colors.bright + colors.yellow,
- pending: colors.reset,
- };
-
- const statusIcons = {
- completed: '✅',
- in_progress: '🔄',
- pending: '⏸️',
- };
-
- const priorityColors = {
- high: colors.red,
- medium: colors.yellow,
- low: colors.dim,
- };
-
- todos.forEach((todo, index) => {
- const statusColor = statusColors[todo.status] || colors.reset;
- const statusIcon = statusIcons[todo.status] || '❓';
- const priorityColor = priorityColors[todo.priority] || colors.reset;
- const checkbox = todo.status === 'completed' ? '☑️' : '☐';
-
- output += ` ${checkbox} ${statusIcon} ${statusColor}${todo.content}${colors.reset}`;
- output += ` ${priorityColor}[${todo.priority}]${colors.reset}`;
+// NewClient creates a new Claude Code client
+func NewClient() (*Client, error) {
+ // First try standard PATH
+ path, err := exec.LookPath("claude")
+ if err == nil && !shouldSkipPath(path) {
+ return &Client{claudePath: path}, nil
+ }
+
+ // Try common installation paths
+ commonPaths := []string{
+ filepath.Join(os.Getenv("HOME"), ".claude/local/claude"), // Add Claude's own directory
+ filepath.Join(os.Getenv("HOME"), ".npm/bin/claude"),
+ filepath.Join(os.Getenv("HOME"), ".bun/bin/claude"),
+ filepath.Join(os.Getenv("HOME"), ".local/bin/claude"),
+ "/usr/local/bin/claude",
+ "/opt/homebrew/bin/claude",
+ }
+
+ for _, candidatePath := range commonPaths {
+ if shouldSkipPath(candidatePath) {
+ continue
+ }
+ if _, err := os.Stat(candidatePath); err == nil {
+ // Verify it's executable
+ if err := isExecutable(candidatePath); err == nil {
+ return &Client{claudePath: candidatePath}, nil
+ }
+ }
+ }
```
@@ -209,11 +207,11 @@ This function is important because it defines how HumanLayer Tutorial: Context E
```mermaid
flowchart TD
- A[getTypeColor]
- B[_formatHeader]
- C[_colorizeJson]
- D[formatTodoList]
- E[formatConcise]
+ A[isClosedPipeError]
+ B[shouldSkipPath]
+ C[ShouldSkipPath]
+ D[NewClient]
+ E[NewClientWithPath]
A --> B
B --> C
C --> D
diff --git a/tutorials/humanlayer-tutorial/02-architecture-and-monorepo-layout.md b/tutorials/humanlayer-tutorial/02-architecture-and-monorepo-layout.md
index f1b198c0..52118f68 100644
--- a/tutorials/humanlayer-tutorial/02-architecture-and-monorepo-layout.md
+++ b/tutorials/humanlayer-tutorial/02-architecture-and-monorepo-layout.md
@@ -28,170 +28,168 @@ You now know where to inspect and extend key parts of the HumanLayer codebase.
Next: [Chapter 3: Context Engineering Workflows](03-context-engineering-workflows.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `hack/visualize.ts`
+### `claudecode-go/client.go`
-The `processStream` function in [`hack/visualize.ts`](https://github.com/humanlayer/humanlayer/blob/HEAD/hack/visualize.ts) handles a key part of this chapter's functionality:
+The `GetPath` function in [`claudecode-go/client.go`](https://github.com/humanlayer/humanlayer/blob/HEAD/claudecode-go/client.go) handles a key part of this chapter's functionality:
-```ts
+```go
}
-async function processStream() {
- const rl = createInterface({
- input: process.stdin,
- crlfDelay: Infinity,
- });
-
- const debugMode = process.argv.includes('--debug');
- const toolCalls = new Map(); // Store tool calls by their ID
- const pendingResults = new Map(); // Store results waiting for their tool calls
- let lastLine = null; // Track the last line to detect final message
- let isLastAssistantMessage = false;
-
- rl.on('line', (line) => {
- if (line.trim()) {
- const timestamp = debugMode
- ? `${colors.dim}[${new Date().toISOString()}]${colors.reset} `
- : '';
-
- try {
- const json = JSON.parse(line);
-
- // Check if this is a tool call
- if (json.type === 'assistant' && json.message?.content?.[0]?.id) {
- const toolCall = json.message.content[0];
- const toolId = toolCall.id;
-
- // Store the tool call
- toolCalls.set(toolId, {
- toolCall: json,
- timestamp: timestamp,
-```
+// GetPath returns the path to the Claude binary
+func (c *Client) GetPath() string {
+ return c.claudePath
+}
-This function is important because it defines how HumanLayer Tutorial: Context Engineering and Human-Governed Coding Agents implements the patterns covered in this chapter.
+// GetVersion executes claude --version and returns the version string
+func (c *Client) GetVersion() (string, error) {
+ if c.claudePath == "" {
+ return "", fmt.Errorf("claude path not set")
+ }
+
+ // Create command with timeout to prevent hanging
+ ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+ defer cancel()
+
+ cmd := exec.CommandContext(ctx, c.claudePath, "--version")
+ output, err := cmd.Output()
+ if err != nil {
+ // Check if it was a timeout
+ if ctx.Err() == context.DeadlineExceeded {
+ return "", fmt.Errorf("claude --version timed out after 5 seconds")
+ }
+ // Check for exit error to get more details
+ if exitErr, ok := err.(*exec.ExitError); ok {
+ return "", fmt.Errorf("claude --version failed with exit code %d: %s", exitErr.ExitCode(), string(exitErr.Stderr))
+ }
+ return "", fmt.Errorf("failed to execute claude --version: %w", err)
+ }
-### `hack/visualize.ts`
-
-The `displayToolCallWithResult` function in [`hack/visualize.ts`](https://github.com/humanlayer/humanlayer/blob/HEAD/hack/visualize.ts) handles a key part of this chapter's functionality:
-
-```ts
- if (pendingResults.has(toolId)) {
- const result = pendingResults.get(toolId);
- displayToolCallWithResult(
- toolCall,
- json,
- result.toolResult,
- result.timestamp,
- timestamp
- );
- pendingResults.delete(toolId);
- } else {
- // Display the tool call and mark it as pending
- process.stdout.write(`${timestamp + formatConcise(json)}\n`);
- process.stdout.write(`${colors.dim} ⎿ Waiting for result...${colors.reset}\n\n`);
- }
- }
- // Check if this is a tool result
- else if (json.type === 'user' && json.message?.content?.[0]?.type === 'tool_result') {
- const toolResult = json.message.content[0];
- const toolId = toolResult.tool_use_id;
-
- if (toolCalls.has(toolId)) {
- // We have the matching tool call, display them together
- const stored = toolCalls.get(toolId);
- displayToolCallWithResult(
- stored.toolCall.message.content[0],
- stored.toolCall,
- json,
- stored.timestamp,
- timestamp
- );
- toolCalls.delete(toolId);
+ // Trim whitespace and return
```
This function is important because it defines how HumanLayer Tutorial: Context Engineering and Human-Governed Coding Agents implements the patterns covered in this chapter.
-### `claudecode-go/types.go`
+### `claudecode-go/client.go`
-The `UnmarshalJSON` function in [`claudecode-go/types.go`](https://github.com/humanlayer/humanlayer/blob/HEAD/claudecode-go/types.go) handles a key part of this chapter's functionality:
+The `GetVersion` function in [`claudecode-go/client.go`](https://github.com/humanlayer/humanlayer/blob/HEAD/claudecode-go/client.go) handles a key part of this chapter's functionality:
```go
}
-// UnmarshalJSON implements custom unmarshaling to handle both string and array formats
-func (c *ContentField) UnmarshalJSON(data []byte) error {
- // First try to unmarshal as string
- var str string
- if err := json.Unmarshal(data, &str); err == nil {
- c.Value = str
- return nil
+// GetVersion executes claude --version and returns the version string
+func (c *Client) GetVersion() (string, error) {
+ if c.claudePath == "" {
+ return "", fmt.Errorf("claude path not set")
}
- // If that fails, try array format
- var arr []struct {
- Type string `json:"type"`
- Text string `json:"text"`
+ // Create command with timeout to prevent hanging
+ ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+ defer cancel()
+
+ cmd := exec.CommandContext(ctx, c.claudePath, "--version")
+ output, err := cmd.Output()
+ if err != nil {
+ // Check if it was a timeout
+ if ctx.Err() == context.DeadlineExceeded {
+ return "", fmt.Errorf("claude --version timed out after 5 seconds")
+ }
+ // Check for exit error to get more details
+ if exitErr, ok := err.(*exec.ExitError); ok {
+ return "", fmt.Errorf("claude --version failed with exit code %d: %s", exitErr.ExitCode(), string(exitErr.Stderr))
+ }
+ return "", fmt.Errorf("failed to execute claude --version: %w", err)
}
- if err := json.Unmarshal(data, &arr); err == nil {
- // Concatenate all text elements
- var texts []string
- for _, item := range arr {
- if item.Type == "text" && item.Text != "" {
- texts = append(texts, item.Text)
+
+ // Trim whitespace and return
+ version := strings.TrimSpace(string(output))
+ if version == "" {
+ return "", fmt.Errorf("claude --version returned empty output")
+ }
+
+```
+
+This function is important because it defines how HumanLayer Tutorial: Context Engineering and Human-Governed Coding Agents implements the patterns covered in this chapter.
+
+### `claudecode-go/client.go`
+
+The `isExecutable` function in [`claudecode-go/client.go`](https://github.com/humanlayer/humanlayer/blob/HEAD/claudecode-go/client.go) handles a key part of this chapter's functionality:
+
+```go
+ if _, err := os.Stat(candidatePath); err == nil {
+ // Verify it's executable
+ if err := isExecutable(candidatePath); err == nil {
+ return &Client{claudePath: candidatePath}, nil
}
}
- c.Value = strings.Join(texts, "\n")
- return nil
}
- return fmt.Errorf("content field is neither string nor array format")
+ // Try login shell as last resort
+ if shellPath := tryLoginShell(); shellPath != "" {
+ return &Client{claudePath: shellPath}, nil
+ }
+
+ return nil, fmt.Errorf("claude binary not found in PATH or common locations")
+}
+
+// NewClientWithPath creates a new client with a specific claude binary path
+func NewClientWithPath(claudePath string) *Client {
+ return &Client{
+ claudePath: claudePath,
+ }
+}
+
+// GetPath returns the path to the Claude binary
+func (c *Client) GetPath() string {
+ return c.claudePath
}
-// MarshalJSON implements custom marshaling to always output as string
+// GetVersion executes claude --version and returns the version string
+func (c *Client) GetVersion() (string, error) {
+ if c.claudePath == "" {
+ return "", fmt.Errorf("claude path not set")
```
This function is important because it defines how HumanLayer Tutorial: Context Engineering and Human-Governed Coding Agents implements the patterns covered in this chapter.
-### `claudecode-go/types.go`
+### `claudecode-go/client.go`
-The `MarshalJSON` function in [`claudecode-go/types.go`](https://github.com/humanlayer/humanlayer/blob/HEAD/claudecode-go/types.go) handles a key part of this chapter's functionality:
+The `IsExecutable` function in [`claudecode-go/client.go`](https://github.com/humanlayer/humanlayer/blob/HEAD/claudecode-go/client.go) handles a key part of this chapter's functionality:
```go
}
-// MarshalJSON implements custom marshaling to always output as string
-func (c ContentField) MarshalJSON() ([]byte, error) {
- return json.Marshal(c.Value)
+// IsExecutable checks if file is executable (exported version)
+func IsExecutable(path string) error {
+ return isExecutable(path)
}
-// Content can be text or tool use
-type Content struct {
- Type string `json:"type"`
- Text string `json:"text,omitempty"`
- Thinking string `json:"thinking,omitempty"`
- ID string `json:"id,omitempty"`
- Name string `json:"name,omitempty"`
- Input map[string]interface{} `json:"input,omitempty"`
- ToolUseID string `json:"tool_use_id,omitempty"`
- Content ContentField `json:"content,omitempty"`
+// tryLoginShell attempts to find claude using a login shell
+func tryLoginShell() string {
+ shells := []string{"zsh", "bash"}
+ for _, shell := range shells {
+ cmd := exec.Command(shell, "-lc", "which claude")
+ out, err := cmd.Output()
+ if err == nil {
+ path := strings.TrimSpace(string(out))
+ if path != "" && path != "claude not found" && !shouldSkipPath(path) {
+ return path
+ }
+ }
+ }
+ return ""
}
-// ServerToolUse tracks server-side tool usage
-type ServerToolUse struct {
- WebSearchRequests int `json:"web_search_requests,omitempty"`
-}
+// buildArgs converts SessionConfig into command line arguments
+func (c *Client) buildArgs(config SessionConfig) ([]string, error) {
+ args := []string{}
-// CacheCreation tracks cache creation metrics
-type CacheCreation struct {
- Ephemeral1HInputTokens int `json:"ephemeral_1h_input_tokens,omitempty"`
- Ephemeral5MInputTokens int `json:"ephemeral_5m_input_tokens,omitempty"`
-}
+ // Session management
+ if config.SessionID != "" {
+ args = append(args, "--resume", config.SessionID)
-// Usage tracks token usage
-type Usage struct {
+ // Add fork flag if specified
```
This function is important because it defines how HumanLayer Tutorial: Context Engineering and Human-Governed Coding Agents implements the patterns covered in this chapter.
@@ -201,11 +199,11 @@ This function is important because it defines how HumanLayer Tutorial: Context E
```mermaid
flowchart TD
- A[processStream]
- B[displayToolCallWithResult]
- C[UnmarshalJSON]
- D[MarshalJSON]
- E[UnmarshalJSON]
+ A[GetPath]
+ B[GetVersion]
+ C[isExecutable]
+ D[IsExecutable]
+ E[tryLoginShell]
A --> B
B --> C
C --> D
diff --git a/tutorials/humanlayer-tutorial/03-context-engineering-workflows.md b/tutorials/humanlayer-tutorial/03-context-engineering-workflows.md
index 0610251f..2438ffe2 100644
--- a/tutorials/humanlayer-tutorial/03-context-engineering-workflows.md
+++ b/tutorials/humanlayer-tutorial/03-context-engineering-workflows.md
@@ -37,156 +37,168 @@ You now have a repeatable context workflow pattern for hard coding tasks.
Next: [Chapter 4: Parallel Agent Orchestration](04-parallel-agent-orchestration.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `claudecode-go/types.go`
+### `claudecode-go/client.go`
-The `MarshalJSON` function in [`claudecode-go/types.go`](https://github.com/humanlayer/humanlayer/blob/HEAD/claudecode-go/types.go) handles a key part of this chapter's functionality:
+The `buildArgs` function in [`claudecode-go/client.go`](https://github.com/humanlayer/humanlayer/blob/HEAD/claudecode-go/client.go) handles a key part of this chapter's functionality:
```go
}
-// MarshalJSON implements custom marshaling to always output as string
-func (c ContentField) MarshalJSON() ([]byte, error) {
- return json.Marshal(c.Value)
-}
+// buildArgs converts SessionConfig into command line arguments
+func (c *Client) buildArgs(config SessionConfig) ([]string, error) {
+ args := []string{}
-// Content can be text or tool use
-type Content struct {
- Type string `json:"type"`
- Text string `json:"text,omitempty"`
- Thinking string `json:"thinking,omitempty"`
- ID string `json:"id,omitempty"`
- Name string `json:"name,omitempty"`
- Input map[string]interface{} `json:"input,omitempty"`
- ToolUseID string `json:"tool_use_id,omitempty"`
- Content ContentField `json:"content,omitempty"`
-}
+ // Session management
+ if config.SessionID != "" {
+ args = append(args, "--resume", config.SessionID)
-// ServerToolUse tracks server-side tool usage
-type ServerToolUse struct {
- WebSearchRequests int `json:"web_search_requests,omitempty"`
-}
+ // Add fork flag if specified
+ if config.ForkSession {
+ args = append(args, "--fork-session")
+ }
+ }
-// CacheCreation tracks cache creation metrics
-type CacheCreation struct {
- Ephemeral1HInputTokens int `json:"ephemeral_1h_input_tokens,omitempty"`
- Ephemeral5MInputTokens int `json:"ephemeral_5m_input_tokens,omitempty"`
-}
+ // Model
+ if config.Model != "" {
+ args = append(args, "--model", string(config.Model))
+ }
-// Usage tracks token usage
-type Usage struct {
+ // Output format
+ if config.OutputFormat != "" {
+ args = append(args, "--output-format", string(config.OutputFormat))
+ // stream-json requires --verbose
+ if config.OutputFormat == OutputStreamJSON && !config.Verbose {
+ args = append(args, "--verbose")
+ }
+ }
+
+ // MCP configuration
+ if config.MCPConfig != nil {
```
This function is important because it defines how HumanLayer Tutorial: Context Engineering and Human-Governed Coding Agents implements the patterns covered in this chapter.
-### `claudecode-go/types.go`
+### `claudecode-go/client.go`
-The `ToStrings` function in [`claudecode-go/types.go`](https://github.com/humanlayer/humanlayer/blob/HEAD/claudecode-go/types.go) handles a key part of this chapter's functionality:
+The `Launch` function in [`claudecode-go/client.go`](https://github.com/humanlayer/humanlayer/blob/HEAD/claudecode-go/client.go) handles a key part of this chapter's functionality:
```go
}
-// ToStrings converts denials to string array for backward compatibility
-func (p PermissionDenials) ToStrings() []string {
- if p.Denials == nil {
- return nil
- }
- result := make([]string, len(p.Denials))
- for i, d := range p.Denials {
- result[i] = d.ToolName
+// Launch starts a new Claude session and returns immediately
+func (c *Client) Launch(config SessionConfig) (*Session, error) {
+ args, err := c.buildArgs(config)
+ if err != nil {
+ return nil, err
}
- return result
-}
-// ModelUsageDetail represents usage details for a specific model
-type ModelUsageDetail struct {
- InputTokens int `json:"inputTokens"`
- OutputTokens int `json:"outputTokens"`
- CacheReadInputTokens int `json:"cacheReadInputTokens"`
- CacheCreationInputTokens int `json:"cacheCreationInputTokens"`
- WebSearchRequests int `json:"webSearchRequests"`
- CostUSD float64 `json:"costUSD"`
- ContextWindow int `json:"contextWindow,omitempty"`
-}
+ log.Printf("Executing Claude command: %s %v", c.claudePath, args)
+ cmd := exec.Command(c.claudePath, args...)
+
+ // Set environment variables if specified
+ if len(config.Env) > 0 {
+ cmd.Env = os.Environ() // Start with current environment
+ for key, value := range config.Env {
+ cmd.Env = append(cmd.Env, fmt.Sprintf("%s=%s", key, value))
+ }
+ }
-// Result represents the final result of a Claude session
-type Result struct {
- Type string `json:"type"`
- Subtype string `json:"subtype"`
- CostUSD float64 `json:"total_cost_usd"`
- IsError bool `json:"is_error"`
- DurationMS int `json:"duration_ms"`
+ // Set working directory if specified
+ if config.WorkingDir != "" {
+ workingDir := config.WorkingDir
+
+ // Expand tilde to user home directory
+ if strings.HasPrefix(workingDir, "~/") {
+ if home, err := os.UserHomeDir(); err == nil {
+ workingDir = filepath.Join(home, workingDir[2:])
+ }
+ } else if workingDir == "~" {
+ if home, err := os.UserHomeDir(); err == nil {
+ workingDir = home
```
This function is important because it defines how HumanLayer Tutorial: Context Engineering and Human-Governed Coding Agents implements the patterns covered in this chapter.
-### `claudecode-go/types.go`
+### `claudecode-go/client.go`
-The `SetError` function in [`claudecode-go/types.go`](https://github.com/humanlayer/humanlayer/blob/HEAD/claudecode-go/types.go) handles a key part of this chapter's functionality:
+The `LaunchAndWait` function in [`claudecode-go/client.go`](https://github.com/humanlayer/humanlayer/blob/HEAD/claudecode-go/client.go) handles a key part of this chapter's functionality:
```go
}
-// SetError safely sets the error
-func (s *Session) SetError(err error) {
- s.mu.Lock()
- defer s.mu.Unlock()
- if s.err == nil {
- s.err = err
+// LaunchAndWait starts a Claude session and waits for it to complete
+func (c *Client) LaunchAndWait(config SessionConfig) (*Result, error) {
+ session, err := c.Launch(config)
+ if err != nil {
+ return nil, err
}
+
+ return session.Wait()
}
-// Error safely gets the error
-func (s *Session) Error() error {
- s.mu.RLock()
- defer s.mu.RUnlock()
- return s.err
+// Wait blocks until the session completes and returns the result
+// TODO: Add context support to allow cancellation/timeout. This would help prevent
+// indefinite blocking when waiting for interrupted sessions or hanging processes.
+// Consider adding WaitContext(ctx context.Context) method or updating Wait() signature.
+func (s *Session) Wait() (*Result, error) {
+ <-s.done
+
+ if err := s.Error(); err != nil && s.result == nil {
+ return nil, fmt.Errorf("claude process failed: %w", err)
+ }
+
+ return s.result, nil
}
+// Kill terminates the session
+func (s *Session) Kill() error {
+ if s.cmd.Process != nil {
+ return s.cmd.Process.Kill()
+ }
+ return nil
```
This function is important because it defines how HumanLayer Tutorial: Context Engineering and Human-Governed Coding Agents implements the patterns covered in this chapter.
-### `claudecode-go/types.go`
+### `claudecode-go/client.go`
-The `Error` function in [`claudecode-go/types.go`](https://github.com/humanlayer/humanlayer/blob/HEAD/claudecode-go/types.go) handles a key part of this chapter's functionality:
+The `Wait` function in [`claudecode-go/client.go`](https://github.com/humanlayer/humanlayer/blob/HEAD/claudecode-go/client.go) handles a key part of this chapter's functionality:
```go
- // Result event fields (when type="result")
- CostUSD float64 `json:"total_cost_usd,omitempty"`
- IsError bool `json:"is_error,omitempty"`
- DurationMS int `json:"duration_ms,omitempty"`
- DurationAPI int `json:"duration_api_ms,omitempty"`
- NumTurns int `json:"num_turns,omitempty"`
- Result string `json:"result,omitempty"`
- Usage *Usage `json:"usage,omitempty"`
- ModelUsage map[string]ModelUsageDetail `json:"modelUsage,omitempty"`
- Error string `json:"error,omitempty"`
- PermissionDenials *PermissionDenials `json:"permission_denials,omitempty"`
- UUID string `json:"uuid,omitempty"`
-}
+ }
+
+ // Wait for process to complete in background
+ go func() {
+ // Wait for the command to exit
+ session.SetError(cmd.Wait())
+
+ // IMPORTANT: Wait for parsing to complete before signaling done.
+ // This ensures that all output has been read and processed before
+ // the session is considered complete. Without this synchronization,
+ // Wait() might return before the result is available.
+ <-parseDone
-// MCPStatus represents the status of an MCP server
-type MCPStatus struct {
- Name string `json:"name"`
- Status string `json:"status"`
+ close(session.done)
+ }()
+
+ return session, nil
}
-// Message represents an assistant or user message
-type Message struct {
- ID string `json:"id"`
- Type string `json:"type"`
- Role string `json:"role"`
- Model string `json:"model,omitempty"`
- Content []Content `json:"content"`
- Usage *Usage `json:"usage,omitempty"`
+// LaunchAndWait starts a Claude session and waits for it to complete
+func (c *Client) LaunchAndWait(config SessionConfig) (*Result, error) {
+ session, err := c.Launch(config)
+ if err != nil {
+ return nil, err
+ }
+
+ return session.Wait()
}
-// ContentField handles both string and array content formats
-type ContentField struct {
+// Wait blocks until the session completes and returns the result
+// TODO: Add context support to allow cancellation/timeout. This would help prevent
+// indefinite blocking when waiting for interrupted sessions or hanging processes.
```
This function is important because it defines how HumanLayer Tutorial: Context Engineering and Human-Governed Coding Agents implements the patterns covered in this chapter.
@@ -196,11 +208,11 @@ This function is important because it defines how HumanLayer Tutorial: Context E
```mermaid
flowchart TD
- A[MarshalJSON]
- B[ToStrings]
- C[SetError]
- D[Error]
- E[isClosedPipeError]
+ A[buildArgs]
+ B[Launch]
+ C[LaunchAndWait]
+ D[Wait]
+ E[Kill]
A --> B
B --> C
C --> D
diff --git a/tutorials/humanlayer-tutorial/04-parallel-agent-orchestration.md b/tutorials/humanlayer-tutorial/04-parallel-agent-orchestration.md
index b6982c2d..207c2c73 100644
--- a/tutorials/humanlayer-tutorial/04-parallel-agent-orchestration.md
+++ b/tutorials/humanlayer-tutorial/04-parallel-agent-orchestration.md
@@ -28,170 +28,168 @@ You now understand how to scale from single-agent workflows to coordinated paral
Next: [Chapter 5: Human Approval and High-Stakes Actions](05-human-approval-and-high-stakes-actions.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `claudecode-go/client.go`
-The `shouldSkipPath` function in [`claudecode-go/client.go`](https://github.com/humanlayer/humanlayer/blob/HEAD/claudecode-go/client.go) handles a key part of this chapter's functionality:
+The `Interrupt` function in [`claudecode-go/client.go`](https://github.com/humanlayer/humanlayer/blob/HEAD/claudecode-go/client.go) handles a key part of this chapter's functionality:
```go
}
-// shouldSkipPath checks if a path should be skipped during search
-func shouldSkipPath(path string) bool {
- // Skip node_modules directories
- if strings.Contains(path, "/node_modules/") {
- return true
- }
- // Skip backup files
- if strings.HasSuffix(path, ".bak") {
- return true
+// Interrupt sends a SIGINT signal to the session process
+func (s *Session) Interrupt() error {
+ if s.cmd.Process != nil {
+ return s.cmd.Process.Signal(syscall.SIGINT)
}
- return false
+ return nil
}
-// ShouldSkipPath checks if a path should be skipped during search (exported version)
-func ShouldSkipPath(path string) bool {
- return shouldSkipPath(path)
-}
-
-// NewClient creates a new Claude Code client
-func NewClient() (*Client, error) {
- // First try standard PATH
- path, err := exec.LookPath("claude")
- if err == nil && !shouldSkipPath(path) {
- return &Client{claudePath: path}, nil
- }
+// parseStreamingJSON reads and parses streaming JSON output
+func (s *Session) parseStreamingJSON(stdout, stderr io.Reader) {
+ scanner := bufio.NewScanner(stdout)
+ // Configure scanner to handle large JSON lines (up to 10MB)
+ // This prevents buffer overflow when Claude returns large file contents
+ scanner.Buffer(make([]byte, 0), 10*1024*1024) // 10MB max line size
+ var stderrBuf strings.Builder
+ stderrDone := make(chan struct{})
+
+ // Capture stderr in background
+ go func() {
+ defer close(stderrDone)
+ buf := make([]byte, 1024)
+ for {
+ n, err := stderr.Read(buf)
+ if err != nil {
+ break
+ }
+ stderrBuf.Write(buf[:n])
+ }
+ }()
- // Try common installation paths
- commonPaths := []string{
- filepath.Join(os.Getenv("HOME"), ".claude/local/claude"), // Add Claude's own directory
- filepath.Join(os.Getenv("HOME"), ".npm/bin/claude"),
```
This function is important because it defines how HumanLayer Tutorial: Context Engineering and Human-Governed Coding Agents implements the patterns covered in this chapter.
### `claudecode-go/client.go`
-The `ShouldSkipPath` function in [`claudecode-go/client.go`](https://github.com/humanlayer/humanlayer/blob/HEAD/claudecode-go/client.go) handles a key part of this chapter's functionality:
+The `parseStreamingJSON` function in [`claudecode-go/client.go`](https://github.com/humanlayer/humanlayer/blob/HEAD/claudecode-go/client.go) handles a key part of this chapter's functionality:
```go
-}
-
-// ShouldSkipPath checks if a path should be skipped during search (exported version)
-func ShouldSkipPath(path string) bool {
- return shouldSkipPath(path)
-}
-
-// NewClient creates a new Claude Code client
-func NewClient() (*Client, error) {
- // First try standard PATH
- path, err := exec.LookPath("claude")
- if err == nil && !shouldSkipPath(path) {
- return &Client{claudePath: path}, nil
+ // Start goroutine to parse streaming JSON
+ go func() {
+ session.parseStreamingJSON(stdout, stderr)
+ close(parseDone)
+ }()
+ case OutputJSON:
+ // Start goroutine to parse single JSON result
+ go func() {
+ session.parseSingleJSON(stdout, stderr)
+ close(parseDone)
+ }()
+ default:
+ // Text output - just capture the result
+ go func() {
+ session.parseTextOutput(stdout, stderr)
+ close(parseDone)
+ }()
}
- // Try common installation paths
- commonPaths := []string{
- filepath.Join(os.Getenv("HOME"), ".claude/local/claude"), // Add Claude's own directory
- filepath.Join(os.Getenv("HOME"), ".npm/bin/claude"),
- filepath.Join(os.Getenv("HOME"), ".bun/bin/claude"),
- filepath.Join(os.Getenv("HOME"), ".local/bin/claude"),
- "/usr/local/bin/claude",
- "/opt/homebrew/bin/claude",
- }
+ // Wait for process to complete in background
+ go func() {
+ // Wait for the command to exit
+ session.SetError(cmd.Wait())
- for _, candidatePath := range commonPaths {
- if shouldSkipPath(candidatePath) {
- continue
- }
- if _, err := os.Stat(candidatePath); err == nil {
- // Verify it's executable
- if err := isExecutable(candidatePath); err == nil {
+ // IMPORTANT: Wait for parsing to complete before signaling done.
+ // This ensures that all output has been read and processed before
+ // the session is considered complete. Without this synchronization,
+ // Wait() might return before the result is available.
+ <-parseDone
+
+ close(session.done)
+ }()
```
This function is important because it defines how HumanLayer Tutorial: Context Engineering and Human-Governed Coding Agents implements the patterns covered in this chapter.
### `claudecode-go/client.go`
-The `NewClient` function in [`claudecode-go/client.go`](https://github.com/humanlayer/humanlayer/blob/HEAD/claudecode-go/client.go) handles a key part of this chapter's functionality:
+The `parseSingleJSON` function in [`claudecode-go/client.go`](https://github.com/humanlayer/humanlayer/blob/HEAD/claudecode-go/client.go) handles a key part of this chapter's functionality:
```go
-}
-
-// NewClient creates a new Claude Code client
-func NewClient() (*Client, error) {
- // First try standard PATH
- path, err := exec.LookPath("claude")
- if err == nil && !shouldSkipPath(path) {
- return &Client{claudePath: path}, nil
+ // Start goroutine to parse single JSON result
+ go func() {
+ session.parseSingleJSON(stdout, stderr)
+ close(parseDone)
+ }()
+ default:
+ // Text output - just capture the result
+ go func() {
+ session.parseTextOutput(stdout, stderr)
+ close(parseDone)
+ }()
}
- // Try common installation paths
- commonPaths := []string{
- filepath.Join(os.Getenv("HOME"), ".claude/local/claude"), // Add Claude's own directory
- filepath.Join(os.Getenv("HOME"), ".npm/bin/claude"),
- filepath.Join(os.Getenv("HOME"), ".bun/bin/claude"),
- filepath.Join(os.Getenv("HOME"), ".local/bin/claude"),
- "/usr/local/bin/claude",
- "/opt/homebrew/bin/claude",
- }
+ // Wait for process to complete in background
+ go func() {
+ // Wait for the command to exit
+ session.SetError(cmd.Wait())
- for _, candidatePath := range commonPaths {
- if shouldSkipPath(candidatePath) {
- continue
- }
- if _, err := os.Stat(candidatePath); err == nil {
- // Verify it's executable
- if err := isExecutable(candidatePath); err == nil {
- return &Client{claudePath: candidatePath}, nil
- }
- }
- }
+ // IMPORTANT: Wait for parsing to complete before signaling done.
+ // This ensures that all output has been read and processed before
+ // the session is considered complete. Without this synchronization,
+ // Wait() might return before the result is available.
+ <-parseDone
+
+ close(session.done)
+ }()
+ return session, nil
+}
+
+// LaunchAndWait starts a Claude session and waits for it to complete
+func (c *Client) LaunchAndWait(config SessionConfig) (*Result, error) {
```
This function is important because it defines how HumanLayer Tutorial: Context Engineering and Human-Governed Coding Agents implements the patterns covered in this chapter.
### `claudecode-go/client.go`
-The `NewClientWithPath` function in [`claudecode-go/client.go`](https://github.com/humanlayer/humanlayer/blob/HEAD/claudecode-go/client.go) handles a key part of this chapter's functionality:
+The `parseTextOutput` function in [`claudecode-go/client.go`](https://github.com/humanlayer/humanlayer/blob/HEAD/claudecode-go/client.go) handles a key part of this chapter's functionality:
```go
-}
-
-// NewClientWithPath creates a new client with a specific claude binary path
-func NewClientWithPath(claudePath string) *Client {
- return &Client{
- claudePath: claudePath,
+ // Text output - just capture the result
+ go func() {
+ session.parseTextOutput(stdout, stderr)
+ close(parseDone)
+ }()
}
-}
-// GetPath returns the path to the Claude binary
-func (c *Client) GetPath() string {
- return c.claudePath
-}
+ // Wait for process to complete in background
+ go func() {
+ // Wait for the command to exit
+ session.SetError(cmd.Wait())
-// GetVersion executes claude --version and returns the version string
-func (c *Client) GetVersion() (string, error) {
- if c.claudePath == "" {
- return "", fmt.Errorf("claude path not set")
- }
+ // IMPORTANT: Wait for parsing to complete before signaling done.
+ // This ensures that all output has been read and processed before
+ // the session is considered complete. Without this synchronization,
+ // Wait() might return before the result is available.
+ <-parseDone
+
+ close(session.done)
+ }()
- // Create command with timeout to prevent hanging
- ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
- defer cancel()
+ return session, nil
+}
- cmd := exec.CommandContext(ctx, c.claudePath, "--version")
- output, err := cmd.Output()
+// LaunchAndWait starts a Claude session and waits for it to complete
+func (c *Client) LaunchAndWait(config SessionConfig) (*Result, error) {
+ session, err := c.Launch(config)
if err != nil {
- // Check if it was a timeout
- if ctx.Err() == context.DeadlineExceeded {
- return "", fmt.Errorf("claude --version timed out after 5 seconds")
- }
- // Check for exit error to get more details
+ return nil, err
+ }
+
+ return session.Wait()
```
This function is important because it defines how HumanLayer Tutorial: Context Engineering and Human-Governed Coding Agents implements the patterns covered in this chapter.
@@ -201,11 +199,11 @@ This function is important because it defines how HumanLayer Tutorial: Context E
```mermaid
flowchart TD
- A[shouldSkipPath]
- B[ShouldSkipPath]
- C[NewClient]
- D[NewClientWithPath]
- E[GetPath]
+ A[Interrupt]
+ B[parseStreamingJSON]
+ C[parseSingleJSON]
+ D[parseTextOutput]
+ E[getTypeColor]
A --> B
B --> C
C --> D
diff --git a/tutorials/humanlayer-tutorial/05-human-approval-and-high-stakes-actions.md b/tutorials/humanlayer-tutorial/05-human-approval-and-high-stakes-actions.md
index 55f53c77..97625c3d 100644
--- a/tutorials/humanlayer-tutorial/05-human-approval-and-high-stakes-actions.md
+++ b/tutorials/humanlayer-tutorial/05-human-approval-and-high-stakes-actions.md
@@ -37,186 +37,26 @@ You now have a practical approval framework for risky coding-agent operations.
Next: [Chapter 6: IDE and CLI Integration Patterns](06-ide-and-cli-integration-patterns.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `claudecode-go/client.go`
-
-The `GetVersion` function in [`claudecode-go/client.go`](https://github.com/humanlayer/humanlayer/blob/HEAD/claudecode-go/client.go) handles a key part of this chapter's functionality:
-
-```go
-}
-
-// GetVersion executes claude --version and returns the version string
-func (c *Client) GetVersion() (string, error) {
- if c.claudePath == "" {
- return "", fmt.Errorf("claude path not set")
- }
-
- // Create command with timeout to prevent hanging
- ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
- defer cancel()
-
- cmd := exec.CommandContext(ctx, c.claudePath, "--version")
- output, err := cmd.Output()
- if err != nil {
- // Check if it was a timeout
- if ctx.Err() == context.DeadlineExceeded {
- return "", fmt.Errorf("claude --version timed out after 5 seconds")
- }
- // Check for exit error to get more details
- if exitErr, ok := err.(*exec.ExitError); ok {
- return "", fmt.Errorf("claude --version failed with exit code %d: %s", exitErr.ExitCode(), string(exitErr.Stderr))
- }
- return "", fmt.Errorf("failed to execute claude --version: %w", err)
- }
-
- // Trim whitespace and return
- version := strings.TrimSpace(string(output))
- if version == "" {
- return "", fmt.Errorf("claude --version returned empty output")
- }
-
-```
-
-This function is important because it defines how HumanLayer Tutorial: Context Engineering and Human-Governed Coding Agents implements the patterns covered in this chapter.
-
-### `claudecode-go/client.go`
-
-The `isExecutable` function in [`claudecode-go/client.go`](https://github.com/humanlayer/humanlayer/blob/HEAD/claudecode-go/client.go) handles a key part of this chapter's functionality:
-
-```go
- if _, err := os.Stat(candidatePath); err == nil {
- // Verify it's executable
- if err := isExecutable(candidatePath); err == nil {
- return &Client{claudePath: candidatePath}, nil
- }
- }
- }
-
- // Try login shell as last resort
- if shellPath := tryLoginShell(); shellPath != "" {
- return &Client{claudePath: shellPath}, nil
- }
-
- return nil, fmt.Errorf("claude binary not found in PATH or common locations")
-}
-
-// NewClientWithPath creates a new client with a specific claude binary path
-func NewClientWithPath(claudePath string) *Client {
- return &Client{
- claudePath: claudePath,
- }
-}
-
-// GetPath returns the path to the Claude binary
-func (c *Client) GetPath() string {
- return c.claudePath
-}
-
-// GetVersion executes claude --version and returns the version string
-func (c *Client) GetVersion() (string, error) {
- if c.claudePath == "" {
- return "", fmt.Errorf("claude path not set")
-```
-
-This function is important because it defines how HumanLayer Tutorial: Context Engineering and Human-Governed Coding Agents implements the patterns covered in this chapter.
-
-### `claudecode-go/client.go`
-
-The `IsExecutable` function in [`claudecode-go/client.go`](https://github.com/humanlayer/humanlayer/blob/HEAD/claudecode-go/client.go) handles a key part of this chapter's functionality:
-
-```go
-}
-
-// IsExecutable checks if file is executable (exported version)
-func IsExecutable(path string) error {
- return isExecutable(path)
-}
-
-// tryLoginShell attempts to find claude using a login shell
-func tryLoginShell() string {
- shells := []string{"zsh", "bash"}
- for _, shell := range shells {
- cmd := exec.Command(shell, "-lc", "which claude")
- out, err := cmd.Output()
- if err == nil {
- path := strings.TrimSpace(string(out))
- if path != "" && path != "claude not found" && !shouldSkipPath(path) {
- return path
- }
- }
- }
- return ""
-}
-
-// buildArgs converts SessionConfig into command line arguments
-func (c *Client) buildArgs(config SessionConfig) ([]string, error) {
- args := []string{}
-
- // Session management
- if config.SessionID != "" {
- args = append(args, "--resume", config.SessionID)
-
- // Add fork flag if specified
-```
+### `humanlayer.md`
-This function is important because it defines how HumanLayer Tutorial: Context Engineering and Human-Governed Coding Agents implements the patterns covered in this chapter.
+The [`humanlayer.md`](https://github.com/humanlayer/humanlayer/blob/main/humanlayer.md) document defines the human approval API surface — `require_approval`, `HumanLayer`, and the tool-call classification patterns used to gate high-stakes actions. This is the primary source for the stake-level model and governance pattern described in this chapter.
### `claudecode-go/client.go`
-The `tryLoginShell` function in [`claudecode-go/client.go`](https://github.com/humanlayer/humanlayer/blob/HEAD/claudecode-go/client.go) handles a key part of this chapter's functionality:
-
-```go
-
- // Try login shell as last resort
- if shellPath := tryLoginShell(); shellPath != "" {
- return &Client{claudePath: shellPath}, nil
- }
-
- return nil, fmt.Errorf("claude binary not found in PATH or common locations")
-}
-
-// NewClientWithPath creates a new client with a specific claude binary path
-func NewClientWithPath(claudePath string) *Client {
- return &Client{
- claudePath: claudePath,
- }
-}
-
-// GetPath returns the path to the Claude binary
-func (c *Client) GetPath() string {
- return c.claudePath
-}
-
-// GetVersion executes claude --version and returns the version string
-func (c *Client) GetVersion() (string, error) {
- if c.claudePath == "" {
- return "", fmt.Errorf("claude path not set")
- }
-
- // Create command with timeout to prevent hanging
- ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
- defer cancel()
-
- cmd := exec.CommandContext(ctx, c.claudePath, "--version")
-```
-
-This function is important because it defines how HumanLayer Tutorial: Context Engineering and Human-Governed Coding Agents implements the patterns covered in this chapter.
-
+The [`claudecode-go/client.go`](https://github.com/humanlayer/humanlayer/blob/HEAD/claudecode-go/client.go) file shows how the Go client integrates with the Claude Code subprocess and how tool-call events are intercepted before execution. The approval gate logic wraps tool calls based on their stake classification — the low/medium/high model this chapter documents.
## How These Components Connect
```mermaid
flowchart TD
- A[GetVersion]
- B[isExecutable]
- C[IsExecutable]
- D[tryLoginShell]
- E[buildArgs]
- A --> B
- B --> C
- C --> D
- D --> E
+ A[Agent tool call] --> B[Stake Classification]
+ B -->|low stake| C[Auto-approve]
+ B -->|medium stake| D[Log and proceed]
+ B -->|high stake| E[require_approval gate]
+ E -->|human approves| F[Execute tool call]
+ E -->|human rejects| G[Cancel with explanation]
+ F --> H[Audit trail captured]
+ G --> H
```
diff --git a/tutorials/humanlayer-tutorial/06-ide-and-cli-integration-patterns.md b/tutorials/humanlayer-tutorial/06-ide-and-cli-integration-patterns.md
index 8082b190..6df20da2 100644
--- a/tutorials/humanlayer-tutorial/06-ide-and-cli-integration-patterns.md
+++ b/tutorials/humanlayer-tutorial/06-ide-and-cli-integration-patterns.md
@@ -25,186 +25,25 @@ You now have baseline patterns to embed HumanLayer workflows into daily IDE and
Next: [Chapter 7: Telemetry, Cost, and Team Governance](07-telemetry-cost-and-team-governance.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `claudecode-go/client.go`
-The `Launch` function in [`claudecode-go/client.go`](https://github.com/humanlayer/humanlayer/blob/HEAD/claudecode-go/client.go) handles a key part of this chapter's functionality:
-
-```go
-}
-
-// Launch starts a new Claude session and returns immediately
-func (c *Client) Launch(config SessionConfig) (*Session, error) {
- args, err := c.buildArgs(config)
- if err != nil {
- return nil, err
- }
-
- log.Printf("Executing Claude command: %s %v", c.claudePath, args)
- cmd := exec.Command(c.claudePath, args...)
-
- // Set environment variables if specified
- if len(config.Env) > 0 {
- cmd.Env = os.Environ() // Start with current environment
- for key, value := range config.Env {
- cmd.Env = append(cmd.Env, fmt.Sprintf("%s=%s", key, value))
- }
- }
-
- // Set working directory if specified
- if config.WorkingDir != "" {
- workingDir := config.WorkingDir
-
- // Expand tilde to user home directory
- if strings.HasPrefix(workingDir, "~/") {
- if home, err := os.UserHomeDir(); err == nil {
- workingDir = filepath.Join(home, workingDir[2:])
- }
- } else if workingDir == "~" {
- if home, err := os.UserHomeDir(); err == nil {
- workingDir = home
-```
-
-This function is important because it defines how HumanLayer Tutorial: Context Engineering and Human-Governed Coding Agents implements the patterns covered in this chapter.
-
-### `claudecode-go/client.go`
-
-The `LaunchAndWait` function in [`claudecode-go/client.go`](https://github.com/humanlayer/humanlayer/blob/HEAD/claudecode-go/client.go) handles a key part of this chapter's functionality:
-
-```go
-}
-
-// LaunchAndWait starts a Claude session and waits for it to complete
-func (c *Client) LaunchAndWait(config SessionConfig) (*Result, error) {
- session, err := c.Launch(config)
- if err != nil {
- return nil, err
- }
-
- return session.Wait()
-}
-
-// Wait blocks until the session completes and returns the result
-// TODO: Add context support to allow cancellation/timeout. This would help prevent
-// indefinite blocking when waiting for interrupted sessions or hanging processes.
-// Consider adding WaitContext(ctx context.Context) method or updating Wait() signature.
-func (s *Session) Wait() (*Result, error) {
- <-s.done
-
- if err := s.Error(); err != nil && s.result == nil {
- return nil, fmt.Errorf("claude process failed: %w", err)
- }
-
- return s.result, nil
-}
-
-// Kill terminates the session
-func (s *Session) Kill() error {
- if s.cmd.Process != nil {
- return s.cmd.Process.Kill()
- }
- return nil
-```
-
-This function is important because it defines how HumanLayer Tutorial: Context Engineering and Human-Governed Coding Agents implements the patterns covered in this chapter.
-
-### `claudecode-go/client.go`
-
-The `Wait` function in [`claudecode-go/client.go`](https://github.com/humanlayer/humanlayer/blob/HEAD/claudecode-go/client.go) handles a key part of this chapter's functionality:
-
-```go
- }
-
- // Wait for process to complete in background
- go func() {
- // Wait for the command to exit
- session.SetError(cmd.Wait())
-
- // IMPORTANT: Wait for parsing to complete before signaling done.
- // This ensures that all output has been read and processed before
- // the session is considered complete. Without this synchronization,
- // Wait() might return before the result is available.
- <-parseDone
-
- close(session.done)
- }()
-
- return session, nil
-}
-
-// LaunchAndWait starts a Claude session and waits for it to complete
-func (c *Client) LaunchAndWait(config SessionConfig) (*Result, error) {
- session, err := c.Launch(config)
- if err != nil {
- return nil, err
- }
-
- return session.Wait()
-}
-
-// Wait blocks until the session completes and returns the result
-// TODO: Add context support to allow cancellation/timeout. This would help prevent
-// indefinite blocking when waiting for interrupted sessions or hanging processes.
-```
-
-This function is important because it defines how HumanLayer Tutorial: Context Engineering and Human-Governed Coding Agents implements the patterns covered in this chapter.
-
-### `claudecode-go/client.go`
-
-The `Kill` function in [`claudecode-go/client.go`](https://github.com/humanlayer/humanlayer/blob/HEAD/claudecode-go/client.go) handles a key part of this chapter's functionality:
-
-```go
-}
-
-// Kill terminates the session
-func (s *Session) Kill() error {
- if s.cmd.Process != nil {
- return s.cmd.Process.Kill()
- }
- return nil
-}
-
-// Interrupt sends a SIGINT signal to the session process
-func (s *Session) Interrupt() error {
- if s.cmd.Process != nil {
- return s.cmd.Process.Signal(syscall.SIGINT)
- }
- return nil
-}
-
-// parseStreamingJSON reads and parses streaming JSON output
-func (s *Session) parseStreamingJSON(stdout, stderr io.Reader) {
- scanner := bufio.NewScanner(stdout)
- // Configure scanner to handle large JSON lines (up to 10MB)
- // This prevents buffer overflow when Claude returns large file contents
- scanner.Buffer(make([]byte, 0), 10*1024*1024) // 10MB max line size
- var stderrBuf strings.Builder
- stderrDone := make(chan struct{})
-
- // Capture stderr in background
- go func() {
- defer close(stderrDone)
- buf := make([]byte, 1024)
- for {
-```
+The [`claudecode-go/client.go`](https://github.com/humanlayer/humanlayer/blob/HEAD/claudecode-go/client.go) file implements the core Claude Code subprocess client. The `buildArgs` and `GetPath` functions define how the CLI arguments and project path are configured when launching coding agents from a terminal or IDE integration — directly relevant to the IDE and CLI workflow patterns this chapter covers.
-This function is important because it defines how HumanLayer Tutorial: Context Engineering and Human-Governed Coding Agents implements the patterns covered in this chapter.
+### `humanlayer.md`
+The [`humanlayer.md`](https://github.com/humanlayer/humanlayer/blob/main/humanlayer.md) document describes the SDK integration patterns that teams embed in their IDE and CLI workflows. It covers how to configure HumanLayer as a wrapper around coding-agent tool calls, enabling the standardized workflow commands and context templates described in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[Launch]
- B[LaunchAndWait]
- C[Wait]
- D[Kill]
- E[Interrupt]
- A --> B
- B --> C
- C --> D
- D --> E
+ A[Developer in IDE/Terminal] --> B[claudecode-go/client.go]
+ B -->|buildArgs| C[Claude Code subprocess]
+ C -->|tool call event| D[HumanLayer approval layer]
+ D -->|approved| E[Action executed]
+ D -->|rejected| F[Blocked with reason]
+ E --> G[PR review artifact]
+ F --> G
```
diff --git a/tutorials/humanlayer-tutorial/07-telemetry-cost-and-team-governance.md b/tutorials/humanlayer-tutorial/07-telemetry-cost-and-team-governance.md
index 3042cbfa..880e5b96 100644
--- a/tutorials/humanlayer-tutorial/07-telemetry-cost-and-team-governance.md
+++ b/tutorials/humanlayer-tutorial/07-telemetry-cost-and-team-governance.md
@@ -28,186 +28,27 @@ You now have a metric framework for sustainable team operations.
Next: [Chapter 8: Production Rollout and Adoption](08-production-rollout-and-adoption.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `claudecode-go/client.go`
-
-The `parseStreamingJSON` function in [`claudecode-go/client.go`](https://github.com/humanlayer/humanlayer/blob/HEAD/claudecode-go/client.go) handles a key part of this chapter's functionality:
-
-```go
- // Start goroutine to parse streaming JSON
- go func() {
- session.parseStreamingJSON(stdout, stderr)
- close(parseDone)
- }()
- case OutputJSON:
- // Start goroutine to parse single JSON result
- go func() {
- session.parseSingleJSON(stdout, stderr)
- close(parseDone)
- }()
- default:
- // Text output - just capture the result
- go func() {
- session.parseTextOutput(stdout, stderr)
- close(parseDone)
- }()
- }
-
- // Wait for process to complete in background
- go func() {
- // Wait for the command to exit
- session.SetError(cmd.Wait())
-
- // IMPORTANT: Wait for parsing to complete before signaling done.
- // This ensures that all output has been read and processed before
- // the session is considered complete. Without this synchronization,
- // Wait() might return before the result is available.
- <-parseDone
-
- close(session.done)
- }()
-```
-
-This function is important because it defines how HumanLayer Tutorial: Context Engineering and Human-Governed Coding Agents implements the patterns covered in this chapter.
-
-### `claudecode-go/client.go`
-
-The `parseSingleJSON` function in [`claudecode-go/client.go`](https://github.com/humanlayer/humanlayer/blob/HEAD/claudecode-go/client.go) handles a key part of this chapter's functionality:
-
-```go
- // Start goroutine to parse single JSON result
- go func() {
- session.parseSingleJSON(stdout, stderr)
- close(parseDone)
- }()
- default:
- // Text output - just capture the result
- go func() {
- session.parseTextOutput(stdout, stderr)
- close(parseDone)
- }()
- }
-
- // Wait for process to complete in background
- go func() {
- // Wait for the command to exit
- session.SetError(cmd.Wait())
-
- // IMPORTANT: Wait for parsing to complete before signaling done.
- // This ensures that all output has been read and processed before
- // the session is considered complete. Without this synchronization,
- // Wait() might return before the result is available.
- <-parseDone
-
- close(session.done)
- }()
-
- return session, nil
-}
-
-// LaunchAndWait starts a Claude session and waits for it to complete
-func (c *Client) LaunchAndWait(config SessionConfig) (*Result, error) {
-```
-
-This function is important because it defines how HumanLayer Tutorial: Context Engineering and Human-Governed Coding Agents implements the patterns covered in this chapter.
-
-### `claudecode-go/client.go`
-
-The `parseTextOutput` function in [`claudecode-go/client.go`](https://github.com/humanlayer/humanlayer/blob/HEAD/claudecode-go/client.go) handles a key part of this chapter's functionality:
-
-```go
- // Text output - just capture the result
- go func() {
- session.parseTextOutput(stdout, stderr)
- close(parseDone)
- }()
- }
+### `claudecode-go/types.go`
- // Wait for process to complete in background
- go func() {
- // Wait for the command to exit
- session.SetError(cmd.Wait())
-
- // IMPORTANT: Wait for parsing to complete before signaling done.
- // This ensures that all output has been read and processed before
- // the session is considered complete. Without this synchronization,
- // Wait() might return before the result is available.
- <-parseDone
-
- close(session.done)
- }()
-
- return session, nil
-}
-
-// LaunchAndWait starts a Claude session and waits for it to complete
-func (c *Client) LaunchAndWait(config SessionConfig) (*Result, error) {
- session, err := c.Launch(config)
- if err != nil {
- return nil, err
- }
-
- return session.Wait()
-```
-
-This function is important because it defines how HumanLayer Tutorial: Context Engineering and Human-Governed Coding Agents implements the patterns covered in this chapter.
-
-### `hack/rotate_icon_colors.py`
-
-The `rgb_to_hsv` function in [`hack/rotate_icon_colors.py`](https://github.com/humanlayer/humanlayer/blob/HEAD/hack/rotate_icon_colors.py) handles a key part of this chapter's functionality:
-
-```py
-import numpy as np
-
-def rgb_to_hsv(rgb):
- """Convert RGB to HSV using numpy for speed"""
- rgb = rgb.astype('float32') / 255.0
- maxc = np.max(rgb, axis=2)
- minc = np.min(rgb, axis=2)
- v = maxc
-
- deltac = maxc - minc
- s = np.where(maxc != 0, deltac / maxc, 0)
-
- # Hue calculation
- rc = np.where(deltac != 0, (maxc - rgb[:,:,0]) / deltac, 0)
- gc = np.where(deltac != 0, (maxc - rgb[:,:,1]) / deltac, 0)
- bc = np.where(deltac != 0, (maxc - rgb[:,:,2]) / deltac, 0)
-
- h = np.zeros_like(maxc)
- h = np.where((rgb[:,:,0] == maxc) & (deltac != 0), bc - gc, h)
- h = np.where((rgb[:,:,1] == maxc) & (deltac != 0), 2.0 + rc - bc, h)
- h = np.where((rgb[:,:,2] == maxc) & (deltac != 0), 4.0 + gc - rc, h)
- h = (h / 6.0) % 1.0
-
- return np.stack([h, s, v], axis=2)
-
-def hsv_to_rgb(hsv):
- """Convert HSV back to RGB"""
- h, s, v = hsv[:,:,0], hsv[:,:,1], hsv[:,:,2]
-
- i = np.floor(h * 6.0).astype(int)
- f = h * 6.0 - i
- p = v * (1.0 - s)
-```
+The [`claudecode-go/types.go`](https://github.com/humanlayer/humanlayer/blob/HEAD/claudecode-go/types.go) file defines the structured event types emitted by the Claude Code subprocess — tool calls, results, usage metrics, and agent outputs. These typed events are the raw telemetry stream from which the quality and cost metrics described in this chapter (accepted patch rate, token spend per task) are derived.
-This function is important because it defines how HumanLayer Tutorial: Context Engineering and Human-Governed Coding Agents implements the patterns covered in this chapter.
+### `humanlayer.md`
+The [`humanlayer.md`](https://github.com/humanlayer/humanlayer/blob/main/humanlayer.md) SDK reference documents the governance hooks — policy violation callbacks, manual override logging, and audit trail capture — that feed the governance metrics (policy violations, manual overrides) in the metrics table of this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[parseStreamingJSON]
- B[parseSingleJSON]
- C[parseTextOutput]
- D[rgb_to_hsv]
- E[hsv_to_rgb]
- A --> B
- B --> C
- C --> D
- D --> E
+ A[claudecode-go/types.go] -->|typed events| B[Telemetry stream]
+ B -->|token counts| C[Cost metrics: spend per task]
+ B -->|tool call/result pairs| D[Quality metrics: patch rate]
+ B -->|time deltas| E[Efficiency metrics: time-to-diff]
+ F[humanlayer.md governance hooks] -->|override events| G[Governance metrics]
+ C --> H[Team dashboard]
+ D --> H
+ E --> H
+ G --> H
```
diff --git a/tutorials/humanlayer-tutorial/08-production-rollout-and-adoption.md b/tutorials/humanlayer-tutorial/08-production-rollout-and-adoption.md
index 924433ef..0dcc905c 100644
--- a/tutorials/humanlayer-tutorial/08-production-rollout-and-adoption.md
+++ b/tutorials/humanlayer-tutorial/08-production-rollout-and-adoption.md
@@ -30,165 +30,168 @@ This chapter outlines a rollout model for adopting HumanLayer workflows across t
You now have a phased adoption strategy for scaling coding-agent workflows with human governance.
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `hack/rotate_icon_colors.py`
-
-The `rotate_hue` function in [`hack/rotate_icon_colors.py`](https://github.com/humanlayer/humanlayer/blob/HEAD/hack/rotate_icon_colors.py) handles a key part of this chapter's functionality:
-
-```py
- return (rgb * 255).astype('uint8')
-
-def rotate_hue(image_path, output_path, hue_shift=0.3):
- """Rotate hue of an image by specified amount (0.3 = 108 degrees)"""
- img = Image.open(image_path).convert('RGBA')
- rgb = np.array(img)
-
- # Separate alpha channel
- alpha = rgb[:,:,3]
- rgb_only = rgb[:,:,:3]
-
- # Convert to HSV, rotate hue, convert back
- hsv = rgb_to_hsv(rgb_only)
- hsv[:,:,0] = (hsv[:,:,0] + hue_shift) % 1.0
- rgb_rotated = hsv_to_rgb(hsv)
-
- # Recombine with alpha
- result = np.dstack([rgb_rotated, alpha])
-
- Image.fromarray(result, 'RGBA').save(output_path)
-
-if __name__ == "__main__":
- if len(sys.argv) != 3:
- print("Usage: python rotate_icon_colors.py input.png output.png")
- sys.exit(1)
-
- rotate_hue(sys.argv[1], sys.argv[2], hue_shift=0.3)
+### `claudecode-go/types.go`
+
+The `MarshalJSON` function in [`claudecode-go/types.go`](https://github.com/humanlayer/humanlayer/blob/HEAD/claudecode-go/types.go) handles a key part of this chapter's functionality:
+
+```go
+}
+
+// MarshalJSON implements custom marshaling to always output as string
+func (c ContentField) MarshalJSON() ([]byte, error) {
+ return json.Marshal(c.Value)
+}
+
+// Content can be text or tool use
+type Content struct {
+ Type string `json:"type"`
+ Text string `json:"text,omitempty"`
+ Thinking string `json:"thinking,omitempty"`
+ ID string `json:"id,omitempty"`
+ Name string `json:"name,omitempty"`
+ Input map[string]interface{} `json:"input,omitempty"`
+ ToolUseID string `json:"tool_use_id,omitempty"`
+ Content ContentField `json:"content,omitempty"`
+}
+
+// ServerToolUse tracks server-side tool usage
+type ServerToolUse struct {
+ WebSearchRequests int `json:"web_search_requests,omitempty"`
+}
+
+// CacheCreation tracks cache creation metrics
+type CacheCreation struct {
+ Ephemeral1HInputTokens int `json:"ephemeral_1h_input_tokens,omitempty"`
+ Ephemeral5MInputTokens int `json:"ephemeral_5m_input_tokens,omitempty"`
+}
+
+// Usage tracks token usage
+type Usage struct {
```
This function is important because it defines how HumanLayer Tutorial: Context Engineering and Human-Governed Coding Agents implements the patterns covered in this chapter.
-### `hack/generate_rounded_icons.py`
-
-The `create_rounded_corners_mask` function in [`hack/generate_rounded_icons.py`](https://github.com/humanlayer/humanlayer/blob/HEAD/hack/generate_rounded_icons.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def create_rounded_corners_mask(size, radius):
- """Create a mask for rounded corners"""
- mask = Image.new("L", (size, size), 0)
- draw = ImageDraw.Draw(mask)
-
- # Draw a rounded rectangle
- draw.rounded_rectangle([(0, 0), (size - 1, size - 1)], radius=radius, fill=255)
-
- return mask
-
-
-def create_rounded_icon(source_path, output_path, size):
- """Create a rounded corner icon at the specified size"""
- # Open and resize the source image
- img = Image.open(source_path)
- img = img.convert("RGBA")
- img = img.resize((size, size), Image.Resampling.LANCZOS)
-
- # Create a rounded corners mask
- radius = size // 5 # 20% corner radius
- mask = create_rounded_corners_mask(size, radius)
-
- # Create output image with transparent background
- output = Image.new("RGBA", (size, size), (0, 0, 0, 0))
- output.paste(img, (0, 0))
-
- # Apply the mask to the alpha channel
- output.putalpha(mask)
-
- # Save the result
+### `claudecode-go/types.go`
+
+The `UnmarshalJSON` function in [`claudecode-go/types.go`](https://github.com/humanlayer/humanlayer/blob/HEAD/claudecode-go/types.go) handles a key part of this chapter's functionality:
+
+```go
+}
+
+// UnmarshalJSON implements custom unmarshaling to handle both string and array formats
+func (c *ContentField) UnmarshalJSON(data []byte) error {
+ // First try to unmarshal as string
+ var str string
+ if err := json.Unmarshal(data, &str); err == nil {
+ c.Value = str
+ return nil
+ }
+
+ // If that fails, try array format
+ var arr []struct {
+ Type string `json:"type"`
+ Text string `json:"text"`
+ }
+ if err := json.Unmarshal(data, &arr); err == nil {
+ // Concatenate all text elements
+ var texts []string
+ for _, item := range arr {
+ if item.Type == "text" && item.Text != "" {
+ texts = append(texts, item.Text)
+ }
+ }
+ c.Value = strings.Join(texts, "\n")
+ return nil
+ }
+
+ return fmt.Errorf("content field is neither string nor array format")
+}
+
+// MarshalJSON implements custom marshaling to always output as string
```
This function is important because it defines how HumanLayer Tutorial: Context Engineering and Human-Governed Coding Agents implements the patterns covered in this chapter.
-### `hack/generate_rounded_icons.py`
-
-The `create_rounded_icon` function in [`hack/generate_rounded_icons.py`](https://github.com/humanlayer/humanlayer/blob/HEAD/hack/generate_rounded_icons.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def create_rounded_icon(source_path, output_path, size):
- """Create a rounded corner icon at the specified size"""
- # Open and resize the source image
- img = Image.open(source_path)
- img = img.convert("RGBA")
- img = img.resize((size, size), Image.Resampling.LANCZOS)
-
- # Create a rounded corners mask
- radius = size // 5 # 20% corner radius
- mask = create_rounded_corners_mask(size, radius)
-
- # Create output image with transparent background
- output = Image.new("RGBA", (size, size), (0, 0, 0, 0))
- output.paste(img, (0, 0))
-
- # Apply the mask to the alpha channel
- output.putalpha(mask)
-
- # Save the result
- output.save(output_path, "PNG")
- print(f"Created: {output_path} ({size}x{size})")
-
-
-def main():
- print("Generating rounded corner icons...")
-
- # Ensure icon directory exists
- os.makedirs(ICON_DIR, exist_ok=True)
-
- # Generate main icons
+### `claudecode-go/types.go`
+
+The `MarshalJSON` function in [`claudecode-go/types.go`](https://github.com/humanlayer/humanlayer/blob/HEAD/claudecode-go/types.go) handles a key part of this chapter's functionality:
+
+```go
+}
+
+// MarshalJSON implements custom marshaling to always output as string
+func (c ContentField) MarshalJSON() ([]byte, error) {
+ return json.Marshal(c.Value)
+}
+
+// Content can be text or tool use
+type Content struct {
+ Type string `json:"type"`
+ Text string `json:"text,omitempty"`
+ Thinking string `json:"thinking,omitempty"`
+ ID string `json:"id,omitempty"`
+ Name string `json:"name,omitempty"`
+ Input map[string]interface{} `json:"input,omitempty"`
+ ToolUseID string `json:"tool_use_id,omitempty"`
+ Content ContentField `json:"content,omitempty"`
+}
+
+// ServerToolUse tracks server-side tool usage
+type ServerToolUse struct {
+ WebSearchRequests int `json:"web_search_requests,omitempty"`
+}
+
+// CacheCreation tracks cache creation metrics
+type CacheCreation struct {
+ Ephemeral1HInputTokens int `json:"ephemeral_1h_input_tokens,omitempty"`
+ Ephemeral5MInputTokens int `json:"ephemeral_5m_input_tokens,omitempty"`
+}
+
+// Usage tracks token usage
+type Usage struct {
```
This function is important because it defines how HumanLayer Tutorial: Context Engineering and Human-Governed Coding Agents implements the patterns covered in this chapter.
-### `hack/generate_rounded_icons.py`
-
-The `main` function in [`hack/generate_rounded_icons.py`](https://github.com/humanlayer/humanlayer/blob/HEAD/hack/generate_rounded_icons.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def main():
- print("Generating rounded corner icons...")
-
- # Ensure icon directory exists
- os.makedirs(ICON_DIR, exist_ok=True)
-
- # Generate main icons
- create_rounded_icon(SOURCE_ICON, f"{ICON_DIR}/icon.png", 512)
- create_rounded_icon(SOURCE_ICON, f"{ICON_DIR}/32x32.png", 32)
- create_rounded_icon(SOURCE_ICON, f"{ICON_DIR}/128x128.png", 128)
- create_rounded_icon(SOURCE_ICON, f"{ICON_DIR}/128x128@2x.png", 256)
-
- # Generate Windows Store icons
- for size in [30, 44, 71, 89, 107, 142, 150, 284, 310]:
- create_rounded_icon(SOURCE_ICON, f"{ICON_DIR}/Square{size}x{size}Logo.png", size)
-
- create_rounded_icon(SOURCE_ICON, f"{ICON_DIR}/StoreLogo.png", 50)
-
- # Generate iconset for macOS
- print("\nCreating macOS iconset...")
- iconset_dir = "/tmp/icon.iconset"
- os.makedirs(iconset_dir, exist_ok=True)
-
- # Standard macOS icon sizes
- icon_sizes = [
- (16, "icon_16x16.png"),
- (32, "icon_16x16@2x.png"),
- (32, "icon_32x32.png"),
- (64, "icon_32x32@2x.png"),
- (128, "icon_128x128.png"),
+### `claudecode-go/types.go`
+
+The `ToStrings` function in [`claudecode-go/types.go`](https://github.com/humanlayer/humanlayer/blob/HEAD/claudecode-go/types.go) handles a key part of this chapter's functionality:
+
+```go
+}
+
+// ToStrings converts denials to string array for backward compatibility
+func (p PermissionDenials) ToStrings() []string {
+ if p.Denials == nil {
+ return nil
+ }
+ result := make([]string, len(p.Denials))
+ for i, d := range p.Denials {
+ result[i] = d.ToolName
+ }
+ return result
+}
+
+// ModelUsageDetail represents usage details for a specific model
+type ModelUsageDetail struct {
+ InputTokens int `json:"inputTokens"`
+ OutputTokens int `json:"outputTokens"`
+ CacheReadInputTokens int `json:"cacheReadInputTokens"`
+ CacheCreationInputTokens int `json:"cacheCreationInputTokens"`
+ WebSearchRequests int `json:"webSearchRequests"`
+ CostUSD float64 `json:"costUSD"`
+ ContextWindow int `json:"contextWindow,omitempty"`
+}
+
+// Result represents the final result of a Claude session
+type Result struct {
+ Type string `json:"type"`
+ Subtype string `json:"subtype"`
+ CostUSD float64 `json:"total_cost_usd"`
+ IsError bool `json:"is_error"`
+ DurationMS int `json:"duration_ms"`
```
This function is important because it defines how HumanLayer Tutorial: Context Engineering and Human-Governed Coding Agents implements the patterns covered in this chapter.
@@ -198,11 +201,11 @@ This function is important because it defines how HumanLayer Tutorial: Context E
```mermaid
flowchart TD
- A[rotate_hue]
- B[create_rounded_corners_mask]
- C[create_rounded_icon]
- D[main]
- E[create_rounded_icon]
+ A[MarshalJSON]
+ B[UnmarshalJSON]
+ C[MarshalJSON]
+ D[ToStrings]
+ E[SetError]
A --> B
B --> C
C --> D
diff --git a/tutorials/kilocode-tutorial/01-getting-started.md b/tutorials/kilocode-tutorial/01-getting-started.md
index 05f4f77a..c90f6ac1 100644
--- a/tutorials/kilocode-tutorial/01-getting-started.md
+++ b/tutorials/kilocode-tutorial/01-getting-started.md
@@ -34,170 +34,168 @@ You now have Kilo ready for first-task execution.
Next: [Chapter 2: Agent Loop and State Model](02-agent-loop-and-state-model.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `script/sync-zed.ts`
+### `script/beta.ts`
-The `main` function in [`script/sync-zed.ts`](https://github.com/Kilo-Org/kilocode/blob/HEAD/script/sync-zed.ts) handles a key part of this chapter's functionality:
+The `commentOnPR` function in [`script/beta.ts`](https://github.com/Kilo-Org/kilocode/blob/HEAD/script/beta.ts) handles a key part of this chapter's functionality:
```ts
-const EXTENSION_NAME = "opencode"
-
-async function main() {
- const version = process.argv[2]
- if (!version) throw new Error("Version argument required, ex: bun script/sync-zed.ts v1.0.52")
-
- const token = process.env.ZED_EXTENSIONS_PAT
- if (!token) throw new Error("ZED_EXTENSIONS_PAT environment variable required")
-
- const prToken = process.env.ZED_PR_PAT
- if (!prToken) throw new Error("ZED_PR_PAT environment variable required")
+}
- const cleanVersion = version.replace(/^v/, "")
- console.log(`📦 Syncing Zed extension for version ${cleanVersion}`)
+async function commentOnPR(prNumber: number, reason: string) {
+ const body = `⚠️ **Blocking Beta Release**
- const commitSha = await $`git rev-parse ${version}`.text()
- const sha = commitSha.trim()
- console.log(`🔍 Found commit SHA: ${sha}`)
+This PR cannot be merged into the beta branch due to: **${reason}**
- const extensionToml = await $`git show ${version}:packages/extensions/zed/extension.toml`.text()
- const parsed = Bun.TOML.parse(extensionToml) as { version: string }
- const extensionVersion = parsed.version
+Please resolve this issue to include this PR in the next beta release.`
- if (extensionVersion !== cleanVersion) {
- throw new Error(`Version mismatch: extension.toml has ${extensionVersion} but tag is ${cleanVersion}`)
+ try {
+ await $`gh pr comment ${prNumber} --body ${body}`
+ console.log(` Posted comment on PR #${prNumber}`)
+ } catch (err) {
+ console.log(` Failed to post comment on PR #${prNumber}: ${err}`)
}
- console.log(`✅ Version ${extensionVersion} matches tag`)
+}
- // Clone the fork to a temp directory
- const workDir = join(tmpdir(), `zed-extensions-${Date.now()}`)
- console.log(`📁 Working in ${workDir}`)
+async function conflicts() {
+ const out = await $`git diff --name-only --diff-filter=U`.text().catch(() => "")
+ return out
+ .split("\n")
+ .map((x) => x.trim())
+ .filter(Boolean)
+}
+async function cleanup() {
+ try {
+ await $`git merge --abort`
+ } catch {}
+ try {
+ await $`git checkout -- .`
+ } catch {}
```
This function is important because it defines how Kilo Code Tutorial: Agentic Engineering from IDE and CLI Surfaces implements the patterns covered in this chapter.
-### `script/changelog.ts`
+### `script/beta.ts`
-The `getLatestRelease` function in [`script/changelog.ts`](https://github.com/Kilo-Org/kilocode/blob/HEAD/script/changelog.ts) handles a key part of this chapter's functionality:
+The `conflicts` function in [`script/beta.ts`](https://github.com/Kilo-Org/kilocode/blob/HEAD/script/beta.ts) handles a key part of this chapter's functionality:
```ts
}
-export async function getLatestRelease(skip?: string) {
- const data = await fetch("https://api.github.com/repos/Kilo-Org/kilocode/releases?per_page=100").then((res) => {
- if (!res.ok) throw new Error(res.statusText)
- return res.json()
- })
-
- const releases = data as Release[]
- const target = skip?.replace(/^v/, "")
-
- for (const release of releases) {
- if (release.draft) continue
- const tag = release.tag_name.replace(/^v/, "")
- if (target && tag === target) continue
- return tag
- }
-
- throw new Error("No releases found")
+async function conflicts() {
+ const out = await $`git diff --name-only --diff-filter=U`.text().catch(() => "")
+ return out
+ .split("\n")
+ .map((x) => x.trim())
+ .filter(Boolean)
}
-type Commit = {
- hash: string
- author: string | null
- message: string
- areas: Set<string>
+async function cleanup() {
+ try {
+ await $`git merge --abort`
+ } catch {}
+ try {
+ await $`git checkout -- .`
+ } catch {}
+ try {
+ await $`git clean -fd`
+ } catch {}
}
-export async function getCommits(from: string, to: string): Promise<Commit[]> {
- const fromRef = from.startsWith("v") ? from : `v${from}`
- const toRef = to === "HEAD" ? to : to.startsWith("v") ? to : `v${to}`
+async function fix(pr: PR, files: string[]) {
+ console.log(` Trying to auto-resolve ${files.length} conflict(s) with opencode...`)
+ const prompt = [
+ `Resolve the current git merge conflicts while merging PR #${pr.number} into the beta branch.`,
+ `Only touch these files: ${files.join(", ")}.`,
+ "Keep the merge in progress, do not abort the merge, and do not create a commit.",
+ "When done, leave the working tree with no unmerged files.",
+ ].join("\n")
+ try {
```
This function is important because it defines how Kilo Code Tutorial: Agentic Engineering from IDE and CLI Surfaces implements the patterns covered in this chapter.
-### `script/changelog.ts`
+### `script/beta.ts`
-The `getCommits` function in [`script/changelog.ts`](https://github.com/Kilo-Org/kilocode/blob/HEAD/script/changelog.ts) handles a key part of this chapter's functionality:
+The `cleanup` function in [`script/beta.ts`](https://github.com/Kilo-Org/kilocode/blob/HEAD/script/beta.ts) handles a key part of this chapter's functionality:
```ts
}
-export async function getCommits(from: string, to: string): Promise<Commit[]> {
- const fromRef = from.startsWith("v") ? from : `v${from}`
- const toRef = to === "HEAD" ? to : to.startsWith("v") ? to : `v${to}`
-
- // Get commit data with GitHub usernames from the API
- const compare =
- await $`gh api "/repos/Kilo-Org/kilocode/compare/${fromRef}...${toRef}" --jq '.commits[] | {sha: .sha, login: .author.login, message: .commit.message}'`.text()
+async function cleanup() {
+ try {
+ await $`git merge --abort`
+ } catch {}
+ try {
+ await $`git checkout -- .`
+ } catch {}
+ try {
+ await $`git clean -fd`
+ } catch {}
+}
- const commitData = new Map<string, { login: string | null; message: string }>()
- for (const line of compare.split("\n").filter(Boolean)) {
- const data = JSON.parse(line) as { sha: string; login: string | null; message: string }
- commitData.set(data.sha, { login: data.login, message: data.message.split("\n")[0] ?? "" })
+async function fix(pr: PR, files: string[]) {
+ console.log(` Trying to auto-resolve ${files.length} conflict(s) with opencode...`)
+ const prompt = [
+ `Resolve the current git merge conflicts while merging PR #${pr.number} into the beta branch.`,
+ `Only touch these files: ${files.join(", ")}.`,
+ "Keep the merge in progress, do not abort the merge, and do not create a commit.",
+ "When done, leave the working tree with no unmerged files.",
+ ].join("\n")
+
+ try {
+ await $`opencode run -m opencode/gpt-5.3-codex ${prompt}`
+ } catch (err) {
+ console.log(` opencode failed: ${err}`)
+ return false
}
- // Get commits that touch the relevant packages
- const log =
- await $`git log ${fromRef}..${toRef} --oneline --format="%H" -- packages/opencode packages/sdk packages/plugin packages/desktop packages/app sdks/vscode packages/extensions github`.text()
- const hashes = log.split("\n").filter(Boolean)
-
- const commits: Commit[] = []
- for (const hash of hashes) {
- const data = commitData.get(hash)
- if (!data) continue
-
- const message = data.message
- if (message.match(/^(ignore:|test:|chore:|ci:|release:)/i)) continue
-
- const files = await $`git diff-tree --no-commit-id --name-only -r ${hash}`.text()
- const areas = new Set<string>()
-
+ const left = await conflicts()
+ if (left.length > 0) {
```
This function is important because it defines how Kilo Code Tutorial: Agentic Engineering from IDE and CLI Surfaces implements the patterns covered in this chapter.
-### `script/changelog.ts`
+### `script/beta.ts`
-The `filterRevertedCommits` function in [`script/changelog.ts`](https://github.com/Kilo-Org/kilocode/blob/HEAD/script/changelog.ts) handles a key part of this chapter's functionality:
+The `fix` function in [`script/beta.ts`](https://github.com/Kilo-Org/kilocode/blob/HEAD/script/beta.ts) handles a key part of this chapter's functionality:
```ts
- }
-
- return filterRevertedCommits(commits)
}
-function filterRevertedCommits(commits: Commit[]): Commit[] {
- const revertPattern = /^Revert "(.+)"$/
- const seen = new Map<string, Commit>()
-
- for (const commit of commits) {
- const match = commit.message.match(revertPattern)
- if (match) {
- // It's a revert - remove the original if we've seen it
- const original = match[1]!
- if (seen.has(original)) seen.delete(original)
- else seen.set(commit.message, commit) // Keep revert if original not in range
- } else {
- // Regular commit - remove if its revert exists, otherwise add
- const revertMsg = `Revert "${commit.message}"`
- if (seen.has(revertMsg)) seen.delete(revertMsg)
- else seen.set(commit.message, commit)
- }
+async function fix(pr: PR, files: string[]) {
+ console.log(` Trying to auto-resolve ${files.length} conflict(s) with opencode...`)
+ const prompt = [
+ `Resolve the current git merge conflicts while merging PR #${pr.number} into the beta branch.`,
+ `Only touch these files: ${files.join(", ")}.`,
+ "Keep the merge in progress, do not abort the merge, and do not create a commit.",
+ "When done, leave the working tree with no unmerged files.",
+ ].join("\n")
+
+ try {
+ await $`opencode run -m opencode/gpt-5.3-codex ${prompt}`
+ } catch (err) {
+ console.log(` opencode failed: ${err}`)
+ return false
+ }
+
+ const left = await conflicts()
+ if (left.length > 0) {
+ console.log(` Conflicts remain: ${left.join(", ")}`)
+ return false
}
- return [...seen.values()]
+ console.log(" Conflicts resolved with opencode")
+ return true
}
-const sections = {
- core: "Core",
- tui: "TUI",
- app: "Desktop",
- tauri: "Desktop",
+async function main() {
+ console.log("Fetching open PRs with beta label...")
+
+ const stdout = await $`gh pr list --state open --label beta --json number,title,author,labels --limit 100`.text()
```
This function is important because it defines how Kilo Code Tutorial: Agentic Engineering from IDE and CLI Surfaces implements the patterns covered in this chapter.
@@ -207,10 +205,10 @@ This function is important because it defines how Kilo Code Tutorial: Agentic En
```mermaid
flowchart TD
- A[main]
- B[getLatestRelease]
- C[getCommits]
- D[filterRevertedCommits]
+ A[commentOnPR]
+ B[conflicts]
+ C[cleanup]
+ D[fix]
A --> B
B --> C
C --> D
diff --git a/tutorials/kilocode-tutorial/02-agent-loop-and-state-model.md b/tutorials/kilocode-tutorial/02-agent-loop-and-state-model.md
index bb599752..5581ecee 100644
--- a/tutorials/kilocode-tutorial/02-agent-loop-and-state-model.md
+++ b/tutorials/kilocode-tutorial/02-agent-loop-and-state-model.md
@@ -36,170 +36,168 @@ You now understand the core loop-state mechanics that drive Kilo interaction beh
Next: [Chapter 3: Modes, Prompts, and Approval Workflow](03-modes-prompts-and-approval-workflow.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `script/changelog.ts`
+### `script/beta.ts`
-The `getSection` function in [`script/changelog.ts`](https://github.com/Kilo-Org/kilocode/blob/HEAD/script/changelog.ts) handles a key part of this chapter's functionality:
+The `main` function in [`script/beta.ts`](https://github.com/Kilo-Org/kilocode/blob/HEAD/script/beta.ts) handles a key part of this chapter's functionality:
```ts
-} as const
-
-function getSection(areas: Set<string>): string {
- // Priority order for multi-area commits
- const priority = ["core", "tui", "app", "tauri", "sdk", "plugin", "extensions/zed", "extensions/vscode", "github"]
- for (const area of priority) {
- if (areas.has(area)) return sections[area as keyof typeof sections]
+ const left = await conflicts()
+ if (left.length > 0) {
+ console.log(` Conflicts remain: ${left.join(", ")}`)
+ return false
}
- return "Core"
+
+ console.log(" Conflicts resolved with opencode")
+ return true
}
-async function summarizeCommit(opencode: Awaited<ReturnType<typeof createKilo>>, message: string): Promise<string> {
- console.log("summarizing commit:", message)
- const session = await opencode.client.session.create()
- const result = await opencode.client.session
- .prompt(
- {
- sessionID: session.data!.id,
- model: { providerID: "kilo", modelID: "anthropic/claude-sonnet-4.5" }, // kilocode_change
- tools: {
- "*": false,
- },
- parts: [
- {
- type: "text",
- text: `Summarize this commit message for a changelog entry. Return ONLY a single line summary starting with a capital letter. Be concise but specific. If the commit message is already well-written, just clean it up (capitalize, fix typos, proper grammar). Do not include any prefixes like "fix:" or "feat:".
-
-Commit: ${message}`,
- },
- ],
- },
- {
-```
+async function main() {
+ console.log("Fetching open PRs with beta label...")
-This function is important because it defines how Kilo Code Tutorial: Agentic Engineering from IDE and CLI Surfaces implements the patterns covered in this chapter.
+ const stdout = await $`gh pr list --state open --label beta --json number,title,author,labels --limit 100`.text()
+ const prs: PR[] = JSON.parse(stdout).sort((a: PR, b: PR) => a.number - b.number)
-### `script/changelog.ts`
+ console.log(`Found ${prs.length} open PRs with beta label`)
-The `summarizeCommit` function in [`script/changelog.ts`](https://github.com/Kilo-Org/kilocode/blob/HEAD/script/changelog.ts) handles a key part of this chapter's functionality:
+ if (prs.length === 0) {
+ console.log("No team PRs to merge")
+ return
+ }
-```ts
-}
+ console.log("Fetching latest main branch...")
+ await $`git fetch origin main`
-async function summarizeCommit(opencode: Awaited<ReturnType<typeof createKilo>>, message: string): Promise<string> {
- console.log("summarizing commit:", message)
- const session = await opencode.client.session.create()
- const result = await opencode.client.session
- .prompt(
- {
- sessionID: session.data!.id,
- model: { providerID: "kilo", modelID: "anthropic/claude-sonnet-4.5" }, // kilocode_change
- tools: {
- "*": false,
- },
- parts: [
- {
- type: "text",
- text: `Summarize this commit message for a changelog entry. Return ONLY a single line summary starting with a capital letter. Be concise but specific. If the commit message is already well-written, just clean it up (capitalize, fix typos, proper grammar). Do not include any prefixes like "fix:" or "feat:".
-
-Commit: ${message}`,
- },
- ],
- },
- {
- signal: AbortSignal.timeout(120_000),
- },
- )
- .then((x) => x.data?.parts?.find((y) => y.type === "text")?.text ?? message)
- return result.trim()
-}
+ console.log("Checking out main branch...")
+ await $`git checkout -B beta origin/main`
+
+ const applied: number[] = []
+ const failed: FailedPR[] = []
-export async function generateChangelog(commits: Commit[], opencode: Awaited<ReturnType<typeof createKilo>>) {
- // Summarize commits in parallel with max 10 concurrent requests
```
This function is important because it defines how Kilo Code Tutorial: Agentic Engineering from IDE and CLI Surfaces implements the patterns covered in this chapter.
-### `script/changelog.ts`
+### `script/beta.ts`
-The `generateChangelog` function in [`script/changelog.ts`](https://github.com/Kilo-Org/kilocode/blob/HEAD/script/changelog.ts) handles a key part of this chapter's functionality:
+The `PR` interface in [`script/beta.ts`](https://github.com/Kilo-Org/kilocode/blob/HEAD/script/beta.ts) handles a key part of this chapter's functionality:
```ts
+import { $ } from "bun"
+
+interface PR {
+ number: number
+ title: string
+ author: { login: string }
+ labels: Array<{ name: string }>
}
-export async function generateChangelog(commits: Commit[], opencode: Awaited<ReturnType<typeof createKilo>>) {
- // Summarize commits in parallel with max 10 concurrent requests
- const BATCH_SIZE = 10
- const summaries: string[] = []
- for (let i = 0; i < commits.length; i += BATCH_SIZE) {
- const batch = commits.slice(i, i + BATCH_SIZE)
- const results = await Promise.all(batch.map((c) => summarizeCommit(opencode, c.message)))
- summaries.push(...results)
- }
+interface FailedPR {
+ number: number
+ title: string
+ reason: string
+}
- const grouped = new Map<string, string[]>()
- for (let i = 0; i < commits.length; i++) {
- const commit = commits[i]!
- const section = getSection(commit.areas)
- const attribution = commit.author && !Script.team.includes(commit.author) ? ` (@${commit.author})` : ""
- const entry = `- ${summaries[i]}${attribution}`
+async function commentOnPR(prNumber: number, reason: string) {
+ const body = `⚠️ **Blocking Beta Release**
- if (!grouped.has(section)) grouped.set(section, [])
- grouped.get(section)!.push(entry)
- }
+This PR cannot be merged into the beta branch due to: **${reason}**
- const sectionOrder = ["Core", "TUI", "Desktop", "SDK", "Extensions"]
- const lines: string[] = []
- for (const section of sectionOrder) {
- const entries = grouped.get(section)
- if (!entries || entries.length === 0) continue
- lines.push(`## ${section}`)
- lines.push(...entries)
+Please resolve this issue to include this PR in the next beta release.`
+
+ try {
+ await $`gh pr comment ${prNumber} --body ${body}`
+ console.log(` Posted comment on PR #${prNumber}`)
+ } catch (err) {
+ console.log(` Failed to post comment on PR #${prNumber}: ${err}`)
}
+}
+async function conflicts() {
+ const out = await $`git diff --name-only --diff-filter=U`.text().catch(() => "")
```
-This function is important because it defines how Kilo Code Tutorial: Agentic Engineering from IDE and CLI Surfaces implements the patterns covered in this chapter.
+This interface is important because it defines how Kilo Code Tutorial: Agentic Engineering from IDE and CLI Surfaces implements the patterns covered in this chapter.
-### `script/changelog.ts`
+### `script/beta.ts`
-The `getContributors` function in [`script/changelog.ts`](https://github.com/Kilo-Org/kilocode/blob/HEAD/script/changelog.ts) handles a key part of this chapter's functionality:
+The `FailedPR` interface in [`script/beta.ts`](https://github.com/Kilo-Org/kilocode/blob/HEAD/script/beta.ts) handles a key part of this chapter's functionality:
```ts
}
-export async function getContributors(from: string, to: string) {
- const fromRef = from.startsWith("v") ? from : `v${from}`
- const toRef = to === "HEAD" ? to : to.startsWith("v") ? to : `v${to}`
- const compare =
- await $`gh api "/repos/Kilo-Org/kilocode/compare/${fromRef}...${toRef}" --jq '.commits[] | {login: .author.login, message: .commit.message}'`.text()
- const contributors = new Map<string, Set<string>>()
-
- for (const line of compare.split("\n").filter(Boolean)) {
- const { login, message } = JSON.parse(line) as { login: string | null; message: string }
- const title = message.split("\n")[0] ?? ""
- if (title.match(/^(ignore:|test:|chore:|ci:|release:)/i)) continue
-
- if (login && !Script.team.includes(login)) {
- if (!contributors.has(login)) contributors.set(login, new Set())
- contributors.get(login)!.add(title)
- }
+interface FailedPR {
+ number: number
+ title: string
+ reason: string
+}
+
+async function commentOnPR(prNumber: number, reason: string) {
+ const body = `⚠️ **Blocking Beta Release**
+
+This PR cannot be merged into the beta branch due to: **${reason}**
+
+Please resolve this issue to include this PR in the next beta release.`
+
+ try {
+ await $`gh pr comment ${prNumber} --body ${body}`
+ console.log(` Posted comment on PR #${prNumber}`)
+ } catch (err) {
+ console.log(` Failed to post comment on PR #${prNumber}: ${err}`)
}
+}
- return contributors
+async function conflicts() {
+ const out = await $`git diff --name-only --diff-filter=U`.text().catch(() => "")
+ return out
+ .split("\n")
+ .map((x) => x.trim())
+ .filter(Boolean)
}
-export async function buildNotes(from: string, to: string) {
- const commits = await getCommits(from, to)
+async function cleanup() {
+```
+
+This interface is important because it defines how Kilo Code Tutorial: Agentic Engineering from IDE and CLI Surfaces implements the patterns covered in this chapter.
- if (commits.length === 0) {
- return []
+### `script/stats.ts`
+
+The `sendToPostHog` function in [`script/stats.ts`](https://github.com/Kilo-Org/kilocode/blob/HEAD/script/stats.ts) handles a key part of this chapter's functionality:
+
+```ts
+#!/usr/bin/env bun
+
+async function sendToPostHog(event: string, properties: Record<string, any>) {
+ const key = process.env["POSTHOG_KEY"]
+
+ if (!key) {
+ console.warn("POSTHOG_API_KEY not set, skipping PostHog event")
+ return
}
- console.log("generating changelog since " + from)
+ const response = await fetch("https://us.i.posthog.com/i/v0/e/", {
+ method: "POST",
+ headers: {
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ distinct_id: "download",
+ api_key: key,
+ event,
+ properties: {
+ ...properties,
+ },
+ }),
+ }).catch(() => null)
+
+ if (response && !response.ok) {
+ console.warn(`PostHog API error: ${response.status}`)
+ }
+}
+interface Asset {
+ name: string
```
This function is important because it defines how Kilo Code Tutorial: Agentic Engineering from IDE and CLI Surfaces implements the patterns covered in this chapter.
@@ -209,10 +207,10 @@ This function is important because it defines how Kilo Code Tutorial: Agentic En
```mermaid
flowchart TD
- A[getSection]
- B[summarizeCommit]
- C[generateChangelog]
- D[getContributors]
+ A[main]
+ B[PR]
+ C[FailedPR]
+ D[sendToPostHog]
A --> B
B --> C
C --> D
diff --git a/tutorials/kilocode-tutorial/03-modes-prompts-and-approval-workflow.md b/tutorials/kilocode-tutorial/03-modes-prompts-and-approval-workflow.md
index 0c238f28..3469dfb2 100644
--- a/tutorials/kilocode-tutorial/03-modes-prompts-and-approval-workflow.md
+++ b/tutorials/kilocode-tutorial/03-modes-prompts-and-approval-workflow.md
@@ -30,92 +30,8 @@ You now have a mode-selection and approval strategy for safer Kilo sessions.
Next: [Chapter 4: Authentication and Provider Routing](04-authentication-and-provider-routing.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `script/changelog.ts`
-
-The `buildNotes` function in [`script/changelog.ts`](https://github.com/Kilo-Org/kilocode/blob/HEAD/script/changelog.ts) handles a key part of this chapter's functionality:
-
-```ts
-}
-
-export async function buildNotes(from: string, to: string) {
- const commits = await getCommits(from, to)
-
- if (commits.length === 0) {
- return []
- }
-
- console.log("generating changelog since " + from)
-
- const opencode = await createKilo({ port: 0 })
- const notes: string[] = []
-
- try {
- const lines = await generateChangelog(commits, opencode)
- notes.push(...lines)
- console.log("---- Generated Changelog ----")
- console.log(notes.join("\n"))
- console.log("-----------------------------")
- } catch (error) {
- if (error instanceof Error && error.name === "TimeoutError") {
- console.log("Changelog generation timed out, using raw commits")
- for (const commit of commits) {
- const attribution = commit.author && !Script.team.includes(commit.author) ? ` (@${commit.author})` : ""
- notes.push(`- ${commit.message}${attribution}`)
- }
- } else {
- throw error
- }
- } finally {
- await opencode.server.close()
-```
-
-This function is important because it defines how Kilo Code Tutorial: Agentic Engineering from IDE and CLI Surfaces implements the patterns covered in this chapter.
-
-### `script/stats.ts`
-
-The `sendToPostHog` function in [`script/stats.ts`](https://github.com/Kilo-Org/kilocode/blob/HEAD/script/stats.ts) handles a key part of this chapter's functionality:
-
-```ts
-#!/usr/bin/env bun
-
-async function sendToPostHog(event: string, properties: Record<string, any>) {
- const key = process.env["POSTHOG_KEY"]
-
- if (!key) {
- console.warn("POSTHOG_API_KEY not set, skipping PostHog event")
- return
- }
-
- const response = await fetch("https://us.i.posthog.com/i/v0/e/", {
- method: "POST",
- headers: {
- "Content-Type": "application/json",
- },
- body: JSON.stringify({
- distinct_id: "download",
- api_key: key,
- event,
- properties: {
- ...properties,
- },
- }),
- }).catch(() => null)
-
- if (response && !response.ok) {
- console.warn(`PostHog API error: ${response.status}`)
- }
-}
-
-interface Asset {
- name: string
-```
-
-This function is important because it defines how Kilo Code Tutorial: Agentic Engineering from IDE and CLI Surfaces implements the patterns covered in this chapter.
-
### `script/stats.ts`
The `fetchNpmDownloads` function in [`script/stats.ts`](https://github.com/Kilo-Org/kilocode/blob/HEAD/script/stats.ts) handles a key part of this chapter's functionality:
@@ -198,15 +114,97 @@ function calculate(releases: Release[]) {
This function is important because it defines how Kilo Code Tutorial: Agentic Engineering from IDE and CLI Surfaces implements the patterns covered in this chapter.
+### `script/stats.ts`
+
+The `calculate` function in [`script/stats.ts`](https://github.com/Kilo-Org/kilocode/blob/HEAD/script/stats.ts) handles a key part of this chapter's functionality:
+
+```ts
+}
+
+function calculate(releases: Release[]) {
+ let total = 0
+ const stats = []
+
+ for (const release of releases) {
+ let downloads = 0
+ const assets = []
+
+ for (const asset of release.assets) {
+ downloads += asset.download_count
+ assets.push({
+ name: asset.name,
+ downloads: asset.download_count,
+ })
+ }
+
+ total += downloads
+ stats.push({
+ tag: release.tag_name,
+ name: release.name,
+ downloads,
+ assets,
+ })
+ }
+
+ return { total, stats }
+}
+
+async function save(githubTotal: number, npmDownloads: number) {
+ const file = "STATS.md"
+```
+
+This function is important because it defines how Kilo Code Tutorial: Agentic Engineering from IDE and CLI Surfaces implements the patterns covered in this chapter.
+
+### `script/stats.ts`
+
+The `save` function in [`script/stats.ts`](https://github.com/Kilo-Org/kilocode/blob/HEAD/script/stats.ts) handles a key part of this chapter's functionality:
+
+```ts
+}
+
+async function save(githubTotal: number, npmDownloads: number) {
+ const file = "STATS.md"
+ const date = new Date().toISOString().split("T")[0]
+ const total = githubTotal + npmDownloads
+
+ let previousGithub = 0
+ let previousNpm = 0
+ let previousTotal = 0
+ let content = ""
+
+ try {
+ content = await Bun.file(file).text()
+ const lines = content.trim().split("\n")
+
+ for (let i = lines.length - 1; i >= 0; i--) {
+ const line = lines[i].trim()
+ if (line.startsWith("|") && !line.includes("Date") && !line.includes("---")) {
+ const match = line.match(
+ /\|\s*[\d-]+\s*\|\s*([\d,]+)\s*(?:\([^)]*\))?\s*\|\s*([\d,]+)\s*(?:\([^)]*\))?\s*\|\s*([\d,]+)\s*(?:\([^)]*\))?\s*\|/,
+ )
+ if (match) {
+ previousGithub = parseInt(match[1].replace(/,/g, ""))
+ previousNpm = parseInt(match[2].replace(/,/g, ""))
+ previousTotal = parseInt(match[3].replace(/,/g, ""))
+ break
+ }
+ }
+ }
+ } catch {
+ content =
+```
+
+This function is important because it defines how Kilo Code Tutorial: Agentic Engineering from IDE and CLI Surfaces implements the patterns covered in this chapter.
+
## How These Components Connect
```mermaid
flowchart TD
- A[buildNotes]
- B[sendToPostHog]
- C[fetchNpmDownloads]
- D[fetchReleases]
+ A[fetchNpmDownloads]
+ B[fetchReleases]
+ C[calculate]
+ D[save]
A --> B
B --> C
C --> D
diff --git a/tutorials/kilocode-tutorial/04-authentication-and-provider-routing.md b/tutorials/kilocode-tutorial/04-authentication-and-provider-routing.md
index 9743bf90..102e1e62 100644
--- a/tutorials/kilocode-tutorial/04-authentication-and-provider-routing.md
+++ b/tutorials/kilocode-tutorial/04-authentication-and-provider-routing.md
@@ -30,104 +30,56 @@ You now understand how Kilo handles auth and provider initialization end-to-end.
Next: [Chapter 5: Session, History, and Context Persistence](05-session-history-and-context-persistence.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `script/stats.ts`
-The `calculate` function in [`script/stats.ts`](https://github.com/Kilo-Org/kilocode/blob/HEAD/script/stats.ts) handles a key part of this chapter's functionality:
+The `Asset` interface in [`script/stats.ts`](https://github.com/Kilo-Org/kilocode/blob/HEAD/script/stats.ts) handles a key part of this chapter's functionality:
```ts
}
-function calculate(releases: Release[]) {
- let total = 0
- const stats = []
-
- for (const release of releases) {
- let downloads = 0
- const assets = []
-
- for (const asset of release.assets) {
- downloads += asset.download_count
- assets.push({
- name: asset.name,
- downloads: asset.download_count,
- })
- }
-
- total += downloads
- stats.push({
- tag: release.tag_name,
- name: release.name,
- downloads,
- assets,
- })
- }
-
- return { total, stats }
+interface Asset {
+ name: string
+ download_count: number
}
-async function save(githubTotal: number, npmDownloads: number) {
- const file = "STATS.md"
-```
-
-This function is important because it defines how Kilo Code Tutorial: Agentic Engineering from IDE and CLI Surfaces implements the patterns covered in this chapter.
-
-### `script/stats.ts`
-
-The `save` function in [`script/stats.ts`](https://github.com/Kilo-Org/kilocode/blob/HEAD/script/stats.ts) handles a key part of this chapter's functionality:
-
-```ts
+interface Release {
+ tag_name: string
+ name: string
+ assets: Asset[]
}
-async function save(githubTotal: number, npmDownloads: number) {
- const file = "STATS.md"
- const date = new Date().toISOString().split("T")[0]
- const total = githubTotal + npmDownloads
-
- let previousGithub = 0
- let previousNpm = 0
- let previousTotal = 0
- let content = ""
+interface NpmDownloadsRange {
+ start: string
+ end: string
+ package: string
+ downloads: Array<{
+ downloads: number
+ day: string
+ }>
+}
+async function fetchNpmDownloads(packageName: string): Promise<number> {
try {
- content = await Bun.file(file).text()
- const lines = content.trim().split("\n")
-
- for (let i = lines.length - 1; i >= 0; i--) {
- const line = lines[i].trim()
- if (line.startsWith("|") && !line.includes("Date") && !line.includes("---")) {
- const match = line.match(
- /\|\s*[\d-]+\s*\|\s*([\d,]+)\s*(?:\([^)]*\))?\s*\|\s*([\d,]+)\s*(?:\([^)]*\))?\s*\|\s*([\d,]+)\s*(?:\([^)]*\))?\s*\|/,
- )
- if (match) {
- previousGithub = parseInt(match[1].replace(/,/g, ""))
- previousNpm = parseInt(match[2].replace(/,/g, ""))
- previousTotal = parseInt(match[3].replace(/,/g, ""))
- break
- }
- }
- }
- } catch {
- content =
+ // Use a range from 2020 to current year + 5 years to ensure it works forever
+ const currentYear = new Date().getFullYear()
+ const endYear = currentYear + 5
+ const response = await fetch(`https://api.npmjs.org/downloads/range/2020-01-01:${endYear}-12-31/${packageName}`)
+ if (!response.ok) {
+ console.warn(`Failed to fetch npm downloads for ${packageName}: ${response.status}`)
+ return 0
```
-This function is important because it defines how Kilo Code Tutorial: Agentic Engineering from IDE and CLI Surfaces implements the patterns covered in this chapter.
+This interface is important because it defines how Kilo Code Tutorial: Agentic Engineering from IDE and CLI Surfaces implements the patterns covered in this chapter.
### `script/stats.ts`
-The `Asset` interface in [`script/stats.ts`](https://github.com/Kilo-Org/kilocode/blob/HEAD/script/stats.ts) handles a key part of this chapter's functionality:
+The `Release` interface in [`script/stats.ts`](https://github.com/Kilo-Org/kilocode/blob/HEAD/script/stats.ts) handles a key part of this chapter's functionality:
```ts
}
-interface Asset {
- name: string
- download_count: number
-}
-
interface Release {
tag_name: string
name: string
@@ -153,23 +105,22 @@ async function fetchNpmDownloads(packageName: string): Promise<number> {
if (!response.ok) {
console.warn(`Failed to fetch npm downloads for ${packageName}: ${response.status}`)
return 0
+ }
+ const data: NpmDownloadsRange = await response.json()
+ return data.downloads.reduce((total, day) => total + day.downloads, 0)
+ } catch (error) {
+ console.warn(`Error fetching npm downloads for ${packageName}:`, error)
```
This interface is important because it defines how Kilo Code Tutorial: Agentic Engineering from IDE and CLI Surfaces implements the patterns covered in this chapter.
### `script/stats.ts`
-The `Release` interface in [`script/stats.ts`](https://github.com/Kilo-Org/kilocode/blob/HEAD/script/stats.ts) handles a key part of this chapter's functionality:
+The `NpmDownloadsRange` interface in [`script/stats.ts`](https://github.com/Kilo-Org/kilocode/blob/HEAD/script/stats.ts) handles a key part of this chapter's functionality:
```ts
}
-interface Release {
- tag_name: string
- name: string
- assets: Asset[]
-}
-
interface NpmDownloadsRange {
start: string
end: string
@@ -194,19 +145,66 @@ async function fetchNpmDownloads(packageName: string): Promise<number> {
return data.downloads.reduce((total, day) => total + day.downloads, 0)
} catch (error) {
console.warn(`Error fetching npm downloads for ${packageName}:`, error)
+ return 0
+ }
+}
+
+async function fetchReleases(): Promise<Release[]> {
+ const releases: Release[] = []
```
This interface is important because it defines how Kilo Code Tutorial: Agentic Engineering from IDE and CLI Surfaces implements the patterns covered in this chapter.
+### `script/changelog.ts`
+
+The `getLatestRelease` function in [`script/changelog.ts`](https://github.com/Kilo-Org/kilocode/blob/HEAD/script/changelog.ts) handles a key part of this chapter's functionality:
+
+```ts
+}
+
+export async function getLatestRelease(skip?: string) {
+ const data = await fetch("https://api.github.com/repos/Kilo-Org/kilocode/releases?per_page=100").then((res) => {
+ if (!res.ok) throw new Error(res.statusText)
+ return res.json()
+ })
+
+ const releases = data as Release[]
+ const target = skip?.replace(/^v/, "")
+
+ for (const release of releases) {
+ if (release.draft) continue
+ const tag = release.tag_name.replace(/^v/, "")
+ if (target && tag === target) continue
+ return tag
+ }
+
+ throw new Error("No releases found")
+}
+
+type Commit = {
+ hash: string
+ author: string | null
+ message: string
+ areas: Set<string>
+}
+
+export async function getCommits(from: string, to: string): Promise<Commit[]> {
+ const fromRef = from.startsWith("v") ? from : `v${from}`
+ const toRef = to === "HEAD" ? to : to.startsWith("v") ? to : `v${to}`
+
+```
+
+This function is important because it defines how Kilo Code Tutorial: Agentic Engineering from IDE and CLI Surfaces implements the patterns covered in this chapter.
+
## How These Components Connect
```mermaid
flowchart TD
- A[calculate]
- B[save]
- C[Asset]
- D[Release]
+ A[Asset]
+ B[Release]
+ C[NpmDownloadsRange]
+ D[getLatestRelease]
A --> B
B --> C
C --> D
diff --git a/tutorials/kilocode-tutorial/05-session-history-and-context-persistence.md b/tutorials/kilocode-tutorial/05-session-history-and-context-persistence.md
index 55c22bbd..a22a8b56 100644
--- a/tutorials/kilocode-tutorial/05-session-history-and-context-persistence.md
+++ b/tutorials/kilocode-tutorial/05-session-history-and-context-persistence.md
@@ -32,170 +32,168 @@ You now have a clear model for how Kilo preserves user context over time.
Next: [Chapter 6: Extensions, MCP, and Custom Modes](06-extensions-mcp-and-custom-modes.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `script/stats.ts`
+### `script/changelog.ts`
-The `NpmDownloadsRange` interface in [`script/stats.ts`](https://github.com/Kilo-Org/kilocode/blob/HEAD/script/stats.ts) handles a key part of this chapter's functionality:
+The `getCommits` function in [`script/changelog.ts`](https://github.com/Kilo-Org/kilocode/blob/HEAD/script/changelog.ts) handles a key part of this chapter's functionality:
```ts
}
-interface NpmDownloadsRange {
- start: string
- end: string
- package: string
- downloads: Array<{
- downloads: number
- day: string
- }>
-}
+export async function getCommits(from: string, to: string): Promise<Commit[]> {
+ const fromRef = from.startsWith("v") ? from : `v${from}`
+ const toRef = to === "HEAD" ? to : to.startsWith("v") ? to : `v${to}`
-async function fetchNpmDownloads(packageName: string): Promise<number> {
- try {
- // Use a range from 2020 to current year + 5 years to ensure it works forever
- const currentYear = new Date().getFullYear()
- const endYear = currentYear + 5
- const response = await fetch(`https://api.npmjs.org/downloads/range/2020-01-01:${endYear}-12-31/${packageName}`)
- if (!response.ok) {
- console.warn(`Failed to fetch npm downloads for ${packageName}: ${response.status}`)
- return 0
- }
- const data: NpmDownloadsRange = await response.json()
- return data.downloads.reduce((total, day) => total + day.downloads, 0)
- } catch (error) {
- console.warn(`Error fetching npm downloads for ${packageName}:`, error)
- return 0
+ // Get commit data with GitHub usernames from the API
+ const compare =
+ await $`gh api "/repos/Kilo-Org/kilocode/compare/${fromRef}...${toRef}" --jq '.commits[] | {sha: .sha, login: .author.login, message: .commit.message}'`.text()
+
+ const commitData = new Map<string, { login: string | null; message: string }>()
+ for (const line of compare.split("\n").filter(Boolean)) {
+ const data = JSON.parse(line) as { sha: string; login: string | null; message: string }
+ commitData.set(data.sha, { login: data.login, message: data.message.split("\n")[0] ?? "" })
}
-}
-async function fetchReleases(): Promise<Release[]> {
- const releases: Release[] = []
-```
+ // Get commits that touch the relevant packages
+ const log =
+ await $`git log ${fromRef}..${toRef} --oneline --format="%H" -- packages/opencode packages/sdk packages/plugin packages/desktop packages/app sdks/vscode packages/extensions github`.text()
+ const hashes = log.split("\n").filter(Boolean)
-This interface is important because it defines how Kilo Code Tutorial: Agentic Engineering from IDE and CLI Surfaces implements the patterns covered in this chapter.
+ const commits: Commit[] = []
+ for (const hash of hashes) {
+ const data = commitData.get(hash)
+ if (!data) continue
-### `script/beta.ts`
+ const message = data.message
+ if (message.match(/^(ignore:|test:|chore:|ci:|release:)/i)) continue
-The `commentOnPR` function in [`script/beta.ts`](https://github.com/Kilo-Org/kilocode/blob/HEAD/script/beta.ts) handles a key part of this chapter's functionality:
+ const files = await $`git diff-tree --no-commit-id --name-only -r ${hash}`.text()
+ const areas = new Set<string>()
-```ts
-}
+```
-async function commentOnPR(prNumber: number, reason: string) {
- const body = `⚠️ **Blocking Beta Release**
+This function is important because it defines how Kilo Code Tutorial: Agentic Engineering from IDE and CLI Surfaces implements the patterns covered in this chapter.
-This PR cannot be merged into the beta branch due to: **${reason}**
+### `script/changelog.ts`
-Please resolve this issue to include this PR in the next beta release.`
+The `filterRevertedCommits` function in [`script/changelog.ts`](https://github.com/Kilo-Org/kilocode/blob/HEAD/script/changelog.ts) handles a key part of this chapter's functionality:
- try {
- await $`gh pr comment ${prNumber} --body ${body}`
- console.log(` Posted comment on PR #${prNumber}`)
- } catch (err) {
- console.log(` Failed to post comment on PR #${prNumber}: ${err}`)
+```ts
}
+
+ return filterRevertedCommits(commits)
}
-async function conflicts() {
- const out = await $`git diff --name-only --diff-filter=U`.text().catch(() => "")
- return out
- .split("\n")
- .map((x) => x.trim())
- .filter(Boolean)
+function filterRevertedCommits(commits: Commit[]): Commit[] {
+ const revertPattern = /^Revert "(.+)"$/
+ const seen = new Map<string, Commit>()
+
+ for (const commit of commits) {
+ const match = commit.message.match(revertPattern)
+ if (match) {
+ // It's a revert - remove the original if we've seen it
+ const original = match[1]!
+ if (seen.has(original)) seen.delete(original)
+ else seen.set(commit.message, commit) // Keep revert if original not in range
+ } else {
+ // Regular commit - remove if its revert exists, otherwise add
+ const revertMsg = `Revert "${commit.message}"`
+ if (seen.has(revertMsg)) seen.delete(revertMsg)
+ else seen.set(commit.message, commit)
+ }
+ }
+
+ return [...seen.values()]
}
-async function cleanup() {
- try {
- await $`git merge --abort`
- } catch {}
- try {
- await $`git checkout -- .`
- } catch {}
+const sections = {
+ core: "Core",
+ tui: "TUI",
+ app: "Desktop",
+ tauri: "Desktop",
```
This function is important because it defines how Kilo Code Tutorial: Agentic Engineering from IDE and CLI Surfaces implements the patterns covered in this chapter.
-### `script/beta.ts`
+### `script/changelog.ts`
-The `conflicts` function in [`script/beta.ts`](https://github.com/Kilo-Org/kilocode/blob/HEAD/script/beta.ts) handles a key part of this chapter's functionality:
+The `getSection` function in [`script/changelog.ts`](https://github.com/Kilo-Org/kilocode/blob/HEAD/script/changelog.ts) handles a key part of this chapter's functionality:
```ts
-}
+} as const
-async function conflicts() {
- const out = await $`git diff --name-only --diff-filter=U`.text().catch(() => "")
- return out
- .split("\n")
- .map((x) => x.trim())
- .filter(Boolean)
-}
-
-async function cleanup() {
- try {
- await $`git merge --abort`
- } catch {}
- try {
- await $`git checkout -- .`
- } catch {}
- try {
- await $`git clean -fd`
- } catch {}
+function getSection(areas: Set<string>): string {
+ // Priority order for multi-area commits
+ const priority = ["core", "tui", "app", "tauri", "sdk", "plugin", "extensions/zed", "extensions/vscode", "github"]
+ for (const area of priority) {
+ if (areas.has(area)) return sections[area as keyof typeof sections]
+ }
+ return "Core"
}
-async function fix(pr: PR, files: string[]) {
- console.log(` Trying to auto-resolve ${files.length} conflict(s) with opencode...`)
- const prompt = [
- `Resolve the current git merge conflicts while merging PR #${pr.number} into the beta branch.`,
- `Only touch these files: ${files.join(", ")}.`,
- "Keep the merge in progress, do not abort the merge, and do not create a commit.",
- "When done, leave the working tree with no unmerged files.",
- ].join("\n")
-
- try {
+async function summarizeCommit(opencode: Awaited<ReturnType<typeof createKilo>>, message: string): Promise<string> {
+ console.log("summarizing commit:", message)
+ const session = await opencode.client.session.create()
+ const result = await opencode.client.session
+ .prompt(
+ {
+ sessionID: session.data!.id,
+ model: { providerID: "kilo", modelID: "anthropic/claude-sonnet-4.5" }, // kilocode_change
+ tools: {
+ "*": false,
+ },
+ parts: [
+ {
+ type: "text",
+ text: `Summarize this commit message for a changelog entry. Return ONLY a single line summary starting with a capital letter. Be concise but specific. If the commit message is already well-written, just clean it up (capitalize, fix typos, proper grammar). Do not include any prefixes like "fix:" or "feat:".
+
+Commit: ${message}`,
+ },
+ ],
+ },
+ {
```
This function is important because it defines how Kilo Code Tutorial: Agentic Engineering from IDE and CLI Surfaces implements the patterns covered in this chapter.
-### `script/beta.ts`
+### `script/changelog.ts`
-The `cleanup` function in [`script/beta.ts`](https://github.com/Kilo-Org/kilocode/blob/HEAD/script/beta.ts) handles a key part of this chapter's functionality:
+The `summarizeCommit` function in [`script/changelog.ts`](https://github.com/Kilo-Org/kilocode/blob/HEAD/script/changelog.ts) handles a key part of this chapter's functionality:
```ts
}
-async function cleanup() {
- try {
- await $`git merge --abort`
- } catch {}
- try {
- await $`git checkout -- .`
- } catch {}
- try {
- await $`git clean -fd`
- } catch {}
+async function summarizeCommit(opencode: Awaited<ReturnType<typeof createKilo>>, message: string): Promise<string> {
+ console.log("summarizing commit:", message)
+ const session = await opencode.client.session.create()
+ const result = await opencode.client.session
+ .prompt(
+ {
+ sessionID: session.data!.id,
+ model: { providerID: "kilo", modelID: "anthropic/claude-sonnet-4.5" }, // kilocode_change
+ tools: {
+ "*": false,
+ },
+ parts: [
+ {
+ type: "text",
+ text: `Summarize this commit message for a changelog entry. Return ONLY a single line summary starting with a capital letter. Be concise but specific. If the commit message is already well-written, just clean it up (capitalize, fix typos, proper grammar). Do not include any prefixes like "fix:" or "feat:".
+
+Commit: ${message}`,
+ },
+ ],
+ },
+ {
+ signal: AbortSignal.timeout(120_000),
+ },
+ )
+ .then((x) => x.data?.parts?.find((y) => y.type === "text")?.text ?? message)
+ return result.trim()
}
-async function fix(pr: PR, files: string[]) {
- console.log(` Trying to auto-resolve ${files.length} conflict(s) with opencode...`)
- const prompt = [
- `Resolve the current git merge conflicts while merging PR #${pr.number} into the beta branch.`,
- `Only touch these files: ${files.join(", ")}.`,
- "Keep the merge in progress, do not abort the merge, and do not create a commit.",
- "When done, leave the working tree with no unmerged files.",
- ].join("\n")
-
- try {
- await $`opencode run -m opencode/gpt-5.3-codex ${prompt}`
- } catch (err) {
- console.log(` opencode failed: ${err}`)
- return false
- }
-
- const left = await conflicts()
- if (left.length > 0) {
+export async function generateChangelog(commits: Commit[], opencode: Awaited<ReturnType<typeof createKilo>>) {
+ // Summarize commits in parallel with max 10 concurrent requests
```
This function is important because it defines how Kilo Code Tutorial: Agentic Engineering from IDE and CLI Surfaces implements the patterns covered in this chapter.
@@ -205,10 +203,10 @@ This function is important because it defines how Kilo Code Tutorial: Agentic En
```mermaid
flowchart TD
- A[NpmDownloadsRange]
- B[commentOnPR]
- C[conflicts]
- D[cleanup]
+ A[getCommits]
+ B[filterRevertedCommits]
+ C[getSection]
+ D[summarizeCommit]
A --> B
B --> C
C --> D
diff --git a/tutorials/kilocode-tutorial/06-extensions-mcp-and-custom-modes.md b/tutorials/kilocode-tutorial/06-extensions-mcp-and-custom-modes.md
index f28c6172..60beb79c 100644
--- a/tutorials/kilocode-tutorial/06-extensions-mcp-and-custom-modes.md
+++ b/tutorials/kilocode-tutorial/06-extensions-mcp-and-custom-modes.md
@@ -30,183 +30,181 @@ You now understand where Kilo can be extended for project-specific or team-speci
Next: [Chapter 7: CLI/TUI Architecture for Contributors](07-cli-tui-architecture-for-contributors.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `script/beta.ts`
+### `script/changelog.ts`
-The `fix` function in [`script/beta.ts`](https://github.com/Kilo-Org/kilocode/blob/HEAD/script/beta.ts) handles a key part of this chapter's functionality:
+The `generateChangelog` function in [`script/changelog.ts`](https://github.com/Kilo-Org/kilocode/blob/HEAD/script/changelog.ts) handles a key part of this chapter's functionality:
```ts
}
-async function fix(pr: PR, files: string[]) {
- console.log(` Trying to auto-resolve ${files.length} conflict(s) with opencode...`)
- const prompt = [
- `Resolve the current git merge conflicts while merging PR #${pr.number} into the beta branch.`,
- `Only touch these files: ${files.join(", ")}.`,
- "Keep the merge in progress, do not abort the merge, and do not create a commit.",
- "When done, leave the working tree with no unmerged files.",
- ].join("\n")
-
- try {
- await $`opencode run -m opencode/gpt-5.3-codex ${prompt}`
- } catch (err) {
- console.log(` opencode failed: ${err}`)
- return false
+export async function generateChangelog(commits: Commit[], opencode: Awaited<ReturnType<typeof createKilo>>) {
+ // Summarize commits in parallel with max 10 concurrent requests
+ const BATCH_SIZE = 10
+ const summaries: string[] = []
+ for (let i = 0; i < commits.length; i += BATCH_SIZE) {
+ const batch = commits.slice(i, i + BATCH_SIZE)
+ const results = await Promise.all(batch.map((c) => summarizeCommit(opencode, c.message)))
+ summaries.push(...results)
}
- const left = await conflicts()
- if (left.length > 0) {
- console.log(` Conflicts remain: ${left.join(", ")}`)
- return false
- }
+ const grouped = new Map<string, string[]>()
+ for (let i = 0; i < commits.length; i++) {
+ const commit = commits[i]!
+ const section = getSection(commit.areas)
+ const attribution = commit.author && !Script.team.includes(commit.author) ? ` (@${commit.author})` : ""
+ const entry = `- ${summaries[i]}${attribution}`
- console.log(" Conflicts resolved with opencode")
- return true
-}
+ if (!grouped.has(section)) grouped.set(section, [])
+ grouped.get(section)!.push(entry)
+ }
-async function main() {
- console.log("Fetching open PRs with beta label...")
+ const sectionOrder = ["Core", "TUI", "Desktop", "SDK", "Extensions"]
+ const lines: string[] = []
+ for (const section of sectionOrder) {
+ const entries = grouped.get(section)
+ if (!entries || entries.length === 0) continue
+ lines.push(`## ${section}`)
+ lines.push(...entries)
+ }
- const stdout = await $`gh pr list --state open --label beta --json number,title,author,labels --limit 100`.text()
```
This function is important because it defines how Kilo Code Tutorial: Agentic Engineering from IDE and CLI Surfaces implements the patterns covered in this chapter.
-### `script/beta.ts`
+### `script/changelog.ts`
-The `main` function in [`script/beta.ts`](https://github.com/Kilo-Org/kilocode/blob/HEAD/script/beta.ts) handles a key part of this chapter's functionality:
+The `getContributors` function in [`script/changelog.ts`](https://github.com/Kilo-Org/kilocode/blob/HEAD/script/changelog.ts) handles a key part of this chapter's functionality:
```ts
- const left = await conflicts()
- if (left.length > 0) {
- console.log(` Conflicts remain: ${left.join(", ")}`)
- return false
- }
-
- console.log(" Conflicts resolved with opencode")
- return true
}
-async function main() {
- console.log("Fetching open PRs with beta label...")
+export async function getContributors(from: string, to: string) {
+ const fromRef = from.startsWith("v") ? from : `v${from}`
+ const toRef = to === "HEAD" ? to : to.startsWith("v") ? to : `v${to}`
+ const compare =
+ await $`gh api "/repos/Kilo-Org/kilocode/compare/${fromRef}...${toRef}" --jq '.commits[] | {login: .author.login, message: .commit.message}'`.text()
+ const contributors = new Map<string, Set<string>>()
+
+ for (const line of compare.split("\n").filter(Boolean)) {
+ const { login, message } = JSON.parse(line) as { login: string | null; message: string }
+ const title = message.split("\n")[0] ?? ""
+ if (title.match(/^(ignore:|test:|chore:|ci:|release:)/i)) continue
+
+ if (login && !Script.team.includes(login)) {
+ if (!contributors.has(login)) contributors.set(login, new Set())
+ contributors.get(login)!.add(title)
+ }
+ }
- const stdout = await $`gh pr list --state open --label beta --json number,title,author,labels --limit 100`.text()
- const prs: PR[] = JSON.parse(stdout).sort((a: PR, b: PR) => a.number - b.number)
+ return contributors
+}
- console.log(`Found ${prs.length} open PRs with beta label`)
+export async function buildNotes(from: string, to: string) {
+ const commits = await getCommits(from, to)
- if (prs.length === 0) {
- console.log("No team PRs to merge")
- return
+ if (commits.length === 0) {
+ return []
}
- console.log("Fetching latest main branch...")
- await $`git fetch origin main`
-
- console.log("Checking out main branch...")
- await $`git checkout -B beta origin/main`
-
- const applied: number[] = []
- const failed: FailedPR[] = []
+ console.log("generating changelog since " + from)
```
This function is important because it defines how Kilo Code Tutorial: Agentic Engineering from IDE and CLI Surfaces implements the patterns covered in this chapter.
-### `script/beta.ts`
+### `script/changelog.ts`
-The `PR` interface in [`script/beta.ts`](https://github.com/Kilo-Org/kilocode/blob/HEAD/script/beta.ts) handles a key part of this chapter's functionality:
+The `buildNotes` function in [`script/changelog.ts`](https://github.com/Kilo-Org/kilocode/blob/HEAD/script/changelog.ts) handles a key part of this chapter's functionality:
```ts
-import { $ } from "bun"
-
-interface PR {
- number: number
- title: string
- author: { login: string }
- labels: Array<{ name: string }>
}
-interface FailedPR {
- number: number
- title: string
- reason: string
-}
+export async function buildNotes(from: string, to: string) {
+ const commits = await getCommits(from, to)
-async function commentOnPR(prNumber: number, reason: string) {
- const body = `⚠️ **Blocking Beta Release**
+ if (commits.length === 0) {
+ return []
+ }
-This PR cannot be merged into the beta branch due to: **${reason}**
+ console.log("generating changelog since " + from)
-Please resolve this issue to include this PR in the next beta release.`
+ const opencode = await createKilo({ port: 0 })
+ const notes: string[] = []
try {
- await $`gh pr comment ${prNumber} --body ${body}`
- console.log(` Posted comment on PR #${prNumber}`)
- } catch (err) {
- console.log(` Failed to post comment on PR #${prNumber}: ${err}`)
- }
-}
-
-async function conflicts() {
- const out = await $`git diff --name-only --diff-filter=U`.text().catch(() => "")
+ const lines = await generateChangelog(commits, opencode)
+ notes.push(...lines)
+ console.log("---- Generated Changelog ----")
+ console.log(notes.join("\n"))
+ console.log("-----------------------------")
+ } catch (error) {
+ if (error instanceof Error && error.name === "TimeoutError") {
+ console.log("Changelog generation timed out, using raw commits")
+ for (const commit of commits) {
+ const attribution = commit.author && !Script.team.includes(commit.author) ? ` (@${commit.author})` : ""
+ notes.push(`- ${commit.message}${attribution}`)
+ }
+ } else {
+ throw error
+ }
+ } finally {
+ await opencode.server.close()
```
-This interface is important because it defines how Kilo Code Tutorial: Agentic Engineering from IDE and CLI Surfaces implements the patterns covered in this chapter.
+This function is important because it defines how Kilo Code Tutorial: Agentic Engineering from IDE and CLI Surfaces implements the patterns covered in this chapter.
-### `script/beta.ts`
+### `script/extract-source-links.ts`
-The `FailedPR` interface in [`script/beta.ts`](https://github.com/Kilo-Org/kilocode/blob/HEAD/script/beta.ts) handles a key part of this chapter's functionality:
+The `shouldExclude` function in [`script/extract-source-links.ts`](https://github.com/Kilo-Org/kilocode/blob/HEAD/script/extract-source-links.ts) handles a key part of this chapter's functionality:
```ts
-}
+const SKIP_FILES = ["models-snapshot.ts"]
-interface FailedPR {
- number: number
- title: string
- reason: string
+function shouldExclude(url: string): boolean {
+ return EXCLUDE_PATTERNS.some((re) => re.test(url))
}
-async function commentOnPR(prNumber: number, reason: string) {
- const body = `⚠️ **Blocking Beta Release**
-
-This PR cannot be merged into the beta branch due to: **${reason}**
-
-Please resolve this issue to include this PR in the next beta release.`
-
- try {
- await $`gh pr comment ${prNumber} --body ${body}`
- console.log(` Posted comment on PR #${prNumber}`)
- } catch (err) {
- console.log(` Failed to post comment on PR #${prNumber}: ${err}`)
- }
+function shouldSkipFile(filepath: string): boolean {
+ const rel = path.relative(ROOT, filepath)
+ const parts = rel.split(path.sep)
+ if (parts.some((p) => SKIP_DIRS.includes(p))) return true
+ if (SKIP_PATH_SEGMENTS.some((seg) => rel.includes(seg))) return true
+ if (/\.test\.[jt]sx?$/.test(filepath)) return true
+ if (/\.spec\.[jt]sx?$/.test(filepath)) return true
+ if (/\.stories\.[jt]sx?$/.test(filepath)) return true
+ if (/\/i18n\//.test(filepath) && !filepath.endsWith("en.ts")) return true
+ const basename = path.basename(filepath)
+ if (SKIP_FILES.includes(basename)) return true
+ return false
}
-async function conflicts() {
- const out = await $`git diff --name-only --diff-filter=U`.text().catch(() => "")
- return out
- .split("\n")
- .map((x) => x.trim())
- .filter(Boolean)
+function clean(url: string): string {
+ return url.replace(/[.),:;]+$/, "").replace(/<\/?\w+>$/, "")
}
-async function cleanup() {
+async function extract(): Promise<Map<string, Set<string>>> {
+ const links = new Map<string, Set<string>>()
+
+ for (const dir of DIRS) {
+ for (const ext of EXTENSIONS) {
+ const glob = new Glob(`**/*.${ext}`)
+ for await (const entry of glob.scan({ cwd: dir, absolute: true })) {
+ if (shouldSkipFile(entry)) continue
```
-This interface is important because it defines how Kilo Code Tutorial: Agentic Engineering from IDE and CLI Surfaces implements the patterns covered in this chapter.
+This function is important because it defines how Kilo Code Tutorial: Agentic Engineering from IDE and CLI Surfaces implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[fix]
- B[main]
- C[PR]
- D[FailedPR]
+ A[generateChangelog]
+ B[getContributors]
+ C[buildNotes]
+ D[shouldExclude]
A --> B
B --> C
C --> D
diff --git a/tutorials/kilocode-tutorial/07-cli-tui-architecture-for-contributors.md b/tutorials/kilocode-tutorial/07-cli-tui-architecture-for-contributors.md
index 17cf1751..d09b5d1f 100644
--- a/tutorials/kilocode-tutorial/07-cli-tui-architecture-for-contributors.md
+++ b/tutorials/kilocode-tutorial/07-cli-tui-architecture-for-contributors.md
@@ -33,170 +33,168 @@ You now have a contributor-level map for Kilo CLI internals.
Next: [Chapter 8: Production Operations and Governance](08-production-operations-and-governance.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `script/duplicate-pr.ts`
+### `script/extract-source-links.ts`
-The `main` function in [`script/duplicate-pr.ts`](https://github.com/Kilo-Org/kilocode/blob/HEAD/script/duplicate-pr.ts) handles a key part of this chapter's functionality:
+The `shouldSkipFile` function in [`script/extract-source-links.ts`](https://github.com/Kilo-Org/kilocode/blob/HEAD/script/extract-source-links.ts) handles a key part of this chapter's functionality:
```ts
-import { parseArgs } from "util"
-
-async function main() {
- const { values, positionals } = parseArgs({
- args: Bun.argv.slice(2),
- options: {
- file: { type: "string", short: "f" },
- help: { type: "boolean", short: "h", default: false },
- },
- allowPositionals: true,
- })
-
- if (values.help) {
- console.log(`
-Usage: bun script/duplicate-pr.ts [options] <message>
-
-Options:
- -f, --file <path> File to attach to the prompt
- -h, --help Show this help message
-
-Examples:
- bun script/duplicate-pr.ts -f pr_info.txt "Check the attached file for PR details"
-`)
- process.exit(0)
- }
+}
- const message = positionals.join(" ")
- if (!message) {
- console.error("Error: message is required")
- process.exit(1)
- }
+function shouldSkipFile(filepath: string): boolean {
+ const rel = path.relative(ROOT, filepath)
+ const parts = rel.split(path.sep)
+ if (parts.some((p) => SKIP_DIRS.includes(p))) return true
+ if (SKIP_PATH_SEGMENTS.some((seg) => rel.includes(seg))) return true
+ if (/\.test\.[jt]sx?$/.test(filepath)) return true
+ if (/\.spec\.[jt]sx?$/.test(filepath)) return true
+ if (/\.stories\.[jt]sx?$/.test(filepath)) return true
+ if (/\/i18n\//.test(filepath) && !filepath.endsWith("en.ts")) return true
+ const basename = path.basename(filepath)
+ if (SKIP_FILES.includes(basename)) return true
+ return false
+}
+function clean(url: string): string {
+ return url.replace(/[.),:;]+$/, "").replace(/<\/?\w+>$/, "")
+}
+
+async function extract(): Promise<Map<string, Set<string>>> {
+ const links = new Map<string, Set<string>>()
+
+ for (const dir of DIRS) {
+ for (const ext of EXTENSIONS) {
+ const glob = new Glob(`**/*.${ext}`)
+ for await (const entry of glob.scan({ cwd: dir, absolute: true })) {
+ if (shouldSkipFile(entry)) continue
+ const content = await Bun.file(entry).text()
+ for (const line of content.split("\n")) {
+ for (const match of line.matchAll(URL_RE)) {
+ const url = clean(match[0])
```
This function is important because it defines how Kilo Code Tutorial: Agentic Engineering from IDE and CLI Surfaces implements the patterns covered in this chapter.
-### `script/upstream/merge.ts`
+### `script/extract-source-links.ts`
-The `parseArgs` function in [`script/upstream/merge.ts`](https://github.com/Kilo-Org/kilocode/blob/HEAD/script/upstream/merge.ts) handles a key part of this chapter's functionality:
+The `clean` function in [`script/extract-source-links.ts`](https://github.com/Kilo-Org/kilocode/blob/HEAD/script/extract-source-links.ts) handles a key part of this chapter's functionality:
```ts
}
-function parseArgs(): MergeOptions {
- const args = process.argv.slice(2)
-
- const options: MergeOptions = {
- dryRun: args.includes("--dry-run"),
- push: !args.includes("--no-push"),
- reportOnly: args.includes("--report-only"),
- verbose: args.includes("--verbose"),
- }
-
- const versionIdx = args.indexOf("--version")
- if (versionIdx !== -1 && args[versionIdx + 1]) {
- options.version = args[versionIdx + 1]
- }
-
- const commitIdx = args.indexOf("--commit")
- if (commitIdx !== -1 && args[commitIdx + 1]) {
- options.commit = args[commitIdx + 1]
- }
+function clean(url: string): string {
+ return url.replace(/[.),:;]+$/, "").replace(/<\/?\w+>$/, "")
+}
- const authorIdx = args.indexOf("--author")
- if (authorIdx !== -1 && args[authorIdx + 1]) {
- options.author = args[authorIdx + 1]
+async function extract(): Promise<Map<string, Set<string>>> {
+ const links = new Map<string, Set<string>>()
+
+ for (const dir of DIRS) {
+ for (const ext of EXTENSIONS) {
+ const glob = new Glob(`**/*.${ext}`)
+ for await (const entry of glob.scan({ cwd: dir, absolute: true })) {
+ if (shouldSkipFile(entry)) continue
+ const content = await Bun.file(entry).text()
+ for (const line of content.split("\n")) {
+ for (const match of line.matchAll(URL_RE)) {
+ const url = clean(match[0])
+ if (shouldExclude(url)) continue
+ if (!links.has(url)) links.set(url, new Set())
+ links.get(url)!.add(path.relative(ROOT, entry))
+ }
+ }
+ }
+ }
}
- const baseBranchIdx = args.indexOf("--base-branch")
- if (baseBranchIdx !== -1 && args[baseBranchIdx + 1]) {
- options.baseBranch = args[baseBranchIdx + 1]
- }
+ return links
+}
+function render(sorted: [string, Set<string>][]): string {
+ const parts = [
```
This function is important because it defines how Kilo Code Tutorial: Agentic Engineering from IDE and CLI Surfaces implements the patterns covered in this chapter.
-### `script/upstream/merge.ts`
+### `script/extract-source-links.ts`
-The `getAuthor` function in [`script/upstream/merge.ts`](https://github.com/Kilo-Org/kilocode/blob/HEAD/script/upstream/merge.ts) handles a key part of this chapter's functionality:
+The `extract` function in [`script/extract-source-links.ts`](https://github.com/Kilo-Org/kilocode/blob/HEAD/script/extract-source-links.ts) handles a key part of this chapter's functionality:
```ts
-}
-
-async function getAuthor(): Promise<string> {
- const result = await $`git config user.name`.text()
- return result
- .trim()
- .normalize("NFD")
- .replace(/[\u0300-\u036f]/g, "")
- .toLowerCase()
- .replace(/\s+/g, "")
-}
-
-async function createBackupBranch(baseBranch: string): Promise<string> {
- const timestamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19)
- const backupName = `backup/${baseBranch}-${timestamp}`
-
- await git.createBranch(backupName, baseBranch)
- await git.checkout(baseBranch)
-
- return backupName
-}
-
-async function main() {
- const options = parseArgs()
- const config = loadConfig(options.baseBranch ? { baseBranch: options.baseBranch } : undefined)
-
- if (options.verbose) {
- logger.setVerbose(true)
- }
-
- logger.header("Kilo Upstream Merge Tool")
-
+ *
+ * Usage:
+ * bun run script/extract-source-links.ts # Generate / update the committed file
+ * bun run script/extract-source-links.ts --check # CI mode — exit 1 if the file is stale
+ */
+
+import { Glob } from "bun"
+import path from "path"
+
+const ROOT = path.resolve(import.meta.dir, "..")
+const OUTPUT = path.join(ROOT, "packages/kilo-docs/source-links.md")
+
+const check = process.argv.includes("--check")
+
+const DIRS = [
+ path.join(ROOT, "packages/kilo-vscode/src"),
+ path.join(ROOT, "packages/kilo-vscode/webview-ui"),
+ path.join(ROOT, "packages/opencode/src"),
+]
+
+const EXTENSIONS = ["ts", "tsx", "js", "jsx"]
+
+// Matches http:// and https:// URLs in string literals or comments
+const URL_RE = /https?:\/\/[^\s"'`)\]},;*\\<>]+/g
+
+// URLs to exclude — only genuinely non-checkable URLs (API endpoints, localhost,
+// examples, dynamic templates, namespaces). Real external URLs should be extracted
+// and validated by lychee; add lychee.toml exclusions for sites that block bots.
+const EXCLUDE_PATTERNS = [
+ // Localhost and internal
+ /^https?:\/\/(localhost|127\.0\.0\.1|0\.0\.0\.0)/,
+ /^https?:\/\/kilo\.internal/,
```
This function is important because it defines how Kilo Code Tutorial: Agentic Engineering from IDE and CLI Surfaces implements the patterns covered in this chapter.
-### `script/upstream/merge.ts`
+### `script/extract-source-links.ts`
-The `createBackupBranch` function in [`script/upstream/merge.ts`](https://github.com/Kilo-Org/kilocode/blob/HEAD/script/upstream/merge.ts) handles a key part of this chapter's functionality:
+The `render` function in [`script/extract-source-links.ts`](https://github.com/Kilo-Org/kilocode/blob/HEAD/script/extract-source-links.ts) handles a key part of this chapter's functionality:
```ts
}
-async function createBackupBranch(baseBranch: string): Promise<string> {
- const timestamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19)
- const backupName = `backup/${baseBranch}-${timestamp}`
-
- await git.createBranch(backupName, baseBranch)
- await git.checkout(baseBranch)
-
- return backupName
-}
-
-async function main() {
- const options = parseArgs()
- const config = loadConfig(options.baseBranch ? { baseBranch: options.baseBranch } : undefined)
-
- if (options.verbose) {
- logger.setVerbose(true)
+function render(sorted: [string, Set<string>][]): string {
+ const parts = [
+ "# Source Code Links",
+ "",
+ "<!-- Auto-generated by script/extract-source-links.ts — DO NOT EDIT -->",
+ `<!-- ${sorted.length} unique URLs extracted from extension and CLI source -->`,
+ "",
+ ]
+
+ for (const [url, files] of sorted) {
+ parts.push(`- <${url}>`)
+ for (const file of [...files].sort()) {
+ parts.push(` <!-- ${file} -->`)
+ }
}
- logger.header("Kilo Upstream Merge Tool")
-
- // Step 1: Validate environment
- logger.step(1, 8, "Validating environment...")
+ parts.push("")
+ return parts.join("\n")
+}
- if (!(await git.hasUpstreamRemote())) {
- logger.error("No 'upstream' remote found. Please add it:")
- logger.info(" git remote add upstream git@github.com:anomalyco/opencode.git")
- process.exit(1)
- }
+const links = await extract()
+const sorted = [...links.entries()].sort(([a], [b]) => a.localeCompare(b))
+const output = render(sorted)
- if (await git.hasUncommittedChanges()) {
+if (check) {
+ const committed = await Bun.file(OUTPUT)
+ .text()
+ .catch(() => "")
+ if (committed === output) {
+ console.log("packages/kilo-docs/source-links.md is up to date.")
```
This function is important because it defines how Kilo Code Tutorial: Agentic Engineering from IDE and CLI Surfaces implements the patterns covered in this chapter.
@@ -206,10 +204,10 @@ This function is important because it defines how Kilo Code Tutorial: Agentic En
```mermaid
flowchart TD
- A[main]
- B[parseArgs]
- C[getAuthor]
- D[createBackupBranch]
+ A[shouldSkipFile]
+ B[clean]
+ C[extract]
+ D[render]
A --> B
B --> C
C --> D
diff --git a/tutorials/kilocode-tutorial/08-production-operations-and-governance.md b/tutorials/kilocode-tutorial/08-production-operations-and-governance.md
index 172a5b81..218018de 100644
--- a/tutorials/kilocode-tutorial/08-production-operations-and-governance.md
+++ b/tutorials/kilocode-tutorial/08-production-operations-and-governance.md
@@ -30,102 +30,106 @@ Production Kilo adoption requires clear policy around auth, approvals, extension
You now have a team-ready operational baseline for Kilo deployment and governance.
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `script/upstream/merge.ts`
+### `script/sync-zed.ts`
-The `main` function in [`script/upstream/merge.ts`](https://github.com/Kilo-Org/kilocode/blob/HEAD/script/upstream/merge.ts) handles a key part of this chapter's functionality:
+The `main` function in [`script/sync-zed.ts`](https://github.com/Kilo-Org/kilocode/blob/HEAD/script/sync-zed.ts) handles a key part of this chapter's functionality:
```ts
- * --version <version> Target upstream version (e.g., v1.1.49)
- * --commit <hash> Target upstream commit hash
- * --base-branch <name> Base branch to merge into (default: main)
- * --dry-run Preview changes without applying them
- * --no-push Don't push branches to remote
- * --report-only Only generate conflict report, don't merge
- * --verbose Enable verbose logging
- * --author <name> Author name for branch prefix (default: from git config)
- */
-
-import { $ } from "bun"
-import * as git from "./utils/git"
-import * as logger from "./utils/logger"
-import * as version from "./utils/version"
-import * as report from "./utils/report"
-import { defaultConfig, loadConfig, type MergeConfig } from "./utils/config"
-import { transformAll as transformPackageNames } from "./transforms/package-names"
-import { preserveAllVersions } from "./transforms/preserve-versions"
-import { keepOursFiles, resetToOurs } from "./transforms/keep-ours"
-import { skipFiles, skipSpecificFiles } from "./transforms/skip-files"
-import { transformConflictedI18n, transformAllI18n } from "./transforms/transform-i18n"
-// New transforms for auto-resolving more conflict types
-import {
- transformConflictedTakeTheirs,
- shouldTakeTheirs,
- transformAllTakeTheirs,
-} from "./transforms/transform-take-theirs"
-import { transformConflictedTauri, isTauriFile, transformAllTauri } from "./transforms/transform-tauri"
-import {
- transformConflictedPackageJson,
- isPackageJson,
- transformAllPackageJson,
+const EXTENSION_NAME = "opencode"
+
+async function main() {
+ const version = process.argv[2]
+ if (!version) throw new Error("Version argument required, ex: bun script/sync-zed.ts v1.0.52")
+
+ const token = process.env.ZED_EXTENSIONS_PAT
+ if (!token) throw new Error("ZED_EXTENSIONS_PAT environment variable required")
+
+ const prToken = process.env.ZED_PR_PAT
+ if (!prToken) throw new Error("ZED_PR_PAT environment variable required")
+
+ const cleanVersion = version.replace(/^v/, "")
+ console.log(`📦 Syncing Zed extension for version ${cleanVersion}`)
+
+ const commitSha = await $`git rev-parse ${version}`.text()
+ const sha = commitSha.trim()
+ console.log(`🔍 Found commit SHA: ${sha}`)
+
+ const extensionToml = await $`git show ${version}:packages/extensions/zed/extension.toml`.text()
+ const parsed = Bun.TOML.parse(extensionToml) as { version: string }
+ const extensionVersion = parsed.version
+
+ if (extensionVersion !== cleanVersion) {
+ throw new Error(`Version mismatch: extension.toml has ${extensionVersion} but tag is ${cleanVersion}`)
+ }
+ console.log(`✅ Version ${extensionVersion} matches tag`)
+
+ // Clone the fork to a temp directory
+ const workDir = join(tmpdir(), `zed-extensions-${Date.now()}`)
+ console.log(`📁 Working in ${workDir}`)
+
```
This function is important because it defines how Kilo Code Tutorial: Agentic Engineering from IDE and CLI Surfaces implements the patterns covered in this chapter.
-### `script/upstream/merge.ts`
+### `script/duplicate-pr.ts`
-The `MergeOptions` interface in [`script/upstream/merge.ts`](https://github.com/Kilo-Org/kilocode/blob/HEAD/script/upstream/merge.ts) handles a key part of this chapter's functionality:
+The `main` function in [`script/duplicate-pr.ts`](https://github.com/Kilo-Org/kilocode/blob/HEAD/script/duplicate-pr.ts) handles a key part of this chapter's functionality:
```ts
-import { resolveLockFileConflicts, regenerateLockFiles } from "./transforms/lock-files"
-
-interface MergeOptions {
- version?: string
- commit?: string
- baseBranch?: string
- dryRun: boolean
- push: boolean
- reportOnly: boolean
- verbose: boolean
- author?: string
-}
+import { parseArgs } from "util"
-function parseArgs(): MergeOptions {
- const args = process.argv.slice(2)
-
- const options: MergeOptions = {
- dryRun: args.includes("--dry-run"),
- push: !args.includes("--no-push"),
- reportOnly: args.includes("--report-only"),
- verbose: args.includes("--verbose"),
+async function main() {
+ const { values, positionals } = parseArgs({
+ args: Bun.argv.slice(2),
+ options: {
+ file: { type: "string", short: "f" },
+ help: { type: "boolean", short: "h", default: false },
+ },
+ allowPositionals: true,
+ })
+
+ if (values.help) {
+ console.log(`
+Usage: bun script/duplicate-pr.ts [options] <message>
+
+Options:
+ -f, --file <path> File to attach to the prompt
+ -h, --help Show this help message
+
+Examples:
+ bun script/duplicate-pr.ts -f pr_info.txt "Check the attached file for PR details"
+`)
+ process.exit(0)
}
- const versionIdx = args.indexOf("--version")
- if (versionIdx !== -1 && args[versionIdx + 1]) {
- options.version = args[versionIdx + 1]
+ const message = positionals.join(" ")
+ if (!message) {
+ console.error("Error: message is required")
+ process.exit(1)
}
- const commitIdx = args.indexOf("--commit")
- if (commitIdx !== -1 && args[commitIdx + 1]) {
- options.commit = args[commitIdx + 1]
- }
```
-This interface is important because it defines how Kilo Code Tutorial: Agentic Engineering from IDE and CLI Surfaces implements the patterns covered in this chapter.
+This function is important because it defines how Kilo Code Tutorial: Agentic Engineering from IDE and CLI Surfaces implements the patterns covered in this chapter.
-### `script/upstream/analyze.ts`
+### `script/upstream/merge.ts`
-The `parseArgs` function in [`script/upstream/analyze.ts`](https://github.com/Kilo-Org/kilocode/blob/HEAD/script/upstream/analyze.ts) handles a key part of this chapter's functionality:
+The `parseArgs` function in [`script/upstream/merge.ts`](https://github.com/Kilo-Org/kilocode/blob/HEAD/script/upstream/merge.ts) handles a key part of this chapter's functionality:
```ts
}
-function parseArgs(): AnalyzeOptions {
+function parseArgs(): MergeOptions {
const args = process.argv.slice(2)
- const options: AnalyzeOptions = {}
+
+ const options: MergeOptions = {
+ dryRun: args.includes("--dry-run"),
+ push: !args.includes("--no-push"),
+ reportOnly: args.includes("--report-only"),
+ verbose: args.includes("--verbose"),
+ }
const versionIdx = args.indexOf("--version")
if (versionIdx !== -1 && args[versionIdx + 1]) {
@@ -137,9 +141,9 @@ function parseArgs(): AnalyzeOptions {
options.commit = args[commitIdx + 1]
}
- const outputIdx = args.indexOf("--output")
- if (outputIdx !== -1 && args[outputIdx + 1]) {
- options.output = args[outputIdx + 1]
+ const authorIdx = args.indexOf("--author")
+ if (authorIdx !== -1 && args[authorIdx + 1]) {
+ options.author = args[authorIdx + 1]
}
const baseBranchIdx = args.indexOf("--base-branch")
@@ -147,53 +151,47 @@ function parseArgs(): AnalyzeOptions {
options.baseBranch = args[baseBranchIdx + 1]
}
- return options
-}
-
-async function main() {
- const options = parseArgs()
- const config = loadConfig(options.baseBranch ? { baseBranch: options.baseBranch } : undefined)
```
This function is important because it defines how Kilo Code Tutorial: Agentic Engineering from IDE and CLI Surfaces implements the patterns covered in this chapter.
-### `script/upstream/analyze.ts`
+### `script/upstream/merge.ts`
-The `main` function in [`script/upstream/analyze.ts`](https://github.com/Kilo-Org/kilocode/blob/HEAD/script/upstream/analyze.ts) handles a key part of this chapter's functionality:
+The `getAuthor` function in [`script/upstream/merge.ts`](https://github.com/Kilo-Org/kilocode/blob/HEAD/script/upstream/merge.ts) handles a key part of this chapter's functionality:
```ts
}
+async function getAuthor(): Promise<string> {
+ const result = await $`git config user.name`.text()
+ return result
+ .trim()
+ .normalize("NFD")
+ .replace(/[\u0300-\u036f]/g, "")
+ .toLowerCase()
+ .replace(/\s+/g, "")
+}
+
+async function createBackupBranch(baseBranch: string): Promise<string> {
+ const timestamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19)
+ const backupName = `backup/${baseBranch}-${timestamp}`
+
+ await git.createBranch(backupName, baseBranch)
+ await git.checkout(baseBranch)
+
+ return backupName
+}
+
async function main() {
const options = parseArgs()
const config = loadConfig(options.baseBranch ? { baseBranch: options.baseBranch } : undefined)
- header("Upstream Change Analysis")
-
- // Check upstream remote
- if (!(await git.hasUpstreamRemote())) {
- error("No 'upstream' remote found. Please add it:")
- info(" git remote add upstream git@github.com:anomalyco/opencode.git")
- process.exit(1)
+ if (options.verbose) {
+ logger.setVerbose(true)
}
- // Fetch upstream
- info("Fetching upstream...")
- await git.fetchUpstream()
-
- // Determine target
- let target: version.VersionInfo | null = null
-
- if (options.commit) {
- target = await version.getVersionForCommit(options.commit)
- if (!target) {
- target = { version: "unknown", tag: "unknown", commit: options.commit }
- }
- } else if (options.version) {
- const versions = await version.getAvailableUpstreamVersions()
- target = versions.find((v) => v.version === options.version || v.tag === options.version) || null
+ logger.header("Kilo Upstream Merge Tool")
- if (!target) {
```
This function is important because it defines how Kilo Code Tutorial: Agentic Engineering from IDE and CLI Surfaces implements the patterns covered in this chapter.
@@ -204,9 +202,9 @@ This function is important because it defines how Kilo Code Tutorial: Agentic En
```mermaid
flowchart TD
A[main]
- B[MergeOptions]
+ B[main]
C[parseArgs]
- D[main]
+ D[getAuthor]
A --> B
B --> C
C --> D
diff --git a/tutorials/kimi-cli-tutorial/01-getting-started.md b/tutorials/kimi-cli-tutorial/01-getting-started.md
index 68eed1b9..94a91c7f 100644
--- a/tutorials/kimi-cli-tutorial/01-getting-started.md
+++ b/tutorials/kimi-cli-tutorial/01-getting-started.md
@@ -48,129 +48,127 @@ You now have Kimi CLI running with authenticated provider access.
Next: [Chapter 2: Command Surface and Session Controls](02-command-surface-and-session-controls.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `web/vite.config.ts`
-
-The `readKimiCliVersion` function in [`web/vite.config.ts`](https://github.com/MoonshotAI/kimi-cli/blob/HEAD/web/vite.config.ts) handles a key part of this chapter's functionality:
-
-```ts
-const PYPROJECT_VERSION_REGEX = /^\s*version\s*=\s*"([^"]+)"/m;
-
-function readKimiCliVersion(): string {
- const fallback = process.env.KIMI_CLI_VERSION ?? "dev";
- const pyprojectPath = path.resolve(__dirname, "../pyproject.toml");
-
- try {
- const pyproject = fs.readFileSync(pyprojectPath, "utf8");
- const match = pyproject.match(PYPROJECT_VERSION_REGEX);
- if (match?.[1]) {
- return match[1];
- }
- } catch (error) {
- console.warn("[vite] Unable to read version", pyprojectPath, error);
- }
-
- return fallback;
-}
-
-const kimiCliVersion = readKimiCliVersion();
-const shouldAnalyze = process.env.ANALYZE === "true";
-
-// https://vite.dev/config/
-export default defineConfig({
- // Use relative paths so assets work under any base path.
- base: "./",
- plugins: [
- nodePolyfills({
- include: ["path", "url"],
- }),
- react(),
- tailwindcss(),
+### `scripts/cleanup_tmp_sessions.py`
+
+The `is_tmp_path` function in [`scripts/cleanup_tmp_sessions.py`](https://github.com/MoonshotAI/kimi-cli/blob/HEAD/scripts/cleanup_tmp_sessions.py) handles a key part of this chapter's functionality:
+
+```py
+
+
+def is_tmp_path(path: str) -> bool:
+ """Return True if *path* looks like a temporary directory."""
+ if path in ("/tmp", "/private/tmp"):
+ return True
+ return any(path.startswith(p) for p in TMP_PREFIXES)
+
+
+def work_dir_hash(path: str, kaos: str = "local") -> str:
+ h = md5(path.encode("utf-8")).hexdigest()
+ return h if kaos == "local" else f"{kaos}_{h}"
+
+
+def dir_total_size(d: Path) -> int:
+ return sum(f.stat().st_size for f in d.rglob("*") if f.is_file())
+
+
+def main() -> None:
+ parser = argparse.ArgumentParser(
+ description=__doc__,
+ formatter_class=argparse.RawDescriptionHelpFormatter,
+ )
+ parser.add_argument("--apply", action="store_true", help="Actually delete (default is dry-run)")
+ args = parser.parse_args()
+
+ if not METADATA_FILE.exists():
+ print(f"Metadata file not found: {METADATA_FILE}")
+ sys.exit(1)
+
+ with open(METADATA_FILE, encoding="utf-8") as f:
+ metadata = json.load(f)
```
This function is important because it defines how Kimi CLI Tutorial: Multi-Mode Terminal Agent with MCP and ACP implements the patterns covered in this chapter.
-### `scripts/check_version_tag.py`
+### `scripts/cleanup_tmp_sessions.py`
-The `load_project_version` function in [`scripts/check_version_tag.py`](https://github.com/MoonshotAI/kimi-cli/blob/HEAD/scripts/check_version_tag.py) handles a key part of this chapter's functionality:
+The `work_dir_hash` function in [`scripts/cleanup_tmp_sessions.py`](https://github.com/MoonshotAI/kimi-cli/blob/HEAD/scripts/cleanup_tmp_sessions.py) handles a key part of this chapter's functionality:
```py
-def load_project_version(pyproject_path: Path) -> str:
- with pyproject_path.open("rb") as handle:
- data = tomllib.load(handle)
+def work_dir_hash(path: str, kaos: str = "local") -> str:
+ h = md5(path.encode("utf-8")).hexdigest()
+ return h if kaos == "local" else f"{kaos}_{h}"
- project = data.get("project")
- if not isinstance(project, dict):
- raise ValueError(f"Missing [project] table in {pyproject_path}")
- version = project.get("version")
- if not isinstance(version, str) or not version:
- raise ValueError(f"Missing project.version in {pyproject_path}")
+def dir_total_size(d: Path) -> int:
+ return sum(f.stat().st_size for f in d.rglob("*") if f.is_file())
- return version
-
-def main() -> int:
- parser = argparse.ArgumentParser(description="Validate tag version against pyproject.")
- parser.add_argument("--pyproject", type=Path, required=True)
- parser.add_argument("--expected-version", required=True)
+def main() -> None:
+ parser = argparse.ArgumentParser(
+ description=__doc__,
+ formatter_class=argparse.RawDescriptionHelpFormatter,
+ )
+ parser.add_argument("--apply", action="store_true", help="Actually delete (default is dry-run)")
args = parser.parse_args()
- semver_re = re.compile(r"^\d+\.\d+\.\d+$")
- if not semver_re.match(args.expected_version):
- print(
- f"error: expected version must include patch (x.y.z): {args.expected_version}",
- file=sys.stderr,
- )
- return 1
+ if not METADATA_FILE.exists():
+ print(f"Metadata file not found: {METADATA_FILE}")
+ sys.exit(1)
+
+ with open(METADATA_FILE, encoding="utf-8") as f:
+ metadata = json.load(f)
+
+ work_dirs: list[dict] = metadata.get("work_dirs", [])
- try:
+ # --- Phase 1: tmp entries in kimi.json ---
+ tmp_entries: list[dict] = []
+ keep_entries: list[dict] = []
+ keep_hashes: set[str] = set()
```
This function is important because it defines how Kimi CLI Tutorial: Multi-Mode Terminal Agent with MCP and ACP implements the patterns covered in this chapter.
-### `scripts/check_version_tag.py`
+### `scripts/cleanup_tmp_sessions.py`
-The `main` function in [`scripts/check_version_tag.py`](https://github.com/MoonshotAI/kimi-cli/blob/HEAD/scripts/check_version_tag.py) handles a key part of this chapter's functionality:
+The `dir_total_size` function in [`scripts/cleanup_tmp_sessions.py`](https://github.com/MoonshotAI/kimi-cli/blob/HEAD/scripts/cleanup_tmp_sessions.py) handles a key part of this chapter's functionality:
```py
-def main() -> int:
- parser = argparse.ArgumentParser(description="Validate tag version against pyproject.")
- parser.add_argument("--pyproject", type=Path, required=True)
- parser.add_argument("--expected-version", required=True)
+def dir_total_size(d: Path) -> int:
+ return sum(f.stat().st_size for f in d.rglob("*") if f.is_file())
+
+
+def main() -> None:
+ parser = argparse.ArgumentParser(
+ description=__doc__,
+ formatter_class=argparse.RawDescriptionHelpFormatter,
+ )
+ parser.add_argument("--apply", action="store_true", help="Actually delete (default is dry-run)")
args = parser.parse_args()
- semver_re = re.compile(r"^\d+\.\d+\.\d+$")
- if not semver_re.match(args.expected_version):
- print(
- f"error: expected version must include patch (x.y.z): {args.expected_version}",
- file=sys.stderr,
- )
- return 1
-
- try:
- project_version = load_project_version(args.pyproject)
- except ValueError as exc:
- print(f"error: {exc}", file=sys.stderr)
- return 1
-
- if not semver_re.match(project_version):
- print(
- "error: project version must include patch (x.y.z): "
- f"{args.pyproject} has {project_version}",
- file=sys.stderr,
- )
- return 1
-
- if project_version != args.expected_version:
- print(
+ if not METADATA_FILE.exists():
+ print(f"Metadata file not found: {METADATA_FILE}")
+ sys.exit(1)
+
+ with open(METADATA_FILE, encoding="utf-8") as f:
+ metadata = json.load(f)
+
+ work_dirs: list[dict] = metadata.get("work_dirs", [])
+
+ # --- Phase 1: tmp entries in kimi.json ---
+ tmp_entries: list[dict] = []
+ keep_entries: list[dict] = []
+ keep_hashes: set[str] = set()
+ for wd in work_dirs:
+ if is_tmp_path(wd.get("path", "")):
+ tmp_entries.append(wd)
+ else:
+ keep_entries.append(wd)
```
This function is important because it defines how Kimi CLI Tutorial: Multi-Mode Terminal Agent with MCP and ACP implements the patterns covered in this chapter.
@@ -180,9 +178,9 @@ This function is important because it defines how Kimi CLI Tutorial: Multi-Mode
```mermaid
flowchart TD
- A[readKimiCliVersion]
- B[load_project_version]
- C[main]
+ A[is_tmp_path]
+ B[work_dir_hash]
+ C[dir_total_size]
A --> B
B --> C
```
diff --git a/tutorials/kimi-cli-tutorial/02-command-surface-and-session-controls.md b/tutorials/kimi-cli-tutorial/02-command-surface-and-session-controls.md
index caeb9745..7aaf1367 100644
--- a/tutorials/kimi-cli-tutorial/02-command-surface-and-session-controls.md
+++ b/tutorials/kimi-cli-tutorial/02-command-surface-and-session-controls.md
@@ -41,58 +41,108 @@ You now understand the core startup/session controls for predictable Kimi workfl
Next: [Chapter 3: Agents, Subagents, and Skills](03-agents-subagents-and-skills.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `scripts/check_kimi_dependency_versions.py`
+### `scripts/cleanup_tmp_sessions.py`
-The `load_project_table` function in [`scripts/check_kimi_dependency_versions.py`](https://github.com/MoonshotAI/kimi-cli/blob/HEAD/scripts/check_kimi_dependency_versions.py) handles a key part of this chapter's functionality:
+The `main` function in [`scripts/cleanup_tmp_sessions.py`](https://github.com/MoonshotAI/kimi-cli/blob/HEAD/scripts/cleanup_tmp_sessions.py) handles a key part of this chapter's functionality:
```py
-def load_project_table(pyproject_path: Path) -> dict:
- with pyproject_path.open("rb") as handle:
- data = tomllib.load(handle)
+def main() -> None:
+ parser = argparse.ArgumentParser(
+ description=__doc__,
+ formatter_class=argparse.RawDescriptionHelpFormatter,
+ )
+ parser.add_argument("--apply", action="store_true", help="Actually delete (default is dry-run)")
+ args = parser.parse_args()
- project = data.get("project")
- if not isinstance(project, dict):
- raise ValueError(f"Missing [project] table in {pyproject_path}")
+ if not METADATA_FILE.exists():
+ print(f"Metadata file not found: {METADATA_FILE}")
+ sys.exit(1)
- return project
+ with open(METADATA_FILE, encoding="utf-8") as f:
+ metadata = json.load(f)
+ work_dirs: list[dict] = metadata.get("work_dirs", [])
-def load_project_version(pyproject_path: Path) -> str:
- project = load_project_table(pyproject_path)
- version = project.get("version")
- if not isinstance(version, str) or not version:
- raise ValueError(f"Missing project.version in {pyproject_path}")
- return version
+ # --- Phase 1: tmp entries in kimi.json ---
+ tmp_entries: list[dict] = []
+ keep_entries: list[dict] = []
+ keep_hashes: set[str] = set()
+ for wd in work_dirs:
+ if is_tmp_path(wd.get("path", "")):
+ tmp_entries.append(wd)
+ else:
+ keep_entries.append(wd)
+ keep_hashes.add(work_dir_hash(wd["path"], wd.get("kaos", "local")))
+ tmp_dirs: list[Path] = []
+ for wd in tmp_entries:
+```
-def find_pinned_dependency(deps: list[str], name: str) -> str | None:
- pattern = re.compile(rf"^{re.escape(name)}(?:\[[^\]]+\])?(.+)$")
- for dep in deps:
- match = pattern.match(dep)
- if not match:
- continue
- spec = match.group(1)
- pinned = re.match(r"^==(.+)$", spec)
- if pinned:
- return pinned.group(1)
- return None
+This function is important because it defines how Kimi CLI Tutorial: Multi-Mode Terminal Agent with MCP and ACP implements the patterns covered in this chapter.
+
+### `web/vite.config.ts`
+
+The `readKimiCliVersion` function in [`web/vite.config.ts`](https://github.com/MoonshotAI/kimi-cli/blob/HEAD/web/vite.config.ts) handles a key part of this chapter's functionality:
+
+```ts
+const PYPROJECT_VERSION_REGEX = /^\s*version\s*=\s*"([^"]+)"/m;
+
+function readKimiCliVersion(): string {
+ const fallback = process.env.KIMI_CLI_VERSION ?? "dev";
+ const pyprojectPath = path.resolve(__dirname, "../pyproject.toml");
+
+ try {
+ const pyproject = fs.readFileSync(pyprojectPath, "utf8");
+ const match = pyproject.match(PYPROJECT_VERSION_REGEX);
+ if (match?.[1]) {
+ return match[1];
+ }
+ } catch (error) {
+ console.warn("[vite] Unable to read version", pyprojectPath, error);
+ }
+
+ return fallback;
+}
+
+const kimiCliVersion = readKimiCliVersion();
+const shouldAnalyze = process.env.ANALYZE === "true";
+
+// https://vite.dev/config/
+export default defineConfig({
+ // Use relative paths so assets work under any base path.
+ base: "./",
+ plugins: [
+ nodePolyfills({
+ include: ["path", "url"],
+ }),
+ react(),
+ tailwindcss(),
```
This function is important because it defines how Kimi CLI Tutorial: Multi-Mode Terminal Agent with MCP and ACP implements the patterns covered in this chapter.
### `scripts/check_kimi_dependency_versions.py`
-The `load_project_version` function in [`scripts/check_kimi_dependency_versions.py`](https://github.com/MoonshotAI/kimi-cli/blob/HEAD/scripts/check_kimi_dependency_versions.py) handles a key part of this chapter's functionality:
+The `load_project_table` function in [`scripts/check_kimi_dependency_versions.py`](https://github.com/MoonshotAI/kimi-cli/blob/HEAD/scripts/check_kimi_dependency_versions.py) handles a key part of this chapter's functionality:
```py
+def load_project_table(pyproject_path: Path) -> dict:
+ with pyproject_path.open("rb") as handle:
+ data = tomllib.load(handle)
+
+ project = data.get("project")
+ if not isinstance(project, dict):
+ raise ValueError(f"Missing [project] table in {pyproject_path}")
+
+ return project
+
+
def load_project_version(pyproject_path: Path) -> str:
project = load_project_table(pyproject_path)
version = project.get("version")
@@ -112,58 +162,6 @@ def find_pinned_dependency(deps: list[str], name: str) -> str | None:
if pinned:
return pinned.group(1)
return None
- return None
-
-
-def main() -> int:
- parser = argparse.ArgumentParser(description="Validate kimi-cli dependency versions.")
- parser.add_argument("--root-pyproject", type=Path, required=True)
- parser.add_argument("--kosong-pyproject", type=Path, required=True)
- parser.add_argument("--pykaos-pyproject", type=Path, required=True)
- args = parser.parse_args()
-
- try:
-```
-
-This function is important because it defines how Kimi CLI Tutorial: Multi-Mode Terminal Agent with MCP and ACP implements the patterns covered in this chapter.
-
-### `scripts/check_kimi_dependency_versions.py`
-
-The `find_pinned_dependency` function in [`scripts/check_kimi_dependency_versions.py`](https://github.com/MoonshotAI/kimi-cli/blob/HEAD/scripts/check_kimi_dependency_versions.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def find_pinned_dependency(deps: list[str], name: str) -> str | None:
- pattern = re.compile(rf"^{re.escape(name)}(?:\[[^\]]+\])?(.+)$")
- for dep in deps:
- match = pattern.match(dep)
- if not match:
- continue
- spec = match.group(1)
- pinned = re.match(r"^==(.+)$", spec)
- if pinned:
- return pinned.group(1)
- return None
- return None
-
-
-def main() -> int:
- parser = argparse.ArgumentParser(description="Validate kimi-cli dependency versions.")
- parser.add_argument("--root-pyproject", type=Path, required=True)
- parser.add_argument("--kosong-pyproject", type=Path, required=True)
- parser.add_argument("--pykaos-pyproject", type=Path, required=True)
- args = parser.parse_args()
-
- try:
- root_project = load_project_table(args.root_pyproject)
- except ValueError as exc:
- print(f"error: {exc}", file=sys.stderr)
- return 1
-
- deps = root_project.get("dependencies", [])
- if not isinstance(deps, list):
- print(
```
This function is important because it defines how Kimi CLI Tutorial: Multi-Mode Terminal Agent with MCP and ACP implements the patterns covered in this chapter.
@@ -173,9 +171,9 @@ This function is important because it defines how Kimi CLI Tutorial: Multi-Mode
```mermaid
flowchart TD
- A[load_project_table]
- B[load_project_version]
- C[find_pinned_dependency]
+ A[main]
+ B[readKimiCliVersion]
+ C[load_project_table]
A --> B
B --> C
```
diff --git a/tutorials/kimi-cli-tutorial/03-agents-subagents-and-skills.md b/tutorials/kimi-cli-tutorial/03-agents-subagents-and-skills.md
index 9e3818aa..c371b03d 100644
--- a/tutorials/kimi-cli-tutorial/03-agents-subagents-and-skills.md
+++ b/tutorials/kimi-cli-tutorial/03-agents-subagents-and-skills.md
@@ -38,17 +38,37 @@ You now have a strategy for standardized yet flexible Kimi behavior customizatio
Next: [Chapter 4: MCP Tooling and Security Model](04-mcp-tooling-and-security-model.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `scripts/check_kimi_dependency_versions.py`
-The `main` function in [`scripts/check_kimi_dependency_versions.py`](https://github.com/MoonshotAI/kimi-cli/blob/HEAD/scripts/check_kimi_dependency_versions.py) handles a key part of this chapter's functionality:
+The `load_project_version` function in [`scripts/check_kimi_dependency_versions.py`](https://github.com/MoonshotAI/kimi-cli/blob/HEAD/scripts/check_kimi_dependency_versions.py) handles a key part of this chapter's functionality:
```py
+def load_project_version(pyproject_path: Path) -> str:
+ project = load_project_table(pyproject_path)
+ version = project.get("version")
+ if not isinstance(version, str) or not version:
+ raise ValueError(f"Missing project.version in {pyproject_path}")
+ return version
+
+
+def find_pinned_dependency(deps: list[str], name: str) -> str | None:
+ pattern = re.compile(rf"^{re.escape(name)}(?:\[[^\]]+\])?(.+)$")
+ for dep in deps:
+ match = pattern.match(dep)
+ if not match:
+ continue
+ spec = match.group(1)
+ pinned = re.match(r"^==(.+)$", spec)
+ if pinned:
+ return pinned.group(1)
+ return None
+ return None
+
+
def main() -> int:
parser = argparse.ArgumentParser(description="Validate kimi-cli dependency versions.")
parser.add_argument("--root-pyproject", type=Path, required=True)
@@ -57,110 +77,88 @@ def main() -> int:
args = parser.parse_args()
try:
- root_project = load_project_table(args.root_pyproject)
- except ValueError as exc:
- print(f"error: {exc}", file=sys.stderr)
- return 1
-
- deps = root_project.get("dependencies", [])
- if not isinstance(deps, list):
- print(
- f"error: project.dependencies must be a list in {args.root_pyproject}",
- file=sys.stderr,
- )
- return 1
-
- errors: list[str] = []
- for name, pyproject_path in (
- ("kosong", args.kosong_pyproject),
- ("pykaos", args.pykaos_pyproject),
- ):
- try:
- package_version = load_project_version(pyproject_path)
- except ValueError as exc:
- errors.append(str(exc))
```
This function is important because it defines how Kimi CLI Tutorial: Multi-Mode Terminal Agent with MCP and ACP implements the patterns covered in this chapter.
-### `scripts/cleanup_tmp_sessions.py`
+### `scripts/check_kimi_dependency_versions.py`
-The `is_tmp_path` function in [`scripts/cleanup_tmp_sessions.py`](https://github.com/MoonshotAI/kimi-cli/blob/HEAD/scripts/cleanup_tmp_sessions.py) handles a key part of this chapter's functionality:
+The `find_pinned_dependency` function in [`scripts/check_kimi_dependency_versions.py`](https://github.com/MoonshotAI/kimi-cli/blob/HEAD/scripts/check_kimi_dependency_versions.py) handles a key part of this chapter's functionality:
```py
-def is_tmp_path(path: str) -> bool:
- """Return True if *path* looks like a temporary directory."""
- if path in ("/tmp", "/private/tmp"):
- return True
- return any(path.startswith(p) for p in TMP_PREFIXES)
-
+def find_pinned_dependency(deps: list[str], name: str) -> str | None:
+ pattern = re.compile(rf"^{re.escape(name)}(?:\[[^\]]+\])?(.+)$")
+ for dep in deps:
+ match = pattern.match(dep)
+ if not match:
+ continue
+ spec = match.group(1)
+ pinned = re.match(r"^==(.+)$", spec)
+ if pinned:
+ return pinned.group(1)
+ return None
+ return None
-def work_dir_hash(path: str, kaos: str = "local") -> str:
- h = md5(path.encode("utf-8")).hexdigest()
- return h if kaos == "local" else f"{kaos}_{h}"
-
-def dir_total_size(d: Path) -> int:
- return sum(f.stat().st_size for f in d.rglob("*") if f.is_file())
-
-
-def main() -> None:
- parser = argparse.ArgumentParser(
- description=__doc__,
- formatter_class=argparse.RawDescriptionHelpFormatter,
- )
- parser.add_argument("--apply", action="store_true", help="Actually delete (default is dry-run)")
+def main() -> int:
+ parser = argparse.ArgumentParser(description="Validate kimi-cli dependency versions.")
+ parser.add_argument("--root-pyproject", type=Path, required=True)
+ parser.add_argument("--kosong-pyproject", type=Path, required=True)
+ parser.add_argument("--pykaos-pyproject", type=Path, required=True)
args = parser.parse_args()
- if not METADATA_FILE.exists():
- print(f"Metadata file not found: {METADATA_FILE}")
- sys.exit(1)
+ try:
+ root_project = load_project_table(args.root_pyproject)
+ except ValueError as exc:
+ print(f"error: {exc}", file=sys.stderr)
+ return 1
- with open(METADATA_FILE, encoding="utf-8") as f:
- metadata = json.load(f)
+ deps = root_project.get("dependencies", [])
+ if not isinstance(deps, list):
+ print(
```
This function is important because it defines how Kimi CLI Tutorial: Multi-Mode Terminal Agent with MCP and ACP implements the patterns covered in this chapter.
-### `scripts/cleanup_tmp_sessions.py`
+### `scripts/check_kimi_dependency_versions.py`
-The `work_dir_hash` function in [`scripts/cleanup_tmp_sessions.py`](https://github.com/MoonshotAI/kimi-cli/blob/HEAD/scripts/cleanup_tmp_sessions.py) handles a key part of this chapter's functionality:
+The `main` function in [`scripts/check_kimi_dependency_versions.py`](https://github.com/MoonshotAI/kimi-cli/blob/HEAD/scripts/check_kimi_dependency_versions.py) handles a key part of this chapter's functionality:
```py
-def work_dir_hash(path: str, kaos: str = "local") -> str:
- h = md5(path.encode("utf-8")).hexdigest()
- return h if kaos == "local" else f"{kaos}_{h}"
-
-
-def dir_total_size(d: Path) -> int:
- return sum(f.stat().st_size for f in d.rglob("*") if f.is_file())
-
-
-def main() -> None:
- parser = argparse.ArgumentParser(
- description=__doc__,
- formatter_class=argparse.RawDescriptionHelpFormatter,
- )
- parser.add_argument("--apply", action="store_true", help="Actually delete (default is dry-run)")
+def main() -> int:
+ parser = argparse.ArgumentParser(description="Validate kimi-cli dependency versions.")
+ parser.add_argument("--root-pyproject", type=Path, required=True)
+ parser.add_argument("--kosong-pyproject", type=Path, required=True)
+ parser.add_argument("--pykaos-pyproject", type=Path, required=True)
args = parser.parse_args()
- if not METADATA_FILE.exists():
- print(f"Metadata file not found: {METADATA_FILE}")
- sys.exit(1)
-
- with open(METADATA_FILE, encoding="utf-8") as f:
- metadata = json.load(f)
+ try:
+ root_project = load_project_table(args.root_pyproject)
+ except ValueError as exc:
+ print(f"error: {exc}", file=sys.stderr)
+ return 1
- work_dirs: list[dict] = metadata.get("work_dirs", [])
+ deps = root_project.get("dependencies", [])
+ if not isinstance(deps, list):
+ print(
+ f"error: project.dependencies must be a list in {args.root_pyproject}",
+ file=sys.stderr,
+ )
+ return 1
- # --- Phase 1: tmp entries in kimi.json ---
- tmp_entries: list[dict] = []
- keep_entries: list[dict] = []
- keep_hashes: set[str] = set()
+ errors: list[str] = []
+ for name, pyproject_path in (
+ ("kosong", args.kosong_pyproject),
+ ("pykaos", args.pykaos_pyproject),
+ ):
+ try:
+ package_version = load_project_version(pyproject_path)
+ except ValueError as exc:
+ errors.append(str(exc))
```
This function is important because it defines how Kimi CLI Tutorial: Multi-Mode Terminal Agent with MCP and ACP implements the patterns covered in this chapter.
@@ -170,9 +168,9 @@ This function is important because it defines how Kimi CLI Tutorial: Multi-Mode
```mermaid
flowchart TD
- A[main]
- B[is_tmp_path]
- C[work_dir_hash]
+ A[load_project_version]
+ B[find_pinned_dependency]
+ C[main]
A --> B
B --> C
```
diff --git a/tutorials/kimi-cli-tutorial/04-mcp-tooling-and-security-model.md b/tutorials/kimi-cli-tutorial/04-mcp-tooling-and-security-model.md
index 42f6d809..d7c3c8e0 100644
--- a/tutorials/kimi-cli-tutorial/04-mcp-tooling-and-security-model.md
+++ b/tutorials/kimi-cli-tutorial/04-mcp-tooling-and-security-model.md
@@ -39,129 +39,127 @@ You now know how to add MCP capabilities while preserving operator control.
Next: [Chapter 5: ACP and IDE Integrations](05-acp-and-ide-integrations.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `scripts/cleanup_tmp_sessions.py`
+### `scripts/check_version_tag.py`
-The `dir_total_size` function in [`scripts/cleanup_tmp_sessions.py`](https://github.com/MoonshotAI/kimi-cli/blob/HEAD/scripts/cleanup_tmp_sessions.py) handles a key part of this chapter's functionality:
+The `load_project_version` function in [`scripts/check_version_tag.py`](https://github.com/MoonshotAI/kimi-cli/blob/HEAD/scripts/check_version_tag.py) handles a key part of this chapter's functionality:
```py
-def dir_total_size(d: Path) -> int:
- return sum(f.stat().st_size for f in d.rglob("*") if f.is_file())
+def load_project_version(pyproject_path: Path) -> str:
+ with pyproject_path.open("rb") as handle:
+ data = tomllib.load(handle)
+ project = data.get("project")
+ if not isinstance(project, dict):
+ raise ValueError(f"Missing [project] table in {pyproject_path}")
-def main() -> None:
- parser = argparse.ArgumentParser(
- description=__doc__,
- formatter_class=argparse.RawDescriptionHelpFormatter,
- )
- parser.add_argument("--apply", action="store_true", help="Actually delete (default is dry-run)")
- args = parser.parse_args()
+ version = project.get("version")
+ if not isinstance(version, str) or not version:
+ raise ValueError(f"Missing project.version in {pyproject_path}")
+
+ return version
- if not METADATA_FILE.exists():
- print(f"Metadata file not found: {METADATA_FILE}")
- sys.exit(1)
- with open(METADATA_FILE, encoding="utf-8") as f:
- metadata = json.load(f)
+def main() -> int:
+ parser = argparse.ArgumentParser(description="Validate tag version against pyproject.")
+ parser.add_argument("--pyproject", type=Path, required=True)
+ parser.add_argument("--expected-version", required=True)
+ args = parser.parse_args()
- work_dirs: list[dict] = metadata.get("work_dirs", [])
+ semver_re = re.compile(r"^\d+\.\d+\.\d+$")
+ if not semver_re.match(args.expected_version):
+ print(
+ f"error: expected version must include patch (x.y.z): {args.expected_version}",
+ file=sys.stderr,
+ )
+ return 1
- # --- Phase 1: tmp entries in kimi.json ---
- tmp_entries: list[dict] = []
- keep_entries: list[dict] = []
- keep_hashes: set[str] = set()
- for wd in work_dirs:
- if is_tmp_path(wd.get("path", "")):
- tmp_entries.append(wd)
- else:
- keep_entries.append(wd)
+ try:
```
This function is important because it defines how Kimi CLI Tutorial: Multi-Mode Terminal Agent with MCP and ACP implements the patterns covered in this chapter.
-### `scripts/cleanup_tmp_sessions.py`
+### `scripts/check_version_tag.py`
-The `main` function in [`scripts/cleanup_tmp_sessions.py`](https://github.com/MoonshotAI/kimi-cli/blob/HEAD/scripts/cleanup_tmp_sessions.py) handles a key part of this chapter's functionality:
+The `main` function in [`scripts/check_version_tag.py`](https://github.com/MoonshotAI/kimi-cli/blob/HEAD/scripts/check_version_tag.py) handles a key part of this chapter's functionality:
```py
-def main() -> None:
- parser = argparse.ArgumentParser(
- description=__doc__,
- formatter_class=argparse.RawDescriptionHelpFormatter,
- )
- parser.add_argument("--apply", action="store_true", help="Actually delete (default is dry-run)")
+def main() -> int:
+ parser = argparse.ArgumentParser(description="Validate tag version against pyproject.")
+ parser.add_argument("--pyproject", type=Path, required=True)
+ parser.add_argument("--expected-version", required=True)
args = parser.parse_args()
- if not METADATA_FILE.exists():
- print(f"Metadata file not found: {METADATA_FILE}")
- sys.exit(1)
-
- with open(METADATA_FILE, encoding="utf-8") as f:
- metadata = json.load(f)
-
- work_dirs: list[dict] = metadata.get("work_dirs", [])
-
- # --- Phase 1: tmp entries in kimi.json ---
- tmp_entries: list[dict] = []
- keep_entries: list[dict] = []
- keep_hashes: set[str] = set()
- for wd in work_dirs:
- if is_tmp_path(wd.get("path", "")):
- tmp_entries.append(wd)
- else:
- keep_entries.append(wd)
- keep_hashes.add(work_dir_hash(wd["path"], wd.get("kaos", "local")))
-
- tmp_dirs: list[Path] = []
- for wd in tmp_entries:
+ semver_re = re.compile(r"^\d+\.\d+\.\d+$")
+ if not semver_re.match(args.expected_version):
+ print(
+ f"error: expected version must include patch (x.y.z): {args.expected_version}",
+ file=sys.stderr,
+ )
+ return 1
+
+ try:
+ project_version = load_project_version(args.pyproject)
+ except ValueError as exc:
+ print(f"error: {exc}", file=sys.stderr)
+ return 1
+
+ if not semver_re.match(project_version):
+ print(
+ "error: project version must include patch (x.y.z): "
+ f"{args.pyproject} has {project_version}",
+ file=sys.stderr,
+ )
+ return 1
+
+ if project_version != args.expected_version:
+ print(
```
This function is important because it defines how Kimi CLI Tutorial: Multi-Mode Terminal Agent with MCP and ACP implements the patterns covered in this chapter.
-### `web/src/App.tsx`
+### `vis/src/App.tsx`
-The `getSessionIdFromUrl` function in [`web/src/App.tsx`](https://github.com/MoonshotAI/kimi-cli/blob/HEAD/web/src/App.tsx) handles a key part of this chapter's functionality:
+The `computeStats` function in [`vis/src/App.tsx`](https://github.com/MoonshotAI/kimi-cli/blob/HEAD/vis/src/App.tsx) handles a key part of this chapter's functionality:
```tsx
- * Get session ID from URL search params
- */
-function getSessionIdFromUrl(): string | null {
- const params = new URLSearchParams(window.location.search);
- return params.get("session");
-}
-
-/**
- * Update URL with session ID without triggering page reload
- */
-function updateUrlWithSession(sessionId: string | null): void {
- const url = new URL(window.location.href);
- if (sessionId) {
- url.searchParams.set("session", sessionId);
- } else {
- url.searchParams.delete("session");
- }
- window.history.replaceState({}, "", url.toString());
}
-const SIDEBAR_COLLAPSED_SIZE = 48;
-const SIDEBAR_MIN_SIZE = 200;
-const SIDEBAR_DEFAULT_SIZE = 260;
-const SIDEBAR_ANIMATION_MS = 250;
-
-function App() {
- // Initialize theme on app startup
- useTheme();
-
- const sidebarElementRef = useRef<HTMLDivElement | null>(null);
- const sidebarPanelRef = useRef<PanelImperativeHandle | null>(null);
- const sessionsHook = useSessions();
+function computeStats(events: WireEvent[]): SessionStatsData {
+ let turns = 0;
+ let steps = 0;
+ let toolCalls = 0;
+ let errors = 0;
+ let compactions = 0;
+ let inputTokens = 0;
+ let outputTokens = 0;
+ let totalCacheRead = 0;
+ let totalInputOther = 0;
+ let totalCacheCreation = 0;
+
+ for (const e of events) {
+ if (e.type === "TurnBegin") turns++;
+ if (e.type === "StepBegin") steps++;
+ if (e.type === "ToolCall") toolCalls++;
+ if (e.type === "CompactionBegin") compactions++;
+ if (isErrorEvent(e)) errors++;
+ if (e.type === "StatusUpdate") {
+ const tu = e.payload.token_usage as Record<string, number> | undefined;
+ if (tu) {
+ inputTokens += (tu.input_other ?? 0) + (tu.input_cache_read ?? 0) + (tu.input_cache_creation ?? 0);
+ outputTokens += tu.output ?? 0;
+ totalCacheRead += tu.input_cache_read ?? 0;
+ totalInputOther += tu.input_other ?? 0;
+ totalCacheCreation += tu.input_cache_creation ?? 0;
+ }
+ }
+ // Count tokens from SubagentEvent-wrapped StatusUpdate
+ if (e.type === "SubagentEvent") {
```
This function is important because it defines how Kimi CLI Tutorial: Multi-Mode Terminal Agent with MCP and ACP implements the patterns covered in this chapter.
@@ -171,9 +169,9 @@ This function is important because it defines how Kimi CLI Tutorial: Multi-Mode
```mermaid
flowchart TD
- A[dir_total_size]
+ A[load_project_version]
B[main]
- C[getSessionIdFromUrl]
+ C[computeStats]
A --> B
B --> C
```
diff --git a/tutorials/kimi-cli-tutorial/05-acp-and-ide-integrations.md b/tutorials/kimi-cli-tutorial/05-acp-and-ide-integrations.md
index d2d28d0d..482159eb 100644
--- a/tutorials/kimi-cli-tutorial/05-acp-and-ide-integrations.md
+++ b/tutorials/kimi-cli-tutorial/05-acp-and-ide-integrations.md
@@ -42,141 +42,139 @@ You now have a pathway to use Kimi beyond standalone terminal sessions.
Next: [Chapter 6: Shell Mode, Print Mode, and Wire Mode](06-shell-mode-print-mode-and-wire-mode.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `web/src/App.tsx`
+### `vis/src/App.tsx`
-The `updateUrlWithSession` function in [`web/src/App.tsx`](https://github.com/MoonshotAI/kimi-cli/blob/HEAD/web/src/App.tsx) handles a key part of this chapter's functionality:
+The `formatDuration` function in [`vis/src/App.tsx`](https://github.com/MoonshotAI/kimi-cli/blob/HEAD/vis/src/App.tsx) handles a key part of this chapter's functionality:
```tsx
- * Update URL with session ID without triggering page reload
- */
-function updateUrlWithSession(sessionId: string | null): void {
- const url = new URL(window.location.href);
- if (sessionId) {
- url.searchParams.set("session", sessionId);
- } else {
- url.searchParams.delete("session");
- }
- window.history.replaceState({}, "", url.toString());
}
-const SIDEBAR_COLLAPSED_SIZE = 48;
-const SIDEBAR_MIN_SIZE = 200;
-const SIDEBAR_DEFAULT_SIZE = 260;
-const SIDEBAR_ANIMATION_MS = 250;
-
-function App() {
- // Initialize theme on app startup
- useTheme();
-
- const sidebarElementRef = useRef<HTMLDivElement | null>(null);
- const sidebarPanelRef = useRef<PanelImperativeHandle | null>(null);
- const sessionsHook = useSessions();
- const [isMobileSidebarOpen, setIsMobileSidebarOpen] = useState(false);
- const [isDesktop, setIsDesktop] = useState(() => {
- if (typeof window === "undefined") {
- return true;
- }
- return window.matchMedia("(min-width: 1024px)").matches;
- });
+function formatDuration(sec: number): string {
+ if (sec < 1) return `${(sec * 1000).toFixed(0)}ms`;
+ if (sec < 60) return `${sec.toFixed(1)}s`;
+ return `${(sec / 60).toFixed(1)}min`;
+}
+
+function formatTokens(n: number): string {
+ if (n === 0) return "0";
+ if (n < 1000) return `${n}`;
+ return `${(n / 1000).toFixed(1)}k`;
+}
+
+function getSessionDir(session: SessionInfo): string {
+ return session.session_dir;
+}
+function SessionDirectoryActions({
+ session,
+ openInSupported,
+}: {
+ session: SessionInfo;
+ openInSupported: boolean;
+}) {
+ const [copied, setCopied] = useState(false);
+
+ const handleOpenSessionDir = useCallback(async () => {
+ try {
+ await openInPath("finder", session.session_dir);
+ } catch (error) {
+ console.error("Failed to open session directory:", error);
```
This function is important because it defines how Kimi CLI Tutorial: Multi-Mode Terminal Agent with MCP and ACP implements the patterns covered in this chapter.
-### `web/src/App.tsx`
+### `vis/src/App.tsx`
-The `App` function in [`web/src/App.tsx`](https://github.com/MoonshotAI/kimi-cli/blob/HEAD/web/src/App.tsx) handles a key part of this chapter's functionality:
+The `formatTokens` function in [`vis/src/App.tsx`](https://github.com/MoonshotAI/kimi-cli/blob/HEAD/vis/src/App.tsx) handles a key part of this chapter's functionality:
```tsx
-const SIDEBAR_ANIMATION_MS = 250;
-
-function App() {
- // Initialize theme on app startup
- useTheme();
-
- const sidebarElementRef = useRef<HTMLDivElement | null>(null);
- const sidebarPanelRef = useRef<PanelImperativeHandle | null>(null);
- const sessionsHook = useSessions();
- const [isMobileSidebarOpen, setIsMobileSidebarOpen] = useState(false);
- const [isDesktop, setIsDesktop] = useState(() => {
- if (typeof window === "undefined") {
- return true;
- }
- return window.matchMedia("(min-width: 1024px)").matches;
- });
-
- const {
- sessions,
- archivedSessions,
- selectedSessionId,
- createSession,
- deleteSession,
- selectSession,
- uploadSessionFile,
- getSessionFile,
- getSessionFileUrl,
- listSessionDirectory,
- refreshSession,
- refreshSessions,
- refreshArchivedSessions,
- loadMoreSessions,
-```
-
-This function is important because it defines how Kimi CLI Tutorial: Multi-Mode Terminal Agent with MCP and ACP implements the patterns covered in this chapter.
-
-### `examples/kimi-psql/main.py`
+}
-The `ExecuteSqlParams` class in [`examples/kimi-psql/main.py`](https://github.com/MoonshotAI/kimi-cli/blob/HEAD/examples/kimi-psql/main.py) handles a key part of this chapter's functionality:
+function formatTokens(n: number): string {
+ if (n === 0) return "0";
+ if (n < 1000) return `${n}`;
+ return `${(n / 1000).toFixed(1)}k`;
+}
-```py
+function getSessionDir(session: SessionInfo): string {
+ return session.session_dir;
+}
+function SessionDirectoryActions({
+ session,
+ openInSupported,
+}: {
+ session: SessionInfo;
+ openInSupported: boolean;
+}) {
+ const [copied, setCopied] = useState(false);
+
+ const handleOpenSessionDir = useCallback(async () => {
+ try {
+ await openInPath("finder", session.session_dir);
+ } catch (error) {
+ console.error("Failed to open session directory:", error);
+ window.alert(
+ error instanceof Error
+ ? `Failed to open session directory:\n${error.message}`
+ : "Failed to open session directory",
+ );
+ }
+```
-class ExecuteSqlParams(BaseModel):
- """Parameters for ExecuteSql tool."""
+This function is important because it defines how Kimi CLI Tutorial: Multi-Mode Terminal Agent with MCP and ACP implements the patterns covered in this chapter.
- sql: str = Field(description="The SQL query to execute in the connected PostgreSQL database")
+### `vis/src/App.tsx`
+The `getSessionDir` function in [`vis/src/App.tsx`](https://github.com/MoonshotAI/kimi-cli/blob/HEAD/vis/src/App.tsx) handles a key part of this chapter's functionality:
-class ExecuteSql(CallableTool2[ExecuteSqlParams]):
- """Execute read-only SQL query in the connected PostgreSQL database."""
+```tsx
+}
- name: str = "ExecuteSql"
- description: str = (
- "Execute a READ-ONLY SQL query in the connected PostgreSQL database. "
- "Use this tool for SELECT queries and database introspection queries. "
- "This tool CANNOT execute write operations (INSERT, UPDATE, DELETE, DROP, etc.). "
- "For write operations, return the SQL in a markdown code block for the user to "
- "execute manually. "
- "Note: psql meta-commands (\\d, \\dt, etc.) are NOT supported - use SQL queries "
- "instead (e.g., SELECT * FROM pg_tables WHERE schemaname = 'public')."
- )
- params: type[ExecuteSqlParams] = ExecuteSqlParams
+function getSessionDir(session: SessionInfo): string {
+ return session.session_dir;
+}
- def __init__(self, conninfo: str):
- """
- Initialize ExecuteSql tool with database connection info.
+function SessionDirectoryActions({
+ session,
+ openInSupported,
+}: {
+ session: SessionInfo;
+ openInSupported: boolean;
+}) {
+ const [copied, setCopied] = useState(false);
+
+ const handleOpenSessionDir = useCallback(async () => {
+ try {
+ await openInPath("finder", session.session_dir);
+ } catch (error) {
+ console.error("Failed to open session directory:", error);
+ window.alert(
+ error instanceof Error
+ ? `Failed to open session directory:\n${error.message}`
+ : "Failed to open session directory",
+ );
+ }
+ }, [session.session_dir]);
- Args:
- conninfo: PostgreSQL connection string
- (e.g., "host=localhost port=5432 dbname=mydb user=postgres")
- """
- super().__init__()
+ const handleCopyDirInfo = useCallback(async () => {
+ try {
+ await navigator.clipboard.writeText(getSessionDir(session));
+ setCopied(true);
```
-This class is important because it defines how Kimi CLI Tutorial: Multi-Mode Terminal Agent with MCP and ACP implements the patterns covered in this chapter.
+This function is important because it defines how Kimi CLI Tutorial: Multi-Mode Terminal Agent with MCP and ACP implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[updateUrlWithSession]
- B[App]
- C[ExecuteSqlParams]
+ A[formatDuration]
+ B[formatTokens]
+ C[getSessionDir]
A --> B
B --> C
```
diff --git a/tutorials/kimi-cli-tutorial/06-shell-mode-print-mode-and-wire-mode.md b/tutorials/kimi-cli-tutorial/06-shell-mode-print-mode-and-wire-mode.md
index bc981cff..27ddf481 100644
--- a/tutorials/kimi-cli-tutorial/06-shell-mode-print-mode-and-wire-mode.md
+++ b/tutorials/kimi-cli-tutorial/06-shell-mode-print-mode-and-wire-mode.md
@@ -38,141 +38,139 @@ You now know when to use interactive mode versus automation/protocol modes.
Next: [Chapter 7: Loop Control, Retries, and Long Tasks](07-loop-control-retries-and-long-tasks.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `examples/kimi-psql/main.py`
-
-The `ExecuteSql` class in [`examples/kimi-psql/main.py`](https://github.com/MoonshotAI/kimi-cli/blob/HEAD/examples/kimi-psql/main.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-class ExecuteSqlParams(BaseModel):
- """Parameters for ExecuteSql tool."""
-
- sql: str = Field(description="The SQL query to execute in the connected PostgreSQL database")
-
-
-class ExecuteSql(CallableTool2[ExecuteSqlParams]):
- """Execute read-only SQL query in the connected PostgreSQL database."""
-
- name: str = "ExecuteSql"
- description: str = (
- "Execute a READ-ONLY SQL query in the connected PostgreSQL database. "
- "Use this tool for SELECT queries and database introspection queries. "
- "This tool CANNOT execute write operations (INSERT, UPDATE, DELETE, DROP, etc.). "
- "For write operations, return the SQL in a markdown code block for the user to "
- "execute manually. "
- "Note: psql meta-commands (\\d, \\dt, etc.) are NOT supported - use SQL queries "
- "instead (e.g., SELECT * FROM pg_tables WHERE schemaname = 'public')."
- )
- params: type[ExecuteSqlParams] = ExecuteSqlParams
-
- def __init__(self, conninfo: str):
- """
- Initialize ExecuteSql tool with database connection info.
-
- Args:
- conninfo: PostgreSQL connection string
- (e.g., "host=localhost port=5432 dbname=mydb user=postgres")
- """
- super().__init__()
+### `vis/src/App.tsx`
+
+The `SessionDirectoryActions` function in [`vis/src/App.tsx`](https://github.com/MoonshotAI/kimi-cli/blob/HEAD/vis/src/App.tsx) handles a key part of this chapter's functionality:
+
+```tsx
+}
+
+function SessionDirectoryActions({
+ session,
+ openInSupported,
+}: {
+ session: SessionInfo;
+ openInSupported: boolean;
+}) {
+ const [copied, setCopied] = useState(false);
+
+ const handleOpenSessionDir = useCallback(async () => {
+ try {
+ await openInPath("finder", session.session_dir);
+ } catch (error) {
+ console.error("Failed to open session directory:", error);
+ window.alert(
+ error instanceof Error
+ ? `Failed to open session directory:\n${error.message}`
+ : "Failed to open session directory",
+ );
+ }
+ }, [session.session_dir]);
+
+ const handleCopyDirInfo = useCallback(async () => {
+ try {
+ await navigator.clipboard.writeText(getSessionDir(session));
+ setCopied(true);
+ setTimeout(() => setCopied(false), 2000);
+ } catch (error) {
+ console.error("Failed to copy DIR info:", error);
+ window.alert("Failed to copy DIR info");
```
-This class is important because it defines how Kimi CLI Tutorial: Multi-Mode Terminal Agent with MCP and ACP implements the patterns covered in this chapter.
-
-### `examples/kimi-psql/main.py`
-
-The `PsqlProcess` class in [`examples/kimi-psql/main.py`](https://github.com/MoonshotAI/kimi-cli/blob/HEAD/examples/kimi-psql/main.py) handles a key part of this chapter's functionality:
-
-```py
-
-# ============================================================================
-# PsqlProcess: PTY-based psql subprocess management
-# ============================================================================
-
-
-class PsqlProcess:
- """Manages a psql subprocess with PTY support for full interactive experience."""
-
- def __init__(self, psql_args: list[str]):
- self.psql_args = psql_args
- self._master_fd: int | None = None
- self._pid: int | None = None
- self._running = False
- self._original_termios: list | None = None
-
- def start(self) -> None:
- """Spawn psql in a pseudo-terminal."""
- # Save original terminal settings
- if sys.stdin.isatty():
- self._original_termios = termios.tcgetattr(sys.stdin)
-
- pid, master_fd = pty.fork()
-
- if pid == 0:
- # Child process: exec psql
- os.execvp("psql", self.psql_args)
- else:
- # Parent process
- self._pid = pid
- self._master_fd = master_fd
- self._running = True
+This function is important because it defines how Kimi CLI Tutorial: Multi-Mode Terminal Agent with MCP and ACP implements the patterns covered in this chapter.
+
+### `vis/src/App.tsx`
+
+The `SessionStats` function in [`vis/src/App.tsx`](https://github.com/MoonshotAI/kimi-cli/blob/HEAD/vis/src/App.tsx) handles a key part of this chapter's functionality:
+
+```tsx
+type Tab = "wire" | "context" | "state" | "dual" | "agents";
+
+interface SessionStatsData {
+ turns: number;
+ steps: number;
+ toolCalls: number;
+ errors: number;
+ compactions: number;
+ durationSec: number;
+ inputTokens: number;
+ outputTokens: number;
+ cacheRate: number;
+}
+
+function computeStats(events: WireEvent[]): SessionStatsData {
+ let turns = 0;
+ let steps = 0;
+ let toolCalls = 0;
+ let errors = 0;
+ let compactions = 0;
+ let inputTokens = 0;
+ let outputTokens = 0;
+ let totalCacheRead = 0;
+ let totalInputOther = 0;
+ let totalCacheCreation = 0;
+
+ for (const e of events) {
+ if (e.type === "TurnBegin") turns++;
+ if (e.type === "StepBegin") steps++;
+ if (e.type === "ToolCall") toolCalls++;
+ if (e.type === "CompactionBegin") compactions++;
+ if (isErrorEvent(e)) errors++;
```
-This class is important because it defines how Kimi CLI Tutorial: Multi-Mode Terminal Agent with MCP and ACP implements the patterns covered in this chapter.
-
-### `examples/kimi-psql/main.py`
-
-The `PsqlMode` class in [`examples/kimi-psql/main.py`](https://github.com/MoonshotAI/kimi-cli/blob/HEAD/examples/kimi-psql/main.py) handles a key part of this chapter's functionality:
-
-```py
-
-# ============================================================================
-# PsqlMode: Operation mode enumeration
-# ============================================================================
-
-
-class PsqlMode(Enum):
- AI = "ai" # AI assistance mode (default)
- PSQL = "psql" # Direct psql interaction
-
- def toggle(self) -> "PsqlMode":
- return PsqlMode.PSQL if self == PsqlMode.AI else PsqlMode.AI
-
-
-# ============================================================================
-# PsqlSoul: SQL generation specialized Soul
-# ============================================================================
-
-
-async def create_psql_soul(llm: LLM | None, conninfo: str) -> KimiSoul:
- """Create a KimiSoul configured for PostgreSQL with ExecuteSql tool
- and standard kimi-cli tools."""
- from typing import cast
-
- from kimi_cli.config import load_config
- from kimi_cli.soul.agent import load_agent
- from kimi_cli.soul.toolset import KimiToolset
-
- config = load_config()
- kaos_work_dir = KaosPath.cwd()
- session = await Session.create(kaos_work_dir)
- runtime = await Runtime.create(
+This function is important because it defines how Kimi CLI Tutorial: Multi-Mode Terminal Agent with MCP and ACP implements the patterns covered in this chapter.
+
+### `vis/src/App.tsx`
+
+The `ShortcutRow` function in [`vis/src/App.tsx`](https://github.com/MoonshotAI/kimi-cli/blob/HEAD/vis/src/App.tsx) handles a key part of this chapter's functionality:
+
+```tsx
+}
+
+function ShortcutRow({ keys, desc }: { keys: string; desc: string }) {
+ return (
+ <div className="flex items-center gap-3">
+ <kbd className="inline-flex min-w-[2rem] items-center justify-center rounded border bg-muted px-1.5 py-0.5 font-mono text-xs">
+ {keys}
+ </kbd>
+ <span className="text-muted-foreground">{desc}</span>
+ </div>
+ );
+}
+
+export function App() {
+ const { theme, toggleTheme } = useTheme();
+ const [sessionId, setSessionId] = useState<string | null>(() => {
+ const params = new URLSearchParams(window.location.search);
+ return params.get("session");
+ });
+ const [activeTab, setActiveTab] = useState<Tab>("wire");
+ const [explorerView, setExplorerView] = useState<"sessions" | "statistics">("sessions");
+ const [showShortcutHelp, setShowShortcutHelp] = useState(false);
+ const [refreshKey, setRefreshKey] = useState(0);
+ const [refreshing, setRefreshing] = useState(false);
+ const [openInSupported, setOpenInSupported] = useState(false);
+ // Agent scope: null = main agent, string = sub-agent ID
+ const [agentScope, setAgentScope] = useState<string | null>(null);
+ // Cross-reference navigation targets
+ const [contextScrollTarget, setContextScrollTarget] = useState<string | null>(null);
+ const [wireScrollTarget, setWireScrollTarget] = useState<string | null>(null);
+
+ const handleNavigateToContext = useCallback((toolCallId: string) => {
```
-This class is important because it defines how Kimi CLI Tutorial: Multi-Mode Terminal Agent with MCP and ACP implements the patterns covered in this chapter.
+This function is important because it defines how Kimi CLI Tutorial: Multi-Mode Terminal Agent with MCP and ACP implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[ExecuteSql]
- B[PsqlProcess]
- C[PsqlMode]
+ A[SessionDirectoryActions]
+ B[SessionStats]
+ C[ShortcutRow]
A --> B
B --> C
```
diff --git a/tutorials/kimi-cli-tutorial/07-loop-control-retries-and-long-tasks.md b/tutorials/kimi-cli-tutorial/07-loop-control-retries-and-long-tasks.md
index 60ef42ea..7073b1d0 100644
--- a/tutorials/kimi-cli-tutorial/07-loop-control-retries-and-long-tasks.md
+++ b/tutorials/kimi-cli-tutorial/07-loop-control-retries-and-long-tasks.md
@@ -38,141 +38,139 @@ You now have an execution-bounding strategy for larger autonomous task loops.
Next: [Chapter 8: Production Operations and Governance](08-production-operations-and-governance.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `examples/kimi-psql/main.py`
-
-The `PsqlShell` class in [`examples/kimi-psql/main.py`](https://github.com/MoonshotAI/kimi-cli/blob/HEAD/examples/kimi-psql/main.py) handles a key part of this chapter's functionality:
-
-```py
-
-# ============================================================================
-# PsqlShell: Main TUI orchestrator
-# ============================================================================
-
-
-class PsqlShell:
- """Main TUI orchestrator for kimi-psql."""
-
- PROMPT_SYMBOL_AI = "✨"
- PROMPT_SYMBOL_PSQL = "$"
-
- def __init__(self, soul: KimiSoul, psql_process: PsqlProcess):
- self.soul = soul
- self._psql_process = psql_process
- self._mode = PsqlMode.AI
- self._switch_requested = False
- self._prompt_session: PromptSession[str] | None = None
- self._psql_entered_before = False # Track if we've entered PSQL mode before
-
- def _create_prompt_session(self) -> PromptSession[str]:
- """Create a prompt_toolkit session with Ctrl-X binding."""
- kb = KeyBindings()
-
- @kb.add("c-x", eager=True)
- def _(event) -> None:
- """Switch to PSQL mode on Ctrl-X."""
- self._switch_requested = True
- event.app.exit(result="")
-
- def get_prompt() -> FormattedText:
- symbol = self.PROMPT_SYMBOL_AI if self._mode == PsqlMode.AI else self.PROMPT_SYMBOL_PSQL
+### `vis/src/App.tsx`
+
+The `App` function in [`vis/src/App.tsx`](https://github.com/MoonshotAI/kimi-cli/blob/HEAD/vis/src/App.tsx) handles a key part of this chapter's functionality:
+
+```tsx
+}
+
+export function App() {
+ const { theme, toggleTheme } = useTheme();
+ const [sessionId, setSessionId] = useState<string | null>(() => {
+ const params = new URLSearchParams(window.location.search);
+ return params.get("session");
+ });
+ const [activeTab, setActiveTab] = useState<Tab>("wire");
+ const [explorerView, setExplorerView] = useState<"sessions" | "statistics">("sessions");
+ const [showShortcutHelp, setShowShortcutHelp] = useState(false);
+ const [refreshKey, setRefreshKey] = useState(0);
+ const [refreshing, setRefreshing] = useState(false);
+ const [openInSupported, setOpenInSupported] = useState(false);
+ // Agent scope: null = main agent, string = sub-agent ID
+ const [agentScope, setAgentScope] = useState<string | null>(null);
+ // Cross-reference navigation targets
+ const [contextScrollTarget, setContextScrollTarget] = useState<string | null>(null);
+ const [wireScrollTarget, setWireScrollTarget] = useState<string | null>(null);
+
+ const handleNavigateToContext = useCallback((toolCallId: string) => {
+ setContextScrollTarget(toolCallId);
+ setActiveTab("context");
+ }, []);
+
+ const handleNavigateToWire = useCallback((toolCallId: string) => {
+ setWireScrollTarget(toolCallId);
+ setActiveTab("wire");
+ }, []);
+
+ const handleSessionChange = useCallback((id: string | null) => {
+ setSessionId(id);
```
-This class is important because it defines how Kimi CLI Tutorial: Multi-Mode Terminal Agent with MCP and ACP implements the patterns covered in this chapter.
-
-### `examples/kimi-psql/main.py`
-
-The `create_psql_soul` function in [`examples/kimi-psql/main.py`](https://github.com/MoonshotAI/kimi-cli/blob/HEAD/examples/kimi-psql/main.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-async def create_psql_soul(llm: LLM | None, conninfo: str) -> KimiSoul:
- """Create a KimiSoul configured for PostgreSQL with ExecuteSql tool
- and standard kimi-cli tools."""
- from typing import cast
-
- from kimi_cli.config import load_config
- from kimi_cli.soul.agent import load_agent
- from kimi_cli.soul.toolset import KimiToolset
-
- config = load_config()
- kaos_work_dir = KaosPath.cwd()
- session = await Session.create(kaos_work_dir)
- runtime = await Runtime.create(
- config=config,
- oauth=OAuthManager(config),
- llm=llm,
- session=session,
- yolo=True, # Auto-approve read-only SQL queries
- )
-
- # Load agent from configuration
- agent_file = Path(__file__).parent / "agent.yaml"
- agent = await load_agent(agent_file, runtime, mcp_configs=[])
-
- # Add custom ExecuteSql tool to the loaded agent
- cast(KimiToolset, agent.toolset).add(ExecuteSql(conninfo))
-
- context = Context(session.context_file)
- return KimiSoul(agent, context=context)
+This function is important because it defines how Kimi CLI Tutorial: Multi-Mode Terminal Agent with MCP and ACP implements the patterns covered in this chapter.
+### `vis/src/App.tsx`
+
+The `SessionStatsData` interface in [`vis/src/App.tsx`](https://github.com/MoonshotAI/kimi-cli/blob/HEAD/vis/src/App.tsx) handles a key part of this chapter's functionality:
+
+```tsx
+type Tab = "wire" | "context" | "state" | "dual" | "agents";
+
+interface SessionStatsData {
+ turns: number;
+ steps: number;
+ toolCalls: number;
+ errors: number;
+ compactions: number;
+ durationSec: number;
+ inputTokens: number;
+ outputTokens: number;
+ cacheRate: number;
+}
+
+function computeStats(events: WireEvent[]): SessionStatsData {
+ let turns = 0;
+ let steps = 0;
+ let toolCalls = 0;
+ let errors = 0;
+ let compactions = 0;
+ let inputTokens = 0;
+ let outputTokens = 0;
+ let totalCacheRead = 0;
+ let totalInputOther = 0;
+ let totalCacheCreation = 0;
+
+ for (const e of events) {
+ if (e.type === "TurnBegin") turns++;
+ if (e.type === "StepBegin") steps++;
+ if (e.type === "ToolCall") toolCalls++;
+ if (e.type === "CompactionBegin") compactions++;
+ if (isErrorEvent(e)) errors++;
```
-This function is important because it defines how Kimi CLI Tutorial: Multi-Mode Terminal Agent with MCP and ACP implements the patterns covered in this chapter.
+This interface is important because it defines how Kimi CLI Tutorial: Multi-Mode Terminal Agent with MCP and ACP implements the patterns covered in this chapter.
-### `examples/kimi-psql/main.py`
+### `src/kimi_cli/app.py`
-The `main` function in [`examples/kimi-psql/main.py`](https://github.com/MoonshotAI/kimi-cli/blob/HEAD/examples/kimi-psql/main.py) handles a key part of this chapter's functionality:
+The `KimiCLI` class in [`src/kimi_cli/app.py`](https://github.com/MoonshotAI/kimi-cli/blob/HEAD/src/kimi_cli/app.py) handles a key part of this chapter's functionality:
```py
-Usage:
- uv run main.py -h localhost -p 5432 -U postgres -d mydb
-"""
-
-import asyncio
-import contextlib
-import fcntl
-import os
-import pty
-import select
-import signal
-import sys
-import termios
-import tty
-from enum import Enum
-from pathlib import Path
-from typing import LiteralString, cast
-
-import psycopg
-import typer
-from kaos.path import KaosPath
-from kosong.tooling import CallableTool2, ToolError, ToolOk, ToolReturnValue
-from prompt_toolkit import PromptSession
-from prompt_toolkit.formatted_text import FormattedText
-from prompt_toolkit.key_binding import KeyBindings
-from prompt_toolkit.patch_stdout import patch_stdout
-from pydantic import BaseModel, Field, SecretStr
-from rich.console import Console
-from rich.panel import Panel
-from rich.text import Text
+class KimiCLI:
+ @staticmethod
+ async def create(
+ session: Session,
+ *,
+ # Basic configuration
+ config: Config | Path | None = None,
+ model_name: str | None = None,
+ thinking: bool | None = None,
+ # Run mode
+ yolo: bool = False,
+ plan_mode: bool = False,
+ resumed: bool = False,
+ # Extensions
+ agent_file: Path | None = None,
+ mcp_configs: list[MCPConfig] | list[dict[str, Any]] | None = None,
+ skills_dirs: list[KaosPath] | None = None,
+ # Loop control
+ max_steps_per_turn: int | None = None,
+ max_retries_per_step: int | None = None,
+ max_ralph_iterations: int | None = None,
+ startup_progress: Callable[[str], None] | None = None,
+ defer_mcp_loading: bool = False,
+ ) -> KimiCLI:
+ """
+ Create a KimiCLI instance.
+
+ Args:
+ session (Session): A session created by `Session.create` or `Session.continue_`.
+ config (Config | Path | None, optional): Configuration to use, or path to config file.
```
-This function is important because it defines how Kimi CLI Tutorial: Multi-Mode Terminal Agent with MCP and ACP implements the patterns covered in this chapter.
+This class is important because it defines how Kimi CLI Tutorial: Multi-Mode Terminal Agent with MCP and ACP implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[PsqlShell]
- B[create_psql_soul]
- C[main]
+ A[App]
+ B[SessionStatsData]
+ C[KimiCLI]
A --> B
B --> C
```
diff --git a/tutorials/kimi-cli-tutorial/08-production-operations-and-governance.md b/tutorials/kimi-cli-tutorial/08-production-operations-and-governance.md
index 23886ce2..a42d5bf7 100644
--- a/tutorials/kimi-cli-tutorial/08-production-operations-and-governance.md
+++ b/tutorials/kimi-cli-tutorial/08-production-operations-and-governance.md
@@ -37,141 +37,139 @@ Team-scale Kimi usage needs clear policy around approvals, skills, integrations,
You now have a production-ready operating framework for Kimi CLI across developer teams.
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `examples/kimi-psql/main.py`
+### `src/kimi_cli/app.py`
-The `import` interface in [`examples/kimi-psql/main.py`](https://github.com/MoonshotAI/kimi-cli/blob/HEAD/examples/kimi-psql/main.py) handles a key part of this chapter's functionality:
+The `enable_logging` function in [`src/kimi_cli/app.py`](https://github.com/MoonshotAI/kimi-cli/blob/HEAD/src/kimi_cli/app.py) handles a key part of this chapter's functionality:
```py
-"""
-
-import asyncio
-import contextlib
-import fcntl
-import os
-import pty
-import select
-import signal
-import sys
-import termios
-import tty
-from enum import Enum
-from pathlib import Path
-from typing import LiteralString, cast
-
-import psycopg
-import typer
-from kaos.path import KaosPath
-from kosong.tooling import CallableTool2, ToolError, ToolOk, ToolReturnValue
-from prompt_toolkit import PromptSession
-from prompt_toolkit.formatted_text import FormattedText
-from prompt_toolkit.key_binding import KeyBindings
-from prompt_toolkit.patch_stdout import patch_stdout
-from pydantic import BaseModel, Field, SecretStr
-from rich.console import Console
-from rich.panel import Panel
-from rich.text import Text
-
-from kimi_cli.auth.oauth import OAuthManager
-from kimi_cli.config import LLMModel, LLMProvider
-from kimi_cli.llm import LLM, create_llm
-```
-This interface is important because it defines how Kimi CLI Tutorial: Multi-Mode Terminal Agent with MCP and ACP implements the patterns covered in this chapter.
-
-### `vis/src/App.tsx`
-
-The `computeStats` function in [`vis/src/App.tsx`](https://github.com/MoonshotAI/kimi-cli/blob/HEAD/vis/src/App.tsx) handles a key part of this chapter's functionality:
-
-```tsx
-}
-
-function computeStats(events: WireEvent[]): SessionStatsData {
- let turns = 0;
- let steps = 0;
- let toolCalls = 0;
- let errors = 0;
- let compactions = 0;
- let inputTokens = 0;
- let outputTokens = 0;
-
- for (const e of events) {
- if (e.type === "TurnBegin") turns++;
- if (e.type === "StepBegin") steps++;
- if (e.type === "ToolCall") toolCalls++;
- if (e.type === "CompactionBegin") compactions++;
- if (isErrorEvent(e)) errors++;
- if (e.type === "StatusUpdate") {
- const tu = e.payload.token_usage as Record<string, number> | undefined;
- if (tu) {
- inputTokens += (tu.input_other ?? 0) + (tu.input_cache_read ?? 0) + (tu.input_cache_creation ?? 0);
- outputTokens += tu.output ?? 0;
- }
- }
- }
-
- const durationSec =
- events.length >= 2
- ? events[events.length - 1].timestamp - events[0].timestamp
- : 0;
-
- return { turns, steps, toolCalls, errors, compactions, durationSec, inputTokens, outputTokens };
+
+def enable_logging(debug: bool = False, *, redirect_stderr: bool = True) -> None:
+ # NOTE: stderr redirection is implemented by swapping the process-level fd=2 (dup2).
+ # That can hide Click/Typer error output during CLI startup, so some entrypoints delay
+ # installing it until after critical initialization succeeds.
+ logger.remove() # Remove default stderr handler
+ logger.enable("kimi_cli")
+ if debug:
+ logger.enable("kosong")
+ logger.add(
+ get_share_dir() / "logs" / "kimi.log",
+ # FIXME: configure level for different modules
+ level="TRACE" if debug else "INFO",
+ rotation="06:00",
+ retention="10 days",
+ )
+ if redirect_stderr:
+ redirect_stderr_to_logger()
+
+
+def _cleanup_stale_foreground_subagents(runtime: Runtime) -> None:
+ subagent_store = getattr(runtime, "subagent_store", None)
+ if subagent_store is None:
+ return
+
+ stale_agent_ids = [
+ record.agent_id
+ for record in subagent_store.list_instances()
+ if record.status == "running_foreground"
+ ]
+ for agent_id in stale_agent_ids:
```
This function is important because it defines how Kimi CLI Tutorial: Multi-Mode Terminal Agent with MCP and ACP implements the patterns covered in this chapter.
-### `vis/src/App.tsx`
-
-The `formatDuration` function in [`vis/src/App.tsx`](https://github.com/MoonshotAI/kimi-cli/blob/HEAD/vis/src/App.tsx) handles a key part of this chapter's functionality:
-
-```tsx
-}
-
-function formatDuration(sec: number): string {
- if (sec < 1) return `${(sec * 1000).toFixed(0)}ms`;
- if (sec < 60) return `${sec.toFixed(1)}s`;
- return `${(sec / 60).toFixed(1)}min`;
-}
-
-function formatTokens(n: number): string {
- if (n === 0) return "0";
- if (n < 1000) return `${n}`;
- return `${(n / 1000).toFixed(1)}k`;
-}
-
-function getSessionDir(session: SessionInfo): string {
- return session.session_dir;
-}
-
-function SessionDirectoryActions({
- session,
- openInSupported,
-}: {
- session: SessionInfo;
- openInSupported: boolean;
-}) {
- const [copied, setCopied] = useState(false);
-
- const handleOpenSessionDir = useCallback(async () => {
- try {
- await openInPath("finder", session.session_dir);
- } catch (error) {
- console.error("Failed to open session directory:", error);
+### `examples/kimi-psql/main.py`
+
+The `ExecuteSqlParams` class in [`examples/kimi-psql/main.py`](https://github.com/MoonshotAI/kimi-cli/blob/HEAD/examples/kimi-psql/main.py) handles a key part of this chapter's functionality:
+
+```py
+
+
+class ExecuteSqlParams(BaseModel):
+ """Parameters for ExecuteSql tool."""
+
+ sql: str = Field(description="The SQL query to execute in the connected PostgreSQL database")
+
+
+class ExecuteSql(CallableTool2[ExecuteSqlParams]):
+ """Execute read-only SQL query in the connected PostgreSQL database."""
+
+ name: str = "ExecuteSql"
+ description: str = (
+ "Execute a READ-ONLY SQL query in the connected PostgreSQL database. "
+ "Use this tool for SELECT queries and database introspection queries. "
+ "This tool CANNOT execute write operations (INSERT, UPDATE, DELETE, DROP, etc.). "
+ "For write operations, return the SQL in a markdown code block for the user to "
+ "execute manually. "
+ "Note: psql meta-commands (\\d, \\dt, etc.) are NOT supported - use SQL queries "
+ "instead (e.g., SELECT * FROM pg_tables WHERE schemaname = 'public')."
+ )
+ params: type[ExecuteSqlParams] = ExecuteSqlParams
+
+ def __init__(self, conninfo: str):
+ """
+ Initialize ExecuteSql tool with database connection info.
+
+ Args:
+ conninfo: PostgreSQL connection string
+ (e.g., "host=localhost port=5432 dbname=mydb user=postgres")
+ """
+ super().__init__()
```
-This function is important because it defines how Kimi CLI Tutorial: Multi-Mode Terminal Agent with MCP and ACP implements the patterns covered in this chapter.
+This class is important because it defines how Kimi CLI Tutorial: Multi-Mode Terminal Agent with MCP and ACP implements the patterns covered in this chapter.
+
+### `examples/kimi-psql/main.py`
+
+The `ExecuteSql` class in [`examples/kimi-psql/main.py`](https://github.com/MoonshotAI/kimi-cli/blob/HEAD/examples/kimi-psql/main.py) handles a key part of this chapter's functionality:
+
+```py
+
+
+class ExecuteSqlParams(BaseModel):
+ """Parameters for ExecuteSql tool."""
+
+ sql: str = Field(description="The SQL query to execute in the connected PostgreSQL database")
+
+
+class ExecuteSql(CallableTool2[ExecuteSqlParams]):
+ """Execute read-only SQL query in the connected PostgreSQL database."""
+
+ name: str = "ExecuteSql"
+ description: str = (
+ "Execute a READ-ONLY SQL query in the connected PostgreSQL database. "
+ "Use this tool for SELECT queries and database introspection queries. "
+ "This tool CANNOT execute write operations (INSERT, UPDATE, DELETE, DROP, etc.). "
+ "For write operations, return the SQL in a markdown code block for the user to "
+ "execute manually. "
+ "Note: psql meta-commands (\\d, \\dt, etc.) are NOT supported - use SQL queries "
+ "instead (e.g., SELECT * FROM pg_tables WHERE schemaname = 'public')."
+ )
+ params: type[ExecuteSqlParams] = ExecuteSqlParams
+
+ def __init__(self, conninfo: str):
+ """
+ Initialize ExecuteSql tool with database connection info.
+
+ Args:
+ conninfo: PostgreSQL connection string
+ (e.g., "host=localhost port=5432 dbname=mydb user=postgres")
+ """
+ super().__init__()
+```
+
+This class is important because it defines how Kimi CLI Tutorial: Multi-Mode Terminal Agent with MCP and ACP implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[import]
- B[computeStats]
- C[formatDuration]
+ A[enable_logging]
+ B[ExecuteSqlParams]
+ C[ExecuteSql]
A --> B
B --> C
```
diff --git a/tutorials/kiro-tutorial/01-getting-started.md b/tutorials/kiro-tutorial/01-getting-started.md
index bb9a4dd6..931c01b6 100644
--- a/tutorials/kiro-tutorial/01-getting-started.md
+++ b/tutorials/kiro-tutorial/01-getting-started.md
@@ -5,6 +5,7 @@ nav_order: 1
parent: Kiro Tutorial
---
+
# Chapter 1: Getting Started
Welcome to **Chapter 1: Getting Started**. In this part of **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
@@ -108,473 +109,27 @@ Next: [Chapter 2: Spec-Driven Development Workflow](02-spec-driven-development-w
## Depth Expansion Playbook
-<!-- depth-expansion-v2 -->
-
-This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
-
-### Strategic Context
-
-- tutorial: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- tutorial slug: **kiro-tutorial**
-- chapter focus: **Chapter 1: Getting Started**
-- system context: **Kiro Tutorial**
-- objective: move from surface-level usage to repeatable engineering operation
-
-### Architecture Decomposition
-
-1. Define the runtime boundary for `Chapter 1: Getting Started` — Kiro process, auth layer, workspace indexer, and model API connection.
-2. Separate control-plane decisions (auth provider choice, workspace configuration) from data-plane execution (model inference, file reads).
-3. Capture input contracts: local filesystem path, user credentials, and workspace settings; output: indexed workspace and live chat session.
-4. Trace state transitions: unauthenticated → authenticated → workspace open → indexed → chat ready.
-5. Identify extension hooks: custom workspace settings, proxy configuration, and excluded-path policies.
-6. Map ownership boundaries: individual developer owns auth tokens; team owns shared workspace config and .kiro/ directory.
-7. Specify rollback paths: sign out and re-authenticate; reopen workspace to trigger re-indexing.
-8. Track observability signals: auth success/failure logs, indexing completion time, first-message latency.
-
-### Operator Decision Matrix
-
-| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
-|:--------------|:--------------|:------------------|:---------|
-| Auth provider | GitHub OAuth | AWS Builder ID with IAM | simplicity vs AWS identity integration |
-| Workspace size | small repo under 10k files | large monorepo with exclusion rules | speed vs completeness |
-| Network config | direct connection | proxy with allowlist for kiro.dev | ease vs enterprise security |
-| Rollout method | individual install | managed deploy via MDM or package manager | velocity vs governance |
-| Incident response | user self-service | IT helpdesk runbook + Kiro logs | cost vs reliability |
-
-### Failure Modes and Countermeasures
-
-| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
-|:-------------|:-------------|:-------------------|:---------------|
-| auth token expiry | 401 on chat requests | long-idle session without refresh | re-authenticate; check session TTL settings |
-| workspace index failure | empty context responses | large or excluded files | add explicit include patterns; reduce workspace scope |
-| proxy interference | connection timeout on model calls | corporate firewall blocking kiro.dev | add kiro.dev to proxy allowlist |
-| OS permission denial | Gatekeeper block on macOS | unsigned binary or quarantine flag | clear quarantine attribute: `xattr -d com.apple.quarantine Kiro.app` |
-| stale credentials | silent auth failures | AWS Builder ID token not refreshed | trigger manual re-auth from Kiro settings |
-| network latency spike | slow first-message response | CDN routing or model endpoint cold start | retry with smaller prompt; check Kiro status page |
-
-### Implementation Runbook
-
-1. Verify platform prerequisites: OS version meets Kiro minimum requirements.
-2. Download Kiro from the official kiro.dev release page and verify the checksum.
-3. Run the platform installer and complete any OS-level permission prompts.
-4. Launch Kiro and select an authentication provider.
-5. Complete the OAuth or device authorization flow and confirm the success screen.
-6. Open a local project folder with at least one source file to confirm workspace indexing.
-7. Send a test message in the Chat panel and verify a model response is returned.
-8. Check the Explorer panel for the `.kiro/` directory (created automatically on first use).
-9. Record the installed version and authentication provider for team onboarding documentation.
-
-### Quality Gate Checklist
-
-- [ ] Kiro launches without OS-level errors on the target platform
-- [ ] authentication flow completes and the Chat panel shows the user identity
-- [ ] workspace indexing completes within acceptable time for the repo size
-- [ ] first chat message returns a model response without timeout
-- [ ] `.kiro/` directory is visible in the Explorer panel
-- [ ] proxy and network configuration is documented for team members
-- [ ] rollback path (sign-out and re-authenticate) is verified and documented
-- [ ] installed version is recorded for future upgrade planning
-
-### Source Alignment
-
-- [Kiro Website](https://kiro.dev)
-- [Kiro Docs: Getting Started](https://kiro.dev/docs/getting-started)
-- [Kiro Docs: Authentication](https://kiro.dev/docs/authentication)
-- [Kiro Repository](https://github.com/kirodotdev/Kiro)
-
-### Cross-Tutorial Connection Map
-
-- [Cline Tutorial](../cline-tutorial/)
-- [Roo Code Tutorial](../roo-code-tutorial/)
-- [Claude Code Tutorial](../claude-code-tutorial/)
-- [OpenCode Tutorial](../opencode-tutorial/)
-- [Chapter 2: Spec-Driven Development Workflow](02-spec-driven-development-workflow.md)
-
-### Advanced Practice Exercises
-
-1. Install Kiro on a second platform (if available) and compare the authentication flow differences.
-2. Configure a large repository with `.kiro/` exclusion settings and measure indexing time before and after.
-3. Simulate an auth token expiry by signing out mid-session and document the re-authentication steps.
-4. Set up a proxy environment and verify Kiro model calls route correctly through it.
-5. Create an onboarding runbook for a five-person team covering install, auth, and first-session steps.
-
-### Review Questions
-
-1. Which authentication method integrates most naturally with your team's existing identity provider?
-2. What signal confirms that workspace indexing completed successfully before sending the first chat message?
-3. What tradeoff did you make between workspace scope and indexing speed?
-4. How would you recover if the AWS Builder ID device code expired during authentication?
-5. What must be documented before scaling Kiro installation to a full engineering team?
-
-### Scenario Playbook 1: Getting Started - Auth Flow Spike
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: authentication provider OAuth endpoint is slow or intermittently unavailable
-- initial hypothesis: identify the smallest reproducible failure boundary in the auth redirect chain
-- immediate action: protect developer productivity by switching to an alternative auth provider temporarily
-- engineering control: document both GitHub and AWS Builder ID flows so teams can pivot without delay
-- verification target: authentication completes within 30 seconds on a standard corporate network
-- rollback trigger: if auth fails three consecutive times, escalate to IT for network proxy review
-- communication step: notify team channel with auth status and estimated resolution time
-- learning capture: add auth fallback procedure to onboarding runbook and automate network pre-check
-
-### Scenario Playbook 2: Getting Started - Large Repo Indexing Failure
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: workspace indexing hangs or produces incomplete context for a monorepo over 50k files
-- initial hypothesis: identify which file patterns or directories are causing indexer stalls
-- immediate action: add exclusion rules for build artifacts, `node_modules`, and generated files in workspace settings
-- engineering control: define a canonical `.kiro/` exclusion list for the monorepo and commit it to version control
-- verification target: indexing completes in under two minutes for the scoped workspace
-- rollback trigger: if context responses remain incomplete after exclusion rules, reduce workspace to a single module
-- communication step: document the exclusion list decision in the team's Kiro setup guide
-- learning capture: convert the exclusion list into a reusable workspace template for new team members
-
-### Scenario Playbook 3: Getting Started - Proxy Interference
+## Source Code Walkthrough
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: corporate proxy blocks model API calls from Kiro, resulting in silent timeouts
-- initial hypothesis: identify the specific endpoint being blocked by running a direct curl test to kiro.dev
-- immediate action: submit an IT ticket to allowlist kiro.dev and the underlying model API endpoints
-- engineering control: configure Kiro's proxy settings with the corporate proxy URL and credentials
-- verification target: first chat message returns a response within five seconds after proxy configuration
-- rollback trigger: if proxy config causes other network issues, revert and use a personal hotspot for temporary access
-- communication step: share proxy configuration steps with the team and add to the network setup section of onboarding docs
-- learning capture: add a pre-install network check script that tests kiro.dev connectivity before the install begins
+> **Note:** Kiro is a proprietary AWS IDE; the [`kirodotdev/Kiro`](https://github.com/kirodotdev/Kiro) public repository contains documentation, specs, and GitHub automation scripts rather than the IDE's source code. The authoritative references for this chapter are the official Kiro documentation and the `.kiro/` directory structure created in your projects.
-### Scenario Playbook 4: Getting Started - OS Permission Denial
+### Kiro workspace layout — `.kiro/` directory
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: macOS Gatekeeper blocks Kiro launch due to quarantine attribute on the downloaded binary
-- initial hypothesis: confirm the quarantine attribute is present using `xattr -l Kiro.app`
-- immediate action: clear the quarantine attribute with `xattr -d com.apple.quarantine Kiro.app` and relaunch
-- engineering control: add a note in the install guide to clear quarantine after download on macOS
-- verification target: Kiro launches without security dialogs after the quarantine clear
-- rollback trigger: if Gatekeeper continues to block after clearing quarantine, escalate to IT for MDM policy review
-- communication step: add the quarantine-clear step to the macOS section of the team install guide
-- learning capture: investigate whether an enterprise-signed distribution eliminates this step for managed machines
+When you open a project in Kiro, it creates a `.kiro/` directory at the project root. This directory contains steering files, spec documents, and hook configurations. The `Explorer` panel in Kiro makes this directory visible — inspecting it confirms that authentication and workspace indexing worked correctly.
-### Scenario Playbook 5: Getting Started - Version Mismatch on Upgrade
+### [Kiro Docs: Getting Started](https://kiro.dev/docs/getting-started)
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: a Kiro update breaks an existing workspace configuration or .kiro/ directory format
-- initial hypothesis: compare the `.kiro/` directory schema between the old and new version release notes
-- immediate action: back up the `.kiro/` directory before applying any upgrade
-- engineering control: pin the Kiro version in team documentation until a new version is validated on the target repo
-- verification target: all spec files and steering configurations load correctly after the upgrade
-- rollback trigger: if the upgrade breaks existing specs, restore from backup and roll back to the previous version
-- communication step: announce the upgrade validation status to the team before rolling out to all workstations
-- learning capture: add a version pin and upgrade validation checklist to the team's Kiro governance document
+The official Getting Started guide documents the installation flow for each platform (`.dmg`, `.exe`, `.deb`/`.AppImage`), the three authentication paths (GitHub OAuth, Google OAuth, AWS Builder ID device flow), and the workspace panel structure covered in this chapter.
-## What Problem Does This Solve?
+## How These Components Connect
-Most teams struggle with agentic IDE adoption because setup friction causes inconsistent baselines across developer machines. Kiro solves this by providing a single downloadable package with a guided authentication flow, auto-indexing workspace setup, and a visible `.kiro/` directory that anchors all AI configuration in version control from day one.
-
-In practical terms, this chapter helps you avoid three common failures:
-
-- inconsistent authentication states that cause intermittent model failures mid-session
-- oversized workspace indexing that produces irrelevant context and slow responses
-- undocumented network or OS requirements that block adoption for entire teams
-
-After working through this chapter, you should be able to reason about Kiro's setup as a deterministic onboarding sequence with explicit checkpoints: installed, authenticated, workspace open, indexed, and chat ready.
-
-## How it Works Under the Hood
-
-Under the hood, `Chapter 1: Getting Started` follows a repeatable control path:
-
-1. **Binary bootstrap**: Kiro launches a VS Code-based electron process and initializes the extension host.
-2. **Auth token acquisition**: the selected OAuth provider issues a token that Kiro stores in the OS credential store.
-3. **Workspace indexing**: Kiro scans the open folder, applies exclusion rules, and builds a local context index.
-4. **Model connection**: Kiro establishes a secure connection to the model API endpoint using the stored auth token.
-5. **Chat session initialization**: the Chat panel registers the workspace context and prepares the first-message prompt template.
-6. **Operational telemetry**: Kiro emits anonymized usage signals for session start, indexing duration, and first-message latency.
-
-When debugging setup failures, walk this sequence in order and confirm each stage completes before moving to the next.
-
-## Source Walkthrough
-
-Use the following upstream sources to verify implementation details while reading this chapter:
-
-- [Kiro Website](https://kiro.dev)
- Why it matters: the primary distribution point for all platform installers and release notes.
-- [Kiro Docs: Getting Started](https://kiro.dev/docs/getting-started)
- Why it matters: official step-by-step guide for first-time setup across all supported platforms.
-- [Kiro Docs: Authentication](https://kiro.dev/docs/authentication)
- Why it matters: documents each auth provider's flow, token lifecycle, and re-authentication steps.
-- [Kiro Repository](https://github.com/kirodotdev/Kiro)
- Why it matters: source of truth for open-source components, release tags, and community issue tracking.
-
-Suggested trace strategy:
-- check the GitHub releases page for the latest version tag before installing
-- compare the kiro.dev docs auth section against your team's identity provider to confirm compatibility before deploying widely
-
-## Chapter Connections
-
-- [Tutorial Index](README.md)
-- [Next Chapter: Chapter 2: Spec-Driven Development Workflow](02-spec-driven-development-workflow.md)
-- [Main Catalog](../../README.md#-tutorial-catalog)
-- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
-
-### Scenario Playbook 1: Chapter 1: Getting Started
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 2: Chapter 1: Getting Started
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 3: Chapter 1: Getting Started
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 4: Chapter 1: Getting Started
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 5: Chapter 1: Getting Started
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 6: Chapter 1: Getting Started
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 7: Chapter 1: Getting Started
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 8: Chapter 1: Getting Started
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 9: Chapter 1: Getting Started
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 10: Chapter 1: Getting Started
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 11: Chapter 1: Getting Started
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 12: Chapter 1: Getting Started
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 13: Chapter 1: Getting Started
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 14: Chapter 1: Getting Started
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 15: Chapter 1: Getting Started
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 16: Chapter 1: Getting Started
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 17: Chapter 1: Getting Started
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 18: Chapter 1: Getting Started
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 19: Chapter 1: Getting Started
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 20: Chapter 1: Getting Started
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 21: Chapter 1: Getting Started
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 22: Chapter 1: Getting Started
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
+```mermaid
+flowchart TD
+ A[Download from kiro.dev] --> B[Platform installer]
+ B --> C[Authentication: GitHub / Google / AWS Builder ID]
+ C --> D[Open project folder]
+ D --> E[Kiro indexes workspace]
+ E --> F[.kiro/ directory created]
+ F --> G[Chat panel available]
+ G --> H[First AI-assisted interaction]
+```
diff --git a/tutorials/kiro-tutorial/02-spec-driven-development-workflow.md b/tutorials/kiro-tutorial/02-spec-driven-development-workflow.md
index 88329f45..0381176b 100644
--- a/tutorials/kiro-tutorial/02-spec-driven-development-workflow.md
+++ b/tutorials/kiro-tutorial/02-spec-driven-development-workflow.md
@@ -5,6 +5,7 @@ nav_order: 2
parent: Kiro Tutorial
---
+
# Chapter 2: Spec-Driven Development Workflow
Welcome to **Chapter 2: Spec-Driven Development Workflow**. In this part of **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
@@ -181,402 +182,26 @@ Next: [Chapter 3: Agent Steering and Rules Configuration](03-agent-steering-and-
## Depth Expansion Playbook
-<!-- depth-expansion-v2 -->
-
-This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
-
-### Strategic Context
-
-- tutorial: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- tutorial slug: **kiro-tutorial**
-- chapter focus: **Chapter 2: Spec-Driven Development Workflow**
-- system context: **Kiro Tutorial**
-- objective: move from surface-level usage to repeatable engineering operation
-
-### Architecture Decomposition
-
-1. Define the runtime boundary for `Chapter 2: Spec-Driven Development Workflow` — the `.kiro/specs/` directory as the source of truth, the spec agent as transformer, and the chat panel as the control interface.
-2. Separate control-plane decisions (which requirements to include, design approval gates) from data-plane execution (file writes, task execution).
-3. Capture input contracts: EARS-formatted `requirements.md`; output contracts: approved `design.md` and executable `tasks.md`.
-4. Trace state transitions: empty spec folder → requirements written → design generated → design approved → tasks generated → tasks executing → tasks complete.
-5. Identify extension hooks: custom EARS templates, design document templates, task numbering conventions.
-6. Map ownership boundaries: product/engineer owns `requirements.md`; architect reviews `design.md`; agent executes `tasks.md`.
-7. Specify rollback paths: revert `design.md` to a previous git commit; regenerate `tasks.md` from the prior design.
-8. Track observability signals: spec generation latency, task completion rate, requirement traceability coverage.
-
-### Operator Decision Matrix
-
-| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
-|:--------------|:--------------|:------------------|:---------|
-| Requirements granularity | 5-10 high-level EARS statements | 20+ detailed acceptance criteria | speed vs precision |
-| Design approval gate | developer self-approves | architect review before task generation | velocity vs quality |
-| Task delegation | manual task-by-task execution | full autonomous delegation | control vs efficiency |
-| Spec versioning | file in .kiro/ only | committed to git with PR review | simplicity vs auditability |
-| Iteration strategy | regenerate full design on change | diff-patch specific sections | speed vs traceability |
-
-### Failure Modes and Countermeasures
-
-| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
-|:-------------|:-------------|:-------------------|:---------------|
-| ambiguous requirements | design doc misses intent | vague EARS statements | add acceptance criteria and examples to each requirement |
-| design drift | tasks diverge from design | design.md edited without regenerating tasks | treat design.md as source of truth; always regenerate tasks after edits |
-| task scope creep | tasks grow beyond spec | underconstrained task generation | add a "scope boundary" section to design.md |
-| stale spec | code diverges from requirements | no enforcement of spec-first updates | add a CI check that alerts when code changes lack a corresponding spec update |
-| overgenerated tasks | too many micro-tasks slow progress | fine-grained design decomposition | set a max-tasks constraint in the spec generation prompt |
-| spec format violations | agent rejects or misreads spec | non-EARS requirements | validate requirements.md against EARS patterns before generation |
-
-### Implementation Runbook
-
-1. Create the spec directory: `.kiro/specs/<feature-name>/`.
-2. Write `requirements.md` using EARS syntax with at least three functional and one non-functional requirement.
-3. Ask Kiro to generate `design.md` from `requirements.md` and review the output for completeness.
-4. Identify any gaps in the design and add clarifying context to `requirements.md`, then regenerate.
-5. Approve `design.md` by committing it to version control with a design-review tag.
-6. Ask Kiro to generate `tasks.md` from `design.md` and verify task ordering and dependencies.
-7. Execute the first two tasks manually to validate the spec-to-code translation quality.
-8. Promote remaining tasks to autonomous agent execution after manual validation.
-9. Mark completed tasks in `tasks.md` and commit the updated spec after each task group completes.
-
-### Quality Gate Checklist
-
-- [ ] all requirements are written in valid EARS syntax with no ambiguous "should" language
-- [ ] `design.md` covers component architecture, data models, API contracts, and error handling
-- [ ] `tasks.md` is numbered, ordered by dependency, and each task references the design section it implements
-- [ ] spec files are committed to version control before task execution begins
-- [ ] at least two tasks are manually validated before autonomous delegation
-- [ ] a rollback path (git revert of spec files) is documented and tested
-- [ ] spec generation latency is within acceptable bounds for the team's workflow
-- [ ] requirement traceability is confirmed: every task maps to at least one requirement
-
-### Source Alignment
-
-- [Kiro Docs: Specs](https://kiro.dev/docs/specs)
-- [Kiro Docs: EARS Syntax](https://kiro.dev/docs/specs/ears)
-- [Kiro Docs: Task Execution](https://kiro.dev/docs/specs/tasks)
-- [Kiro Repository](https://github.com/kirodotdev/Kiro)
-
-### Cross-Tutorial Connection Map
-
-- [Claude Code Tutorial](../claude-code-tutorial/)
-- [Cline Tutorial](../cline-tutorial/)
-- [OpenHands Tutorial](../openhands-tutorial/)
-- [Plandex Tutorial](../plandex-tutorial/)
-- [Chapter 3: Agent Steering and Rules Configuration](03-agent-steering-and-rules-configuration.md)
-
-### Advanced Practice Exercises
-
-1. Write a complete `requirements.md` for a payment processing feature using all five EARS patterns.
-2. Generate `design.md` and identify one gap; update requirements and regenerate to confirm the gap is filled.
-3. Simulate a requirement change mid-execution and practice updating only the affected tasks in `tasks.md`.
-4. Add a CI check that lints `requirements.md` for non-EARS language like "should" or "might".
-5. Compare the task output from two different levels of design granularity and measure execution accuracy.
-
-### Review Questions
-
-1. What is the purpose of EARS syntax and why does Kiro require it for high-quality spec generation?
-2. Which approval gate prevents design drift from propagating into task execution?
-3. What tradeoff did you make between task granularity and autonomous delegation speed?
-4. How would you recover if `design.md` was edited manually and `tasks.md` is now inconsistent?
-5. What must be in version control before autonomous task execution begins?
-
-### Scenario Playbook 1: Spec Generation - Ambiguous Requirements
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: design.md misses key business logic because requirements.md used vague language
-- initial hypothesis: identify which EARS statements lack acceptance criteria or measurable conditions
-- immediate action: add concrete examples and edge cases to the failing requirements before regenerating
-- engineering control: require peer review of requirements.md before submitting to the spec agent
-- verification target: every requirement in the regenerated design.md maps to a specific, testable implementation
-- rollback trigger: if two regeneration attempts still miss key logic, escalate to a design workshop with the team
-- communication step: document the ambiguous requirements and their clarified versions in the spec PR description
-- learning capture: add the clarified examples to the team's EARS writing guide for future features
-
-### Scenario Playbook 2: Spec Generation - Design Drift
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: tasks.md references components or APIs that no longer match design.md after manual edits
-- initial hypothesis: diff design.md against its last committed version to identify manual changes
-- immediate action: revert design.md to the last approved commit and regenerate tasks.md
-- engineering control: treat design.md as an append-only document; add new sections rather than editing existing ones
-- verification target: every task in tasks.md references a section that exists in the current design.md
-- rollback trigger: if task regeneration continues to produce drift, split the spec into two separate feature specs
-- communication step: notify the team that design.md has a new version and tasks.md has been regenerated
-- learning capture: add a git hook that warns when design.md is modified without a corresponding tasks.md regeneration
+## Source Code Walkthrough
-### Scenario Playbook 3: Spec Execution - Task Scope Creep
+> **Note:** Kiro is a proprietary AWS IDE; the [`kirodotdev/Kiro`](https://github.com/kirodotdev/Kiro) public repository contains documentation and GitHub automation scripts rather than the IDE's source code. The authoritative references for this chapter are the official Kiro documentation and configuration files within your project's `.kiro/` directory.
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: autonomous agent adds files or changes outside the defined task scope during execution
-- initial hypothesis: review the task description for missing scope boundaries or implicit dependencies
-- immediate action: halt agent execution, review changes, and revert any out-of-scope modifications
-- engineering control: add an explicit "out of scope" section to tasks.md listing what the agent must not change
-- verification target: agent changes are confined to the files and directories listed in the task description
-- rollback trigger: if out-of-scope changes recur on the next task, switch to manual task-by-task execution
-- communication step: document the out-of-scope incident in the spec's revision history
-- learning capture: update the task generation prompt template to always include a scope boundary constraint
+### [Kiro Docs: Specs](https://kiro.dev/docs/specs)
-### Scenario Playbook 4: Spec Iteration - Mid-Sprint Requirement Change
+The official specs guide documents the three-file structure (`requirements.md`, `design.md`, `tasks.md`), EARS syntax patterns, and the iterative spec workflow described in this chapter. The `.kiro/specs/<feature>/` directory layout is the authoritative schema.
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: a product decision changes one requirement after task execution has already begun
-- initial hypothesis: identify which completed tasks are affected by the changed requirement
-- immediate action: mark affected completed tasks as "needs-revision" in tasks.md and halt further execution
-- engineering control: update requirements.md first, then regenerate only the affected design.md sections and tasks
-- verification target: updated tasks are re-executed and produce output consistent with the new requirement
-- rollback trigger: if the change invalidates more than 50% of completed tasks, create a new spec branch
-- communication step: update the PR description with the requirement change and its impact on the task list
-- learning capture: add a "change impact" section to the spec template for documenting mid-sprint pivots
+### [Kiro Docs: EARS Syntax](https://kiro.dev/docs/specs/ears)
-### Scenario Playbook 5: Spec Quality - Stale Spec After Code Refactor
+The EARS syntax reference documents the five requirement patterns (Ubiquitous, Event-driven, Unwanted behavior, State-driven, Optional feature) that structure `requirements.md` files and drive Kiro's spec-to-design generation.
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: code has been refactored but the spec files still reference the old architecture
-- initial hypothesis: compare the current codebase structure against design.md component references
-- immediate action: flag the spec as "stale" and schedule a spec refresh session before the next feature build
-- engineering control: add a quarterly spec audit to the team's engineering calendar
-- verification target: refreshed design.md accurately describes the current architecture and data models
-- rollback trigger: if the spec refresh reveals architectural inconsistencies, escalate to an architecture review
-- communication step: announce the spec refresh in the team channel and request review from senior engineers
-- learning capture: add a "last verified" timestamp field to each spec and enforce it in the PR template
+## How These Components Connect
-## What Problem Does This Solve?
-
-Most agentic coding tools suffer from the "chat amnesia" problem: each conversation starts fresh, there is no persistent record of design decisions, and AI-generated code accumulates without traceability back to requirements. Kiro's spec-driven workflow solves this by making the design artifact — not the conversation — the primary interface for AI assistance.
-
-In practical terms, this chapter helps you avoid three common failures:
-
-- generating code that satisfies the immediate prompt but misses the broader system design
-- losing context across sessions when working on a multi-day feature
-- having no audit trail of why specific implementation choices were made
-
-After working through this chapter, you should be able to reason about Kiro specs as a contract layer between product intent, system design, and agent execution — with explicit traceability from requirement to code.
-
-## How it Works Under the Hood
-
-Under the hood, `Chapter 2: Spec-Driven Development Workflow` follows a repeatable control path:
-
-1. **Spec directory initialization**: Kiro creates `.kiro/specs/<feature>/` and registers the spec in the workspace index.
-2. **Requirements parsing**: the spec agent reads `requirements.md` and classifies each statement by EARS pattern type.
-3. **Design generation**: the agent maps requirements to components, data models, and APIs and writes `design.md`.
-4. **Design approval gate**: the developer reviews and commits `design.md`; Kiro treats the committed version as canonical.
-5. **Task decomposition**: the agent reads `design.md` and generates ordered, dependency-aware tasks in `tasks.md`.
-6. **Task execution loop**: each task is dispatched to the appropriate execution agent with the design as grounding context.
-
-When debugging spec quality issues, walk this sequence in order and check the output at each stage before moving forward.
-
-## Source Walkthrough
-
-Use the following upstream sources to verify implementation details while reading this chapter:
-
-- [Kiro Docs: Specs](https://kiro.dev/docs/specs)
- Why it matters: the authoritative reference for the three-file spec format and generation workflow.
-- [Kiro Docs: EARS Syntax](https://kiro.dev/docs/specs/ears)
- Why it matters: defines the exact EARS patterns Kiro uses to parse and classify requirements.
-- [Kiro Docs: Task Execution](https://kiro.dev/docs/specs/tasks)
- Why it matters: documents how tasks.md items are dispatched to agents and how completion is tracked.
-- [Kiro Repository](https://github.com/kirodotdev/Kiro)
- Why it matters: source of truth for spec agent implementation and community-contributed spec templates.
-
-Suggested trace strategy:
-- search the Kiro docs for each EARS pattern keyword before writing your first requirements.md
-- compare generated design.md sections against the design template in the docs to confirm coverage
-
-## Chapter Connections
-
-- [Tutorial Index](README.md)
-- [Previous Chapter: Chapter 1: Getting Started](01-getting-started.md)
-- [Next Chapter: Chapter 3: Agent Steering and Rules Configuration](03-agent-steering-and-rules-configuration.md)
-- [Main Catalog](../../README.md#-tutorial-catalog)
-- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
-
-### Scenario Playbook 1: Chapter 2: Spec-Driven Development Workflow
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 2: Chapter 2: Spec-Driven Development Workflow
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 3: Chapter 2: Spec-Driven Development Workflow
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 4: Chapter 2: Spec-Driven Development Workflow
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 5: Chapter 2: Spec-Driven Development Workflow
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 6: Chapter 2: Spec-Driven Development Workflow
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 7: Chapter 2: Spec-Driven Development Workflow
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 8: Chapter 2: Spec-Driven Development Workflow
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 9: Chapter 2: Spec-Driven Development Workflow
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 10: Chapter 2: Spec-Driven Development Workflow
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 11: Chapter 2: Spec-Driven Development Workflow
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 12: Chapter 2: Spec-Driven Development Workflow
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 13: Chapter 2: Spec-Driven Development Workflow
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 14: Chapter 2: Spec-Driven Development Workflow
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 15: Chapter 2: Spec-Driven Development Workflow
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 16: Chapter 2: Spec-Driven Development Workflow
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
+```mermaid
+flowchart TD
+ A[requirements.md EARS syntax] --> B[Kiro spec agent]
+ B --> C[design.md components + APIs]
+ C --> D[tasks.md numbered implementation steps]
+ D --> E[Agent executes task]
+ E --> F[Code changes]
+ F --> G[Mark task complete in tasks.md]
+```
\ No newline at end of file
diff --git a/tutorials/kiro-tutorial/03-agent-steering-and-rules-configuration.md b/tutorials/kiro-tutorial/03-agent-steering-and-rules-configuration.md
index 6e4a9e56..2070105b 100644
--- a/tutorials/kiro-tutorial/03-agent-steering-and-rules-configuration.md
+++ b/tutorials/kiro-tutorial/03-agent-steering-and-rules-configuration.md
@@ -5,6 +5,7 @@ nav_order: 3
parent: Kiro Tutorial
---
+
# Chapter 3: Agent Steering and Rules Configuration
Welcome to **Chapter 3: Agent Steering and Rules Configuration**. In this part of **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
@@ -178,414 +179,26 @@ Next: [Chapter 4: Autonomous Agent Mode](04-autonomous-agent-mode.md)
## Depth Expansion Playbook
-<!-- depth-expansion-v2 -->
-
-This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
-
-### Strategic Context
-
-- tutorial: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- tutorial slug: **kiro-tutorial**
-- chapter focus: **Chapter 3: Agent Steering and Rules Configuration**
-- system context: **Kiro Tutorial**
-- objective: move from surface-level usage to repeatable engineering operation
-
-### Architecture Decomposition
-
-1. Define the runtime boundary for `Chapter 3: Agent Steering and Rules Configuration` — the `.kiro/steering/` directory as a persistent context source, the Kiro context injector as the delivery mechanism, and the agent as the consumer.
-2. Separate control-plane decisions (which steering files to create, scoping rules) from data-plane execution (file reads and context injection at session start).
-3. Capture input contracts: markdown files in `.kiro/steering/`; output: augmented system prompt for every agent interaction.
-4. Trace state transitions: no steering → steering files created → steering loaded at session start → agent behavior reflects rules.
-5. Identify extension hooks: inclusion patterns for file-scoped rules, numeric prefixes for priority ordering.
-6. Map ownership boundaries: team leads own `00-project.md` and `03-security.md`; individual developers own feature-specific steering files.
-7. Specify rollback paths: remove or rename a steering file to exclude it from context; use git revert for team-wide rollback.
-8. Track observability signals: verify agent responses reflect steering rules by testing with rule-specific questions.
-
-### Operator Decision Matrix
-
-| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
-|:--------------|:--------------|:------------------|:---------|
-| Steering granularity | one general project.md | multiple scoped files per concern | simplicity vs precision |
-| Rule enforcement | informational guidance | explicit forbidden patterns | flexibility vs compliance |
-| Versioning | committed to git | PR review required for changes | speed vs governance |
-| Scoping | global rules only | file-pattern scoped rules | ease vs relevance |
-| Team ownership | any developer edits | designated maintainer with review | velocity vs consistency |
-
-### Failure Modes and Countermeasures
-
-| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
-|:-------------|:-------------|:-------------------|:---------------|
-| steering not loaded | agent ignores known rules | session not restarted after adding files | reopen workspace to trigger re-load |
-| conflicting rules | inconsistent agent output | two steering files with contradicting guidance | audit files for conflicts; use numeric prefix to set explicit priority |
-| overly broad rules | agent refuses valid patterns | steering file uses absolute prohibition on useful patterns | rewrite rules as guidance with explicit exceptions |
-| stale steering | agent applies outdated tech stack choices | steering not updated after refactor | add a quarterly steering review to the team's engineering calendar |
-| rule explosion | too many steering files slow context loading | fine-grained file-per-rule authoring | consolidate related rules into thematic files |
-| secret leakage in steering | sensitive values committed to git | developer pasted credentials into steering file | scan steering files with secret detection in CI |
-
-### Implementation Runbook
-
-1. Create the `.kiro/steering/` directory and add it to the git-tracked files.
-2. Write `00-project.md` with the technology stack, key decisions, and forbidden patterns.
-3. Write `01-coding-style.md` with language-specific style conventions for the primary language.
-4. Write `02-testing.md` with the testing framework, naming conventions, and coverage targets.
-5. Write `03-security.md` with authentication requirements, input validation policies, and dependency rules.
-6. Reopen the workspace to trigger steering file loading.
-7. Verify each steering file by asking a targeted question that requires knowledge of that file's rules.
-8. Commit all steering files to version control with a PR description explaining each file's purpose.
-9. Add a CI lint step to check steering files for secret patterns and markdown syntax errors.
-
-### Quality Gate Checklist
-
-- [ ] steering files cover the four core domains: project context, coding style, testing, and security
-- [ ] all steering files use plain markdown with no embedded secrets or credentials
-- [ ] file-scoped rules use valid inclusion patterns tested against actual file paths
-- [ ] priority ordering is explicit via numeric prefixes on filenames
-- [ ] steering rules are verified by targeted agent questions before committing
-- [ ] steering files are committed to version control with clear PR descriptions
-- [ ] a CI step checks steering files for secret patterns
-- [ ] a review process is defined for who can approve changes to security.md and project.md
-
-### Source Alignment
-
-- [Kiro Docs: Steering](https://kiro.dev/docs/steering)
-- [Kiro Docs: Steering Files](https://kiro.dev/docs/steering/files)
-- [Kiro Docs: Steering Scoping](https://kiro.dev/docs/steering/scoping)
-- [Kiro Repository](https://github.com/kirodotdev/Kiro)
-
-### Cross-Tutorial Connection Map
-
-- [Cline Tutorial](../cline-tutorial/)
-- [Roo Code Tutorial](../roo-code-tutorial/)
-- [Claude Code Tutorial](../claude-code-tutorial/)
-- [Agents MD Tutorial](../agents-md-tutorial/)
-- [Chapter 4: Autonomous Agent Mode](04-autonomous-agent-mode.md)
-
-### Advanced Practice Exercises
-
-1. Write a complete four-file steering setup (project, style, testing, security) for a real project and verify each file's rules with targeted agent questions.
-2. Create a file-scoped steering file for the `src/api/` directory and confirm it does not affect agent behavior in `src/models/`.
-3. Simulate a steering conflict by writing two files with contradicting rules and observe the agent's behavior; then resolve the conflict with explicit priority ordering.
-4. Add a GitHub Actions step that runs `gitleaks` or `trufflehog` against the `.kiro/steering/` directory on every PR.
-5. Write a steering update proposal PR that changes a security rule and practice the review and approval workflow.
-
-### Review Questions
-
-1. What is the difference between a steering file and a chat prompt, and when should you use each?
-2. How does Kiro determine the priority order when two steering files have conflicting rules?
-3. What tradeoff did you make between steering granularity and context loading performance?
-4. How would you recover if a steering file was accidentally committed with an API key?
-5. What governance process should control changes to the security steering file in a team environment?
-
-### Scenario Playbook 1: Steering - Rules Not Loaded After Adding Files
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: agent ignores steering rules despite `.kiro/steering/` containing valid markdown files
-- initial hypothesis: the workspace session was not restarted after adding the steering files
-- immediate action: close and reopen the Kiro workspace to trigger steering file re-loading
-- engineering control: add a note to the team onboarding guide that workspace restart is required after steering changes
-- verification target: agent responds with steering-aligned content when asked a targeted rule question
-- rollback trigger: if restarting does not load steering, check for markdown syntax errors in the steering files
-- communication step: document the restart requirement in the project's Kiro setup README section
-- learning capture: request a Kiro feature for hot-reloading steering files without workspace restart
-
-### Scenario Playbook 2: Steering - Conflicting Rules Between Files
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: agent produces inconsistent output because two steering files have contradicting guidance
-- initial hypothesis: identify the specific rule conflict by reviewing all steering files for overlapping topics
-- immediate action: temporarily disable the lower-priority file by renaming it with a `.disabled` extension
-- engineering control: audit all steering files for topic overlap and consolidate conflicting rules into a single file
-- verification target: agent consistently applies the intended rule with the conflict file disabled
-- rollback trigger: if the conflict resolution introduces new inconsistencies, split into more narrowly scoped files
-- communication step: document the conflict resolution decision in the PR that updates the steering files
-- learning capture: add a steering file review checklist that flags topic overlap during PR review
+## Source Code Walkthrough
-### Scenario Playbook 3: Steering - Secret Committed to Steering File
+> **Note:** Kiro is a proprietary AWS IDE; the [`kirodotdev/Kiro`](https://github.com/kirodotdev/Kiro) public repository contains documentation and GitHub automation scripts rather than the IDE's source code. The authoritative references for this chapter are the official Kiro documentation and configuration files within your project's `.kiro/` directory.
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: a developer pasted a real API key or database password into a steering file and committed it
-- initial hypothesis: confirm the secret is present by running gitleaks against the repository history
-- immediate action: immediately revoke the exposed credential at the issuing service; do not wait for git history cleanup
-- engineering control: use `git filter-branch` or BFG Repo Cleaner to remove the secret from git history, then force-push
-- verification target: gitleaks scan reports zero secrets in `.kiro/steering/` after history cleanup
-- rollback trigger: if history rewrite fails, mark the repository as compromised and rotate all project credentials
-- communication step: notify the security team and affected service owners of the exposure within one hour
-- learning capture: add a pre-commit hook that runs secret detection on `.kiro/steering/` before allowing commits
+### [Kiro Docs: Steering](https://kiro.dev/docs/steering)
-### Scenario Playbook 4: Steering - Stale Technology Stack After Refactor
+The steering guide documents the `.kiro/steering/` directory structure, the front-matter fields (`inclusion`, `alwaysApply`), and how multiple steering files are composed. These files are the actual configuration artifacts for the agent behavior described in this chapter.
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: agent recommends patterns from the old tech stack because project.md was not updated after a framework migration
-- initial hypothesis: compare the current package.json and import statements against the technology stack in project.md
-- immediate action: update project.md with the new framework and remove all references to the deprecated stack
-- engineering control: add a steering review to the definition of done for major refactoring tasks
-- verification target: agent recommends only the new framework's patterns after project.md is updated
-- rollback trigger: if the update causes agent confusion, create a migration note section in project.md explaining the transition
-- communication step: announce the project.md update in the team channel and ask members to restart their Kiro workspaces
-- learning capture: add "update project.md" as a required step in the refactoring PR checklist
+### [Kiro Repository — example steering files](https://github.com/kirodotdev/Kiro/tree/main/.kiro)
-### Scenario Playbook 5: Steering - Overly Broad Security Rules Breaking Valid Patterns
+The Kiro repository's own `.kiro/` directory contains real steering file examples used by the project itself — examining these shows practical steering file structure and scope patterns.
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: agent refuses to generate valid code patterns because security.md uses absolute prohibitions that are too broad
-- initial hypothesis: identify the specific rule that is blocking valid patterns and test with a targeted prompt
-- immediate action: rewrite the prohibition as a conditional rule with explicit exceptions for the valid patterns
-- engineering control: review all absolute prohibitions in security.md and add exception clauses where appropriate
-- verification target: agent generates valid code patterns while still respecting the underlying security intent
-- rollback trigger: if rule rewriting introduces security gaps, escalate to a security team review before committing
-- communication step: document the rule refinement and its rationale in the security.md commit message
-- learning capture: add a rule-testing protocol to the steering governance process: test each new rule with both valid and invalid code examples
+## How These Components Connect
-## What Problem Does This Solve?
-
-Without persistent project context, every Kiro session starts from scratch. Developers repeat the same stack choices, style preferences, and policy constraints in every chat prompt, and new team members have no way to discover what the AI has been told to do. Kiro's steering system solves this by storing project rules in version-controlled markdown files that are automatically injected into every agent interaction.
-
-In practical terms, this chapter helps you avoid three common failures:
-
-- agents generating code that contradicts established team conventions because the rules were never encoded
-- inconsistent AI behavior across team members because each person prompts differently
-- policy drift where security rules agreed upon in a meeting never make it into the AI's working context
-
-After working through this chapter, you should be able to treat the `.kiro/steering/` directory as the authoritative source of your team's AI operating rules, reviewed and version-controlled like any other engineering artifact.
-
-## How it Works Under the Hood
-
-Under the hood, `Chapter 3: Agent Steering and Rules Configuration` follows a repeatable control path:
-
-1. **Directory scan**: at workspace open, Kiro scans `.kiro/steering/` and loads all `.md` files in alphabetical order.
-2. **Scoping evaluation**: for each file, Kiro checks the `applies_to` frontmatter against the current file context.
-3. **Context injection**: active steering file content is prepended to the system prompt for every agent interaction.
-4. **Priority resolution**: files with lower numeric prefixes take precedence when content conflicts.
-5. **Session persistence**: steering context persists for the entire workspace session without re-loading on each message.
-6. **Operational telemetry**: Kiro logs which steering files were loaded and their total character count for debugging.
-
-When debugging steering issues, verify each stage: files exist, scoping matches, context is injected, and agent responses reflect the rules.
-
-## Source Walkthrough
-
-Use the following upstream sources to verify implementation details while reading this chapter:
-
-- [Kiro Docs: Steering](https://kiro.dev/docs/steering)
- Why it matters: the authoritative reference for the steering directory structure and file format.
-- [Kiro Docs: Steering Files](https://kiro.dev/docs/steering/files)
- Why it matters: documents the frontmatter options including `applies_to` scoping patterns.
-- [Kiro Docs: Steering Scoping](https://kiro.dev/docs/steering/scoping)
- Why it matters: explains how Kiro matches file-pattern rules against the current active file in the editor.
-- [Kiro Repository](https://github.com/kirodotdev/Kiro)
- Why it matters: source of community-contributed steering file examples and issue tracking for steering bugs.
-
-Suggested trace strategy:
-- check the steering docs for the exact frontmatter schema before writing `applies_to` patterns
-- test each steering file with a targeted question immediately after creation to confirm loading
-
-## Chapter Connections
-
-- [Tutorial Index](README.md)
-- [Previous Chapter: Chapter 2: Spec-Driven Development Workflow](02-spec-driven-development-workflow.md)
-- [Next Chapter: Chapter 4: Autonomous Agent Mode](04-autonomous-agent-mode.md)
-- [Main Catalog](../../README.md#-tutorial-catalog)
-- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
-
-### Scenario Playbook 1: Chapter 3: Agent Steering and Rules Configuration
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 2: Chapter 3: Agent Steering and Rules Configuration
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 3: Chapter 3: Agent Steering and Rules Configuration
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 4: Chapter 3: Agent Steering and Rules Configuration
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 5: Chapter 3: Agent Steering and Rules Configuration
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 6: Chapter 3: Agent Steering and Rules Configuration
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 7: Chapter 3: Agent Steering and Rules Configuration
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 8: Chapter 3: Agent Steering and Rules Configuration
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 9: Chapter 3: Agent Steering and Rules Configuration
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 10: Chapter 3: Agent Steering and Rules Configuration
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 11: Chapter 3: Agent Steering and Rules Configuration
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 12: Chapter 3: Agent Steering and Rules Configuration
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 13: Chapter 3: Agent Steering and Rules Configuration
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 14: Chapter 3: Agent Steering and Rules Configuration
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 15: Chapter 3: Agent Steering and Rules Configuration
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 16: Chapter 3: Agent Steering and Rules Configuration
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 17: Chapter 3: Agent Steering and Rules Configuration
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
+```mermaid
+flowchart TD
+ A[.kiro/steering/] --> B[project-conventions.md alwaysApply=true]
+ A --> C[typescript-rules.md glob=**/*.ts]
+ A --> D[security.md alwaysApply=true]
+ B --> E[Agent loads on every request]
+ C --> F[Agent loads for TypeScript files only]
+ D --> E
+```
\ No newline at end of file
diff --git a/tutorials/kiro-tutorial/04-autonomous-agent-mode.md b/tutorials/kiro-tutorial/04-autonomous-agent-mode.md
index b3b38e7d..61683692 100644
--- a/tutorials/kiro-tutorial/04-autonomous-agent-mode.md
+++ b/tutorials/kiro-tutorial/04-autonomous-agent-mode.md
@@ -5,6 +5,7 @@ nav_order: 4
parent: Kiro Tutorial
---
+
# Chapter 4: Autonomous Agent Mode
Welcome to **Chapter 4: Autonomous Agent Mode**. In this part of **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
@@ -178,403 +179,31 @@ Next: [Chapter 5: MCP Integration and External Tools](05-mcp-integration-and-ext
## Depth Expansion Playbook
-<!-- depth-expansion-v2 -->
-
-This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
-
-### Strategic Context
-
-- tutorial: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- tutorial slug: **kiro-tutorial**
-- chapter focus: **Chapter 4: Autonomous Agent Mode**
-- system context: **Kiro Tutorial**
-- objective: move from surface-level usage to repeatable engineering operation
-
-### Architecture Decomposition
-
-1. Define the runtime boundary for `Chapter 4: Autonomous Agent Mode` — the agent executor, the tool dispatch layer, and the approval gate controller.
-2. Separate control-plane decisions (autonomy level, allowed commands, approval gates) from data-plane execution (file writes, test runs, self-correction loops).
-3. Capture input contracts: a task description from tasks.md with spec context; output: completed code changes and passing tests.
-4. Trace state transitions: task selected → agent plan generated → sub-steps executing → error or completion → human review.
-5. Identify extension hooks: `allowedCommands`, `forbiddenCommands`, `maxFileEditsPerTask`, and custom approval triggers.
-6. Map ownership boundaries: developer owns task delegation decisions; team leads own autonomy level configuration; security team approves `allowedCommands` list.
-7. Specify rollback paths: `git checkout` to revert agent changes; restore from task checkpoint if execution was interrupted.
-8. Track observability signals: agent activity log, test pass/fail rates, self-correction frequency, task completion time.
-
-### Operator Decision Matrix
-
-| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
-|:--------------|:--------------|:------------------|:---------|
-| Autonomy level | cautious (one step at a time) | full autonomy for well-specified tasks | control vs efficiency |
-| Command allowlist | no shell commands | narrow allowlist of known-safe commands | safety vs capability |
-| Task scope | single task delegation | multi-task sequential delegation | simplicity vs throughput |
-| Error recovery | human intervention on first error | agent self-correction with logging | oversight vs speed |
-| Rollback strategy | manual git checkout | automated checkpoint and revert | effort vs recovery speed |
-
-### Failure Modes and Countermeasures
-
-| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
-|:-------------|:-------------|:-------------------|:---------------|
-| agent scope creep | unexpected file edits outside task scope | underconstrained task description | add explicit file scope to task description |
-| runaway command execution | agent runs commands not in allowlist | missing `forbiddenCommands` config | maintain an explicit `forbiddenCommands` list in settings |
-| self-correction loop | agent retries same failing pattern | root cause not identified before retry | set max self-correction attempts; escalate to human on limit |
-| context window overflow | agent loses task context mid-execution | very long task with many sub-steps | split long tasks into smaller independent tasks |
-| environment mismatch | tests pass locally but agent tests fail | agent uses different Node or env vars | standardize the test environment in jest.config.ts |
-| partial completion without reporting | agent stops mid-task without clear status | error swallowed by recovery logic | require agent to log completion status for every sub-step |
-
-### Implementation Runbook
-
-1. Define the autonomy level for the current task profile in `.kiro/settings.json`.
-2. Review and set the `allowedCommands` list to only include commands safe for automated execution.
-3. Confirm the task in tasks.md has a clear, bounded scope with references to specific files or modules.
-4. Delegate the task via the Chat panel or the Specs task list interface.
-5. Monitor the Agent Activity panel during execution and verify each sub-step output.
-6. If the agent self-corrects, review the correction log to confirm the fix is sound.
-7. After task completion, run the full test suite manually to verify no regressions were introduced.
-8. Review the git diff to confirm changes are scoped to the expected files.
-9. Mark the task as complete in tasks.md and commit the updated spec.
-
-### Quality Gate Checklist
-
-- [ ] autonomy level is configured appropriately for the task type before delegation
-- [ ] `allowedCommands` and `forbiddenCommands` are explicitly set in `.kiro/settings.json`
-- [ ] task description includes explicit file scope to prevent agent scope creep
-- [ ] agent activity log is reviewed after each task for unexpected behavior
-- [ ] self-correction events are counted and investigated for root cause
-- [ ] full test suite passes after autonomous task completion
-- [ ] git diff is reviewed to confirm no out-of-scope changes
-- [ ] task completion is marked in tasks.md and committed to version control
-
-### Source Alignment
-
-- [Kiro Docs: Autonomous Agent](https://kiro.dev/docs/agent)
-- [Kiro Docs: Autonomy Levels](https://kiro.dev/docs/agent/autonomy)
-- [Kiro Docs: Agent Activity](https://kiro.dev/docs/agent/activity)
-- [Kiro Docs: Settings](https://kiro.dev/docs/settings)
-- [Kiro Repository](https://github.com/kirodotdev/Kiro)
-
-### Cross-Tutorial Connection Map
-
-- [OpenHands Tutorial](../openhands-tutorial/)
-- [SWE-Agent Tutorial](../swe-agent-tutorial/)
-- [AutoGen Tutorial](../autogen-tutorial/)
-- [CrewAI Tutorial](../crewai-tutorial/)
-- [Chapter 5: MCP Integration and External Tools](05-mcp-integration-and-external-tools.md)
-
-### Advanced Practice Exercises
-
-1. Configure three different autonomy levels in `.kiro/settings.json` and test each with the same task to compare output quality and speed.
-2. Deliberately give the agent an ambiguous task and observe where it gets confused; then rewrite the task with explicit scope and compare outcomes.
-3. Simulate an agent self-correction scenario by introducing a test environment variable that is missing; confirm the agent detects and fixes the issue.
-4. Set up a post-task git diff review workflow and practice identifying out-of-scope changes from three different autonomous executions.
-5. Build a multi-task delegation sequence for a five-task feature and practice the pause-and-review pattern between task groups.
-
-### Review Questions
-
-1. What determines whether the "balanced" or "full" autonomy level is appropriate for a given task?
-2. How do `allowedCommands` and `forbiddenCommands` interact, and what happens if a command appears in neither list?
-3. What tradeoff did you make between autonomous efficiency and oversight granularity?
-4. How would you recover if the agent completed tasks 1-3 but made an error in task 2 that was only discovered after task 3 completed?
-5. What conditions must be true before delegating a task to full autonomous mode without per-step review?
-
-### Scenario Playbook 1: Autonomous Agent - Scope Creep
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: autonomous agent modifies files outside the task's defined scope
-- initial hypothesis: task description lacked explicit file boundaries causing the agent to infer additional scope
-- immediate action: interrupt the agent and run `git checkout` to revert out-of-scope changes
-- engineering control: add explicit file path constraints to the task description before re-delegating
-- verification target: re-run the task and confirm only expected files appear in the git diff
-- rollback trigger: if scope creep recurs, switch to cautious autonomy level for this task type
-- communication step: document the scope creep incident in the task's completion notes
-- learning capture: update the task generation prompt to always include an explicit "files to modify" constraint
-
-### Scenario Playbook 2: Autonomous Agent - Runaway Command Execution
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: agent attempts to run a command not on the allowedCommands list
-- initial hypothesis: the command was implied by the task but not explicitly listed in the allowed list
-- immediate action: the agent should be blocked by the forbiddenCommands check; if not, stop execution immediately
-- engineering control: audit the allowedCommands list and add the missing command if it is safe; update forbiddenCommands otherwise
-- verification target: agent is blocked from the command on the next execution attempt
-- rollback trigger: if the agent bypassed the command check, report as a security incident to the Kiro team
-- communication step: update the team's Kiro security policy with the new command classification
-- learning capture: add the new command to the appropriate list and commit the settings.json update with a PR review
+## Source Code Walkthrough
-### Scenario Playbook 3: Autonomous Agent - Infinite Self-Correction Loop
+> **Note:** Kiro is a proprietary AWS IDE; the [`kirodotdev/Kiro`](https://github.com/kirodotdev/Kiro) public repository contains documentation and GitHub automation scripts rather than the IDE's source code. The authoritative references for this chapter are the official Kiro documentation and configuration files within your project's `.kiro/` directory.
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: agent retries the same failing test pattern more than three times without progress
-- initial hypothesis: agent is not identifying the true root cause and is applying surface-level fixes
-- immediate action: interrupt the agent and manually diagnose the test failure
-- engineering control: set a maximum self-correction attempt count in the agent settings
-- verification target: after manual fix, re-delegate the task and confirm completion on first attempt
-- rollback trigger: if the failure pattern is systemic, escalate to a debugging session with the full team
-- communication step: document the root cause and manual fix in the task completion notes
-- learning capture: add the root cause pattern to the project steering file's troubleshooting section
+### [Kiro Docs: Agent Mode](https://kiro.dev/docs/agent)
-### Scenario Playbook 4: Autonomous Agent - Context Window Overflow
+The agent mode documentation covers autonomy levels (assisted, supervised, autonomous), task delegation patterns, the approval checkpoint system, and rollback mechanisms. These are the runtime behaviors described in this chapter.
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: agent loses coherence mid-task on a large feature with many sub-steps
-- initial hypothesis: the task description plus design context exceeds the model's effective context window
-- immediate action: interrupt the agent and split the task into two independent smaller tasks in tasks.md
-- engineering control: set a `maxFileEditsPerTask` limit in settings.json to force task splitting at design time
-- verification target: each smaller task completes independently without context loss
-- rollback trigger: if splitting creates unresolvable dependencies, escalate to manual implementation of the transition step
-- communication step: update tasks.md to document the split and the dependency between the two new tasks
-- learning capture: add a task complexity guideline to the team's spec writing standards
+### [Kiro Docs: Specs — tasks.md execution](https://kiro.dev/docs/specs)
-### Scenario Playbook 5: Autonomous Agent - Partial Completion Without Status
+When autonomous mode executes a `tasks.md` file, it processes numbered tasks sequentially. The spec documentation explains how Kiro's agent tracks task completion, pauses for human review at checkpoints, and resumes execution after approval.
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: agent stops executing mid-task without reporting completion or error status
-- initial hypothesis: an unhandled exception in the agent execution loop caused a silent exit
-- immediate action: check the Kiro logs for the last recorded sub-step and manually continue from that point
-- engineering control: require the agent to write a checkpoint file after each sub-step for crash recovery
-- verification target: after the fix, re-running the task resumes from the last checkpoint without duplicating work
-- rollback trigger: if checkpoint recovery produces duplicate code, revert to the pre-task git state and restart
-- communication step: report the silent exit as a bug to the Kiro issue tracker with the relevant log snippet
-- learning capture: add a post-task verification step that confirms the agent reported a terminal status before marking the task complete
+## How These Components Connect
-## What Problem Does This Solve?
-
-The fundamental bottleneck in AI-assisted development is not model quality — it is the human-in-the-loop approval rate. When every file edit requires a manual "yes", developers spend more time approving than designing. Kiro's autonomous agent mode removes this bottleneck for well-specified tasks by delegating end-to-end execution while preserving human control at the configuration level.
-
-In practical terms, this chapter helps you avoid three common failures:
-
-- treating the AI as a typing accelerator rather than a true task delegate
-- delegating tasks without clear boundaries and getting unexpected side effects
-- losing confidence in autonomous mode because errors are not surfaced or recoverable
-
-After working through this chapter, you should be able to reason about autonomous delegation as a spectrum with explicit configuration knobs — not a binary "trust everything" or "approve everything" choice.
-
-## How it Works Under the Hood
-
-Under the hood, `Chapter 4: Autonomous Agent Mode` follows a repeatable control path:
-
-1. **Task ingestion**: the agent reads the task description and fetches the spec context from `design.md`.
-2. **Plan generation**: the agent decomposes the task into ordered sub-steps with explicit tool calls.
-3. **Tool dispatch**: each sub-step invokes a Kiro tool: file read, file write, shell command, or test runner.
-4. **Output validation**: the agent checks each tool output against its expected result before proceeding.
-5. **Self-correction loop**: on unexpected output, the agent applies a fix hypothesis and retries up to the configured limit.
-6. **Completion reporting**: the agent writes a structured completion report to the Agent Activity log.
-
-When debugging autonomous failures, check each stage in sequence and look for the first sub-step where the output diverged from expectation.
-
-## Source Walkthrough
-
-Use the following upstream sources to verify implementation details while reading this chapter:
-
-- [Kiro Docs: Autonomous Agent](https://kiro.dev/docs/agent)
- Why it matters: the primary reference for agent capabilities, tool dispatch, and execution lifecycle.
-- [Kiro Docs: Autonomy Levels](https://kiro.dev/docs/agent/autonomy)
- Why it matters: documents the exact behavior of each autonomy level and its approval gate logic.
-- [Kiro Docs: Agent Activity](https://kiro.dev/docs/agent/activity)
- Why it matters: explains the activity panel format and how to read the sub-step execution log.
-- [Kiro Docs: Settings](https://kiro.dev/docs/settings)
- Why it matters: reference for all configurable agent parameters including `allowedCommands` and `maxFileEditsPerTask`.
-
-Suggested trace strategy:
-- check the autonomy levels docs before each new task type to select the right configuration
-- review the agent activity log after every autonomous execution to build intuition for normal vs. anomalous behavior
-
-## Chapter Connections
-
-- [Tutorial Index](README.md)
-- [Previous Chapter: Chapter 3: Agent Steering and Rules Configuration](03-agent-steering-and-rules-configuration.md)
-- [Next Chapter: Chapter 5: MCP Integration and External Tools](05-mcp-integration-and-external-tools.md)
-- [Main Catalog](../../README.md#-tutorial-catalog)
-- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
-
-### Scenario Playbook 1: Chapter 4: Autonomous Agent Mode
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 2: Chapter 4: Autonomous Agent Mode
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 3: Chapter 4: Autonomous Agent Mode
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 4: Chapter 4: Autonomous Agent Mode
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 5: Chapter 4: Autonomous Agent Mode
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 6: Chapter 4: Autonomous Agent Mode
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 7: Chapter 4: Autonomous Agent Mode
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 8: Chapter 4: Autonomous Agent Mode
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 9: Chapter 4: Autonomous Agent Mode
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 10: Chapter 4: Autonomous Agent Mode
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 11: Chapter 4: Autonomous Agent Mode
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 12: Chapter 4: Autonomous Agent Mode
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 13: Chapter 4: Autonomous Agent Mode
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 14: Chapter 4: Autonomous Agent Mode
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 15: Chapter 4: Autonomous Agent Mode
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 16: Chapter 4: Autonomous Agent Mode
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
+```mermaid
+flowchart TD
+ A[tasks.md] --> B[Autonomous agent picks task 1]
+ B --> C{Autonomy level?}
+ C -->|supervised| D[Show plan, await approval]
+ C -->|autonomous| E[Execute directly]
+ D -->|approved| E
+ E --> F[Code changes applied]
+ F --> G{High-stakes action?}
+ G -->|yes| H[Pause for checkpoint]
+ G -->|no| I[Mark task complete]
+ H -->|approved| I
+ I --> J[Next task]
+```
\ No newline at end of file
diff --git a/tutorials/kiro-tutorial/05-mcp-integration-and-external-tools.md b/tutorials/kiro-tutorial/05-mcp-integration-and-external-tools.md
index f5dc5936..445a6f91 100644
--- a/tutorials/kiro-tutorial/05-mcp-integration-and-external-tools.md
+++ b/tutorials/kiro-tutorial/05-mcp-integration-and-external-tools.md
@@ -5,6 +5,7 @@ nav_order: 5
parent: Kiro Tutorial
---
+
# Chapter 5: MCP Integration and External Tools
Welcome to **Chapter 5: MCP Integration and External Tools**. In this part of **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
@@ -222,368 +223,27 @@ Next: [Chapter 6: Hooks and Automation](06-hooks-and-automation.md)
## Depth Expansion Playbook
-<!-- depth-expansion-v2 -->
-
-This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
-
-### Strategic Context
-
-- tutorial: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- tutorial slug: **kiro-tutorial**
-- chapter focus: **Chapter 5: MCP Integration and External Tools**
-- system context: **Kiro Tutorial**
-- objective: move from surface-level usage to repeatable engineering operation
-
-### Architecture Decomposition
-
-1. Define the runtime boundary for `Chapter 5: MCP Integration and External Tools` — Kiro as the MCP client, external MCP servers as tool providers, and the agent as the tool consumer.
-2. Separate control-plane decisions (which servers to connect, tool scoping, auth configuration) from data-plane execution (tool invocations, response parsing).
-3. Capture input contracts: `.kiro/mcp.json` server definitions; output: tool results injected into agent context.
-4. Trace state transitions: config written → workspace restart → server process started → tools registered → agent invokes tools → results returned.
-5. Identify extension hooks: custom MCP server implementations, remote SSE/HTTP transports, per-tool access controls.
-6. Map ownership boundaries: platform team owns shared remote MCP servers; individual developers own local server configs; security team approves tool scopes.
-7. Specify rollback paths: remove server entry from `mcp.json` and restart workspace; revert to previous `mcp.json` via git.
-8. Track observability signals: tool invocation logs, latency per tool call, error rates per MCP server, credential rotation alerts.
-
-### Operator Decision Matrix
-
-| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
-|:--------------|:--------------|:------------------|:---------|
-| Server type | well-known community MCP packages | custom internal MCP server | ease vs specificity |
-| Auth method | env var references in mcp.json | secret manager integration | simplicity vs security posture |
-| Tool scope | all tools from a server enabled | explicit tool allowlist per server | ease vs least-privilege |
-| Deployment | local npx-based servers | containerized remote servers | zero-setup vs isolation |
-| Audit logging | none | full tool invocation audit log | performance vs compliance |
-
-### Failure Modes and Countermeasures
-
-| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
-|:-------------|:-------------|:-------------------|:---------------|
-| MCP server not found | agent reports tool unavailable | server not started or misconfigured | verify server entry in mcp.json and restart workspace |
-| credential exposure | hardcoded token in mcp.json committed to git | developer bypassed env var pattern | scan mcp.json in CI; enforce env var references |
-| tool call timeout | agent stalls waiting for tool response | remote MCP server unavailable or slow | set timeout in mcp.json; add health check for remote servers |
-| overprivileged tool | agent queries production data unintentionally | read-write access granted to data source | restrict MCP server to read-only role for non-production use |
-| schema mismatch | tool returns unexpected response format | upstream API changed without updating server | add schema validation to custom MCP server response handler |
-| context overflow from large tool responses | agent loses context after tool call | tool returns unfiltered large dataset | add response size limits and pagination to custom MCP servers |
-
-### Implementation Runbook
-
-1. Identify the external data sources or APIs needed for the current feature spec.
-2. Select or build an MCP server for each data source.
-3. Configure each server in `.kiro/mcp.json` using environment variable references for all credentials.
-4. Restart the Kiro workspace to load the new MCP configuration.
-5. Verify each server is listed as active in Kiro settings and test one tool call per server.
-6. Update the relevant steering file (`project.md` or a new `mcp.md`) to document available MCP tools.
-7. Add MCP tool invocations to relevant tasks in `tasks.md` where external data is needed.
-8. Monitor tool invocation logs during the first autonomous task execution that uses MCP tools.
-9. Commit `mcp.json` to version control with a note listing which environment variables must be set by each developer.
-
-### Quality Gate Checklist
-
-- [ ] all credentials in mcp.json use environment variable references, not hardcoded values
-- [ ] each MCP server is verified active in Kiro settings before task delegation
-- [ ] tool scopes are restricted to the minimum access required for each server
-- [ ] a `.env.example` file documents the required environment variables for MCP servers
-- [ ] remote MCP servers have a health check endpoint and a timeout configured
-- [ ] tool invocation logging is enabled and accessible for audit review
-- [ ] mcp.json is committed to version control with a clear setup README
-- [ ] CI scans mcp.json and related files for hardcoded credentials on every PR
-
-### Source Alignment
-
-- [Kiro Docs: MCP](https://kiro.dev/docs/mcp)
-- [Kiro Docs: MCP Configuration](https://kiro.dev/docs/mcp/configuration)
-- [MCP Specification](https://spec.modelcontextprotocol.io)
-- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
-- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
-- [MCP Server Registry](https://github.com/modelcontextprotocol/servers)
-
-### Cross-Tutorial Connection Map
-
-- [MCP TypeScript SDK Tutorial](../mcp-typescript-sdk-tutorial/)
-- [MCP Python SDK Tutorial](../mcp-python-sdk-tutorial/)
-- [Awesome MCP Servers Tutorial](../awesome-mcp-servers-tutorial/)
-- [Claude Code Tutorial](../claude-code-tutorial/)
-- [Chapter 6: Hooks and Automation](06-hooks-and-automation.md)
-
-### Advanced Practice Exercises
-
-1. Configure three different MCP servers (GitHub, PostgreSQL, and a custom one) and verify each with a targeted tool call.
-2. Build a minimal custom MCP server that exposes one tool reading from a local JSON config file and register it in Kiro.
-3. Simulate a credential exposure incident by hardcoding a test token in mcp.json, then fix it with env var references and add a CI scan.
-4. Create a Kiro task that requires data from two different MCP servers and confirm the agent orchestrates both tool calls correctly.
-5. Set up a remote MCP server with an HTTP transport and configure a timeout; test the timeout behavior by intentionally delaying the server response.
-
-### Review Questions
-
-1. What is the difference between a local stdio-based MCP server and a remote HTTP-based MCP server, and when should you use each?
-2. Why should all credentials in mcp.json use environment variable references rather than hardcoded values?
-3. What tradeoff did you make between enabling all tools from a server and restricting to an explicit allowlist?
-4. How would you recover if a custom MCP server returned a schema-breaking response that corrupted an in-progress autonomous task?
-5. What must be in the project's README before team members can use a shared MCP configuration?
-
-### Scenario Playbook 1: MCP - Server Not Launching
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: agent reports a tool is unavailable after mcp.json was updated with a new server
-- initial hypothesis: the MCP server process failed to start due to a missing npm package or wrong command path
-- immediate action: run the server command manually in the terminal to see the startup error
-- engineering control: add a startup health check to the mcp.json server entry and verify it passes after workspace restart
-- verification target: the server appears as active in Kiro settings and a test tool call succeeds
-- rollback trigger: if the server cannot start after three attempts, remove the entry from mcp.json and use a fallback approach
-- communication step: document the startup error and fix in the project's MCP setup README
-- learning capture: add a pre-installation step to the MCP onboarding guide that verifies the required npm packages are installed
-
-### Scenario Playbook 2: MCP - Credential Hardcoded in mcp.json
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: a code review catches a real API token hardcoded in mcp.json before it is merged
-- initial hypothesis: the developer copied a working token from a local test rather than using an env var reference
-- immediate action: immediately revoke the exposed token and issue a new one before merging the PR
-- engineering control: replace the hardcoded value with `${ENV_VAR_NAME}` and add the variable to `.env.example`
-- verification target: gitleaks scan on the PR shows zero secrets in mcp.json after the fix
-- rollback trigger: if the token was already merged to main, treat it as a confirmed secret exposure and escalate
-- communication step: notify the security team and the token owner of the exposure within one hour
-- learning capture: add a required gitleaks check to the PR pipeline targeting the `.kiro/` directory
+## Source Code Walkthrough
-### Scenario Playbook 3: MCP - Tool Call Timeout During Autonomous Task
+> **Note:** Kiro is a proprietary AWS IDE; the [`kirodotdev/Kiro`](https://github.com/kirodotdev/Kiro) public repository contains documentation and GitHub automation scripts rather than the IDE's source code. The authoritative references for this chapter are the official Kiro documentation and configuration files within your project's `.kiro/` directory.
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: autonomous agent stalls waiting for a response from a remote MCP server during task execution
-- initial hypothesis: the remote MCP server is unavailable or experiencing high latency
-- immediate action: interrupt the agent and check the remote server's health endpoint
-- engineering control: add a `timeout` field to the mcp.json server entry and implement a fallback behavior in the task
-- verification target: re-run the task with timeout configured; agent fails gracefully within the timeout window
-- rollback trigger: if the remote server is consistently unavailable, switch to a local MCP server for the same data source
-- communication step: file an incident report for the remote MCP server team with the timeout details and impact
-- learning capture: add timeout configuration as a required field in the team's MCP server onboarding template
+### [Kiro Docs: MCP](https://kiro.dev/docs/mcp)
-### Scenario Playbook 4: MCP - Overprivileged Database Access
+The MCP guide documents how to configure MCP servers in `.kiro/settings.json`, the supported transport types (stdio, SSE), and how Kiro exposes MCP tools in the Chat panel and autonomous agent task execution.
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: agent accidentally modifies production database records through an MCP server with write access
-- initial hypothesis: the PostgreSQL MCP server was configured with a read-write database role
-- immediate action: revoke the write permissions from the MCP server's database role immediately
-- engineering control: create a dedicated read-only database user for MCP server connections and update mcp.json
-- verification target: confirm the agent cannot execute INSERT, UPDATE, or DELETE statements through the MCP server
-- rollback trigger: if the database modification caused data corruption, initiate the database recovery runbook
-- communication step: notify the DBA team and affected data owners of the unauthorized modification within 30 minutes
-- learning capture: add a mandatory read-only access requirement to the security steering file for all MCP database servers
+### [.kiro/settings.json — MCP server configuration](https://kiro.dev/docs/mcp)
-### Scenario Playbook 5: MCP - Large Tool Response Causes Context Overflow
+MCP server configuration lives in `.kiro/settings.json` under the `mcpServers` key. The schema specifies `command`, `args`, `env`, and `disabled` fields for each server — examining this file in a Kiro project shows the exact configuration format.
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: agent loses coherence after receiving a large unfiltered response from an MCP tool (e.g., thousands of GitHub issues)
-- initial hypothesis: the tool response exceeds the agent's effective context window, pushing out earlier task context
-- immediate action: interrupt the agent and redesign the tool call to return only the top 10 most relevant results
-- engineering control: add response size limits and filtering parameters to the custom MCP server's tool schema
-- verification target: re-run the agent task with the filtered tool call; agent maintains context through task completion
-- rollback trigger: if filtering removes critical data, implement pagination and chain two agent calls instead of one
-- communication step: update the tool's documentation in the MCP server README with the recommended query parameters
-- learning capture: add a maximum response size guideline to the team's custom MCP server development standards
+## How These Components Connect
-## What Problem Does This Solve?
-
-Agentic coding IDEs are limited to what they can see in the local workspace. Kiro's MCP integration breaks this boundary by connecting agents to the full context of an engineering organization: issue trackers, documentation wikis, internal APIs, database schemas, and feature flag systems. This means agents can generate code that references the actual current state of external systems, not just what is hardcoded in the repo.
-
-In practical terms, this chapter helps you avoid three common failures:
-
-- generating code against stale or assumed API contracts because the agent cannot see the live API schema
-- writing tasks that require human lookups from external systems, breaking the autonomous execution flow
-- integrating with external tools through ad-hoc prompt stuffing instead of structured, auditable tool calls
-
-After working through this chapter, you should be able to treat MCP servers as the API boundary between Kiro agents and your organization's full data ecosystem.
-
-## How it Works Under the Hood
-
-Under the hood, `Chapter 5: MCP Integration and External Tools` follows a repeatable control path:
-
-1. **Server registration**: at workspace load, Kiro reads `mcp.json` and starts each server process using the configured command.
-2. **Tool discovery**: Kiro sends a `tools/list` request to each server and registers the returned tool schemas.
-3. **Context injection**: available tool names and schemas are injected into the agent's system prompt.
-4. **Tool dispatch**: when the agent decides to use a tool, Kiro sends a `tools/call` request to the appropriate server process.
-5. **Response integration**: the server's response is formatted and injected into the agent's next context block.
-6. **Audit logging**: each tool invocation with its arguments and response size is logged for security and debugging.
-
-When debugging MCP issues, trace this sequence from server startup through tool registration before investigating individual tool calls.
-
-## Source Walkthrough
-
-Use the following upstream sources to verify implementation details while reading this chapter:
-
-- [Kiro Docs: MCP](https://kiro.dev/docs/mcp)
- Why it matters: the primary reference for how Kiro implements MCP client behavior and mcp.json format.
-- [MCP Specification](https://spec.modelcontextprotocol.io)
- Why it matters: the canonical protocol definition for tools/list and tools/call message formats.
-- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
- Why it matters: the official SDK for building custom MCP servers in TypeScript.
-- [MCP Server Registry](https://github.com/modelcontextprotocol/servers)
- Why it matters: the community catalog of ready-to-use MCP servers for common data sources.
-
-Suggested trace strategy:
-- check the MCP server registry before building a custom server to avoid duplicating existing work
-- test each new MCP server with a direct stdio call before registering it in mcp.json to isolate startup issues
-
-## Chapter Connections
-
-- [Tutorial Index](README.md)
-- [Previous Chapter: Chapter 4: Autonomous Agent Mode](04-autonomous-agent-mode.md)
-- [Next Chapter: Chapter 6: Hooks and Automation](06-hooks-and-automation.md)
-- [Main Catalog](../../README.md#-tutorial-catalog)
-- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
-
-### Scenario Playbook 1: Chapter 5: MCP Integration and External Tools
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 2: Chapter 5: MCP Integration and External Tools
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 3: Chapter 5: MCP Integration and External Tools
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 4: Chapter 5: MCP Integration and External Tools
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 5: Chapter 5: MCP Integration and External Tools
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 6: Chapter 5: MCP Integration and External Tools
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 7: Chapter 5: MCP Integration and External Tools
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 8: Chapter 5: MCP Integration and External Tools
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 9: Chapter 5: MCP Integration and External Tools
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 10: Chapter 5: MCP Integration and External Tools
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 11: Chapter 5: MCP Integration and External Tools
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 12: Chapter 5: MCP Integration and External Tools
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 13: Chapter 5: MCP Integration and External Tools
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
+```mermaid
+flowchart TD
+ A[.kiro/settings.json mcpServers] --> B[MCP server process]
+ B --> C[stdio or SSE transport]
+ C --> D[MCP tool definitions]
+ D --> E[Kiro Chat panel tools]
+ D --> F[Autonomous agent tools]
+ E --> G[Developer invokes tool]
+ F --> H[Agent invokes tool in task]
+```
\ No newline at end of file
diff --git a/tutorials/kiro-tutorial/06-hooks-and-automation.md b/tutorials/kiro-tutorial/06-hooks-and-automation.md
index 4497954c..9d454843 100644
--- a/tutorials/kiro-tutorial/06-hooks-and-automation.md
+++ b/tutorials/kiro-tutorial/06-hooks-and-automation.md
@@ -5,6 +5,7 @@ nav_order: 6
parent: Kiro Tutorial
---
+
# Chapter 6: Hooks and Automation
Welcome to **Chapter 6: Hooks and Automation**. In this part of **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
@@ -211,379 +212,26 @@ Next: [Chapter 7: Multi-Model Strategy and Providers](07-multi-model-strategy-an
## Depth Expansion Playbook
-<!-- depth-expansion-v2 -->
-
-This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
-
-### Strategic Context
-
-- tutorial: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- tutorial slug: **kiro-tutorial**
-- chapter focus: **Chapter 6: Hooks and Automation**
-- system context: **Kiro Tutorial**
-- objective: move from surface-level usage to repeatable engineering operation
-
-### Architecture Decomposition
-
-1. Define the runtime boundary for `Chapter 6: Hooks and Automation` — the `.kiro/hooks/` directory as the event rule store, the Kiro event bus as the trigger dispatcher, and the agent as the action executor.
-2. Separate control-plane decisions (which events to hook, condition design) from data-plane execution (agent action invocation, file modification, chat output).
-3. Capture input contracts: hook file with event type, condition expression, and action description; output: agent-executed action on trigger.
-4. Trace state transitions: hook file written → workspace restart → event bus registers hook → event fires → condition evaluated → agent action invoked → output produced.
-5. Identify extension hooks: custom event types via MCP, condition expression extensions, action scope constraints.
-6. Map ownership boundaries: developers own feature-specific hooks; team leads own shared hooks in the repository; security team approves hooks that trigger git or publish operations.
-7. Specify rollback paths: disable hook by adding `.disabled` extension; revert hook file via git; restart workspace to clear in-flight hook executions.
-8. Track observability signals: hook activation frequency, agent action token usage per hook, false-positive activation rate, hook-induced test failures.
-
-### Operator Decision Matrix
-
-| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
-|:--------------|:--------------|:------------------|:---------|
-| Hook scope | narrow file-pattern conditions | broad event hooks with explicit exclusions | simplicity vs coverage |
-| Agent action type | read-only analysis and reporting | write operations on source files | safety vs automation level |
-| Activation frequency | save-level hooks with debounce | commit-level or task-complete hooks | responsiveness vs cost |
-| Output channel | chat panel notifications | log file writes for audit | visibility vs noise |
-| Hook governance | individual developer hooks | team-reviewed hooks committed to git | velocity vs consistency |
-
-### Failure Modes and Countermeasures
-
-| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
-|:-------------|:-------------|:-------------------|:---------------|
-| infinite loop | hook activates repeatedly on same file | hook modifies the file that triggered it | add exclusion for agent output files in condition |
-| token cost spike | unexpectedly high daily token usage | hook activates on high-frequency events without conditions | add specific conditions to reduce activation rate |
-| noisy chat | chat panel fills with hook notifications | hook outputs to chat on common events | redirect output to a log file for low-priority hooks |
-| unexpected file edit | agent modifies unintended files during hook | underconstrained action description | add explicit "do not modify files other than X" constraint in action |
-| hook ordering conflict | two hooks produce conflicting changes to the same file | overlapping hook triggers | use numeric prefix to serialize execution; add mutual exclusion conditions |
-| slow workspace | every save triggers multiple concurrent agent invocations | too many broad hooks active simultaneously | audit hook conditions and consolidate overlapping triggers |
-
-### Implementation Runbook
-
-1. Create `.kiro/hooks/` in the project root.
-2. Identify the three highest-value repetitive manual workflows in your daily development cycle.
-3. Write one hook file per workflow using the event/condition/action format.
-4. Save a test file to trigger the first `file:save` hook and verify the agent's action output.
-5. Check the agent activity log for the hook invocation and confirm the output is correct.
-6. Add numeric prefixes to hooks that share the same event to control execution order.
-7. Test the full hook set after a real coding session and identify any noise or false activations.
-8. Refine condition expressions to reduce false activations and commit the final hook set.
-9. Document each hook's purpose and expected behavior in a `.kiro/hooks/README.md`.
-
-### Quality Gate Checklist
-
-- [ ] all hooks have a condition expression to prevent broad activation
-- [ ] no hook modifies a file that could re-trigger the same event (infinite loop prevention)
-- [ ] hook action descriptions include explicit scope constraints on file modifications
-- [ ] hooks are tested with a real event before committing to version control
-- [ ] high-frequency event hooks (file:save) use specific file pattern conditions
-- [ ] a hooks README documents each hook's purpose and expected activation rate
-- [ ] token usage is monitored after adding new hooks for the first week
-- [ ] disabled hooks use the `.disabled` extension naming convention for easy re-enabling
-
-### Source Alignment
-
-- [Kiro Docs: Hooks](https://kiro.dev/docs/hooks)
-- [Kiro Docs: Hook Events](https://kiro.dev/docs/hooks/events)
-- [Kiro Docs: Hook Conditions](https://kiro.dev/docs/hooks/conditions)
-- [Kiro Docs: Hook Action Constraints](https://kiro.dev/docs/hooks/actions)
-- [Kiro Repository](https://github.com/kirodotdev/Kiro)
-
-### Cross-Tutorial Connection Map
-
-- [Claude Code Tutorial](../claude-code-tutorial/)
-- [N8N AI Tutorial](../n8n-ai-tutorial/)
-- [Activepieces Tutorial](../activepieces-tutorial/)
-- [GitHub MCP Server Tutorial](../github-mcp-server-tutorial/)
-- [Chapter 7: Multi-Model Strategy and Providers](07-multi-model-strategy-and-providers.md)
-
-### Advanced Practice Exercises
-
-1. Build a hook that triggers on test failure, analyzes the failing test, and writes a diagnostic summary to a log file.
-2. Create a hook that checks documentation freshness when API files are committed and lists stale doc sections.
-3. Simulate an infinite loop scenario by creating a hook that modifies the file it watches; then fix it with an exclusion condition.
-4. Monitor token usage for one week with three active hooks and calculate the cost per activation for each hook type.
-5. Design a hook governance proposal: define which hooks require team review before merging to main and which can be individual developer hooks.
-
-### Review Questions
-
-1. What is the difference between a `file:save` hook and a `git:commit` hook, and when is each more appropriate?
-2. How do you prevent an infinite loop when a hook agent modifies a source file?
-3. What tradeoff did you make between hook responsiveness (save-level) and token efficiency (commit-level)?
-4. How would you recover if a hook introduced a test failure by auto-applying a lint fix that broke logic?
-5. What governance process should control hooks that trigger write operations on shared source files?
-
-### Scenario Playbook 1: Hooks - Infinite Loop
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: a file:save hook that applies lint fixes re-triggers itself every time it saves the fixed file
-- initial hypothesis: the hook condition does not exclude the files the agent modifies after applying fixes
-- immediate action: disable the hook immediately by adding the `.disabled` extension to stop the loop
-- engineering control: add `file not matches ".kiro/agent-output/**"` or a similar exclusion to the hook condition
-- verification target: save a TypeScript file and confirm the hook activates only once per developer save
-- rollback trigger: if the exclusion condition is too broad and blocks legitimate activations, narrow the exclusion pattern
-- communication step: document the infinite loop incident and fix in the hooks README
-- learning capture: add "check for self-triggering loops" as a required review step in the hook PR checklist
-
-### Scenario Playbook 2: Hooks - Token Cost Spike
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: daily token usage spikes after adding a file:save hook without a file pattern condition
-- initial hypothesis: the hook is activating on every file save including node_modules and build artifacts
-- immediate action: disable the hook and check the activation log for unexpected trigger files
-- engineering control: add a specific file pattern condition: `file matches "src/**/*.ts" AND file not matches "node_modules/**"`
-- verification target: token usage returns to baseline levels after the condition is applied
-- rollback trigger: if token cost remains high after condition refinement, switch the event to `git:commit` instead of `file:save`
-- communication step: share the token cost findings with the team and add a token budget guideline to the hook governance doc
-- learning capture: add token cost estimation to the hook design process before activating a new hook in production
+## Source Code Walkthrough
-### Scenario Playbook 3: Hooks - Noisy Chat Panel
+> **Note:** Kiro is a proprietary AWS IDE; the [`kirodotdev/Kiro`](https://github.com/kirodotdev/Kiro) public repository contains documentation and GitHub automation scripts rather than the IDE's source code. The authoritative references for this chapter are the official Kiro documentation and configuration files within your project's `.kiro/` directory.
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: the chat panel is filled with low-value hook notifications every time a file is saved
-- initial hypothesis: the hook is configured to output its findings to the chat panel for events that occur too frequently
-- immediate action: redirect the hook's output from chat to a log file: `.kiro/hook-log.md`
-- engineering control: use chat output only for high-priority hooks (test failure analysis, security warnings); use log files for routine hooks
-- verification target: chat panel shows only actionable notifications; routine logs are in `.kiro/hook-log.md`
-- rollback trigger: if log file grows too large, add a rotation mechanism or summarize logs daily
-- communication step: update the hooks README with the output channel conventions for the team
-- learning capture: add output channel selection as a required design decision in the hook template
+### [Kiro Docs: Hooks](https://kiro.dev/docs/hooks)
-### Scenario Playbook 4: Hooks - Unexpected File Edit
+The hooks documentation covers hook configuration in `.kiro/hooks/`, the supported trigger events (file save, test complete, task complete, custom), condition syntax, and the agent prompt template that executes when a hook fires.
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: a hook agent modifies files beyond the intended scope during a file:save trigger
-- initial hypothesis: the hook action description was underspecified and allowed the agent to infer additional scope
-- immediate action: revert the unintended file modifications using `git checkout`
-- engineering control: add explicit "do not modify files other than the saved file" constraint to the hook action description
-- verification target: re-trigger the hook and confirm only the specified file is modified
-- rollback trigger: if the constraint causes the hook to produce incomplete output, split into two hooks with different scopes
-- communication step: document the out-of-scope modification in the hook's revision history
-- learning capture: add scope constraint as a mandatory field in the hook file template
+### [.kiro/hooks/ directory structure](https://kiro.dev/docs/hooks)
-### Scenario Playbook 5: Hooks - Hook Ordering Conflict
+Each hook is a Markdown file in `.kiro/hooks/` with YAML front-matter specifying `trigger`, `condition`, and `agent` fields, followed by the prompt body. Inspecting existing hook files shows the schema that drives the event-driven automation described in this chapter.
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: two hooks triggered by the same file:save event produce conflicting changes to the same file
-- initial hypothesis: both hooks modify the same file without coordination, and their execution order is non-deterministic
-- immediate action: disable the conflicting hook and manually merge the intended changes
-- engineering control: add numeric prefixes to both hooks to enforce serial execution and add a mutual exclusion condition to the second hook
-- verification target: save a test file and confirm hook 1 completes before hook 2 activates, with no conflicting changes
-- rollback trigger: if serial execution still produces conflicts, merge the two hooks into one combined hook
-- communication step: document the merge decision and the new combined hook in the team's hooks change log
-- learning capture: add a "check for file overlap with existing hooks" step to the hook PR review checklist
+## How These Components Connect
-## What Problem Does This Solve?
-
-Repetitive manual workflows are the silent tax on engineering productivity. Every time a developer saves a file and then manually runs lint, checks test failures, and updates documentation, they are doing work that follows a predictable pattern. Kiro hooks eliminate this tax by encoding the "what happens next" logic as event-driven agents that run automatically.
-
-In practical terms, this chapter helps you avoid three common failures:
-
-- letting lint errors accumulate because running the linter is a separate manual step that gets skipped under deadline pressure
-- discovering test failures hours after they were introduced because no automated analysis ran at the point of change
-- letting documentation drift because doc updates are always "the next task" that never gets done
-
-After working through this chapter, you should be able to treat `.kiro/hooks/` as a team-owned library of automation patterns that encode the team's quality practices as first-class workspace behavior.
-
-## How it Works Under the Hood
-
-Under the hood, `Chapter 6: Hooks and Automation` follows a repeatable control path:
-
-1. **Hook registration**: at workspace open, Kiro scans `.kiro/hooks/` and registers each hook with the event bus.
-2. **Event detection**: the Kiro event bus monitors workspace state for registered event types.
-3. **Condition evaluation**: when an event fires, Kiro evaluates the hook's condition expression against the event context.
-4. **Agent dispatch**: if the condition passes, Kiro dispatches the hook action to an agent with the event context as input.
-5. **Action execution**: the agent executes the action, potentially reading files, writing output, or running commands.
-6. **Result routing**: the agent's output is routed to the configured channel (chat panel or log file).
-
-When debugging hook issues, verify each stage: hook registered, event fired, condition evaluated, agent dispatched, action completed, output routed.
-
-## Source Walkthrough
-
-Use the following upstream sources to verify implementation details while reading this chapter:
-
-- [Kiro Docs: Hooks](https://kiro.dev/docs/hooks)
- Why it matters: the primary reference for hook file format, event types, and condition syntax.
-- [Kiro Docs: Hook Events](https://kiro.dev/docs/hooks/events)
- Why it matters: documents all available event types and the context data available for condition evaluation.
-- [Kiro Docs: Hook Conditions](https://kiro.dev/docs/hooks/conditions)
- Why it matters: defines the condition expression language and supported operators.
-- [Kiro Docs: Hook Action Constraints](https://kiro.dev/docs/hooks/actions)
- Why it matters: explains how to scope hook agent actions to prevent unintended side effects.
-
-Suggested trace strategy:
-- check the hook events docs for the exact context variables available before writing condition expressions
-- test each hook with the minimal possible condition before expanding to broader file pattern matching
-
-## Chapter Connections
-
-- [Tutorial Index](README.md)
-- [Previous Chapter: Chapter 5: MCP Integration and External Tools](05-mcp-integration-and-external-tools.md)
-- [Next Chapter: Chapter 7: Multi-Model Strategy and Providers](07-multi-model-strategy-and-providers.md)
-- [Main Catalog](../../README.md#-tutorial-catalog)
-- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
-
-### Scenario Playbook 1: Chapter 6: Hooks and Automation
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 2: Chapter 6: Hooks and Automation
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 3: Chapter 6: Hooks and Automation
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 4: Chapter 6: Hooks and Automation
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 5: Chapter 6: Hooks and Automation
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 6: Chapter 6: Hooks and Automation
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 7: Chapter 6: Hooks and Automation
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 8: Chapter 6: Hooks and Automation
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 9: Chapter 6: Hooks and Automation
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 10: Chapter 6: Hooks and Automation
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 11: Chapter 6: Hooks and Automation
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 12: Chapter 6: Hooks and Automation
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 13: Chapter 6: Hooks and Automation
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 14: Chapter 6: Hooks and Automation
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
+```mermaid
+flowchart TD
+ A[File save event] --> B{Match .kiro/hooks/ condition?}
+ B -->|yes| C[Hook fires]
+ B -->|no| D[Ignored]
+ C --> E[Agent prompt executes]
+ E --> F[Agent action: format, test, lint]
+ F --> G[Changes applied to workspace]
+```
\ No newline at end of file
diff --git a/tutorials/kiro-tutorial/07-multi-model-strategy-and-providers.md b/tutorials/kiro-tutorial/07-multi-model-strategy-and-providers.md
index 0be964f4..d1a33864 100644
--- a/tutorials/kiro-tutorial/07-multi-model-strategy-and-providers.md
+++ b/tutorials/kiro-tutorial/07-multi-model-strategy-and-providers.md
@@ -5,6 +5,7 @@ nav_order: 7
parent: Kiro Tutorial
---
+
# Chapter 7: Multi-Model Strategy and Providers
Welcome to **Chapter 7: Multi-Model Strategy and Providers**. In this part of **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
@@ -180,403 +181,27 @@ Next: [Chapter 8: Team Operations and Governance](08-team-operations-and-governa
## Depth Expansion Playbook
-<!-- depth-expansion-v2 -->
-
-This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
-
-### Strategic Context
-
-- tutorial: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- tutorial slug: **kiro-tutorial**
-- chapter focus: **Chapter 7: Multi-Model Strategy and Providers**
-- system context: **Kiro Tutorial**
-- objective: move from surface-level usage to repeatable engineering operation
-
-### Architecture Decomposition
-
-1. Define the runtime boundary for `Chapter 7: Multi-Model Strategy and Providers` — the model routing layer, the budget controller, and the provider API gateway.
-2. Separate control-plane decisions (model selection, routing policy, budget limits) from data-plane execution (token generation, inference calls).
-3. Capture input contracts: task type classification from interaction context; output: model-routed inference request and response.
-4. Trace state transitions: task initiated → type classified → routing rule applied → model selected → request sent → response received → cost tracked.
-5. Identify extension hooks: custom routing rules per task type, budget action policies, provider failover paths.
-6. Map ownership boundaries: developers choose fast/primary preference; team leads set routing policy; finance owns budget limits.
-7. Specify rollback paths: switch routing back to previous model; restore budget settings from version control.
-8. Track observability signals: token consumption per model per task type, cost per session, budget threshold alerts, model latency distribution.
-
-### Operator Decision Matrix
-
-| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
-|:--------------|:--------------|:------------------|:---------|
-| Model selection | Kiro defaults (Sonnet 4.0 primary) | explicit routing per task type | ease vs cost optimization |
-| Budget controls | monthly soft cap with notification | daily hard cap with auto-restrict | flexibility vs cost certainty |
-| Upgrade cadence | upgrade immediately on release | validation protocol before upgrade | speed vs quality assurance |
-| Usage monitoring | check manually via /usage | automated daily usage reports | effort vs visibility |
-| Cost allocation | project-level budget | per-developer or per-team budgets | simplicity vs granularity |
-
-### Failure Modes and Countermeasures
-
-| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
-|:-------------|:-------------|:-------------------|:---------------|
-| budget overrun | unexpected high token usage | hooks or autonomous tasks using primary model at high frequency | audit routing config and redirect high-frequency actions to fast model |
-| model quality regression | lower spec generation quality after upgrade | new model performs differently on the team's task profile | run quality benchmark before upgrading primary model |
-| provider outage | 503 errors on model API calls | Anthropic service disruption | configure fallback model or degrade to interactive-only mode |
-| token waste on large contexts | high input token counts for simple tasks | full codebase context sent for small tasks | scope context explicitly in task descriptions |
-| routing misconfiguration | wrong model used for expensive tasks | misconfigured routing JSON | audit routing config and verify with /usage after changes |
-| cost spike from hook frequency | daily budget hits threshold early | save-level hooks using primary model | switch hook routing to fast model and add conditions to reduce frequency |
-
-### Implementation Runbook
-
-1. Review the Kiro model documentation to understand the current Claude Sonnet 4.0 and 3.7 capability profiles.
-2. Map your team's top five task types to the appropriate model tier based on quality vs. cost priority.
-3. Configure the routing policy in Kiro settings or `.kiro/settings.json`.
-4. Set a daily token budget with a notify action at 80% of the limit.
-5. Run a full one-day session with the new configuration and review the `/usage` output.
-6. Identify the three highest-cost task types and optimize their routing or context scope.
-7. Set the monthly budget with a restrict action at 90% of the limit.
-8. Document the model routing rationale in `.kiro/settings.json` comments for team transparency.
-9. Schedule a quarterly model upgrade review to assess whether new Claude versions improve quality or reduce cost.
-
-### Quality Gate Checklist
-
-- [ ] routing policy is explicitly configured for at least five task types in settings
-- [ ] daily and monthly token budgets are set with appropriate alert thresholds
-- [ ] budget action for monthly limit is set to `restrict` or `pause` to prevent overruns
-- [ ] `/usage` is reviewed after the first full day with the new routing configuration
-- [ ] high-frequency hook actions are routed to the fast model
-- [ ] a model upgrade validation protocol is documented before the first upgrade
-- [ ] routing configuration is committed to version control with clear comments
-- [ ] team members are informed of the routing policy and budget limits
-
-### Source Alignment
-
-- [Kiro Docs: Model Configuration](https://kiro.dev/docs/models)
-- [Kiro Docs: Budget Controls](https://kiro.dev/docs/models/budget)
-- [Kiro Docs: Usage Dashboard](https://kiro.dev/docs/models/usage)
-- [Anthropic Models Overview](https://docs.anthropic.com/en/docs/models-overview)
-- [Kiro Repository](https://github.com/kirodotdev/Kiro)
-
-### Cross-Tutorial Connection Map
-
-- [LiteLLM Tutorial](../litellm-tutorial/)
-- [Claude Code Tutorial](../claude-code-tutorial/)
-- [OpenCode Tutorial](../opencode-tutorial/)
-- [Cline Tutorial](../cline-tutorial/)
-- [Chapter 8: Team Operations and Governance](08-team-operations-and-governance.md)
-
-### Advanced Practice Exercises
-
-1. Configure a complete routing policy for six task types and document the quality vs. cost rationale for each routing decision.
-2. Run identical spec generation tasks with Sonnet 4.0 and Sonnet 3.7 and compare output quality in a structured evaluation table.
-3. Simulate a budget overrun by setting a very low daily limit and observe the restrict action behavior; then restore the correct limit.
-4. Build a model upgrade validation checklist for your team's specific task profile and run it against a hypothetical new Claude version.
-5. Analyze one week of `/usage` output and identify the top three opportunities to reduce token consumption without reducing quality.
-
-### Review Questions
-
-1. Why does Kiro route spec generation to the primary (Sonnet 4.0) model rather than the fast model by default?
-2. What is the difference between the `restrict` and `pause` budget actions, and when should you use each?
-3. What tradeoff did you make between model quality and cost when routing hook actions to the fast model?
-4. How would you validate that a new Claude model version is safe to use as the primary routing target for your team's spec generation tasks?
-5. What conditions trigger an automatic routing switch in Kiro's budget control system?
-
-### Scenario Playbook 1: Model Strategy - Budget Overrun from Hook Frequency
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: daily token budget alert fires at 9am because file:save hooks are consuming primary model tokens at high frequency
-- initial hypothesis: hooks are routing to the primary model and activating on every TypeScript file save in a large codebase
-- immediate action: switch all hook routing to the fast model and add file-pattern conditions to reduce activation rate
-- engineering control: update the routing config to explicitly map `hookActions` to `fast` model
-- verification target: token usage at end of day stays below 60% of the daily budget after routing change
-- rollback trigger: if fast model produces lower-quality hook outputs that are actionable, add a flag for critical hooks to use primary
-- communication step: notify the team of the routing change and explain the cost rationale
-- learning capture: add hook routing as a required configuration step in the team's Kiro onboarding checklist
-
-### Scenario Playbook 2: Model Strategy - Quality Regression After Upgrade
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: spec generation quality drops noticeably after the team upgraded to a new Claude version
-- initial hypothesis: the new model has different default behaviors for EARS requirement parsing and design generation
-- immediate action: revert the primary model routing to the previous version while the quality issue is investigated
-- engineering control: run the quality benchmark suite on the new model version and document the delta
-- verification target: benchmark scores for spec generation match or exceed the previous model version
-- rollback trigger: if the new model cannot match previous quality after prompt adjustments, remain on the previous version
-- communication step: share the benchmark results with the team and the model upgrade status
-- learning capture: add a quality benchmark run as a mandatory step before any future model version upgrade
+## Source Code Walkthrough
-### Scenario Playbook 3: Model Strategy - Provider Outage
+> **Note:** Kiro is a proprietary AWS IDE; the [`kirodotdev/Kiro`](https://github.com/kirodotdev/Kiro) public repository contains documentation and GitHub automation scripts rather than the IDE's source code. The authoritative references for this chapter are the official Kiro documentation and configuration files within your project's `.kiro/` directory.
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: Anthropic API returns 503 errors causing all Kiro model calls to fail
-- initial hypothesis: the Anthropic service is experiencing an outage affecting the Claude Sonnet endpoints
-- immediate action: check the Anthropic status page and switch Kiro to interactive-only mode for in-flight autonomous tasks
-- engineering control: configure a fallback model in Kiro settings pointing to an alternative provider if available
-- verification target: team can continue interactive chat in degraded mode while the outage is active
-- rollback trigger: restore full model routing once Anthropic reports the incident resolved
-- communication step: notify the team of the outage status and expected recovery time from the Anthropic status page
-- learning capture: add provider outage response steps to the team's Kiro incident runbook
+### [Kiro Docs: Model Configuration](https://kiro.dev/docs/models)
-### Scenario Playbook 4: Model Strategy - Token Waste on Large Contexts
+The model configuration documentation explains how to set the default model (Claude Sonnet 4.0), configure routing rules for different task profiles (chat vs. autonomous tasks), and manage budget controls in Kiro's settings.
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: `/usage` shows extremely high input token counts for tasks that should be simple
-- initial hypothesis: the agent is loading the full codebase context for tasks that only require a single file or module
-- immediate action: add explicit context constraints to the task descriptions in tasks.md: "only read files in src/auth/"
-- engineering control: update the spec generation prompt template to include a "context scope" field for each task
-- verification target: input token count per task decreases by at least 30% after scope constraints are applied
-- rollback trigger: if scope constraints cause the agent to miss necessary context, expand the scope incrementally
-- communication step: share the context scoping pattern with the team as a best practice in the Kiro usage guide
-- learning capture: add a context scope field to the tasks.md template and document the expected files per task type
+### [.kiro/settings.json — model routing](https://kiro.dev/docs/models)
-### Scenario Playbook 5: Model Strategy - Routing Misconfiguration
+Model routing configuration lives in `.kiro/settings.json` under the `models` key. The schema allows specifying different models for interactive chat and autonomous agent execution — the primary source for the multi-model strategy described in this chapter.
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: interactive chat is using the primary (Sonnet 4.0) model despite routing being configured for fast model
-- initial hypothesis: the routing configuration in settings.json has a syntax error or the key name does not match Kiro's expected format
-- immediate action: validate the settings.json against the Kiro settings schema and fix any key name mismatches
-- engineering control: add a JSON schema validation step to the CI pipeline for `.kiro/settings.json`
-- verification target: `/usage` confirms interactive chat is routed to Sonnet 3.7 after the configuration fix
-- rollback trigger: if schema validation is not feasible, revert settings.json to the last known good commit
-- communication step: share the corrected settings.json format with the team and update the configuration docs
-- learning capture: add a settings.json validation step to the Kiro onboarding checklist
+## How These Components Connect
-## What Problem Does This Solve?
-
-Most agentic coding tools treat model selection as a binary choice. Kiro's multi-model routing strategy recognizes that different task types have fundamentally different quality and cost requirements. Spec generation demands the highest-quality reasoning; interactive chat demands the lowest latency. Routing these to the same model either wastes money on fast interactions or underserves the tasks that matter most.
-
-In practical terms, this chapter helps you avoid three common failures:
-
-- paying primary-model prices for every lint check, code explanation, and quick question
-- using a fast model for spec generation and getting design documents that miss key architectural considerations
-- running out of daily token budget before the high-value autonomous tasks run
-
-After working through this chapter, you should be able to treat model routing as a cost-quality optimization policy that is explicit, versioned, and tuned to your team's actual workload distribution.
-
-## How it Works Under the Hood
-
-Under the hood, `Chapter 7: Multi-Model Strategy and Providers` follows a repeatable control path:
-
-1. **Task type classification**: Kiro inspects the interaction type (chat, spec generation, hook action, etc.) to classify the task.
-2. **Routing rule lookup**: the routing policy in settings is consulted to select the model profile for the task type.
-3. **Budget check**: before dispatching, Kiro checks the current usage against the configured budget limits.
-4. **Model API call**: Kiro sends the inference request to the Anthropic API endpoint for the selected model.
-5. **Response tracking**: the token counts from the API response are recorded against the session and daily budgets.
-6. **Usage aggregation**: the dashboard aggregates usage by model, task type, and time window for monitoring.
-
-When debugging cost or quality issues, trace this sequence from task classification through budget tracking to identify where the routing or consumption is diverging from expectations.
-
-## Source Walkthrough
-
-Use the following upstream sources to verify implementation details while reading this chapter:
-
-- [Kiro Docs: Model Configuration](https://kiro.dev/docs/models)
- Why it matters: the primary reference for routing configuration format and available model identifiers.
-- [Kiro Docs: Budget Controls](https://kiro.dev/docs/models/budget)
- Why it matters: documents the exact budget action behaviors and threshold configuration options.
-- [Anthropic Models Overview](https://docs.anthropic.com/en/docs/models-overview)
- Why it matters: the canonical reference for Claude model capabilities, context windows, and pricing tiers.
-- [Kiro Repository](https://github.com/kirodotdev/Kiro)
- Why it matters: source for model configuration schema and community discussions on routing strategies.
-
-Suggested trace strategy:
-- check the Anthropic models page before configuring routing to confirm the current model identifier strings
-- run `/usage` after each configuration change to confirm routing is working as intended
-
-## Chapter Connections
-
-- [Tutorial Index](README.md)
-- [Previous Chapter: Chapter 6: Hooks and Automation](06-hooks-and-automation.md)
-- [Next Chapter: Chapter 8: Team Operations and Governance](08-team-operations-and-governance.md)
-- [Main Catalog](../../README.md#-tutorial-catalog)
-- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
-
-### Scenario Playbook 1: Chapter 7: Multi-Model Strategy and Providers
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 2: Chapter 7: Multi-Model Strategy and Providers
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 3: Chapter 7: Multi-Model Strategy and Providers
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 4: Chapter 7: Multi-Model Strategy and Providers
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 5: Chapter 7: Multi-Model Strategy and Providers
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 6: Chapter 7: Multi-Model Strategy and Providers
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 7: Chapter 7: Multi-Model Strategy and Providers
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 8: Chapter 7: Multi-Model Strategy and Providers
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 9: Chapter 7: Multi-Model Strategy and Providers
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 10: Chapter 7: Multi-Model Strategy and Providers
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 11: Chapter 7: Multi-Model Strategy and Providers
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 12: Chapter 7: Multi-Model Strategy and Providers
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 13: Chapter 7: Multi-Model Strategy and Providers
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 14: Chapter 7: Multi-Model Strategy and Providers
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 15: Chapter 7: Multi-Model Strategy and Providers
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 16: Chapter 7: Multi-Model Strategy and Providers
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
+```mermaid
+flowchart TD
+ A[.kiro/settings.json models] --> B[Chat model: Claude Sonnet 4.0]
+ A --> C[Agent model: Claude Sonnet 3.7]
+ B --> D[Interactive conversation]
+ C --> E[Autonomous task execution]
+ D --> F[Token usage tracked]
+ E --> F
+ F --> G[Budget control gate]
+```
\ No newline at end of file
diff --git a/tutorials/kiro-tutorial/08-team-operations-and-governance.md b/tutorials/kiro-tutorial/08-team-operations-and-governance.md
index 60defd32..70fc8303 100644
--- a/tutorials/kiro-tutorial/08-team-operations-and-governance.md
+++ b/tutorials/kiro-tutorial/08-team-operations-and-governance.md
@@ -5,6 +5,7 @@ nav_order: 8
parent: Kiro Tutorial
---
+
# Chapter 8: Team Operations and Governance
Welcome to **Chapter 8: Team Operations and Governance**. In this part of **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
@@ -221,367 +222,28 @@ You now have the operational playbook for team-scale Kiro deployment: governance
## Depth Expansion Playbook
-<!-- depth-expansion-v2 -->
-
-This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
-
-### Strategic Context
-
-- tutorial: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- tutorial slug: **kiro-tutorial**
-- chapter focus: **Chapter 8: Team Operations and Governance**
-- system context: **Kiro Tutorial**
-- objective: move from surface-level usage to repeatable engineering operation
-
-### Architecture Decomposition
-
-1. Define the runtime boundary for `Chapter 8: Team Operations and Governance` — the `.kiro/` directory as the shared configuration contract, the PR review process as the governance gate, and AWS IAM Autopilot as the infrastructure automation layer.
-2. Separate control-plane decisions (PR review policies, ownership assignments, Power configurations) from data-plane execution (agent task runs, IAM analysis, hook executions).
-3. Capture input contracts: team configuration in `.kiro/`, developer workstations running Kiro, AWS account ID and CloudTrail access for IAM Autopilot.
-4. Trace state transitions: individual use → team config shared → governance review established → onboarding complete → incident response tested.
-5. Identify extension hooks: additional Kiro Powers as they are released, custom shared hook libraries, organization-level steering templates.
-6. Map ownership boundaries: security engineer owns `mcp.json` and `security.md` reviews; architecture lead owns `project.md` and `design.md` reviews; engineering manager owns budget configuration.
-7. Specify rollback paths: revert `.kiro/` configuration via git; disable Powers individually in settings; use PR-only mode for IAM Autopilot to prevent direct changes.
-8. Track observability signals: PR cycle time for `.kiro/` changes, autonomous agent incident rate, IAM Autopilot PR merge rate, team onboarding completion rate.
-
-### Operator Decision Matrix
-
-| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
-|:--------------|:--------------|:------------------|:---------|
-| Spec ownership | developer-owned specs | product owner sign-off on requirements.md | velocity vs alignment |
-| Steering governance | any developer edits | architect + security sign-off | speed vs policy integrity |
-| IAM Autopilot mode | PR-only, never direct apply | pr-only with security alert on escalation | automation vs safety |
-| Onboarding approach | self-service with docs | guided session with tech lead | scale vs quality |
-| Incident response | informal revert + fix | structured runbook with postmortem | effort vs learning |
-
-### Failure Modes and Countermeasures
-
-| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
-|:-------------|:-------------|:-------------------|:---------------|
-| steering drift | agent behavior inconsistency across developers | no review process for steering changes | require PR review for all steering file changes |
-| spec sprawl | many incomplete specs with no active tasks | specs created without commitment to execution | add a "spec status" field (draft/active/complete) and review in weekly planning |
-| IAM over-automation | IAM Autopilot applies changes without approval | PR-only mode not configured | enforce `"mode": "pr-only"` before enabling IAM Autopilot |
-| onboarding failure | new developers cannot get Kiro working in first session | incomplete env setup docs | add `.env.example` and a setup verification checklist to the onboarding guide |
-| incident escalation | autonomous agent incident affects shared staging environment | no incident response protocol | implement the 13-step runbook before enabling autonomous mode in shared environments |
-| Power scope creep | IAM Autopilot analyzes roles outside the defined scope | missing `targetRoles` configuration | always configure `targetRoles` to restrict analysis to known role patterns |
-
-### Implementation Runbook
-
-1. Commit the team's `.kiro/` configuration directory to the shared repository with a clear README.
-2. Define the PR review policy for each `.kiro/` subdirectory and add it to the contributing guide.
-3. Assign named owners for `security.md`, `project.md`, and `mcp.json` with documented approval authority.
-4. Configure AWS IAM Autopilot in `settings.json` with PR-only mode and `targetRoles` restrictions.
-5. Run the team onboarding checklist with the first cohort of developers and collect feedback.
-6. Test the autonomous agent incident runbook with a controlled test scenario before enabling full autonomy in shared environments.
-7. Establish a weekly `.kiro/` configuration review as part of the team's engineering meeting.
-8. Set up a Slack or Teams channel for Kiro-related alerts from budget thresholds and IAM Autopilot escalations.
-9. Schedule a quarterly Kiro governance review to assess the effectiveness of the PR policies and onboarding process.
-
-### Quality Gate Checklist
-
-- [ ] `.kiro/` directory is committed to version control with a README and owner assignments
-- [ ] PR review policy is documented in the contributing guide for all `.kiro/` subdirectories
-- [ ] named owners are assigned for security.md, project.md, and mcp.json reviews
-- [ ] AWS IAM Autopilot is configured with `"mode": "pr-only"` and `targetRoles` restrictions
-- [ ] team onboarding checklist is complete for all active developers
-- [ ] autonomous agent incident runbook is tested with a controlled scenario
-- [ ] budget alerts are configured and the notification channel is verified
-- [ ] quarterly governance review is scheduled on the team engineering calendar
-
-### Source Alignment
-
-- [Kiro Docs: Team Setup](https://kiro.dev/docs/team)
-- [Kiro Docs: Powers](https://kiro.dev/docs/powers)
-- [Kiro Docs: AWS IAM Autopilot](https://kiro.dev/docs/powers/iam-autopilot)
-- [Kiro Docs: Governance](https://kiro.dev/docs/governance)
-- [Kiro Repository](https://github.com/kirodotdev/Kiro)
-
-### Cross-Tutorial Connection Map
-
-- [Claude Code Tutorial](../claude-code-tutorial/)
-- [Goose Tutorial](../goose-tutorial/)
-- [OpenHands Tutorial](../openhands-tutorial/)
-- [HumanLayer Tutorial](../humanlayer-tutorial/)
-- [Chapter 1: Getting Started](01-getting-started.md)
-
-### Advanced Practice Exercises
-
-1. Design a complete governance model for a 10-person team: ownership assignments, PR review policy, and escalation path for each `.kiro/` subdirectory.
-2. Run the autonomous agent incident runbook as a tabletop exercise with the team: simulate an agent that modifies the wrong database migration and practice the recovery steps.
-3. Configure AWS IAM Autopilot for a test AWS account with a narrow `targetRoles` filter and validate that it generates a PR without applying changes directly.
-4. Write a team onboarding guide that covers install, auth, env setup, and first spec creation in under 45 minutes for a developer who has never used Kiro.
-5. Propose and document a Kiro Powers roadmap for your team: which future Powers (beyond IAM Autopilot) would provide the highest value for your AWS-based infrastructure?
-
-### Review Questions
-
-1. Why should `.kiro/settings.json` and `.kiro/mcp.json` require security engineer approval in the PR review policy?
-2. What is the most important safety configuration for AWS IAM Autopilot before enabling it in a production AWS account?
-3. What tradeoff did you make between autonomous agent efficiency and oversight in shared staging environments?
-4. How would you recover if a steering file change was merged without the required security review and the change weakened an authentication policy?
-5. What must be tested before enabling full autonomous mode for a team's shared feature work environment?
-
-### Scenario Playbook 1: Team Operations - Steering Drift
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: different developers receive inconsistent agent behavior because steering files were edited without review
-- initial hypothesis: steering file changes are being merged without the required architecture and security reviews
-- immediate action: audit the git log for recent steering file changes and identify any that bypassed the review policy
-- engineering control: add a CODEOWNERS file that requires specific reviewers for `.kiro/steering/` changes
-- verification target: the next steering file PR is blocked until the designated reviewers approve
-- rollback trigger: if inconsistent agent behavior affects a production feature, revert the steering file to the last reviewed commit
-- communication step: notify the team of the CODEOWNERS addition and update the contributing guide
-- learning capture: add steering file governance to the team's quarterly engineering review agenda
-
-### Scenario Playbook 2: Team Operations - IAM Autopilot Scope Creep
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: IAM Autopilot generates PRs targeting IAM roles outside the configured `targetRoles` filter
-- initial hypothesis: the `targetRoles` pattern is too broad or a new role was created that matches the pattern unexpectedly
-- immediate action: review the generated PRs and close any that target out-of-scope roles without merging
-- engineering control: narrow the `targetRoles` pattern and add a specific exclusion list for known out-of-scope roles
-- verification target: IAM Autopilot generates PRs only for roles matching the intended pattern after the config update
-- rollback trigger: if scope creep continues, disable IAM Autopilot and conduct a manual configuration audit
-- communication step: notify the security team of the scope creep and the config change made to remediate it
-- learning capture: add a quarterly review of the `targetRoles` filter to the team's IAM governance calendar
+## Source Code Walkthrough
-### Scenario Playbook 3: Team Operations - Autonomous Agent Incident in Staging
+> **Note:** Kiro is a proprietary AWS IDE; the [`kirodotdev/Kiro`](https://github.com/kirodotdev/Kiro) public repository contains documentation and GitHub automation scripts rather than the IDE's source code. The authoritative references for this chapter are the official Kiro documentation and configuration files within your project's `.kiro/` directory.
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: autonomous agent modifies a shared database migration in the staging environment causing test failures for other developers
-- initial hypothesis: the agent executed a task with scope that included the shared migrations directory
-- immediate action: interrupt the agent, revert the migration change using git, and notify the team
-- engineering control: add an explicit scope exclusion for shared migration directories in the task description template
-- verification target: re-run the task with the scope exclusion and confirm no shared files are modified
-- rollback trigger: if the migration was already applied to the staging database, run the down migration and restore from backup
-- communication step: follow the 13-step incident runbook; notify the team in the incident channel within 5 minutes
-- learning capture: add "never modify shared migration files autonomously" as a rule in the task generation guidelines
+### [Kiro Docs: Team Features](https://kiro.dev/docs/team)
-### Scenario Playbook 4: Team Operations - Onboarding Failure
+The team features documentation covers shared steering file repositories, PR review policies for spec changes, AWS IAM Autopilot configuration for enterprise deployments, and team onboarding workflows — the governance patterns described in this chapter.
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: a new developer cannot get Kiro working after 2 hours because the onboarding guide is incomplete
-- initial hypothesis: the `.env.example` file is missing or the MCP server setup steps are not documented
-- immediate action: pair the new developer with a senior team member to complete the setup and document each missing step
-- engineering control: update the onboarding guide with the missing steps and add a setup verification checklist
-- verification target: the next new developer completes onboarding independently in under 45 minutes
-- rollback trigger: if the onboarding guide update does not resolve the issue, schedule a group onboarding session for the next cohort
-- communication step: announce the onboarding guide update in the team channel and ask the new developer to confirm it worked
-- learning capture: add onboarding guide review to the pre-release checklist for every Kiro version upgrade
+### [Kiro Docs: AWS Integration](https://kiro.dev/docs/aws)
-### Scenario Playbook 5: Team Operations - Spec Sprawl
+The AWS integration guide documents IAM Autopilot configuration, AWS Builder ID team provisioning, and the permission model for autonomous agent actions in AWS environments. This is the primary source for the AWS governance controls in this chapter.
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: `.kiro/specs/` contains 20+ spec directories with no active task execution, indicating abandoned or stale specs
-- initial hypothesis: specs are being created as planning artifacts but never reaching the task execution phase
-- immediate action: conduct a spec audit: categorize each spec as active, on-hold, or abandoned and add status labels
-- engineering control: add a "spec status" field to the spec README template and require status updates in weekly planning
-- verification target: after one sprint, each spec has a clear status and a responsible owner
-- rollback trigger: if spec debt continues to grow, implement a spec age limit: any spec older than 30 days without task activity is automatically archived
-- communication step: present the spec audit results in the next team planning session
-- learning capture: add spec lifecycle management to the team's Kiro governance document
+## How These Components Connect
-## What Problem Does This Solve?
-
-Agentic tools that work brilliantly for individual developers often fail catastrophically at team scale. Without governance, steering files drift, specs accumulate without execution, autonomous agents operate without safety boundaries, and costs grow without visibility. Kiro's team operations model solves this by making governance artifacts first-class citizens: version-controlled, reviewer-assigned, and incident-runbook-backed.
-
-In practical terms, this chapter helps you avoid three common failures:
-
-- an autonomous agent modifying shared infrastructure because nobody defined the scope boundary for team environments
-- security policy regressions when a well-meaning developer edits `security.md` without a security review
-- AWS IAM Autopilot applying changes directly to a production account because PR-only mode was not configured before enabling the Power
-
-After working through this chapter, you should be able to operate Kiro as a governed team tool with the same rigor applied to AI configuration artifacts that you apply to production infrastructure code.
-
-## How it Works Under the Hood
-
-Under the hood, `Chapter 8: Team Operations and Governance` follows a repeatable control path:
-
-1. **Configuration sharing**: the `.kiro/` directory is committed to version control and distributed to all developer workstations via git pull.
-2. **CODEOWNERS enforcement**: GitHub or GitLab CODEOWNERS rules block merges to `.kiro/` subdirectories without designated reviewer approval.
-3. **Power activation**: when a Power like IAM Autopilot is enabled in `settings.json`, Kiro connects to the corresponding AWS service using the configured credentials.
-4. **IAM analysis**: IAM Autopilot queries CloudTrail logs to identify permission usage patterns and generates a least-privilege policy recommendation.
-5. **PR creation**: instead of applying changes, IAM Autopilot creates a PR in the configured infrastructure repository for human review.
-6. **Incident response**: when an agent incident occurs, the runbook provides a structured 13-step recovery and learning process.
-
-When debugging governance issues, trace this sequence from configuration sharing through CODEOWNERS enforcement to identify where the policy gap occurred.
-
-## Source Walkthrough
-
-Use the following upstream sources to verify implementation details while reading this chapter:
-
-- [Kiro Docs: Team Setup](https://kiro.dev/docs/team)
- Why it matters: the official guide for team-scale Kiro configuration and shared workspace setup.
-- [Kiro Docs: Powers](https://kiro.dev/docs/powers)
- Why it matters: the primary reference for the Powers extension model and available Power configurations.
-- [Kiro Docs: AWS IAM Autopilot](https://kiro.dev/docs/powers/iam-autopilot)
- Why it matters: the detailed reference for IAM Autopilot configuration, safety controls, and CloudTrail integration.
-- [Kiro Docs: Governance](https://kiro.dev/docs/governance)
- Why it matters: documents Kiro's recommended governance practices for enterprise team deployments.
-
-Suggested trace strategy:
-- review the Powers docs before enabling any Power to understand the exact AWS permissions required by the Power
-- test IAM Autopilot in a sandbox AWS account before enabling it in a production account to verify PR-only mode works as expected
-
-## Chapter Connections
-
-- [Tutorial Index](README.md)
-- [Previous Chapter: Chapter 7: Multi-Model Strategy and Providers](07-multi-model-strategy-and-providers.md)
-- [Tutorial Index](README.md)
-- [Main Catalog](../../README.md#-tutorial-catalog)
-- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
-
-### Scenario Playbook 1: Chapter 8: Team Operations and Governance
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 2: Chapter 8: Team Operations and Governance
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 3: Chapter 8: Team Operations and Governance
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 4: Chapter 8: Team Operations and Governance
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 5: Chapter 8: Team Operations and Governance
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 6: Chapter 8: Team Operations and Governance
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 7: Chapter 8: Team Operations and Governance
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 8: Chapter 8: Team Operations and Governance
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 9: Chapter 8: Team Operations and Governance
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 10: Chapter 8: Team Operations and Governance
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 11: Chapter 8: Team Operations and Governance
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 12: Chapter 8: Team Operations and Governance
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 13: Chapter 8: Team Operations and Governance
-
-- tutorial context: **Kiro Tutorial: Spec-Driven Agentic IDE from AWS**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
+```mermaid
+flowchart TD
+ A[Team repository] --> B[Shared .kiro/steering/ files]
+ A --> C[Shared .kiro/hooks/ templates]
+ B --> D[Consistent agent behavior across team]
+ C --> E[Consistent automation triggers]
+ F[AWS IAM Autopilot] --> G[Permission boundaries for agent]
+ G --> H[Approved tool scopes]
+ D --> I[PR review: spec changes reviewed]
+ E --> I
+```
\ No newline at end of file
diff --git a/tutorials/kubernetes-operator-tutorial/01-getting-started.md b/tutorials/kubernetes-operator-tutorial/01-getting-started.md
index 9c9a7550..9d15cbe9 100644
--- a/tutorials/kubernetes-operator-tutorial/01-getting-started.md
+++ b/tutorials/kubernetes-operator-tutorial/01-getting-started.md
@@ -15,6 +15,17 @@ Welcome to **Chapter 1: Getting Started with Kubernetes Operators**. In this par
## Overview
+```mermaid
+flowchart TD
+ A[operator-sdk init] --> B[Project scaffold]
+ B --> C[operator-sdk create api]
+ C --> D[CRD + Controller stub]
+ D --> E[Implement Reconcile]
+ E --> F[make run]
+ F --> G[Controller watches CRD]
+ G --> H[Reconcile loop active]
+```
+
This chapter introduces Kubernetes Operators and guides you through setting up the development environment. You'll create your first operator and understand the fundamental concepts that make operators work.
## Understanding Operators
diff --git a/tutorials/kubernetes-operator-tutorial/02-custom-resources.md b/tutorials/kubernetes-operator-tutorial/02-custom-resources.md
index d0ac69ce..16469f5a 100644
--- a/tutorials/kubernetes-operator-tutorial/02-custom-resources.md
+++ b/tutorials/kubernetes-operator-tutorial/02-custom-resources.md
@@ -15,6 +15,16 @@ Welcome to **Chapter 2: Custom Resource Definitions - Designing Robust APIs**. I
## Overview
+```mermaid
+flowchart TD
+ A[CRD YAML] --> B[apiextensions.k8s.io]
+ B --> C[API Server registers type]
+ C --> D[kubectl apply MyApp]
+ D --> E[CR stored in etcd]
+ E --> F[Controller cache notified]
+ F --> G[Reconcile enqueued]
+```
+
Custom Resource Definitions (CRDs) are the foundation of Kubernetes operators. This chapter covers designing, implementing, and managing CRDs with proper validation, versioning, and API design principles.
## CRD Fundamentals
diff --git a/tutorials/kubernetes-operator-tutorial/03-reconciliation-loop.md b/tutorials/kubernetes-operator-tutorial/03-reconciliation-loop.md
index 86a2e52e..c4600ebd 100644
--- a/tutorials/kubernetes-operator-tutorial/03-reconciliation-loop.md
+++ b/tutorials/kubernetes-operator-tutorial/03-reconciliation-loop.md
@@ -15,6 +15,20 @@ Welcome to **Chapter 3: The Reconciliation Loop - Core Operator Logic**. In this
## Overview
+```mermaid
+flowchart TD
+ A[Watch event] --> B[Work queue]
+ B --> C[Reconcile called]
+ C --> D[Get CR from cache]
+ D --> E[Observe current state]
+ E --> F[Compute desired state]
+ F --> G{Diff?}
+ G -->|yes| H[Apply changes]
+ G -->|no| I[Return nil]
+ H --> J[Update CR status]
+ J --> I
+```
+
The reconciliation loop is the core mechanism that makes operators work. This chapter covers implementing robust reconciliation logic, managing state transitions, ensuring idempotency, and handling errors gracefully.
## Reconciliation Fundamentals
diff --git a/tutorials/kubernetes-operator-tutorial/04-owned-resources.md b/tutorials/kubernetes-operator-tutorial/04-owned-resources.md
index 605e55c2..da8bddd8 100644
--- a/tutorials/kubernetes-operator-tutorial/04-owned-resources.md
+++ b/tutorials/kubernetes-operator-tutorial/04-owned-resources.md
@@ -15,6 +15,17 @@ Welcome to **Chapter 4: Managing Owned Resources - Creating and Managing Kuberne
## Overview
+```mermaid
+flowchart TD
+ A[CR created] --> B[Reconciler creates Deployment]
+ B --> C[SetControllerReference owner]
+ C --> D[Deployment owned by CR]
+ D --> E{CR deleted?}
+ E -->|yes| F[GC deletes Deployment]
+ E -->|no| G[Reconciler watches Deployment]
+ G --> H[Sync replicas on drift]
+```
+
Operators manage complex applications by creating and controlling multiple Kubernetes resources. This chapter covers creating, updating, and managing owned resources while maintaining proper relationships and lifecycle management.
## Resource Ownership Patterns
diff --git a/tutorials/kubernetes-operator-tutorial/05-status-conditions.md b/tutorials/kubernetes-operator-tutorial/05-status-conditions.md
index b129f0fd..b2daa212 100644
--- a/tutorials/kubernetes-operator-tutorial/05-status-conditions.md
+++ b/tutorials/kubernetes-operator-tutorial/05-status-conditions.md
@@ -15,6 +15,17 @@ Welcome to **Chapter 5: Status and Conditions - Reporting Resource Status and Im
## Overview
+```mermaid
+flowchart TD
+ A[Reconcile completes] --> B[Compute status]
+ B --> C{All pods ready?}
+ C -->|yes| D[Set Available=True]
+ C -->|no| E[Set Available=False reason=Progressing]
+ D --> F[Patch CR status subresource]
+ E --> F
+ F --> G[kubectl get myapp shows status]
+```
+
Status reporting is crucial for operator observability. This chapter covers implementing comprehensive status reporting, condition patterns, and ensuring operators provide clear feedback about managed resources.
## Status Subresource
diff --git a/tutorials/kubernetes-operator-tutorial/06-testing.md b/tutorials/kubernetes-operator-tutorial/06-testing.md
index 65493105..288b7d25 100644
--- a/tutorials/kubernetes-operator-tutorial/06-testing.md
+++ b/tutorials/kubernetes-operator-tutorial/06-testing.md
@@ -15,6 +15,16 @@ Welcome to **Chapter 6: Testing Operators - Unit Tests, Integration Tests, and e
## Overview
+```mermaid
+flowchart LR
+ A[Unit tests] --> B[Reconciler with fake client]
+ C[Integration tests] --> D[envtest local API server]
+ D --> E[Apply CR YAML]
+ E --> F[Run Reconcile]
+ F --> G[Assert owned resources]
+ G --> H[Assert CR status]
+```
+
Testing operators is critical for reliability and maintainability. This chapter covers unit testing, integration testing, and using the envtest framework to test operators against a real Kubernetes API server.
## Unit Testing
diff --git a/tutorials/kubernetes-operator-tutorial/07-observability.md b/tutorials/kubernetes-operator-tutorial/07-observability.md
index 51811f6c..e127c2a1 100644
--- a/tutorials/kubernetes-operator-tutorial/07-observability.md
+++ b/tutorials/kubernetes-operator-tutorial/07-observability.md
@@ -15,6 +15,18 @@ Welcome to **Chapter 7: Observability & Debugging - Metrics, Logging, Tracing, a
## Overview
+```mermaid
+flowchart LR
+ A[Reconciler] --> B[ctrl.Log logger]
+ A --> C[prometheus.Counter reconcile_total]
+ A --> D[prometheus.Histogram reconcile_duration]
+ B --> E[Structured log output]
+ C --> F[/metrics endpoint]
+ D --> F
+ F --> G[Prometheus scrape]
+ G --> H[Grafana dashboard]
+```
+
Observability is crucial for production operators. This chapter covers implementing metrics, logging, tracing, and debugging capabilities to ensure operators are maintainable and debuggable in production environments.
## Metrics Collection
diff --git a/tutorials/kubernetes-operator-tutorial/08-production-deployment.md b/tutorials/kubernetes-operator-tutorial/08-production-deployment.md
index c876b29b..33f19cee 100644
--- a/tutorials/kubernetes-operator-tutorial/08-production-deployment.md
+++ b/tutorials/kubernetes-operator-tutorial/08-production-deployment.md
@@ -15,6 +15,17 @@ Welcome to **Chapter 8: Production Deployment - OLM, Helm Charts, Security, and
## Overview
+```mermaid
+flowchart TD
+ A[Operator image] --> B[OLM ClusterServiceVersion]
+ B --> C[OperatorHub publish]
+ C --> D[kubectl install via OLM]
+ D --> E[RBAC auto-configured]
+ E --> F[Leader election HA]
+ F --> G[Operator pod running]
+ G --> H[Manages CRs cluster-wide]
+```
+
Production deployment requires robust packaging, security, lifecycle management, and scaling. This chapter covers Operator Lifecycle Manager (OLM), Helm packaging, security hardening, and production scaling patterns.
## Operator Lifecycle Manager (OLM)
diff --git a/tutorials/lancedb-tutorial/01-getting-started.md b/tutorials/lancedb-tutorial/01-getting-started.md
index 8b335cf9..f19fdc81 100644
--- a/tutorials/lancedb-tutorial/01-getting-started.md
+++ b/tutorials/lancedb-tutorial/01-getting-started.md
@@ -14,6 +14,16 @@ Welcome to **Chapter 1: Getting Started with LanceDB**. In this part of **LanceD
## Overview
+```mermaid
+flowchart LR
+ A[lancedb.connect path] --> B[LanceDB database]
+ B --> C[db.create_table name data]
+ C --> D[Lance format files]
+ D --> E[table.search vector]
+ E --> F[ANN index]
+ F --> G[Ranked results]
+```
+
This chapter guides you through installing LanceDB, understanding its architecture, creating databases and tables, and performing your first vector similarity searches.
## Installation
diff --git a/tutorials/lancedb-tutorial/02-data-modeling.md b/tutorials/lancedb-tutorial/02-data-modeling.md
index d7acc2f3..19ec1bb0 100644
--- a/tutorials/lancedb-tutorial/02-data-modeling.md
+++ b/tutorials/lancedb-tutorial/02-data-modeling.md
@@ -14,6 +14,17 @@ Welcome to **Chapter 2: Data Modeling**. In this part of **LanceDB Tutorial: Ser
## Overview
+```mermaid
+flowchart TD
+ A[PyArrow schema] --> B[LanceDB table]
+ B --> C[vector column float32 dim=768]
+ B --> D[scalar columns text metadata]
+ B --> E[nested columns struct]
+ C --> F[Vector index IVF_PQ]
+ D --> G[Scalar index BTree]
+ E --> H[Full-text index BM25]
+```
+
Proper data modeling is crucial for building efficient vector search applications. This chapter covers schema design, data types, Pydantic models, and best practices for structuring your data in LanceDB.
## Schema Definition
diff --git a/tutorials/lancedb-tutorial/03-vector-operations.md b/tutorials/lancedb-tutorial/03-vector-operations.md
index eb4280dd..67504cdb 100644
--- a/tutorials/lancedb-tutorial/03-vector-operations.md
+++ b/tutorials/lancedb-tutorial/03-vector-operations.md
@@ -14,6 +14,16 @@ Welcome to **Chapter 3: Vector Operations**. In this part of **LanceDB Tutorial:
## Overview
+```mermaid
+flowchart LR
+ A[Embedding model] --> B[query vector float32]
+ B --> C[table.search vector]
+ C --> D[ANN search IVF_PQ]
+ D --> E[Top-K candidates]
+ E --> F[Reranking optional]
+ F --> G[Results with distance score]
+```
+
Vector operations are at the heart of LanceDB. This chapter covers indexing strategies, distance metrics, approximate nearest neighbor (ANN) search, and advanced query patterns for building high-performance vector search applications.
## Vector Indexing
diff --git a/tutorials/lancedb-tutorial/04-hybrid-search.md b/tutorials/lancedb-tutorial/04-hybrid-search.md
index 9ce18760..53a86481 100644
--- a/tutorials/lancedb-tutorial/04-hybrid-search.md
+++ b/tutorials/lancedb-tutorial/04-hybrid-search.md
@@ -14,6 +14,20 @@ Welcome to **Chapter 4: Hybrid Search**. In this part of **LanceDB Tutorial: Ser
## Overview
+```mermaid
+flowchart TD
+ A[Query] --> B[Vector search branch]
+ A --> C[Full-text search BM25 branch]
+ A --> D[Scalar filter branch]
+ B --> E[Vector scores]
+ C --> F[BM25 scores]
+ D --> G[Filtered candidates]
+ E --> H[RRF fusion]
+ F --> H
+ G --> H
+ H --> I[Hybrid results]
+```
+
Hybrid search combines multiple retrieval strategies to improve search quality. This chapter covers LanceDB's full-text search capabilities, combining vector and keyword search, and building effective hybrid retrieval pipelines.
## Full-Text Search
diff --git a/tutorials/lancedb-tutorial/05-integrations.md b/tutorials/lancedb-tutorial/05-integrations.md
index ac13c63d..dba8716d 100644
--- a/tutorials/lancedb-tutorial/05-integrations.md
+++ b/tutorials/lancedb-tutorial/05-integrations.md
@@ -14,6 +14,16 @@ Welcome to **Chapter 5: Integrations**. In this part of **LanceDB Tutorial: Serv
## Overview
+```mermaid
+flowchart LR
+ A[LangChain] --> B[LanceDB VectorStore]
+ C[LlamaIndex] --> B
+ D[OpenAI embeddings] --> B
+ E[HuggingFace embeddings] --> B
+ B --> F[Unified retrieve interface]
+ F --> G[RAG pipeline LLM]
+```
+
LanceDB integrates seamlessly with popular AI frameworks and tools. This chapter covers integrations with LangChain, LlamaIndex, various embedding providers, and other components of the modern AI stack.
## LangChain Integration
diff --git a/tutorials/lancedb-tutorial/06-performance.md b/tutorials/lancedb-tutorial/06-performance.md
index 8b2aa35f..4fcac6e4 100644
--- a/tutorials/lancedb-tutorial/06-performance.md
+++ b/tutorials/lancedb-tutorial/06-performance.md
@@ -14,6 +14,16 @@ Welcome to **Chapter 6: Performance**. In this part of **LanceDB Tutorial: Serve
## Overview
+```mermaid
+flowchart TD
+ A[Table with N vectors] --> B[create_index IVF_PQ]
+ B --> C[nlist partitions]
+ C --> D[nprobes at query time]
+ D --> E[Recall vs latency tradeoff]
+ F[Compact files] --> G[Reduced fragment count]
+ H[Pre-filter] --> I[Smaller search space]
+```
+
Performance optimization is crucial for production deployments. This chapter covers indexing strategies, query optimization, memory management, and benchmarking techniques for LanceDB.
## Index Optimization
diff --git a/tutorials/lancedb-tutorial/07-production.md b/tutorials/lancedb-tutorial/07-production.md
index 11622e69..f28333bb 100644
--- a/tutorials/lancedb-tutorial/07-production.md
+++ b/tutorials/lancedb-tutorial/07-production.md
@@ -14,6 +14,18 @@ Welcome to **Chapter 7: Production Deployment**. In this part of **LanceDB Tutor
## Overview
+```mermaid
+flowchart LR
+ A[Local Lance files] --> B{Storage backend}
+ B -->|S3| C[s3://bucket/db]
+ B -->|GCS| D[gs://bucket/db]
+ B -->|Azure| E[az://container/db]
+ C --> F[lancedb.connect uri]
+ D --> F
+ E --> F
+ F --> G[Same API as local]
+```
+
This chapter covers deploying LanceDB in production environments, including cloud storage backends, scaling strategies, monitoring, backup and recovery, and operational best practices.
## Cloud Storage Backends
diff --git a/tutorials/lancedb-tutorial/08-advanced-patterns.md b/tutorials/lancedb-tutorial/08-advanced-patterns.md
index 3724bb57..49141a60 100644
--- a/tutorials/lancedb-tutorial/08-advanced-patterns.md
+++ b/tutorials/lancedb-tutorial/08-advanced-patterns.md
@@ -14,6 +14,17 @@ Welcome to **Chapter 8: Advanced Patterns**. In this part of **LanceDB Tutorial:
## Overview
+```mermaid
+flowchart TD
+ A[Multi-tenant app] --> B[Namespace per tenant]
+ B --> C[Separate table per tenant]
+ C --> D[Access control at table level]
+ E[RAG pipeline] --> F[Chunk documents]
+ F --> G[Embed + store in LanceDB]
+ G --> H[Retrieve on query]
+ H --> I[LLM generates answer]
+```
+
This chapter covers advanced patterns for building sophisticated applications with LanceDB, including multi-tenant architectures, document processing pipelines, RAG systems, and real-time applications.
## Multi-Tenancy
diff --git a/tutorials/langchain-architecture-tutorial/README.md b/tutorials/langchain-architecture-tutorial/README.md
index 71346961..219f68ed 100644
--- a/tutorials/langchain-architecture-tutorial/README.md
+++ b/tutorials/langchain-architecture-tutorial/README.md
@@ -69,14 +69,14 @@ flowchart TB
## Why This Track Matters
-LangChain Architecture matters for developers building production systems. This track covers chapter 1: gett, chap, chapter 3: and helps you understand how the components fit together for real-world use.
+LangChain Architecture matters for developers building production systems who want to understand the internals: how the `Runnable` protocol enables composability, how chat models and callbacks are structured, and how agents and retrievers work at the code level.
This track focuses on:
-- understanding gett
-- understanding chap
-- understanding
-- understanding chain
+- understanding the `Runnable` protocol and LCEL composition
+- understanding chat model internals and the message type system
+- understanding the agent execution loop and tool binding
+- understanding production patterns: callbacks, caching, and LangSmith tracing
## Who This Guide Is For
diff --git a/tutorials/langchain-tutorial/01-getting-started.md b/tutorials/langchain-tutorial/01-getting-started.md
index 017459d1..d0cd841b 100644
--- a/tutorials/langchain-tutorial/01-getting-started.md
+++ b/tutorials/langchain-tutorial/01-getting-started.md
@@ -171,6 +171,20 @@ Now that you have the basics working, you're ready to explore more advanced feat
*What would you like to build with your new LangChain setup? Try modifying the example to ask different questions or change the system message!* 🚀
+## LangChain Building Blocks
+
+```mermaid
+flowchart TD
+ A[User input] --> B[LangChain chain]
+ B --> C[PromptTemplate]
+ C --> D[ChatModel / LLM]
+ D --> E[OutputParser]
+ E --> F[Structured response]
+ D --> G[Tool calls]
+ G --> H[External API / DB]
+ H --> D
+```
+
## What Problem Does This Solve?
Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for `langchain`, `messages`, `chat` so behavior stays predictable as complexity grows.
diff --git a/tutorials/langchain-tutorial/02-prompt-templates.md b/tutorials/langchain-tutorial/02-prompt-templates.md
index 958c9917..38885c11 100644
--- a/tutorials/langchain-tutorial/02-prompt-templates.md
+++ b/tutorials/langchain-tutorial/02-prompt-templates.md
@@ -335,6 +335,19 @@ Ready to add memory to your applications? In [Chapter 3: Memory Systems](03-memo
*What's the most interesting chain you can think of building?* 🚀
+## Prompt Template Flow
+
+```mermaid
+flowchart TD
+ A[ChatPromptTemplate] --> B[SystemMessagePromptTemplate]
+ A --> C[HumanMessagePromptTemplate]
+ B --> D[Format with variables]
+ C --> D
+ D --> E[List of messages]
+ E --> F[ChatModel.invoke]
+ F --> G[AIMessage response]
+```
+
## What Problem Does This Solve?
Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for `ChatPromptTemplate`, `from_template`, `query` so behavior stays predictable as complexity grows.
diff --git a/tutorials/langchain-tutorial/03-memory-systems.md b/tutorials/langchain-tutorial/03-memory-systems.md
index c45ea047..daa2305e 100644
--- a/tutorials/langchain-tutorial/03-memory-systems.md
+++ b/tutorials/langchain-tutorial/03-memory-systems.md
@@ -371,6 +371,19 @@ Create a memory-enabled chatbot that remembers user preferences (like favorite c
*What kind of memory would you use for a personal assistant that needs to remember appointments, preferences, and ongoing tasks?* 🤔
+## Memory System Architecture
+
+```mermaid
+flowchart TD
+ A[User message] --> B[Memory: load history]
+ B --> C[Prompt with history + new message]
+ C --> D[LLM call]
+ D --> E[AI response]
+ E --> F[Memory: save interaction]
+ F --> G[Updated conversation buffer]
+ G --> B
+```
+
## What Problem Does This Solve?
Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for `memory`, `input`, `langchain` so behavior stays predictable as complexity grows.
diff --git a/tutorials/langchain-tutorial/04-document-processing.md b/tutorials/langchain-tutorial/04-document-processing.md
index 9efb250c..9e06021a 100644
--- a/tutorials/langchain-tutorial/04-document-processing.md
+++ b/tutorials/langchain-tutorial/04-document-processing.md
@@ -447,6 +447,19 @@ Create a document processing pipeline that:
*What types of documents do you want to make searchable with AI?* 📚
+## Document Processing Pipeline
+
+```mermaid
+flowchart TD
+ A[Raw documents] --> B[Document loaders]
+ B --> C[TextSplitter]
+ C --> D[Chunks with metadata]
+ D --> E[Embeddings model]
+ E --> F[Vector embeddings]
+ F --> G[Vector store ingest]
+ G --> H[Indexed for retrieval]
+```
+
## What Problem Does This Solve?
Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for `documents`, `langchain`, `load` so behavior stays predictable as complexity grows.
diff --git a/tutorials/langchain-tutorial/05-vector-stores.md b/tutorials/langchain-tutorial/05-vector-stores.md
index 36d9cb27..3019138b 100644
--- a/tutorials/langchain-tutorial/05-vector-stores.md
+++ b/tutorials/langchain-tutorial/05-vector-stores.md
@@ -483,6 +483,19 @@ Build a RAG system that can answer questions about a specific domain (like progr
*What's the most interesting application you can think of for RAG systems?* 🤖
+## Vector Store RAG Flow
+
+```mermaid
+flowchart TD
+ A[Query string] --> B[Embeddings model]
+ B --> C[Query embedding vector]
+ C --> D[Vector store similarity search]
+ D --> E[Top-k similar documents]
+ E --> F[Stuffed into prompt]
+ F --> G[LLM generates answer]
+ G --> H[Response with sources]
+```
+
## What Problem Does This Solve?
Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for `documents`, `print`, `page_content` so behavior stays predictable as complexity grows.
diff --git a/tutorials/langchain-tutorial/06-agents-tools.md b/tutorials/langchain-tutorial/06-agents-tools.md
index 651ff972..b7daa129 100644
--- a/tutorials/langchain-tutorial/06-agents-tools.md
+++ b/tutorials/langchain-tutorial/06-agents-tools.md
@@ -710,6 +710,19 @@ Now that you understand agents and tools, let's explore advanced chains and cust
*What kind of autonomous agent will you build first?* 🤖
+## Agent ReAct Loop
+
+```mermaid
+flowchart TD
+ A[User task] --> B[Agent LLM]
+ B --> C{Decide action}
+ C -->|Use tool| D[Tool executor]
+ D --> E[Tool result / observation]
+ E --> B
+ C -->|Answer ready| F[Final answer]
+ G[Tool registry] --> B
+```
+
## What Problem Does This Solve?
Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for `self`, `tools`, `agent` so behavior stays predictable as complexity grows.
diff --git a/tutorials/langchain-tutorial/07-advanced-chains.md b/tutorials/langchain-tutorial/07-advanced-chains.md
index dd15e1f8..c86991cd 100644
--- a/tutorials/langchain-tutorial/07-advanced-chains.md
+++ b/tutorials/langchain-tutorial/07-advanced-chains.md
@@ -780,6 +780,21 @@ Now that you understand advanced chains, let's explore production deployment con
*What kind of advanced chain will you build first?* 🔗
+## Advanced Chain Patterns
+
+```mermaid
+flowchart TD
+ A[Input] --> B[LCEL chain using | operator]
+ B --> C[PromptTemplate]
+ C --> D[ChatModel]
+ D --> E[OutputParser]
+ E --> F[Output]
+ B --> G[Parallel branch]
+ G --> H[RunnableParallel]
+ H --> I[Multiple sub-chains]
+ I --> J[Merged result]
+```
+
## What Problem Does This Solve?
Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for `self`, `chain`, `result` so behavior stays predictable as complexity grows.
diff --git a/tutorials/langchain-tutorial/08-production-deployment.md b/tutorials/langchain-tutorial/08-production-deployment.md
index 95da844b..0ae55624 100644
--- a/tutorials/langchain-tutorial/08-production-deployment.md
+++ b/tutorials/langchain-tutorial/08-production-deployment.md
@@ -928,6 +928,20 @@ Your LangChain journey is complete! You now have the knowledge and tools to buil
*What production LangChain application will you build first?* 🚀
+## Production Deployment
+
+```mermaid
+flowchart TD
+ A[LangChain app] --> B[LangServe REST API]
+ B --> C[POST /chain/invoke]
+ C --> D[Chain executes]
+ D --> E[LangSmith tracing]
+ E --> F[Trace stored]
+ D --> G[Response]
+ A --> H[Docker container]
+ H --> I[Cloud deployment]
+```
+
## What Problem Does This Solve?
Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for `self`, `time`, `metrics` so behavior stays predictable as complexity grows.
diff --git a/tutorials/langchain-tutorial/09-evaluation-monitoring.md b/tutorials/langchain-tutorial/09-evaluation-monitoring.md
index 04333151..3a4bb759 100644
--- a/tutorials/langchain-tutorial/09-evaluation-monitoring.md
+++ b/tutorials/langchain-tutorial/09-evaluation-monitoring.md
@@ -749,6 +749,20 @@ monitor.track_performance("qa_chain", evaluation_score, latency_seconds)
This evaluation and monitoring chapter provides comprehensive tools for maintaining and improving LangChain application performance in production environments. The combination of evaluation frameworks, monitoring systems, and continuous improvement processes ensures your AI applications remain reliable and effective over time.
+## Evaluation and Monitoring
+
+```mermaid
+flowchart TD
+ A[LangSmith project] --> B[Trace every LLM call]
+ B --> C[Latency, cost, tokens logged]
+ C --> D{Evaluation}
+ D -->|Automated| E[Evaluator LLM scores outputs]
+ D -->|Human| F[Manual feedback annotations]
+ E --> G[Dataset + scores]
+ F --> G
+ G --> H[Regression testing on new versions]
+```
+
## What Problem Does This Solve?
Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for `self`, `chain_name`, `error` so behavior stays predictable as complexity grows.
diff --git a/tutorials/langflow-tutorial/01-getting-started.md b/tutorials/langflow-tutorial/01-getting-started.md
index 595be3cc..ef27ee4d 100644
--- a/tutorials/langflow-tutorial/01-getting-started.md
+++ b/tutorials/langflow-tutorial/01-getting-started.md
@@ -47,184 +47,16 @@ You now have a working Langflow environment ready for architecture and workflow
Next: [Chapter 2: Platform Architecture](02-platform-architecture.md)
-## Depth Expansion Playbook
-
-## Source Code Walkthrough
-
-### `scripts/generate_migration.py`
-
-The `upgrade` function in [`scripts/generate_migration.py`](https://github.com/langflow-ai/langflow/blob/HEAD/scripts/generate_migration.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def upgrade() -> None:
- """
- EXPAND PHASE: Add new schema elements (backward compatible)
- - All new columns must be nullable or have defaults
- - No breaking changes to existing schema
- - Services using old schema continue to work
- """
- bind = op.get_bind()
- inspector = inspect(bind)
-
- # Get existing columns for idempotency
- columns = [col['name'] for col in inspector.get_columns('{table_name}')]
- }
-
- # Add new nullable column (always check existence first)
- if '{column_name}' not in columns:
- op.add_column('{table_name}',
- sa.Column('{column_name}', sa.{column_type}(), nullable=True{default_value})
- )
-
- print(f"✅ Added column '{column_name}' to table '{table_name}'")
-
- # Optional: Add index for performance
- # op.create_index('ix_{table_name}_{column_name}', '{table_name}', ['{column_name}'])
- else:
- print(f"⏭️ Column '{column_name}' already exists in table '{table_name}'")
-
- # Verify the change
- result = bind.execute(text(
- "SELECT COUNT(*) as cnt FROM {table_name}"
-```
-
-This function is important because it defines how Langflow Tutorial: Visual AI Agent and Workflow Platform implements the patterns covered in this chapter.
-
-### `scripts/generate_migration.py`
-
-The `downgrade` function in [`scripts/generate_migration.py`](https://github.com/langflow-ai/langflow/blob/HEAD/scripts/generate_migration.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def downgrade() -> None:
- """
- Rollback EXPAND phase
- - Safe to rollback as it only removes additions
- - Check for data loss before dropping
- """
- bind = op.get_bind()
- inspector = inspect(bind)
- columns = [col['name'] for col in inspector.get_columns('{table_name}')]
-
- if '{column_name}' in columns:
- # Check if column has data
- result = bind.execute(text("""
- SELECT COUNT(*) as cnt FROM {table_name}
- WHERE {column_name} IS NOT NULL
- """)).first()
-
- if result and result.cnt > 0:
- print(f"⚠️ Warning: Dropping column '{column_name}' with {{result.cnt}} non-null values")
-
- # Optional: Create backup table
- backup_table = '_{table_name}_{column_name}_backup_' + datetime.now().strftime('%Y%m%d_%H%M%S')
- bind.execute(text(f"""
- CREATE TABLE {{backup_table}} AS
- SELECT id, {column_name}, NOW() as backed_up_at
- FROM {table_name}
- WHERE {column_name} IS NOT NULL
- """))
- print(f"💾 Created backup table: {{backup_table}}")
-
-```
-
-This function is important because it defines how Langflow Tutorial: Visual AI Agent and Workflow Platform implements the patterns covered in this chapter.
-
-### `scripts/generate_migration.py`
-
-The `upgrade` function in [`scripts/generate_migration.py`](https://github.com/langflow-ai/langflow/blob/HEAD/scripts/generate_migration.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def upgrade() -> None:
- """
- EXPAND PHASE: Add new schema elements (backward compatible)
- - All new columns must be nullable or have defaults
- - No breaking changes to existing schema
- - Services using old schema continue to work
- """
- bind = op.get_bind()
- inspector = inspect(bind)
-
- # Get existing columns for idempotency
- columns = [col['name'] for col in inspector.get_columns('{table_name}')]
- }
-
- # Add new nullable column (always check existence first)
- if '{column_name}' not in columns:
- op.add_column('{table_name}',
- sa.Column('{column_name}', sa.{column_type}(), nullable=True{default_value})
- )
-
- print(f"✅ Added column '{column_name}' to table '{table_name}'")
-
- # Optional: Add index for performance
- # op.create_index('ix_{table_name}_{column_name}', '{table_name}', ['{column_name}'])
- else:
- print(f"⏭️ Column '{column_name}' already exists in table '{table_name}'")
-
- # Verify the change
- result = bind.execute(text(
- "SELECT COUNT(*) as cnt FROM {table_name}"
-```
-
-This function is important because it defines how Langflow Tutorial: Visual AI Agent and Workflow Platform implements the patterns covered in this chapter.
-
-### `scripts/generate_migration.py`
-
-The `downgrade` function in [`scripts/generate_migration.py`](https://github.com/langflow-ai/langflow/blob/HEAD/scripts/generate_migration.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def downgrade() -> None:
- """
- Rollback EXPAND phase
- - Safe to rollback as it only removes additions
- - Check for data loss before dropping
- """
- bind = op.get_bind()
- inspector = inspect(bind)
- columns = [col['name'] for col in inspector.get_columns('{table_name}')]
-
- if '{column_name}' in columns:
- # Check if column has data
- result = bind.execute(text("""
- SELECT COUNT(*) as cnt FROM {table_name}
- WHERE {column_name} IS NOT NULL
- """)).first()
-
- if result and result.cnt > 0:
- print(f"⚠️ Warning: Dropping column '{column_name}' with {{result.cnt}} non-null values")
-
- # Optional: Create backup table
- backup_table = '_{table_name}_{column_name}_backup_' + datetime.now().strftime('%Y%m%d_%H%M%S')
- bind.execute(text(f"""
- CREATE TABLE {{backup_table}} AS
- SELECT id, {column_name}, NOW() as backed_up_at
- FROM {table_name}
- WHERE {column_name} IS NOT NULL
- """))
- print(f"💾 Created backup table: {{backup_table}}")
-
-```
-
-This function is important because it defines how Langflow Tutorial: Visual AI Agent and Workflow Platform implements the patterns covered in this chapter.
-
-
## How These Components Connect
```mermaid
flowchart TD
- A[upgrade]
- B[downgrade]
- C[upgrade]
- D[downgrade]
- A --> B
- B --> C
- C --> D
+ A[Install Langflow] --> B{Install method}
+ B -->|pip| C[pip install langflow]
+ B -->|Docker| D[docker run langflow]
+ C --> E[langflow run]
+ D --> E
+ E --> F[Langflow UI on :7860]
+ F --> G[Create new flow]
+ G --> H[Drag-and-drop components]
```
diff --git a/tutorials/langflow-tutorial/02-platform-architecture.md b/tutorials/langflow-tutorial/02-platform-architecture.md
index acde2fb3..e96175ea 100644
--- a/tutorials/langflow-tutorial/02-platform-architecture.md
+++ b/tutorials/langflow-tutorial/02-platform-architecture.md
@@ -43,184 +43,17 @@ You now understand where to place design, logic, and deployment concerns in Lang
Next: [Chapter 3: Visual Flow Builder](03-visual-flow-builder.md)
-## Depth Expansion Playbook
-
-## Source Code Walkthrough
-
-### `scripts/generate_migration.py`
-
-The `upgrade` function in [`scripts/generate_migration.py`](https://github.com/langflow-ai/langflow/blob/HEAD/scripts/generate_migration.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def upgrade() -> None:
- """
- EXPAND PHASE: Add new schema elements (backward compatible)
- - All new columns must be nullable or have defaults
- - No breaking changes to existing schema
- - Services using old schema continue to work
- """
- bind = op.get_bind()
- inspector = inspect(bind)
-
- # Get existing columns for idempotency
- columns = [col['name'] for col in inspector.get_columns('{table_name}')]
- }
-
- # Add new nullable column (always check existence first)
- if '{column_name}' not in columns:
- op.add_column('{table_name}',
- sa.Column('{column_name}', sa.{column_type}(), nullable=True{default_value})
- )
-
- print(f"✅ Added column '{column_name}' to table '{table_name}'")
-
- # Optional: Add index for performance
- # op.create_index('ix_{table_name}_{column_name}', '{table_name}', ['{column_name}'])
- else:
- print(f"⏭️ Column '{column_name}' already exists in table '{table_name}'")
-
- # Verify the change
- result = bind.execute(text(
- "SELECT COUNT(*) as cnt FROM {table_name}"
-```
-
-This function is important because it defines how Langflow Tutorial: Visual AI Agent and Workflow Platform implements the patterns covered in this chapter.
-
-### `scripts/migrate_secret_key.py`
-
-The `get_default_config_dir` function in [`scripts/migrate_secret_key.py`](https://github.com/langflow-ai/langflow/blob/HEAD/scripts/migrate_secret_key.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def get_default_config_dir() -> Path:
- """Get the default Langflow config directory using platformdirs."""
- return Path(user_cache_dir("langflow", "langflow"))
-
-
-def get_config_dir() -> Path:
- """Get the Langflow config directory from environment or default."""
- config_dir = os.environ.get("LANGFLOW_CONFIG_DIR")
- if config_dir:
- return Path(config_dir)
- return get_default_config_dir()
-
-
-def set_secure_permissions(file_path: Path) -> None:
- """Set restrictive permissions on a file (600 on Unix)."""
- if platform.system() in {"Linux", "Darwin"}:
- file_path.chmod(0o600)
- elif platform.system() == "Windows":
- try:
- import win32api
- import win32con
- import win32security
-
- user, _, _ = win32security.LookupAccountName("", win32api.GetUserName())
- sd = win32security.GetFileSecurity(str(file_path), win32security.DACL_SECURITY_INFORMATION)
- dacl = win32security.ACL()
- dacl.AddAccessAllowedAce(
- win32security.ACL_REVISION,
- win32con.GENERIC_READ | win32con.GENERIC_WRITE,
- user,
-```
-
-This function is important because it defines how Langflow Tutorial: Visual AI Agent and Workflow Platform implements the patterns covered in this chapter.
-
-### `scripts/migrate_secret_key.py`
-
-The `get_config_dir` function in [`scripts/migrate_secret_key.py`](https://github.com/langflow-ai/langflow/blob/HEAD/scripts/migrate_secret_key.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def get_config_dir() -> Path:
- """Get the Langflow config directory from environment or default."""
- config_dir = os.environ.get("LANGFLOW_CONFIG_DIR")
- if config_dir:
- return Path(config_dir)
- return get_default_config_dir()
-
-
-def set_secure_permissions(file_path: Path) -> None:
- """Set restrictive permissions on a file (600 on Unix)."""
- if platform.system() in {"Linux", "Darwin"}:
- file_path.chmod(0o600)
- elif platform.system() == "Windows":
- try:
- import win32api
- import win32con
- import win32security
-
- user, _, _ = win32security.LookupAccountName("", win32api.GetUserName())
- sd = win32security.GetFileSecurity(str(file_path), win32security.DACL_SECURITY_INFORMATION)
- dacl = win32security.ACL()
- dacl.AddAccessAllowedAce(
- win32security.ACL_REVISION,
- win32con.GENERIC_READ | win32con.GENERIC_WRITE,
- user,
- )
- sd.SetSecurityDescriptorDacl(1, dacl, 0)
- win32security.SetFileSecurity(str(file_path), win32security.DACL_SECURITY_INFORMATION, sd)
- except ImportError:
- print("Warning: Could not set secure permissions on Windows (pywin32 not installed)")
-```
-
-This function is important because it defines how Langflow Tutorial: Visual AI Agent and Workflow Platform implements the patterns covered in this chapter.
-
-### `scripts/migrate_secret_key.py`
-
-The `set_secure_permissions` function in [`scripts/migrate_secret_key.py`](https://github.com/langflow-ai/langflow/blob/HEAD/scripts/migrate_secret_key.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def set_secure_permissions(file_path: Path) -> None:
- """Set restrictive permissions on a file (600 on Unix)."""
- if platform.system() in {"Linux", "Darwin"}:
- file_path.chmod(0o600)
- elif platform.system() == "Windows":
- try:
- import win32api
- import win32con
- import win32security
-
- user, _, _ = win32security.LookupAccountName("", win32api.GetUserName())
- sd = win32security.GetFileSecurity(str(file_path), win32security.DACL_SECURITY_INFORMATION)
- dacl = win32security.ACL()
- dacl.AddAccessAllowedAce(
- win32security.ACL_REVISION,
- win32con.GENERIC_READ | win32con.GENERIC_WRITE,
- user,
- )
- sd.SetSecurityDescriptorDacl(1, dacl, 0)
- win32security.SetFileSecurity(str(file_path), win32security.DACL_SECURITY_INFORMATION, sd)
- except ImportError:
- print("Warning: Could not set secure permissions on Windows (pywin32 not installed)")
-
-
-def read_secret_key_from_file(config_dir: Path) -> str | None:
- """Read the secret key from the config directory."""
- secret_file = config_dir / "secret_key"
- if secret_file.exists():
- return secret_file.read_text(encoding="utf-8").strip()
- return None
-```
-
-This function is important because it defines how Langflow Tutorial: Visual AI Agent and Workflow Platform implements the patterns covered in this chapter.
-
-
## How These Components Connect
```mermaid
flowchart TD
- A[upgrade]
- B[get_default_config_dir]
- C[get_config_dir]
- D[set_secure_permissions]
- A --> B
- B --> C
- C --> D
+ A[Langflow platform] --> B[React frontend]
+ A --> C[FastAPI backend]
+ B --> D[Flow canvas drag-and-drop]
+ C --> E[Flow executor]
+ C --> F[Component registry]
+ E --> G[LangChain runtime]
+ G --> H[LLM providers]
+ G --> I[Vector stores]
+ G --> J[Tools and agents]
```
diff --git a/tutorials/langflow-tutorial/03-visual-flow-builder.md b/tutorials/langflow-tutorial/03-visual-flow-builder.md
index b95eac56..dc987ac0 100644
--- a/tutorials/langflow-tutorial/03-visual-flow-builder.md
+++ b/tutorials/langflow-tutorial/03-visual-flow-builder.md
@@ -38,184 +38,16 @@ You now have practical rules for building maintainable visual flow graphs.
Next: [Chapter 4: Agent Workflows and Orchestration](04-agent-workflows-and-orchestration.md)
-## Depth Expansion Playbook
-
-## Source Code Walkthrough
-
-### `scripts/migrate_secret_key.py`
-
-The `read_secret_key_from_file` function in [`scripts/migrate_secret_key.py`](https://github.com/langflow-ai/langflow/blob/HEAD/scripts/migrate_secret_key.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def read_secret_key_from_file(config_dir: Path) -> str | None:
- """Read the secret key from the config directory."""
- secret_file = config_dir / "secret_key"
- if secret_file.exists():
- return secret_file.read_text(encoding="utf-8").strip()
- return None
-
-
-def write_secret_key_to_file(config_dir: Path, key: str, filename: str = "secret_key") -> None:
- """Write a secret key to file with secure permissions."""
- config_dir.mkdir(parents=True, exist_ok=True)
- secret_file = config_dir / filename
- secret_file.write_text(key, encoding="utf-8")
- set_secure_permissions(secret_file)
-
-
-def ensure_valid_key(s: str) -> bytes:
- """Convert a secret key string to valid Fernet key bytes.
-
- For keys shorter than MINIMUM_KEY_LENGTH (32), generates a deterministic
- key by seeding random with the input string. For longer keys, pads with
- '=' to ensure valid base64 encoding.
-
- NOTE: This function is duplicated from langflow.services.auth.utils.ensure_valid_key
- to keep the migration script self-contained (can run without full Langflow installation).
- Keep in sync if encryption logic changes.
- """
- if len(s) < MINIMUM_KEY_LENGTH:
- random.seed(s)
- key = bytes(random.getrandbits(8) for _ in range(32))
-```
-
-This function is important because it defines how Langflow Tutorial: Visual AI Agent and Workflow Platform implements the patterns covered in this chapter.
-
-### `scripts/migrate_secret_key.py`
-
-The `write_secret_key_to_file` function in [`scripts/migrate_secret_key.py`](https://github.com/langflow-ai/langflow/blob/HEAD/scripts/migrate_secret_key.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def write_secret_key_to_file(config_dir: Path, key: str, filename: str = "secret_key") -> None:
- """Write a secret key to file with secure permissions."""
- config_dir.mkdir(parents=True, exist_ok=True)
- secret_file = config_dir / filename
- secret_file.write_text(key, encoding="utf-8")
- set_secure_permissions(secret_file)
-
-
-def ensure_valid_key(s: str) -> bytes:
- """Convert a secret key string to valid Fernet key bytes.
-
- For keys shorter than MINIMUM_KEY_LENGTH (32), generates a deterministic
- key by seeding random with the input string. For longer keys, pads with
- '=' to ensure valid base64 encoding.
-
- NOTE: This function is duplicated from langflow.services.auth.utils.ensure_valid_key
- to keep the migration script self-contained (can run without full Langflow installation).
- Keep in sync if encryption logic changes.
- """
- if len(s) < MINIMUM_KEY_LENGTH:
- random.seed(s)
- key = bytes(random.getrandbits(8) for _ in range(32))
- return base64.urlsafe_b64encode(key)
- padding_needed = 4 - len(s) % 4
- return (s + "=" * padding_needed).encode()
-
-
-def decrypt_with_key(encrypted: str, key: str) -> str:
- """Decrypt data with the given key."""
- fernet = Fernet(ensure_valid_key(key))
-```
-
-This function is important because it defines how Langflow Tutorial: Visual AI Agent and Workflow Platform implements the patterns covered in this chapter.
-
-### `scripts/migrate_secret_key.py`
-
-The `ensure_valid_key` function in [`scripts/migrate_secret_key.py`](https://github.com/langflow-ai/langflow/blob/HEAD/scripts/migrate_secret_key.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def ensure_valid_key(s: str) -> bytes:
- """Convert a secret key string to valid Fernet key bytes.
-
- For keys shorter than MINIMUM_KEY_LENGTH (32), generates a deterministic
- key by seeding random with the input string. For longer keys, pads with
- '=' to ensure valid base64 encoding.
-
- NOTE: This function is duplicated from langflow.services.auth.utils.ensure_valid_key
- to keep the migration script self-contained (can run without full Langflow installation).
- Keep in sync if encryption logic changes.
- """
- if len(s) < MINIMUM_KEY_LENGTH:
- random.seed(s)
- key = bytes(random.getrandbits(8) for _ in range(32))
- return base64.urlsafe_b64encode(key)
- padding_needed = 4 - len(s) % 4
- return (s + "=" * padding_needed).encode()
-
-
-def decrypt_with_key(encrypted: str, key: str) -> str:
- """Decrypt data with the given key."""
- fernet = Fernet(ensure_valid_key(key))
- return fernet.decrypt(encrypted.encode()).decode()
-
-
-def encrypt_with_key(plaintext: str, key: str) -> str:
- """Encrypt data with the given key."""
- fernet = Fernet(ensure_valid_key(key))
- return fernet.encrypt(plaintext.encode()).decode()
-
-```
-
-This function is important because it defines how Langflow Tutorial: Visual AI Agent and Workflow Platform implements the patterns covered in this chapter.
-
-### `scripts/migrate_secret_key.py`
-
-The `decrypt_with_key` function in [`scripts/migrate_secret_key.py`](https://github.com/langflow-ai/langflow/blob/HEAD/scripts/migrate_secret_key.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def decrypt_with_key(encrypted: str, key: str) -> str:
- """Decrypt data with the given key."""
- fernet = Fernet(ensure_valid_key(key))
- return fernet.decrypt(encrypted.encode()).decode()
-
-
-def encrypt_with_key(plaintext: str, key: str) -> str:
- """Encrypt data with the given key."""
- fernet = Fernet(ensure_valid_key(key))
- return fernet.encrypt(plaintext.encode()).decode()
-
-
-def migrate_value(encrypted: str, old_key: str, new_key: str) -> str | None:
- """Decrypt with old key and re-encrypt with new key.
-
- Returns:
- The re-encrypted value, or None if decryption fails (invalid key or corrupted data).
- """
- try:
- plaintext = decrypt_with_key(encrypted, old_key)
- return encrypt_with_key(plaintext, new_key)
- except InvalidToken:
- return None
-
-
-def migrate_auth_settings(auth_settings: dict, old_key: str, new_key: str) -> tuple[dict, list[str]]:
- """Re-encrypt sensitive fields in auth_settings dict.
-
- Returns:
- Tuple of (migrated_settings, failed_fields) where failed_fields contains
-```
-
-This function is important because it defines how Langflow Tutorial: Visual AI Agent and Workflow Platform implements the patterns covered in this chapter.
-
-
## How These Components Connect
```mermaid
flowchart TD
- A[read_secret_key_from_file]
- B[write_secret_key_to_file]
- C[ensure_valid_key]
- D[decrypt_with_key]
- A --> B
- B --> C
- C --> D
+ A[Langflow canvas] --> B[Add component node]
+ B --> C[Configure node inputs/params]
+ C --> D[Connect nodes with edges]
+ D --> E[Validate flow]
+ E --> F{Valid?}
+ F -->|Yes| G[Run flow via UI or API]
+ F -->|No| H[Fix connection errors]
+ G --> I[LangChain executes pipeline]
```
diff --git a/tutorials/langflow-tutorial/04-agent-workflows-and-orchestration.md b/tutorials/langflow-tutorial/04-agent-workflows-and-orchestration.md
index 39347be5..8ce91d54 100644
--- a/tutorials/langflow-tutorial/04-agent-workflows-and-orchestration.md
+++ b/tutorials/langflow-tutorial/04-agent-workflows-and-orchestration.md
@@ -36,184 +36,19 @@ You now know how to structure robust Langflow orchestration beyond simple demo c
Next: [Chapter 5: API and MCP Deployment](05-api-and-mcp-deployment.md)
-## Depth Expansion Playbook
-
-## Source Code Walkthrough
-
-### `scripts/migrate_secret_key.py`
-
-The `encrypt_with_key` function in [`scripts/migrate_secret_key.py`](https://github.com/langflow-ai/langflow/blob/HEAD/scripts/migrate_secret_key.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def encrypt_with_key(plaintext: str, key: str) -> str:
- """Encrypt data with the given key."""
- fernet = Fernet(ensure_valid_key(key))
- return fernet.encrypt(plaintext.encode()).decode()
-
-
-def migrate_value(encrypted: str, old_key: str, new_key: str) -> str | None:
- """Decrypt with old key and re-encrypt with new key.
-
- Returns:
- The re-encrypted value, or None if decryption fails (invalid key or corrupted data).
- """
- try:
- plaintext = decrypt_with_key(encrypted, old_key)
- return encrypt_with_key(plaintext, new_key)
- except InvalidToken:
- return None
-
-
-def migrate_auth_settings(auth_settings: dict, old_key: str, new_key: str) -> tuple[dict, list[str]]:
- """Re-encrypt sensitive fields in auth_settings dict.
-
- Returns:
- Tuple of (migrated_settings, failed_fields) where failed_fields contains
- names of fields that could not be decrypted with the old key.
- """
- result = auth_settings.copy()
- failed_fields = []
- for field in SENSITIVE_AUTH_FIELDS:
- if result.get(field):
-```
-
-This function is important because it defines how Langflow Tutorial: Visual AI Agent and Workflow Platform implements the patterns covered in this chapter.
-
-### `scripts/migrate_secret_key.py`
-
-The `migrate_value` function in [`scripts/migrate_secret_key.py`](https://github.com/langflow-ai/langflow/blob/HEAD/scripts/migrate_secret_key.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def migrate_value(encrypted: str, old_key: str, new_key: str) -> str | None:
- """Decrypt with old key and re-encrypt with new key.
-
- Returns:
- The re-encrypted value, or None if decryption fails (invalid key or corrupted data).
- """
- try:
- plaintext = decrypt_with_key(encrypted, old_key)
- return encrypt_with_key(plaintext, new_key)
- except InvalidToken:
- return None
-
-
-def migrate_auth_settings(auth_settings: dict, old_key: str, new_key: str) -> tuple[dict, list[str]]:
- """Re-encrypt sensitive fields in auth_settings dict.
-
- Returns:
- Tuple of (migrated_settings, failed_fields) where failed_fields contains
- names of fields that could not be decrypted with the old key.
- """
- result = auth_settings.copy()
- failed_fields = []
- for field in SENSITIVE_AUTH_FIELDS:
- if result.get(field):
- new_value = migrate_value(result[field], old_key, new_key)
- if new_value:
- result[field] = new_value
- else:
- failed_fields.append(field)
- return result, failed_fields
-```
-
-This function is important because it defines how Langflow Tutorial: Visual AI Agent and Workflow Platform implements the patterns covered in this chapter.
-
-### `scripts/migrate_secret_key.py`
-
-The `migrate_auth_settings` function in [`scripts/migrate_secret_key.py`](https://github.com/langflow-ai/langflow/blob/HEAD/scripts/migrate_secret_key.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def migrate_auth_settings(auth_settings: dict, old_key: str, new_key: str) -> tuple[dict, list[str]]:
- """Re-encrypt sensitive fields in auth_settings dict.
-
- Returns:
- Tuple of (migrated_settings, failed_fields) where failed_fields contains
- names of fields that could not be decrypted with the old key.
- """
- result = auth_settings.copy()
- failed_fields = []
- for field in SENSITIVE_AUTH_FIELDS:
- if result.get(field):
- new_value = migrate_value(result[field], old_key, new_key)
- if new_value:
- result[field] = new_value
- else:
- failed_fields.append(field)
- return result, failed_fields
-
-
-def verify_migration(conn, new_key: str) -> tuple[int, int]:
- """Verify migrated data can be decrypted with the new key.
-
- Samples records from each table and attempts decryption.
-
- Returns:
- Tuple of (verified_count, failed_count).
- """
- verified, failed = 0, 0
-
- # Verify user.store_api_key (sample up to 3)
-```
-
-This function is important because it defines how Langflow Tutorial: Visual AI Agent and Workflow Platform implements the patterns covered in this chapter.
-
-### `scripts/migrate_secret_key.py`
-
-The `verify_migration` function in [`scripts/migrate_secret_key.py`](https://github.com/langflow-ai/langflow/blob/HEAD/scripts/migrate_secret_key.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def verify_migration(conn, new_key: str) -> tuple[int, int]:
- """Verify migrated data can be decrypted with the new key.
-
- Samples records from each table and attempts decryption.
-
- Returns:
- Tuple of (verified_count, failed_count).
- """
- verified, failed = 0, 0
-
- # Verify user.store_api_key (sample up to 3)
- users = conn.execute(
- text('SELECT id, store_api_key FROM "user" WHERE store_api_key IS NOT NULL LIMIT 3')
- ).fetchall()
- for _, encrypted_key in users:
- try:
- decrypt_with_key(encrypted_key, new_key)
- verified += 1
- except InvalidToken:
- failed += 1
-
- # Verify variable.value (sample up to 3)
- variables = conn.execute(
- text("SELECT id, value FROM variable WHERE type = :type AND value IS NOT NULL LIMIT 3"),
- {"type": CREDENTIAL_TYPE},
- ).fetchall()
- for _, encrypted_value in variables:
- try:
- decrypt_with_key(encrypted_value, new_key)
- verified += 1
-```
-
-This function is important because it defines how Langflow Tutorial: Visual AI Agent and Workflow Platform implements the patterns covered in this chapter.
-
-
## How These Components Connect
```mermaid
flowchart TD
- A[encrypt_with_key]
- B[migrate_value]
- C[migrate_auth_settings]
- D[verify_migration]
- A --> B
- B --> C
- C --> D
+ A[Agent flow in Langflow] --> B[Agent component]
+ B --> C[LLM node]
+ B --> D[Tool nodes]
+ D --> E[Search tool]
+ D --> F[Code execution tool]
+ D --> G[Custom tool]
+ C --> H[ReAct reasoning loop]
+ H --> I[Select and invoke tool]
+ I --> J[Observe result]
+ J --> H
+ H --> K[Final answer]
```
diff --git a/tutorials/langflow-tutorial/05-api-and-mcp-deployment.md b/tutorials/langflow-tutorial/05-api-and-mcp-deployment.md
index 471a005b..762e8968 100644
--- a/tutorials/langflow-tutorial/05-api-and-mcp-deployment.md
+++ b/tutorials/langflow-tutorial/05-api-and-mcp-deployment.md
@@ -38,184 +38,16 @@ You now have a practical approach for publishing Langflow workflows as reusable
Next: [Chapter 6: Observability and Security](06-observability-and-security.md)
-## Depth Expansion Playbook
-
-## Source Code Walkthrough
-
-### `scripts/migrate_secret_key.py`
-
-The `get_default_database_url` function in [`scripts/migrate_secret_key.py`](https://github.com/langflow-ai/langflow/blob/HEAD/scripts/migrate_secret_key.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def get_default_database_url(config_dir: Path) -> str | None:
- """Get database URL from default SQLite location."""
- default_db = config_dir / "langflow.db"
- if default_db.exists():
- return f"sqlite:///{default_db}"
- return None
-
-
-DATABASE_URL_DISPLAY_LENGTH = 50
-
-
-def migrate(
- config_dir: Path,
- database_url: str,
- old_key: str | None = None,
- new_key: str | None = None,
- *,
- dry_run: bool = False,
-):
- """Run the secret key migration.
-
- Args:
- config_dir: Path to Langflow config directory containing secret_key file.
- database_url: SQLAlchemy database connection URL.
- old_key: Current secret key. If None, reads from config_dir/secret_key.
- new_key: New secret key. If None, generates a secure random key.
- dry_run: If True, simulates migration without making changes.
-
- The migration runs as an atomic transaction - either all database changes
- succeed or none are applied. Key files are only modified after successful
-```
-
-This function is important because it defines how Langflow Tutorial: Visual AI Agent and Workflow Platform implements the patterns covered in this chapter.
-
-### `scripts/migrate_secret_key.py`
-
-The `migrate` function in [`scripts/migrate_secret_key.py`](https://github.com/langflow-ai/langflow/blob/HEAD/scripts/migrate_secret_key.py) handles a key part of this chapter's functionality:
-
-```py
-
-Usage:
- uv run python scripts/migrate_secret_key.py --help
- uv run python scripts/migrate_secret_key.py --dry-run
- uv run python scripts/migrate_secret_key.py --database-url postgresql://...
-"""
-
-import argparse
-import base64
-import json
-import os
-import platform
-import random
-import secrets
-import sys
-from datetime import datetime, timezone
-from pathlib import Path
-
-from cryptography.fernet import Fernet, InvalidToken
-from platformdirs import user_cache_dir
-from sqlalchemy import create_engine, text
-
-MINIMUM_KEY_LENGTH = 32
-SENSITIVE_AUTH_FIELDS = ["oauth_client_secret", "api_key"]
-# Must match langflow.services.variable.constants.CREDENTIAL_TYPE
-CREDENTIAL_TYPE = "Credential"
-
-
-def get_default_config_dir() -> Path:
- """Get the default Langflow config directory using platformdirs."""
- return Path(user_cache_dir("langflow", "langflow"))
-
-```
-
-This function is important because it defines how Langflow Tutorial: Visual AI Agent and Workflow Platform implements the patterns covered in this chapter.
-
-### `scripts/migrate_secret_key.py`
-
-The `main` function in [`scripts/migrate_secret_key.py`](https://github.com/langflow-ai/langflow/blob/HEAD/scripts/migrate_secret_key.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def main():
- default_config = get_config_dir()
-
- parser = argparse.ArgumentParser(
- description="Migrate Langflow encrypted data to a new secret key",
- formatter_class=argparse.RawDescriptionHelpFormatter,
- epilog="""
-Examples:
- # Preview what will be migrated
- %(prog)s --dry-run
-
- # Run migration with defaults
- %(prog)s
-
- # Custom database and config
- %(prog)s --database-url postgresql://user:pass@host/db --config-dir /etc/langflow # pragma: allowlist secret
-
- # Provide keys explicitly
- %(prog)s --old-key "current-key" --new-key "replacement-key"
- """,
- )
-
- parser.add_argument(
- "--dry-run",
- action="store_true",
- help="Preview changes without modifying anything",
- )
- parser.add_argument(
- "--config-dir",
- type=Path,
-```
-
-This function is important because it defines how Langflow Tutorial: Visual AI Agent and Workflow Platform implements the patterns covered in this chapter.
-
-### `scripts/generate_coverage_config.py`
-
-The `extract_sidebar_bundles` function in [`scripts/generate_coverage_config.py`](https://github.com/langflow-ai/langflow/blob/HEAD/scripts/generate_coverage_config.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def extract_sidebar_bundles(frontend_path: Path) -> set[str]:
- """Extract component names from SIDEBAR_BUNDLES in styleUtils.ts."""
- style_utils_path = frontend_path / "src/utils/styleUtils.ts"
-
- if not style_utils_path.exists():
- print(f"Warning: styleUtils.ts not found at {style_utils_path}")
- return set()
-
- bundle_names = set()
-
- with style_utils_path.open(encoding="utf-8") as f:
- content = f.read()
-
- # Find SIDEBAR_BUNDLES array
- sidebar_match = re.search(r"export const SIDEBAR_BUNDLES = \[(.*?)\];", content, re.DOTALL)
- if not sidebar_match:
- print("Warning: SIDEBAR_BUNDLES not found in styleUtils.ts")
- return set()
-
- bundles_content = sidebar_match.group(1)
-
- # Extract name fields using regex
- name_matches = re.findall(r'name:\s*["\']([^"\']+)["\']', bundles_content)
-
- for name in name_matches:
- bundle_names.add(name)
-
- print(f"Found {len(bundle_names)} bundled components from SIDEBAR_BUNDLES")
- return bundle_names
-
-```
-
-This function is important because it defines how Langflow Tutorial: Visual AI Agent and Workflow Platform implements the patterns covered in this chapter.
-
-
## How These Components Connect
```mermaid
flowchart TD
- A[get_default_database_url]
- B[migrate]
- C[main]
- D[extract_sidebar_bundles]
- A --> B
- B --> C
- C --> D
+ A[Langflow flow] --> B[Auto-generated REST API]
+ B --> C[POST /api/v1/run/:flow_id]
+ C --> D[Execute flow]
+ D --> E[Return structured JSON]
+ A --> F[MCP server endpoint]
+ F --> G[Claude Desktop / AI coding tools]
+ G --> H[Tool calls via MCP protocol]
+ H --> D
```
diff --git a/tutorials/langflow-tutorial/06-observability-and-security.md b/tutorials/langflow-tutorial/06-observability-and-security.md
index 05165a38..d3e89471 100644
--- a/tutorials/langflow-tutorial/06-observability-and-security.md
+++ b/tutorials/langflow-tutorial/06-observability-and-security.md
@@ -40,184 +40,17 @@ You now have a security and telemetry baseline for operating Langflow safely.
Next: [Chapter 7: Custom Components and Extensions](07-custom-components-and-extensions.md)
-## Depth Expansion Playbook
-
-## Source Code Walkthrough
-
-### `scripts/generate_coverage_config.py`
-
-The `find_legacy_components` function in [`scripts/generate_coverage_config.py`](https://github.com/langflow-ai/langflow/blob/HEAD/scripts/generate_coverage_config.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def find_legacy_components(backend_components_path: Path) -> set[str]:
- """Find Python files containing 'legacy = True'."""
- legacy_files = set()
-
- if not backend_components_path.exists():
- print(f"Warning: Backend components path not found: {backend_components_path}")
- return set()
-
- # Walk through all Python files in components directory
- for py_file in backend_components_path.rglob("*.py"):
- try:
- with py_file.open(encoding="utf-8") as f:
- content = f.read()
-
- # Check if file contains 'legacy = True'
- if re.search(r"\blegacy\s*=\s*True\b", content):
- # Get relative path from components directory
- rel_path = py_file.relative_to(backend_components_path)
- legacy_files.add(str(rel_path))
-
- except (UnicodeDecodeError, PermissionError) as e:
- print(f"Warning: Could not read {py_file}: {e}")
- continue
-
- print(f"Found {len(legacy_files)} legacy component files")
- return legacy_files
-
-
-def generate_coveragerc(bundle_names: set[str], legacy_files: set[str], output_path: Path):
- """Generate .coveragerc file with omit patterns."""
-```
-
-This function is important because it defines how Langflow Tutorial: Visual AI Agent and Workflow Platform implements the patterns covered in this chapter.
-
-### `scripts/generate_coverage_config.py`
-
-The `generate_coveragerc` function in [`scripts/generate_coverage_config.py`](https://github.com/langflow-ai/langflow/blob/HEAD/scripts/generate_coverage_config.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def generate_coveragerc(bundle_names: set[str], legacy_files: set[str], output_path: Path):
- """Generate .coveragerc file with omit patterns."""
- # Base coveragerc content
- config_content = """# Auto-generated .coveragerc file
-# Generated by scripts/generate_coverage_config.py
-# Do not edit manually - changes will be overwritten
-
-[run]
-source = src/backend/base/langflow
-omit =
- # Test files
- */tests/*
- */test_*
- */*test*
-
- # Migration files
- */alembic/*
- */migrations/*
-
- # Cache and build files
- */__pycache__/*
- */.*
-
- # Init files (typically just imports)
- */__init__.py
-
- # Deactivate Components
- */components/deactivated/*
-
-"""
-```
-
-This function is important because it defines how Langflow Tutorial: Visual AI Agent and Workflow Platform implements the patterns covered in this chapter.
-
-### `scripts/generate_coverage_config.py`
-
-The `main` function in [`scripts/generate_coverage_config.py`](https://github.com/langflow-ai/langflow/blob/HEAD/scripts/generate_coverage_config.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def main():
- """Main function."""
- # Determine project root (script is in scripts/ directory)
- script_dir = Path(__file__).parent
- project_root = script_dir.parent
-
- # Paths
- frontend_path = project_root / "src" / "frontend"
- backend_components_path = project_root / "src" / "backend" / "base" / "langflow" / "components"
- output_path = project_root / "src" / "backend" / ".coveragerc"
-
- print(f"Project root: {project_root}")
- print(f"Frontend path: {frontend_path}")
- print(f"Backend components path: {backend_components_path}")
- print(f"Output path: {output_path}")
- print()
-
- # Extract bundled component names
- bundle_names = extract_sidebar_bundles(frontend_path)
-
- # Find legacy components
- legacy_files = find_legacy_components(backend_components_path)
-
- # Generate .coveragerc file
- generate_coveragerc(bundle_names, legacy_files, output_path)
-
- print("\nDone! You can now run backend tests with coverage using:")
- print("cd src/backend && python -m pytest --cov=src/backend/base/langflow --cov-config=.coveragerc")
-
-
-```
-
-This function is important because it defines how Langflow Tutorial: Visual AI Agent and Workflow Platform implements the patterns covered in this chapter.
-
-### `scripts/check_changes_filter.py`
-
-The `load_filter_patterns` function in [`scripts/check_changes_filter.py`](https://github.com/langflow-ai/langflow/blob/HEAD/scripts/check_changes_filter.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def load_filter_patterns(filter_file: Path) -> dict[str, list[str]]:
- """Load all patterns from the changes-filter.yaml file.
-
- Validates and normalizes the YAML structure to ensure it's a dict mapping
- str to list[str]. Handles top-level "filters" key if present.
- """
- with filter_file.open() as f:
- data = yaml.safe_load(f)
-
- # Handle empty or null file
- if data is None:
- return {}
-
- # If there's a top-level "filters" key, use that instead
- if isinstance(data, dict) and "filters" in data:
- data = data["filters"]
-
- # Ensure we have a dict
- if not isinstance(data, dict):
- msg = f"Expected dict at top level, got {type(data).__name__}"
- raise TypeError(msg)
-
- # Normalize and validate the structure
- result: dict[str, list[str]] = {}
- for key, value in data.items():
- # Validate key is a string
- if not isinstance(key, str):
- msg = f"Expected string key, got {type(key).__name__}: {key}"
- raise TypeError(msg)
-
-```
-
-This function is important because it defines how Langflow Tutorial: Visual AI Agent and Workflow Platform implements the patterns covered in this chapter.
-
-
## How These Components Connect
```mermaid
flowchart TD
- A[find_legacy_components]
- B[generate_coveragerc]
- C[main]
- D[load_filter_patterns]
- A --> B
- B --> C
- C --> D
+ A[Langflow server] --> B[Request authentication]
+ B --> C{Auth method}
+ C -->|API key| D[x-api-key header]
+ C -->|OAuth| E[JWT token]
+ D --> F[Execute flow]
+ E --> F
+ F --> G[LangSmith tracing]
+ G --> H[Per-run trace: inputs, outputs, latency]
+ H --> I[Alerting / dashboards]
```
diff --git a/tutorials/langflow-tutorial/07-custom-components-and-extensions.md b/tutorials/langflow-tutorial/07-custom-components-and-extensions.md
index ccf983d3..062d0f7e 100644
--- a/tutorials/langflow-tutorial/07-custom-components-and-extensions.md
+++ b/tutorials/langflow-tutorial/07-custom-components-and-extensions.md
@@ -39,184 +39,15 @@ You now know how to extend Langflow without compromising maintainability.
Next: [Chapter 8: Production Operations](08-production-operations.md)
-## Depth Expansion Playbook
-
-## Source Code Walkthrough
-
-### `scripts/check_changes_filter.py`
-
-The `get_changed_files_from_stdin` function in [`scripts/check_changes_filter.py`](https://github.com/langflow-ai/langflow/blob/HEAD/scripts/check_changes_filter.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def get_changed_files_from_stdin() -> list[str]:
- """Get list of changed files from stdin (one per line), filtered to src/frontend only."""
- files = []
- for line in sys.stdin:
- stripped = line.strip()
- if stripped and stripped.startswith("src/frontend/"):
- files.append(stripped)
- return files
-
-
-def matches_pattern(file_path: str, pattern: str) -> bool:
- """Check if a file matches a glob pattern using pathlib semantics.
-
- Supports ** and a simple one-level {a,b} brace expansion.
- """
- import re
- from pathlib import PurePosixPath
-
- # Normalize
- file_path = file_path.lstrip("./").replace("\\", "/")
- pattern = pattern.lstrip("./")
-
- # Simple one-level brace expansion: foo.{ts,tsx} -> [foo.ts, foo.tsx]
- patterns = [pattern]
- m = re.search(r"\{([^{}]+)\}", pattern)
- if m:
- opts = [opt.strip() for opt in m.group(1).split(",")]
- pre, post = pattern[: m.start()], pattern[m.end() :]
- patterns = [f"{pre}{opt}{post}" for opt in opts]
-
-```
-
-This function is important because it defines how Langflow Tutorial: Visual AI Agent and Workflow Platform implements the patterns covered in this chapter.
-
-### `scripts/check_changes_filter.py`
-
-The `matches_pattern` function in [`scripts/check_changes_filter.py`](https://github.com/langflow-ai/langflow/blob/HEAD/scripts/check_changes_filter.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def matches_pattern(file_path: str, pattern: str) -> bool:
- """Check if a file matches a glob pattern using pathlib semantics.
-
- Supports ** and a simple one-level {a,b} brace expansion.
- """
- import re
- from pathlib import PurePosixPath
-
- # Normalize
- file_path = file_path.lstrip("./").replace("\\", "/")
- pattern = pattern.lstrip("./")
-
- # Simple one-level brace expansion: foo.{ts,tsx} -> [foo.ts, foo.tsx]
- patterns = [pattern]
- m = re.search(r"\{([^{}]+)\}", pattern)
- if m:
- opts = [opt.strip() for opt in m.group(1).split(",")]
- pre, post = pattern[: m.start()], pattern[m.end() :]
- patterns = [f"{pre}{opt}{post}" for opt in opts]
-
- # PurePosixPath.match() only does relative matching from the right
- # For patterns with **, we need full path matching
- for pat in patterns:
- if "**" in pat:
- # Use fnmatch-style matching for ** patterns
- # Convert ** to match any depth
- import fnmatch
-
- regex_pattern = pat.replace("**", "*")
- if fnmatch.fnmatch(file_path, regex_pattern):
-```
-
-This function is important because it defines how Langflow Tutorial: Visual AI Agent and Workflow Platform implements the patterns covered in this chapter.
-
-### `scripts/check_changes_filter.py`
-
-The `check_file_coverage` function in [`scripts/check_changes_filter.py`](https://github.com/langflow-ai/langflow/blob/HEAD/scripts/check_changes_filter.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def check_file_coverage(changed_files: list[str], filter_patterns: dict[str, list[str]]) -> tuple[list[str], list[str]]:
- """Check which files are covered by at least one pattern.
-
- Returns: (covered_files, uncovered_files)
- """
- # Flatten all patterns from all categories
- all_patterns = []
- for category_patterns in filter_patterns.values():
- all_patterns.extend(category_patterns)
-
- covered = []
- uncovered = []
-
- for file_path in changed_files:
- is_covered = False
- for pattern in all_patterns:
- if matches_pattern(file_path, pattern):
- is_covered = True
- break
-
- if is_covered:
- covered.append(file_path)
- else:
- uncovered.append(file_path)
-
- return covered, uncovered
-
-
-def main():
- """Main execution function."""
-```
-
-This function is important because it defines how Langflow Tutorial: Visual AI Agent and Workflow Platform implements the patterns covered in this chapter.
-
-### `scripts/check_changes_filter.py`
-
-The `main` function in [`scripts/check_changes_filter.py`](https://github.com/langflow-ai/langflow/blob/HEAD/scripts/check_changes_filter.py) handles a key part of this chapter's functionality:
-
-```py
-
-Usage:
- # Check files changed in current branch vs main
- git diff --name-only origin/main HEAD | python scripts/check_changes_filter.py
-
- # Check specific files
- echo -e "src/frontend/file1.tsx\nsrc/frontend/file2.ts" | python scripts/check_changes_filter.py
-
-Note:
- Only files under src/frontend/ are checked. All other files are ignored.
-
-Exit codes:
- 0 - All frontend files are covered by patterns
- 1 - Some frontend files are not covered (or error occurred)
-"""
-
-import sys
-from pathlib import Path
-
-import yaml
-
-
-def load_filter_patterns(filter_file: Path) -> dict[str, list[str]]:
- """Load all patterns from the changes-filter.yaml file.
-
- Validates and normalizes the YAML structure to ensure it's a dict mapping
- str to list[str]. Handles top-level "filters" key if present.
- """
- with filter_file.open() as f:
- data = yaml.safe_load(f)
-
- # Handle empty or null file
-```
-
-This function is important because it defines how Langflow Tutorial: Visual AI Agent and Workflow Platform implements the patterns covered in this chapter.
-
-
## How These Components Connect
```mermaid
flowchart TD
- A[get_changed_files_from_stdin]
- B[matches_pattern]
- C[check_file_coverage]
- D[main]
- A --> B
- B --> C
- C --> D
+ A[Custom component class] --> B[Extend CustomComponent]
+ B --> C[Define inputs as class attributes]
+ C --> D[Implement build method]
+ D --> E[Return LangChain object]
+ E --> F[Register in Langflow component list]
+ F --> G[Available in canvas palette]
+ G --> H[Drag into flow, connect, run]
```
diff --git a/tutorials/langflow-tutorial/08-production-operations.md b/tutorials/langflow-tutorial/08-production-operations.md
index 7f98bc55..c624113c 100644
--- a/tutorials/langflow-tutorial/08-production-operations.md
+++ b/tutorials/langflow-tutorial/08-production-operations.md
@@ -38,184 +38,16 @@ This chapter turns Langflow from a builder experience into a production platform
You now have an operational baseline for running Langflow at production scale.
-## Depth Expansion Playbook
-
-## Source Code Walkthrough
-
-### `docs/docusaurus.config.js`
-
-The `gtag` function in [`docs/docusaurus.config.js`](https://github.com/langflow-ai/langflow/blob/HEAD/docs/docusaurus.config.js) handles a key part of this chapter's functionality:
-
-```js
- innerHTML: `
- window.dataLayer = window.dataLayer || [];
- function gtag(){dataLayer.push(arguments);}
-
- // Set default consent to denied
- gtag('consent', 'default', {
- 'ad_storage': 'denied',
- 'ad_user_data': 'denied',
- 'ad_personalization': 'denied',
- 'analytics_storage': 'denied'
- });
- `,
- },
- // TrustArc Consent Update Listener
- {
- tagName: "script",
- attributes: {},
- innerHTML: `
- (function() {
- function updateGoogleConsent() {
- if (typeof window.truste !== 'undefined' && window.truste.cma) {
- var consent = window.truste.cma.callApi('getConsent', window.location.href) || {};
-
- // Map TrustArc categories to Google consent types
- // Category 0 = Required, 1 = Functional, 2 = Advertising, 3 = Analytics
- var hasAdvertising = consent[2] === 1;
- var hasAnalytics = consent[3] === 1;
-
- gtag('consent', 'update', {
- 'ad_storage': hasAdvertising ? 'granted' : 'denied',
- 'ad_user_data': hasAdvertising ? 'granted' : 'denied',
- 'ad_personalization': hasAdvertising ? 'granted' : 'denied',
-```
-
-This function is important because it defines how Langflow Tutorial: Visual AI Agent and Workflow Platform implements the patterns covered in this chapter.
-
-### `docs/docusaurus.config.js`
-
-The `updateGoogleConsent` function in [`docs/docusaurus.config.js`](https://github.com/langflow-ai/langflow/blob/HEAD/docs/docusaurus.config.js) handles a key part of this chapter's functionality:
-
-```js
- innerHTML: `
- (function() {
- function updateGoogleConsent() {
- if (typeof window.truste !== 'undefined' && window.truste.cma) {
- var consent = window.truste.cma.callApi('getConsent', window.location.href) || {};
-
- // Map TrustArc categories to Google consent types
- // Category 0 = Required, 1 = Functional, 2 = Advertising, 3 = Analytics
- var hasAdvertising = consent[2] === 1;
- var hasAnalytics = consent[3] === 1;
-
- gtag('consent', 'update', {
- 'ad_storage': hasAdvertising ? 'granted' : 'denied',
- 'ad_user_data': hasAdvertising ? 'granted' : 'denied',
- 'ad_personalization': hasAdvertising ? 'granted' : 'denied',
- 'analytics_storage': hasAnalytics ? 'granted' : 'denied'
- });
- }
- }
-
- // Listen for consent changes
- if (window.addEventListener) {
- window.addEventListener('cm_data_subject_consent_changed', updateGoogleConsent);
- window.addEventListener('cm_consent_preferences_set', updateGoogleConsent);
- }
-
- // Initial check after TrustArc loads
- if (document.readyState === 'complete') {
- updateGoogleConsent();
- } else {
- window.addEventListener('load', updateGoogleConsent);
- }
-```
-
-This function is important because it defines how Langflow Tutorial: Visual AI Agent and Workflow Platform implements the patterns covered in this chapter.
-
-### `docs/docusaurus.config.js`
-
-The `langflowCodeImportPlugin` function in [`docs/docusaurus.config.js`](https://github.com/langflow-ai/langflow/blob/HEAD/docs/docusaurus.config.js) handles a key part of this chapter's functionality:
-
-```js
- plugins: [
- // Alias so MDX can import code from the Langflow repo with !!raw-loader!@langflow/src/...
- function langflowCodeImportPlugin(context) {
- return {
- name: "langflow-code-import",
- configureWebpack() {
- return {
- resolve: {
- alias: {
- "@langflow": path.resolve(context.siteDir, ".."),
- },
- },
- };
- },
- };
- },
- ["docusaurus-node-polyfills", { excludeAliases: ["console"] }],
- "docusaurus-plugin-image-zoom",
- ["./src/plugins/segment", { segmentPublicWriteKey: process.env.SEGMENT_PUBLIC_WRITE_KEY, allowedInDev: true }],
- [
- "@docusaurus/plugin-client-redirects",
- {
- redirects: [
- {
- to: "/",
- from: [
- "/whats-new-a-new-chapter-langflow",
- "/👋 Welcome-to-Langflow",
- "/getting-started-welcome-to-langflow",
- "/guides-new-to-llms",
- "/about-langflow",
- ],
-```
-
-This function is important because it defines how Langflow Tutorial: Visual AI Agent and Workflow Platform implements the patterns covered in this chapter.
-
-### `docs/docusaurus.config.js`
-
-The `myPlugin` function in [`docs/docusaurus.config.js`](https://github.com/langflow-ai/langflow/blob/HEAD/docs/docusaurus.config.js) handles a key part of this chapter's functionality:
-
-```js
- ],
- // ....
- async function myPlugin(context, options) {
- return {
- name: "docusaurus-tailwindcss",
- configurePostCss(postcssOptions) {
- // Appends TailwindCSS and AutoPrefixer.
- postcssOptions.plugins.push(require("tailwindcss"));
- postcssOptions.plugins.push(require("autoprefixer"));
- return postcssOptions;
- },
- };
- },
- ],
- themeConfig:
- /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
- ({
- navbar: {
- hideOnScroll: true,
- logo: {
- alt: "Langflow",
- src: "img/lf-docs-light.svg",
- srcDark: "img/lf-docs-dark.svg",
- },
- items: [
- // right
- {
- position: "right",
- href: "https://github.com/langflow-ai/langflow",
- className: "header-github-link",
- target: "_blank",
- rel: null,
-```
-
-This function is important because it defines how Langflow Tutorial: Visual AI Agent and Workflow Platform implements the patterns covered in this chapter.
-
-
## How These Components Connect
```mermaid
flowchart TD
- A[gtag]
- B[updateGoogleConsent]
- C[langflowCodeImportPlugin]
- D[myPlugin]
- A --> B
- B --> C
- C --> D
+ A[Langflow in production] --> B[Docker / K8s deployment]
+ B --> C[PostgreSQL for flow storage]
+ C --> D[Horizontal scaling]
+ D --> E[Load balancer]
+ E --> F[Health endpoint /health]
+ F --> G{Healthy?}
+ G -->|Yes| H[Serve API traffic]
+ G -->|No| I[Restart pod / container]
```
diff --git a/tutorials/langfuse-tutorial/01-getting-started.md b/tutorials/langfuse-tutorial/01-getting-started.md
index 43dfd669..589ef232 100644
--- a/tutorials/langfuse-tutorial/01-getting-started.md
+++ b/tutorials/langfuse-tutorial/01-getting-started.md
@@ -6,6 +6,7 @@ has_children: false
parent: Langfuse Tutorial
---
+
# Chapter 1: Getting Started with Langfuse
Welcome to **Chapter 1: Getting Started with Langfuse**. In this part of **Langfuse Tutorial: LLM Observability, Evaluation, and Prompt Operations**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
@@ -321,316 +322,148 @@ Under **Settings** you manage API keys, team members, project configuration, and
## Depth Expansion Playbook
-<!-- depth-expansion-v2 -->
-
-This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
-
-### Strategic Context
-
-- tutorial: **Langfuse Tutorial: LLM Observability, Evaluation, and Prompt Operations**
-- tutorial slug: **langfuse-tutorial**
-- chapter focus: **Chapter 1: Getting Started with Langfuse**
-- system context: **Langfuse Tutorial**
-- objective: move from surface-level usage to repeatable engineering operation
-
-### Architecture Decomposition
-
-1. Define the runtime boundary for `Chapter 1: Getting Started with Langfuse`.
-2. Separate control-plane decisions from data-plane execution.
-3. Capture input contracts, transformation points, and output contracts.
-4. Trace state transitions across request lifecycle stages.
-5. Identify extension hooks and policy interception points.
-6. Map ownership boundaries for team and automation workflows.
-7. Specify rollback and recovery paths for unsafe changes.
-8. Track observability signals for correctness, latency, and cost.
-
-### Operator Decision Matrix
-
-| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
-|:--------------|:--------------|:------------------|:---------|
-| Runtime mode | managed defaults | explicit policy config | speed vs control |
-| State handling | local ephemeral | durable persisted state | simplicity vs auditability |
-| Tool integration | direct API use | mediated adapter layer | velocity vs governance |
-| Rollout method | manual change | staged + canary rollout | effort vs safety |
-| Incident response | best effort logs | runbooks + SLO alerts | cost vs reliability |
-
-### Failure Modes and Countermeasures
-
-| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
-|:-------------|:-------------|:-------------------|:---------------|
-| stale context | inconsistent outputs | missing refresh window | enforce context TTL and refresh hooks |
-| policy drift | unexpected execution | ad hoc overrides | centralize policy profiles |
-| auth mismatch | 401/403 bursts | credential sprawl | rotation schedule + scope minimization |
-| schema breakage | parser/validation errors | unmanaged upstream changes | contract tests per release |
-| retry storms | queue congestion | no backoff controls | jittered backoff + circuit breakers |
-| silent regressions | quality drop without alerts | weak baseline metrics | eval harness with thresholds |
-
-### Implementation Runbook
-
-1. Establish a reproducible baseline environment.
-2. Capture chapter-specific success criteria before changes.
-3. Implement minimal viable path with explicit interfaces.
-4. Add observability before expanding feature scope.
-5. Run deterministic tests for happy-path behavior.
-6. Inject failure scenarios for negative-path validation.
-7. Compare output quality against baseline snapshots.
-8. Promote through staged environments with rollback gates.
-9. Record operational lessons in release notes.
-
-### Quality Gate Checklist
-
-- [ ] chapter-level assumptions are explicit and testable
-- [ ] API/tool boundaries are documented with input/output examples
-- [ ] failure handling includes retry, timeout, and fallback policy
-- [ ] security controls include auth scopes and secret rotation plans
-- [ ] observability includes logs, metrics, traces, and alert thresholds
-- [ ] deployment guidance includes canary and rollback paths
-- [ ] docs include links to upstream sources and related tracks
-- [ ] post-release verification confirms expected behavior under load
-
-### Source Alignment
-
-- [Langfuse Repository](https://github.com/langfuse/langfuse)
-- [Langfuse Releases](https://github.com/langfuse/langfuse/releases)
-- [Langfuse Docs](https://langfuse.com/docs)
-
-### Cross-Tutorial Connection Map
-
-- [LiteLLM Tutorial](../litellm-tutorial/)
-- [LangChain Tutorial](../langchain-tutorial/)
-- [LlamaIndex Tutorial](../llamaindex-tutorial/)
-- [Vercel AI SDK Tutorial](../vercel-ai-tutorial/)
-- [Chapter 1: Getting Started](01-getting-started.md)
-
-### Advanced Practice Exercises
-
-1. Build a minimal end-to-end implementation for `Chapter 1: Getting Started with Langfuse`.
-2. Add instrumentation and measure baseline latency and error rate.
-3. Introduce one controlled failure and confirm graceful recovery.
-4. Add policy constraints and verify they are enforced consistently.
-5. Run a staged rollout and document rollback decision criteria.
-
-### Review Questions
-
-1. Which execution boundary matters most for this chapter and why?
-2. What signal detects regressions earliest in your environment?
-3. What tradeoff did you make between delivery speed and governance?
-4. How would you recover from the highest-impact failure mode?
-5. What must be automated before scaling to team-wide adoption?
-
-### Scenario Playbook 1: Chapter 1: Getting Started with Langfuse
-
-- tutorial context: **Langfuse Tutorial: LLM Observability, Evaluation, and Prompt Operations**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 2: Chapter 1: Getting Started with Langfuse
-
-- tutorial context: **Langfuse Tutorial: LLM Observability, Evaluation, and Prompt Operations**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 3: Chapter 1: Getting Started with Langfuse
-
-- tutorial context: **Langfuse Tutorial: LLM Observability, Evaluation, and Prompt Operations**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 4: Chapter 1: Getting Started with Langfuse
-
-- tutorial context: **Langfuse Tutorial: LLM Observability, Evaluation, and Prompt Operations**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 5: Chapter 1: Getting Started with Langfuse
-
-- tutorial context: **Langfuse Tutorial: LLM Observability, Evaluation, and Prompt Operations**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 6: Chapter 1: Getting Started with Langfuse
-
-- tutorial context: **Langfuse Tutorial: LLM Observability, Evaluation, and Prompt Operations**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 7: Chapter 1: Getting Started with Langfuse
-
-- tutorial context: **Langfuse Tutorial: LLM Observability, Evaluation, and Prompt Operations**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 8: Chapter 1: Getting Started with Langfuse
-
-- tutorial context: **Langfuse Tutorial: LLM Observability, Evaluation, and Prompt Operations**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 9: Chapter 1: Getting Started with Langfuse
-
-- tutorial context: **Langfuse Tutorial: LLM Observability, Evaluation, and Prompt Operations**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 10: Chapter 1: Getting Started with Langfuse
-
-- tutorial context: **Langfuse Tutorial: LLM Observability, Evaluation, and Prompt Operations**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 11: Chapter 1: Getting Started with Langfuse
-
-- tutorial context: **Langfuse Tutorial: LLM Observability, Evaluation, and Prompt Operations**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 12: Chapter 1: Getting Started with Langfuse
-
-- tutorial context: **Langfuse Tutorial: LLM Observability, Evaluation, and Prompt Operations**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 13: Chapter 1: Getting Started with Langfuse
-
-- tutorial context: **Langfuse Tutorial: LLM Observability, Evaluation, and Prompt Operations**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 14: Chapter 1: Getting Started with Langfuse
-
-- tutorial context: **Langfuse Tutorial: LLM Observability, Evaluation, and Prompt Operations**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-## What Problem Does This Solve?
-
-Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for `langfuse`, `Langfuse`, `trace` so behavior stays predictable as complexity grows.
-
-In practical terms, this chapter helps you avoid three common failures:
-
-- coupling core logic too tightly to one implementation path
-- missing the handoff boundaries between setup, execution, and validation
-- shipping changes without clear rollback or observability strategy
-
-After working through this chapter, you should be able to reason about `Chapter 1: Getting Started with Langfuse` as an operating subsystem inside **Langfuse Tutorial: LLM Observability, Evaluation, and Prompt Operations**, with explicit contracts for inputs, state transitions, and outputs.
-
-Use the implementation notes around `span`, `style`, `fill` as your checklist when adapting these patterns to your own repository.
-
-## How it Works Under the Hood
-
-Under the hood, `Chapter 1: Getting Started with Langfuse` usually follows a repeatable control path:
-
-1. **Context bootstrap**: initialize runtime config and prerequisites for `langfuse`.
-2. **Input normalization**: shape incoming data so `Langfuse` receives stable contracts.
-3. **Core execution**: run the main logic branch and propagate intermediate state through `trace`.
-4. **Policy and safety checks**: enforce limits, auth scopes, and failure boundaries.
-5. **Output composition**: return canonical result payloads for downstream consumers.
-6. **Operational telemetry**: emit logs/metrics needed for debugging and performance tuning.
-
-When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
-
-## Source Walkthrough
-
-Use the following upstream sources to verify implementation details while reading this chapter:
-
-- [Langfuse Repository](https://github.com/langfuse/langfuse)
- Why it matters: authoritative reference on `Langfuse Repository` (github.com).
-- [Langfuse Releases](https://github.com/langfuse/langfuse/releases)
- Why it matters: authoritative reference on `Langfuse Releases` (github.com).
-- [Langfuse Docs](https://langfuse.com/docs)
- Why it matters: authoritative reference on `Langfuse Docs` (langfuse.com).
-
-Suggested trace strategy:
-- search upstream code for `langfuse` and `Langfuse` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
-
-## Chapter Connections
-
-- [Tutorial Index](README.md)
-- [Next Chapter: Chapter 2: Tracing Fundamentals](02-tracing.md)
-- [Main Catalog](../../README.md#-tutorial-catalog)
-- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
+## Source Code Walkthrough
+
+### `package.json`
+
+The `package` module in [`package.json`](https://github.com/langfuse/langfuse/blob/HEAD/package.json) handles a key part of this chapter's functionality:
+
+```json
+{
+ "name": "langfuse",
+ "version": "3.163.0",
+ "author": "engineering@langfuse.com",
+ "license": "MIT",
+ "private": true,
+ "engines": {
+ "node": "24"
+ },
+ "scripts": {
+ "agents:check": "node scripts/agents/sync-agent-shims.mjs --check",
+ "agents:sync": "node scripts/agents/sync-agent-shims.mjs",
+ "postinstall": "node -e \"const fs = require('node:fs'); const cp = require('node:child_process'); if (!fs.existsSync('scripts/postinstall.sh')) { console.log('Skipping repo postinstall helper: scripts/postinstall.sh is not present in this install context.'); process.exit(0); } cp.execSync('bash scripts/postinstall.sh', { stdio: 'inherit' });\"",
+ "preinstall": "npx only-allow pnpm",
+ "infra:dev:up": "docker compose -f ./docker-compose.dev.yml up -d --wait",
+ "infra:dev:down": "docker compose -f ./docker-compose.dev.yml down",
+ "infra:dev:prune": "docker compose -f ./docker-compose.dev.yml down -v",
+ "db:generate": "turbo run db:generate",
+ "db:migrate": "turbo run db:migrate",
+ "db:seed": "turbo run db:seed",
+ "db:seed:examples": "turbo run db:seed:examples",
+ "nuke": "bash ./scripts/nuke.sh",
+ "dx": "pnpm i && pnpm run infra:dev:prune && pnpm run infra:dev:up --pull always && pnpm --filter=shared run db:reset:test && pnpm --filter=shared run db:reset && pnpm --filter=shared run ch:reset && pnpm --filter=shared run db:seed:examples && pnpm run dev",
+ "dx-f": "pnpm i && pnpm run infra:dev:prune && pnpm run infra:dev:up --pull always && pnpm --filter=shared run db:reset:test && pnpm --filter=shared run db:reset -f && SKIP_CONFIRM=1 pnpm --filter=shared run ch:reset && pnpm --filter=shared run db:seed:examples && pnpm run dev",
+ "dx:skip-infra": "pnpm i && pnpm --filter=shared run db:reset:test && pnpm --filter=shared run db:reset && pnpm --filter=shared run ch:reset && pnpm --filter=shared run db:seed:examples && pnpm run dev",
+ "build": "turbo run build",
+ "build:check": "turbo run build:check",
+ "typecheck": "turbo run typecheck",
+ "tc": "turbo run typecheck",
+ "start": "turbo run start",
+ "dev": "turbo run dev",
+ "dev:worker": "turbo run dev --filter=worker",
+ "dev:web": "turbo run dev --filter=web",
+ "dev:web-webpack": "turbo run dev --filter=web -- --webpack",
+ "lint": "turbo run lint",
+```
+
+This module is important because it defines how Langfuse Tutorial: LLM Observability, Evaluation, and Prompt Operations implements the patterns covered in this chapter.
+
+### `docker-compose.dev-azure.yml`
+
+The `docker-compose.dev-azure` module in [`docker-compose.dev-azure.yml`](https://github.com/langfuse/langfuse/blob/HEAD/docker-compose.dev-azure.yml) handles a key part of this chapter's functionality:
+
+```yml
+services:
+ clickhouse:
+ image: docker.io/clickhouse/clickhouse-server:24.3
+ user: "101:101"
+ environment:
+ CLICKHOUSE_DB: default
+ CLICKHOUSE_USER: ${CLICKHOUSE_USER:-clickhouse}
+ CLICKHOUSE_PASSWORD: ${CLICKHOUSE_PASSWORD:-clickhouse}
+ volumes:
+ - langfuse_clickhouse_data:/var/lib/clickhouse
+ - langfuse_clickhouse_logs:/var/log/clickhouse-server
+ ports:
+ - "8123:8123"
+ - "9000:9000"
+ healthcheck:
+ test: wget --no-verbose --tries=1 --spider http://localhost:8123/ping || exit 1
+ interval: 5s
+ timeout: 5s
+ retries: 10
+ start_period: 1s
+ depends_on:
+ - postgres
+
+ azurite:
+ image: mcr.microsoft.com/azure-storage/azurite
+ command: azurite-blob --blobHost 0.0.0.0
+ ports:
+ - "10000:10000"
+ volumes:
+ - langfuse_azurite_data:/data
+
+ minio:
+ image: cgr.dev/chainguard/minio
+ container_name: ${MINIO_CONTAINER_NAME:-langfuse-minio}
+ entrypoint: sh
+```
+
+This module is important because it defines how Langfuse Tutorial: LLM Observability, Evaluation, and Prompt Operations implements the patterns covered in this chapter.
+
+### `docker-compose.yml`
+
+The `docker-compose` module in [`docker-compose.yml`](https://github.com/langfuse/langfuse/blob/HEAD/docker-compose.yml) handles a key part of this chapter's functionality:
+
+```yml
+# Make sure to update the credential placeholders with your own secrets.
+# We mark them with # CHANGEME in the file below.
+# In addition, we recommend to restrict inbound traffic on the host to langfuse-web (port 3000) and minio (port 9090) only.
+# All other components are bound to localhost (127.0.0.1) to only accept connections from the local machine.
+# External connections from other machines will not be able to reach these services directly.
+services:
+ langfuse-worker:
+ image: docker.io/langfuse/langfuse-worker:3
+ restart: always
+ depends_on: &langfuse-depends-on
+ postgres:
+ condition: service_healthy
+ minio:
+ condition: service_healthy
+ redis:
+ condition: service_healthy
+ clickhouse:
+ condition: service_healthy
+ ports:
+ - 127.0.0.1:3030:3030
+ environment: &langfuse-worker-env
+ NEXTAUTH_URL: ${NEXTAUTH_URL:-http://localhost:3000}
+ DATABASE_URL: ${DATABASE_URL:-postgresql://postgres:postgres@postgres:5432/postgres} # CHANGEME
+ SALT: ${SALT:-mysalt} # CHANGEME
+ ENCRYPTION_KEY: ${ENCRYPTION_KEY:-0000000000000000000000000000000000000000000000000000000000000000} # CHANGEME: generate via `openssl rand -hex 32`
+ TELEMETRY_ENABLED: ${TELEMETRY_ENABLED:-true}
+ LANGFUSE_ENABLE_EXPERIMENTAL_FEATURES: ${LANGFUSE_ENABLE_EXPERIMENTAL_FEATURES:-false}
+ CLICKHOUSE_MIGRATION_URL: ${CLICKHOUSE_MIGRATION_URL:-clickhouse://clickhouse:9000}
+ CLICKHOUSE_URL: ${CLICKHOUSE_URL:-http://clickhouse:8123}
+ CLICKHOUSE_USER: ${CLICKHOUSE_USER:-clickhouse}
+ CLICKHOUSE_PASSWORD: ${CLICKHOUSE_PASSWORD:-clickhouse} # CHANGEME
+ CLICKHOUSE_CLUSTER_ENABLED: ${CLICKHOUSE_CLUSTER_ENABLED:-false}
+ LANGFUSE_USE_AZURE_BLOB: ${LANGFUSE_USE_AZURE_BLOB:-false}
+ LANGFUSE_S3_EVENT_UPLOAD_BUCKET: ${LANGFUSE_S3_EVENT_UPLOAD_BUCKET:-langfuse}
+ LANGFUSE_S3_EVENT_UPLOAD_REGION: ${LANGFUSE_S3_EVENT_UPLOAD_REGION:-auto}
+```
+
+This module is important because it defines how Langfuse Tutorial: LLM Observability, Evaluation, and Prompt Operations implements the patterns covered in this chapter.
+
+
+## How These Components Connect
+
+```mermaid
+flowchart TD
+ A[package]
+ B[docker-compose.dev-azure]
+ C[docker-compose]
+ A --> B
+ B --> C
+```
diff --git a/tutorials/langfuse-tutorial/02-tracing.md b/tutorials/langfuse-tutorial/02-tracing.md
index e19d353b..e5bc0d9f 100644
--- a/tutorials/langfuse-tutorial/02-tracing.md
+++ b/tutorials/langfuse-tutorial/02-tracing.md
@@ -6,6 +6,7 @@ has_children: false
parent: Langfuse Tutorial
---
+
# Chapter 2: Tracing Fundamentals
Welcome to **Chapter 2: Tracing Fundamentals**. In this part of **Langfuse Tutorial: LLM Observability, Evaluation, and Prompt Operations**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
@@ -525,149 +526,148 @@ In the Langfuse UI this trace will display five nested spans (`rag_pipeline` > `
## Depth Expansion Playbook
-<!-- depth-expansion-v2 -->
-
-This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
-
-### Strategic Context
-
-- tutorial: **Langfuse Tutorial: LLM Observability, Evaluation, and Prompt Operations**
-- tutorial slug: **langfuse-tutorial**
-- chapter focus: **Chapter 2: Tracing Fundamentals**
-- system context: **Langfuse Tutorial**
-- objective: move from surface-level usage to repeatable engineering operation
-
-### Architecture Decomposition
-
-1. Define the runtime boundary for `Chapter 2: Tracing Fundamentals`.
-2. Separate control-plane decisions from data-plane execution.
-3. Capture input contracts, transformation points, and output contracts.
-4. Trace state transitions across request lifecycle stages.
-5. Identify extension hooks and policy interception points.
-6. Map ownership boundaries for team and automation workflows.
-7. Specify rollback and recovery paths for unsafe changes.
-8. Track observability signals for correctness, latency, and cost.
-
-### Operator Decision Matrix
-
-| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
-|:--------------|:--------------|:------------------|:---------|
-| Runtime mode | managed defaults | explicit policy config | speed vs control |
-| State handling | local ephemeral | durable persisted state | simplicity vs auditability |
-| Tool integration | direct API use | mediated adapter layer | velocity vs governance |
-| Rollout method | manual change | staged + canary rollout | effort vs safety |
-| Incident response | best effort logs | runbooks + SLO alerts | cost vs reliability |
-
-### Failure Modes and Countermeasures
-
-| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
-|:-------------|:-------------|:-------------------|:---------------|
-| stale context | inconsistent outputs | missing refresh window | enforce context TTL and refresh hooks |
-| policy drift | unexpected execution | ad hoc overrides | centralize policy profiles |
-| auth mismatch | 401/403 bursts | credential sprawl | rotation schedule + scope minimization |
-| schema breakage | parser/validation errors | unmanaged upstream changes | contract tests per release |
-| retry storms | queue congestion | no backoff controls | jittered backoff + circuit breakers |
-| silent regressions | quality drop without alerts | weak baseline metrics | eval harness with thresholds |
-
-### Implementation Runbook
-
-1. Establish a reproducible baseline environment.
-2. Capture chapter-specific success criteria before changes.
-3. Implement minimal viable path with explicit interfaces.
-4. Add observability before expanding feature scope.
-5. Run deterministic tests for happy-path behavior.
-6. Inject failure scenarios for negative-path validation.
-7. Compare output quality against baseline snapshots.
-8. Promote through staged environments with rollback gates.
-9. Record operational lessons in release notes.
-
-### Quality Gate Checklist
-
-- [ ] chapter-level assumptions are explicit and testable
-- [ ] API/tool boundaries are documented with input/output examples
-- [ ] failure handling includes retry, timeout, and fallback policy
-- [ ] security controls include auth scopes and secret rotation plans
-- [ ] observability includes logs, metrics, traces, and alert thresholds
-- [ ] deployment guidance includes canary and rollback paths
-- [ ] docs include links to upstream sources and related tracks
-- [ ] post-release verification confirms expected behavior under load
-
-### Source Alignment
-
-- [Langfuse Repository](https://github.com/langfuse/langfuse)
-- [Langfuse Releases](https://github.com/langfuse/langfuse/releases)
-- [Langfuse Docs](https://langfuse.com/docs)
-
-### Cross-Tutorial Connection Map
-
-- [LiteLLM Tutorial](../litellm-tutorial/)
-- [LangChain Tutorial](../langchain-tutorial/)
-- [LlamaIndex Tutorial](../llamaindex-tutorial/)
-- [Vercel AI SDK Tutorial](../vercel-ai-tutorial/)
-- [Chapter 1: Getting Started](01-getting-started.md)
-
-### Advanced Practice Exercises
-
-1. Build a minimal end-to-end implementation for `Chapter 2: Tracing Fundamentals`.
-2. Add instrumentation and measure baseline latency and error rate.
-3. Introduce one controlled failure and confirm graceful recovery.
-4. Add policy constraints and verify they are enforced consistently.
-5. Run a staged rollout and document rollback decision criteria.
-
-### Review Questions
-
-1. Which execution boundary matters most for this chapter and why?
-2. What signal detects regressions earliest in your environment?
-3. What tradeoff did you make between delivery speed and governance?
-4. How would you recover from the highest-impact failure mode?
-5. What must be automated before scaling to team-wide adoption?
-
-## What Problem Does This Solve?
-
-Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for `question`, `resp`, `observe` so behavior stays predictable as complexity grows.
-
-In practical terms, this chapter helps you avoid three common failures:
-
-- coupling core logic too tightly to one implementation path
-- missing the handoff boundaries between setup, execution, and validation
-- shipping changes without clear rollback or observability strategy
-
-After working through this chapter, you should be able to reason about `Chapter 2: Tracing Fundamentals` as an operating subsystem inside **Langfuse Tutorial: LLM Observability, Evaluation, and Prompt Operations**, with explicit contracts for inputs, state transitions, and outputs.
-
-Use the implementation notes around `trace`, `name`, `content` as your checklist when adapting these patterns to your own repository.
-
-## How it Works Under the Hood
-
-Under the hood, `Chapter 2: Tracing Fundamentals` usually follows a repeatable control path:
-
-1. **Context bootstrap**: initialize runtime config and prerequisites for `question`.
-2. **Input normalization**: shape incoming data so `resp` receives stable contracts.
-3. **Core execution**: run the main logic branch and propagate intermediate state through `observe`.
-4. **Policy and safety checks**: enforce limits, auth scopes, and failure boundaries.
-5. **Output composition**: return canonical result payloads for downstream consumers.
-6. **Operational telemetry**: emit logs/metrics needed for debugging and performance tuning.
-
-When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## Source Code Walkthrough
+
+### `package.json`
+
+The `package` module in [`package.json`](https://github.com/langfuse/langfuse/blob/HEAD/package.json) handles a key part of this chapter's functionality:
+
+```json
+{
+ "name": "langfuse",
+ "version": "3.163.0",
+ "author": "engineering@langfuse.com",
+ "license": "MIT",
+ "private": true,
+ "engines": {
+ "node": "24"
+ },
+ "scripts": {
+ "agents:check": "node scripts/agents/sync-agent-shims.mjs --check",
+ "agents:sync": "node scripts/agents/sync-agent-shims.mjs",
+ "postinstall": "node -e \"const fs = require('node:fs'); const cp = require('node:child_process'); if (!fs.existsSync('scripts/postinstall.sh')) { console.log('Skipping repo postinstall helper: scripts/postinstall.sh is not present in this install context.'); process.exit(0); } cp.execSync('bash scripts/postinstall.sh', { stdio: 'inherit' });\"",
+ "preinstall": "npx only-allow pnpm",
+ "infra:dev:up": "docker compose -f ./docker-compose.dev.yml up -d --wait",
+ "infra:dev:down": "docker compose -f ./docker-compose.dev.yml down",
+ "infra:dev:prune": "docker compose -f ./docker-compose.dev.yml down -v",
+ "db:generate": "turbo run db:generate",
+ "db:migrate": "turbo run db:migrate",
+ "db:seed": "turbo run db:seed",
+ "db:seed:examples": "turbo run db:seed:examples",
+ "nuke": "bash ./scripts/nuke.sh",
+ "dx": "pnpm i && pnpm run infra:dev:prune && pnpm run infra:dev:up --pull always && pnpm --filter=shared run db:reset:test && pnpm --filter=shared run db:reset && pnpm --filter=shared run ch:reset && pnpm --filter=shared run db:seed:examples && pnpm run dev",
+ "dx-f": "pnpm i && pnpm run infra:dev:prune && pnpm run infra:dev:up --pull always && pnpm --filter=shared run db:reset:test && pnpm --filter=shared run db:reset -f && SKIP_CONFIRM=1 pnpm --filter=shared run ch:reset && pnpm --filter=shared run db:seed:examples && pnpm run dev",
+ "dx:skip-infra": "pnpm i && pnpm --filter=shared run db:reset:test && pnpm --filter=shared run db:reset && pnpm --filter=shared run ch:reset && pnpm --filter=shared run db:seed:examples && pnpm run dev",
+ "build": "turbo run build",
+ "build:check": "turbo run build:check",
+ "typecheck": "turbo run typecheck",
+ "tc": "turbo run typecheck",
+ "start": "turbo run start",
+ "dev": "turbo run dev",
+ "dev:worker": "turbo run dev --filter=worker",
+ "dev:web": "turbo run dev --filter=web",
+ "dev:web-webpack": "turbo run dev --filter=web -- --webpack",
+ "lint": "turbo run lint",
+```
-## Source Walkthrough
+This module is important because it defines how Langfuse Tutorial: LLM Observability, Evaluation, and Prompt Operations implements the patterns covered in this chapter.
+
+### `docker-compose.dev-azure.yml`
+
+The `docker-compose.dev-azure` module in [`docker-compose.dev-azure.yml`](https://github.com/langfuse/langfuse/blob/HEAD/docker-compose.dev-azure.yml) handles a key part of this chapter's functionality:
+
+```yml
+services:
+ clickhouse:
+ image: docker.io/clickhouse/clickhouse-server:24.3
+ user: "101:101"
+ environment:
+ CLICKHOUSE_DB: default
+ CLICKHOUSE_USER: ${CLICKHOUSE_USER:-clickhouse}
+ CLICKHOUSE_PASSWORD: ${CLICKHOUSE_PASSWORD:-clickhouse}
+ volumes:
+ - langfuse_clickhouse_data:/var/lib/clickhouse
+ - langfuse_clickhouse_logs:/var/log/clickhouse-server
+ ports:
+ - "8123:8123"
+ - "9000:9000"
+ healthcheck:
+ test: wget --no-verbose --tries=1 --spider http://localhost:8123/ping || exit 1
+ interval: 5s
+ timeout: 5s
+ retries: 10
+ start_period: 1s
+ depends_on:
+ - postgres
+
+ azurite:
+ image: mcr.microsoft.com/azure-storage/azurite
+ command: azurite-blob --blobHost 0.0.0.0
+ ports:
+ - "10000:10000"
+ volumes:
+ - langfuse_azurite_data:/data
+
+ minio:
+ image: cgr.dev/chainguard/minio
+ container_name: ${MINIO_CONTAINER_NAME:-langfuse-minio}
+ entrypoint: sh
+```
-Use the following upstream sources to verify implementation details while reading this chapter:
+This module is important because it defines how Langfuse Tutorial: LLM Observability, Evaluation, and Prompt Operations implements the patterns covered in this chapter.
+
+### `docker-compose.yml`
+
+The `docker-compose` module in [`docker-compose.yml`](https://github.com/langfuse/langfuse/blob/HEAD/docker-compose.yml) handles a key part of this chapter's functionality:
+
+```yml
+# Make sure to update the credential placeholders with your own secrets.
+# We mark them with # CHANGEME in the file below.
+# In addition, we recommend to restrict inbound traffic on the host to langfuse-web (port 3000) and minio (port 9090) only.
+# All other components are bound to localhost (127.0.0.1) to only accept connections from the local machine.
+# External connections from other machines will not be able to reach these services directly.
+services:
+ langfuse-worker:
+ image: docker.io/langfuse/langfuse-worker:3
+ restart: always
+ depends_on: &langfuse-depends-on
+ postgres:
+ condition: service_healthy
+ minio:
+ condition: service_healthy
+ redis:
+ condition: service_healthy
+ clickhouse:
+ condition: service_healthy
+ ports:
+ - 127.0.0.1:3030:3030
+ environment: &langfuse-worker-env
+ NEXTAUTH_URL: ${NEXTAUTH_URL:-http://localhost:3000}
+ DATABASE_URL: ${DATABASE_URL:-postgresql://postgres:postgres@postgres:5432/postgres} # CHANGEME
+ SALT: ${SALT:-mysalt} # CHANGEME
+ ENCRYPTION_KEY: ${ENCRYPTION_KEY:-0000000000000000000000000000000000000000000000000000000000000000} # CHANGEME: generate via `openssl rand -hex 32`
+ TELEMETRY_ENABLED: ${TELEMETRY_ENABLED:-true}
+ LANGFUSE_ENABLE_EXPERIMENTAL_FEATURES: ${LANGFUSE_ENABLE_EXPERIMENTAL_FEATURES:-false}
+ CLICKHOUSE_MIGRATION_URL: ${CLICKHOUSE_MIGRATION_URL:-clickhouse://clickhouse:9000}
+ CLICKHOUSE_URL: ${CLICKHOUSE_URL:-http://clickhouse:8123}
+ CLICKHOUSE_USER: ${CLICKHOUSE_USER:-clickhouse}
+ CLICKHOUSE_PASSWORD: ${CLICKHOUSE_PASSWORD:-clickhouse} # CHANGEME
+ CLICKHOUSE_CLUSTER_ENABLED: ${CLICKHOUSE_CLUSTER_ENABLED:-false}
+ LANGFUSE_USE_AZURE_BLOB: ${LANGFUSE_USE_AZURE_BLOB:-false}
+ LANGFUSE_S3_EVENT_UPLOAD_BUCKET: ${LANGFUSE_S3_EVENT_UPLOAD_BUCKET:-langfuse}
+ LANGFUSE_S3_EVENT_UPLOAD_REGION: ${LANGFUSE_S3_EVENT_UPLOAD_REGION:-auto}
+```
-- [Langfuse Repository](https://github.com/langfuse/langfuse)
- Why it matters: authoritative reference on `Langfuse Repository` (github.com).
-- [Langfuse Releases](https://github.com/langfuse/langfuse/releases)
- Why it matters: authoritative reference on `Langfuse Releases` (github.com).
-- [Langfuse Docs](https://langfuse.com/docs)
- Why it matters: authoritative reference on `Langfuse Docs` (langfuse.com).
+This module is important because it defines how Langfuse Tutorial: LLM Observability, Evaluation, and Prompt Operations implements the patterns covered in this chapter.
-Suggested trace strategy:
-- search upstream code for `question` and `resp` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
-## Chapter Connections
+## How These Components Connect
-- [Tutorial Index](README.md)
-- [Previous Chapter: Chapter 1: Getting Started with Langfuse](01-getting-started.md)
-- [Next Chapter: Chapter 3: Prompt Management](03-prompts.md)
-- [Main Catalog](../../README.md#-tutorial-catalog)
-- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
+```mermaid
+flowchart TD
+ A[package]
+ B[docker-compose.dev-azure]
+ C[docker-compose]
+ A --> B
+ B --> C
+```
diff --git a/tutorials/langfuse-tutorial/03-prompts.md b/tutorials/langfuse-tutorial/03-prompts.md
index af782750..ad457400 100644
--- a/tutorials/langfuse-tutorial/03-prompts.md
+++ b/tutorials/langfuse-tutorial/03-prompts.md
@@ -6,6 +6,7 @@ has_children: false
parent: Langfuse Tutorial
---
+
# Chapter 3: Prompt Management
Welcome to **Chapter 3: Prompt Management**. In this part of **Langfuse Tutorial: LLM Observability, Evaluation, and Prompt Operations**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
@@ -469,173 +470,148 @@ These tips will help you get the most out of Langfuse prompt management:
## Depth Expansion Playbook
-<!-- depth-expansion-v2 -->
-
-This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
-
-### Strategic Context
-
-- tutorial: **Langfuse Tutorial: LLM Observability, Evaluation, and Prompt Operations**
-- tutorial slug: **langfuse-tutorial**
-- chapter focus: **Chapter 3: Prompt Management**
-- system context: **Langfuse Tutorial**
-- objective: move from surface-level usage to repeatable engineering operation
-
-### Architecture Decomposition
-
-1. Define the runtime boundary for `Chapter 3: Prompt Management`.
-2. Separate control-plane decisions from data-plane execution.
-3. Capture input contracts, transformation points, and output contracts.
-4. Trace state transitions across request lifecycle stages.
-5. Identify extension hooks and policy interception points.
-6. Map ownership boundaries for team and automation workflows.
-7. Specify rollback and recovery paths for unsafe changes.
-8. Track observability signals for correctness, latency, and cost.
-
-### Operator Decision Matrix
-
-| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
-|:--------------|:--------------|:------------------|:---------|
-| Runtime mode | managed defaults | explicit policy config | speed vs control |
-| State handling | local ephemeral | durable persisted state | simplicity vs auditability |
-| Tool integration | direct API use | mediated adapter layer | velocity vs governance |
-| Rollout method | manual change | staged + canary rollout | effort vs safety |
-| Incident response | best effort logs | runbooks + SLO alerts | cost vs reliability |
-
-### Failure Modes and Countermeasures
-
-| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
-|:-------------|:-------------|:-------------------|:---------------|
-| stale context | inconsistent outputs | missing refresh window | enforce context TTL and refresh hooks |
-| policy drift | unexpected execution | ad hoc overrides | centralize policy profiles |
-| auth mismatch | 401/403 bursts | credential sprawl | rotation schedule + scope minimization |
-| schema breakage | parser/validation errors | unmanaged upstream changes | contract tests per release |
-| retry storms | queue congestion | no backoff controls | jittered backoff + circuit breakers |
-| silent regressions | quality drop without alerts | weak baseline metrics | eval harness with thresholds |
-
-### Implementation Runbook
-
-1. Establish a reproducible baseline environment.
-2. Capture chapter-specific success criteria before changes.
-3. Implement minimal viable path with explicit interfaces.
-4. Add observability before expanding feature scope.
-5. Run deterministic tests for happy-path behavior.
-6. Inject failure scenarios for negative-path validation.
-7. Compare output quality against baseline snapshots.
-8. Promote through staged environments with rollback gates.
-9. Record operational lessons in release notes.
-
-### Quality Gate Checklist
-
-- [ ] chapter-level assumptions are explicit and testable
-- [ ] API/tool boundaries are documented with input/output examples
-- [ ] failure handling includes retry, timeout, and fallback policy
-- [ ] security controls include auth scopes and secret rotation plans
-- [ ] observability includes logs, metrics, traces, and alert thresholds
-- [ ] deployment guidance includes canary and rollback paths
-- [ ] docs include links to upstream sources and related tracks
-- [ ] post-release verification confirms expected behavior under load
-
-### Source Alignment
-
-- [Langfuse Repository](https://github.com/langfuse/langfuse)
-- [Langfuse Releases](https://github.com/langfuse/langfuse/releases)
-- [Langfuse Docs](https://langfuse.com/docs)
-
-### Cross-Tutorial Connection Map
-
-- [LiteLLM Tutorial](../litellm-tutorial/)
-- [LangChain Tutorial](../langchain-tutorial/)
-- [LlamaIndex Tutorial](../llamaindex-tutorial/)
-- [Vercel AI SDK Tutorial](../vercel-ai-tutorial/)
-- [Chapter 1: Getting Started](01-getting-started.md)
-
-### Advanced Practice Exercises
-
-1. Build a minimal end-to-end implementation for `Chapter 3: Prompt Management`.
-2. Add instrumentation and measure baseline latency and error rate.
-3. Introduce one controlled failure and confirm graceful recovery.
-4. Add policy constraints and verify they are enforced consistently.
-5. Run a staged rollout and document rollback decision criteria.
+## Source Code Walkthrough
-### Review Questions
+### `package.json`
-1. Which execution boundary matters most for this chapter and why?
-2. What signal detects regressions earliest in your environment?
-3. What tradeoff did you make between delivery speed and governance?
-4. How would you recover from the highest-impact failure mode?
-5. What must be automated before scaling to team-wide adoption?
+The `package` module in [`package.json`](https://github.com/langfuse/langfuse/blob/HEAD/package.json) handles a key part of this chapter's functionality:
-### Scenario Playbook 1: Chapter 3: Prompt Management
-
-- tutorial context: **Langfuse Tutorial: LLM Observability, Evaluation, and Prompt Operations**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 2: Chapter 3: Prompt Management
-
-- tutorial context: **Langfuse Tutorial: LLM Observability, Evaluation, and Prompt Operations**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-## What Problem Does This Solve?
-
-Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for `prompt`, `langfuse`, `label` so behavior stays predictable as complexity grows.
-
-In practical terms, this chapter helps you avoid three common failures:
-
-- coupling core logic too tightly to one implementation path
-- missing the handoff boundaries between setup, execution, and validation
-- shipping changes without clear rollback or observability strategy
-
-After working through this chapter, you should be able to reason about `Chapter 3: Prompt Management` as an operating subsystem inside **Langfuse Tutorial: LLM Observability, Evaluation, and Prompt Operations**, with explicit contracts for inputs, state transitions, and outputs.
-
-Use the implementation notes around `name`, `production`, `messages` as your checklist when adapting these patterns to your own repository.
-
-## How it Works Under the Hood
-
-Under the hood, `Chapter 3: Prompt Management` usually follows a repeatable control path:
-
-1. **Context bootstrap**: initialize runtime config and prerequisites for `prompt`.
-2. **Input normalization**: shape incoming data so `langfuse` receives stable contracts.
-3. **Core execution**: run the main logic branch and propagate intermediate state through `label`.
-4. **Policy and safety checks**: enforce limits, auth scopes, and failure boundaries.
-5. **Output composition**: return canonical result payloads for downstream consumers.
-6. **Operational telemetry**: emit logs/metrics needed for debugging and performance tuning.
-
-When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+```json
+{
+ "name": "langfuse",
+ "version": "3.163.0",
+ "author": "engineering@langfuse.com",
+ "license": "MIT",
+ "private": true,
+ "engines": {
+ "node": "24"
+ },
+ "scripts": {
+ "agents:check": "node scripts/agents/sync-agent-shims.mjs --check",
+ "agents:sync": "node scripts/agents/sync-agent-shims.mjs",
+ "postinstall": "node -e \"const fs = require('node:fs'); const cp = require('node:child_process'); if (!fs.existsSync('scripts/postinstall.sh')) { console.log('Skipping repo postinstall helper: scripts/postinstall.sh is not present in this install context.'); process.exit(0); } cp.execSync('bash scripts/postinstall.sh', { stdio: 'inherit' });\"",
+ "preinstall": "npx only-allow pnpm",
+ "infra:dev:up": "docker compose -f ./docker-compose.dev.yml up -d --wait",
+ "infra:dev:down": "docker compose -f ./docker-compose.dev.yml down",
+ "infra:dev:prune": "docker compose -f ./docker-compose.dev.yml down -v",
+ "db:generate": "turbo run db:generate",
+ "db:migrate": "turbo run db:migrate",
+ "db:seed": "turbo run db:seed",
+ "db:seed:examples": "turbo run db:seed:examples",
+ "nuke": "bash ./scripts/nuke.sh",
+ "dx": "pnpm i && pnpm run infra:dev:prune && pnpm run infra:dev:up --pull always && pnpm --filter=shared run db:reset:test && pnpm --filter=shared run db:reset && pnpm --filter=shared run ch:reset && pnpm --filter=shared run db:seed:examples && pnpm run dev",
+ "dx-f": "pnpm i && pnpm run infra:dev:prune && pnpm run infra:dev:up --pull always && pnpm --filter=shared run db:reset:test && pnpm --filter=shared run db:reset -f && SKIP_CONFIRM=1 pnpm --filter=shared run ch:reset && pnpm --filter=shared run db:seed:examples && pnpm run dev",
+ "dx:skip-infra": "pnpm i && pnpm --filter=shared run db:reset:test && pnpm --filter=shared run db:reset && pnpm --filter=shared run ch:reset && pnpm --filter=shared run db:seed:examples && pnpm run dev",
+ "build": "turbo run build",
+ "build:check": "turbo run build:check",
+ "typecheck": "turbo run typecheck",
+ "tc": "turbo run typecheck",
+ "start": "turbo run start",
+ "dev": "turbo run dev",
+ "dev:worker": "turbo run dev --filter=worker",
+ "dev:web": "turbo run dev --filter=web",
+ "dev:web-webpack": "turbo run dev --filter=web -- --webpack",
+ "lint": "turbo run lint",
+```
-## Source Walkthrough
+This module is important because it defines how Langfuse Tutorial: LLM Observability, Evaluation, and Prompt Operations implements the patterns covered in this chapter.
+
+### `docker-compose.dev-azure.yml`
+
+The `docker-compose.dev-azure` module in [`docker-compose.dev-azure.yml`](https://github.com/langfuse/langfuse/blob/HEAD/docker-compose.dev-azure.yml) handles a key part of this chapter's functionality:
+
+```yml
+services:
+ clickhouse:
+ image: docker.io/clickhouse/clickhouse-server:24.3
+ user: "101:101"
+ environment:
+ CLICKHOUSE_DB: default
+ CLICKHOUSE_USER: ${CLICKHOUSE_USER:-clickhouse}
+ CLICKHOUSE_PASSWORD: ${CLICKHOUSE_PASSWORD:-clickhouse}
+ volumes:
+ - langfuse_clickhouse_data:/var/lib/clickhouse
+ - langfuse_clickhouse_logs:/var/log/clickhouse-server
+ ports:
+ - "8123:8123"
+ - "9000:9000"
+ healthcheck:
+ test: wget --no-verbose --tries=1 --spider http://localhost:8123/ping || exit 1
+ interval: 5s
+ timeout: 5s
+ retries: 10
+ start_period: 1s
+ depends_on:
+ - postgres
+
+ azurite:
+ image: mcr.microsoft.com/azure-storage/azurite
+ command: azurite-blob --blobHost 0.0.0.0
+ ports:
+ - "10000:10000"
+ volumes:
+ - langfuse_azurite_data:/data
+
+ minio:
+ image: cgr.dev/chainguard/minio
+ container_name: ${MINIO_CONTAINER_NAME:-langfuse-minio}
+ entrypoint: sh
+```
-Use the following upstream sources to verify implementation details while reading this chapter:
+This module is important because it defines how Langfuse Tutorial: LLM Observability, Evaluation, and Prompt Operations implements the patterns covered in this chapter.
+
+### `docker-compose.yml`
+
+The `docker-compose` module in [`docker-compose.yml`](https://github.com/langfuse/langfuse/blob/HEAD/docker-compose.yml) handles a key part of this chapter's functionality:
+
+```yml
+# Make sure to update the credential placeholders with your own secrets.
+# We mark them with # CHANGEME in the file below.
+# In addition, we recommend to restrict inbound traffic on the host to langfuse-web (port 3000) and minio (port 9090) only.
+# All other components are bound to localhost (127.0.0.1) to only accept connections from the local machine.
+# External connections from other machines will not be able to reach these services directly.
+services:
+ langfuse-worker:
+ image: docker.io/langfuse/langfuse-worker:3
+ restart: always
+ depends_on: &langfuse-depends-on
+ postgres:
+ condition: service_healthy
+ minio:
+ condition: service_healthy
+ redis:
+ condition: service_healthy
+ clickhouse:
+ condition: service_healthy
+ ports:
+ - 127.0.0.1:3030:3030
+ environment: &langfuse-worker-env
+ NEXTAUTH_URL: ${NEXTAUTH_URL:-http://localhost:3000}
+ DATABASE_URL: ${DATABASE_URL:-postgresql://postgres:postgres@postgres:5432/postgres} # CHANGEME
+ SALT: ${SALT:-mysalt} # CHANGEME
+ ENCRYPTION_KEY: ${ENCRYPTION_KEY:-0000000000000000000000000000000000000000000000000000000000000000} # CHANGEME: generate via `openssl rand -hex 32`
+ TELEMETRY_ENABLED: ${TELEMETRY_ENABLED:-true}
+ LANGFUSE_ENABLE_EXPERIMENTAL_FEATURES: ${LANGFUSE_ENABLE_EXPERIMENTAL_FEATURES:-false}
+ CLICKHOUSE_MIGRATION_URL: ${CLICKHOUSE_MIGRATION_URL:-clickhouse://clickhouse:9000}
+ CLICKHOUSE_URL: ${CLICKHOUSE_URL:-http://clickhouse:8123}
+ CLICKHOUSE_USER: ${CLICKHOUSE_USER:-clickhouse}
+ CLICKHOUSE_PASSWORD: ${CLICKHOUSE_PASSWORD:-clickhouse} # CHANGEME
+ CLICKHOUSE_CLUSTER_ENABLED: ${CLICKHOUSE_CLUSTER_ENABLED:-false}
+ LANGFUSE_USE_AZURE_BLOB: ${LANGFUSE_USE_AZURE_BLOB:-false}
+ LANGFUSE_S3_EVENT_UPLOAD_BUCKET: ${LANGFUSE_S3_EVENT_UPLOAD_BUCKET:-langfuse}
+ LANGFUSE_S3_EVENT_UPLOAD_REGION: ${LANGFUSE_S3_EVENT_UPLOAD_REGION:-auto}
+```
-- [Langfuse Repository](https://github.com/langfuse/langfuse)
- Why it matters: authoritative reference on `Langfuse Repository` (github.com).
-- [Langfuse Releases](https://github.com/langfuse/langfuse/releases)
- Why it matters: authoritative reference on `Langfuse Releases` (github.com).
-- [Langfuse Docs](https://langfuse.com/docs)
- Why it matters: authoritative reference on `Langfuse Docs` (langfuse.com).
+This module is important because it defines how Langfuse Tutorial: LLM Observability, Evaluation, and Prompt Operations implements the patterns covered in this chapter.
-Suggested trace strategy:
-- search upstream code for `prompt` and `langfuse` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
-## Chapter Connections
+## How These Components Connect
-- [Tutorial Index](README.md)
-- [Previous Chapter: Chapter 2: Tracing Fundamentals](02-tracing.md)
-- [Next Chapter: Chapter 4: Evaluation](04-evaluation.md)
-- [Main Catalog](../../README.md#-tutorial-catalog)
-- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
+```mermaid
+flowchart TD
+ A[package]
+ B[docker-compose.dev-azure]
+ C[docker-compose]
+ A --> B
+ B --> C
+```
diff --git a/tutorials/langfuse-tutorial/05-analytics.md b/tutorials/langfuse-tutorial/05-analytics.md
index aef54858..9306ce37 100644
--- a/tutorials/langfuse-tutorial/05-analytics.md
+++ b/tutorials/langfuse-tutorial/05-analytics.md
@@ -6,6 +6,7 @@ has_children: false
parent: Langfuse Tutorial
---
+
# Chapter 5: Analytics & Metrics
Welcome to **Chapter 5: Analytics & Metrics**. In this part of **Langfuse Tutorial: LLM Observability, Evaluation, and Prompt Operations**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
@@ -524,149 +525,148 @@ Next: [Chapter 6: Datasets & Testing](06-datasets.md) -- create test datasets fr
## Depth Expansion Playbook
-<!-- depth-expansion-v2 -->
-
-This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
-
-### Strategic Context
-
-- tutorial: **Langfuse Tutorial: LLM Observability, Evaluation, and Prompt Operations**
-- tutorial slug: **langfuse-tutorial**
-- chapter focus: **Chapter 5: Analytics & Metrics**
-- system context: **Langfuse Tutorial**
-- objective: move from surface-level usage to repeatable engineering operation
-
-### Architecture Decomposition
-
-1. Define the runtime boundary for `Chapter 5: Analytics & Metrics`.
-2. Separate control-plane decisions from data-plane execution.
-3. Capture input contracts, transformation points, and output contracts.
-4. Trace state transitions across request lifecycle stages.
-5. Identify extension hooks and policy interception points.
-6. Map ownership boundaries for team and automation workflows.
-7. Specify rollback and recovery paths for unsafe changes.
-8. Track observability signals for correctness, latency, and cost.
-
-### Operator Decision Matrix
-
-| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
-|:--------------|:--------------|:------------------|:---------|
-| Runtime mode | managed defaults | explicit policy config | speed vs control |
-| State handling | local ephemeral | durable persisted state | simplicity vs auditability |
-| Tool integration | direct API use | mediated adapter layer | velocity vs governance |
-| Rollout method | manual change | staged + canary rollout | effort vs safety |
-| Incident response | best effort logs | runbooks + SLO alerts | cost vs reliability |
-
-### Failure Modes and Countermeasures
-
-| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
-|:-------------|:-------------|:-------------------|:---------------|
-| stale context | inconsistent outputs | missing refresh window | enforce context TTL and refresh hooks |
-| policy drift | unexpected execution | ad hoc overrides | centralize policy profiles |
-| auth mismatch | 401/403 bursts | credential sprawl | rotation schedule + scope minimization |
-| schema breakage | parser/validation errors | unmanaged upstream changes | contract tests per release |
-| retry storms | queue congestion | no backoff controls | jittered backoff + circuit breakers |
-| silent regressions | quality drop without alerts | weak baseline metrics | eval harness with thresholds |
-
-### Implementation Runbook
-
-1. Establish a reproducible baseline environment.
-2. Capture chapter-specific success criteria before changes.
-3. Implement minimal viable path with explicit interfaces.
-4. Add observability before expanding feature scope.
-5. Run deterministic tests for happy-path behavior.
-6. Inject failure scenarios for negative-path validation.
-7. Compare output quality against baseline snapshots.
-8. Promote through staged environments with rollback gates.
-9. Record operational lessons in release notes.
-
-### Quality Gate Checklist
-
-- [ ] chapter-level assumptions are explicit and testable
-- [ ] API/tool boundaries are documented with input/output examples
-- [ ] failure handling includes retry, timeout, and fallback policy
-- [ ] security controls include auth scopes and secret rotation plans
-- [ ] observability includes logs, metrics, traces, and alert thresholds
-- [ ] deployment guidance includes canary and rollback paths
-- [ ] docs include links to upstream sources and related tracks
-- [ ] post-release verification confirms expected behavior under load
-
-### Source Alignment
-
-- [Langfuse Repository](https://github.com/langfuse/langfuse)
-- [Langfuse Releases](https://github.com/langfuse/langfuse/releases)
-- [Langfuse Docs](https://langfuse.com/docs)
-
-### Cross-Tutorial Connection Map
-
-- [LiteLLM Tutorial](../litellm-tutorial/)
-- [LangChain Tutorial](../langchain-tutorial/)
-- [LlamaIndex Tutorial](../llamaindex-tutorial/)
-- [Vercel AI SDK Tutorial](../vercel-ai-tutorial/)
-- [Chapter 1: Getting Started](01-getting-started.md)
-
-### Advanced Practice Exercises
-
-1. Build a minimal end-to-end implementation for `Chapter 5: Analytics & Metrics`.
-2. Add instrumentation and measure baseline latency and error rate.
-3. Introduce one controlled failure and confirm graceful recovery.
-4. Add policy constraints and verify they are enforced consistently.
-5. Run a staged rollout and document rollback decision criteria.
-
-### Review Questions
-
-1. Which execution boundary matters most for this chapter and why?
-2. What signal detects regressions earliest in your environment?
-3. What tradeoff did you make between delivery speed and governance?
-4. How would you recover from the highest-impact failure mode?
-5. What must be automated before scaling to team-wide adoption?
-
-## What Problem Does This Solve?
-
-Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for `traces`, `trace`, `langfuse` so behavior stays predictable as complexity grows.
-
-In practical terms, this chapter helps you avoid three common failures:
-
-- coupling core logic too tightly to one implementation path
-- missing the handoff boundaries between setup, execution, and validation
-- shipping changes without clear rollback or observability strategy
-
-After working through this chapter, you should be able to reason about `Chapter 5: Analytics & Metrics` as an operating subsystem inside **Langfuse Tutorial: LLM Observability, Evaluation, and Prompt Operations**, with explicit contracts for inputs, state transitions, and outputs.
-
-Use the implementation notes around `total_cost`, `cost`, `print` as your checklist when adapting these patterns to your own repository.
-
-## How it Works Under the Hood
-
-Under the hood, `Chapter 5: Analytics & Metrics` usually follows a repeatable control path:
-
-1. **Context bootstrap**: initialize runtime config and prerequisites for `traces`.
-2. **Input normalization**: shape incoming data so `trace` receives stable contracts.
-3. **Core execution**: run the main logic branch and propagate intermediate state through `langfuse`.
-4. **Policy and safety checks**: enforce limits, auth scopes, and failure boundaries.
-5. **Output composition**: return canonical result payloads for downstream consumers.
-6. **Operational telemetry**: emit logs/metrics needed for debugging and performance tuning.
-
-When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## Source Code Walkthrough
+
+### `package.json`
+
+The `package` module in [`package.json`](https://github.com/langfuse/langfuse/blob/HEAD/package.json) handles a key part of this chapter's functionality:
+
+```json
+{
+ "name": "langfuse",
+ "version": "3.163.0",
+ "author": "engineering@langfuse.com",
+ "license": "MIT",
+ "private": true,
+ "engines": {
+ "node": "24"
+ },
+ "scripts": {
+ "agents:check": "node scripts/agents/sync-agent-shims.mjs --check",
+ "agents:sync": "node scripts/agents/sync-agent-shims.mjs",
+ "postinstall": "node -e \"const fs = require('node:fs'); const cp = require('node:child_process'); if (!fs.existsSync('scripts/postinstall.sh')) { console.log('Skipping repo postinstall helper: scripts/postinstall.sh is not present in this install context.'); process.exit(0); } cp.execSync('bash scripts/postinstall.sh', { stdio: 'inherit' });\"",
+ "preinstall": "npx only-allow pnpm",
+ "infra:dev:up": "docker compose -f ./docker-compose.dev.yml up -d --wait",
+ "infra:dev:down": "docker compose -f ./docker-compose.dev.yml down",
+ "infra:dev:prune": "docker compose -f ./docker-compose.dev.yml down -v",
+ "db:generate": "turbo run db:generate",
+ "db:migrate": "turbo run db:migrate",
+ "db:seed": "turbo run db:seed",
+ "db:seed:examples": "turbo run db:seed:examples",
+ "nuke": "bash ./scripts/nuke.sh",
+ "dx": "pnpm i && pnpm run infra:dev:prune && pnpm run infra:dev:up --pull always && pnpm --filter=shared run db:reset:test && pnpm --filter=shared run db:reset && pnpm --filter=shared run ch:reset && pnpm --filter=shared run db:seed:examples && pnpm run dev",
+ "dx-f": "pnpm i && pnpm run infra:dev:prune && pnpm run infra:dev:up --pull always && pnpm --filter=shared run db:reset:test && pnpm --filter=shared run db:reset -f && SKIP_CONFIRM=1 pnpm --filter=shared run ch:reset && pnpm --filter=shared run db:seed:examples && pnpm run dev",
+ "dx:skip-infra": "pnpm i && pnpm --filter=shared run db:reset:test && pnpm --filter=shared run db:reset && pnpm --filter=shared run ch:reset && pnpm --filter=shared run db:seed:examples && pnpm run dev",
+ "build": "turbo run build",
+ "build:check": "turbo run build:check",
+ "typecheck": "turbo run typecheck",
+ "tc": "turbo run typecheck",
+ "start": "turbo run start",
+ "dev": "turbo run dev",
+ "dev:worker": "turbo run dev --filter=worker",
+ "dev:web": "turbo run dev --filter=web",
+ "dev:web-webpack": "turbo run dev --filter=web -- --webpack",
+ "lint": "turbo run lint",
+```
-## Source Walkthrough
+This module is important because it defines how Langfuse Tutorial: LLM Observability, Evaluation, and Prompt Operations implements the patterns covered in this chapter.
+
+### `docker-compose.dev-azure.yml`
+
+The `docker-compose.dev-azure` module in [`docker-compose.dev-azure.yml`](https://github.com/langfuse/langfuse/blob/HEAD/docker-compose.dev-azure.yml) handles a key part of this chapter's functionality:
+
+```yml
+services:
+ clickhouse:
+ image: docker.io/clickhouse/clickhouse-server:24.3
+ user: "101:101"
+ environment:
+ CLICKHOUSE_DB: default
+ CLICKHOUSE_USER: ${CLICKHOUSE_USER:-clickhouse}
+ CLICKHOUSE_PASSWORD: ${CLICKHOUSE_PASSWORD:-clickhouse}
+ volumes:
+ - langfuse_clickhouse_data:/var/lib/clickhouse
+ - langfuse_clickhouse_logs:/var/log/clickhouse-server
+ ports:
+ - "8123:8123"
+ - "9000:9000"
+ healthcheck:
+ test: wget --no-verbose --tries=1 --spider http://localhost:8123/ping || exit 1
+ interval: 5s
+ timeout: 5s
+ retries: 10
+ start_period: 1s
+ depends_on:
+ - postgres
+
+ azurite:
+ image: mcr.microsoft.com/azure-storage/azurite
+ command: azurite-blob --blobHost 0.0.0.0
+ ports:
+ - "10000:10000"
+ volumes:
+ - langfuse_azurite_data:/data
+
+ minio:
+ image: cgr.dev/chainguard/minio
+ container_name: ${MINIO_CONTAINER_NAME:-langfuse-minio}
+ entrypoint: sh
+```
-Use the following upstream sources to verify implementation details while reading this chapter:
+This module is important because it defines how Langfuse Tutorial: LLM Observability, Evaluation, and Prompt Operations implements the patterns covered in this chapter.
+
+### `docker-compose.yml`
+
+The `docker-compose` module in [`docker-compose.yml`](https://github.com/langfuse/langfuse/blob/HEAD/docker-compose.yml) handles a key part of this chapter's functionality:
+
+```yml
+# Make sure to update the credential placeholders with your own secrets.
+# We mark them with # CHANGEME in the file below.
+# In addition, we recommend to restrict inbound traffic on the host to langfuse-web (port 3000) and minio (port 9090) only.
+# All other components are bound to localhost (127.0.0.1) to only accept connections from the local machine.
+# External connections from other machines will not be able to reach these services directly.
+services:
+ langfuse-worker:
+ image: docker.io/langfuse/langfuse-worker:3
+ restart: always
+ depends_on: &langfuse-depends-on
+ postgres:
+ condition: service_healthy
+ minio:
+ condition: service_healthy
+ redis:
+ condition: service_healthy
+ clickhouse:
+ condition: service_healthy
+ ports:
+ - 127.0.0.1:3030:3030
+ environment: &langfuse-worker-env
+ NEXTAUTH_URL: ${NEXTAUTH_URL:-http://localhost:3000}
+ DATABASE_URL: ${DATABASE_URL:-postgresql://postgres:postgres@postgres:5432/postgres} # CHANGEME
+ SALT: ${SALT:-mysalt} # CHANGEME
+ ENCRYPTION_KEY: ${ENCRYPTION_KEY:-0000000000000000000000000000000000000000000000000000000000000000} # CHANGEME: generate via `openssl rand -hex 32`
+ TELEMETRY_ENABLED: ${TELEMETRY_ENABLED:-true}
+ LANGFUSE_ENABLE_EXPERIMENTAL_FEATURES: ${LANGFUSE_ENABLE_EXPERIMENTAL_FEATURES:-false}
+ CLICKHOUSE_MIGRATION_URL: ${CLICKHOUSE_MIGRATION_URL:-clickhouse://clickhouse:9000}
+ CLICKHOUSE_URL: ${CLICKHOUSE_URL:-http://clickhouse:8123}
+ CLICKHOUSE_USER: ${CLICKHOUSE_USER:-clickhouse}
+ CLICKHOUSE_PASSWORD: ${CLICKHOUSE_PASSWORD:-clickhouse} # CHANGEME
+ CLICKHOUSE_CLUSTER_ENABLED: ${CLICKHOUSE_CLUSTER_ENABLED:-false}
+ LANGFUSE_USE_AZURE_BLOB: ${LANGFUSE_USE_AZURE_BLOB:-false}
+ LANGFUSE_S3_EVENT_UPLOAD_BUCKET: ${LANGFUSE_S3_EVENT_UPLOAD_BUCKET:-langfuse}
+ LANGFUSE_S3_EVENT_UPLOAD_REGION: ${LANGFUSE_S3_EVENT_UPLOAD_REGION:-auto}
+```
-- [Langfuse Repository](https://github.com/langfuse/langfuse)
- Why it matters: authoritative reference on `Langfuse Repository` (github.com).
-- [Langfuse Releases](https://github.com/langfuse/langfuse/releases)
- Why it matters: authoritative reference on `Langfuse Releases` (github.com).
-- [Langfuse Docs](https://langfuse.com/docs)
- Why it matters: authoritative reference on `Langfuse Docs` (langfuse.com).
+This module is important because it defines how Langfuse Tutorial: LLM Observability, Evaluation, and Prompt Operations implements the patterns covered in this chapter.
-Suggested trace strategy:
-- search upstream code for `traces` and `trace` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
-## Chapter Connections
+## How These Components Connect
-- [Tutorial Index](README.md)
-- [Previous Chapter: Chapter 4: Evaluation](04-evaluation.md)
-- [Next Chapter: Chapter 6: Datasets & Testing](06-datasets.md)
-- [Main Catalog](../../README.md#-tutorial-catalog)
-- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
+```mermaid
+flowchart TD
+ A[package]
+ B[docker-compose.dev-azure]
+ C[docker-compose]
+ A --> B
+ B --> C
+```
diff --git a/tutorials/langfuse-tutorial/06-datasets.md b/tutorials/langfuse-tutorial/06-datasets.md
index 1af856f0..4c97f402 100644
--- a/tutorials/langfuse-tutorial/06-datasets.md
+++ b/tutorials/langfuse-tutorial/06-datasets.md
@@ -6,6 +6,7 @@ has_children: false
parent: Langfuse Tutorial
---
+
# Chapter 6: Datasets & Testing
Welcome to **Chapter 6: Datasets & Testing**. In this part of **Langfuse Tutorial: LLM Observability, Evaluation, and Prompt Operations**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
@@ -515,149 +516,148 @@ Next: [Chapter 7: Integrations](07-integrations.md) -- connect Langfuse with Lan
## Depth Expansion Playbook
-<!-- depth-expansion-v2 -->
-
-This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
-
-### Strategic Context
-
-- tutorial: **Langfuse Tutorial: LLM Observability, Evaluation, and Prompt Operations**
-- tutorial slug: **langfuse-tutorial**
-- chapter focus: **Chapter 6: Datasets & Testing**
-- system context: **Langfuse Tutorial**
-- objective: move from surface-level usage to repeatable engineering operation
-
-### Architecture Decomposition
-
-1. Define the runtime boundary for `Chapter 6: Datasets & Testing`.
-2. Separate control-plane decisions from data-plane execution.
-3. Capture input contracts, transformation points, and output contracts.
-4. Trace state transitions across request lifecycle stages.
-5. Identify extension hooks and policy interception points.
-6. Map ownership boundaries for team and automation workflows.
-7. Specify rollback and recovery paths for unsafe changes.
-8. Track observability signals for correctness, latency, and cost.
-
-### Operator Decision Matrix
-
-| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
-|:--------------|:--------------|:------------------|:---------|
-| Runtime mode | managed defaults | explicit policy config | speed vs control |
-| State handling | local ephemeral | durable persisted state | simplicity vs auditability |
-| Tool integration | direct API use | mediated adapter layer | velocity vs governance |
-| Rollout method | manual change | staged + canary rollout | effort vs safety |
-| Incident response | best effort logs | runbooks + SLO alerts | cost vs reliability |
-
-### Failure Modes and Countermeasures
-
-| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
-|:-------------|:-------------|:-------------------|:---------------|
-| stale context | inconsistent outputs | missing refresh window | enforce context TTL and refresh hooks |
-| policy drift | unexpected execution | ad hoc overrides | centralize policy profiles |
-| auth mismatch | 401/403 bursts | credential sprawl | rotation schedule + scope minimization |
-| schema breakage | parser/validation errors | unmanaged upstream changes | contract tests per release |
-| retry storms | queue congestion | no backoff controls | jittered backoff + circuit breakers |
-| silent regressions | quality drop without alerts | weak baseline metrics | eval harness with thresholds |
-
-### Implementation Runbook
-
-1. Establish a reproducible baseline environment.
-2. Capture chapter-specific success criteria before changes.
-3. Implement minimal viable path with explicit interfaces.
-4. Add observability before expanding feature scope.
-5. Run deterministic tests for happy-path behavior.
-6. Inject failure scenarios for negative-path validation.
-7. Compare output quality against baseline snapshots.
-8. Promote through staged environments with rollback gates.
-9. Record operational lessons in release notes.
-
-### Quality Gate Checklist
-
-- [ ] chapter-level assumptions are explicit and testable
-- [ ] API/tool boundaries are documented with input/output examples
-- [ ] failure handling includes retry, timeout, and fallback policy
-- [ ] security controls include auth scopes and secret rotation plans
-- [ ] observability includes logs, metrics, traces, and alert thresholds
-- [ ] deployment guidance includes canary and rollback paths
-- [ ] docs include links to upstream sources and related tracks
-- [ ] post-release verification confirms expected behavior under load
-
-### Source Alignment
-
-- [Langfuse Repository](https://github.com/langfuse/langfuse)
-- [Langfuse Releases](https://github.com/langfuse/langfuse/releases)
-- [Langfuse Docs](https://langfuse.com/docs)
-
-### Cross-Tutorial Connection Map
+## Source Code Walkthrough
-- [LiteLLM Tutorial](../litellm-tutorial/)
-- [LangChain Tutorial](../langchain-tutorial/)
-- [LlamaIndex Tutorial](../llamaindex-tutorial/)
-- [Vercel AI SDK Tutorial](../vercel-ai-tutorial/)
-- [Chapter 1: Getting Started](01-getting-started.md)
+### `package.json`
-### Advanced Practice Exercises
+The `package` module in [`package.json`](https://github.com/langfuse/langfuse/blob/HEAD/package.json) handles a key part of this chapter's functionality:
-1. Build a minimal end-to-end implementation for `Chapter 6: Datasets & Testing`.
-2. Add instrumentation and measure baseline latency and error rate.
-3. Introduce one controlled failure and confirm graceful recovery.
-4. Add policy constraints and verify they are enforced consistently.
-5. Run a staged rollout and document rollback decision criteria.
-
-### Review Questions
-
-1. Which execution boundary matters most for this chapter and why?
-2. What signal detects regressions earliest in your environment?
-3. What tradeoff did you make between delivery speed and governance?
-4. How would you recover from the highest-impact failure mode?
-5. What must be automated before scaling to team-wide adoption?
-
-## What Problem Does This Solve?
-
-Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for `scores`, `langfuse`, `results` so behavior stays predictable as complexity grows.
-
-In practical terms, this chapter helps you avoid three common failures:
-
-- coupling core logic too tightly to one implementation path
-- missing the handoff boundaries between setup, execution, and validation
-- shipping changes without clear rollback or observability strategy
-
-After working through this chapter, you should be able to reason about `Chapter 6: Datasets & Testing` as an operating subsystem inside **Langfuse Tutorial: LLM Observability, Evaluation, and Prompt Operations**, with explicit contracts for inputs, state transitions, and outputs.
-
-Use the implementation notes around `item`, `dataset`, `trace` as your checklist when adapting these patterns to your own repository.
-
-## How it Works Under the Hood
-
-Under the hood, `Chapter 6: Datasets & Testing` usually follows a repeatable control path:
-
-1. **Context bootstrap**: initialize runtime config and prerequisites for `scores`.
-2. **Input normalization**: shape incoming data so `langfuse` receives stable contracts.
-3. **Core execution**: run the main logic branch and propagate intermediate state through `results`.
-4. **Policy and safety checks**: enforce limits, auth scopes, and failure boundaries.
-5. **Output composition**: return canonical result payloads for downstream consumers.
-6. **Operational telemetry**: emit logs/metrics needed for debugging and performance tuning.
-
-When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+```json
+{
+ "name": "langfuse",
+ "version": "3.163.0",
+ "author": "engineering@langfuse.com",
+ "license": "MIT",
+ "private": true,
+ "engines": {
+ "node": "24"
+ },
+ "scripts": {
+ "agents:check": "node scripts/agents/sync-agent-shims.mjs --check",
+ "agents:sync": "node scripts/agents/sync-agent-shims.mjs",
+ "postinstall": "node -e \"const fs = require('node:fs'); const cp = require('node:child_process'); if (!fs.existsSync('scripts/postinstall.sh')) { console.log('Skipping repo postinstall helper: scripts/postinstall.sh is not present in this install context.'); process.exit(0); } cp.execSync('bash scripts/postinstall.sh', { stdio: 'inherit' });\"",
+ "preinstall": "npx only-allow pnpm",
+ "infra:dev:up": "docker compose -f ./docker-compose.dev.yml up -d --wait",
+ "infra:dev:down": "docker compose -f ./docker-compose.dev.yml down",
+ "infra:dev:prune": "docker compose -f ./docker-compose.dev.yml down -v",
+ "db:generate": "turbo run db:generate",
+ "db:migrate": "turbo run db:migrate",
+ "db:seed": "turbo run db:seed",
+ "db:seed:examples": "turbo run db:seed:examples",
+ "nuke": "bash ./scripts/nuke.sh",
+ "dx": "pnpm i && pnpm run infra:dev:prune && pnpm run infra:dev:up --pull always && pnpm --filter=shared run db:reset:test && pnpm --filter=shared run db:reset && pnpm --filter=shared run ch:reset && pnpm --filter=shared run db:seed:examples && pnpm run dev",
+ "dx-f": "pnpm i && pnpm run infra:dev:prune && pnpm run infra:dev:up --pull always && pnpm --filter=shared run db:reset:test && pnpm --filter=shared run db:reset -f && SKIP_CONFIRM=1 pnpm --filter=shared run ch:reset && pnpm --filter=shared run db:seed:examples && pnpm run dev",
+ "dx:skip-infra": "pnpm i && pnpm --filter=shared run db:reset:test && pnpm --filter=shared run db:reset && pnpm --filter=shared run ch:reset && pnpm --filter=shared run db:seed:examples && pnpm run dev",
+ "build": "turbo run build",
+ "build:check": "turbo run build:check",
+ "typecheck": "turbo run typecheck",
+ "tc": "turbo run typecheck",
+ "start": "turbo run start",
+ "dev": "turbo run dev",
+ "dev:worker": "turbo run dev --filter=worker",
+ "dev:web": "turbo run dev --filter=web",
+ "dev:web-webpack": "turbo run dev --filter=web -- --webpack",
+ "lint": "turbo run lint",
+```
-## Source Walkthrough
+This module is important because it defines how Langfuse Tutorial: LLM Observability, Evaluation, and Prompt Operations implements the patterns covered in this chapter.
+
+### `docker-compose.dev-azure.yml`
+
+The `docker-compose.dev-azure` module in [`docker-compose.dev-azure.yml`](https://github.com/langfuse/langfuse/blob/HEAD/docker-compose.dev-azure.yml) handles a key part of this chapter's functionality:
+
+```yml
+services:
+ clickhouse:
+ image: docker.io/clickhouse/clickhouse-server:24.3
+ user: "101:101"
+ environment:
+ CLICKHOUSE_DB: default
+ CLICKHOUSE_USER: ${CLICKHOUSE_USER:-clickhouse}
+ CLICKHOUSE_PASSWORD: ${CLICKHOUSE_PASSWORD:-clickhouse}
+ volumes:
+ - langfuse_clickhouse_data:/var/lib/clickhouse
+ - langfuse_clickhouse_logs:/var/log/clickhouse-server
+ ports:
+ - "8123:8123"
+ - "9000:9000"
+ healthcheck:
+ test: wget --no-verbose --tries=1 --spider http://localhost:8123/ping || exit 1
+ interval: 5s
+ timeout: 5s
+ retries: 10
+ start_period: 1s
+ depends_on:
+ - postgres
+
+ azurite:
+ image: mcr.microsoft.com/azure-storage/azurite
+ command: azurite-blob --blobHost 0.0.0.0
+ ports:
+ - "10000:10000"
+ volumes:
+ - langfuse_azurite_data:/data
+
+ minio:
+ image: cgr.dev/chainguard/minio
+ container_name: ${MINIO_CONTAINER_NAME:-langfuse-minio}
+ entrypoint: sh
+```
-Use the following upstream sources to verify implementation details while reading this chapter:
+This module is important because it defines how Langfuse Tutorial: LLM Observability, Evaluation, and Prompt Operations implements the patterns covered in this chapter.
+
+### `docker-compose.yml`
+
+The `docker-compose` module in [`docker-compose.yml`](https://github.com/langfuse/langfuse/blob/HEAD/docker-compose.yml) handles a key part of this chapter's functionality:
+
+```yml
+# Make sure to update the credential placeholders with your own secrets.
+# We mark them with # CHANGEME in the file below.
+# In addition, we recommend to restrict inbound traffic on the host to langfuse-web (port 3000) and minio (port 9090) only.
+# All other components are bound to localhost (127.0.0.1) to only accept connections from the local machine.
+# External connections from other machines will not be able to reach these services directly.
+services:
+ langfuse-worker:
+ image: docker.io/langfuse/langfuse-worker:3
+ restart: always
+ depends_on: &langfuse-depends-on
+ postgres:
+ condition: service_healthy
+ minio:
+ condition: service_healthy
+ redis:
+ condition: service_healthy
+ clickhouse:
+ condition: service_healthy
+ ports:
+ - 127.0.0.1:3030:3030
+ environment: &langfuse-worker-env
+ NEXTAUTH_URL: ${NEXTAUTH_URL:-http://localhost:3000}
+ DATABASE_URL: ${DATABASE_URL:-postgresql://postgres:postgres@postgres:5432/postgres} # CHANGEME
+ SALT: ${SALT:-mysalt} # CHANGEME
+ ENCRYPTION_KEY: ${ENCRYPTION_KEY:-0000000000000000000000000000000000000000000000000000000000000000} # CHANGEME: generate via `openssl rand -hex 32`
+ TELEMETRY_ENABLED: ${TELEMETRY_ENABLED:-true}
+ LANGFUSE_ENABLE_EXPERIMENTAL_FEATURES: ${LANGFUSE_ENABLE_EXPERIMENTAL_FEATURES:-false}
+ CLICKHOUSE_MIGRATION_URL: ${CLICKHOUSE_MIGRATION_URL:-clickhouse://clickhouse:9000}
+ CLICKHOUSE_URL: ${CLICKHOUSE_URL:-http://clickhouse:8123}
+ CLICKHOUSE_USER: ${CLICKHOUSE_USER:-clickhouse}
+ CLICKHOUSE_PASSWORD: ${CLICKHOUSE_PASSWORD:-clickhouse} # CHANGEME
+ CLICKHOUSE_CLUSTER_ENABLED: ${CLICKHOUSE_CLUSTER_ENABLED:-false}
+ LANGFUSE_USE_AZURE_BLOB: ${LANGFUSE_USE_AZURE_BLOB:-false}
+ LANGFUSE_S3_EVENT_UPLOAD_BUCKET: ${LANGFUSE_S3_EVENT_UPLOAD_BUCKET:-langfuse}
+ LANGFUSE_S3_EVENT_UPLOAD_REGION: ${LANGFUSE_S3_EVENT_UPLOAD_REGION:-auto}
+```
-- [Langfuse Repository](https://github.com/langfuse/langfuse)
- Why it matters: authoritative reference on `Langfuse Repository` (github.com).
-- [Langfuse Releases](https://github.com/langfuse/langfuse/releases)
- Why it matters: authoritative reference on `Langfuse Releases` (github.com).
-- [Langfuse Docs](https://langfuse.com/docs)
- Why it matters: authoritative reference on `Langfuse Docs` (langfuse.com).
+This module is important because it defines how Langfuse Tutorial: LLM Observability, Evaluation, and Prompt Operations implements the patterns covered in this chapter.
-Suggested trace strategy:
-- search upstream code for `scores` and `langfuse` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
-## Chapter Connections
+## How These Components Connect
-- [Tutorial Index](README.md)
-- [Previous Chapter: Chapter 5: Analytics & Metrics](05-analytics.md)
-- [Next Chapter: Chapter 7: Integrations](07-integrations.md)
-- [Main Catalog](../../README.md#-tutorial-catalog)
-- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
+```mermaid
+flowchart TD
+ A[package]
+ B[docker-compose.dev-azure]
+ C[docker-compose]
+ A --> B
+ B --> C
+```
diff --git a/tutorials/langfuse-tutorial/08-production.md b/tutorials/langfuse-tutorial/08-production.md
index 3c6a4991..b1739c1a 100644
--- a/tutorials/langfuse-tutorial/08-production.md
+++ b/tutorials/langfuse-tutorial/08-production.md
@@ -6,6 +6,7 @@ has_children: false
parent: Langfuse Tutorial
---
+
# Chapter 8: Production Deployment
Welcome to **Chapter 8: Production Deployment**. In this part of **Langfuse Tutorial: LLM Observability, Evaluation, and Prompt Operations**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
@@ -417,220 +418,148 @@ With these tools and practices in place, you are well-equipped to build, monitor
## Depth Expansion Playbook
-<!-- depth-expansion-v2 -->
-
-This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
-
-### Strategic Context
-
-- tutorial: **Langfuse Tutorial: LLM Observability, Evaluation, and Prompt Operations**
-- tutorial slug: **langfuse-tutorial**
-- chapter focus: **Chapter 8: Production Deployment**
-- system context: **Langfuse Tutorial**
-- objective: move from surface-level usage to repeatable engineering operation
-
-### Architecture Decomposition
-
-1. Define the runtime boundary for `Chapter 8: Production Deployment`.
-2. Separate control-plane decisions from data-plane execution.
-3. Capture input contracts, transformation points, and output contracts.
-4. Trace state transitions across request lifecycle stages.
-5. Identify extension hooks and policy interception points.
-6. Map ownership boundaries for team and automation workflows.
-7. Specify rollback and recovery paths for unsafe changes.
-8. Track observability signals for correctness, latency, and cost.
-
-### Operator Decision Matrix
-
-| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
-|:--------------|:--------------|:------------------|:---------|
-| Runtime mode | managed defaults | explicit policy config | speed vs control |
-| State handling | local ephemeral | durable persisted state | simplicity vs auditability |
-| Tool integration | direct API use | mediated adapter layer | velocity vs governance |
-| Rollout method | manual change | staged + canary rollout | effort vs safety |
-| Incident response | best effort logs | runbooks + SLO alerts | cost vs reliability |
-
-### Failure Modes and Countermeasures
-
-| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
-|:-------------|:-------------|:-------------------|:---------------|
-| stale context | inconsistent outputs | missing refresh window | enforce context TTL and refresh hooks |
-| policy drift | unexpected execution | ad hoc overrides | centralize policy profiles |
-| auth mismatch | 401/403 bursts | credential sprawl | rotation schedule + scope minimization |
-| schema breakage | parser/validation errors | unmanaged upstream changes | contract tests per release |
-| retry storms | queue congestion | no backoff controls | jittered backoff + circuit breakers |
-| silent regressions | quality drop without alerts | weak baseline metrics | eval harness with thresholds |
-
-### Implementation Runbook
-
-1. Establish a reproducible baseline environment.
-2. Capture chapter-specific success criteria before changes.
-3. Implement minimal viable path with explicit interfaces.
-4. Add observability before expanding feature scope.
-5. Run deterministic tests for happy-path behavior.
-6. Inject failure scenarios for negative-path validation.
-7. Compare output quality against baseline snapshots.
-8. Promote through staged environments with rollback gates.
-9. Record operational lessons in release notes.
-
-### Quality Gate Checklist
-
-- [ ] chapter-level assumptions are explicit and testable
-- [ ] API/tool boundaries are documented with input/output examples
-- [ ] failure handling includes retry, timeout, and fallback policy
-- [ ] security controls include auth scopes and secret rotation plans
-- [ ] observability includes logs, metrics, traces, and alert thresholds
-- [ ] deployment guidance includes canary and rollback paths
-- [ ] docs include links to upstream sources and related tracks
-- [ ] post-release verification confirms expected behavior under load
-
-### Source Alignment
-
-- [Langfuse Repository](https://github.com/langfuse/langfuse)
-- [Langfuse Releases](https://github.com/langfuse/langfuse/releases)
-- [Langfuse Docs](https://langfuse.com/docs)
-
-### Cross-Tutorial Connection Map
-
-- [LiteLLM Tutorial](../litellm-tutorial/)
-- [LangChain Tutorial](../langchain-tutorial/)
-- [LlamaIndex Tutorial](../llamaindex-tutorial/)
-- [Vercel AI SDK Tutorial](../vercel-ai-tutorial/)
-- [Chapter 1: Getting Started](01-getting-started.md)
-
-### Advanced Practice Exercises
-
-1. Build a minimal end-to-end implementation for `Chapter 8: Production Deployment`.
-2. Add instrumentation and measure baseline latency and error rate.
-3. Introduce one controlled failure and confirm graceful recovery.
-4. Add policy constraints and verify they are enforced consistently.
-5. Run a staged rollout and document rollback decision criteria.
-
-### Review Questions
-
-1. Which execution boundary matters most for this chapter and why?
-2. What signal detects regressions earliest in your environment?
-3. What tradeoff did you make between delivery speed and governance?
-4. How would you recover from the highest-impact failure mode?
-5. What must be automated before scaling to team-wide adoption?
-
-### Scenario Playbook 1: Chapter 8: Production Deployment
-
-- tutorial context: **Langfuse Tutorial: LLM Observability, Evaluation, and Prompt Operations**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 2: Chapter 8: Production Deployment
-
-- tutorial context: **Langfuse Tutorial: LLM Observability, Evaluation, and Prompt Operations**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 3: Chapter 8: Production Deployment
-
-- tutorial context: **Langfuse Tutorial: LLM Observability, Evaluation, and Prompt Operations**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 4: Chapter 8: Production Deployment
-
-- tutorial context: **Langfuse Tutorial: LLM Observability, Evaluation, and Prompt Operations**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 5: Chapter 8: Production Deployment
-
-- tutorial context: **Langfuse Tutorial: LLM Observability, Evaluation, and Prompt Operations**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 6: Chapter 8: Production Deployment
-
-- tutorial context: **Langfuse Tutorial: LLM Observability, Evaluation, and Prompt Operations**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-## What Problem Does This Solve?
-
-Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for `langfuse`, `redis`, `name` so behavior stays predictable as complexity grows.
-
-In practical terms, this chapter helps you avoid three common failures:
-
-- coupling core logic too tightly to one implementation path
-- missing the handoff boundaries between setup, execution, and validation
-- shipping changes without clear rollback or observability strategy
-
-After working through this chapter, you should be able to reason about `Chapter 8: Production Deployment` as an operating subsystem inside **Langfuse Tutorial: LLM Observability, Evaluation, and Prompt Operations**, with explicit contracts for inputs, state transitions, and outputs.
-
-Use the implementation notes around `subgraph`, `image`, `spec` as your checklist when adapting these patterns to your own repository.
-
-## How it Works Under the Hood
-
-Under the hood, `Chapter 8: Production Deployment` usually follows a repeatable control path:
-
-1. **Context bootstrap**: initialize runtime config and prerequisites for `langfuse`.
-2. **Input normalization**: shape incoming data so `redis` receives stable contracts.
-3. **Core execution**: run the main logic branch and propagate intermediate state through `name`.
-4. **Policy and safety checks**: enforce limits, auth scopes, and failure boundaries.
-5. **Output composition**: return canonical result payloads for downstream consumers.
-6. **Operational telemetry**: emit logs/metrics needed for debugging and performance tuning.
-
-When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
-
-## Source Walkthrough
-
-Use the following upstream sources to verify implementation details while reading this chapter:
-
-- [Langfuse Repository](https://github.com/langfuse/langfuse)
- Why it matters: authoritative reference on `Langfuse Repository` (github.com).
-- [Langfuse Releases](https://github.com/langfuse/langfuse/releases)
- Why it matters: authoritative reference on `Langfuse Releases` (github.com).
-- [Langfuse Docs](https://langfuse.com/docs)
- Why it matters: authoritative reference on `Langfuse Docs` (langfuse.com).
-
-Suggested trace strategy:
-- search upstream code for `langfuse` and `redis` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
-
-## Chapter Connections
-
-- [Tutorial Index](README.md)
-- [Previous Chapter: Chapter 7: Integrations](07-integrations.md)
-- [Main Catalog](../../README.md#-tutorial-catalog)
-- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
+## Source Code Walkthrough
+
+### `package.json`
+
+The `package` module in [`package.json`](https://github.com/langfuse/langfuse/blob/HEAD/package.json) handles a key part of this chapter's functionality:
+
+```json
+{
+ "name": "langfuse",
+ "version": "3.163.0",
+ "author": "engineering@langfuse.com",
+ "license": "MIT",
+ "private": true,
+ "engines": {
+ "node": "24"
+ },
+ "scripts": {
+ "agents:check": "node scripts/agents/sync-agent-shims.mjs --check",
+ "agents:sync": "node scripts/agents/sync-agent-shims.mjs",
+ "postinstall": "node -e \"const fs = require('node:fs'); const cp = require('node:child_process'); if (!fs.existsSync('scripts/postinstall.sh')) { console.log('Skipping repo postinstall helper: scripts/postinstall.sh is not present in this install context.'); process.exit(0); } cp.execSync('bash scripts/postinstall.sh', { stdio: 'inherit' });\"",
+ "preinstall": "npx only-allow pnpm",
+ "infra:dev:up": "docker compose -f ./docker-compose.dev.yml up -d --wait",
+ "infra:dev:down": "docker compose -f ./docker-compose.dev.yml down",
+ "infra:dev:prune": "docker compose -f ./docker-compose.dev.yml down -v",
+ "db:generate": "turbo run db:generate",
+ "db:migrate": "turbo run db:migrate",
+ "db:seed": "turbo run db:seed",
+ "db:seed:examples": "turbo run db:seed:examples",
+ "nuke": "bash ./scripts/nuke.sh",
+ "dx": "pnpm i && pnpm run infra:dev:prune && pnpm run infra:dev:up --pull always && pnpm --filter=shared run db:reset:test && pnpm --filter=shared run db:reset && pnpm --filter=shared run ch:reset && pnpm --filter=shared run db:seed:examples && pnpm run dev",
+ "dx-f": "pnpm i && pnpm run infra:dev:prune && pnpm run infra:dev:up --pull always && pnpm --filter=shared run db:reset:test && pnpm --filter=shared run db:reset -f && SKIP_CONFIRM=1 pnpm --filter=shared run ch:reset && pnpm --filter=shared run db:seed:examples && pnpm run dev",
+ "dx:skip-infra": "pnpm i && pnpm --filter=shared run db:reset:test && pnpm --filter=shared run db:reset && pnpm --filter=shared run ch:reset && pnpm --filter=shared run db:seed:examples && pnpm run dev",
+ "build": "turbo run build",
+ "build:check": "turbo run build:check",
+ "typecheck": "turbo run typecheck",
+ "tc": "turbo run typecheck",
+ "start": "turbo run start",
+ "dev": "turbo run dev",
+ "dev:worker": "turbo run dev --filter=worker",
+ "dev:web": "turbo run dev --filter=web",
+ "dev:web-webpack": "turbo run dev --filter=web -- --webpack",
+ "lint": "turbo run lint",
+```
+
+This module is important because it defines how Langfuse Tutorial: LLM Observability, Evaluation, and Prompt Operations implements the patterns covered in this chapter.
+
+### `docker-compose.dev-azure.yml`
+
+The `docker-compose.dev-azure` module in [`docker-compose.dev-azure.yml`](https://github.com/langfuse/langfuse/blob/HEAD/docker-compose.dev-azure.yml) handles a key part of this chapter's functionality:
+
+```yml
+services:
+ clickhouse:
+ image: docker.io/clickhouse/clickhouse-server:24.3
+ user: "101:101"
+ environment:
+ CLICKHOUSE_DB: default
+ CLICKHOUSE_USER: ${CLICKHOUSE_USER:-clickhouse}
+ CLICKHOUSE_PASSWORD: ${CLICKHOUSE_PASSWORD:-clickhouse}
+ volumes:
+ - langfuse_clickhouse_data:/var/lib/clickhouse
+ - langfuse_clickhouse_logs:/var/log/clickhouse-server
+ ports:
+ - "8123:8123"
+ - "9000:9000"
+ healthcheck:
+ test: wget --no-verbose --tries=1 --spider http://localhost:8123/ping || exit 1
+ interval: 5s
+ timeout: 5s
+ retries: 10
+ start_period: 1s
+ depends_on:
+ - postgres
+
+ azurite:
+ image: mcr.microsoft.com/azure-storage/azurite
+ command: azurite-blob --blobHost 0.0.0.0
+ ports:
+ - "10000:10000"
+ volumes:
+ - langfuse_azurite_data:/data
+
+ minio:
+ image: cgr.dev/chainguard/minio
+ container_name: ${MINIO_CONTAINER_NAME:-langfuse-minio}
+ entrypoint: sh
+```
+
+This module is important because it defines how Langfuse Tutorial: LLM Observability, Evaluation, and Prompt Operations implements the patterns covered in this chapter.
+
+### `docker-compose.yml`
+
+The `docker-compose` module in [`docker-compose.yml`](https://github.com/langfuse/langfuse/blob/HEAD/docker-compose.yml) handles a key part of this chapter's functionality:
+
+```yml
+# Make sure to update the credential placeholders with your own secrets.
+# We mark them with # CHANGEME in the file below.
+# In addition, we recommend to restrict inbound traffic on the host to langfuse-web (port 3000) and minio (port 9090) only.
+# All other components are bound to localhost (127.0.0.1) to only accept connections from the local machine.
+# External connections from other machines will not be able to reach these services directly.
+services:
+ langfuse-worker:
+ image: docker.io/langfuse/langfuse-worker:3
+ restart: always
+ depends_on: &langfuse-depends-on
+ postgres:
+ condition: service_healthy
+ minio:
+ condition: service_healthy
+ redis:
+ condition: service_healthy
+ clickhouse:
+ condition: service_healthy
+ ports:
+ - 127.0.0.1:3030:3030
+ environment: &langfuse-worker-env
+ NEXTAUTH_URL: ${NEXTAUTH_URL:-http://localhost:3000}
+ DATABASE_URL: ${DATABASE_URL:-postgresql://postgres:postgres@postgres:5432/postgres} # CHANGEME
+ SALT: ${SALT:-mysalt} # CHANGEME
+ ENCRYPTION_KEY: ${ENCRYPTION_KEY:-0000000000000000000000000000000000000000000000000000000000000000} # CHANGEME: generate via `openssl rand -hex 32`
+ TELEMETRY_ENABLED: ${TELEMETRY_ENABLED:-true}
+ LANGFUSE_ENABLE_EXPERIMENTAL_FEATURES: ${LANGFUSE_ENABLE_EXPERIMENTAL_FEATURES:-false}
+ CLICKHOUSE_MIGRATION_URL: ${CLICKHOUSE_MIGRATION_URL:-clickhouse://clickhouse:9000}
+ CLICKHOUSE_URL: ${CLICKHOUSE_URL:-http://clickhouse:8123}
+ CLICKHOUSE_USER: ${CLICKHOUSE_USER:-clickhouse}
+ CLICKHOUSE_PASSWORD: ${CLICKHOUSE_PASSWORD:-clickhouse} # CHANGEME
+ CLICKHOUSE_CLUSTER_ENABLED: ${CLICKHOUSE_CLUSTER_ENABLED:-false}
+ LANGFUSE_USE_AZURE_BLOB: ${LANGFUSE_USE_AZURE_BLOB:-false}
+ LANGFUSE_S3_EVENT_UPLOAD_BUCKET: ${LANGFUSE_S3_EVENT_UPLOAD_BUCKET:-langfuse}
+ LANGFUSE_S3_EVENT_UPLOAD_REGION: ${LANGFUSE_S3_EVENT_UPLOAD_REGION:-auto}
+```
+
+This module is important because it defines how Langfuse Tutorial: LLM Observability, Evaluation, and Prompt Operations implements the patterns covered in this chapter.
+
+
+## How These Components Connect
+
+```mermaid
+flowchart TD
+ A[package]
+ B[docker-compose.dev-azure]
+ C[docker-compose]
+ A --> B
+ B --> C
+```
diff --git a/tutorials/langgraph-tutorial/01-getting-started.md b/tutorials/langgraph-tutorial/01-getting-started.md
index 351d4e99..55233463 100644
--- a/tutorials/langgraph-tutorial/01-getting-started.md
+++ b/tutorials/langgraph-tutorial/01-getting-started.md
@@ -386,6 +386,20 @@ Now that you understand LangGraph basics, let's explore state management in dept
*What kind of AI application will you build first with LangGraph?* 🤖
+## LangGraph Core Model
+
+```mermaid
+flowchart TD
+ A[StateGraph definition] --> B[Add nodes: functions or runnables]
+ B --> C[Add edges: node to node]
+ C --> D[Set entry point]
+ D --> E[graph.compile]
+ E --> F[Runnable graph]
+ F --> G[graph.invoke with initial state]
+ G --> H[Nodes execute in order]
+ H --> I[Final state returned]
+```
+
## What Problem Does This Solve?
Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for `state`, `graph`, `messages` so behavior stays predictable as complexity grows.
diff --git a/tutorials/langgraph-tutorial/02-state-management.md b/tutorials/langgraph-tutorial/02-state-management.md
index c23416a0..877afa94 100644
--- a/tutorials/langgraph-tutorial/02-state-management.md
+++ b/tutorials/langgraph-tutorial/02-state-management.md
@@ -417,6 +417,20 @@ Ready to build complex graphs? In [Chapter 3: Nodes and Edges](03-nodes-edges.md
*How will you manage state in your AI applications?* 🧠
+## State Management Flow
+
+```mermaid
+flowchart TD
+ A[TypedDict State schema] --> B[Initial state dict]
+ B --> C[Node receives state]
+ C --> D[Node returns partial state update]
+ D --> E[Reducer merges update into state]
+ E --> F[Updated state passed to next node]
+ F --> C
+ G[Checkpoint] --> B
+ F --> G
+```
+
## What Problem Does This Solve?
Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for `self`, `state`, `Dict` so behavior stays predictable as complexity grows.
diff --git a/tutorials/langgraph-tutorial/03-nodes-edges.md b/tutorials/langgraph-tutorial/03-nodes-edges.md
index d7120ff8..ac6aa420 100644
--- a/tutorials/langgraph-tutorial/03-nodes-edges.md
+++ b/tutorials/langgraph-tutorial/03-nodes-edges.md
@@ -568,6 +568,21 @@ Ready for conditional logic and decision-making? In [Chapter 4: Conditional Logi
*What's the most complex graph structure you'll build?* 🔀
+## Node and Edge Architecture
+
+```mermaid
+flowchart TD
+ A[StateGraph] --> B[Node: Python function]
+ B --> C[Receives state dict]
+ C --> D[Returns state updates]
+ A --> E[Edge: node_a to node_b]
+ A --> F[Conditional edge: router function]
+ F --> G{Routing decision}
+ G -->|Condition A| H[Node A]
+ G -->|Condition B| I[Node B]
+ G -->|END| J[Graph terminates]
+```
+
## What Problem Does This Solve?
Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for `state`, `graph`, `GraphState` so behavior stays predictable as complexity grows.
diff --git a/tutorials/langgraph-tutorial/04-conditional-logic.md b/tutorials/langgraph-tutorial/04-conditional-logic.md
index bb9829d2..d3d7f3a1 100644
--- a/tutorials/langgraph-tutorial/04-conditional-logic.md
+++ b/tutorials/langgraph-tutorial/04-conditional-logic.md
@@ -801,6 +801,20 @@ Ready to coordinate multiple agents? In [Chapter 5: Multi-Agent Systems](05-mult
*What's the most sophisticated decision system you'll build?* 🤔
+## Conditional Routing
+
+```mermaid
+flowchart TD
+ A[Current state] --> B[Router function]
+ B --> C{Evaluate condition}
+ C -->|should_continue| D[Continue node]
+ C -->|need_tools| E[Tool node]
+ C -->|END| F[Terminal state]
+ D --> G[Next processing]
+ E --> H[Tool execution]
+ H --> A
+```
+
## What Problem Does This Solve?
Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for `state`, `graph`, `dict` so behavior stays predictable as complexity grows.
diff --git a/tutorials/langgraph-tutorial/05-multi-agent-systems.md b/tutorials/langgraph-tutorial/05-multi-agent-systems.md
index 601b7d2b..f5a785ca 100644
--- a/tutorials/langgraph-tutorial/05-multi-agent-systems.md
+++ b/tutorials/langgraph-tutorial/05-multi-agent-systems.md
@@ -679,6 +679,21 @@ Ready to integrate external tools and APIs? In [Chapter 6: Tool Integration](06-
*What's the most complex multi-agent system you'll create?* 🤝
+## Multi-Agent Graph
+
+```mermaid
+flowchart TD
+ A[Supervisor agent] --> B{Route to specialist}
+ B -->|Research task| C[Researcher agent node]
+ B -->|Coding task| D[Coder agent node]
+ B -->|Review| E[Reviewer agent node]
+ C --> F[Update shared state]
+ D --> F
+ E --> F
+ F --> A
+ A -->|FINISH| G[Final output]
+```
+
## What Problem Does This Solve?
Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for `state`, `self`, `graph` so behavior stays predictable as complexity grows.
diff --git a/tutorials/letta-tutorial/01-getting-started.md b/tutorials/letta-tutorial/01-getting-started.md
index 93f82c39..8958b192 100644
--- a/tutorials/letta-tutorial/01-getting-started.md
+++ b/tutorials/letta-tutorial/01-getting-started.md
@@ -13,6 +13,29 @@ Welcome to **Chapter 1: Getting Started with Letta**. In this part of **Letta Tu
> Install Letta, create your first agent, and start a conversation with persistent memory.
+## Architecture Overview
+
+```mermaid
+flowchart TD
+ A[Install: pip install letta] --> B[Configure LLM Provider]
+ B --> C[Start Letta Server]
+ C --> D[Create Agent via SDK or CLI]
+ D --> E[Agent with Core Memory]
+ E --> F[Send Messages]
+ F --> G[Agent Processes + Stores Facts]
+ G --> H[Persistent Memory Across Sessions]
+
+ classDef install fill:#e1f5fe,stroke:#01579b
+ classDef config fill:#f3e5f5,stroke:#4a148c
+ classDef agent fill:#fff3e0,stroke:#ef6c00
+ classDef output fill:#e8f5e9,stroke:#1b5e20
+
+ class A,B install
+ class C,D config
+ class E,F,G agent
+ class H output
+```
+
## Overview
Letta (formerly MemGPT) enables AI agents with persistent memory. This chapter covers installation, basic setup, and your first conversation with an agent that remembers.
@@ -196,16 +219,13 @@ When debugging, walk this sequence in order and confirm each stage has explicit
## Source Walkthrough
-Use the following upstream sources to verify implementation details while reading this chapter:
+Key source files in [`letta-ai/letta`](https://github.com/letta-ai/letta):
-- [View Repo](https://github.com/letta-ai/letta)
- Why it matters: authoritative reference on `View Repo` (github.com).
-- [Awesome Code Docs](https://github.com/johnxie/awesome-code-docs)
- Why it matters: authoritative reference on `Awesome Code Docs` (github.com).
+- [`letta/client/client.py`](https://github.com/letta-ai/letta/blob/main/letta/client/client.py) -- `LocalClient` and `RESTClient`: `create_agent()`, `send_message()`, `get_agent()` entry points
+- [`letta/server/server.py`](https://github.com/letta-ai/letta/blob/main/letta/server/server.py) -- `SyncServer`: orchestrates agent creation, message processing, and memory persistence
+- [`letta/agent.py`](https://github.com/letta-ai/letta/blob/main/letta/agent.py) -- `Agent` class: `step()` method drives the core LLM call + memory update loop
-Suggested trace strategy:
-- search upstream code for `letta` and `name` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+Suggested trace: `client.send_message()` → `SyncServer.user_message()` → `Agent.step()` to follow a message from user input to persisted memory update.
## Chapter Connections
diff --git a/tutorials/letta-tutorial/02-memory.md b/tutorials/letta-tutorial/02-memory.md
index 09faa604..c390ff9a 100644
--- a/tutorials/letta-tutorial/02-memory.md
+++ b/tutorials/letta-tutorial/02-memory.md
@@ -13,6 +13,41 @@ Welcome to **Chapter 2: Memory Architecture in Letta**. In this part of **Letta
> Understand core memory, archival memory, and recall memory - the three pillars of persistent agent memory.
+## Memory Architecture
+
+```mermaid
+flowchart TD
+ CTX[LLM Context Window]
+
+ subgraph CoreMem["Core Memory (In-Context)"]
+ PM[Persona Block]
+ HM[Human Block]
+ end
+
+ subgraph ArchivalMem["Archival Memory (External Store)"]
+ VS[Vector Database]
+ KG[Knowledge Graph]
+ end
+
+ subgraph RecallMem["Recall Memory (Conversation History)"]
+ CH[Past Messages Index]
+ end
+
+ CTX --> CoreMem
+ CoreMem -->|search_archival| ArchivalMem
+ CoreMem -->|search_recall| RecallMem
+ ArchivalMem -->|retrieved chunks| CTX
+ RecallMem -->|retrieved messages| CTX
+
+ classDef ctx fill:#e1f5fe,stroke:#01579b
+ classDef core fill:#f3e5f5,stroke:#4a148c
+ classDef external fill:#fff3e0,stroke:#ef6c00
+
+ class CTX ctx
+ class PM,HM core
+ class VS,KG,CH external
+```
+
## Overview
Letta's memory system is hierarchical and designed to give agents virtually unlimited context. This chapter explores the three types of memory and how they work together.
@@ -246,16 +281,13 @@ When debugging, walk this sequence in order and confirm each stage has explicit
## Source Walkthrough
-Use the following upstream sources to verify implementation details while reading this chapter:
+Key source files in [`letta-ai/letta`](https://github.com/letta-ai/letta):
-- [View Repo](https://github.com/letta-ai/letta)
- Why it matters: authoritative reference on `View Repo` (github.com).
-- [Awesome Code Docs](https://github.com/johnxie/awesome-code-docs)
- Why it matters: authoritative reference on `Awesome Code Docs` (github.com).
+- [`letta/memory.py`](https://github.com/letta-ai/letta/blob/main/letta/memory.py) -- `CoreMemory`, `ArchivalMemory`, `RecallMemory` base classes; `__repr__` shows what's visible in context
+- [`letta/agent.py`](https://github.com/letta-ai/letta/blob/main/letta/agent.py) -- `_build_system_message()` assembles the context window by combining core memory blocks with tool definitions
+- [`letta/functions/function_sets/base.py`](https://github.com/letta-ai/letta/blob/main/letta/functions/function_sets/base.py) -- built-in memory tools: `archival_memory_search`, `archival_memory_insert`, `recall_memory_search`
-Suggested trace strategy:
-- search upstream code for `client` and `memory` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+Suggested trace: watch how `Agent.step()` calls `_build_system_message()` to construct the prompt, then observe how archival search results get injected into the tool response context.
## Chapter Connections
diff --git a/tutorials/letta-tutorial/03-configuration.md b/tutorials/letta-tutorial/03-configuration.md
index 7f2eabfb..d3926294 100644
--- a/tutorials/letta-tutorial/03-configuration.md
+++ b/tutorials/letta-tutorial/03-configuration.md
@@ -13,6 +13,23 @@ Welcome to **Chapter 3: Agent Configuration**. In this part of **Letta Tutorial:
> Customize agent personalities, system prompts, models, and behavior settings.
+## Agent Configuration Model
+
+```mermaid
+flowchart LR
+ A[create_agent call] --> B{Configuration}
+ B --> C[LLM Config\nmodel, provider, context_window]
+ B --> D[Embedding Config\nmodel, endpoint]
+ B --> E[Memory Blocks\npersona + human blocks]
+ B --> F[System Prompt\ninstruction override]
+ B --> G[Tools\nbuilt-in + custom]
+ C --> H[Agent Instance]
+ D --> H
+ E --> H
+ F --> H
+ G --> H
+```
+
## Overview
Letta agents are highly configurable. This chapter covers personas, system prompts, model selection, and fine-tuning agent behavior for different use cases.
@@ -321,16 +338,13 @@ When debugging, walk this sequence in order and confirm each stage has explicit
## Source Walkthrough
-Use the following upstream sources to verify implementation details while reading this chapter:
+Key source files in [`letta-ai/letta`](https://github.com/letta-ai/letta):
-- [View Repo](https://github.com/letta-ai/letta)
- Why it matters: authoritative reference on `View Repo` (github.com).
-- [Awesome Code Docs](https://github.com/johnxie/awesome-code-docs)
- Why it matters: authoritative reference on `Awesome Code Docs` (github.com).
+- [`letta/schemas/agent.py`](https://github.com/letta-ai/letta/blob/main/letta/schemas/agent.py) -- `AgentState` and `CreateAgent` schemas; all configurable fields including `llm_config`, `embedding_config`, and `memory_blocks`
+- [`letta/schemas/llm_config.py`](https://github.com/letta-ai/letta/blob/main/letta/schemas/llm_config.py) -- `LLMConfig` dataclass: `model`, `model_endpoint_type`, `context_window` fields
+- [`letta/server/server.py`](https://github.com/letta-ai/letta/blob/main/letta/server/server.py) -- `create_agent()` method: validates config and initializes agent state in the database
-Suggested trace strategy:
-- search upstream code for `name` and `persona` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+Suggested trace: `CreateAgent` schema validation → `SyncServer.create_agent()` → `Agent.__init__()` to follow configuration from API call to runtime.
## Chapter Connections
diff --git a/tutorials/letta-tutorial/04-tools.md b/tutorials/letta-tutorial/04-tools.md
index 965829b0..82302098 100644
--- a/tutorials/letta-tutorial/04-tools.md
+++ b/tutorials/letta-tutorial/04-tools.md
@@ -13,6 +13,25 @@ Welcome to **Chapter 4: Tool Integration**. In this part of **Letta Tutorial: St
> Extend agent capabilities with custom tools, functions, and external integrations.
+## Tool Execution Flow
+
+```mermaid
+sequenceDiagram
+ participant U as User
+ participant A as Letta Agent
+ participant L as LLM
+ participant T as Tool Function
+
+ U->>A: send_message("Get weather in NYC")
+ A->>L: Context + available tools (schema)
+ L->>A: Tool call: get_weather(city="NYC")
+ A->>T: Execute get_weather("NYC")
+ T->>A: "Sunny, 72°F"
+ A->>L: Tool result injected into context
+ L->>A: Final response text
+ A->>U: "The weather in NYC is sunny and 72°F"
+```
+
## Overview
Tools allow agents to interact with the external world - calling APIs, running code, accessing databases, and more. This chapter covers creating and integrating tools with Letta agents.
@@ -425,16 +444,13 @@ When debugging, walk this sequence in order and confirm each stage has explicit
## Source Walkthrough
-Use the following upstream sources to verify implementation details while reading this chapter:
+Key source files in [`letta-ai/letta`](https://github.com/letta-ai/letta):
-- [View Repo](https://github.com/letta-ai/letta)
- Why it matters: authoritative reference on `View Repo` (github.com).
-- [Awesome Code Docs](https://github.com/johnxie/awesome-code-docs)
- Why it matters: authoritative reference on `Awesome Code Docs` (github.com).
+- [`letta/functions/functions.py`](https://github.com/letta-ai/letta/blob/main/letta/functions/functions.py) -- `derive_openai_json_schema()` converts Python function signatures to JSON Schema for the LLM tool spec
+- [`letta/agent.py`](https://github.com/letta-ai/letta/blob/main/letta/agent.py) -- `_execute_tool()` method: dispatches tool calls, captures results, and appends them to the message chain
+- [`letta/server/server.py`](https://github.com/letta-ai/letta/blob/main/letta/server/server.py) -- `create_tool()` and `attach_tool()` methods for registering custom tools with an agent
-Suggested trace strategy:
-- search upstream code for `client` and `result` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+Suggested trace: `Agent._execute_tool()` receives the LLM's tool call → looks up the function by name → executes with arguments → returns result as a tool message.
## Chapter Connections
diff --git a/tutorials/letta-tutorial/05-conversations.md b/tutorials/letta-tutorial/05-conversations.md
index 48605c90..d1c64035 100644
--- a/tutorials/letta-tutorial/05-conversations.md
+++ b/tutorials/letta-tutorial/05-conversations.md
@@ -13,6 +13,19 @@ Welcome to **Chapter 5: Conversation Management**. In this part of **Letta Tutor
> Handle long-running dialogues, manage conversation state, and implement conversation patterns.
+## Conversation Lifecycle
+
+```mermaid
+stateDiagram-v2
+ [*] --> Created: create_agent()
+ Created --> Active: send_message()
+ Active --> Processing: LLM inference + memory ops
+ Processing --> Active: response returned
+ Active --> Archived: agent inactive for extended period
+ Archived --> Active: send_message() resumes
+ Active --> [*]: agent deleted
+```
+
## Overview
Letta excels at managing long-term conversations. This chapter covers conversation lifecycle, state management, branching conversations, and implementing conversation patterns.
@@ -437,16 +450,13 @@ When debugging, walk this sequence in order and confirm each stage has explicit
## Source Walkthrough
-Use the following upstream sources to verify implementation details while reading this chapter:
+Key source files in [`letta-ai/letta`](https://github.com/letta-ai/letta):
-- [View Repo](https://github.com/letta-ai/letta)
- Why it matters: authoritative reference on `View Repo` (github.com).
-- [Awesome Code Docs](https://github.com/johnxie/awesome-code-docs)
- Why it matters: authoritative reference on `Awesome Code Docs` (github.com).
+- [`letta/client/client.py`](https://github.com/letta-ai/letta/blob/main/letta/client/client.py) -- `send_message()` and `get_messages()`: the primary conversation API surface
+- [`letta/server/server.py`](https://github.com/letta-ai/letta/blob/main/letta/server/server.py) -- `user_message()`: processes incoming messages and triggers `Agent.step()`
+- [`letta/agent.py`](https://github.com/letta-ai/letta/blob/main/letta/agent.py) -- `_init_messages()` shows how conversation history is reconstructed at the start of each `step()`
-Suggested trace strategy:
-- search upstream code for `agent_name` and `self` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+Suggested trace: follow `send_message()` → `user_message()` → `Agent.step()` → observe how prior conversation turns from recall memory are injected into the prompt.
## Chapter Connections
diff --git a/tutorials/letta-tutorial/06-multi-agent.md b/tutorials/letta-tutorial/06-multi-agent.md
index 4a314ec3..ada7eca3 100644
--- a/tutorials/letta-tutorial/06-multi-agent.md
+++ b/tutorials/letta-tutorial/06-multi-agent.md
@@ -13,6 +13,22 @@ Welcome to **Chapter 6: Multi-Agent Systems**. In this part of **Letta Tutorial:
> Coordinate multiple agents, implement agent communication, and build collaborative workflows.
+## Multi-Agent Coordination
+
+```mermaid
+flowchart TD
+ U[User Request] --> O[Orchestrator Agent]
+ O -->|delegate research| R[Research Agent]
+ O -->|delegate writing| W[Writer Agent]
+ R -->|findings| O
+ W -->|draft| O
+ O -->|combined response| U
+
+ R --> M1[(Agent 1 Memory)]
+ W --> M2[(Agent 2 Memory)]
+ O --> M3[(Orchestrator Memory)]
+```
+
## Overview
Letta supports multi-agent systems where agents can communicate, delegate tasks, and collaborate. This chapter covers agent coordination, message passing, and implementing complex multi-agent workflows.
@@ -491,16 +507,13 @@ When debugging, walk this sequence in order and confirm each stage has explicit
## Source Walkthrough
-Use the following upstream sources to verify implementation details while reading this chapter:
+Key source files in [`letta-ai/letta`](https://github.com/letta-ai/letta):
-- [View Repo](https://github.com/letta-ai/letta)
- Why it matters: authoritative reference on `View Repo` (github.com).
-- [Awesome Code Docs](https://github.com/johnxie/awesome-code-docs)
- Why it matters: authoritative reference on `Awesome Code Docs` (github.com).
+- [`letta/functions/function_sets/multi_agent.py`](https://github.com/letta-ai/letta/blob/main/letta/functions/function_sets/multi_agent.py) -- `send_message_to_agent()` built-in tool that enables one agent to message another
+- [`letta/server/server.py`](https://github.com/letta-ai/letta/blob/main/letta/server/server.py) -- `user_message()` accepts messages from both human users and other agents
+- [`letta/schemas/agent.py`](https://github.com/letta-ai/letta/blob/main/letta/schemas/agent.py) -- `AgentState` with `agent_type` field distinguishing orchestrator vs. subagent roles
-Suggested trace strategy:
-- search upstream code for `self` and `content` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+Suggested trace: examine how `send_message_to_agent` tool call triggers a recursive `SyncServer.user_message()` call targeting the destination agent.
## Chapter Connections
diff --git a/tutorials/letta-tutorial/07-api.md b/tutorials/letta-tutorial/07-api.md
index 363d2a51..079849e1 100644
--- a/tutorials/letta-tutorial/07-api.md
+++ b/tutorials/letta-tutorial/07-api.md
@@ -13,6 +13,24 @@ Welcome to **Chapter 7: REST API**. In this part of **Letta Tutorial: Stateful L
> Deploy Letta agents as REST API services for integration with applications.
+## REST API Architecture
+
+```mermaid
+flowchart LR
+ C[Client App] -->|HTTP POST /v1/agents/{id}/messages| S[Letta Server :8283]
+ S --> AG[Agent Engine]
+ AG --> LLM[LLM Provider]
+ AG --> DB[(PostgreSQL / SQLite)]
+ S -->|JSON response| C
+
+ subgraph Endpoints
+ E1[POST /v1/agents]
+ E2[POST /v1/agents/{id}/messages]
+ E3[GET /v1/agents/{id}/memory]
+ E4[PATCH /v1/agents/{id}/memory/blocks]
+ end
+```
+
## Overview
Letta provides a REST API for programmatic access to agents. This chapter covers API endpoints, authentication, deployment options, and building applications that integrate with Letta agents.
@@ -497,16 +515,13 @@ When debugging, walk this sequence in order and confirm each stage has explicit
## Source Walkthrough
-Use the following upstream sources to verify implementation details while reading this chapter:
+Key source files in [`letta-ai/letta`](https://github.com/letta-ai/letta):
-- [View Repo](https://github.com/letta-ai/letta)
- Why it matters: authoritative reference on `View Repo` (github.com).
-- [Awesome Code Docs](https://github.com/johnxie/awesome-code-docs)
- Why it matters: authoritative reference on `Awesome Code Docs` (github.com).
+- [`letta/server/rest_api/app.py`](https://github.com/letta-ai/letta/blob/main/letta/server/rest_api/app.py) -- FastAPI app setup; mounts all API routers
+- [`letta/server/rest_api/routers/v1/agents.py`](https://github.com/letta-ai/letta/blob/main/letta/server/rest_api/routers/v1/agents.py) -- REST endpoints for agent CRUD and messaging (`POST /v1/agents/{agent_id}/messages`)
+- [`letta/client/client.py`](https://github.com/letta-ai/letta/blob/main/letta/client/client.py) -- `RESTClient` class: wraps HTTP calls to match `LocalClient` API surface; useful reference for building custom API clients
-Suggested trace strategy:
-- search upstream code for `response` and `json` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+Suggested trace: `RESTClient.send_message()` → HTTP POST to `/v1/agents/{id}/messages` → `agents.py` router → `SyncServer.user_message()`.
## Chapter Connections
diff --git a/tutorials/letta-tutorial/08-production.md b/tutorials/letta-tutorial/08-production.md
index 76fdedab..d97ececb 100644
--- a/tutorials/letta-tutorial/08-production.md
+++ b/tutorials/letta-tutorial/08-production.md
@@ -13,6 +13,28 @@ Welcome to **Chapter 8: Production Deployment**. In this part of **Letta Tutoria
> Deploy Letta agents to production with scaling, monitoring, security, and operational best practices.
+## Production Deployment Architecture
+
+```mermaid
+flowchart TD
+ LB[Load Balancer] --> S1[Letta Server Instance 1]
+ LB --> S2[Letta Server Instance 2]
+ S1 --> DB[(PostgreSQL - Shared State)]
+ S2 --> DB
+ S1 --> LLM[LLM Provider API]
+ S2 --> LLM
+ S1 --> MON[Metrics / Logging]
+ S2 --> MON
+
+ classDef infra fill:#e1f5fe,stroke:#01579b
+ classDef server fill:#f3e5f5,stroke:#4a148c
+ classDef storage fill:#fff3e0,stroke:#ef6c00
+
+ class LB infra
+ class S1,S2 server
+ class DB,LLM,MON storage
+```
+
## Overview
Deploying Letta agents to production requires careful consideration of scaling, data persistence, security, and monitoring. This chapter covers production deployment patterns and operational practices.
@@ -669,16 +691,13 @@ When debugging, walk this sequence in order and confirm each stage has explicit
## Source Walkthrough
-Use the following upstream sources to verify implementation details while reading this chapter:
+Key source files in [`letta-ai/letta`](https://github.com/letta-ai/letta):
-- [View Repo](https://github.com/letta-ai/letta)
- Why it matters: authoritative reference on `View Repo` (github.com).
-- [Awesome Code Docs](https://github.com/johnxie/awesome-code-docs)
- Why it matters: authoritative reference on `Awesome Code Docs` (github.com).
+- [`letta/server/rest_api/app.py`](https://github.com/letta-ai/letta/blob/main/letta/server/rest_api/app.py) -- startup config: database URL, auth middleware, CORS, and worker settings
+- [`docker-compose.yml`](https://github.com/letta-ai/letta/blob/main/docker-compose.yml) -- reference compose file for PostgreSQL + Letta server with environment variable config
+- [`letta/settings.py`](https://github.com/letta-ai/letta/blob/main/letta/settings.py) -- `Settings` class using Pydantic `BaseSettings`; all environment variable overrides for production tuning
-Suggested trace strategy:
-- search upstream code for `letta` and `name` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+Suggested trace: review `Settings` fields to understand all production-relevant config options, then compare against the `docker-compose.yml` service definition.
## Chapter Connections
diff --git a/tutorials/litellm-tutorial/01-getting-started.md b/tutorials/litellm-tutorial/01-getting-started.md
index c16ec931..d778815e 100644
--- a/tutorials/litellm-tutorial/01-getting-started.md
+++ b/tutorials/litellm-tutorial/01-getting-started.md
@@ -6,6 +6,7 @@ has_children: false
parent: LiteLLM Tutorial
---
+
# Chapter 1: Getting Started with LiteLLM
Welcome to **Chapter 1: Getting Started with LiteLLM**. In this part of **LiteLLM Tutorial: Unified LLM Gateway and Routing Layer**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
@@ -317,316 +318,184 @@ print('Response:', response.choices[0].message.content)
## Depth Expansion Playbook
-<!-- depth-expansion-v2 -->
-
-This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
-
-### Strategic Context
-
-- tutorial: **LiteLLM Tutorial: Unified LLM Gateway and Routing Layer**
-- tutorial slug: **litellm-tutorial**
-- chapter focus: **Chapter 1: Getting Started with LiteLLM**
-- system context: **Litellm Tutorial**
-- objective: move from surface-level usage to repeatable engineering operation
-
-### Architecture Decomposition
-
-1. Define the runtime boundary for `Chapter 1: Getting Started with LiteLLM`.
-2. Separate control-plane decisions from data-plane execution.
-3. Capture input contracts, transformation points, and output contracts.
-4. Trace state transitions across request lifecycle stages.
-5. Identify extension hooks and policy interception points.
-6. Map ownership boundaries for team and automation workflows.
-7. Specify rollback and recovery paths for unsafe changes.
-8. Track observability signals for correctness, latency, and cost.
-
-### Operator Decision Matrix
-
-| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
-|:--------------|:--------------|:------------------|:---------|
-| Runtime mode | managed defaults | explicit policy config | speed vs control |
-| State handling | local ephemeral | durable persisted state | simplicity vs auditability |
-| Tool integration | direct API use | mediated adapter layer | velocity vs governance |
-| Rollout method | manual change | staged + canary rollout | effort vs safety |
-| Incident response | best effort logs | runbooks + SLO alerts | cost vs reliability |
-
-### Failure Modes and Countermeasures
-
-| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
-|:-------------|:-------------|:-------------------|:---------------|
-| stale context | inconsistent outputs | missing refresh window | enforce context TTL and refresh hooks |
-| policy drift | unexpected execution | ad hoc overrides | centralize policy profiles |
-| auth mismatch | 401/403 bursts | credential sprawl | rotation schedule + scope minimization |
-| schema breakage | parser/validation errors | unmanaged upstream changes | contract tests per release |
-| retry storms | queue congestion | no backoff controls | jittered backoff + circuit breakers |
-| silent regressions | quality drop without alerts | weak baseline metrics | eval harness with thresholds |
-
-### Implementation Runbook
-
-1. Establish a reproducible baseline environment.
-2. Capture chapter-specific success criteria before changes.
-3. Implement minimal viable path with explicit interfaces.
-4. Add observability before expanding feature scope.
-5. Run deterministic tests for happy-path behavior.
-6. Inject failure scenarios for negative-path validation.
-7. Compare output quality against baseline snapshots.
-8. Promote through staged environments with rollback gates.
-9. Record operational lessons in release notes.
-
-### Quality Gate Checklist
-
-- [ ] chapter-level assumptions are explicit and testable
-- [ ] API/tool boundaries are documented with input/output examples
-- [ ] failure handling includes retry, timeout, and fallback policy
-- [ ] security controls include auth scopes and secret rotation plans
-- [ ] observability includes logs, metrics, traces, and alert thresholds
-- [ ] deployment guidance includes canary and rollback paths
-- [ ] docs include links to upstream sources and related tracks
-- [ ] post-release verification confirms expected behavior under load
-
-### Source Alignment
-
-- [LiteLLM Repository](https://github.com/BerriAI/litellm)
-- [LiteLLM Releases](https://github.com/BerriAI/litellm/releases)
-- [LiteLLM Docs](https://docs.litellm.ai/)
-
-### Cross-Tutorial Connection Map
-
-- [Langfuse Tutorial](../langfuse-tutorial/)
-- [Vercel AI SDK Tutorial](../vercel-ai-tutorial/)
-- [OpenAI Python SDK Tutorial](../openai-python-sdk-tutorial/)
-- [Aider Tutorial](../aider-tutorial/)
-- [Chapter 1: Getting Started](01-getting-started.md)
-
-### Advanced Practice Exercises
-
-1. Build a minimal end-to-end implementation for `Chapter 1: Getting Started with LiteLLM`.
-2. Add instrumentation and measure baseline latency and error rate.
-3. Introduce one controlled failure and confirm graceful recovery.
-4. Add policy constraints and verify they are enforced consistently.
-5. Run a staged rollout and document rollback decision criteria.
-
-### Review Questions
-
-1. Which execution boundary matters most for this chapter and why?
-2. What signal detects regressions earliest in your environment?
-3. What tradeoff did you make between delivery speed and governance?
-4. How would you recover from the highest-impact failure mode?
-5. What must be automated before scaling to team-wide adoption?
-
-### Scenario Playbook 1: Chapter 1: Getting Started with LiteLLM
-
-- tutorial context: **LiteLLM Tutorial: Unified LLM Gateway and Routing Layer**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 2: Chapter 1: Getting Started with LiteLLM
-
-- tutorial context: **LiteLLM Tutorial: Unified LLM Gateway and Routing Layer**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 3: Chapter 1: Getting Started with LiteLLM
-
-- tutorial context: **LiteLLM Tutorial: Unified LLM Gateway and Routing Layer**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 4: Chapter 1: Getting Started with LiteLLM
-
-- tutorial context: **LiteLLM Tutorial: Unified LLM Gateway and Routing Layer**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 5: Chapter 1: Getting Started with LiteLLM
-
-- tutorial context: **LiteLLM Tutorial: Unified LLM Gateway and Routing Layer**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 6: Chapter 1: Getting Started with LiteLLM
-
-- tutorial context: **LiteLLM Tutorial: Unified LLM Gateway and Routing Layer**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 7: Chapter 1: Getting Started with LiteLLM
-
-- tutorial context: **LiteLLM Tutorial: Unified LLM Gateway and Routing Layer**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 8: Chapter 1: Getting Started with LiteLLM
-
-- tutorial context: **LiteLLM Tutorial: Unified LLM Gateway and Routing Layer**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 9: Chapter 1: Getting Started with LiteLLM
-
-- tutorial context: **LiteLLM Tutorial: Unified LLM Gateway and Routing Layer**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 10: Chapter 1: Getting Started with LiteLLM
-
-- tutorial context: **LiteLLM Tutorial: Unified LLM Gateway and Routing Layer**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 11: Chapter 1: Getting Started with LiteLLM
-
-- tutorial context: **LiteLLM Tutorial: Unified LLM Gateway and Routing Layer**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 12: Chapter 1: Getting Started with LiteLLM
-
-- tutorial context: **LiteLLM Tutorial: Unified LLM Gateway and Routing Layer**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 13: Chapter 1: Getting Started with LiteLLM
-
-- tutorial context: **LiteLLM Tutorial: Unified LLM Gateway and Routing Layer**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 14: Chapter 1: Getting Started with LiteLLM
-
-- tutorial context: **LiteLLM Tutorial: Unified LLM Gateway and Routing Layer**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-## What Problem Does This Solve?
-
-Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for `litellm`, `model`, `content` so behavior stays predictable as complexity grows.
-
-In practical terms, this chapter helps you avoid three common failures:
-
-- coupling core logic too tightly to one implementation path
-- missing the handoff boundaries between setup, execution, and validation
-- shipping changes without clear rollback or observability strategy
-
-After working through this chapter, you should be able to reason about `Chapter 1: Getting Started with LiteLLM` as an operating subsystem inside **LiteLLM Tutorial: Unified LLM Gateway and Routing Layer**, with explicit contracts for inputs, state transitions, and outputs.
-
-Use the implementation notes around `response`, `turbo`, `completion` as your checklist when adapting these patterns to your own repository.
-
-## How it Works Under the Hood
-
-Under the hood, `Chapter 1: Getting Started with LiteLLM` usually follows a repeatable control path:
-
-1. **Context bootstrap**: initialize runtime config and prerequisites for `litellm`.
-2. **Input normalization**: shape incoming data so `model` receives stable contracts.
-3. **Core execution**: run the main logic branch and propagate intermediate state through `content`.
-4. **Policy and safety checks**: enforce limits, auth scopes, and failure boundaries.
-5. **Output composition**: return canonical result payloads for downstream consumers.
-6. **Operational telemetry**: emit logs/metrics needed for debugging and performance tuning.
-
-When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
-
-## Source Walkthrough
-
-Use the following upstream sources to verify implementation details while reading this chapter:
-
-- [LiteLLM Repository](https://github.com/BerriAI/litellm)
- Why it matters: authoritative reference on `LiteLLM Repository` (github.com).
-- [LiteLLM Releases](https://github.com/BerriAI/litellm/releases)
- Why it matters: authoritative reference on `LiteLLM Releases` (github.com).
-- [LiteLLM Docs](https://docs.litellm.ai/)
- Why it matters: authoritative reference on `LiteLLM Docs` (docs.litellm.ai).
-
-Suggested trace strategy:
-- search upstream code for `litellm` and `model` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
-
-## Chapter Connections
-
-- [Tutorial Index](README.md)
-- [Next Chapter: Chapter 2: Provider Configuration](02-providers.md)
-- [Main Catalog](../../README.md#-tutorial-catalog)
-- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
+## Source Code Walkthrough
+
+### `pyproject.toml`
+
+The `with` interface in [`pyproject.toml`](https://github.com/BerriAI/litellm/blob/HEAD/pyproject.toml) handles a key part of this chapter's functionality:
+
+```toml
+name = "litellm"
+version = "1.83.2"
+description = "Library to easily interface with LLM API providers"
+authors = ["BerriAI"]
+license = "MIT"
+readme = "README.md"
+packages = [
+ { include = "litellm" },
+ { include = "litellm/py.typed"},
+]
+
+[tool.poetry.urls]
+homepage = "https://litellm.ai"
+Homepage = "https://litellm.ai"
+repository = "https://github.com/BerriAI/litellm"
+Repository = "https://github.com/BerriAI/litellm"
+documentation = "https://docs.litellm.ai"
+Documentation = "https://docs.litellm.ai"
+
+# Dependencies pinned from `pip install litellm[proxy]==1.83.0` PyPI resolution.
+# Docker builds use requirements.txt (different pins). These two paths are independent.
+[tool.poetry.dependencies]
+python = ">=3.9,<4.0"
+fastuuid = "0.14.0"
+httpx = "0.28.1"
+openai = "2.30.0"
+python-dotenv = "1.0.1"
+tiktoken = "0.12.0"
+importlib-metadata = "8.5.0"
+tokenizers = "0.22.2"
+click = "8.1.8"
+jinja2 = "3.1.6"
+```
+
+This interface is important because it defines how LiteLLM Tutorial: Unified LLM Gateway and Routing Layer implements the patterns covered in this chapter.
+
+### `litellm/_lazy_imports.py`
+
+The `value` class in [`litellm/_lazy_imports.py`](https://github.com/BerriAI/litellm/blob/HEAD/litellm/_lazy_imports.py) handles a key part of this chapter's functionality:
+
+```py
+ Steps:
+ 1. Check if the name exists in the import map (if not, raise error)
+ 2. Check if we've already imported it (if yes, return cached value)
+ 3. Look up where to find it (module_path and attr_name from the map)
+ 4. Import the module (Python caches this automatically)
+ 5. Get the attribute from the module
+ 6. Cache it in _globals so we don't import again
+ 7. Return it
+
+ Args:
+ name: The attribute name someone is trying to access (e.g., "ModelResponse")
+ import_map: Dictionary telling us where to find each attribute
+ Format: {"ModelResponse": (".utils", "ModelResponse")}
+ category: Just for error messages (e.g., "Utils", "Cost calculator")
+ """
+ # Step 1: Make sure this attribute exists in our map
+ if name not in import_map:
+ raise AttributeError(f"{category} lazy import: unknown attribute {name!r}")
+
+ # Step 2: Get the cache (where we store imported things)
+ _globals = _get_litellm_globals()
+
+ # Step 3: If we've already imported it, just return the cached version
+ if name in _globals:
+ return _globals[name]
+
+ # Step 4: Look up where to find this attribute
+ # The map tells us: (module_path, attribute_name)
+ # Example: (".utils", "ModelResponse") means "look in .utils module, get ModelResponse"
+ module_path, attr_name = import_map[name]
+
+ # Step 5: Import the module
+```
+
+This class is important because it defines how LiteLLM Tutorial: Unified LLM Gateway and Routing Layer implements the patterns covered in this chapter.
+
+### `litellm/_lazy_imports.py`
+
+The `itself` class in [`litellm/_lazy_imports.py`](https://github.com/BerriAI/litellm/blob/HEAD/litellm/_lazy_imports.py) handles a key part of this chapter's functionality:
+
+```py
+
+ This one is different because:
+ - "LLMClientCache" is the class itself
+ - "in_memory_llm_clients_cache" is a singleton instance of that class
+ So we need custom logic to handle both cases.
+ """
+ _globals = _get_litellm_globals()
+
+ # If already cached, return it
+ if name in _globals:
+ return _globals[name]
+
+ # Import the class
+ module = importlib.import_module("litellm.caching.llm_caching_handler")
+ LLMClientCache = getattr(module, "LLMClientCache")
+
+ # If they want the class itself, return it
+ if name == "LLMClientCache":
+ _globals["LLMClientCache"] = LLMClientCache
+ return LLMClientCache
+
+ # If they want the singleton instance, create it (only once)
+ if name == "in_memory_llm_clients_cache":
+ instance = LLMClientCache()
+ _globals["in_memory_llm_clients_cache"] = instance
+ return instance
+
+ raise AttributeError(f"LLM client cache lazy import: unknown attribute {name!r}")
+
+
+def _lazy_import_http_handlers(name: str) -> Any:
+ """
+```
+
+This class is important because it defines how LiteLLM Tutorial: Unified LLM Gateway and Routing Layer implements the patterns covered in this chapter.
+
+### `litellm/_lazy_imports.py`
+
+The `So` class in [`litellm/_lazy_imports.py`](https://github.com/BerriAI/litellm/blob/HEAD/litellm/_lazy_imports.py) handles a key part of this chapter's functionality:
+
+```py
+ - "LLMClientCache" is the class itself
+ - "in_memory_llm_clients_cache" is a singleton instance of that class
+ So we need custom logic to handle both cases.
+ """
+ _globals = _get_litellm_globals()
+
+ # If already cached, return it
+ if name in _globals:
+ return _globals[name]
+
+ # Import the class
+ module = importlib.import_module("litellm.caching.llm_caching_handler")
+ LLMClientCache = getattr(module, "LLMClientCache")
+
+ # If they want the class itself, return it
+ if name == "LLMClientCache":
+ _globals["LLMClientCache"] = LLMClientCache
+ return LLMClientCache
+
+ # If they want the singleton instance, create it (only once)
+ if name == "in_memory_llm_clients_cache":
+ instance = LLMClientCache()
+ _globals["in_memory_llm_clients_cache"] = instance
+ return instance
+
+ raise AttributeError(f"LLM client cache lazy import: unknown attribute {name!r}")
+
+
+def _lazy_import_http_handlers(name: str) -> Any:
+ """
+ Handler for HTTP clients - has special logic for creating client instances.
+
+```
+
+This class is important because it defines how LiteLLM Tutorial: Unified LLM Gateway and Routing Layer implements the patterns covered in this chapter.
+
+
+## How These Components Connect
+
+```mermaid
+flowchart TD
+ A[with]
+ B[value]
+ C[itself]
+ D[So]
+ E[module]
+ A --> B
+ B --> C
+ C --> D
+ D --> E
+```
diff --git a/tutorials/litellm-tutorial/02-providers.md b/tutorials/litellm-tutorial/02-providers.md
index 832a3f54..e750cff2 100644
--- a/tutorials/litellm-tutorial/02-providers.md
+++ b/tutorials/litellm-tutorial/02-providers.md
@@ -6,6 +6,7 @@ has_children: false
parent: LiteLLM Tutorial
---
+
# Chapter 2: Provider Configuration
Welcome to **Chapter 2: Provider Configuration**. In this part of **LiteLLM Tutorial: Unified LLM Gateway and Routing Layer**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
@@ -485,149 +486,184 @@ This comprehensive provider configuration gives you the flexibility to use any L
## Depth Expansion Playbook
-<!-- depth-expansion-v2 -->
+## Source Code Walkthrough
+
+### `litellm/anthropic_beta_headers_manager.py`
+
+The `get_beta_headers_config` function in [`litellm/anthropic_beta_headers_manager.py`](https://github.com/BerriAI/litellm/blob/HEAD/litellm/anthropic_beta_headers_manager.py) handles a key part of this chapter's functionality:
+
+```py
+
+
+def get_beta_headers_config(url: str) -> dict:
+ """
+ Public entry point — returns the beta headers config dict.
+
+ 1. If ``LITELLM_LOCAL_ANTHROPIC_BETA_HEADERS`` is set, uses the local backup only.
+ 2. Otherwise fetches from ``url``, validates integrity, and falls back
+ to the local backup on any failure.
+
+ Args:
+ url: URL to fetch the remote beta headers configuration from
+
+ Returns:
+ Dict containing the beta headers configuration
+ """
+ # Check if local-only mode is enabled
+ if os.getenv("LITELLM_LOCAL_ANTHROPIC_BETA_HEADERS", "").lower() == "true":
+ # verbose_logger.debug("Using local Anthropic beta headers config (LITELLM_LOCAL_ANTHROPIC_BETA_HEADERS=True)")
+ return GetAnthropicBetaHeadersConfig.load_local_beta_headers_config()
+
+ try:
+ content = GetAnthropicBetaHeadersConfig.fetch_remote_beta_headers_config(url)
+ except Exception as e:
+ verbose_logger.warning(
+ "LiteLLM: Failed to fetch remote beta headers config from %s: %s. "
+ "Falling back to local backup.",
+ url,
+ str(e),
+ )
+ return GetAnthropicBetaHeadersConfig.load_local_beta_headers_config()
+
+```
+
+This function is important because it defines how LiteLLM Tutorial: Unified LLM Gateway and Routing Layer implements the patterns covered in this chapter.
-This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
+### `litellm/anthropic_beta_headers_manager.py`
-### Strategic Context
+The `reload_beta_headers_config` function in [`litellm/anthropic_beta_headers_manager.py`](https://github.com/BerriAI/litellm/blob/HEAD/litellm/anthropic_beta_headers_manager.py) handles a key part of this chapter's functionality:
-- tutorial: **LiteLLM Tutorial: Unified LLM Gateway and Routing Layer**
-- tutorial slug: **litellm-tutorial**
-- chapter focus: **Chapter 2: Provider Configuration**
-- system context: **Litellm Tutorial**
-- objective: move from surface-level usage to repeatable engineering operation
+```py
-### Architecture Decomposition
-1. Define the runtime boundary for `Chapter 2: Provider Configuration`.
-2. Separate control-plane decisions from data-plane execution.
-3. Capture input contracts, transformation points, and output contracts.
-4. Trace state transitions across request lifecycle stages.
-5. Identify extension hooks and policy interception points.
-6. Map ownership boundaries for team and automation workflows.
-7. Specify rollback and recovery paths for unsafe changes.
-8. Track observability signals for correctness, latency, and cost.
+def reload_beta_headers_config() -> Dict:
+ """
+ Force reload the beta headers configuration from source (remote or local).
+ Clears the cache and fetches fresh configuration.
-### Operator Decision Matrix
+ Returns:
+ Dict containing the newly loaded beta headers configuration
+ """
+ global _BETA_HEADERS_CONFIG
+ _BETA_HEADERS_CONFIG = None
+ verbose_logger.info("Reloading beta headers config (cache cleared)")
+ return _load_beta_headers_config()
-| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
-|:--------------|:--------------|:------------------|:---------|
-| Runtime mode | managed defaults | explicit policy config | speed vs control |
-| State handling | local ephemeral | durable persisted state | simplicity vs auditability |
-| Tool integration | direct API use | mediated adapter layer | velocity vs governance |
-| Rollout method | manual change | staged + canary rollout | effort vs safety |
-| Incident response | best effort logs | runbooks + SLO alerts | cost vs reliability |
-### Failure Modes and Countermeasures
+def get_provider_name(provider: str) -> str:
+ """
+ Resolve provider aliases to canonical provider names.
-| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
-|:-------------|:-------------|:-------------------|:---------------|
-| stale context | inconsistent outputs | missing refresh window | enforce context TTL and refresh hooks |
-| policy drift | unexpected execution | ad hoc overrides | centralize policy profiles |
-| auth mismatch | 401/403 bursts | credential sprawl | rotation schedule + scope minimization |
-| schema breakage | parser/validation errors | unmanaged upstream changes | contract tests per release |
-| retry storms | queue congestion | no backoff controls | jittered backoff + circuit breakers |
-| silent regressions | quality drop without alerts | weak baseline metrics | eval harness with thresholds |
+ Args:
+ provider: Provider name (may be an alias)
-### Implementation Runbook
+ Returns:
+ Canonical provider name
+ """
+ config = _load_beta_headers_config()
+ aliases = config.get("provider_aliases", {})
+ return aliases.get(provider, provider)
-1. Establish a reproducible baseline environment.
-2. Capture chapter-specific success criteria before changes.
-3. Implement minimal viable path with explicit interfaces.
-4. Add observability before expanding feature scope.
-5. Run deterministic tests for happy-path behavior.
-6. Inject failure scenarios for negative-path validation.
-7. Compare output quality against baseline snapshots.
-8. Promote through staged environments with rollback gates.
-9. Record operational lessons in release notes.
-### Quality Gate Checklist
+def filter_and_transform_beta_headers(
+```
-- [ ] chapter-level assumptions are explicit and testable
-- [ ] API/tool boundaries are documented with input/output examples
-- [ ] failure handling includes retry, timeout, and fallback policy
-- [ ] security controls include auth scopes and secret rotation plans
-- [ ] observability includes logs, metrics, traces, and alert thresholds
-- [ ] deployment guidance includes canary and rollback paths
-- [ ] docs include links to upstream sources and related tracks
-- [ ] post-release verification confirms expected behavior under load
+This function is important because it defines how LiteLLM Tutorial: Unified LLM Gateway and Routing Layer implements the patterns covered in this chapter.
-### Source Alignment
+### `litellm/anthropic_beta_headers_manager.py`
-- [LiteLLM Repository](https://github.com/BerriAI/litellm)
-- [LiteLLM Releases](https://github.com/BerriAI/litellm/releases)
-- [LiteLLM Docs](https://docs.litellm.ai/)
+The `get_provider_name` function in [`litellm/anthropic_beta_headers_manager.py`](https://github.com/BerriAI/litellm/blob/HEAD/litellm/anthropic_beta_headers_manager.py) handles a key part of this chapter's functionality:
-### Cross-Tutorial Connection Map
+```py
-- [Langfuse Tutorial](../langfuse-tutorial/)
-- [Vercel AI SDK Tutorial](../vercel-ai-tutorial/)
-- [OpenAI Python SDK Tutorial](../openai-python-sdk-tutorial/)
-- [Aider Tutorial](../aider-tutorial/)
-- [Chapter 1: Getting Started](01-getting-started.md)
-### Advanced Practice Exercises
+def get_provider_name(provider: str) -> str:
+ """
+ Resolve provider aliases to canonical provider names.
-1. Build a minimal end-to-end implementation for `Chapter 2: Provider Configuration`.
-2. Add instrumentation and measure baseline latency and error rate.
-3. Introduce one controlled failure and confirm graceful recovery.
-4. Add policy constraints and verify they are enforced consistently.
-5. Run a staged rollout and document rollback decision criteria.
+ Args:
+ provider: Provider name (may be an alias)
-### Review Questions
+ Returns:
+ Canonical provider name
+ """
+ config = _load_beta_headers_config()
+ aliases = config.get("provider_aliases", {})
+ return aliases.get(provider, provider)
-1. Which execution boundary matters most for this chapter and why?
-2. What signal detects regressions earliest in your environment?
-3. What tradeoff did you make between delivery speed and governance?
-4. How would you recover from the highest-impact failure mode?
-5. What must be automated before scaling to team-wide adoption?
-## What Problem Does This Solve?
+def filter_and_transform_beta_headers(
+ beta_headers: List[str],
+ provider: str,
+) -> List[str]:
+ """
+ Filter and transform beta headers based on provider's mapping configuration.
+
+ This function:
+ 1. Only allows headers that are present in the provider's mapping keys
+ 2. Filters out headers with null values (unsupported)
+ 3. Maps headers to provider-specific names (e.g., advanced-tool-use -> tool-search-tool)
+
+ Args:
+ beta_headers: List of Anthropic beta header values
+ provider: Provider name (e.g., "anthropic", "bedrock", "vertex_ai")
+```
-Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for `model`, `litellm`, `messages` so behavior stays predictable as complexity grows.
+This function is important because it defines how LiteLLM Tutorial: Unified LLM Gateway and Routing Layer implements the patterns covered in this chapter.
-In practical terms, this chapter helps you avoid three common failures:
+### `litellm/anthropic_beta_headers_manager.py`
-- coupling core logic too tightly to one implementation path
-- missing the handoff boundaries between setup, execution, and validation
-- shipping changes without clear rollback or observability strategy
-
-After working through this chapter, you should be able to reason about `Chapter 2: Provider Configuration` as an operating subsystem inside **LiteLLM Tutorial: Unified LLM Gateway and Routing Layer**, with explicit contracts for inputs, state transitions, and outputs.
+The `filter_and_transform_beta_headers` function in [`litellm/anthropic_beta_headers_manager.py`](https://github.com/BerriAI/litellm/blob/HEAD/litellm/anthropic_beta_headers_manager.py) handles a key part of this chapter's functionality:
-Use the implementation notes around `content`, `response`, `getenv` as your checklist when adapting these patterns to your own repository.
+```py
-## How it Works Under the Hood
-Under the hood, `Chapter 2: Provider Configuration` usually follows a repeatable control path:
-
-1. **Context bootstrap**: initialize runtime config and prerequisites for `model`.
-2. **Input normalization**: shape incoming data so `litellm` receives stable contracts.
-3. **Core execution**: run the main logic branch and propagate intermediate state through `messages`.
-4. **Policy and safety checks**: enforce limits, auth scopes, and failure boundaries.
-5. **Output composition**: return canonical result payloads for downstream consumers.
-6. **Operational telemetry**: emit logs/metrics needed for debugging and performance tuning.
+def filter_and_transform_beta_headers(
+ beta_headers: List[str],
+ provider: str,
+) -> List[str]:
+ """
+ Filter and transform beta headers based on provider's mapping configuration.
-When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+ This function:
+ 1. Only allows headers that are present in the provider's mapping keys
+ 2. Filters out headers with null values (unsupported)
+ 3. Maps headers to provider-specific names (e.g., advanced-tool-use -> tool-search-tool)
-## Source Walkthrough
+ Args:
+ beta_headers: List of Anthropic beta header values
+ provider: Provider name (e.g., "anthropic", "bedrock", "vertex_ai")
-Use the following upstream sources to verify implementation details while reading this chapter:
+ Returns:
+ List of filtered and transformed beta headers for the provider
+ """
+ if not beta_headers:
+ return []
-- [LiteLLM Repository](https://github.com/BerriAI/litellm)
- Why it matters: authoritative reference on `LiteLLM Repository` (github.com).
-- [LiteLLM Releases](https://github.com/BerriAI/litellm/releases)
- Why it matters: authoritative reference on `LiteLLM Releases` (github.com).
-- [LiteLLM Docs](https://docs.litellm.ai/)
- Why it matters: authoritative reference on `LiteLLM Docs` (docs.litellm.ai).
+ config = _load_beta_headers_config()
+ provider = get_provider_name(provider)
-Suggested trace strategy:
-- search upstream code for `model` and `litellm` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+ # Get the header mapping for this provider
+ provider_mapping = config.get(provider, {})
-## Chapter Connections
+ filtered_headers: Set[str] = set()
-- [Tutorial Index](README.md)
-- [Previous Chapter: Chapter 1: Getting Started with LiteLLM](01-getting-started.md)
-- [Next Chapter: Chapter 3: Completion API](03-completion.md)
-- [Main Catalog](../../README.md#-tutorial-catalog)
-- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
+```
+
+This function is important because it defines how LiteLLM Tutorial: Unified LLM Gateway and Routing Layer implements the patterns covered in this chapter.
+
+
+## How These Components Connect
+
+```mermaid
+flowchart TD
+ A[get_beta_headers_config]
+ B[reload_beta_headers_config]
+ C[get_provider_name]
+ D[filter_and_transform_beta_headers]
+ E[is_beta_header_supported]
+ A --> B
+ B --> C
+ C --> D
+ D --> E
+```
diff --git a/tutorials/litellm-tutorial/03-completion.md b/tutorials/litellm-tutorial/03-completion.md
index 0f7fc6c6..5b1a0b91 100644
--- a/tutorials/litellm-tutorial/03-completion.md
+++ b/tutorials/litellm-tutorial/03-completion.md
@@ -6,6 +6,7 @@ has_children: false
parent: LiteLLM Tutorial
---
+
# Chapter 3: Completion API
Welcome to **Chapter 3: Completion API**. In this part of **LiteLLM Tutorial: Unified LLM Gateway and Routing Layer**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
@@ -511,149 +512,184 @@ The completion API is your primary interface to LLM capabilities. Mastering thes
## Depth Expansion Playbook
-<!-- depth-expansion-v2 -->
+## Source Code Walkthrough
+
+### `litellm/setup_wizard.py`
+
+The `bold` function in [`litellm/setup_wizard.py`](https://github.com/BerriAI/litellm/blob/HEAD/litellm/setup_wizard.py) handles a key part of this chapter's functionality:
+
+```py
+
+
+def bold(t: str) -> str:
+ return _c(_BOLD, t)
+
+
+def green(t: str) -> str:
+ return _c(_GREEN, t)
+
+
+def blue(t: str) -> str:
+ return _c(_BLUE, t)
+
+
+def grey(t: str) -> str:
+ return _c(_GREY, t)
+
+
+def dim(t: str) -> str:
+ return _c(_DIM, t)
+
+
+def _divider() -> str:
+ """Return a styled divider line (evaluated at call-time, not import-time)."""
+ return dim(" " + "╌" * 74)
+
+
+def _styled_input(prompt: str) -> str:
+ """
+ Like input() but wraps ANSI sequences in readline ignore markers
+ (\\001...\\002) so readline correctly tracks the cursor column.
+ In non-TTY contexts, strips ANSI entirely so no escape codes appear.
+```
+
+This function is important because it defines how LiteLLM Tutorial: Unified LLM Gateway and Routing Layer implements the patterns covered in this chapter.
+
+### `litellm/setup_wizard.py`
+
+The `green` function in [`litellm/setup_wizard.py`](https://github.com/BerriAI/litellm/blob/HEAD/litellm/setup_wizard.py) handles a key part of this chapter's functionality:
+
+```py
+
-This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
+def green(t: str) -> str:
+ return _c(_GREEN, t)
-### Strategic Context
-- tutorial: **LiteLLM Tutorial: Unified LLM Gateway and Routing Layer**
-- tutorial slug: **litellm-tutorial**
-- chapter focus: **Chapter 3: Completion API**
-- system context: **Litellm Tutorial**
-- objective: move from surface-level usage to repeatable engineering operation
+def blue(t: str) -> str:
+ return _c(_BLUE, t)
-### Architecture Decomposition
-1. Define the runtime boundary for `Chapter 3: Completion API`.
-2. Separate control-plane decisions from data-plane execution.
-3. Capture input contracts, transformation points, and output contracts.
-4. Trace state transitions across request lifecycle stages.
-5. Identify extension hooks and policy interception points.
-6. Map ownership boundaries for team and automation workflows.
-7. Specify rollback and recovery paths for unsafe changes.
-8. Track observability signals for correctness, latency, and cost.
+def grey(t: str) -> str:
+ return _c(_GREY, t)
-### Operator Decision Matrix
-| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
-|:--------------|:--------------|:------------------|:---------|
-| Runtime mode | managed defaults | explicit policy config | speed vs control |
-| State handling | local ephemeral | durable persisted state | simplicity vs auditability |
-| Tool integration | direct API use | mediated adapter layer | velocity vs governance |
-| Rollout method | manual change | staged + canary rollout | effort vs safety |
-| Incident response | best effort logs | runbooks + SLO alerts | cost vs reliability |
+def dim(t: str) -> str:
+ return _c(_DIM, t)
-### Failure Modes and Countermeasures
-| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
-|:-------------|:-------------|:-------------------|:---------------|
-| stale context | inconsistent outputs | missing refresh window | enforce context TTL and refresh hooks |
-| policy drift | unexpected execution | ad hoc overrides | centralize policy profiles |
-| auth mismatch | 401/403 bursts | credential sprawl | rotation schedule + scope minimization |
-| schema breakage | parser/validation errors | unmanaged upstream changes | contract tests per release |
-| retry storms | queue congestion | no backoff controls | jittered backoff + circuit breakers |
-| silent regressions | quality drop without alerts | weak baseline metrics | eval harness with thresholds |
+def _divider() -> str:
+ """Return a styled divider line (evaluated at call-time, not import-time)."""
+ return dim(" " + "╌" * 74)
-### Implementation Runbook
-1. Establish a reproducible baseline environment.
-2. Capture chapter-specific success criteria before changes.
-3. Implement minimal viable path with explicit interfaces.
-4. Add observability before expanding feature scope.
-5. Run deterministic tests for happy-path behavior.
-6. Inject failure scenarios for negative-path validation.
-7. Compare output quality against baseline snapshots.
-8. Promote through staged environments with rollback gates.
-9. Record operational lessons in release notes.
+def _styled_input(prompt: str) -> str:
+ """
+ Like input() but wraps ANSI sequences in readline ignore markers
+ (\\001...\\002) so readline correctly tracks the cursor column.
+ In non-TTY contexts, strips ANSI entirely so no escape codes appear.
+ """
+ if sys.stdout.isatty():
+ rl_prompt = _ANSI_RE.sub(lambda m: f"\001{m.group()}\002", prompt)
+ else:
+```
+
+This function is important because it defines how LiteLLM Tutorial: Unified LLM Gateway and Routing Layer implements the patterns covered in this chapter.
+
+### `litellm/setup_wizard.py`
-### Quality Gate Checklist
+The `blue` function in [`litellm/setup_wizard.py`](https://github.com/BerriAI/litellm/blob/HEAD/litellm/setup_wizard.py) handles a key part of this chapter's functionality:
-- [ ] chapter-level assumptions are explicit and testable
-- [ ] API/tool boundaries are documented with input/output examples
-- [ ] failure handling includes retry, timeout, and fallback policy
-- [ ] security controls include auth scopes and secret rotation plans
-- [ ] observability includes logs, metrics, traces, and alert thresholds
-- [ ] deployment guidance includes canary and rollback paths
-- [ ] docs include links to upstream sources and related tracks
-- [ ] post-release verification confirms expected behavior under load
+```py
-### Source Alignment
-- [LiteLLM Repository](https://github.com/BerriAI/litellm)
-- [LiteLLM Releases](https://github.com/BerriAI/litellm/releases)
-- [LiteLLM Docs](https://docs.litellm.ai/)
+def blue(t: str) -> str:
+ return _c(_BLUE, t)
-### Cross-Tutorial Connection Map
-- [Langfuse Tutorial](../langfuse-tutorial/)
-- [Vercel AI SDK Tutorial](../vercel-ai-tutorial/)
-- [OpenAI Python SDK Tutorial](../openai-python-sdk-tutorial/)
-- [Aider Tutorial](../aider-tutorial/)
-- [Chapter 1: Getting Started](01-getting-started.md)
+def grey(t: str) -> str:
+ return _c(_GREY, t)
-### Advanced Practice Exercises
-1. Build a minimal end-to-end implementation for `Chapter 3: Completion API`.
-2. Add instrumentation and measure baseline latency and error rate.
-3. Introduce one controlled failure and confirm graceful recovery.
-4. Add policy constraints and verify they are enforced consistently.
-5. Run a staged rollout and document rollback decision criteria.
+def dim(t: str) -> str:
+ return _c(_DIM, t)
-### Review Questions
-1. Which execution boundary matters most for this chapter and why?
-2. What signal detects regressions earliest in your environment?
-3. What tradeoff did you make between delivery speed and governance?
-4. How would you recover from the highest-impact failure mode?
-5. What must be automated before scaling to team-wide adoption?
+def _divider() -> str:
+ """Return a styled divider line (evaluated at call-time, not import-time)."""
+ return dim(" " + "╌" * 74)
-## What Problem Does This Solve?
-Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for `messages`, `content`, `response` so behavior stays predictable as complexity grows.
+def _styled_input(prompt: str) -> str:
+ """
+ Like input() but wraps ANSI sequences in readline ignore markers
+ (\\001...\\002) so readline correctly tracks the cursor column.
+ In non-TTY contexts, strips ANSI entirely so no escape codes appear.
+ """
+ if sys.stdout.isatty():
+ rl_prompt = _ANSI_RE.sub(lambda m: f"\001{m.group()}\002", prompt)
+ else:
+ rl_prompt = _ANSI_RE.sub("", prompt)
+ return input(rl_prompt).strip()
-In practical terms, this chapter helps you avoid three common failures:
-- coupling core logic too tightly to one implementation path
-- missing the handoff boundaries between setup, execution, and validation
-- shipping changes without clear rollback or observability strategy
-
-After working through this chapter, you should be able to reason about `Chapter 3: Completion API` as an operating subsystem inside **LiteLLM Tutorial: Unified LLM Gateway and Routing Layer**, with explicit contracts for inputs, state transitions, and outputs.
+```
+
+This function is important because it defines how LiteLLM Tutorial: Unified LLM Gateway and Routing Layer implements the patterns covered in this chapter.
-Use the implementation notes around `self`, `role`, `model` as your checklist when adapting these patterns to your own repository.
+### `litellm/setup_wizard.py`
-## How it Works Under the Hood
+The `grey` function in [`litellm/setup_wizard.py`](https://github.com/BerriAI/litellm/blob/HEAD/litellm/setup_wizard.py) handles a key part of this chapter's functionality:
-Under the hood, `Chapter 3: Completion API` usually follows a repeatable control path:
-
-1. **Context bootstrap**: initialize runtime config and prerequisites for `messages`.
-2. **Input normalization**: shape incoming data so `content` receives stable contracts.
-3. **Core execution**: run the main logic branch and propagate intermediate state through `response`.
-4. **Policy and safety checks**: enforce limits, auth scopes, and failure boundaries.
-5. **Output composition**: return canonical result payloads for downstream consumers.
-6. **Operational telemetry**: emit logs/metrics needed for debugging and performance tuning.
+```py
-When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
-## Source Walkthrough
+def grey(t: str) -> str:
+ return _c(_GREY, t)
-Use the following upstream sources to verify implementation details while reading this chapter:
-- [LiteLLM Repository](https://github.com/BerriAI/litellm)
- Why it matters: authoritative reference on `LiteLLM Repository` (github.com).
-- [LiteLLM Releases](https://github.com/BerriAI/litellm/releases)
- Why it matters: authoritative reference on `LiteLLM Releases` (github.com).
-- [LiteLLM Docs](https://docs.litellm.ai/)
- Why it matters: authoritative reference on `LiteLLM Docs` (docs.litellm.ai).
+def dim(t: str) -> str:
+ return _c(_DIM, t)
-Suggested trace strategy:
-- search upstream code for `messages` and `content` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
-## Chapter Connections
+def _divider() -> str:
+ """Return a styled divider line (evaluated at call-time, not import-time)."""
+ return dim(" " + "╌" * 74)
-- [Tutorial Index](README.md)
-- [Previous Chapter: Chapter 2: Provider Configuration](02-providers.md)
-- [Next Chapter: Chapter 4: Streaming & Async](04-streaming.md)
-- [Main Catalog](../../README.md#-tutorial-catalog)
-- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
+
+def _styled_input(prompt: str) -> str:
+ """
+ Like input() but wraps ANSI sequences in readline ignore markers
+ (\\001...\\002) so readline correctly tracks the cursor column.
+ In non-TTY contexts, strips ANSI entirely so no escape codes appear.
+ """
+ if sys.stdout.isatty():
+ rl_prompt = _ANSI_RE.sub(lambda m: f"\001{m.group()}\002", prompt)
+ else:
+ rl_prompt = _ANSI_RE.sub("", prompt)
+ return input(rl_prompt).strip()
+
+
+def _yaml_escape(value: str) -> str:
+ """Escape a string for safe embedding in a double-quoted YAML scalar."""
+ return (
+ value.replace("\\", "\\\\")
+```
+
+This function is important because it defines how LiteLLM Tutorial: Unified LLM Gateway and Routing Layer implements the patterns covered in this chapter.
+
+
+## How These Components Connect
+
+```mermaid
+flowchart TD
+ A[bold]
+ B[green]
+ C[blue]
+ D[grey]
+ E[dim]
+ A --> B
+ B --> C
+ C --> D
+ D --> E
+```
diff --git a/tutorials/litellm-tutorial/04-streaming.md b/tutorials/litellm-tutorial/04-streaming.md
index e20824f9..0b0ef336 100644
--- a/tutorials/litellm-tutorial/04-streaming.md
+++ b/tutorials/litellm-tutorial/04-streaming.md
@@ -6,6 +6,7 @@ has_children: false
parent: LiteLLM Tutorial
---
+
# Chapter 4: Streaming & Async
Welcome to **Chapter 4: Streaming & Async**. In this part of **LiteLLM Tutorial: Unified LLM Gateway and Routing Layer**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
@@ -489,149 +490,184 @@ Streaming and async processing enable responsive, scalable AI applications. Thes
## Depth Expansion Playbook
-<!-- depth-expansion-v2 -->
-
-This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
-
-### Strategic Context
-
-- tutorial: **LiteLLM Tutorial: Unified LLM Gateway and Routing Layer**
-- tutorial slug: **litellm-tutorial**
-- chapter focus: **Chapter 4: Streaming & Async**
-- system context: **Litellm Tutorial**
-- objective: move from surface-level usage to repeatable engineering operation
-
-### Architecture Decomposition
-
-1. Define the runtime boundary for `Chapter 4: Streaming & Async`.
-2. Separate control-plane decisions from data-plane execution.
-3. Capture input contracts, transformation points, and output contracts.
-4. Trace state transitions across request lifecycle stages.
-5. Identify extension hooks and policy interception points.
-6. Map ownership boundaries for team and automation workflows.
-7. Specify rollback and recovery paths for unsafe changes.
-8. Track observability signals for correctness, latency, and cost.
-
-### Operator Decision Matrix
-
-| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
-|:--------------|:--------------|:------------------|:---------|
-| Runtime mode | managed defaults | explicit policy config | speed vs control |
-| State handling | local ephemeral | durable persisted state | simplicity vs auditability |
-| Tool integration | direct API use | mediated adapter layer | velocity vs governance |
-| Rollout method | manual change | staged + canary rollout | effort vs safety |
-| Incident response | best effort logs | runbooks + SLO alerts | cost vs reliability |
-
-### Failure Modes and Countermeasures
-
-| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
-|:-------------|:-------------|:-------------------|:---------------|
-| stale context | inconsistent outputs | missing refresh window | enforce context TTL and refresh hooks |
-| policy drift | unexpected execution | ad hoc overrides | centralize policy profiles |
-| auth mismatch | 401/403 bursts | credential sprawl | rotation schedule + scope minimization |
-| schema breakage | parser/validation errors | unmanaged upstream changes | contract tests per release |
-| retry storms | queue congestion | no backoff controls | jittered backoff + circuit breakers |
-| silent regressions | quality drop without alerts | weak baseline metrics | eval harness with thresholds |
-
-### Implementation Runbook
-
-1. Establish a reproducible baseline environment.
-2. Capture chapter-specific success criteria before changes.
-3. Implement minimal viable path with explicit interfaces.
-4. Add observability before expanding feature scope.
-5. Run deterministic tests for happy-path behavior.
-6. Inject failure scenarios for negative-path validation.
-7. Compare output quality against baseline snapshots.
-8. Promote through staged environments with rollback gates.
-9. Record operational lessons in release notes.
-
-### Quality Gate Checklist
-
-- [ ] chapter-level assumptions are explicit and testable
-- [ ] API/tool boundaries are documented with input/output examples
-- [ ] failure handling includes retry, timeout, and fallback policy
-- [ ] security controls include auth scopes and secret rotation plans
-- [ ] observability includes logs, metrics, traces, and alert thresholds
-- [ ] deployment guidance includes canary and rollback paths
-- [ ] docs include links to upstream sources and related tracks
-- [ ] post-release verification confirms expected behavior under load
-
-### Source Alignment
-
-- [LiteLLM Repository](https://github.com/BerriAI/litellm)
-- [LiteLLM Releases](https://github.com/BerriAI/litellm/releases)
-- [LiteLLM Docs](https://docs.litellm.ai/)
-
-### Cross-Tutorial Connection Map
-
-- [Langfuse Tutorial](../langfuse-tutorial/)
-- [Vercel AI SDK Tutorial](../vercel-ai-tutorial/)
-- [OpenAI Python SDK Tutorial](../openai-python-sdk-tutorial/)
-- [Aider Tutorial](../aider-tutorial/)
-- [Chapter 1: Getting Started](01-getting-started.md)
-
-### Advanced Practice Exercises
-
-1. Build a minimal end-to-end implementation for `Chapter 4: Streaming & Async`.
-2. Add instrumentation and measure baseline latency and error rate.
-3. Introduce one controlled failure and confirm graceful recovery.
-4. Add policy constraints and verify they are enforced consistently.
-5. Run a staged rollout and document rollback decision criteria.
-
-### Review Questions
-
-1. Which execution boundary matters most for this chapter and why?
-2. What signal detects regressions earliest in your environment?
-3. What tradeoff did you make between delivery speed and governance?
-4. How would you recover from the highest-impact failure mode?
-5. What must be automated before scaling to team-wide adoption?
-
-## What Problem Does This Solve?
-
-Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for `content`, `messages`, `chunk` so behavior stays predictable as complexity grows.
-
-In practical terms, this chapter helps you avoid three common failures:
-
-- coupling core logic too tightly to one implementation path
-- missing the handoff boundaries between setup, execution, and validation
-- shipping changes without clear rollback or observability strategy
-
-After working through this chapter, you should be able to reason about `Chapter 4: Streaming & Async` as an operating subsystem inside **LiteLLM Tutorial: Unified LLM Gateway and Routing Layer**, with explicit contracts for inputs, state transitions, and outputs.
-
-Use the implementation notes around `print`, `response`, `model` as your checklist when adapting these patterns to your own repository.
-
-## How it Works Under the Hood
-
-Under the hood, `Chapter 4: Streaming & Async` usually follows a repeatable control path:
-
-1. **Context bootstrap**: initialize runtime config and prerequisites for `content`.
-2. **Input normalization**: shape incoming data so `messages` receives stable contracts.
-3. **Core execution**: run the main logic branch and propagate intermediate state through `chunk`.
-4. **Policy and safety checks**: enforce limits, auth scopes, and failure boundaries.
-5. **Output composition**: return canonical result payloads for downstream consumers.
-6. **Operational telemetry**: emit logs/metrics needed for debugging and performance tuning.
+## Source Code Walkthrough
+
+### `scripts/benchmark_proxy_vs_provider.py`
+
+The `print_results` function in [`scripts/benchmark_proxy_vs_provider.py`](https://github.com/BerriAI/litellm/blob/HEAD/scripts/benchmark_proxy_vs_provider.py) handles a key part of this chapter's functionality:
+
+```py
+
+
+def print_results(name: str, results: BenchmarkResults):
+ """Print formatted benchmark results"""
+ stats = results.calculate_stats()
+
+ print(f"\n{'='*60}")
+ print(f"Results for {name}")
+ print(f"{'='*60}")
+ print(f"Total Requests: {stats['total_requests']}")
+ print(f"Successful Requests: {stats['successful_requests']}")
+ print(f"Failed Requests: {stats['failed_requests']}")
+ print(f"Success Rate: {stats['success_rate']:.2f}%")
+ print(f"Error Rate: {stats['error_rate']:.2f}%")
+ print(f"Total Time: {stats['total_time']:.2f}s")
+ print(f"Requests/Second: {stats['requests_per_second']:.2f}")
+
+ if 'latency_stats' in stats:
+ latency = stats['latency_stats']
+ print(f"\nLatency Statistics (seconds):")
+ print(f" Mean: {latency['mean']:.4f}s")
+ print(f" Median (p50): {latency['median']:.4f}s")
+ print(f" Min: {latency['min']:.4f}s")
+ print(f" Max: {latency['max']:.4f}s")
+ print(f" Std Dev: {latency['std_dev']:.4f}s")
+ print(f" p95: {latency['p95']:.4f}s")
+ print(f" p99: {latency['p99']:.4f}s")
+
+ if stats['status_codes']:
+ print(f"\nStatus Codes:")
+ for code, count in sorted(stats['status_codes'].items()):
+ print(f" {code}: {count}")
+```
-When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+This function is important because it defines how LiteLLM Tutorial: Unified LLM Gateway and Routing Layer implements the patterns covered in this chapter.
+
+### `scripts/benchmark_proxy_vs_provider.py`
+
+The `aggregate_results` function in [`scripts/benchmark_proxy_vs_provider.py`](https://github.com/BerriAI/litellm/blob/HEAD/scripts/benchmark_proxy_vs_provider.py) handles a key part of this chapter's functionality:
+
+```py
+
+
+def aggregate_results(results_list: List[BenchmarkResults]) -> BenchmarkResults:
+ """Aggregate results from multiple runs"""
+ if not results_list:
+ return BenchmarkResults()
+
+ aggregated = BenchmarkResults()
+
+ # Aggregate all latencies
+ all_latencies = []
+ all_errors = []
+ total_requests = 0
+ total_successful = 0
+ total_failed = 0
+ total_time_sum = 0.0
+ status_codes_combined = {}
+
+ for result in results_list:
+ all_latencies.extend(result.latencies)
+ all_errors.extend(result.errors)
+ total_requests += result.total_requests
+ total_successful += result.successful_requests
+ total_failed += result.failed_requests
+ total_time_sum += result.total_time
+
+ for code, count in result.status_codes.items():
+ status_codes_combined[code] = status_codes_combined.get(code, 0) + count
+
+ aggregated.latencies = all_latencies
+ aggregated.errors = all_errors
+ aggregated.total_requests = total_requests
+```
-## Source Walkthrough
+This function is important because it defines how LiteLLM Tutorial: Unified LLM Gateway and Routing Layer implements the patterns covered in this chapter.
+
+### `scripts/benchmark_proxy_vs_provider.py`
+
+The `print_run_variance` function in [`scripts/benchmark_proxy_vs_provider.py`](https://github.com/BerriAI/litellm/blob/HEAD/scripts/benchmark_proxy_vs_provider.py) handles a key part of this chapter's functionality:
+
+```py
+
+
+def print_run_variance(name: str, results_list: List[BenchmarkResults]):
+ """Print variance statistics across multiple runs"""
+ if len(results_list) <= 1:
+ return
+
+ print(f"\n{'='*60}")
+ print(f"Run-to-Run Variance: {name}")
+ print(f"{'='*60}")
+
+ # Collect mean latencies from each run
+ mean_latencies = []
+ throughputs = []
+
+ for result in results_list:
+ stats = result.calculate_stats()
+ if 'latency_stats' in stats:
+ mean_latencies.append(stats['latency_stats']['mean'])
+ throughputs.append(stats['requests_per_second'])
+
+ if mean_latencies:
+ print(f"\nMean Latency Variance:")
+ print(f" Runs: {len(mean_latencies)}")
+ print(f" Mean: {mean(mean_latencies):.4f}s")
+ print(f" Min: {min(mean_latencies):.4f}s")
+ print(f" Max: {max(mean_latencies):.4f}s")
+ print(f" Std Dev: {stdev(mean_latencies):.4f}s" if len(mean_latencies) > 1 else " Std Dev: N/A")
+ print(f" Coefficient of Variation: {(stdev(mean_latencies) / mean(mean_latencies) * 100):.2f}%" if len(mean_latencies) > 1 else " Coefficient of Variation: N/A")
+
+ if throughputs:
+ print(f"\nThroughput Variance:")
+```
-Use the following upstream sources to verify implementation details while reading this chapter:
+This function is important because it defines how LiteLLM Tutorial: Unified LLM Gateway and Routing Layer implements the patterns covered in this chapter.
+
+### `scripts/benchmark_proxy_vs_provider.py`
+
+The `compare_results` function in [`scripts/benchmark_proxy_vs_provider.py`](https://github.com/BerriAI/litellm/blob/HEAD/scripts/benchmark_proxy_vs_provider.py) handles a key part of this chapter's functionality:
+
+```py
+
+
+def compare_results(proxy_results: BenchmarkResults, provider_results: BenchmarkResults):
+ """Compare and print differences between proxy and provider results"""
+ proxy_stats = proxy_results.calculate_stats()
+ provider_stats = provider_results.calculate_stats()
+
+ print(f"\n{'='*60}")
+ print(f"Comparison: LiteLLM Proxy vs Direct Provider")
+ print(f"{'='*60}")
+
+ # Success Rate Comparison
+ print(f"\nSuccess Rate:")
+ print(f" Proxy: {proxy_stats['success_rate']:.2f}%")
+ print(f" Provider: {provider_stats['success_rate']:.2f}%")
+ diff = proxy_stats['success_rate'] - provider_stats['success_rate']
+ print(f" Difference: {diff:+.2f}%")
+
+ # Throughput Comparison
+ print(f"\nThroughput (requests/second):")
+ print(f" Proxy: {proxy_stats['requests_per_second']:.2f}")
+ print(f" Provider: {provider_stats['requests_per_second']:.2f}")
+ diff = proxy_stats['requests_per_second'] - provider_stats['requests_per_second']
+ print(f" Difference: {diff:+.2f} req/s")
+
+ # Latency Comparison
+ if 'latency_stats' in proxy_stats and 'latency_stats' in provider_stats:
+ print(f"\nLatency Comparison (seconds):")
+ proxy_latency = proxy_stats['latency_stats']
+ provider_latency = provider_stats['latency_stats']
+
+ metrics = ['mean', 'median', 'p95', 'p99']
+```
-- [LiteLLM Repository](https://github.com/BerriAI/litellm)
- Why it matters: authoritative reference on `LiteLLM Repository` (github.com).
-- [LiteLLM Releases](https://github.com/BerriAI/litellm/releases)
- Why it matters: authoritative reference on `LiteLLM Releases` (github.com).
-- [LiteLLM Docs](https://docs.litellm.ai/)
- Why it matters: authoritative reference on `LiteLLM Docs` (docs.litellm.ai).
+This function is important because it defines how LiteLLM Tutorial: Unified LLM Gateway and Routing Layer implements the patterns covered in this chapter.
-Suggested trace strategy:
-- search upstream code for `content` and `messages` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
-## Chapter Connections
+## How These Components Connect
-- [Tutorial Index](README.md)
-- [Previous Chapter: Chapter 3: Completion API](03-completion.md)
-- [Next Chapter: Chapter 5: Fallbacks & Retries](05-fallbacks.md)
-- [Main Catalog](../../README.md#-tutorial-catalog)
-- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
+```mermaid
+flowchart TD
+ A[print_results]
+ B[aggregate_results]
+ C[print_run_variance]
+ D[compare_results]
+ E[main]
+ A --> B
+ B --> C
+ C --> D
+ D --> E
+```
diff --git a/tutorials/litellm-tutorial/05-fallbacks.md b/tutorials/litellm-tutorial/05-fallbacks.md
index d5fc3123..69cdb120 100644
--- a/tutorials/litellm-tutorial/05-fallbacks.md
+++ b/tutorials/litellm-tutorial/05-fallbacks.md
@@ -6,6 +6,7 @@ has_children: false
parent: LiteLLM Tutorial
---
+
# Chapter 5: Fallbacks & Retries
Welcome to **Chapter 5: Fallbacks & Retries**. In this part of **LiteLLM Tutorial: Unified LLM Gateway and Routing Layer**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
@@ -535,149 +536,184 @@ These resilience patterns ensure your AI applications remain reliable and availa
## Depth Expansion Playbook
-<!-- depth-expansion-v2 -->
-
-This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
-
-### Strategic Context
-
-- tutorial: **LiteLLM Tutorial: Unified LLM Gateway and Routing Layer**
-- tutorial slug: **litellm-tutorial**
-- chapter focus: **Chapter 5: Fallbacks & Retries**
-- system context: **Litellm Tutorial**
-- objective: move from surface-level usage to repeatable engineering operation
-
-### Architecture Decomposition
-
-1. Define the runtime boundary for `Chapter 5: Fallbacks & Retries`.
-2. Separate control-plane decisions from data-plane execution.
-3. Capture input contracts, transformation points, and output contracts.
-4. Trace state transitions across request lifecycle stages.
-5. Identify extension hooks and policy interception points.
-6. Map ownership boundaries for team and automation workflows.
-7. Specify rollback and recovery paths for unsafe changes.
-8. Track observability signals for correctness, latency, and cost.
-
-### Operator Decision Matrix
-
-| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
-|:--------------|:--------------|:------------------|:---------|
-| Runtime mode | managed defaults | explicit policy config | speed vs control |
-| State handling | local ephemeral | durable persisted state | simplicity vs auditability |
-| Tool integration | direct API use | mediated adapter layer | velocity vs governance |
-| Rollout method | manual change | staged + canary rollout | effort vs safety |
-| Incident response | best effort logs | runbooks + SLO alerts | cost vs reliability |
-
-### Failure Modes and Countermeasures
-
-| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
-|:-------------|:-------------|:-------------------|:---------------|
-| stale context | inconsistent outputs | missing refresh window | enforce context TTL and refresh hooks |
-| policy drift | unexpected execution | ad hoc overrides | centralize policy profiles |
-| auth mismatch | 401/403 bursts | credential sprawl | rotation schedule + scope minimization |
-| schema breakage | parser/validation errors | unmanaged upstream changes | contract tests per release |
-| retry storms | queue congestion | no backoff controls | jittered backoff + circuit breakers |
-| silent regressions | quality drop without alerts | weak baseline metrics | eval harness with thresholds |
-
-### Implementation Runbook
-
-1. Establish a reproducible baseline environment.
-2. Capture chapter-specific success criteria before changes.
-3. Implement minimal viable path with explicit interfaces.
-4. Add observability before expanding feature scope.
-5. Run deterministic tests for happy-path behavior.
-6. Inject failure scenarios for negative-path validation.
-7. Compare output quality against baseline snapshots.
-8. Promote through staged environments with rollback gates.
-9. Record operational lessons in release notes.
-
-### Quality Gate Checklist
-
-- [ ] chapter-level assumptions are explicit and testable
-- [ ] API/tool boundaries are documented with input/output examples
-- [ ] failure handling includes retry, timeout, and fallback policy
-- [ ] security controls include auth scopes and secret rotation plans
-- [ ] observability includes logs, metrics, traces, and alert thresholds
-- [ ] deployment guidance includes canary and rollback paths
-- [ ] docs include links to upstream sources and related tracks
-- [ ] post-release verification confirms expected behavior under load
-
-### Source Alignment
-
-- [LiteLLM Repository](https://github.com/BerriAI/litellm)
-- [LiteLLM Releases](https://github.com/BerriAI/litellm/releases)
-- [LiteLLM Docs](https://docs.litellm.ai/)
-
-### Cross-Tutorial Connection Map
-
-- [Langfuse Tutorial](../langfuse-tutorial/)
-- [Vercel AI SDK Tutorial](../vercel-ai-tutorial/)
-- [OpenAI Python SDK Tutorial](../openai-python-sdk-tutorial/)
-- [Aider Tutorial](../aider-tutorial/)
-- [Chapter 1: Getting Started](01-getting-started.md)
-
-### Advanced Practice Exercises
-
-1. Build a minimal end-to-end implementation for `Chapter 5: Fallbacks & Retries`.
-2. Add instrumentation and measure baseline latency and error rate.
-3. Introduce one controlled failure and confirm graceful recovery.
-4. Add policy constraints and verify they are enforced consistently.
-5. Run a staged rollout and document rollback decision criteria.
-
-### Review Questions
-
-1. Which execution boundary matters most for this chapter and why?
-2. What signal detects regressions earliest in your environment?
-3. What tradeoff did you make between delivery speed and governance?
-4. How would you recover from the highest-impact failure mode?
-5. What must be automated before scaling to team-wide adoption?
-
-## What Problem Does This Solve?
-
-Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for `self`, `model`, `messages` so behavior stays predictable as complexity grows.
-
-In practical terms, this chapter helps you avoid three common failures:
-
-- coupling core logic too tightly to one implementation path
-- missing the handoff boundaries between setup, execution, and validation
-- shipping changes without clear rollback or observability strategy
-
-After working through this chapter, you should be able to reason about `Chapter 5: Fallbacks & Retries` as an operating subsystem inside **LiteLLM Tutorial: Unified LLM Gateway and Routing Layer**, with explicit contracts for inputs, state transitions, and outputs.
-
-Use the implementation notes around `models`, `response`, `claude` as your checklist when adapting these patterns to your own repository.
-
-## How it Works Under the Hood
-
-Under the hood, `Chapter 5: Fallbacks & Retries` usually follows a repeatable control path:
-
-1. **Context bootstrap**: initialize runtime config and prerequisites for `self`.
-2. **Input normalization**: shape incoming data so `model` receives stable contracts.
-3. **Core execution**: run the main logic branch and propagate intermediate state through `messages`.
-4. **Policy and safety checks**: enforce limits, auth scopes, and failure boundaries.
-5. **Output composition**: return canonical result payloads for downstream consumers.
-6. **Operational telemetry**: emit logs/metrics needed for debugging and performance tuning.
+## Source Code Walkthrough
+
+### `litellm/exceptions.py`
+
+The `AuthenticationError` class in [`litellm/exceptions.py`](https://github.com/BerriAI/litellm/blob/HEAD/litellm/exceptions.py) handles a key part of this chapter's functionality:
+
+```py
+
+
+class AuthenticationError(openai.AuthenticationError): # type: ignore
+ def __init__(
+ self,
+ message,
+ llm_provider,
+ model,
+ response: Optional[httpx.Response] = None,
+ litellm_debug_info: Optional[str] = None,
+ max_retries: Optional[int] = None,
+ num_retries: Optional[int] = None,
+ ):
+ self.status_code = 401
+ self.message = "litellm.AuthenticationError: {}".format(message)
+ self.llm_provider = llm_provider
+ self.model = model
+ self.litellm_debug_info = litellm_debug_info
+ self.max_retries = max_retries
+ self.num_retries = num_retries
+ self.response = response or httpx.Response(
+ status_code=self.status_code,
+ request=httpx.Request(
+ method="GET", url="https://litellm.ai"
+ ), # mock request object
+ )
+ super().__init__(
+ self.message, response=self.response, body=None
+ ) # Call the base class constructor with the parameters it needs
+
+ def __str__(self):
+ _message = self.message
+```
-When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+This class is important because it defines how LiteLLM Tutorial: Unified LLM Gateway and Routing Layer implements the patterns covered in this chapter.
+
+### `litellm/exceptions.py`
+
+The `constructor` class in [`litellm/exceptions.py`](https://github.com/BerriAI/litellm/blob/HEAD/litellm/exceptions.py) handles a key part of this chapter's functionality:
+
+```py
+ super().__init__(
+ self.message, response=self.response, body=None
+ ) # Call the base class constructor with the parameters it needs
+
+ def __str__(self):
+ _message = self.message
+ if self.num_retries:
+ _message += f" LiteLLM Retried: {self.num_retries} times"
+ if self.max_retries:
+ _message += f", LiteLLM Max Retries: {self.max_retries}"
+ return _message
+
+ def __repr__(self):
+ _message = self.message
+ if self.num_retries:
+ _message += f" LiteLLM Retried: {self.num_retries} times"
+ if self.max_retries:
+ _message += f", LiteLLM Max Retries: {self.max_retries}"
+ return _message
+
+
+# raise when invalid models passed, example gpt-8
+class NotFoundError(openai.NotFoundError): # type: ignore
+ def __init__(
+ self,
+ message,
+ model,
+ llm_provider,
+ response: Optional[httpx.Response] = None,
+ litellm_debug_info: Optional[str] = None,
+ max_retries: Optional[int] = None,
+ num_retries: Optional[int] = None,
+```
-## Source Walkthrough
+This class is important because it defines how LiteLLM Tutorial: Unified LLM Gateway and Routing Layer implements the patterns covered in this chapter.
+
+### `litellm/exceptions.py`
+
+The `NotFoundError` class in [`litellm/exceptions.py`](https://github.com/BerriAI/litellm/blob/HEAD/litellm/exceptions.py) handles a key part of this chapter's functionality:
+
+```py
+
+# raise when invalid models passed, example gpt-8
+class NotFoundError(openai.NotFoundError): # type: ignore
+ def __init__(
+ self,
+ message,
+ model,
+ llm_provider,
+ response: Optional[httpx.Response] = None,
+ litellm_debug_info: Optional[str] = None,
+ max_retries: Optional[int] = None,
+ num_retries: Optional[int] = None,
+ ):
+ self.status_code = 404
+ self.message = "litellm.NotFoundError: {}".format(message)
+ self.model = model
+ self.llm_provider = llm_provider
+ self.litellm_debug_info = litellm_debug_info
+ self.max_retries = max_retries
+ self.num_retries = num_retries
+ self.response = response or httpx.Response(
+ status_code=self.status_code,
+ request=httpx.Request(
+ method="GET", url="https://litellm.ai"
+ ), # mock request object
+ )
+ super().__init__(
+ self.message, response=self.response, body=None
+ ) # Call the base class constructor with the parameters it needs
+
+ def __str__(self):
+ _message = self.message
+```
-Use the following upstream sources to verify implementation details while reading this chapter:
+This class is important because it defines how LiteLLM Tutorial: Unified LLM Gateway and Routing Layer implements the patterns covered in this chapter.
+
+### `litellm/exceptions.py`
+
+The `constructor` class in [`litellm/exceptions.py`](https://github.com/BerriAI/litellm/blob/HEAD/litellm/exceptions.py) handles a key part of this chapter's functionality:
+
+```py
+ super().__init__(
+ self.message, response=self.response, body=None
+ ) # Call the base class constructor with the parameters it needs
+
+ def __str__(self):
+ _message = self.message
+ if self.num_retries:
+ _message += f" LiteLLM Retried: {self.num_retries} times"
+ if self.max_retries:
+ _message += f", LiteLLM Max Retries: {self.max_retries}"
+ return _message
+
+ def __repr__(self):
+ _message = self.message
+ if self.num_retries:
+ _message += f" LiteLLM Retried: {self.num_retries} times"
+ if self.max_retries:
+ _message += f", LiteLLM Max Retries: {self.max_retries}"
+ return _message
+
+
+# raise when invalid models passed, example gpt-8
+class NotFoundError(openai.NotFoundError): # type: ignore
+ def __init__(
+ self,
+ message,
+ model,
+ llm_provider,
+ response: Optional[httpx.Response] = None,
+ litellm_debug_info: Optional[str] = None,
+ max_retries: Optional[int] = None,
+ num_retries: Optional[int] = None,
+```
-- [LiteLLM Repository](https://github.com/BerriAI/litellm)
- Why it matters: authoritative reference on `LiteLLM Repository` (github.com).
-- [LiteLLM Releases](https://github.com/BerriAI/litellm/releases)
- Why it matters: authoritative reference on `LiteLLM Releases` (github.com).
-- [LiteLLM Docs](https://docs.litellm.ai/)
- Why it matters: authoritative reference on `LiteLLM Docs` (docs.litellm.ai).
+This class is important because it defines how LiteLLM Tutorial: Unified LLM Gateway and Routing Layer implements the patterns covered in this chapter.
-Suggested trace strategy:
-- search upstream code for `self` and `model` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
-## Chapter Connections
+## How These Components Connect
-- [Tutorial Index](README.md)
-- [Previous Chapter: Chapter 4: Streaming & Async](04-streaming.md)
-- [Next Chapter: Chapter 6: Cost Tracking](06-cost-tracking.md)
-- [Main Catalog](../../README.md#-tutorial-catalog)
-- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
+```mermaid
+flowchart TD
+ A[AuthenticationError]
+ B[constructor]
+ C[NotFoundError]
+ D[constructor]
+ E[BadRequestError]
+ A --> B
+ B --> C
+ C --> D
+ D --> E
+```
diff --git a/tutorials/litellm-tutorial/06-cost-tracking.md b/tutorials/litellm-tutorial/06-cost-tracking.md
index ede78ae1..0d2cd53b 100644
--- a/tutorials/litellm-tutorial/06-cost-tracking.md
+++ b/tutorials/litellm-tutorial/06-cost-tracking.md
@@ -13,6 +13,19 @@ Welcome to **Chapter 6: Cost Tracking**. In this part of **LiteLLM Tutorial: Uni
> Monitor, analyze, and optimize your LLM spending across all providers with detailed cost insights.
+## Cost Tracking Architecture
+
+```mermaid
+flowchart LR
+ REQ[LLM Request] --> LITE[LiteLLM]
+ LITE --> PROV[Provider API\nOpenAI / Anthropic / etc.]
+ PROV --> RESP[Response + Usage]
+ RESP --> CALC[litellm.completion_cost\nprice per token lookup]
+ CALC --> LOG[Cost Logger\ncallback: success_callback]
+ LOG --> DB[(Cost Database\nSQLite / Postgres)]
+ LOG --> DASH[Dashboard / Alerts]
+```
+
## Overview
Understanding and controlling costs is crucial for production LLM applications. LiteLLM provides comprehensive cost tracking that works across all providers, giving you detailed insights into your spending patterns.
diff --git a/tutorials/litellm-tutorial/07-proxy.md b/tutorials/litellm-tutorial/07-proxy.md
index b6d589ad..23505aa7 100644
--- a/tutorials/litellm-tutorial/07-proxy.md
+++ b/tutorials/litellm-tutorial/07-proxy.md
@@ -13,6 +13,19 @@ Welcome to **Chapter 7: LiteLLM Proxy**. In this part of **LiteLLM Tutorial: Uni
> Deploy a centralized OpenAI-compatible proxy server that routes requests to multiple LLM providers with unified authentication, rate limiting, and cost tracking.
+## LiteLLM Proxy Architecture
+
+```mermaid
+flowchart LR
+ CLIENTS[Apps / Teams\nOpenAI SDK] -->|Virtual Key auth| PROXY[LiteLLM Proxy Server\nlitellm --config config.yaml]
+ PROXY --> RL[Rate Limiting\nper-key or global]
+ PROXY --> ROUTE[Router / Load Balancer\nmodel aliases]
+ ROUTE --> P1[OpenAI GPT-4]
+ ROUTE --> P2[Anthropic Claude]
+ ROUTE --> P3[Azure OpenAI]
+ PROXY --> DB[(Postgres\nvirtual keys + spend)]
+```
+
## Overview
The LiteLLM Proxy provides a single endpoint that accepts OpenAI API calls and routes them to any configured LLM provider. This enables easy integration with existing applications while providing enterprise features like authentication, rate limiting, and cost tracking.
diff --git a/tutorials/litellm-tutorial/08-production.md b/tutorials/litellm-tutorial/08-production.md
index 05ac9f95..8c2369a5 100644
--- a/tutorials/litellm-tutorial/08-production.md
+++ b/tutorials/litellm-tutorial/08-production.md
@@ -13,6 +13,22 @@ Welcome to **Chapter 8: Production Deployment**. In this part of **LiteLLM Tutor
> Deploy LiteLLM applications to production with monitoring, scaling, security, and operational best practices.
+## Production Deployment Model
+
+```mermaid
+flowchart TD
+ LB[Load Balancer] --> P1[LiteLLM Proxy Instance 1]
+ LB --> P2[LiteLLM Proxy Instance 2]
+ P1 --> DB[(Postgres: keys + spend)]
+ P2 --> DB
+ P1 --> REDIS[(Redis: rate limit cache)]
+ P2 --> REDIS
+ P1 --> PROV[LLM Providers]
+ P2 --> PROV
+ P1 --> OBS[Observability\nPrometheus / Langfuse]
+ P2 --> OBS
+```
+
## Overview
Production deployment of LiteLLM requires careful consideration of performance, reliability, security, and cost management. This chapter covers comprehensive production patterns for both direct LiteLLM usage and proxy deployments.
diff --git a/tutorials/llama-cpp-tutorial/01-getting-started.md b/tutorials/llama-cpp-tutorial/01-getting-started.md
index a59fb2a5..2d7bba28 100644
--- a/tutorials/llama-cpp-tutorial/01-getting-started.md
+++ b/tutorials/llama-cpp-tutorial/01-getting-started.md
@@ -13,6 +13,23 @@ Welcome to **Chapter 1: Getting Started with llama.cpp**. In this part of **llam
> Build llama.cpp from source and run your first LLM locally with optimized C/C++ inference.
+## Getting Started Flow
+
+```mermaid
+flowchart TD
+ A[Clone ggerganov/llama.cpp] --> B[Install Build Dependencies\ncmake + compiler]
+ B --> C{Platform}
+ C -->|macOS| D[cmake -DLLAMA_METAL=ON]
+ C -->|Linux| E[cmake -DLLAMA_CUDA=ON or CPU]
+ C -->|Windows| F[cmake -G Visual Studio]
+ D --> G[Build: cmake --build build]
+ E --> G
+ F --> G
+ G --> H[Download GGUF Model]
+ H --> I[Run llama-cli -m model.gguf]
+ I --> J[Local Inference Output]
+```
+
## Overview
llama.cpp enables fast, local LLM inference without Python dependencies. This chapter covers building the project and running your first model on CPU.
@@ -346,16 +363,13 @@ When debugging, walk this sequence in order and confirm each stage has explicit
## Source Walkthrough
-Use the following upstream sources to verify implementation details while reading this chapter:
+Key source files in [`ggerganov/llama.cpp`](https://github.com/ggerganov/llama.cpp):
-- [View Repo](https://github.com/ggerganov/llama.cpp)
- Why it matters: authoritative reference on `View Repo` (github.com).
-- [Awesome Code Docs](https://github.com/johnxie/awesome-code-docs)
- Why it matters: authoritative reference on `Awesome Code Docs` (github.com).
+- [`CMakeLists.txt`](https://github.com/ggerganov/llama.cpp/blob/master/CMakeLists.txt) -- CMake build system; see `GGML_METAL`, `GGML_CUDA`, `GGML_HIPBLAS` option flags
+- [`examples/main/main.cpp`](https://github.com/ggerganov/llama.cpp/blob/master/examples/main/main.cpp) -- `llama-cli` entry point; argument parsing and inference loop
+- [`llama.h`](https://github.com/ggerganov/llama.cpp/blob/master/llama.h) -- public C API: `llama_model_load_from_file`, `llama_new_context_with_model`, `llama_decode`
-Suggested trace strategy:
-- search upstream code for `llama` and `model` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+Suggested trace: follow `llama_model_load_from_file()` → `llama_new_context_with_model()` → `llama_decode()` to understand the model loading and inference pipeline.
## Chapter Connections
diff --git a/tutorials/llama-cpp-tutorial/02-model-formats.md b/tutorials/llama-cpp-tutorial/02-model-formats.md
index b67548c2..6fbfa97c 100644
--- a/tutorials/llama-cpp-tutorial/02-model-formats.md
+++ b/tutorials/llama-cpp-tutorial/02-model-formats.md
@@ -13,6 +13,28 @@ Welcome to **Chapter 2: Model Formats and GGUF**. In this part of **llama.cpp Tu
> Understand GGUF format, quantization levels, and how to choose the right model for your hardware.
+## GGUF Format and Quantization Overview
+
+```mermaid
+flowchart LR
+ A[Original Model\nPyTorch FP32/FP16] --> B[convert_hf_to_gguf.py]
+ B --> C[GGUF Base File\nF16 or F32]
+ C --> D[llama-quantize]
+ D --> E1[Q2_K - 2bit smallest]
+ D --> E2[Q4_K_M - 4bit balanced]
+ D --> E3[Q5_K_M - 5bit quality]
+ D --> E4[Q8_0 - 8bit near-lossless]
+ D --> E5[F16 - full precision]
+
+ classDef source fill:#e1f5fe,stroke:#01579b
+ classDef tool fill:#f3e5f5,stroke:#4a148c
+ classDef output fill:#e8f5e9,stroke:#1b5e20
+
+ class A source
+ class B,D tool
+ class C,E1,E2,E3,E4,E5 output
+```
+
## Overview
llama.cpp uses the GGUF format for models. This chapter explains what GGUF is, different quantization options, and how to select models that fit your hardware constraints.
@@ -373,16 +395,13 @@ When debugging, walk this sequence in order and confirm each stage has explicit
## Source Walkthrough
-Use the following upstream sources to verify implementation details while reading this chapter:
+Key source files in [`ggerganov/llama.cpp`](https://github.com/ggerganov/llama.cpp):
-- [View Repo](https://github.com/ggerganov/llama.cpp)
- Why it matters: authoritative reference on `View Repo` (github.com).
-- [Awesome Code Docs](https://github.com/johnxie/awesome-code-docs)
- Why it matters: authoritative reference on `Awesome Code Docs` (github.com).
+- [`gguf-py/gguf/gguf_writer.py`](https://github.com/ggerganov/llama.cpp/blob/master/gguf-py/gguf/gguf_writer.py) -- Python `GGUFWriter`: shows all GGUF metadata keys and tensor layout
+- [`convert_hf_to_gguf.py`](https://github.com/ggerganov/llama.cpp/blob/master/convert_hf_to_gguf.py) -- model conversion script from HuggingFace format to GGUF F16/F32
+- [`src/llama.cpp`](https://github.com/ggerganov/llama.cpp/blob/master/src/llama.cpp) -- `llama_model_load()`: reads GGUF header, validates magic bytes, loads tensor metadata
-Suggested trace strategy:
-- search upstream code for `gguf` and `model` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+Suggested trace: read the GGUF spec comments at the top of `gguf_writer.py`, then follow `convert_hf_to_gguf.py` to understand how weights are mapped to GGUF format.
## Chapter Connections
diff --git a/tutorials/llama-cpp-tutorial/03-cli-usage.md b/tutorials/llama-cpp-tutorial/03-cli-usage.md
index 8caa8772..eb8dfaef 100644
--- a/tutorials/llama-cpp-tutorial/03-cli-usage.md
+++ b/tutorials/llama-cpp-tutorial/03-cli-usage.md
@@ -13,6 +13,21 @@ Welcome to **Chapter 3: Command Line Interface**. In this part of **llama.cpp Tu
> Master llama-cli with advanced options, interactive modes, and conversation management.
+## CLI Execution Modes
+
+```mermaid
+flowchart TD
+ CLI[llama-cli] --> M1[Single Prompt Mode\n-p text -n tokens]
+ CLI --> M2[Interactive Mode\n--interactive]
+ CLI --> M3[Instruction Mode\n--instruct]
+ CLI --> M4[Conversation Mode\n--conversation]
+
+ M1 --> O1[Generate and exit]
+ M2 --> O2[REPL loop with user input]
+ M3 --> O3[Instruction-tuned chat loop]
+ M4 --> O4[Multi-turn with full history]
+```
+
## Overview
The llama-cli tool provides comprehensive control over model inference. This chapter covers all major options, interactive modes, and advanced usage patterns.
@@ -523,16 +538,13 @@ When debugging, walk this sequence in order and confirm each stage has explicit
## Source Walkthrough
-Use the following upstream sources to verify implementation details while reading this chapter:
+Key source files in [`ggerganov/llama.cpp`](https://github.com/ggerganov/llama.cpp):
-- [View Repo](https://github.com/ggerganov/llama.cpp)
- Why it matters: authoritative reference on `View Repo` (github.com).
-- [Awesome Code Docs](https://github.com/johnxie/awesome-code-docs)
- Why it matters: authoritative reference on `Awesome Code Docs` (github.com).
+- [`examples/main/main.cpp`](https://github.com/ggerganov/llama.cpp/blob/master/examples/main/main.cpp) -- argument parsing for all `llama-cli` flags; shows which params map to which `llama_context_params` fields
+- [`common/arg.cpp`](https://github.com/ggerganov/llama.cpp/blob/master/common/arg.cpp) -- full CLI argument registry; authoritative reference for all flags and their defaults
+- [`common/sampling.cpp`](https://github.com/ggerganov/llama.cpp/blob/master/common/sampling.cpp) -- sampling pipeline: top-k, top-p, temperature, repetition penalty logic
-Suggested trace strategy:
-- search upstream code for `model` and `llama` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+Suggested trace: search `arg.cpp` for any flag (e.g., `--temp`) to find its default, type, and description, then find how it flows into the sampling or context params struct.
## Chapter Connections
diff --git a/tutorials/llama-cpp-tutorial/04-server.md b/tutorials/llama-cpp-tutorial/04-server.md
index f15c8812..65e7b9b2 100644
--- a/tutorials/llama-cpp-tutorial/04-server.md
+++ b/tutorials/llama-cpp-tutorial/04-server.md
@@ -13,6 +13,18 @@ Welcome to **Chapter 4: Server Mode**. In this part of **llama.cpp Tutorial: Loc
> Run llama.cpp as an OpenAI-compatible HTTP server for API access and integration with applications.
+## Server Architecture
+
+```mermaid
+flowchart LR
+ C[Client: OpenAI SDK / curl] -->|POST /v1/chat/completions| S[llama-server :8080]
+ S --> Q[Request Queue]
+ Q --> I[llama.cpp Inference Engine]
+ I --> M[GGUF Model in RAM/VRAM]
+ I -->|token stream or full response| S
+ S -->|JSON / SSE stream| C
+```
+
## Overview
llama.cpp includes a built-in HTTP server that provides an OpenAI-compatible API. This allows you to use any OpenAI client or library with your local models.
@@ -637,16 +649,13 @@ When debugging, walk this sequence in order and confirm each stage has explicit
## Source Walkthrough
-Use the following upstream sources to verify implementation details while reading this chapter:
+Key source files in [`ggerganov/llama.cpp`](https://github.com/ggerganov/llama.cpp):
-- [View Repo](https://github.com/ggerganov/llama.cpp)
- Why it matters: authoritative reference on `View Repo` (github.com).
-- [Awesome Code Docs](https://github.com/johnxie/awesome-code-docs)
- Why it matters: authoritative reference on `Awesome Code Docs` (github.com).
+- [`examples/server/server.cpp`](https://github.com/ggerganov/llama.cpp/blob/master/examples/server/server.cpp) -- HTTP server implementation; OpenAI-compatible route handlers for `/v1/chat/completions`, `/v1/completions`, `/v1/embeddings`
+- [`examples/server/utils.hpp`](https://github.com/ggerganov/llama.cpp/blob/master/examples/server/utils.hpp) -- JSON serialization helpers for request/response objects
+- [`examples/server/public/index.html`](https://github.com/ggerganov/llama.cpp/blob/master/examples/server/public/index.html) -- built-in web UI served at `http://localhost:8080`
-Suggested trace strategy:
-- search upstream code for `llama` and `server` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+Suggested trace: find the `/v1/chat/completions` handler in `server.cpp` to see how messages are tokenized, queued, and streamed back as SSE.
## Chapter Connections
diff --git a/tutorials/llama-cpp-tutorial/05-gpu.md b/tutorials/llama-cpp-tutorial/05-gpu.md
index fda76ee4..75e5e750 100644
--- a/tutorials/llama-cpp-tutorial/05-gpu.md
+++ b/tutorials/llama-cpp-tutorial/05-gpu.md
@@ -13,6 +13,23 @@ Welcome to **Chapter 5: GPU Acceleration**. In this part of **llama.cpp Tutorial
> Enable GPU acceleration with CUDA, Metal, and ROCm for dramatically faster inference.
+## GPU Offloading Architecture
+
+```mermaid
+flowchart TD
+ M[GGUF Model] --> CPU[CPU RAM: non-offloaded layers]
+ M --> GPU[GPU VRAM: -ngl N layers]
+ CPU --> INF[Inference Engine]
+ GPU --> INF
+ INF --> OUT[Generated Tokens]
+
+ subgraph Platforms
+ P1[NVIDIA CUDA: -DGGML_CUDA=ON]
+ P2[Apple Metal: -DGGML_METAL=ON auto on macOS]
+ P3[AMD ROCm: -DGGML_HIPBLAS=ON]
+ end
+```
+
## Overview
GPU acceleration can provide 5-10x speed improvements over CPU-only inference. llama.cpp supports multiple GPU platforms: NVIDIA CUDA, Apple Metal, and AMD ROCm.
@@ -530,16 +547,13 @@ When debugging, walk this sequence in order and confirm each stage has explicit
## Source Walkthrough
-Use the following upstream sources to verify implementation details while reading this chapter:
+Key source files in [`ggerganov/llama.cpp`](https://github.com/ggerganov/llama.cpp):
-- [View Repo](https://github.com/ggerganov/llama.cpp)
- Why it matters: authoritative reference on `View Repo` (github.com).
-- [Awesome Code Docs](https://github.com/johnxie/awesome-code-docs)
- Why it matters: authoritative reference on `Awesome Code Docs` (github.com).
+- [`CMakeLists.txt`](https://github.com/ggerganov/llama.cpp/blob/master/CMakeLists.txt) -- `GGML_CUDA`, `GGML_METAL`, `GGML_HIPBLAS` cmake options; controls which GPU backends are compiled
+- [`ggml/src/ggml-cuda/`](https://github.com/ggerganov/llama.cpp/tree/master/ggml/src/ggml-cuda) -- CUDA backend: kernel implementations for matrix multiplication and attention
+- [`ggml/src/ggml-metal.m`](https://github.com/ggerganov/llama.cpp/blob/master/ggml/src/ggml-metal.m) -- Apple Metal backend: MSL shaders for M-series GPU acceleration
-Suggested trace strategy:
-- search upstream code for `layers` and `llama` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+Suggested trace: in `src/llama.cpp` search for `n_gpu_layers` to see how the `-ngl` flag controls how many transformer layers are offloaded to GPU VRAM.
## Chapter Connections
diff --git a/tutorials/llama-cpp-tutorial/06-quantization.md b/tutorials/llama-cpp-tutorial/06-quantization.md
index 2fdb12cc..648dabb3 100644
--- a/tutorials/llama-cpp-tutorial/06-quantization.md
+++ b/tutorials/llama-cpp-tutorial/06-quantization.md
@@ -13,6 +13,20 @@ Welcome to **Chapter 6: Quantization**. In this part of **llama.cpp Tutorial: Lo
> Convert and quantize models to reduce memory usage while maintaining quality.
+## Quantization Workflow
+
+```mermaid
+flowchart LR
+ A[HuggingFace Model] -->|python convert_hf_to_gguf.py| B[model-f16.gguf]
+ B -->|./llama-quantize model-f16.gguf model-q4.gguf Q4_K_M| C[model-q4_k_m.gguf]
+ B -->|./llama-quantize ... Q8_0| D[model-q8.gguf]
+ B -->|./llama-quantize ... Q2_K| E[model-q2.gguf - smallest]
+
+ C --> V[Validation: llama-perplexity]
+ D --> V
+ E --> V
+```
+
## Overview
Quantization reduces model precision to save memory and improve speed. This chapter covers converting PyTorch models to GGUF and applying different quantization schemes.
@@ -485,16 +499,13 @@ When debugging, walk this sequence in order and confirm each stage has explicit
## Source Walkthrough
-Use the following upstream sources to verify implementation details while reading this chapter:
+Key source files in [`ggerganov/llama.cpp`](https://github.com/ggerganov/llama.cpp):
-- [View Repo](https://github.com/ggerganov/llama.cpp)
- Why it matters: authoritative reference on `View Repo` (github.com).
-- [Awesome Code Docs](https://github.com/johnxie/awesome-code-docs)
- Why it matters: authoritative reference on `Awesome Code Docs` (github.com).
+- [`examples/quantize/quantize.cpp`](https://github.com/ggerganov/llama.cpp/blob/master/examples/quantize/quantize.cpp) -- `llama-quantize` tool entry point; maps quantization type names like `Q4_K_M` to `ggml_type` enum
+- [`ggml/src/ggml-quants.c`](https://github.com/ggerganov/llama.cpp/blob/master/ggml/src/ggml-quants.c) -- actual quantization math: `quantize_row_q4_K`, block-wise quantization algorithms
+- [`src/llama.cpp`](https://github.com/ggerganov/llama.cpp/blob/master/src/llama.cpp) -- `llama_model_quantize()` function: orchestrates tensor-by-tensor quantization with the selected scheme
-Suggested trace strategy:
-- search upstream code for `model` and `gguf` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+Suggested trace: in `quantize.cpp` find the quant type enum → follow to `llama_model_quantize()` → see which tensors use k-quants vs. legacy quantization.
## Chapter Connections
diff --git a/tutorials/llama-cpp-tutorial/07-advanced.md b/tutorials/llama-cpp-tutorial/07-advanced.md
index 82472fc9..e70b7542 100644
--- a/tutorials/llama-cpp-tutorial/07-advanced.md
+++ b/tutorials/llama-cpp-tutorial/07-advanced.md
@@ -13,6 +13,21 @@ Welcome to **Chapter 7: Advanced Features**. In this part of **llama.cpp Tutoria
> Explore grammar-based generation, embeddings, multimodal models, and custom extensions.
+## Advanced Features Map
+
+```mermaid
+flowchart TD
+ LLAMA[llama.cpp] --> G[Grammar-Constrained Generation\n--grammar / --grammar-file]
+ LLAMA --> E[Embeddings\nllama-embedding tool]
+ LLAMA --> MM[Multimodal\nllava / MobileVLM support]
+ LLAMA --> SP[Speculative Decoding\n--model-draft flag]
+
+ G --> J[JSON Schema Output]
+ G --> R[GBNF Grammar Rules]
+ E --> RAG[RAG Pipelines]
+ MM --> V[Vision + Text Input]
+```
+
## Overview
Beyond basic text generation, llama.cpp supports advanced features like structured output, embeddings, and multimodal capabilities. This chapter covers these advanced use cases.
@@ -548,16 +563,14 @@ When debugging, walk this sequence in order and confirm each stage has explicit
## Source Walkthrough
-Use the following upstream sources to verify implementation details while reading this chapter:
+Key source files in [`ggerganov/llama.cpp`](https://github.com/ggerganov/llama.cpp):
-- [View Repo](https://github.com/ggerganov/llama.cpp)
- Why it matters: authoritative reference on `View Repo` (github.com).
-- [Awesome Code Docs](https://github.com/johnxie/awesome-code-docs)
- Why it matters: authoritative reference on `Awesome Code Docs` (github.com).
+- [`examples/grammar-based-sampling/`](https://github.com/ggerganov/llama.cpp/tree/master/examples/grammar-based-sampling) -- grammar-constrained sampling examples with GBNF grammar files
+- [`common/grammar-parser.cpp`](https://github.com/ggerganov/llama.cpp/blob/master/common/grammar-parser.cpp) -- parses GBNF grammar notation into a finite-state machine for constrained decoding
+- [`examples/embedding/embedding.cpp`](https://github.com/ggerganov/llama.cpp/blob/master/examples/embedding/embedding.cpp) -- `llama-embedding` tool: runs a model in embedding mode and outputs float vectors
+- [`examples/llava/`](https://github.com/ggerganov/llama.cpp/tree/master/examples/llava) -- LLaVA multimodal support: vision encoder integration with the language model
-Suggested trace strategy:
-- search upstream code for `self` and `model` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+Suggested trace: for grammar sampling, follow `llama_grammar_init()` → `llama_sample_grammar()` to see how grammar constraints prune the token probability distribution.
## Chapter Connections
diff --git a/tutorials/llama-cpp-tutorial/08-integration.md b/tutorials/llama-cpp-tutorial/08-integration.md
index 95239ef6..a36b757b 100644
--- a/tutorials/llama-cpp-tutorial/08-integration.md
+++ b/tutorials/llama-cpp-tutorial/08-integration.md
@@ -13,6 +13,17 @@ Welcome to **Chapter 8: Integration**. In this part of **llama.cpp Tutorial: Loc
> Integrate llama.cpp with Python applications, web services, and production systems.
+## Integration Patterns
+
+```mermaid
+flowchart TD
+ LLAMA[llama.cpp Engine] --> PY[llama-cpp-python\npip install llama-cpp-python]
+ LLAMA --> HTTP[llama-server REST API\nOpenAI-compatible]
+ PY --> APP1[Python Application\ndirect in-process]
+ HTTP --> APP2[Any OpenAI Client\nopenai, langchain, etc.]
+ HTTP --> APP3[Web Service\nFastAPI / Flask proxy]
+```
+
## Overview
While llama.cpp is written in C++, it provides excellent Python bindings and can be integrated into various applications. This chapter covers Python integration, web applications, and production deployment patterns.
@@ -733,16 +744,13 @@ When debugging, walk this sequence in order and confirm each stage has explicit
## Source Walkthrough
-Use the following upstream sources to verify implementation details while reading this chapter:
+Key source files in [`ggerganov/llama.cpp`](https://github.com/ggerganov/llama.cpp):
-- [View Repo](https://github.com/ggerganov/llama.cpp)
- Why it matters: authoritative reference on `View Repo` (github.com).
-- [Awesome Code Docs](https://github.com/johnxie/awesome-code-docs)
- Why it matters: authoritative reference on `Awesome Code Docs` (github.com).
+- [`llama.h`](https://github.com/ggerganov/llama.cpp/blob/master/llama.h) -- public C API: the stable ABI surface that `llama-cpp-python` binds against
+- [`examples/server/server.cpp`](https://github.com/ggerganov/llama.cpp/blob/master/examples/server/server.cpp) -- HTTP server that enables OpenAI SDK integration without Python bindings
+- Python bindings: [`abetlen/llama-cpp-python`](https://github.com/abetlen/llama-cpp-python) (separate repo) -- ctypes/cffi wrapper around `llama.h`; `Llama` class maps 1-to-1 with the C API
-Suggested trace strategy:
-- search upstream code for `self` and `model` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+Suggested trace: compare the `llama.h` C API with `llama-cpp-python`'s `Llama.__init__()` and `Llama.__call__()` to understand the Python-to-C binding layer.
## Chapter Connections
diff --git a/tutorials/llama-factory-tutorial/01-getting-started.md b/tutorials/llama-factory-tutorial/01-getting-started.md
index 23e3ab69..7e9f2386 100644
--- a/tutorials/llama-factory-tutorial/01-getting-started.md
+++ b/tutorials/llama-factory-tutorial/01-getting-started.md
@@ -11,6 +11,21 @@ Welcome to LLaMA-Factory! If you've ever wanted to train, fine-tune, or deploy l
## What Makes LLaMA-Factory Powerful?
+## LLaMA-Factory Training Pipeline
+
+```mermaid
+flowchart LR
+ A[Base Model\nLLaMA / Qwen / Mistral] --> B[LLaMA-Factory]
+ B --> C{Training Stage}
+ C --> D[SFT: Supervised Fine-Tuning]
+ C --> E[DPO: Preference Optimization]
+ C --> F[PPO: Reinforcement Learning]
+ D --> G[LoRA Adapter or Full Weights]
+ E --> G
+ F --> G
+ G --> H[Inference / Export / Serve]
+```
+
LLaMA-Factory revolutionizes LLM development by:
- **Unified Interface** - Single framework for training, fine-tuning, and deployment
- **Multiple Model Support** - Works with LLaMA, Qwen, and other architectures
@@ -393,14 +408,13 @@ When debugging, walk this sequence in order and confirm each stage has explicit
## Source Walkthrough
-Use the following upstream sources to verify implementation details while reading this chapter:
+Key source files in [`hiyouga/LLaMA-Factory`](https://github.com/hiyouga/LLaMA-Factory):
-- [View Repo](https://github.com/hiyouga/LLaMA-Factory)
- Why it matters: authoritative reference on `View Repo` (github.com).
+- [`src/llamafactory/train/tuner.py`](https://github.com/hiyouga/LLaMA-Factory/blob/main/src/llamafactory/train/tuner.py) -- `run_exp()` entry point; dispatches to the correct training stage (SFT, DPO, PPO)
+- [`src/llamafactory/hparams/`](https://github.com/hiyouga/LLaMA-Factory/tree/main/src/llamafactory/hparams) -- all hyperparameter dataclasses; `ModelArguments`, `DataArguments`, `FinetuningArguments`, `GeneratingArguments`
+- [`llamafactory/webui/`](https://github.com/hiyouga/LLaMA-Factory/tree/main/src/llamafactory/webui) -- Gradio-based web UI source code
-Suggested trace strategy:
-- search upstream code for `json` and `llamafactory` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+Suggested trace: follow `run_exp()` → stage dispatch → `run_sft()` to understand how training arguments flow from YAML/JSON config into the HuggingFace `Trainer`.
## Chapter Connections
diff --git a/tutorials/llama-factory-tutorial/02-data-preparation.md b/tutorials/llama-factory-tutorial/02-data-preparation.md
index 7b9a35db..604bb88e 100644
--- a/tutorials/llama-factory-tutorial/02-data-preparation.md
+++ b/tutorials/llama-factory-tutorial/02-data-preparation.md
@@ -9,6 +9,19 @@ nav_order: 2
Welcome to the crucial phase of fine-tuning: data preparation. The quality and format of your training data directly impacts the performance of your fine-tuned model. This chapter covers data collection, preprocessing, and formatting for LLaMA Factory.
+## Data Pipeline Overview
+
+```mermaid
+flowchart TD
+ RAW[Raw Data Sources\ntext, conversations, Q&A] --> FMT[Format Conversion]
+ FMT --> A[Alpaca Format\ninstruction + input + output]
+ FMT --> B[ShareGPT Format\nconversation turns]
+ A --> REG[dataset_info.json Registration]
+ B --> REG
+ REG --> PROC[Tokenization + Padding\nLLaMA-Factory preprocessor]
+ PROC --> TRAIN[Training Run]
+```
+
## Understanding Data Requirements
LLaMA Factory expects data in specific formats depending on the task type:
@@ -652,14 +665,13 @@ When debugging, walk this sequence in order and confirm each stage has explicit
## Source Walkthrough
-Use the following upstream sources to verify implementation details while reading this chapter:
+Key source files in [`hiyouga/LLaMA-Factory`](https://github.com/hiyouga/LLaMA-Factory):
-- [View Repo](https://github.com/hiyouga/LLaMA-Factory)
- Why it matters: authoritative reference on `View Repo` (github.com).
+- [`data/dataset_info.json`](https://github.com/hiyouga/LLaMA-Factory/blob/main/data/dataset_info.json) -- registry of all built-in datasets; shows alpaca/sharegpt format specs and load paths
+- [`src/llamafactory/data/loader.py`](https://github.com/hiyouga/LLaMA-Factory/blob/main/src/llamafactory/data/loader.py) -- `get_dataset()`: loads and merges datasets from `dataset_info.json`
+- [`src/llamafactory/data/formatter.py`](https://github.com/hiyouga/LLaMA-Factory/blob/main/src/llamafactory/data/formatter.py) -- applies chat template formatting to convert raw data into model-ready token sequences
-Suggested trace strategy:
-- search upstream code for `self` and `example` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+Suggested trace: `get_dataset()` → `convert_alpaca()` or `convert_sharegpt()` → `formatter.py` to see how raw dataset items become token IDs with the correct chat template.
## Chapter Connections
diff --git a/tutorials/llama-factory-tutorial/03-model-configuration.md b/tutorials/llama-factory-tutorial/03-model-configuration.md
index ad9692de..2b90282e 100644
--- a/tutorials/llama-factory-tutorial/03-model-configuration.md
+++ b/tutorials/llama-factory-tutorial/03-model-configuration.md
@@ -9,6 +9,22 @@ nav_order: 3
Welcome to the heart of fine-tuning! This chapter covers everything you need to know about configuring LLaMA models for optimal performance. We'll explore model selection, parameter tuning, quantization, and deployment strategies.
+## Fine-Tuning Method Comparison
+
+```mermaid
+flowchart LR
+ BASE[Base Model] --> FT{Fine-Tuning Type}
+ FT -->|Full Fine-Tuning| FULL[Update all parameters\nHigh VRAM, best quality]
+ FT -->|LoRA| LORA[Low-Rank Adapters\nLow VRAM, fast training]
+ FT -->|QLoRA| QLORA[4-bit Quantized LoRA\nMinimal VRAM required]
+ FT -->|DoRA| DORA[Weight-Decomposed LoRA\nImproved LoRA variant]
+
+ LORA --> MERGE[Merge adapter into base]
+ QLORA --> MERGE
+ FULL --> OUT[Fine-Tuned Model]
+ MERGE --> OUT
+```
+
## Understanding LLaMA Architecture
LLaMA models come in different sizes and variants, each optimized for specific use cases:
@@ -612,14 +628,13 @@ When debugging, walk this sequence in order and confirm each stage has explicit
## Source Walkthrough
-Use the following upstream sources to verify implementation details while reading this chapter:
+Key source files in [`hiyouga/LLaMA-Factory`](https://github.com/hiyouga/LLaMA-Factory):
-- [View Repo](https://github.com/hiyouga/LLaMA-Factory)
- Why it matters: authoritative reference on `View Repo` (github.com).
+- [`src/llamafactory/model/loader.py`](https://github.com/hiyouga/LLaMA-Factory/blob/main/src/llamafactory/model/loader.py) -- `load_model()` and `load_tokenizer()`: base model loading with quantization and device mapping
+- [`src/llamafactory/model/adapter.py`](https://github.com/hiyouga/LLaMA-Factory/blob/main/src/llamafactory/model/adapter.py) -- `init_adapter()`: initializes LoRA/QLoRA/DoRA adapters using PEFT library
+- [`src/llamafactory/hparams/model_args.py`](https://github.com/hiyouga/LLaMA-Factory/blob/main/src/llamafactory/hparams/model_args.py) -- `ModelArguments`: all model config flags including `quantization_bit`, `lora_target`, `rope_scaling`
-Suggested trace strategy:
-- search upstream code for `model` and `torch` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+Suggested trace: `load_model()` → `init_adapter()` to understand how a base model becomes a LoRA-trainable model via PEFT's `get_peft_model()`.
## Chapter Connections
diff --git a/tutorials/llama-factory-tutorial/04-training-pipeline.md b/tutorials/llama-factory-tutorial/04-training-pipeline.md
index af89df85..fe7f0cf9 100644
--- a/tutorials/llama-factory-tutorial/04-training-pipeline.md
+++ b/tutorials/llama-factory-tutorial/04-training-pipeline.md
@@ -9,6 +9,22 @@ nav_order: 4
Welcome to the training phase! This chapter covers the complete training pipeline for LLaMA Factory, from data loading to model training, monitoring, and optimization. We'll explore distributed training, hyperparameter tuning, and best practices for successful fine-tuning.
+## Training Pipeline Flow
+
+```mermaid
+flowchart TD
+ A[llamafactory-cli train config.yaml] --> B[Load Base Model]
+ B --> C[Load + Tokenize Dataset]
+ C --> D[Apply Fine-Tuning Method\nLoRA / QLoRA / Full]
+ D --> E[Training Loop]
+ E --> F{Checkpoint?}
+ F -->|Every save_steps| G[Save Checkpoint]
+ F -->|Continue| E
+ E --> H[Training Complete]
+ H --> I[Export / Merge Adapter]
+ I --> J[Evaluate with llama-eval]
+```
+
## Setting Up the Training Environment
### Hardware Requirements and Optimization
@@ -723,14 +739,13 @@ When debugging, walk this sequence in order and confirm each stage has explicit
## Source Walkthrough
-Use the following upstream sources to verify implementation details while reading this chapter:
+Key source files in [`hiyouga/LLaMA-Factory`](https://github.com/hiyouga/LLaMA-Factory):
-- [View Repo](https://github.com/hiyouga/LLaMA-Factory)
- Why it matters: authoritative reference on `View Repo` (github.com).
+- [`src/llamafactory/train/sft/trainer.py`](https://github.com/hiyouga/LLaMA-Factory/blob/main/src/llamafactory/train/sft/trainer.py) -- `CustomSeq2SeqTrainer`: extends HuggingFace `Seq2SeqTrainer` with custom loss computation and metrics
+- [`src/llamafactory/train/sft/workflow.py`](https://github.com/hiyouga/LLaMA-Factory/blob/main/src/llamafactory/train/sft/workflow.py) -- `run_sft()`: orchestrates data loading, model init, trainer creation, and training call
+- [`src/llamafactory/train/callbacks.py`](https://github.com/hiyouga/LLaMA-Factory/blob/main/src/llamafactory/train/callbacks.py) -- custom training callbacks for logging, checkpoint saving, and progress tracking
-Suggested trace strategy:
-- search upstream code for `self` and `loss` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+Suggested trace: `run_sft()` → `CustomSeq2SeqTrainer.train()` → `compute_loss()` to see the complete SFT training loop from workflow entry to loss calculation.
## Chapter Connections
diff --git a/tutorials/llama-factory-tutorial/05-model-evaluation.md b/tutorials/llama-factory-tutorial/05-model-evaluation.md
index 42520052..32e0ccbb 100644
--- a/tutorials/llama-factory-tutorial/05-model-evaluation.md
+++ b/tutorials/llama-factory-tutorial/05-model-evaluation.md
@@ -9,6 +9,22 @@ nav_order: 5
Welcome to the critical phase of model assessment! Evaluating your fine-tuned LLaMA models ensures they perform well on your target tasks. This chapter covers comprehensive evaluation techniques, benchmarks, and quality metrics for production-ready models.
+## Evaluation Workflow
+
+```mermaid
+flowchart LR
+ M[Fine-Tuned Model] --> E{Evaluation Type}
+ E --> A[Automated Benchmarks\nMMLU, CMMLU, C-Eval]
+ E --> B[Task-Specific Metrics\nROUGE, BLEU, accuracy]
+ E --> C[Human Evaluation\nquality rubrics]
+ A --> SCORE[Benchmark Score]
+ B --> SCORE
+ C --> SCORE
+ SCORE --> D{Pass Threshold?}
+ D -->|Yes| DEPLOY[Deploy to Production]
+ D -->|No| ITER[Iterate: adjust data or hyperparameters]
+```
+
## Evaluation Metrics and Benchmarks
### Core Evaluation Metrics
@@ -817,14 +833,13 @@ When debugging, walk this sequence in order and confirm each stage has explicit
## Source Walkthrough
-Use the following upstream sources to verify implementation details while reading this chapter:
+Key source files in [`hiyouga/LLaMA-Factory`](https://github.com/hiyouga/LLaMA-Factory):
-- [View Repo](https://github.com/hiyouga/LLaMA-Factory)
- Why it matters: authoritative reference on `View Repo` (github.com).
+- [`src/llamafactory/eval/evaluator.py`](https://github.com/hiyouga/LLaMA-Factory/blob/main/src/llamafactory/eval/evaluator.py) -- `Evaluator` class: benchmark evaluation loop for MMLU, C-Eval, and custom tasks
+- [`src/llamafactory/train/sft/metric.py`](https://github.com/hiyouga/LLaMA-Factory/blob/main/src/llamafactory/train/sft/metric.py) -- `compute_metrics()`: ROUGE, BLEU, accuracy calculations for SFT evaluation
+- [`src/llamafactory/chat/chat_model.py`](https://github.com/hiyouga/LLaMA-Factory/blob/main/src/llamafactory/chat/chat_model.py) -- `ChatModel`: used during evaluation for interactive chat testing of fine-tuned models
-Suggested trace strategy:
-- search upstream code for `self` and `report` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+Suggested trace: `run_eval()` → `Evaluator.eval()` to see how benchmark datasets are loaded, questions are answered by the model, and scores are aggregated.
## Chapter Connections
diff --git a/tutorials/llama-factory-tutorial/06-deployment.md b/tutorials/llama-factory-tutorial/06-deployment.md
index 839436f8..6f047836 100644
--- a/tutorials/llama-factory-tutorial/06-deployment.md
+++ b/tutorials/llama-factory-tutorial/06-deployment.md
@@ -9,6 +9,20 @@ nav_order: 6
Welcome to the deployment phase! This chapter covers production deployment strategies for your fine-tuned LLaMA models, from model optimization to serving infrastructure and scaling considerations.
+## Deployment Options
+
+```mermaid
+flowchart TD
+ M[Fine-Tuned Model + LoRA Adapter] --> OPT[Optimization]
+ OPT --> Q[Quantize: GPTQ / AWQ / GGUF]
+ OPT --> MERGE[Merge LoRA into Base]
+ Q --> SERVE{Serving Backend}
+ MERGE --> SERVE
+ SERVE --> A[llamafactory-cli api\nbuilt-in OpenAI API]
+ SERVE --> B[vLLM\nhigh-throughput serving]
+ SERVE --> C[llama.cpp server\nlow-resource edge]
+```
+
## Model Optimization for Production
### Quantization and Compression
@@ -628,14 +642,13 @@ When debugging, walk this sequence in order and confirm each stage has explicit
## Source Walkthrough
-Use the following upstream sources to verify implementation details while reading this chapter:
+Key source files in [`hiyouga/LLaMA-Factory`](https://github.com/hiyouga/LLaMA-Factory):
-- [View Repo](https://github.com/hiyouga/LLaMA-Factory)
- Why it matters: authoritative reference on `View Repo` (github.com).
+- [`src/llamafactory/api/app.py`](https://github.com/hiyouga/LLaMA-Factory/blob/main/src/llamafactory/api/app.py) -- FastAPI OpenAI-compatible API server: `/v1/chat/completions` endpoint
+- [`src/llamafactory/model/loader.py`](https://github.com/hiyouga/LLaMA-Factory/blob/main/src/llamafactory/model/loader.py) -- `load_model()` with `finetuning_type="lora"` and `adapter_name_or_path` to load merged adapters
+- [`src/llamafactory/train/sft/workflow.py`](https://github.com/hiyouga/LLaMA-Factory/blob/main/src/llamafactory/train/sft/workflow.py) -- `run_export()`: merges LoRA adapter weights into the base model for deployment
-Suggested trace strategy:
-- search upstream code for `self` and `request` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+Suggested trace: `run_export()` → `merge_lora()` → see how PEFT's `merge_and_unload()` is called to produce a standalone merged model ready for serving.
## Chapter Connections
diff --git a/tutorials/llama-factory-tutorial/07-advanced-techniques.md b/tutorials/llama-factory-tutorial/07-advanced-techniques.md
index 4b6d2595..38a143d6 100644
--- a/tutorials/llama-factory-tutorial/07-advanced-techniques.md
+++ b/tutorials/llama-factory-tutorial/07-advanced-techniques.md
@@ -9,6 +9,20 @@ nav_order: 7
Welcome to the cutting edge! This chapter explores advanced techniques for pushing the boundaries of LLaMA fine-tuning, from continual learning to multi-modal models and beyond.
+## Advanced Techniques Overview
+
+```mermaid
+flowchart TD
+ ADV[Advanced Techniques] --> CL[Continual Learning\nIncremental fine-tuning]
+ ADV --> MULTI[Multi-GPU Training\nDeepSpeed / FSDP]
+ ADV --> RLHF[RLHF Pipeline\nReward Modeling + PPO]
+ ADV --> VLM[Vision-Language\nQwen2-VL, LLaVA support]
+ ADV --> MERGE_TECH[Model Merging\nTIES, DARE, SLERP]
+
+ MULTI --> DS[DeepSpeed ZeRO-3]
+ MULTI --> FSDP[FSDP + QLoRA]
+```
+
## Continual Learning and Model Updates
### Incremental Fine-tuning
@@ -660,12 +674,28 @@ When debugging, walk this sequence in order and confirm each stage has explicit
Use the following upstream sources to verify implementation details while reading this chapter:
-- [View Repo](https://github.com/hiyouga/LLaMA-Factory)
- Why it matters: authoritative reference on `View Repo` (github.com).
+- [`src/llamafactory/train/dpo/trainer.py`](https://github.com/hiyouga/LLaMA-Factory/blob/main/src/llamafactory/train/dpo/trainer.py)
+ The DPO (Direct Preference Optimization) trainer used for RLHF-style alignment training. Shows how preference pairs are processed and the DPO loss is computed against a reference model.
+
+- [`src/llamafactory/train/ppo/trainer.py`](https://github.com/hiyouga/LLaMA-Factory/blob/main/src/llamafactory/train/ppo/trainer.py)
+ PPO (Proximal Policy Optimization) trainer for reinforcement learning from human feedback. Implements reward model scoring, KL-divergence penalty, and policy gradient updates.
+
+- [`src/llamafactory/train/rm/trainer.py`](https://github.com/hiyouga/LLaMA-Factory/blob/main/src/llamafactory/train/rm/trainer.py)
+ Reward model trainer used to learn human preferences from ranked response pairs. Required as the first stage of a full RLHF pipeline before PPO fine-tuning.
+
+- [`src/llamafactory/model/model_utils/visual.py`](https://github.com/hiyouga/LLaMA-Factory/blob/main/src/llamafactory/model/model_utils/visual.py)
+ Vision-language model integration utilities. Handles multi-modal input encoding, image patch embedding projection, and alignment with the language model's embedding space for VLM fine-tuning (e.g., Qwen2-VL, LLaVA).
+
+- [`examples/deepspeed/`](https://github.com/hiyouga/LLaMA-Factory/tree/main/examples/deepspeed)
+ DeepSpeed ZeRO configuration examples (ZeRO-2, ZeRO-3, offload variants) used for multi-GPU and multi-node distributed training. These YAML files are passed via `--deepspeed` to enable sharded optimizer states, gradients, and parameters.
+
+- [`src/llamafactory/hparams/finetuning_args.py`](https://github.com/hiyouga/LLaMA-Factory/blob/main/src/llamafactory/hparams/finetuning_args.py)
+ Defines `FinetuningArguments` dataclass including fields for `stage` (sft/dpo/ppo/rm/kto), `lora_rank`, `use_dora`, `pissa_init`, `rope_scaling`, and model-merging method (`merge_method`: ties, dare, slerp). This is the authoritative source for all advanced training options.
Suggested trace strategy:
-- search upstream code for `self` and `model` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+- Follow `src/llamafactory/train/dpo/trainer.py` → `compute_preference_loss()` to understand how RLHF alignment differs from SFT
+- Check `src/llamafactory/hparams/finetuning_args.py` for the full list of supported `merge_method` values and VLM-specific flags
+- Review DeepSpeed ZeRO-3 config in `examples/deepspeed/ds_z3_config.json` before running multi-GPU jobs
## Chapter Connections
diff --git a/tutorials/llama-factory-tutorial/08-production-case-studies.md b/tutorials/llama-factory-tutorial/08-production-case-studies.md
index 31b8488a..b19a7500 100644
--- a/tutorials/llama-factory-tutorial/08-production-case-studies.md
+++ b/tutorials/llama-factory-tutorial/08-production-case-studies.md
@@ -7,7 +7,21 @@ nav_order: 8
# Chapter 8: Production Case Studies
-Welcome to the grand finale! 🎉 This chapter showcases real-world production deployments of LLaMA Factory, complete with challenges faced, solutions implemented, and lessons learned. These case studies demonstrate how to apply everything you've learned in a production environment.
+Welcome to the grand finale! This chapter showcases real-world production deployments of LLaMA Factory, complete with challenges faced, solutions implemented, and lessons learned. These case studies demonstrate how to apply everything you've learned in a production environment.
+
+## Production Workflow Summary
+
+```mermaid
+flowchart LR
+ REQ[Business Requirement] --> DATA[Curate Domain Dataset]
+ DATA --> TRAIN[Fine-tune with LLaMA-Factory\nLoRA or QLoRA]
+ TRAIN --> EVAL[Evaluate: task-specific benchmarks]
+ EVAL --> OK{Quality Gate?}
+ OK -->|Pass| DEPLOY[Deploy: vLLM / llama.cpp / API]
+ OK -->|Fail| DATA
+ DEPLOY --> MON[Monitor: latency, quality, cost]
+ MON -->|Drift detected| DATA
+```
## Case Study 1: AI Customer Support System
@@ -827,12 +841,28 @@ When debugging, walk this sequence in order and confirm each stage has explicit
Use the following upstream sources to verify implementation details while reading this chapter:
-- [View Repo](https://github.com/hiyouga/LLaMA-Factory)
- Why it matters: authoritative reference on `View Repo` (github.com).
+- [`src/llamafactory/api/app.py`](https://github.com/hiyouga/LLaMA-Factory/blob/main/src/llamafactory/api/app.py)
+ FastAPI application implementing an OpenAI-compatible REST API (`/v1/chat/completions`, `/v1/models`). This is the production serving layer used when deploying fine-tuned models as an API endpoint. Shows model loading, streaming response generation, and error handling.
+
+- [`src/llamafactory/chat/hf_engine.py`](https://github.com/hiyouga/LLaMA-Factory/blob/main/src/llamafactory/chat/hf_engine.py)
+ HuggingFace inference engine used by the API server and chat interface. Handles tokenization, generation parameters (temperature, top-p, repetition penalty), and streaming token output. Key file for understanding production inference throughput.
+
+- [`src/llamafactory/train/sft/workflow.py`](https://github.com/hiyouga/LLaMA-Factory/blob/main/src/llamafactory/train/sft/workflow.py)
+ Contains `run_sft()` and `run_export()`. The `run_export()` function implements LoRA adapter merging into the base model weights for deployment - critical for the case study pattern of train-then-export-then-serve.
+
+- [`examples/`](https://github.com/hiyouga/LLaMA-Factory/tree/main/examples)
+ Production-ready YAML configuration examples for common fine-tuning recipes: `full_multi_gpu/`, `lora_single_gpu/`, `qlora_deepspeed/`. These reference configs align with the case study training patterns shown in this chapter.
+
+- [`src/llamafactory/extras/callbacks.py`](https://github.com/hiyouga/LLaMA-Factory/blob/main/src/llamafactory/extras/callbacks.py)
+ Training callbacks for logging loss curves, saving checkpoints, and triggering early stopping. In production pipelines, these callbacks feed metrics into monitoring systems and enable the continuous learning cycle.
+
+- [`src/llamafactory/eval/evaluator.py`](https://github.com/hiyouga/LLaMA-Factory/blob/main/src/llamafactory/eval/evaluator.py)
+ Evaluation pipeline for benchmarking fine-tuned models on standard datasets (MMLU, C-Eval, etc.). Used in the production quality gate step before deploying a new model version.
Suggested trace strategy:
-- search upstream code for `self` and `Step` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+- Trace `src/llamafactory/api/app.py` → `create_app()` to understand production API bootstrapping with adapter loading
+- Compare `src/llamafactory/chat/hf_engine.py` `ChatModel.stream_chat()` with vLLM async engine for throughput differences
+- Review `examples/lora_single_gpu/llama3_lora_sft.yaml` as a concrete template before adapting configs for domain-specific deployments
## Chapter Connections
diff --git a/tutorials/llamaindex-tutorial/01-getting-started.md b/tutorials/llamaindex-tutorial/01-getting-started.md
index 658bbf7e..ddb1df6c 100644
--- a/tutorials/llamaindex-tutorial/01-getting-started.md
+++ b/tutorials/llamaindex-tutorial/01-getting-started.md
@@ -588,12 +588,22 @@ When debugging, walk this sequence in order and confirm each stage has explicit
Use the following upstream sources to verify implementation details while reading this chapter:
-- [View Repo](https://github.com/run-llama/llama_index)
- Why it matters: authoritative reference on `View Repo` (github.com).
+- [`llama_index/core/__init__.py`](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/__init__.py)
+ Top-level namespace exports for `VectorStoreIndex`, `SimpleDirectoryReader`, `Settings`, and `StorageContext`. This is the surface API that most getting-started examples use.
+
+- [`llama_index/core/settings.py`](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/settings.py)
+ Defines the global `Settings` object (formerly `ServiceContext`). Controls default LLM, embedding model, chunk size, and callback manager. Understanding this file is essential before any end-to-end pipeline.
+
+- [`llama_index/core/indices/vector_store/base.py`](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/indices/vector_store/base.py)
+ `VectorStoreIndex` implementation. Shows how documents are chunked, embedded, and stored during `from_documents()`, and how the index is loaded back from a storage context.
+
+- [`llama_index/core/readers/file/base.py`](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/readers/file/base.py)
+ `SimpleDirectoryReader` that scans a directory, dispatches to format-specific parsers, and returns a list of `Document` objects. The entry point for almost every getting-started example.
Suggested trace strategy:
-- search upstream code for `self` and `documents` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+- Start at `Settings` to understand how LLM and embedding defaults are configured globally before running any index build
+- Trace `VectorStoreIndex.from_documents()` through `llama_index/core/indices/vector_store/base.py` to see chunking → embedding → upsert flow
+- Check `SimpleDirectoryReader._load_data()` to understand how file metadata is attached to `Document` objects
## Chapter Connections
diff --git a/tutorials/llamaindex-tutorial/02-data-ingestion.md b/tutorials/llamaindex-tutorial/02-data-ingestion.md
index f68969a7..5571603d 100644
--- a/tutorials/llamaindex-tutorial/02-data-ingestion.md
+++ b/tutorials/llamaindex-tutorial/02-data-ingestion.md
@@ -12,6 +12,18 @@ Welcome to **Chapter 2: Data Ingestion & Loading**. In this part of **LlamaIndex
> Master the art of loading diverse data sources into LlamaIndex for comprehensive RAG systems.
+## Data Ingestion Pipeline
+
+```mermaid
+flowchart LR
+ SRC[Files, PDFs, URLs\nAPIs, Databases] --> LOAD[SimpleDirectoryReader\nor LlamaHub connectors]
+ LOAD --> DOC[Document objects\nwith metadata]
+ DOC --> SPLIT[NodeParser\nSentenceSplitter]
+ SPLIT --> NODES[TextNode chunks]
+ NODES --> EMBED[Embedding Model]
+ EMBED --> INDEX[VectorStoreIndex]
+```
+
## 🎯 Overview
This chapter covers LlamaIndex's powerful data ingestion capabilities, showing you how to load data from various sources including files, APIs, databases, and web content. You'll learn to handle different data formats and create robust data pipelines for your RAG applications.
@@ -1153,12 +1165,22 @@ When debugging, walk this sequence in order and confirm each stage has explicit
Use the following upstream sources to verify implementation details while reading this chapter:
-- [View Repo](https://github.com/run-llama/llama_index)
- Why it matters: authoritative reference on `View Repo` (github.com).
+- [`llama_index/core/readers/base.py`](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/readers/base.py)
+ Defines the `BaseReader` abstract class with `load_data()` method. All connectors (PDFReader, WebBaseLoader, DatabaseReader) implement this interface and return lists of `Document` objects.
+
+- [`llama_index/core/schema.py`](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/schema.py)
+ Core data model definitions: `Document`, `TextNode`, `NodeWithScore`, `MediaResource`. Understanding `Document.metadata` structure and `TextNode.relationships` is essential for understanding how ingestion populates the graph for downstream retrieval.
+
+- [`llama_index/core/node_parser/text/sentence.py`](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/node_parser/text/sentence.py)
+ `SentenceSplitter` implementation - the default text chunking strategy. Shows how `chunk_size`, `chunk_overlap`, and sentence boundary detection interact to produce `TextNode` objects from raw document text.
+
+- [`llama_index/core/ingestion/pipeline.py`](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/ingestion/pipeline.py)
+ `IngestionPipeline` that chains readers → transformations → vector store upsert. Supports deduplication via document ID tracking and async execution for large-scale ingestion jobs.
Suggested trace strategy:
-- search upstream code for `documents` and `text` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+- Trace `BaseReader.load_data()` → `Document` creation to understand how metadata is attached from source connectors
+- Follow `SentenceSplitter.get_nodes_from_documents()` to see how chunk boundaries are calculated with overlap
+- Inspect `IngestionPipeline.run()` to see how transformation stages are chained and cached for incremental re-ingestion
## Chapter Connections
diff --git a/tutorials/llamaindex-tutorial/03-indexing-storage.md b/tutorials/llamaindex-tutorial/03-indexing-storage.md
index 16e888fe..ebc2d5dd 100644
--- a/tutorials/llamaindex-tutorial/03-indexing-storage.md
+++ b/tutorials/llamaindex-tutorial/03-indexing-storage.md
@@ -12,6 +12,20 @@ Welcome to **Chapter 3: Indexing & Storage**. In this part of **LlamaIndex Tutor
> Master the creation of efficient indexes and storage strategies for optimal retrieval performance.
+## Index and Storage Architecture
+
+```mermaid
+flowchart TD
+ NODES[TextNodes] --> IDX{Index Type}
+ IDX --> VI[VectorStoreIndex\nsemantic similarity]
+ IDX --> SI[SummaryIndex\ndocument summarization]
+ IDX --> KGI[KnowledgeGraphIndex\nentity relationships]
+ VI --> SC[StorageContext]
+ SC --> VS[VectorStore\nChroma, Pinecone, Qdrant]
+ SC --> DS[DocStore\nredis, mongo, filesystem]
+ SC --> IS[IndexStore\npersist index metadata]
+```
+
## 🎯 Overview
This chapter covers LlamaIndex's indexing and storage capabilities, showing you how to create different types of indexes, choose appropriate storage backends, and optimize for various use cases. You'll learn to build scalable, high-performance knowledge bases for your RAG applications.
@@ -978,12 +992,25 @@ When debugging, walk this sequence in order and confirm each stage has explicit
Use the following upstream sources to verify implementation details while reading this chapter:
-- [View Repo](https://github.com/run-llama/llama_index)
- Why it matters: authoritative reference on `View Repo` (github.com).
+- [`llama_index/core/storage/storage_context.py`](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/storage/storage_context.py)
+ `StorageContext` bundles `DocStore`, `IndexStore`, `VectorStore`, and `GraphStore`. This is the persistence layer for all index types. Understanding `from_defaults()` vs `from_persist_dir()` is critical for saving and loading indices.
+
+- [`llama_index/core/indices/vector_store/base.py`](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/indices/vector_store/base.py)
+ `VectorStoreIndex` internals including `_add_nodes_to_index()` and `_build_index_from_nodes()`. Shows how embedding batch size is controlled and how metadata filters are applied at insert time.
+
+- [`llama_index/core/storage/docstore/keyval_docstore.py`](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/storage/docstore/keyval_docstore.py)
+ Key-value document store that persists `TextNode` objects by ID. Supports SimpleDocumentStore (in-memory/JSON) and can be backed by Redis or MongoDB via integration packages.
+
+- [`llama_index/core/indices/keyword_table/base.py`](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/indices/keyword_table/base.py)
+ `KeywordTableIndex` implementation for keyword-based retrieval. Contrast with `VectorStoreIndex` to understand when exact keyword matching is preferable to semantic similarity search.
+
+- [`llama_index/core/graph_stores/`](https://github.com/run-llama/llama_index/tree/main/llama-index-core/llama_index/core/graph_stores)
+ Graph store interface and in-memory implementation used by `KnowledgeGraphIndex`. Shows how triples (subject, predicate, object) are extracted and stored for graph-based retrieval.
Suggested trace strategy:
-- search upstream code for `index` and `documents` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+- Follow `StorageContext.persist()` to understand which files (docstore.json, index_store.json, vector_store.json) are written to disk
+- Trace `VectorStoreIndex._add_nodes_to_index()` to see how embeddings are batched and inserted into the vector store backend
+- Compare `SimpleVectorStore` (in-memory) vs a Pinecone/Weaviate integration to understand the adapter interface
## Chapter Connections
diff --git a/tutorials/llamaindex-tutorial/04-query-engines.md b/tutorials/llamaindex-tutorial/04-query-engines.md
index c42058ad..c24e0364 100644
--- a/tutorials/llamaindex-tutorial/04-query-engines.md
+++ b/tutorials/llamaindex-tutorial/04-query-engines.md
@@ -12,6 +12,24 @@ Welcome to **Chapter 4: Query Engines & Retrieval**. In this part of **LlamaInde
> Build sophisticated query engines and retrieval systems for advanced RAG applications.
+## Query Engine Architecture
+
+```mermaid
+flowchart LR
+ Q[User Query] --> RET[Retriever\nVectorIndexRetriever]
+ RET --> NODES[Retrieved TextNodes]
+ NODES --> RERANK[Re-ranker\noptional]
+ RERANK --> SYNTH[ResponseSynthesizer]
+ SYNTH --> LLM[LLM]
+ LLM --> ANS[Answer + Source Nodes]
+
+ subgraph QueryEngines
+ QE1[VectorStoreIndex.as_query_engine]
+ QE2[SubQuestionQueryEngine]
+ QE3[RouterQueryEngine]
+ end
+```
+
## 🎯 Overview
This chapter covers LlamaIndex's query engines and retrieval mechanisms, showing you how to build complex query pipelines, implement different retrieval strategies, and create intelligent systems that can answer complex questions using your indexed data.
@@ -812,12 +830,25 @@ When debugging, walk this sequence in order and confirm each stage has explicit
Use the following upstream sources to verify implementation details while reading this chapter:
-- [View Repo](https://github.com/run-llama/llama_index)
- Why it matters: authoritative reference on `View Repo` (github.com).
+- [`llama_index/core/query_engine/retriever_query_engine.py`](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/query_engine/retriever_query_engine.py)
+ `RetrieverQueryEngine` - the default query engine wiring retriever → node postprocessors → response synthesizer. The `query()` method shows the full retrieve-then-synthesize pipeline.
+
+- [`llama_index/core/retrievers/vector_store.py`](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/retrievers/vector_store.py)
+ `VectorIndexRetriever` that embeds the query and performs cosine similarity search against stored node embeddings. Key parameters: `similarity_top_k` and `vector_store_query_mode` (default, sparse, hybrid).
+
+- [`llama_index/core/response_synthesizers/`](https://github.com/run-llama/llama_index/tree/main/llama-index-core/llama_index/core/response_synthesizers)
+ Response synthesis strategies: `compact`, `refine`, `tree_summarize`, `simple_summarize`, `no_text`. Each uses a different pattern for combining retrieved nodes into a final LLM prompt. `Refine` iteratively updates the answer across chunks; `tree_summarize` builds a summary tree.
+
+- [`llama_index/core/postprocessor/`](https://github.com/run-llama/llama_index/tree/main/llama-index-core/llama_index/core/postprocessor)
+ Node postprocessors including `SimilarityPostprocessor` (score threshold filtering), `KeywordNodePostprocessor` (keyword inclusion/exclusion), and `LLMRerank` (rerank with LLM relevance scoring). Applied between retrieval and synthesis.
+
+- [`llama_index/core/chat_engine/condense_plus_context.py`](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/chat_engine/condense_plus_context.py)
+ `CondensePlusContextChatEngine` for multi-turn conversations. Shows how chat history is condensed into a standalone query before retrieval, enabling coherent multi-turn RAG conversations.
Suggested trace strategy:
-- search upstream code for `query` and `self` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+- Trace `RetrieverQueryEngine.query()` → `retrieve()` → `synthesize()` to map the full query lifecycle
+- Compare `refine` vs `tree_summarize` synthesizers in `response_synthesizers/` to understand token budget tradeoffs for long contexts
+- Check `LLMRerank` postprocessor to see how a cross-encoder reranking call is inserted after initial vector retrieval
## Chapter Connections
diff --git a/tutorials/llamaindex-tutorial/05-advanced-rag.md b/tutorials/llamaindex-tutorial/05-advanced-rag.md
index 86223a74..7a240b07 100644
--- a/tutorials/llamaindex-tutorial/05-advanced-rag.md
+++ b/tutorials/llamaindex-tutorial/05-advanced-rag.md
@@ -12,6 +12,21 @@ Welcome to **Chapter 5: Advanced RAG Patterns**. In this part of **LlamaIndex Tu
> Implement sophisticated RAG architectures with multi-modal data, agents, and hybrid approaches.
+## Advanced RAG Patterns
+
+```mermaid
+flowchart TD
+ ADV[Advanced RAG] --> HYB[Hybrid Search\nVector + BM25 keyword]
+ ADV --> MQ[Multi-Query\nHyDE, query decomposition]
+ ADV --> MR[Multi-Modal RAG\ntext + images + tables]
+ ADV --> AG[Agent-Based RAG\nReActAgent with tools]
+ ADV --> KG[Knowledge Graph RAG\nentity linking]
+
+ HYB --> FUSE[Reciprocal Rank Fusion]
+ MQ --> SYNTH[Response synthesis]
+ AG --> TOOLS[QueryEngine as Tool]
+```
+
## 🎯 Overview
This chapter covers advanced Retrieval-Augmented Generation patterns including multi-modal RAG, agent-based systems, knowledge graphs, and hybrid architectures that combine multiple retrieval and generation strategies.
@@ -858,12 +873,25 @@ When debugging, walk this sequence in order and confirm each stage has explicit
Use the following upstream sources to verify implementation details while reading this chapter:
-- [View Repo](https://github.com/run-llama/llama_index)
- Why it matters: authoritative reference on `View Repo` (github.com).
+- [`llama_index/core/query_engine/sub_question_query_engine.py`](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/query_engine/sub_question_query_engine.py)
+ `SubQuestionQueryEngine` that decomposes complex queries into sub-questions, routes each to a relevant index, then combines answers. Core of the multi-document advanced RAG pattern.
+
+- [`llama_index/core/retrievers/fusion_retriever.py`](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/retrievers/fusion_retriever.py)
+ `QueryFusionRetriever` implementing multi-query fusion. Generates multiple query variants via LLM, retrieves from each, then merges results with Reciprocal Rank Fusion (RRF) to improve recall for complex questions.
+
+- [`llama_index/core/node_parser/text/hierarchical.py`](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/node_parser/text/hierarchical.py)
+ `HierarchicalNodeParser` for building multi-granularity chunking. Creates parent (larger) and child (smaller) nodes with relationship links, enabling "small-to-big" retrieval where small chunks are retrieved but larger context windows are passed to the LLM.
+
+- [`llama_index/core/postprocessor/llm_rerank.py`](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/postprocessor/llm_rerank.py)
+ `LLMRerank` postprocessor that uses an LLM to score and reorder retrieved nodes by relevance before synthesis. Essential for advanced RAG pipelines where top-k retrieval is noisy.
+
+- [`llama_index/core/query_engine/router_query_engine.py`](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/query_engine/router_query_engine.py)
+ `RouterQueryEngine` that uses a `LLMSingleSelector` or `PydanticMultiSelector` to route queries to the most relevant index or query engine among multiple options. Key component in multi-source RAG architectures.
Suggested trace strategy:
-- search upstream code for `query` and `self` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+- Study `QueryFusionRetriever` to understand how RRF merges ranked lists from multiple query variants
+- Trace `SubQuestionQueryEngine.query()` to see how sub-questions are generated and then combined with a final synthesis prompt
+- Compare `HierarchicalNodeParser` chunk levels with `AutoMergingRetriever` to understand parent-child node retrieval patterns
## Chapter Connections
diff --git a/tutorials/llamaindex-tutorial/06-custom-components.md b/tutorials/llamaindex-tutorial/06-custom-components.md
index cf25d4cb..5a6ef2d8 100644
--- a/tutorials/llamaindex-tutorial/06-custom-components.md
+++ b/tutorials/llamaindex-tutorial/06-custom-components.md
@@ -12,6 +12,19 @@ Welcome to **Chapter 6: Custom Components**. In this part of **LlamaIndex Tutori
> Build custom loaders, indexes, query engines, and other components for specialized LlamaIndex applications.
+## Custom Component Extension Points
+
+```mermaid
+flowchart TD
+ LLAMA[LlamaIndex] --> EXT[Extension Points]
+ EXT --> CL[Custom BaseReader\nload_data method]
+ EXT --> CNP[Custom NodeParser\nget_nodes_from_documents]
+ EXT --> CE[Custom Embedding\nBaseEmbedding]
+ EXT --> CQE[Custom QueryEngine\nquery method]
+ EXT --> CR[Custom Retriever\nretrieve method]
+ CL --> HUB[Publish to LlamaHub]
+```
+
## 🎯 Overview
This chapter covers creating custom components in LlamaIndex to extend functionality for specific use cases, including custom data loaders, specialized indexes, query engines, and processing pipelines.
@@ -957,12 +970,25 @@ When debugging, walk this sequence in order and confirm each stage has explicit
Use the following upstream sources to verify implementation details while reading this chapter:
-- [View Repo](https://github.com/run-llama/llama_index)
- Why it matters: authoritative reference on `View Repo` (github.com).
+- [`llama_index/core/embeddings/base.py`](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/embeddings/base.py)
+ `BaseEmbedding` abstract class defining `_get_text_embedding()` and `_get_query_embedding()`. Subclass this to implement a custom embedding model by providing a local model or proprietary API.
+
+- [`llama_index/core/llms/llm.py`](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/llms/llm.py)
+ `LLM` base class with `chat()`, `complete()`, and `stream_chat()` abstract methods. Implement these to integrate any custom LLM provider or local model into LlamaIndex pipelines.
+
+- [`llama_index/core/node_parser/interface.py`](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/node_parser/interface.py)
+ `NodeParser` base class and `TextSplitter` mixin. Subclass to implement custom chunking strategies (e.g., code-aware splitting by function boundaries, or domain-specific segmentation).
+
+- [`llama_index/core/postprocessor/types.py`](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/postprocessor/types.py)
+ `BaseNodePostprocessor` interface with `_postprocess_nodes()` method. Implement custom filtering, scoring, or augmentation of retrieved nodes before they reach the response synthesizer.
+
+- [`llama_index/core/storage/kvstore/`](https://github.com/run-llama/llama_index/tree/main/llama-index-core/llama_index/core/storage/kvstore)
+ Key-value store interface used by DocStore and IndexStore. Implement `BaseKVStore` to add a custom persistence backend (e.g., DynamoDB, Cassandra) without changing higher-level components.
Suggested trace strategy:
-- search upstream code for `self` and `node` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+- Implement a minimal `BaseEmbedding` subclass and register it via `Settings.embed_model` to see how the custom embedding integrates with `VectorStoreIndex`
+- Trace `NodeParser._parse_nodes()` to understand the `Document` → `TextNode` boundary contract any custom splitter must satisfy
+- Check `BaseNodePostprocessor._postprocess_nodes()` signature to see what metadata and scores are available for custom re-ranking logic
## Chapter Connections
diff --git a/tutorials/llamaindex-tutorial/07-production-deployment.md b/tutorials/llamaindex-tutorial/07-production-deployment.md
index 407e8a2c..1d760eaf 100644
--- a/tutorials/llamaindex-tutorial/07-production-deployment.md
+++ b/tutorials/llamaindex-tutorial/07-production-deployment.md
@@ -12,6 +12,21 @@ Welcome to **Chapter 7: Production Deployment**. In this part of **LlamaIndex Tu
> Deploy LlamaIndex applications at scale with enterprise-grade reliability and performance.
+## Production Deployment Architecture
+
+```mermaid
+flowchart TD
+ APP[LlamaIndex Application] --> DOCKER[Docker Container]
+ DOCKER --> ORCK[Kubernetes / ECS]
+ ORCK --> LB[Load Balancer]
+ LB --> INST1[Instance 1]
+ LB --> INST2[Instance 2]
+ INST1 --> STORE[Shared Vector Store\nPinecone / Qdrant]
+ INST2 --> STORE
+ INST1 --> CACHE[Redis Cache\nembeddings + responses]
+ INST2 --> CACHE
+```
+
## 🎯 Overview
This chapter covers production deployment strategies for LlamaIndex applications, including containerization, orchestration, scaling, and operational best practices for running RAG systems in production environments.
@@ -1394,12 +1409,22 @@ When debugging, walk this sequence in order and confirm each stage has explicit
Use the following upstream sources to verify implementation details while reading this chapter:
-- [View Repo](https://github.com/run-llama/llama_index)
- Why it matters: authoritative reference on `View Repo` (github.com).
+- [`llama_index/core/callbacks/base.py`](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/callbacks/base.py)
+ `CallbackManager` and `CBEventType` enum. Callbacks fire on events like `RETRIEVE`, `LLM`, `EMBEDDING`, `CHUNKING`, enabling latency tracing and token counting in production. The primary hook for integrating with Langfuse, Arize, or custom observability backends.
+
+- [`llama_index/core/indices/vector_store/base.py`](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/indices/vector_store/base.py)
+ `VectorStoreIndex.as_query_engine()` and `as_retriever()` factory methods with their full parameter sets. Production deployments call these with explicit `similarity_top_k`, `streaming=True`, and metadata filter arguments.
+
+- [`llama_index/core/llms/base.py`](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/llms/base.py)
+ `BaseLLM` with `max_retries`, `timeout`, and `callback_manager` parameters. Production deployments set these explicitly for resilience and observability rather than relying on defaults.
+
+- [`llama_index/core/query_engine/retriever_query_engine.py`](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/query_engine/retriever_query_engine.py)
+ `RetrieverQueryEngine.aquery()` for async production serving. Enables concurrent request handling when deployed behind FastAPI or similar async frameworks.
Suggested trace strategy:
-- search upstream code for `self` and `query` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+- Instrument a production pipeline by passing `CallbackManager([LlamaDebugHandler()])` to `Settings` and reviewing event timings per query
+- Compare sync `query()` vs async `aquery()` throughput to determine when async is required for production latency targets
+- Review `VectorStoreIndex.as_query_engine(streaming=True)` to understand how streaming token responses work end-to-end for real-time UIs
## Chapter Connections
diff --git a/tutorials/llamaindex-tutorial/08-monitoring-optimization.md b/tutorials/llamaindex-tutorial/08-monitoring-optimization.md
index 6b219ea0..3b936ad7 100644
--- a/tutorials/llamaindex-tutorial/08-monitoring-optimization.md
+++ b/tutorials/llamaindex-tutorial/08-monitoring-optimization.md
@@ -12,6 +12,19 @@ Welcome to **Chapter 8: Monitoring & Optimization**. In this part of **LlamaInde
> Master advanced performance tuning, observability, and optimization techniques for production LlamaIndex applications.
+## Observability and Optimization Stack
+
+```mermaid
+flowchart LR
+ APP[LlamaIndex RAG] --> OBS[Observability Layer]
+ OBS --> CB[LlamaIndex Callbacks\nspan timing, token counts]
+ OBS --> ARIZE[Arize Phoenix / Langfuse\ntrace export]
+ APP --> OPT[Optimization Levers]
+ OPT --> EC[Embedding Cache]
+ OPT --> RC[Response Cache\nGPTCache]
+ OPT --> ASYNC[Async Retrieval\nBatch embedding calls]
+```
+
## 🎯 Overview
This final chapter covers advanced monitoring, performance optimization, and operational excellence for LlamaIndex RAG systems. You'll learn to identify bottlenecks, implement advanced caching strategies, optimize for specific use cases, and maintain high-performance production deployments.
@@ -1528,12 +1541,25 @@ When debugging, walk this sequence in order and confirm each stage has explicit
Use the following upstream sources to verify implementation details while reading this chapter:
-- [View Repo](https://github.com/run-llama/llama_index)
- Why it matters: authoritative reference on `View Repo` (github.com).
+- [`llama_index/core/callbacks/llama_debug.py`](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/callbacks/llama_debug.py)
+ `LlamaDebugHandler` that captures per-event timing and payload data. Call `llama_debug.get_event_pairs(CBEventType.LLM)` to inspect token counts and latency for every LLM call in a query trace.
+
+- [`llama_index/core/callbacks/token_counting.py`](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/callbacks/token_counting.py)
+ `TokenCountingHandler` that accumulates prompt/completion token counts across a session. Key for cost tracking and setting budget limits in production pipelines.
+
+- [`llama_index/core/storage/docstore/`](https://github.com/run-llama/llama_index/tree/main/llama-index-core/llama_index/core/storage/docstore)
+ DocStore implementations used to detect document updates and trigger incremental re-indexing. The `hash` field on stored nodes enables change detection for cache invalidation strategies.
+
+- [`llama_index/core/evaluation/`](https://github.com/run-llama/llama_index/tree/main/llama-index-core/llama_index/core/evaluation)
+ Evaluation modules including `FaithfulnessEvaluator`, `RelevancyEvaluator`, `CorrectnessEvaluator`, and `BatchEvalRunner`. These form the automated quality assessment layer for RAG pipeline optimization.
+
+- [`llama_index/core/indices/utils.py`](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/indices/utils.py)
+ Utility functions for chunking and node processing. Contains `log_vector_store_query_result()` that produces the debug output shown in query trace logs.
Suggested trace strategy:
-- search upstream code for `self` and `query` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+- Attach `LlamaDebugHandler` and `TokenCountingHandler` to `Settings.callback_manager` before running a test suite to baseline token consumption per query type
+- Use `FaithfulnessEvaluator` and `RelevancyEvaluator` from `llama_index/core/evaluation/` to build an automated regression suite that catches RAG quality regressions after index updates
+- Inspect `DocStore` node hashes to implement a hash-based incremental re-indexing pipeline that only re-embeds changed documents
## Chapter Connections
diff --git a/tutorials/localai-tutorial/01-getting-started.md b/tutorials/localai-tutorial/01-getting-started.md
index 7ae5cd90..fe710fe1 100644
--- a/tutorials/localai-tutorial/01-getting-started.md
+++ b/tutorials/localai-tutorial/01-getting-started.md
@@ -13,6 +13,19 @@ Welcome to **Chapter 1: Getting Started with LocalAI**. In this part of **LocalA
> Install LocalAI, run your first model, and make your initial API call to the OpenAI-compatible endpoint.
+## LocalAI System Architecture
+
+```mermaid
+flowchart TD
+ CLIENT[OpenAI SDK or curl] -->|HTTP /v1/...| LOCALAI[LocalAI Server :8080]
+ LOCALAI --> ROUTER[Model Router]
+ ROUTER --> LLM[LLM Backend\nllama.cpp, gpt4all]
+ ROUTER --> IMG[Image Backend\nStable Diffusion]
+ ROUTER --> AUDIO[Audio Backend\nWhisper, TTS]
+ ROUTER --> EMB[Embedding Backend\nSentence Transformers]
+ LOCALAI --> GALLERY[Model Gallery\nauto-download + config]
+```
+
## Overview
LocalAI provides a drop-in replacement for OpenAI's API that runs entirely on your local machine. This chapter covers installation, basic setup, and your first local AI inference.
@@ -466,14 +479,22 @@ When debugging, walk this sequence in order and confirm each stage has explicit
Use the following upstream sources to verify implementation details while reading this chapter:
-- [View Repo](https://github.com/mudler/LocalAI)
- Why it matters: authoritative reference on `View Repo` (github.com).
-- [Awesome Code Docs](https://github.com/johnxie/awesome-code-docs)
- Why it matters: authoritative reference on `Awesome Code Docs` (github.com).
+- [`core/http/app.go`](https://github.com/mudler/LocalAI/blob/master/core/http/app.go)
+ Entry point for the LocalAI HTTP server built on Go Fiber. Registers all API routes including `/v1/chat/completions`, `/v1/completions`, `/v1/images/generations`, and health endpoints. This is where OpenAI compatibility is wired in.
+
+- [`core/config/application_config.go`](https://github.com/mudler/LocalAI/blob/master/core/config/application_config.go)
+ `ApplicationConfig` struct holding runtime configuration: model directory, address/port, backend concurrency limits, gallery URLs, and feature flags. This is what `--models-path`, `--address`, and environment variables map to.
+
+- [`core/startup/startup.go`](https://github.com/mudler/LocalAI/blob/master/core/startup/startup.go)
+ Server initialization sequence: loads application config, initializes backend pools, discovers model files, loads gallery index, and starts the HTTP server. Tracing this file gives a complete picture of the startup process.
+
+- [`Makefile`](https://github.com/mudler/LocalAI/blob/master/Makefile)
+ Build targets including `make build`, `make docker`, and backend-specific targets. Shows which C/C++ backends (llama.cpp, whisper, stable-diffusion) are compiled in and what GPU acceleration flags are used.
Suggested trace strategy:
-- search upstream code for `models` and `localai` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+- Start at `core/startup/startup.go` to trace initialization sequence from config loading to HTTP server ready
+- Check `core/http/app.go` route registration to confirm which OpenAI API endpoints are supported
+- Review `core/config/application_config.go` fields to understand all available environment variable overrides
## Chapter Connections
diff --git a/tutorials/localai-tutorial/02-models.md b/tutorials/localai-tutorial/02-models.md
index 593ee9f4..46ff0fa3 100644
--- a/tutorials/localai-tutorial/02-models.md
+++ b/tutorials/localai-tutorial/02-models.md
@@ -13,6 +13,17 @@ Welcome to **Chapter 2: Model Gallery and Management**. In this part of **LocalA
> Discover available models, install different architectures, and manage your local model collection.
+## Model Gallery and Installation Flow
+
+```mermaid
+flowchart LR
+ GALLERY[LocalAI Model Gallery\ngallery.yaml definitions] --> API[POST /models/apply\nwith model id]
+ API --> DOWNLOAD[Auto-download GGUF / weights]
+ DOWNLOAD --> CONFIG[Generate model config YAML]
+ CONFIG --> READY[Model available at /v1/models]
+ MANUAL[Manual: place .gguf + config.yaml\nin models/ directory] --> READY
+```
+
## Overview
LocalAI supports a wide variety of models through its gallery system. This chapter covers model discovery, installation, and management of different model types.
@@ -543,14 +554,22 @@ When debugging, walk this sequence in order and confirm each stage has explicit
Use the following upstream sources to verify implementation details while reading this chapter:
-- [View Repo](https://github.com/mudler/LocalAI)
- Why it matters: authoritative reference on `View Repo` (github.com).
-- [Awesome Code Docs](https://github.com/johnxie/awesome-code-docs)
- Why it matters: authoritative reference on `Awesome Code Docs` (github.com).
+- [`core/gallery/gallery.go`](https://github.com/mudler/LocalAI/blob/master/core/gallery/gallery.go)
+ Gallery system for discovering and installing model presets. Implements `InstallModel()` which downloads YAML model configs and model weights from configured gallery URLs (including the official `localai-gallery`).
+
+- [`core/config/backend_config.go`](https://github.com/mudler/LocalAI/blob/master/core/config/backend_config.go)
+ `BackendConfig` struct that maps to per-model YAML configuration files. Fields include `Backend` (llama-cpp, whisper, diffusers), `Parameters` (temperature, top-p, max_tokens), `GPU` layers, `Threads`, and `ContextSize`. This is the schema for every `models/*.yaml` file.
+
+- [`core/services/gallery.go`](https://github.com/mudler/LocalAI/blob/master/core/services/gallery.go)
+ Gallery service layer connecting HTTP endpoints to gallery operations: list available models, install from gallery, get install status. Powers the `/models/available` and `/models/apply` API endpoints.
+
+- [`core/config/config.go`](https://github.com/mudler/LocalAI/blob/master/core/config/config.go)
+ Config loader that scans the models directory, parses YAML backend configs, and builds the model registry. Shows how LocalAI auto-discovers model files without explicit registration.
Suggested trace strategy:
-- search upstream code for `models` and `model` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+- Read `core/config/backend_config.go` to understand every field available in a model's YAML config file
+- Trace `core/gallery/gallery.go` `InstallModel()` to understand how gallery install downloads both the YAML config and model weights
+- Check `core/config/config.go` `LoadConfigs()` to see how the models directory is scanned and which YAML fields are required vs optional
## Chapter Connections
diff --git a/tutorials/localai-tutorial/03-text-generation.md b/tutorials/localai-tutorial/03-text-generation.md
index 6b2c1e07..3526c5e6 100644
--- a/tutorials/localai-tutorial/03-text-generation.md
+++ b/tutorials/localai-tutorial/03-text-generation.md
@@ -13,6 +13,21 @@ Welcome to **Chapter 3: Text Generation and Chat Completions**. In this part of
> Master text generation with LocalAI using OpenAI-compatible APIs, chat formats, and advanced parameters.
+## Text Generation Request Flow
+
+```mermaid
+sequenceDiagram
+ participant C as Client (openai SDK)
+ participant L as LocalAI Server
+ participant B as llama.cpp Backend
+
+ C->>L: POST /v1/chat/completions\n{model, messages, stream}
+ L->>B: Forward to loaded model
+ B->>L: Token stream
+ L->>C: SSE chunks (if stream=true)
+ L->>C: Final JSON response
+```
+
## Overview
LocalAI provides complete OpenAI API compatibility for text generation. This chapter covers chat completions, parameter tuning, and conversation management.
@@ -609,14 +624,22 @@ When debugging, walk this sequence in order and confirm each stage has explicit
Use the following upstream sources to verify implementation details while reading this chapter:
-- [View Repo](https://github.com/mudler/LocalAI)
- Why it matters: authoritative reference on `View Repo` (github.com).
-- [Awesome Code Docs](https://github.com/johnxie/awesome-code-docs)
- Why it matters: authoritative reference on `Awesome Code Docs` (github.com).
+- [`core/http/endpoints/openai/chat.go`](https://github.com/mudler/LocalAI/blob/master/core/http/endpoints/openai/chat.go)
+ HTTP handler for `POST /v1/chat/completions`. Parses the OpenAI `ChatCompletionRequest`, resolves the model backend, dispatches to the inference engine, and formats the streaming or non-streaming response. The critical file for understanding OpenAI API compatibility.
+
+- [`core/http/endpoints/openai/completion.go`](https://github.com/mudler/LocalAI/blob/master/core/http/endpoints/openai/completion.go)
+ Handler for `POST /v1/completions` (legacy text completion API). Shows how `prompt` parameter maps to the backend inference call, distinct from the chat completions message format.
+
+- [`backend/python/transformers/`](https://github.com/mudler/LocalAI/tree/master/backend/python/transformers)
+ Python gRPC backend for HuggingFace Transformers models. The `backend.py` file shows how LocalAI calls a subprocess gRPC server for Python-based backends, enabling use of any HuggingFace model.
+
+- [`core/backend/llm.go`](https://github.com/mudler/LocalAI/blob/master/core/backend/llm.go)
+ Core LLM inference dispatcher. Routes text generation requests to the appropriate backend (llama-cpp, transformers, vllm, etc.) based on model config. Shows how streaming token callbacks are implemented across backends.
Suggested trace strategy:
-- search upstream code for `content` and `messages` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+- Trace `core/http/endpoints/openai/chat.go` → `core/backend/llm.go` to follow a chat completion request from HTTP parse to backend inference
+- Compare the streaming response format in `chat.go` with `completion.go` to understand SSE chunking implementation
+- Check `backend/python/transformers/backend.py` to see how Python backends communicate with the Go server via gRPC protobuf
## Chapter Connections
diff --git a/tutorials/localai-tutorial/04-image-generation.md b/tutorials/localai-tutorial/04-image-generation.md
index 4ca98ad1..7a57aff5 100644
--- a/tutorials/localai-tutorial/04-image-generation.md
+++ b/tutorials/localai-tutorial/04-image-generation.md
@@ -13,6 +13,17 @@ Welcome to **Chapter 4: Image Generation with Stable Diffusion**. In this part o
> Generate images locally using Stable Diffusion models through LocalAI's OpenAI-compatible API.
+## Image Generation Pipeline
+
+```mermaid
+flowchart LR
+ PROMPT[Text Prompt] --> API[POST /v1/images/generations]
+ API --> SD[Stable Diffusion Backend\nstablediffusion-cpp or diffusers]
+ SD --> STEPS[Denoising Steps\nscheduler: euler, ddim]
+ STEPS --> IMG[Generated Image\nbase64 or URL]
+ IMG --> CLIENT[Client Application]
+```
+
## Overview
LocalAI supports image generation using Stable Diffusion models, providing an OpenAI DALL-E compatible API that runs entirely on your local hardware.
@@ -476,14 +487,22 @@ When debugging, walk this sequence in order and confirm each stage has explicit
Use the following upstream sources to verify implementation details while reading this chapter:
-- [View Repo](https://github.com/mudler/LocalAI)
- Why it matters: authoritative reference on `View Repo` (github.com).
-- [Awesome Code Docs](https://github.com/johnxie/awesome-code-docs)
- Why it matters: authoritative reference on `Awesome Code Docs` (github.com).
+- [`core/http/endpoints/openai/image.go`](https://github.com/mudler/LocalAI/blob/master/core/http/endpoints/openai/image.go)
+ HTTP handler for `POST /v1/images/generations`. Parses the image generation request (prompt, size, n, response_format), dispatches to the image backend, and returns base64 or URL responses matching the OpenAI Images API format.
+
+- [`backend/go/stablediffusion/`](https://github.com/mudler/LocalAI/tree/master/backend/go/stablediffusion)
+ Go-native Stable Diffusion backend using the `go-stable-diffusion` library. The `stablediffusion.go` file shows how the prompt, negative prompt, steps, CFG scale, and seed are passed to the C++ diffusion engine.
+
+- [`backend/python/diffusers/`](https://github.com/mudler/LocalAI/tree/master/backend/python/diffusers)
+ Python HuggingFace Diffusers backend enabling Stable Diffusion XL, FLUX, and other HuggingFace image generation models. Uses gRPC to communicate with the Go server, allowing GPU-accelerated diffusion via PyTorch.
+
+- [`core/backend/image.go`](https://github.com/mudler/LocalAI/blob/master/core/backend/image.go)
+ Image generation backend dispatcher. Routes image requests to either the Go `stablediffusion` backend or the Python `diffusers` backend based on the model's `Backend` config field.
Suggested trace strategy:
-- search upstream code for `stablediffusion` and `model` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+- Trace `core/http/endpoints/openai/image.go` → `core/backend/image.go` to follow an image generation request to the backend
+- Compare `backend/go/stablediffusion/` vs `backend/python/diffusers/` to understand backend selection tradeoffs (native speed vs HuggingFace model support)
+- Check the model YAML `Backend: diffusers` vs `Backend: stable-diffusion` field to understand how LocalAI selects the image generation engine
## Chapter Connections
diff --git a/tutorials/localai-tutorial/05-audio.md b/tutorials/localai-tutorial/05-audio.md
index f7c35392..b38e050d 100644
--- a/tutorials/localai-tutorial/05-audio.md
+++ b/tutorials/localai-tutorial/05-audio.md
@@ -13,6 +13,19 @@ Welcome to **Chapter 5: Audio Processing - Whisper & TTS**. In this part of **Lo
> Transcribe speech to text with Whisper and generate speech with text-to-speech models.
+## Audio Processing Capabilities
+
+```mermaid
+flowchart TD
+ AUDIO[Audio Capabilities] --> STT[Speech-to-Text\nPOST /v1/audio/transcriptions]
+ AUDIO --> TTS[Text-to-Speech\nPOST /v1/audio/speech]
+ STT --> WHISPER[Whisper model\ntiny/base/small/medium/large]
+ TTS --> PIPER[Piper TTS\nlocal neural TTS]
+ TTS --> BARK[Bark\nhigh-quality generative]
+ WHISPER --> TRANSCRIPT[Transcription JSON]
+ PIPER --> MP3[Audio file response]
+```
+
## Overview
LocalAI supports audio processing through Whisper (speech-to-text) and various TTS (text-to-speech) models, all running locally.
@@ -551,14 +564,22 @@ When debugging, walk this sequence in order and confirm each stage has explicit
Use the following upstream sources to verify implementation details while reading this chapter:
-- [View Repo](https://github.com/mudler/LocalAI)
- Why it matters: authoritative reference on `View Repo` (github.com).
-- [Awesome Code Docs](https://github.com/johnxie/awesome-code-docs)
- Why it matters: authoritative reference on `Awesome Code Docs` (github.com).
+- [`core/http/endpoints/openai/transcription.go`](https://github.com/mudler/LocalAI/blob/master/core/http/endpoints/openai/transcription.go)
+ HTTP handler for `POST /v1/audio/transcriptions`. Receives multipart audio file upload, saves to temp file, dispatches to the whisper backend, and returns a JSON transcript matching the OpenAI Audio API format.
+
+- [`backend/go/whisper/`](https://github.com/mudler/LocalAI/tree/master/backend/go/whisper)
+ Go-native Whisper backend using the `go-whisper` library (bindings to whisper.cpp). The `whisper.go` file shows how audio is decoded and passed to the C++ Whisper model for speech-to-text transcription.
+
+- [`core/backend/transcription.go`](https://github.com/mudler/LocalAI/blob/master/core/backend/transcription.go)
+ Transcription backend dispatcher that routes audio transcription requests to the appropriate backend based on the model config's `Backend` field (whisper, faster-whisper, etc.).
+
+- [`core/http/endpoints/localai/tts.go`](https://github.com/mudler/LocalAI/blob/master/core/http/endpoints/localai/tts.go)
+ Text-to-speech endpoint (`POST /tts`). Shows how LocalAI extends the OpenAI API with a TTS endpoint, routing to backends like piper or bark for speech synthesis from text prompts.
Suggested trace strategy:
-- search upstream code for `model` and `audio` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+- Trace `core/http/endpoints/openai/transcription.go` → `core/backend/transcription.go` → `backend/go/whisper/whisper.go` for a complete audio transcription request lifecycle
+- Check the whisper model YAML config for `language`, `threads`, and `translate` parameters that control transcription behavior
+- Compare the whisper Go backend with any Python faster-whisper backend to understand backend selection for latency vs accuracy tradeoffs
## Chapter Connections
diff --git a/tutorials/localai-tutorial/06-embeddings.md b/tutorials/localai-tutorial/06-embeddings.md
index e3cbf2f9..189603cc 100644
--- a/tutorials/localai-tutorial/06-embeddings.md
+++ b/tutorials/localai-tutorial/06-embeddings.md
@@ -13,6 +13,19 @@ Welcome to **Chapter 6: Vector Embeddings for RAG**. In this part of **LocalAI T
> Generate embeddings locally and build semantic search applications with LocalAI.
+## Embeddings and RAG Flow
+
+```mermaid
+flowchart LR
+ TEXT[Text Input] --> API[POST /v1/embeddings\nmodel: all-minilm-l6-v2]
+ API --> EMB[Embedding Model\nSentence Transformers]
+ EMB --> VEC[Float Vector\n384 or 768 dims]
+ VEC --> VS[Vector Store\nChroma / Qdrant]
+ VS --> SEARCH[Similarity Search]
+ SEARCH --> CTX[Retrieved Context]
+ CTX --> LLM[LLM Generation\n/v1/chat/completions]
+```
+
## Overview
LocalAI supports various embedding models for generating vector representations of text, enabling semantic search and RAG (Retrieval-Augmented Generation) applications.
@@ -538,14 +551,22 @@ When debugging, walk this sequence in order and confirm each stage has explicit
Use the following upstream sources to verify implementation details while reading this chapter:
-- [View Repo](https://github.com/mudler/LocalAI)
- Why it matters: authoritative reference on `View Repo` (github.com).
-- [Awesome Code Docs](https://github.com/johnxie/awesome-code-docs)
- Why it matters: authoritative reference on `Awesome Code Docs` (github.com).
+- [`core/http/endpoints/openai/embeddings.go`](https://github.com/mudler/LocalAI/blob/master/core/http/endpoints/openai/embeddings.go)
+ HTTP handler for `POST /v1/embeddings`. Accepts the OpenAI embeddings request format (input text, model name), dispatches to the embeddings backend, and returns float vector arrays in the OpenAI API response shape.
+
+- [`core/backend/embeddings.go`](https://github.com/mudler/LocalAI/blob/master/core/backend/embeddings.go)
+ Embeddings backend dispatcher. Routes embedding requests to the appropriate backend - llama.cpp (which supports embedding generation for GGUF models), bert.cpp, or Python sentence-transformers via gRPC.
+
+- [`backend/python/sentencetransformers/`](https://github.com/mudler/LocalAI/tree/master/backend/python/sentencetransformers)
+ Python backend for HuggingFace sentence-transformers. Enables high-quality embedding models like `all-MiniLM-L6-v2`, `BGE`, and `E5` without converting to GGUF format.
+
+- [`core/config/backend_config.go`](https://github.com/mudler/LocalAI/blob/master/core/config/backend_config.go)
+ `BackendConfig.Embeddings` field enables embedding mode for a model. When set to `true`, the model is treated as an embedding-only model and the `/v1/embeddings` endpoint is activated for it.
Suggested trace strategy:
-- search upstream code for `self` and `documents` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+- Trace `core/http/endpoints/openai/embeddings.go` → `core/backend/embeddings.go` to follow an embedding request to backend dispatch
+- Compare llama.cpp embedding mode (GGUF model with `embeddings: true`) vs the Python sentence-transformers backend for model support and performance tradeoffs
+- Check model YAML config `embeddings: true` flag to understand how LocalAI selects the embedding pipeline for a given model name
## Chapter Connections
diff --git a/tutorials/localai-tutorial/07-configuration.md b/tutorials/localai-tutorial/07-configuration.md
index e9baca0f..623227ba 100644
--- a/tutorials/localai-tutorial/07-configuration.md
+++ b/tutorials/localai-tutorial/07-configuration.md
@@ -13,6 +13,18 @@ Welcome to **Chapter 7: Advanced Configuration and Tuning**. In this part of **L
> Optimize LocalAI performance with advanced configuration options, hardware tuning, and production settings.
+## Configuration Hierarchy
+
+```mermaid
+flowchart TD
+ CONF[LocalAI Configuration] --> ENV[Environment Variables\nTHREADS, DEBUG, etc.]
+ CONF --> YAML[Model Config YAML\nper-model parameters]
+ CONF --> CLI[CLI Flags\n--models-path, --port]
+ YAML --> PARAM[inference parameters\nctx-size, batch, GPU layers]
+ YAML --> TMPL[Prompt Templates\nchat format, system prompt]
+ YAML --> BACK[Backend Selection\nllama.cpp, exllama2]
+```
+
## Overview
LocalAI offers extensive configuration options for performance tuning, hardware optimization, and production deployment.
@@ -625,14 +637,22 @@ When debugging, walk this sequence in order and confirm each stage has explicit
Use the following upstream sources to verify implementation details while reading this chapter:
-- [View Repo](https://github.com/mudler/LocalAI)
- Why it matters: authoritative reference on `View Repo` (github.com).
-- [Awesome Code Docs](https://github.com/johnxie/awesome-code-docs)
- Why it matters: authoritative reference on `Awesome Code Docs` (github.com).
+- [`core/config/backend_config.go`](https://github.com/mudler/LocalAI/blob/master/core/config/backend_config.go)
+ The authoritative definition of every field in per-model YAML configuration files. `BackendConfig` fields include `ContextSize`, `Threads`, `GPU` (number of GPU layers), `F16`, `NUMA`, `Rope*`, `ModelPath`, `PromptCachePath`, and generation parameters. This is the schema reference for all advanced tuning.
+
+- [`core/config/application_config.go`](https://github.com/mudler/LocalAI/blob/master/core/config/application_config.go)
+ Global server configuration. Controls `ConcurrentRequests` (parallelism), `ContextSize` (default context window), `Threads` (default CPU threads), `ModelsPath`, `UploadDir`, `ImageDir`, and feature flags like `DisableGallery` and `SingleActiveBackend`.
+
+- [`core/config/config_loader.go`](https://github.com/mudler/LocalAI/blob/master/core/config/config_loader.go)
+ Config loader that merges application defaults with per-model YAML overrides. Shows the priority order: CLI flags → environment variables → per-model YAML → built-in defaults. Critical for understanding how settings propagate.
+
+- [`core/http/middleware/`](https://github.com/mudler/LocalAI/tree/master/core/http/middleware)
+ HTTP middleware including API key authentication (`auth.go`), CORS configuration, and request logging. The auth middleware reads the `API_KEY` environment variable or `--api-key` flag to enforce bearer token authentication.
Suggested trace strategy:
-- search upstream code for `enabled` and `localai` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+- Read `core/config/backend_config.go` to find the exact YAML key names for GPU offloading (`gpu-layers`), context size, and generation parameters
+- Trace `core/config/config_loader.go` `LoadConfigs()` to understand config merge priority and which fields can be overridden per-model
+- Check `core/http/middleware/auth.go` to understand how API key validation works and what happens on unauthorized requests
## Chapter Connections
diff --git a/tutorials/localai-tutorial/08-integration.md b/tutorials/localai-tutorial/08-integration.md
index 5b13406c..42397b2d 100644
--- a/tutorials/localai-tutorial/08-integration.md
+++ b/tutorials/localai-tutorial/08-integration.md
@@ -13,6 +13,19 @@ Welcome to **Chapter 8: Production Integration and Applications**. In this part
> Build production applications with LocalAI, integrating with web frameworks, APIs, and enterprise systems.
+## Integration Architecture
+
+```mermaid
+flowchart TD
+ APP[Application] --> OACLIENT[OpenAI SDK\nbase_url=http://localhost:8080/v1]
+ OACLIENT --> LOCALAI[LocalAI Server]
+ APP --> LCHAIN[LangChain\nChatOpenAI with custom base_url]
+ LCHAIN --> LOCALAI
+ APP --> LLAMAIDX[LlamaIndex\nOpenAILike LLM]
+ LLAMAIDX --> LOCALAI
+ LOCALAI --> MODELS[Local Models\nno data leaves your machine]
+```
+
## Overview
LocalAI's OpenAI-compatible API makes it easy to integrate into existing applications. This chapter covers production integration patterns and real-world applications.
@@ -823,14 +836,22 @@ When debugging, walk this sequence in order and confirm each stage has explicit
Use the following upstream sources to verify implementation details while reading this chapter:
-- [View Repo](https://github.com/mudler/LocalAI)
- Why it matters: authoritative reference on `View Repo` (github.com).
-- [Awesome Code Docs](https://github.com/johnxie/awesome-code-docs)
- Why it matters: authoritative reference on `Awesome Code Docs` (github.com).
+- [`core/http/app.go`](https://github.com/mudler/LocalAI/blob/master/core/http/app.go)
+ All registered API routes including the OpenAI-compatible endpoints (`/v1/*`) and LocalAI-specific endpoints (`/tts`, `/v1/rerank`). This is the integration surface - any client using the OpenAI SDK can point its `base_url` to LocalAI and use all registered routes.
+
+- [`core/http/endpoints/openai/`](https://github.com/mudler/LocalAI/tree/master/core/http/endpoints/openai)
+ Full collection of OpenAI-compatible endpoint handlers: `chat.go`, `completion.go`, `embeddings.go`, `image.go`, `transcription.go`, `files.go`, `models.go`. These are the integration points for any OpenAI SDK (Python, Node.js, Go) or tool (LangChain, LlamaIndex) that uses the OpenAI protocol.
+
+- [`docker-compose.yaml`](https://github.com/mudler/LocalAI/blob/master/docker-compose.yaml)
+ Reference Docker Compose configuration showing volume mounts for models directory, environment variable injection for `API_KEY`, `THREADS`, `CONTEXT_SIZE`, and GPU device access via `deploy.resources.reservations`. Use this as the production deployment template.
+
+- [`examples/`](https://github.com/mudler/LocalAI/tree/master/examples)
+ Integration examples including LangChain, OpenAI SDK usage, function calling demos, and RAG pipeline examples. Reference these for concrete integration patterns with popular frameworks.
Suggested trace strategy:
-- search upstream code for `model` and `response` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+- Review `core/http/app.go` route list to confirm which OpenAI API versions and endpoints are supported before writing integration code
+- Use `docker-compose.yaml` as the baseline for production container configuration, adding GPU device reservations and volume mounts for your models directory
+- Check `examples/` for working code snippets showing LangChain and LlamaIndex integration pointing to a LocalAI base URL
## Chapter Connections
diff --git a/tutorials/logseq-tutorial/01-knowledge-management-principles.md b/tutorials/logseq-tutorial/01-knowledge-management-principles.md
index 69763392..c0aeb0f2 100644
--- a/tutorials/logseq-tutorial/01-knowledge-management-principles.md
+++ b/tutorials/logseq-tutorial/01-knowledge-management-principles.md
@@ -6,6 +6,7 @@ has_children: false
parent: "Logseq Knowledge Management"
---
+
# Chapter 1: Knowledge Management Philosophy
Welcome to **Chapter 1: Knowledge Management Philosophy**. In this part of **Logseq: Deep Dive Tutorial**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
@@ -526,94 +527,184 @@ Suggested trace strategy:
## Depth Expansion Playbook
-<!-- depth-expansion-v2 -->
-
-This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
-
-### Strategic Context
-
-- tutorial: **Logseq: Deep Dive Tutorial**
-- tutorial slug: **logseq-tutorial**
-- chapter focus: **Chapter 1: Knowledge Management Philosophy**
-- system context: **Logseq Knowledge Management**
-- objective: move from surface-level usage to repeatable engineering operation
-
-### Architecture Decomposition
-
-1. Define the runtime boundary for `Chapter 1: Knowledge Management Philosophy`.
-2. Separate control-plane decisions from data-plane execution.
-3. Capture input contracts, transformation points, and output contracts.
-4. Trace state transitions across request lifecycle stages.
-5. Identify extension hooks and policy interception points.
-6. Map ownership boundaries for team and automation workflows.
-7. Specify rollback and recovery paths for unsafe changes.
-8. Track observability signals for correctness, latency, and cost.
-
-### Operator Decision Matrix
-
-| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
-|:--------------|:--------------|:------------------|:---------|
-| Runtime mode | managed defaults | explicit policy config | speed vs control |
-| State handling | local ephemeral | durable persisted state | simplicity vs auditability |
-| Tool integration | direct API use | mediated adapter layer | velocity vs governance |
-| Rollout method | manual change | staged + canary rollout | effort vs safety |
-| Incident response | best effort logs | runbooks + SLO alerts | cost vs reliability |
-
-### Failure Modes and Countermeasures
-
-| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
-|:-------------|:-------------|:-------------------|:---------------|
-| stale context | inconsistent outputs | missing refresh window | enforce context TTL and refresh hooks |
-| policy drift | unexpected execution | ad hoc overrides | centralize policy profiles |
-| auth mismatch | 401/403 bursts | credential sprawl | rotation schedule + scope minimization |
-| schema breakage | parser/validation errors | unmanaged upstream changes | contract tests per release |
-| retry storms | queue congestion | no backoff controls | jittered backoff + circuit breakers |
-| silent regressions | quality drop without alerts | weak baseline metrics | eval harness with thresholds |
-
-### Implementation Runbook
-
-1. Establish a reproducible baseline environment.
-2. Capture chapter-specific success criteria before changes.
-3. Implement minimal viable path with explicit interfaces.
-4. Add observability before expanding feature scope.
-5. Run deterministic tests for happy-path behavior.
-6. Inject failure scenarios for negative-path validation.
-7. Compare output quality against baseline snapshots.
-8. Promote through staged environments with rollback gates.
-9. Record operational lessons in release notes.
-
-### Quality Gate Checklist
-
-- [ ] chapter-level assumptions are explicit and testable
-- [ ] API/tool boundaries are documented with input/output examples
-- [ ] failure handling includes retry, timeout, and fallback policy
-- [ ] security controls include auth scopes and secret rotation plans
-- [ ] observability includes logs, metrics, traces, and alert thresholds
-- [ ] deployment guidance includes canary and rollback paths
-- [ ] docs include links to upstream sources and related tracks
-- [ ] post-release verification confirms expected behavior under load
-
-### Source Alignment
+## Source Code Walkthrough
+
+### `tailwind.config.js`
+
+The `exposeColorsToCssVars` function in [`tailwind.config.js`](https://github.com/logseq/logseq/blob/HEAD/tailwind.config.js) handles a key part of this chapter's functionality:
+
+```js
+}
+
+function exposeColorsToCssVars ({ addBase, theme }) {
+ function extractColorVars (colorObj, colorGroup = '') {
+ return Object.keys(colorObj).reduce((vars, colorKey) => {
+ const value = colorObj[colorKey]
+
+ const newVars =
+ typeof value === 'string'
+ ? { [`--color${colorGroup}-${colorKey}`]: value }
+ : extractColorVars(value, `-${colorKey}`)
+
+ return { ...vars, ...newVars }
+ }, {})
+ }
+
+ addBase({
+ ':root': extractColorVars(theme('colors')),
+ })
+}
+
+const withOverride = plugin(function ({ matchUtilities }) {
+ matchUtilities({
+ 'or': (value, b) => {
+ // check if the value starts with "bg-"
+ if (value.startsWith('bg-')) {
+ return { [`--lx-bg-override`]: `var(--lx-${value})` }
+ }
+ // check if the value starts with "text-"
+ if (value.startsWith('text-')) {
+ return { [`--lx-text-override`]: `var(--lx-${value})` }
+ }
+```
-- [Logseq](https://github.com/logseq/logseq)
-- [AI Codebase Knowledge Builder](https://github.com/The-Pocket/Tutorial-Codebase-Knowledge)
+This function is important because it defines how Logseq: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+### `tailwind.config.js`
+
+The `extractColorVars` function in [`tailwind.config.js`](https://github.com/logseq/logseq/blob/HEAD/tailwind.config.js) handles a key part of this chapter's functionality:
+
+```js
+
+function exposeColorsToCssVars ({ addBase, theme }) {
+ function extractColorVars (colorObj, colorGroup = '') {
+ return Object.keys(colorObj).reduce((vars, colorKey) => {
+ const value = colorObj[colorKey]
+
+ const newVars =
+ typeof value === 'string'
+ ? { [`--color${colorGroup}-${colorKey}`]: value }
+ : extractColorVars(value, `-${colorKey}`)
+
+ return { ...vars, ...newVars }
+ }, {})
+ }
+
+ addBase({
+ ':root': extractColorVars(theme('colors')),
+ })
+}
+
+const withOverride = plugin(function ({ matchUtilities }) {
+ matchUtilities({
+ 'or': (value, b) => {
+ // check if the value starts with "bg-"
+ if (value.startsWith('bg-')) {
+ return { [`--lx-bg-override`]: `var(--lx-${value})` }
+ }
+ // check if the value starts with "text-"
+ if (value.startsWith('text-')) {
+ return { [`--lx-text-override`]: `var(--lx-${value})` }
+ }
+ // check if the value starts with "border-"
+```
-### Cross-Tutorial Connection Map
+This function is important because it defines how Logseq: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+### `tailwind.config.js`
+
+The `mapRadixColorToTailwind` function in [`tailwind.config.js`](https://github.com/logseq/logseq/blob/HEAD/tailwind.config.js) handles a key part of this chapter's functionality:
+
+```js
+})
+
+function mapRadixColorToTailwind (color) {
+ const radixColor = radix[color]
+ if (!radixColor) throw new Error(`[radix color] not exist for ${color}`)
+ const twSteps = [10, 50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950]
+ const rxSteps = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]
+ const colors = {}
+
+ twSteps.forEach((twStep, index) => {
+ const rxStep = rxSteps[index]
+ // base color
+ colors[twStep] = radixColor[`${color}${rxStep}`]
+ // theme vars color
+ const rxStepName = `${(rxStep < 10) ? '0' : ''}${rxStep}`
+ const rxVarName = `--rx-${color}-${rxStepName}`
+ colors[`rx-${rxStepName}`] = `var(${rxVarName})`
+ colors[`rx-${rxStepName}-alpha`] = `var(${rxVarName}-alpha)`
+ })
+
+ return colors
+}
+
+module.exports = {
+ darkMode: 'class',
+ content: [
+ './src/**/*.js',
+ './src/**/*.cljs',
+ './resources/**/*.html',
+ './deps/shui/src/**/*.cljs',
+ './deps/shui/src/**/*.cljc',
+ './packages/ui/@/components/**/*.{ts,tsx}',
+```
-- Related tutorials are listed in this tutorial index.
+This function is important because it defines how Logseq: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+### `libs/src/LSPlugin.user.ts`
+
+The `LSPluginUser` class in [`libs/src/LSPlugin.user.ts`](https://github.com/logseq/logseq/blob/HEAD/libs/src/LSPlugin.user.ts) handles a key part of this chapter's functionality:
+
+```ts
+ IDBProxy,
+ IEditorProxy,
+ ILSPluginUser,
+ LSPluginBaseInfo,
+ LSPluginUserEvents,
+ SlashCommandAction,
+ BlockCommandCallback,
+ StyleString,
+ Theme,
+ UIOptions,
+ IHookEvent,
+ BlockIdentity,
+ BlockPageName,
+ UIContainerAttrs,
+ SimpleCommandCallback,
+ SimpleCommandKeybinding,
+ SettingSchemaDesc,
+ IUserOffHook,
+ IGitProxy,
+ IUIProxy,
+ UserProxyNSTags,
+ BlockUUID,
+ BlockEntity,
+ IDatom,
+ IAssetsProxy,
+ AppInfo,
+ IPluginSearchServiceHooks,
+ PageEntity, IUtilsProxy,
+} from './LSPlugin'
+import Debug from 'debug'
+import * as CSS from 'csstype'
+import EventEmitter from 'eventemitter3'
+```
-### Advanced Practice Exercises
+This class is important because it defines how Logseq: Deep Dive Tutorial implements the patterns covered in this chapter.
-1. Build a minimal end-to-end implementation for `Chapter 1: Knowledge Management Philosophy`.
-2. Add instrumentation and measure baseline latency and error rate.
-3. Introduce one controlled failure and confirm graceful recovery.
-4. Add policy constraints and verify they are enforced consistently.
-5. Run a staged rollout and document rollback decision criteria.
-### Review Questions
+## How These Components Connect
-1. Which execution boundary matters most for this chapter and why?
-2. What signal detects regressions earliest in your environment?
-3. What tradeoff did you make between delivery speed and governance?
-4. How would you recover from the highest-impact failure mode?
-5. What must be automated before scaling to team-wide adoption?
+```mermaid
+flowchart TD
+ A[exposeColorsToCssVars]
+ B[extractColorVars]
+ C[mapRadixColorToTailwind]
+ D[LSPluginUser]
+ E[registerSimpleCommand]
+ A --> B
+ B --> C
+ C --> D
+ D --> E
+```
diff --git a/tutorials/logseq-tutorial/02-system-architecture.md b/tutorials/logseq-tutorial/02-system-architecture.md
index 11f85b83..0ebb3d06 100644
--- a/tutorials/logseq-tutorial/02-system-architecture.md
+++ b/tutorials/logseq-tutorial/02-system-architecture.md
@@ -6,6 +6,7 @@ has_children: false
parent: "Logseq Knowledge Management"
---
+
# Chapter 2: System Architecture
Welcome to **Chapter 2: System Architecture**. In this part of **Logseq: Deep Dive Tutorial**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
@@ -95,490 +96,184 @@ Suggested trace strategy:
## Depth Expansion Playbook
-<!-- depth-expansion-v2 -->
-
-This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
-
-### Strategic Context
-
-- tutorial: **Logseq: Deep Dive Tutorial**
-- tutorial slug: **logseq-tutorial**
-- chapter focus: **Chapter 2: System Architecture**
-- system context: **Logseq Knowledge Management**
-- objective: move from surface-level usage to repeatable engineering operation
-
-### Architecture Decomposition
-
-1. Define the runtime boundary for `Chapter 2: System Architecture`.
-2. Separate control-plane decisions from data-plane execution.
-3. Capture input contracts, transformation points, and output contracts.
-4. Trace state transitions across request lifecycle stages.
-5. Identify extension hooks and policy interception points.
-6. Map ownership boundaries for team and automation workflows.
-7. Specify rollback and recovery paths for unsafe changes.
-8. Track observability signals for correctness, latency, and cost.
-
-### Operator Decision Matrix
-
-| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
-|:--------------|:--------------|:------------------|:---------|
-| Runtime mode | managed defaults | explicit policy config | speed vs control |
-| State handling | local ephemeral | durable persisted state | simplicity vs auditability |
-| Tool integration | direct API use | mediated adapter layer | velocity vs governance |
-| Rollout method | manual change | staged + canary rollout | effort vs safety |
-| Incident response | best effort logs | runbooks + SLO alerts | cost vs reliability |
-
-### Failure Modes and Countermeasures
-
-| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
-|:-------------|:-------------|:-------------------|:---------------|
-| stale context | inconsistent outputs | missing refresh window | enforce context TTL and refresh hooks |
-| policy drift | unexpected execution | ad hoc overrides | centralize policy profiles |
-| auth mismatch | 401/403 bursts | credential sprawl | rotation schedule + scope minimization |
-| schema breakage | parser/validation errors | unmanaged upstream changes | contract tests per release |
-| retry storms | queue congestion | no backoff controls | jittered backoff + circuit breakers |
-| silent regressions | quality drop without alerts | weak baseline metrics | eval harness with thresholds |
-
-### Implementation Runbook
-
-1. Establish a reproducible baseline environment.
-2. Capture chapter-specific success criteria before changes.
-3. Implement minimal viable path with explicit interfaces.
-4. Add observability before expanding feature scope.
-5. Run deterministic tests for happy-path behavior.
-6. Inject failure scenarios for negative-path validation.
-7. Compare output quality against baseline snapshots.
-8. Promote through staged environments with rollback gates.
-9. Record operational lessons in release notes.
-
-### Quality Gate Checklist
-
-- [ ] chapter-level assumptions are explicit and testable
-- [ ] API/tool boundaries are documented with input/output examples
-- [ ] failure handling includes retry, timeout, and fallback policy
-- [ ] security controls include auth scopes and secret rotation plans
-- [ ] observability includes logs, metrics, traces, and alert thresholds
-- [ ] deployment guidance includes canary and rollback paths
-- [ ] docs include links to upstream sources and related tracks
-- [ ] post-release verification confirms expected behavior under load
-
-### Source Alignment
+## Source Code Walkthrough
+
+### `libs/src/LSPlugin.user.ts`
+
+The `Window` interface in [`libs/src/LSPlugin.user.ts`](https://github.com/logseq/logseq/blob/HEAD/libs/src/LSPlugin.user.ts) handles a key part of this chapter's functionality:
+
+```ts
+
+declare global {
+ interface Window {
+ __LSP__HOST__: boolean
+ logseq: LSPluginUser
+ }
+}
+
+type callableMethods = keyof typeof callableAPIs | string // host exported SDK apis & host platform related apis
+
+const PROXY_CONTINUE = Symbol.for('proxy-continue')
+const debug = Debug('LSPlugin:user')
+const logger = new PluginLogger('', { console: true })
+
+/**
+ * @param type (key of group commands)
+ * @param opts
+ * @param action
+ */
+function registerSimpleCommand(
+ this: LSPluginUser,
+ type: string,
+ opts: {
+ key: string
+ label: string
+ desc?: string
+ palette?: boolean
+ keybinding?: SimpleCommandKeybinding
+ extras?: Record<string, any>
+ },
+ action: SimpleCommandCallback
+) {
+```
-- [Logseq](https://github.com/logseq/logseq)
-- [AI Codebase Knowledge Builder](https://github.com/The-Pocket/Tutorial-Codebase-Knowledge)
-
-### Cross-Tutorial Connection Map
-
-- Related tutorials are listed in this tutorial index.
-
-### Advanced Practice Exercises
-
-1. Build a minimal end-to-end implementation for `Chapter 2: System Architecture`.
-2. Add instrumentation and measure baseline latency and error rate.
-3. Introduce one controlled failure and confirm graceful recovery.
-4. Add policy constraints and verify they are enforced consistently.
-5. Run a staged rollout and document rollback decision criteria.
-
-### Review Questions
-
-1. Which execution boundary matters most for this chapter and why?
-2. What signal detects regressions earliest in your environment?
-3. What tradeoff did you make between delivery speed and governance?
-4. How would you recover from the highest-impact failure mode?
-5. What must be automated before scaling to team-wide adoption?
-
-### Scenario Playbook 1: Chapter 2: System Architecture
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 2: Chapter 2: System Architecture
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 3: Chapter 2: System Architecture
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 4: Chapter 2: System Architecture
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 5: Chapter 2: System Architecture
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 6: Chapter 2: System Architecture
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 7: Chapter 2: System Architecture
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 8: Chapter 2: System Architecture
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 9: Chapter 2: System Architecture
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 10: Chapter 2: System Architecture
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 11: Chapter 2: System Architecture
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 12: Chapter 2: System Architecture
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 13: Chapter 2: System Architecture
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 14: Chapter 2: System Architecture
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 15: Chapter 2: System Architecture
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 16: Chapter 2: System Architecture
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 17: Chapter 2: System Architecture
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 18: Chapter 2: System Architecture
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 19: Chapter 2: System Architecture
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 20: Chapter 2: System Architecture
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 21: Chapter 2: System Architecture
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 22: Chapter 2: System Architecture
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 23: Chapter 2: System Architecture
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 24: Chapter 2: System Architecture
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 25: Chapter 2: System Architecture
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 26: Chapter 2: System Architecture
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 27: Chapter 2: System Architecture
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 28: Chapter 2: System Architecture
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 29: Chapter 2: System Architecture
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 30: Chapter 2: System Architecture
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 31: Chapter 2: System Architecture
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 32: Chapter 2: System Architecture
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 33: Chapter 2: System Architecture
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
+This interface is important because it defines how Logseq: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+### `libs/src/LSPlugin.core.ts`
+
+The `PluginSettings` class in [`libs/src/LSPlugin.core.ts`](https://github.com/logseq/logseq/blob/HEAD/libs/src/LSPlugin.core.ts) handles a key part of this chapter's functionality:
+
+```ts
+ * User settings
+ */
+class PluginSettings extends EventEmitter<'change' | 'reset'> {
+ private _settings: Record<string, any> = {
+ disabled: false,
+ }
+
+ constructor(
+ private readonly _userPluginSettings: any,
+ private _schema?: SettingSchemaDesc[]
+ ) {
+ super()
+
+ Object.assign(this._settings, _userPluginSettings)
+ }
+
+ get<T = any>(k: string): T {
+ return this._settings[k]
+ }
+
+ set(k: string | Record<string, any>, v?: any) {
+ const o = deepMerge({}, this._settings)
+
+ if (typeof k === 'string') {
+ if (this._settings[k] == v) return
+ this._settings[k] = v
+ } else if (isObject(k)) {
+ this._settings = deepMerge(this._settings, k)
+ } else {
+ return
+ }
+
+```
+
+This class is important because it defines how Logseq: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+### `libs/src/LSPlugin.core.ts`
+
+The `IllegalPluginPackageError` class in [`libs/src/LSPlugin.core.ts`](https://github.com/logseq/logseq/blob/HEAD/libs/src/LSPlugin.core.ts) handles a key part of this chapter's functionality:
+
+```ts
+}
+
+class IllegalPluginPackageError extends Error {
+ constructor(message: string) {
+ super(message)
+ this.name = 'IllegalPluginPackageError'
+ }
+}
+
+class ExistedImportedPluginPackageError extends Error {
+ constructor(message: string) {
+ super(message)
+ this.name = 'ExistedImportedPluginPackageError'
+ }
+}
+
+/**
+ * Host plugin for local
+ */
+class PluginLocal extends EventEmitter<
+ 'loaded' | 'unloaded' | 'beforeunload' | 'error' | string
+> {
+ private _sdk: Partial<PluginLocalSDKMetadata> = {}
+ private _disposes: Array<() => Promise<any>> = []
+ private _id: PluginLocalIdentity
+ private _status: PluginLocalLoadStatus = PluginLocalLoadStatus.UNLOADED
+ private _loadErr?: Error
+ private _localRoot?: string
+ private _dotSettingsFile?: string
+ private _caller?: LSPluginCaller
+ private _logger?: PluginLogger = new PluginLogger('PluginLocal')
+
+```
+
+This class is important because it defines how Logseq: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+### `libs/src/LSPlugin.core.ts`
+
+The `ExistedImportedPluginPackageError` class in [`libs/src/LSPlugin.core.ts`](https://github.com/logseq/logseq/blob/HEAD/libs/src/LSPlugin.core.ts) handles a key part of this chapter's functionality:
+
+```ts
+}
+
+class ExistedImportedPluginPackageError extends Error {
+ constructor(message: string) {
+ super(message)
+ this.name = 'ExistedImportedPluginPackageError'
+ }
+}
+
+/**
+ * Host plugin for local
+ */
+class PluginLocal extends EventEmitter<
+ 'loaded' | 'unloaded' | 'beforeunload' | 'error' | string
+> {
+ private _sdk: Partial<PluginLocalSDKMetadata> = {}
+ private _disposes: Array<() => Promise<any>> = []
+ private _id: PluginLocalIdentity
+ private _status: PluginLocalLoadStatus = PluginLocalLoadStatus.UNLOADED
+ private _loadErr?: Error
+ private _localRoot?: string
+ private _dotSettingsFile?: string
+ private _caller?: LSPluginCaller
+ private _logger?: PluginLogger = new PluginLogger('PluginLocal')
+
+ /**
+ * @param _options
+ * @param _themeMgr
+ * @param _ctx
+ */
+ constructor(
+ private _options: PluginLocalOptions,
+```
+
+This class is important because it defines how Logseq: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+
+## How These Components Connect
+
+```mermaid
+flowchart TD
+ A[Window]
+ B[PluginSettings]
+ C[IllegalPluginPackageError]
+ D[ExistedImportedPluginPackageError]
+ E[PluginLocal]
+ A --> B
+ B --> C
+ C --> D
+ D --> E
+```
diff --git a/tutorials/logseq-tutorial/03-local-first-data.md b/tutorials/logseq-tutorial/03-local-first-data.md
index f1c6532b..fceed38b 100644
--- a/tutorials/logseq-tutorial/03-local-first-data.md
+++ b/tutorials/logseq-tutorial/03-local-first-data.md
@@ -6,6 +6,7 @@ has_children: false
parent: "Logseq Knowledge Management"
---
+
# Chapter 3: Local-First Data
Welcome to **Chapter 3: Local-First Data**. In this part of **Logseq: Deep Dive Tutorial**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
@@ -96,490 +97,165 @@ Suggested trace strategy:
## Depth Expansion Playbook
-<!-- depth-expansion-v2 -->
-
-This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
-
-### Strategic Context
-
-- tutorial: **Logseq: Deep Dive Tutorial**
-- tutorial slug: **logseq-tutorial**
-- chapter focus: **Chapter 3: Local-First Data**
-- system context: **Logseq Knowledge Management**
-- objective: move from surface-level usage to repeatable engineering operation
-
-### Architecture Decomposition
-
-1. Define the runtime boundary for `Chapter 3: Local-First Data`.
-2. Separate control-plane decisions from data-plane execution.
-3. Capture input contracts, transformation points, and output contracts.
-4. Trace state transitions across request lifecycle stages.
-5. Identify extension hooks and policy interception points.
-6. Map ownership boundaries for team and automation workflows.
-7. Specify rollback and recovery paths for unsafe changes.
-8. Track observability signals for correctness, latency, and cost.
-
-### Operator Decision Matrix
-
-| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
-|:--------------|:--------------|:------------------|:---------|
-| Runtime mode | managed defaults | explicit policy config | speed vs control |
-| State handling | local ephemeral | durable persisted state | simplicity vs auditability |
-| Tool integration | direct API use | mediated adapter layer | velocity vs governance |
-| Rollout method | manual change | staged + canary rollout | effort vs safety |
-| Incident response | best effort logs | runbooks + SLO alerts | cost vs reliability |
-
-### Failure Modes and Countermeasures
-
-| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
-|:-------------|:-------------|:-------------------|:---------------|
-| stale context | inconsistent outputs | missing refresh window | enforce context TTL and refresh hooks |
-| policy drift | unexpected execution | ad hoc overrides | centralize policy profiles |
-| auth mismatch | 401/403 bursts | credential sprawl | rotation schedule + scope minimization |
-| schema breakage | parser/validation errors | unmanaged upstream changes | contract tests per release |
-| retry storms | queue congestion | no backoff controls | jittered backoff + circuit breakers |
-| silent regressions | quality drop without alerts | weak baseline metrics | eval harness with thresholds |
-
-### Implementation Runbook
-
-1. Establish a reproducible baseline environment.
-2. Capture chapter-specific success criteria before changes.
-3. Implement minimal viable path with explicit interfaces.
-4. Add observability before expanding feature scope.
-5. Run deterministic tests for happy-path behavior.
-6. Inject failure scenarios for negative-path validation.
-7. Compare output quality against baseline snapshots.
-8. Promote through staged environments with rollback gates.
-9. Record operational lessons in release notes.
-
-### Quality Gate Checklist
-
-- [ ] chapter-level assumptions are explicit and testable
-- [ ] API/tool boundaries are documented with input/output examples
-- [ ] failure handling includes retry, timeout, and fallback policy
-- [ ] security controls include auth scopes and secret rotation plans
-- [ ] observability includes logs, metrics, traces, and alert thresholds
-- [ ] deployment guidance includes canary and rollback paths
-- [ ] docs include links to upstream sources and related tracks
-- [ ] post-release verification confirms expected behavior under load
-
-### Source Alignment
+## Source Code Walkthrough
-- [Logseq](https://github.com/logseq/logseq)
-- [AI Codebase Knowledge Builder](https://github.com/The-Pocket/Tutorial-Codebase-Knowledge)
-
-### Cross-Tutorial Connection Map
-
-- Related tutorials are listed in this tutorial index.
-
-### Advanced Practice Exercises
-
-1. Build a minimal end-to-end implementation for `Chapter 3: Local-First Data`.
-2. Add instrumentation and measure baseline latency and error rate.
-3. Introduce one controlled failure and confirm graceful recovery.
-4. Add policy constraints and verify they are enforced consistently.
-5. Run a staged rollout and document rollback decision criteria.
-
-### Review Questions
-
-1. Which execution boundary matters most for this chapter and why?
-2. What signal detects regressions earliest in your environment?
-3. What tradeoff did you make between delivery speed and governance?
-4. How would you recover from the highest-impact failure mode?
-5. What must be automated before scaling to team-wide adoption?
-
-### Scenario Playbook 1: Chapter 3: Local-First Data
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 2: Chapter 3: Local-First Data
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 3: Chapter 3: Local-First Data
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 4: Chapter 3: Local-First Data
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 5: Chapter 3: Local-First Data
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 6: Chapter 3: Local-First Data
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 7: Chapter 3: Local-First Data
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 8: Chapter 3: Local-First Data
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 9: Chapter 3: Local-First Data
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 10: Chapter 3: Local-First Data
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 11: Chapter 3: Local-First Data
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 12: Chapter 3: Local-First Data
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 13: Chapter 3: Local-First Data
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 14: Chapter 3: Local-First Data
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 15: Chapter 3: Local-First Data
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 16: Chapter 3: Local-First Data
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 17: Chapter 3: Local-First Data
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 18: Chapter 3: Local-First Data
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 19: Chapter 3: Local-First Data
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 20: Chapter 3: Local-First Data
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 21: Chapter 3: Local-First Data
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 22: Chapter 3: Local-First Data
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 23: Chapter 3: Local-First Data
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 24: Chapter 3: Local-First Data
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 25: Chapter 3: Local-First Data
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 26: Chapter 3: Local-First Data
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 27: Chapter 3: Local-First Data
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 28: Chapter 3: Local-First Data
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 29: Chapter 3: Local-First Data
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 30: Chapter 3: Local-First Data
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 31: Chapter 3: Local-First Data
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 32: Chapter 3: Local-First Data
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 33: Chapter 3: Local-First Data
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
+### `libs/src/LSPlugin.core.ts`
+
+The `initProviderHandlers` function in [`libs/src/LSPlugin.core.ts`](https://github.com/logseq/logseq/blob/HEAD/libs/src/LSPlugin.core.ts) handles a key part of this chapter's functionality:
+
+```ts
+}
+
+function initProviderHandlers(pluginLocal: PluginLocal) {
+ const _ = (label: string): any => `provider:${label}`
+ let themed = false
+
+ // provider:theme
+ pluginLocal.on(_('theme'), (theme: Theme) => {
+ pluginLocal.themeMgr.registerTheme(pluginLocal.id, theme)
+
+ if (!themed) {
+ pluginLocal._dispose(() => {
+ pluginLocal.themeMgr.unregisterTheme(pluginLocal.id)
+ })
+
+ themed = true
+ }
+ })
+
+ // provider:style
+ pluginLocal.on(_('style'), (style: StyleString | StyleOptions) => {
+ let key: string | undefined
+
+ if (typeof style !== 'string') {
+ key = style.key
+ style = style.style
+ }
+
+ if (!style || !style.trim()) return
+
+ pluginLocal._dispose(
+ setupInjectedStyle(style, {
+```
+
+This function is important because it defines how Logseq: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+### `libs/src/LSPlugin.core.ts`
+
+The `initApiProxyHandlers` function in [`libs/src/LSPlugin.core.ts`](https://github.com/logseq/logseq/blob/HEAD/libs/src/LSPlugin.core.ts) handles a key part of this chapter's functionality:
+
+```ts
+}
+
+function initApiProxyHandlers(pluginLocal: PluginLocal) {
+ const _ = (label: string): any => `api:${label}`
+
+ pluginLocal.on(_('call'), async (payload) => {
+ let ret: any
+
+ try {
+ window.$$callerPluginID = pluginLocal.id
+ ret = await invokeHostExportedApi.apply(pluginLocal, [
+ payload.method,
+ ...payload.args,
+ ])
+ } catch (e) {
+ ret = {
+ [LSPMSG_ERROR_TAG]: e,
+ }
+ } finally {
+ window.$$callerPluginID = undefined
+ }
+
+ if (pluginLocal.shadow) {
+ if (payload.actor) {
+ payload.actor.resolve(ret)
+ }
+ return
+ }
+
+ const { _sync } = payload
+
+ if (_sync != null) {
+```
+
+This function is important because it defines how Logseq: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+### `libs/src/LSPlugin.core.ts`
+
+The `convertToLSPResource` function in [`libs/src/LSPlugin.core.ts`](https://github.com/logseq/logseq/blob/HEAD/libs/src/LSPlugin.core.ts) handles a key part of this chapter's functionality:
+
+```ts
+}
+
+function convertToLSPResource(fullUrl: string, dotPluginRoot: string) {
+ if (dotPluginRoot && fullUrl.startsWith(PROTOCOL_FILE + dotPluginRoot)) {
+ fullUrl = safetyPathJoin(
+ URL_LSP,
+ fullUrl.substr(PROTOCOL_FILE.length + dotPluginRoot.length)
+ )
+ }
+ return fullUrl
+}
+
+class IllegalPluginPackageError extends Error {
+ constructor(message: string) {
+ super(message)
+ this.name = 'IllegalPluginPackageError'
+ }
+}
+
+class ExistedImportedPluginPackageError extends Error {
+ constructor(message: string) {
+ super(message)
+ this.name = 'ExistedImportedPluginPackageError'
+ }
+}
+
+/**
+ * Host plugin for local
+ */
+class PluginLocal extends EventEmitter<
+ 'loaded' | 'unloaded' | 'beforeunload' | 'error' | string
+> {
+```
+
+This function is important because it defines how Logseq: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+### `libs/src/LSPlugin.core.ts`
+
+The `setupPluginCore` function in [`libs/src/LSPlugin.core.ts`](https://github.com/logseq/logseq/blob/HEAD/libs/src/LSPlugin.core.ts) handles a key part of this chapter's functionality:
+
+```ts
+}
+
+function setupPluginCore(options: any) {
+ const pluginCore = new LSPluginCore(options)
+
+ debug('=== 🔗 Setup Logseq Plugin System 🔗 ===')
+
+ window.LSPluginCore = pluginCore
+ window.DOMPurify = DOMPurify
+}
+
+export { PluginLocal, pluginHelpers, setupPluginCore }
+
+```
+
+This function is important because it defines how Logseq: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+
+## How These Components Connect
+
+```mermaid
+flowchart TD
+ A[initProviderHandlers]
+ B[initApiProxyHandlers]
+ C[convertToLSPResource]
+ D[setupPluginCore]
+ E[Window]
+ A --> B
+ B --> C
+ C --> D
+ D --> E
+```
diff --git a/tutorials/logseq-tutorial/04-development-setup.md b/tutorials/logseq-tutorial/04-development-setup.md
index d526cab9..ca4b2590 100644
--- a/tutorials/logseq-tutorial/04-development-setup.md
+++ b/tutorials/logseq-tutorial/04-development-setup.md
@@ -13,6 +13,19 @@ Welcome to **Logseq Development Environment Setup**. In this part of **Logseq: D
## Prerequisites & System Requirements
+```mermaid
+flowchart LR
+ A[Node.js 18+] --> D[yarn install]
+ B[Java 11+ JDK] --> E[shadow-cljs compile]
+ C[Clojure CLI] --> E
+ D --> F[npm dependencies]
+ E --> G[ClojureScript compiled JS]
+ G --> H[Electron app]
+ F --> H
+ H --> I[Logseq dev environment]
+```
+
+
### Hardware Requirements
- **Memory**: Minimum 8GB RAM (16GB recommended for large knowledge bases)
- **Storage**: 5GB+ available space for development environment
diff --git a/tutorials/logseq-tutorial/05-block-data-model.md b/tutorials/logseq-tutorial/05-block-data-model.md
index 6732ff6e..fb89a9bd 100644
--- a/tutorials/logseq-tutorial/05-block-data-model.md
+++ b/tutorials/logseq-tutorial/05-block-data-model.md
@@ -6,6 +6,7 @@ has_children: false
parent: "Logseq Knowledge Management"
---
+
# Chapter 5: Block Data Model
Welcome to **Chapter 5: Block Data Model**. In this part of **Logseq: Deep Dive Tutorial**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
@@ -100,490 +101,184 @@ Suggested trace strategy:
## Depth Expansion Playbook
-<!-- depth-expansion-v2 -->
-
-This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
-
-### Strategic Context
-
-- tutorial: **Logseq: Deep Dive Tutorial**
-- tutorial slug: **logseq-tutorial**
-- chapter focus: **Chapter 5: Block Data Model**
-- system context: **Logseq Knowledge Management**
-- objective: move from surface-level usage to repeatable engineering operation
-
-### Architecture Decomposition
-
-1. Define the runtime boundary for `Chapter 5: Block Data Model`.
-2. Separate control-plane decisions from data-plane execution.
-3. Capture input contracts, transformation points, and output contracts.
-4. Trace state transitions across request lifecycle stages.
-5. Identify extension hooks and policy interception points.
-6. Map ownership boundaries for team and automation workflows.
-7. Specify rollback and recovery paths for unsafe changes.
-8. Track observability signals for correctness, latency, and cost.
-
-### Operator Decision Matrix
-
-| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
-|:--------------|:--------------|:------------------|:---------|
-| Runtime mode | managed defaults | explicit policy config | speed vs control |
-| State handling | local ephemeral | durable persisted state | simplicity vs auditability |
-| Tool integration | direct API use | mediated adapter layer | velocity vs governance |
-| Rollout method | manual change | staged + canary rollout | effort vs safety |
-| Incident response | best effort logs | runbooks + SLO alerts | cost vs reliability |
-
-### Failure Modes and Countermeasures
-
-| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
-|:-------------|:-------------|:-------------------|:---------------|
-| stale context | inconsistent outputs | missing refresh window | enforce context TTL and refresh hooks |
-| policy drift | unexpected execution | ad hoc overrides | centralize policy profiles |
-| auth mismatch | 401/403 bursts | credential sprawl | rotation schedule + scope minimization |
-| schema breakage | parser/validation errors | unmanaged upstream changes | contract tests per release |
-| retry storms | queue congestion | no backoff controls | jittered backoff + circuit breakers |
-| silent regressions | quality drop without alerts | weak baseline metrics | eval harness with thresholds |
-
-### Implementation Runbook
-
-1. Establish a reproducible baseline environment.
-2. Capture chapter-specific success criteria before changes.
-3. Implement minimal viable path with explicit interfaces.
-4. Add observability before expanding feature scope.
-5. Run deterministic tests for happy-path behavior.
-6. Inject failure scenarios for negative-path validation.
-7. Compare output quality against baseline snapshots.
-8. Promote through staged environments with rollback gates.
-9. Record operational lessons in release notes.
-
-### Quality Gate Checklist
-
-- [ ] chapter-level assumptions are explicit and testable
-- [ ] API/tool boundaries are documented with input/output examples
-- [ ] failure handling includes retry, timeout, and fallback policy
-- [ ] security controls include auth scopes and secret rotation plans
-- [ ] observability includes logs, metrics, traces, and alert thresholds
-- [ ] deployment guidance includes canary and rollback paths
-- [ ] docs include links to upstream sources and related tracks
-- [ ] post-release verification confirms expected behavior under load
-
-### Source Alignment
+## Source Code Walkthrough
-- [Logseq](https://github.com/logseq/logseq)
-- [AI Codebase Knowledge Builder](https://github.com/The-Pocket/Tutorial-Codebase-Knowledge)
-
-### Cross-Tutorial Connection Map
-
-- Related tutorials are listed in this tutorial index.
-
-### Advanced Practice Exercises
-
-1. Build a minimal end-to-end implementation for `Chapter 5: Block Data Model`.
-2. Add instrumentation and measure baseline latency and error rate.
-3. Introduce one controlled failure and confirm graceful recovery.
-4. Add policy constraints and verify they are enforced consistently.
-5. Run a staged rollout and document rollback decision criteria.
-
-### Review Questions
-
-1. Which execution boundary matters most for this chapter and why?
-2. What signal detects regressions earliest in your environment?
-3. What tradeoff did you make between delivery speed and governance?
-4. How would you recover from the highest-impact failure mode?
-5. What must be automated before scaling to team-wide adoption?
-
-### Scenario Playbook 1: Chapter 5: Block Data Model
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 2: Chapter 5: Block Data Model
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 3: Chapter 5: Block Data Model
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 4: Chapter 5: Block Data Model
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 5: Chapter 5: Block Data Model
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 6: Chapter 5: Block Data Model
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 7: Chapter 5: Block Data Model
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 8: Chapter 5: Block Data Model
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 9: Chapter 5: Block Data Model
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 10: Chapter 5: Block Data Model
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 11: Chapter 5: Block Data Model
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 12: Chapter 5: Block Data Model
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 13: Chapter 5: Block Data Model
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 14: Chapter 5: Block Data Model
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 15: Chapter 5: Block Data Model
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 16: Chapter 5: Block Data Model
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 17: Chapter 5: Block Data Model
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 18: Chapter 5: Block Data Model
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 19: Chapter 5: Block Data Model
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 20: Chapter 5: Block Data Model
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 21: Chapter 5: Block Data Model
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 22: Chapter 5: Block Data Model
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 23: Chapter 5: Block Data Model
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 24: Chapter 5: Block Data Model
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 25: Chapter 5: Block Data Model
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 26: Chapter 5: Block Data Model
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 27: Chapter 5: Block Data Model
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 28: Chapter 5: Block Data Model
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 29: Chapter 5: Block Data Model
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 30: Chapter 5: Block Data Model
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 31: Chapter 5: Block Data Model
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 32: Chapter 5: Block Data Model
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 33: Chapter 5: Block Data Model
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
+### `libs/src/helpers.ts`
+
+The `ucFirst` function in [`libs/src/helpers.ts`](https://github.com/logseq/logseq/blob/HEAD/libs/src/helpers.ts) handles a key part of this chapter's functionality:
+
+```ts
+}
+
+export function ucFirst(str: string) {
+ return str.charAt(0).toUpperCase() + str.slice(1)
+}
+
+export function withFileProtocol(path: string) {
+ if (!path) return ''
+ const reg = /^(http|file|lsp)/
+
+ if (!reg.test(path)) {
+ path = PROTOCOL_FILE + path
+ }
+
+ return path
+}
+
+export function safetyPathJoin(basePath: string, ...parts: Array<string>) {
+ try {
+ const url = new URL(basePath)
+ if (!url.origin) throw new Error(null)
+ const fullPath = path.join(basePath.substr(url.origin.length), ...parts)
+ return url.origin + fullPath
+ } catch (e) {
+ return path.join(basePath, ...parts)
+ }
+}
+
+export function safetyPathNormalize(basePath: string) {
+ if (!basePath?.match(/^(http?|lsp|assets):/)) {
+ basePath = path.normalize(basePath)
+ }
+```
+
+This function is important because it defines how Logseq: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+### `libs/src/helpers.ts`
+
+The `withFileProtocol` function in [`libs/src/helpers.ts`](https://github.com/logseq/logseq/blob/HEAD/libs/src/helpers.ts) handles a key part of this chapter's functionality:
+
+```ts
+}
+
+export function withFileProtocol(path: string) {
+ if (!path) return ''
+ const reg = /^(http|file|lsp)/
+
+ if (!reg.test(path)) {
+ path = PROTOCOL_FILE + path
+ }
+
+ return path
+}
+
+export function safetyPathJoin(basePath: string, ...parts: Array<string>) {
+ try {
+ const url = new URL(basePath)
+ if (!url.origin) throw new Error(null)
+ const fullPath = path.join(basePath.substr(url.origin.length), ...parts)
+ return url.origin + fullPath
+ } catch (e) {
+ return path.join(basePath, ...parts)
+ }
+}
+
+export function safetyPathNormalize(basePath: string) {
+ if (!basePath?.match(/^(http?|lsp|assets):/)) {
+ basePath = path.normalize(basePath)
+ }
+ return basePath
+}
+
+/**
+```
+
+This function is important because it defines how Logseq: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+### `libs/src/helpers.ts`
+
+The `safetyPathJoin` function in [`libs/src/helpers.ts`](https://github.com/logseq/logseq/blob/HEAD/libs/src/helpers.ts) handles a key part of this chapter's functionality:
+
+```ts
+ const appPathRoot = await getAppPathRoot()
+
+ return safetyPathJoin(appPathRoot, 'js')
+}
+
+export function isObject(item: any) {
+ return item === Object(item) && !Array.isArray(item)
+}
+
+export function deepMerge<T>(a: Partial<T>, b: Partial<T>): T {
+ const overwriteArrayMerge = (destinationArray, sourceArray) => sourceArray
+ return merge(a, b, { arrayMerge: overwriteArrayMerge })
+}
+
+export class PluginLogger extends EventEmitter<'change'> {
+ private _logs: Array<[type: string, payload: any]> = []
+
+ constructor(
+ private _tag?: string,
+ private _opts?: {
+ console: boolean
+ }
+ ) {
+ super()
+ }
+
+ write(type: string, payload: any[], inConsole?: boolean) {
+ if (payload?.length && true === payload[payload.length - 1]) {
+ inConsole = true
+ payload.pop()
+ }
+
+```
+
+This function is important because it defines how Logseq: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+### `libs/src/helpers.ts`
+
+The `safetyPathNormalize` function in [`libs/src/helpers.ts`](https://github.com/logseq/logseq/blob/HEAD/libs/src/helpers.ts) handles a key part of this chapter's functionality:
+
+```ts
+}
+
+export function safetyPathNormalize(basePath: string) {
+ if (!basePath?.match(/^(http?|lsp|assets):/)) {
+ basePath = path.normalize(basePath)
+ }
+ return basePath
+}
+
+/**
+ * @param timeout milliseconds
+ * @param tag string
+ */
+export function deferred<T = any>(timeout?: number, tag?: string) {
+ let resolve: any, reject: any
+ let settled = false
+ const timeFn = (r: Function) => {
+ return (v: T) => {
+ timeout && clearTimeout(timeout)
+ r(v)
+ settled = true
+ }
+ }
+
+ const promise = new Promise<T>((resolve1, reject1) => {
+ resolve = timeFn(resolve1)
+ reject = timeFn(reject1)
+
+ if (timeout) {
+ // @ts-ignore
+ timeout = setTimeout(
+ () => reject(new Error(`[deferred timeout] ${tag}`)),
+```
+
+This function is important because it defines how Logseq: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+
+## How These Components Connect
+
+```mermaid
+flowchart TD
+ A[ucFirst]
+ B[withFileProtocol]
+ C[safetyPathJoin]
+ D[safetyPathNormalize]
+ E[invokeHostExportedApi]
+ A --> B
+ B --> C
+ C --> D
+ D --> E
+```
diff --git a/tutorials/logseq-tutorial/06-block-editor.md b/tutorials/logseq-tutorial/06-block-editor.md
index dc5d64ea..fe7f07a6 100644
--- a/tutorials/logseq-tutorial/06-block-editor.md
+++ b/tutorials/logseq-tutorial/06-block-editor.md
@@ -6,6 +6,7 @@ has_children: false
parent: "Logseq Knowledge Management"
---
+
# Chapter 6: Block Editor
Welcome to **Chapter 6: Block Editor**. In this part of **Logseq: Deep Dive Tutorial**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
@@ -96,490 +97,184 @@ Suggested trace strategy:
## Depth Expansion Playbook
-<!-- depth-expansion-v2 -->
-
-This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
-
-### Strategic Context
-
-- tutorial: **Logseq: Deep Dive Tutorial**
-- tutorial slug: **logseq-tutorial**
-- chapter focus: **Chapter 6: Block Editor**
-- system context: **Logseq Knowledge Management**
-- objective: move from surface-level usage to repeatable engineering operation
-
-### Architecture Decomposition
-
-1. Define the runtime boundary for `Chapter 6: Block Editor`.
-2. Separate control-plane decisions from data-plane execution.
-3. Capture input contracts, transformation points, and output contracts.
-4. Trace state transitions across request lifecycle stages.
-5. Identify extension hooks and policy interception points.
-6. Map ownership boundaries for team and automation workflows.
-7. Specify rollback and recovery paths for unsafe changes.
-8. Track observability signals for correctness, latency, and cost.
-
-### Operator Decision Matrix
-
-| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
-|:--------------|:--------------|:------------------|:---------|
-| Runtime mode | managed defaults | explicit policy config | speed vs control |
-| State handling | local ephemeral | durable persisted state | simplicity vs auditability |
-| Tool integration | direct API use | mediated adapter layer | velocity vs governance |
-| Rollout method | manual change | staged + canary rollout | effort vs safety |
-| Incident response | best effort logs | runbooks + SLO alerts | cost vs reliability |
-
-### Failure Modes and Countermeasures
-
-| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
-|:-------------|:-------------|:-------------------|:---------------|
-| stale context | inconsistent outputs | missing refresh window | enforce context TTL and refresh hooks |
-| policy drift | unexpected execution | ad hoc overrides | centralize policy profiles |
-| auth mismatch | 401/403 bursts | credential sprawl | rotation schedule + scope minimization |
-| schema breakage | parser/validation errors | unmanaged upstream changes | contract tests per release |
-| retry storms | queue congestion | no backoff controls | jittered backoff + circuit breakers |
-| silent regressions | quality drop without alerts | weak baseline metrics | eval harness with thresholds |
-
-### Implementation Runbook
-
-1. Establish a reproducible baseline environment.
-2. Capture chapter-specific success criteria before changes.
-3. Implement minimal viable path with explicit interfaces.
-4. Add observability before expanding feature scope.
-5. Run deterministic tests for happy-path behavior.
-6. Inject failure scenarios for negative-path validation.
-7. Compare output quality against baseline snapshots.
-8. Promote through staged environments with rollback gates.
-9. Record operational lessons in release notes.
-
-### Quality Gate Checklist
-
-- [ ] chapter-level assumptions are explicit and testable
-- [ ] API/tool boundaries are documented with input/output examples
-- [ ] failure handling includes retry, timeout, and fallback policy
-- [ ] security controls include auth scopes and secret rotation plans
-- [ ] observability includes logs, metrics, traces, and alert thresholds
-- [ ] deployment guidance includes canary and rollback paths
-- [ ] docs include links to upstream sources and related tracks
-- [ ] post-release verification confirms expected behavior under load
-
-### Source Alignment
+## Source Code Walkthrough
-- [Logseq](https://github.com/logseq/logseq)
-- [AI Codebase Knowledge Builder](https://github.com/The-Pocket/Tutorial-Codebase-Knowledge)
-
-### Cross-Tutorial Connection Map
-
-- Related tutorials are listed in this tutorial index.
-
-### Advanced Practice Exercises
-
-1. Build a minimal end-to-end implementation for `Chapter 6: Block Editor`.
-2. Add instrumentation and measure baseline latency and error rate.
-3. Introduce one controlled failure and confirm graceful recovery.
-4. Add policy constraints and verify they are enforced consistently.
-5. Run a staged rollout and document rollback decision criteria.
-
-### Review Questions
-
-1. Which execution boundary matters most for this chapter and why?
-2. What signal detects regressions earliest in your environment?
-3. What tradeoff did you make between delivery speed and governance?
-4. How would you recover from the highest-impact failure mode?
-5. What must be automated before scaling to team-wide adoption?
-
-### Scenario Playbook 1: Chapter 6: Block Editor
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 2: Chapter 6: Block Editor
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 3: Chapter 6: Block Editor
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 4: Chapter 6: Block Editor
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 5: Chapter 6: Block Editor
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 6: Chapter 6: Block Editor
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 7: Chapter 6: Block Editor
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 8: Chapter 6: Block Editor
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 9: Chapter 6: Block Editor
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 10: Chapter 6: Block Editor
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 11: Chapter 6: Block Editor
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 12: Chapter 6: Block Editor
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 13: Chapter 6: Block Editor
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 14: Chapter 6: Block Editor
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 15: Chapter 6: Block Editor
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 16: Chapter 6: Block Editor
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 17: Chapter 6: Block Editor
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 18: Chapter 6: Block Editor
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 19: Chapter 6: Block Editor
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 20: Chapter 6: Block Editor
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 21: Chapter 6: Block Editor
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 22: Chapter 6: Block Editor
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 23: Chapter 6: Block Editor
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 24: Chapter 6: Block Editor
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 25: Chapter 6: Block Editor
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 26: Chapter 6: Block Editor
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 27: Chapter 6: Block Editor
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 28: Chapter 6: Block Editor
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 29: Chapter 6: Block Editor
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 30: Chapter 6: Block Editor
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 31: Chapter 6: Block Editor
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 32: Chapter 6: Block Editor
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 33: Chapter 6: Block Editor
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
+### `libs/src/helpers.ts`
+
+The `cleanInjectedUI` function in [`libs/src/helpers.ts`](https://github.com/logseq/logseq/blob/HEAD/libs/src/helpers.ts) handles a key part of this chapter's functionality:
+
+```ts
+}
+
+export function cleanInjectedUI(id: string) {
+ if (!injectedUIEffects.has(id)) return
+ const clean = injectedUIEffects.get(id)
+ try {
+ clean()
+ } catch (e) {
+ console.warn('[CLEAN Injected UI] ', id, e)
+ }
+}
+
+export function cleanInjectedScripts(this: PluginLocal) {
+ const scripts = document.head.querySelectorAll(`script[data-ref=${this.id}]`)
+
+ scripts?.forEach((it) => it.remove())
+}
+
+export function transformableEvent(target: HTMLElement, e: Event) {
+ const obj: any = {}
+
+ if (target) {
+ obj.type = e.type
+
+ const ds = target.dataset
+ const FLAG_RECT = 'rect'
+
+ ;['value', 'id', 'className', 'dataset', FLAG_RECT].forEach((k) => {
+ let v: any
+
+ switch (k) {
+ case FLAG_RECT:
+```
+
+This function is important because it defines how Logseq: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+### `libs/src/helpers.ts`
+
+The `cleanInjectedScripts` function in [`libs/src/helpers.ts`](https://github.com/logseq/logseq/blob/HEAD/libs/src/helpers.ts) handles a key part of this chapter's functionality:
+
+```ts
+}
+
+export function cleanInjectedScripts(this: PluginLocal) {
+ const scripts = document.head.querySelectorAll(`script[data-ref=${this.id}]`)
+
+ scripts?.forEach((it) => it.remove())
+}
+
+export function transformableEvent(target: HTMLElement, e: Event) {
+ const obj: any = {}
+
+ if (target) {
+ obj.type = e.type
+
+ const ds = target.dataset
+ const FLAG_RECT = 'rect'
+
+ ;['value', 'id', 'className', 'dataset', FLAG_RECT].forEach((k) => {
+ let v: any
+
+ switch (k) {
+ case FLAG_RECT:
+ if (!ds.hasOwnProperty(FLAG_RECT)) return
+ v = target.getBoundingClientRect().toJSON()
+ break
+ default:
+ v = target[k]
+ }
+
+ if (typeof v === 'object') {
+ v = { ...v }
+ }
+```
+
+This function is important because it defines how Logseq: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+### `libs/src/helpers.ts`
+
+The `transformableEvent` function in [`libs/src/helpers.ts`](https://github.com/logseq/logseq/blob/HEAD/libs/src/helpers.ts) handles a key part of this chapter's functionality:
+
+```ts
+ const msgType = trigger.dataset[`on${ucFirst(type)}`]
+ if (msgType)
+ pl.caller?.callUserModel(msgType, transformableEvent(trigger, e))
+ if (preventDefault?.toLowerCase() === 'true') e.preventDefault()
+ },
+ false
+ )
+ })
+
+ // callback
+ initialCallback?.({ el, float })
+
+ teardownUI = () => {
+ disposeFloat?.()
+ injectedUIEffects.delete(id)
+ target!.removeChild(el)
+ }
+
+ injectedUIEffects.set(id, teardownUI)
+ return teardownUI
+}
+
+export function cleanInjectedUI(id: string) {
+ if (!injectedUIEffects.has(id)) return
+ const clean = injectedUIEffects.get(id)
+ try {
+ clean()
+ } catch (e) {
+ console.warn('[CLEAN Injected UI] ', id, e)
+ }
+}
+
+```
+
+This function is important because it defines how Logseq: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+### `libs/src/helpers.ts`
+
+The `injectTheme` function in [`libs/src/helpers.ts`](https://github.com/logseq/logseq/blob/HEAD/libs/src/helpers.ts) handles a key part of this chapter's functionality:
+
+```ts
+}
+
+export function injectTheme(url: string) {
+ const link = document.createElement('link')
+ link.rel = 'stylesheet'
+ link.href = url
+ document.head.appendChild(link)
+
+ const ejectTheme = () => {
+ try {
+ document.head.removeChild(link)
+ } catch (e) {
+ console.error(e)
+ }
+ }
+
+ return ejectTheme
+}
+
+export function mergeSettingsWithSchema(
+ settings: Record<string, any>,
+ schema: Array<SettingSchemaDesc>
+) {
+ const defaults = (schema || []).reduce((a, b) => {
+ if ('default' in b) {
+ a[b.key] = b.default
+ }
+ return a
+ }, {})
+
+ // shadow copy
+ return Object.assign(defaults, settings)
+```
+
+This function is important because it defines how Logseq: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+
+## How These Components Connect
+
+```mermaid
+flowchart TD
+ A[cleanInjectedUI]
+ B[cleanInjectedScripts]
+ C[transformableEvent]
+ D[injectTheme]
+ E[mergeSettingsWithSchema]
+ A --> B
+ B --> C
+ C --> D
+ D --> E
+```
diff --git a/tutorials/logseq-tutorial/07-bidirectional-links.md b/tutorials/logseq-tutorial/07-bidirectional-links.md
index 94d783f7..f691caf5 100644
--- a/tutorials/logseq-tutorial/07-bidirectional-links.md
+++ b/tutorials/logseq-tutorial/07-bidirectional-links.md
@@ -6,6 +6,7 @@ has_children: false
parent: "Logseq Knowledge Management"
---
+
# Chapter 7: Bi-Directional Links
Welcome to **Chapter 7: Bi-Directional Links**. In this part of **Logseq: Deep Dive Tutorial**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
@@ -92,490 +93,184 @@ Suggested trace strategy:
## Depth Expansion Playbook
-<!-- depth-expansion-v2 -->
-
-This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
-
-### Strategic Context
-
-- tutorial: **Logseq: Deep Dive Tutorial**
-- tutorial slug: **logseq-tutorial**
-- chapter focus: **Chapter 7: Bi-Directional Links**
-- system context: **Logseq Knowledge Management**
-- objective: move from surface-level usage to repeatable engineering operation
-
-### Architecture Decomposition
-
-1. Define the runtime boundary for `Chapter 7: Bi-Directional Links`.
-2. Separate control-plane decisions from data-plane execution.
-3. Capture input contracts, transformation points, and output contracts.
-4. Trace state transitions across request lifecycle stages.
-5. Identify extension hooks and policy interception points.
-6. Map ownership boundaries for team and automation workflows.
-7. Specify rollback and recovery paths for unsafe changes.
-8. Track observability signals for correctness, latency, and cost.
-
-### Operator Decision Matrix
-
-| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
-|:--------------|:--------------|:------------------|:---------|
-| Runtime mode | managed defaults | explicit policy config | speed vs control |
-| State handling | local ephemeral | durable persisted state | simplicity vs auditability |
-| Tool integration | direct API use | mediated adapter layer | velocity vs governance |
-| Rollout method | manual change | staged + canary rollout | effort vs safety |
-| Incident response | best effort logs | runbooks + SLO alerts | cost vs reliability |
-
-### Failure Modes and Countermeasures
-
-| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
-|:-------------|:-------------|:-------------------|:---------------|
-| stale context | inconsistent outputs | missing refresh window | enforce context TTL and refresh hooks |
-| policy drift | unexpected execution | ad hoc overrides | centralize policy profiles |
-| auth mismatch | 401/403 bursts | credential sprawl | rotation schedule + scope minimization |
-| schema breakage | parser/validation errors | unmanaged upstream changes | contract tests per release |
-| retry storms | queue congestion | no backoff controls | jittered backoff + circuit breakers |
-| silent regressions | quality drop without alerts | weak baseline metrics | eval harness with thresholds |
-
-### Implementation Runbook
-
-1. Establish a reproducible baseline environment.
-2. Capture chapter-specific success criteria before changes.
-3. Implement minimal viable path with explicit interfaces.
-4. Add observability before expanding feature scope.
-5. Run deterministic tests for happy-path behavior.
-6. Inject failure scenarios for negative-path validation.
-7. Compare output quality against baseline snapshots.
-8. Promote through staged environments with rollback gates.
-9. Record operational lessons in release notes.
-
-### Quality Gate Checklist
-
-- [ ] chapter-level assumptions are explicit and testable
-- [ ] API/tool boundaries are documented with input/output examples
-- [ ] failure handling includes retry, timeout, and fallback policy
-- [ ] security controls include auth scopes and secret rotation plans
-- [ ] observability includes logs, metrics, traces, and alert thresholds
-- [ ] deployment guidance includes canary and rollback paths
-- [ ] docs include links to upstream sources and related tracks
-- [ ] post-release verification confirms expected behavior under load
-
-### Source Alignment
-
-- [Logseq](https://github.com/logseq/logseq)
-- [AI Codebase Knowledge Builder](https://github.com/The-Pocket/Tutorial-Codebase-Knowledge)
-
-### Cross-Tutorial Connection Map
-
-- Related tutorials are listed in this tutorial index.
-
-### Advanced Practice Exercises
-
-1. Build a minimal end-to-end implementation for `Chapter 7: Bi-Directional Links`.
-2. Add instrumentation and measure baseline latency and error rate.
-3. Introduce one controlled failure and confirm graceful recovery.
-4. Add policy constraints and verify they are enforced consistently.
-5. Run a staged rollout and document rollback decision criteria.
-
-### Review Questions
-
-1. Which execution boundary matters most for this chapter and why?
-2. What signal detects regressions earliest in your environment?
-3. What tradeoff did you make between delivery speed and governance?
-4. How would you recover from the highest-impact failure mode?
-5. What must be automated before scaling to team-wide adoption?
-
-### Scenario Playbook 1: Chapter 7: Bi-Directional Links
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 2: Chapter 7: Bi-Directional Links
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 3: Chapter 7: Bi-Directional Links
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 4: Chapter 7: Bi-Directional Links
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 5: Chapter 7: Bi-Directional Links
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 6: Chapter 7: Bi-Directional Links
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 7: Chapter 7: Bi-Directional Links
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 8: Chapter 7: Bi-Directional Links
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 9: Chapter 7: Bi-Directional Links
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 10: Chapter 7: Bi-Directional Links
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 11: Chapter 7: Bi-Directional Links
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 12: Chapter 7: Bi-Directional Links
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 13: Chapter 7: Bi-Directional Links
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 14: Chapter 7: Bi-Directional Links
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 15: Chapter 7: Bi-Directional Links
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 16: Chapter 7: Bi-Directional Links
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 17: Chapter 7: Bi-Directional Links
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 18: Chapter 7: Bi-Directional Links
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 19: Chapter 7: Bi-Directional Links
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 20: Chapter 7: Bi-Directional Links
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 21: Chapter 7: Bi-Directional Links
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 22: Chapter 7: Bi-Directional Links
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 23: Chapter 7: Bi-Directional Links
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 24: Chapter 7: Bi-Directional Links
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 25: Chapter 7: Bi-Directional Links
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 26: Chapter 7: Bi-Directional Links
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 27: Chapter 7: Bi-Directional Links
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 28: Chapter 7: Bi-Directional Links
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 29: Chapter 7: Bi-Directional Links
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 30: Chapter 7: Bi-Directional Links
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 31: Chapter 7: Bi-Directional Links
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 32: Chapter 7: Bi-Directional Links
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 33: Chapter 7: Bi-Directional Links
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
+## Source Code Walkthrough
+
+### `libs/src/LSPlugin.ts`
+
+The `Theme` interface in [`libs/src/LSPlugin.ts`](https://github.com/logseq/logseq/blob/HEAD/libs/src/LSPlugin.ts) handles a key part of this chapter's functionality:
+
+```ts
+export type PluginLocalIdentity = string
+
+export type ThemeMode = 'light' | 'dark'
+
+export interface LegacyTheme {
+ name: string
+ url: string
+ description?: string
+ mode?: ThemeMode
+ pid: PluginLocalIdentity
+}
+
+export interface Theme extends LegacyTheme {
+ mode: ThemeMode
+}
+
+export type StyleString = string
+export type StyleOptions = {
+ key?: string
+ style: StyleString
+}
+
+export type UIContainerAttrs = {
+ draggable: boolean
+ resizable: boolean
+}
+
+export type UIBaseOptions = {
+ key?: string
+ replace?: boolean
+ template: string | null
+ style?: CSS.Properties
+```
+
+This interface is important because it defines how Logseq: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+### `libs/src/LSPlugin.ts`
+
+The `LSPluginPkgConfig` interface in [`libs/src/LSPlugin.ts`](https://github.com/logseq/logseq/blob/HEAD/libs/src/LSPlugin.ts) handles a key part of this chapter's functionality:
+
+```ts
+export type UIOptions = UIBaseOptions | UIPathOptions | UISlotOptions
+
+export interface LSPluginPkgConfig {
+ id: PluginLocalIdentity
+ main: string
+ entry: string // alias of main
+ title: string
+ mode: 'shadow' | 'iframe'
+ themes: Theme[]
+ icon: string
+ /**
+ * Alternative entrypoint for development.
+ */
+ devEntry: string
+ /**
+ * For legacy themes, do not use.
+ */
+ theme: unknown
+}
+
+export interface LSPluginBaseInfo {
+ /**
+ * Must be unique.
+ */
+ id: string
+ mode: 'shadow' | 'iframe'
+ settings: {
+ disabled: boolean
+ } & Record<string, unknown>
+ effect: boolean
+ /**
+ * For internal use only. Indicates if plugin is installed in dot root.
+```
+
+This interface is important because it defines how Logseq: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+### `libs/src/LSPlugin.ts`
+
+The `LSPluginBaseInfo` interface in [`libs/src/LSPlugin.ts`](https://github.com/logseq/logseq/blob/HEAD/libs/src/LSPlugin.ts) handles a key part of this chapter's functionality:
+
+```ts
+}
+
+export interface LSPluginBaseInfo {
+ /**
+ * Must be unique.
+ */
+ id: string
+ mode: 'shadow' | 'iframe'
+ settings: {
+ disabled: boolean
+ } & Record<string, unknown>
+ effect: boolean
+ /**
+ * For internal use only. Indicates if plugin is installed in dot root.
+ */
+ iir: boolean
+ /**
+ * For internal use only.
+ */
+ lsr: string
+}
+
+export type IHookEvent = {
+ [key: string]: any
+}
+
+export type IUserOffHook = () => void
+export type IUserHook<E = any, R = IUserOffHook> = (
+ callback: (e: IHookEvent & E) => void
+) => IUserOffHook
+export type IUserSlotHook<E = any> = (
+ callback: (e: IHookEvent & UISlotIdentity & E) => void
+```
+
+This interface is important because it defines how Logseq: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+### `libs/src/LSPlugin.ts`
+
+The `AppUserInfo` interface in [`libs/src/LSPlugin.ts`](https://github.com/logseq/logseq/blob/HEAD/libs/src/LSPlugin.ts) handles a key part of this chapter's functionality:
+
+```ts
+export type IGitResult = { stdout: string; stderr: string; exitCode: number }
+
+export interface AppUserInfo {
+ [key: string]: any
+}
+
+export interface AppInfo {
+ version: string
+ supportDb: boolean
+
+ [key: string]: unknown
+}
+
+/**
+ * User's app configurations
+ */
+export interface AppUserConfigs {
+ preferredThemeMode: ThemeMode
+ preferredFormat: 'markdown' | 'org'
+ preferredDateFormat: string
+ preferredStartOfWeek: string
+ preferredLanguage: string
+ preferredWorkflow: string
+
+ currentGraph: string
+ showBracket: boolean
+ enabledFlashcards: boolean
+ enabledJournals: boolean
+
+ [key: string]: unknown
+}
+
+```
+
+This interface is important because it defines how Logseq: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+
+## How These Components Connect
+
+```mermaid
+flowchart TD
+ A[Theme]
+ B[LSPluginPkgConfig]
+ C[LSPluginBaseInfo]
+ D[AppUserInfo]
+ E[AppInfo]
+ A --> B
+ B --> C
+ C --> D
+ D --> E
+```
diff --git a/tutorials/logseq-tutorial/08-graph-visualization.md b/tutorials/logseq-tutorial/08-graph-visualization.md
index 46fb55bd..5e99ab24 100644
--- a/tutorials/logseq-tutorial/08-graph-visualization.md
+++ b/tutorials/logseq-tutorial/08-graph-visualization.md
@@ -6,6 +6,7 @@ has_children: false
parent: "Logseq Knowledge Management"
---
+
# Chapter 8: Graph Visualization
Welcome to **Chapter 8: Graph Visualization**. In this part of **Logseq: Deep Dive Tutorial**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
@@ -98,490 +99,184 @@ Suggested trace strategy:
## Depth Expansion Playbook
-<!-- depth-expansion-v2 -->
-
-This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
-
-### Strategic Context
-
-- tutorial: **Logseq: Deep Dive Tutorial**
-- tutorial slug: **logseq-tutorial**
-- chapter focus: **Chapter 8: Graph Visualization**
-- system context: **Logseq Knowledge Management**
-- objective: move from surface-level usage to repeatable engineering operation
-
-### Architecture Decomposition
-
-1. Define the runtime boundary for `Chapter 8: Graph Visualization`.
-2. Separate control-plane decisions from data-plane execution.
-3. Capture input contracts, transformation points, and output contracts.
-4. Trace state transitions across request lifecycle stages.
-5. Identify extension hooks and policy interception points.
-6. Map ownership boundaries for team and automation workflows.
-7. Specify rollback and recovery paths for unsafe changes.
-8. Track observability signals for correctness, latency, and cost.
-
-### Operator Decision Matrix
-
-| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
-|:--------------|:--------------|:------------------|:---------|
-| Runtime mode | managed defaults | explicit policy config | speed vs control |
-| State handling | local ephemeral | durable persisted state | simplicity vs auditability |
-| Tool integration | direct API use | mediated adapter layer | velocity vs governance |
-| Rollout method | manual change | staged + canary rollout | effort vs safety |
-| Incident response | best effort logs | runbooks + SLO alerts | cost vs reliability |
-
-### Failure Modes and Countermeasures
-
-| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
-|:-------------|:-------------|:-------------------|:---------------|
-| stale context | inconsistent outputs | missing refresh window | enforce context TTL and refresh hooks |
-| policy drift | unexpected execution | ad hoc overrides | centralize policy profiles |
-| auth mismatch | 401/403 bursts | credential sprawl | rotation schedule + scope minimization |
-| schema breakage | parser/validation errors | unmanaged upstream changes | contract tests per release |
-| retry storms | queue congestion | no backoff controls | jittered backoff + circuit breakers |
-| silent regressions | quality drop without alerts | weak baseline metrics | eval harness with thresholds |
-
-### Implementation Runbook
-
-1. Establish a reproducible baseline environment.
-2. Capture chapter-specific success criteria before changes.
-3. Implement minimal viable path with explicit interfaces.
-4. Add observability before expanding feature scope.
-5. Run deterministic tests for happy-path behavior.
-6. Inject failure scenarios for negative-path validation.
-7. Compare output quality against baseline snapshots.
-8. Promote through staged environments with rollback gates.
-9. Record operational lessons in release notes.
-
-### Quality Gate Checklist
-
-- [ ] chapter-level assumptions are explicit and testable
-- [ ] API/tool boundaries are documented with input/output examples
-- [ ] failure handling includes retry, timeout, and fallback policy
-- [ ] security controls include auth scopes and secret rotation plans
-- [ ] observability includes logs, metrics, traces, and alert thresholds
-- [ ] deployment guidance includes canary and rollback paths
-- [ ] docs include links to upstream sources and related tracks
-- [ ] post-release verification confirms expected behavior under load
-
-### Source Alignment
-
-- [Logseq](https://github.com/logseq/logseq)
-- [AI Codebase Knowledge Builder](https://github.com/The-Pocket/Tutorial-Codebase-Knowledge)
-
-### Cross-Tutorial Connection Map
-
-- Related tutorials are listed in this tutorial index.
-
-### Advanced Practice Exercises
-
-1. Build a minimal end-to-end implementation for `Chapter 8: Graph Visualization`.
-2. Add instrumentation and measure baseline latency and error rate.
-3. Introduce one controlled failure and confirm graceful recovery.
-4. Add policy constraints and verify they are enforced consistently.
-5. Run a staged rollout and document rollback decision criteria.
-
-### Review Questions
-
-1. Which execution boundary matters most for this chapter and why?
-2. What signal detects regressions earliest in your environment?
-3. What tradeoff did you make between delivery speed and governance?
-4. How would you recover from the highest-impact failure mode?
-5. What must be automated before scaling to team-wide adoption?
-
-### Scenario Playbook 1: Chapter 8: Graph Visualization
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 2: Chapter 8: Graph Visualization
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 3: Chapter 8: Graph Visualization
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 4: Chapter 8: Graph Visualization
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 5: Chapter 8: Graph Visualization
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 6: Chapter 8: Graph Visualization
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 7: Chapter 8: Graph Visualization
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 8: Chapter 8: Graph Visualization
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 9: Chapter 8: Graph Visualization
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 10: Chapter 8: Graph Visualization
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 11: Chapter 8: Graph Visualization
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 12: Chapter 8: Graph Visualization
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 13: Chapter 8: Graph Visualization
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 14: Chapter 8: Graph Visualization
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 15: Chapter 8: Graph Visualization
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 16: Chapter 8: Graph Visualization
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 17: Chapter 8: Graph Visualization
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 18: Chapter 8: Graph Visualization
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 19: Chapter 8: Graph Visualization
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 20: Chapter 8: Graph Visualization
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 21: Chapter 8: Graph Visualization
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 22: Chapter 8: Graph Visualization
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 23: Chapter 8: Graph Visualization
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 24: Chapter 8: Graph Visualization
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 25: Chapter 8: Graph Visualization
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 26: Chapter 8: Graph Visualization
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 27: Chapter 8: Graph Visualization
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 28: Chapter 8: Graph Visualization
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 29: Chapter 8: Graph Visualization
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 30: Chapter 8: Graph Visualization
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 31: Chapter 8: Graph Visualization
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 32: Chapter 8: Graph Visualization
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 33: Chapter 8: Graph Visualization
-
-- tutorial context: **Logseq: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
+## Source Code Walkthrough
+
+### `libs/src/LSPlugin.ts`
+
+The `PageEntity` interface in [`libs/src/LSPlugin.ts`](https://github.com/logseq/logseq/blob/HEAD/libs/src/LSPlugin.ts) handles a key part of this chapter's functionality:
+
+```ts
+ * Page is just a block with some specific properties.
+ */
+export interface PageEntity {
+ id: EntityID
+ uuid: BlockUUID
+ name: string
+ format: 'markdown' | 'org'
+ type: 'page' | 'journal' | 'whiteboard' | 'class' | 'property' | 'hidden'
+ updatedAt: number
+ createdAt: number
+ 'journal?': boolean
+
+ title?: string
+ file?: IEntityID
+ originalName?: string
+ namespace?: IEntityID
+ children?: Array<PageEntity>
+ properties?: Record<string, any>
+ journalDay?: number
+ ident?: string
+
+ [key: string]: unknown
+}
+
+export type BlockIdentity = BlockUUID | Pick<BlockEntity, 'uuid'>
+export type BlockPageName = string
+export type PageIdentity = BlockPageName | BlockIdentity
+export type SlashCommandActionCmd =
+ | 'editor/input'
+ | 'editor/hook'
+ | 'editor/clear-current-slash'
+ | 'editor/restore-saved-cursor'
+```
+
+This interface is important because it defines how Logseq: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+### `libs/src/LSPlugin.ts`
+
+The `IPluginSearchServiceHooks` interface in [`libs/src/LSPlugin.ts`](https://github.com/logseq/logseq/blob/HEAD/libs/src/LSPlugin.ts) handles a key part of this chapter's functionality:
+
+```ts
+}
+
+export interface IPluginSearchServiceHooks {
+ name: string
+ options?: Record<string, any>
+
+ onQuery: (
+ graph: string,
+ key: string,
+ opts: Partial<{ limit: number }>
+ ) => Promise<{
+ graph: string
+ key: string
+ blocks?: Array<Partial<SearchBlockItem>>
+ pages?: Array<SearchPageItem>
+ files?: Array<SearchFileItem>
+ }>
+
+ onIndiceInit: (graph: string) => Promise<SearchIndiceInitStatus>
+ onIndiceReset: (graph: string) => Promise<void>
+ onBlocksChanged: (
+ graph: string,
+ changes: {
+ added: Array<SearchBlockItem>
+ removed: Array<EntityID>
+ }
+ ) => Promise<void>
+ onGraphRemoved: (graph: string, opts?: {}) => Promise<any>
+}
+
+/**
+ * App level APIs
+```
+
+This interface is important because it defines how Logseq: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+### `libs/src/LSPlugin.ts`
+
+The `IAppProxy` interface in [`libs/src/LSPlugin.ts`](https://github.com/logseq/logseq/blob/HEAD/libs/src/LSPlugin.ts) handles a key part of this chapter's functionality:
+
+```ts
+ * App level APIs
+ */
+export interface IAppProxy {
+ /**
+ * @added 0.0.4
+ * @param key
+ */
+ getInfo: (key?: keyof AppInfo) => Promise<AppInfo | any>
+
+ getUserInfo: () => Promise<AppUserInfo | null>
+ getUserConfigs: () => Promise<AppUserConfigs>
+
+ // services
+ registerSearchService<T extends IPluginSearchServiceHooks>(s: T): void
+
+ // commands
+ registerCommand: (
+ type: string,
+ opts: {
+ key: string
+ label: string
+ desc?: string
+ palette?: boolean
+ keybinding?: SimpleCommandKeybinding
+ },
+ action: SimpleCommandCallback
+ ) => void
+
+ registerCommandPalette: (
+ opts: {
+ key: string
+ label: string
+```
+
+This interface is important because it defines how Logseq: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+### `libs/src/LSPlugin.ts`
+
+The `IEditorProxy` interface in [`libs/src/LSPlugin.ts`](https://github.com/logseq/logseq/blob/HEAD/libs/src/LSPlugin.ts) handles a key part of this chapter's functionality:
+
+```ts
+ * Editor related APIs
+ */
+export interface IEditorProxy extends Record<string, any> {
+ /**
+ * register a custom command which will be added to the Logseq slash command list
+ * @param tag - displayed name of command
+ * @param action - can be a single callback function to run when the command is called, or an array of fixed commands with arguments
+ *
+ *
+ * @example https://github.com/logseq/logseq-plugin-samples/tree/master/logseq-slash-commands
+ *
+ * @example
+ * ```ts
+ * logseq.Editor.registerSlashCommand("Say Hi", () => {
+ * console.log('Hi!')
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * logseq.Editor.registerSlashCommand("💥 Big Bang", [
+ * ["editor/hook", "customCallback"],
+ * ["editor/clear-current-slash"],
+ * ]);
+ * ```
+ */
+ registerSlashCommand: (
+ tag: string,
+ action: BlockCommandCallback | Array<SlashCommandAction>
+ ) => unknown
+
+ /**
+```
+
+This interface is important because it defines how Logseq: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+
+## How These Components Connect
+
+```mermaid
+flowchart TD
+ A[PageEntity]
+ B[IPluginSearchServiceHooks]
+ C[IAppProxy]
+ D[IEditorProxy]
+ E[IDBProxy]
+ A --> B
+ B --> C
+ C --> D
+ D --> E
+```
diff --git a/tutorials/mastra-tutorial/01-getting-started.md b/tutorials/mastra-tutorial/01-getting-started.md
index e24b08d7..a6c062cd 100644
--- a/tutorials/mastra-tutorial/01-getting-started.md
+++ b/tutorials/mastra-tutorial/01-getting-started.md
@@ -49,170 +49,168 @@ You now have a working Mastra project baseline for deeper architecture work.
Next: [Chapter 2: System Architecture](02-system-architecture.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `explorations/network-validation-bridge.ts`
+### `explorations/ralph-wiggum-loop-prototype.ts`
-The `testsPass` function in [`explorations/network-validation-bridge.ts`](https://github.com/mastra-ai/mastra/blob/HEAD/explorations/network-validation-bridge.ts) handles a key part of this chapter's functionality:
+The `testsPassing` function in [`explorations/ralph-wiggum-loop-prototype.ts`](https://github.com/mastra-ai/mastra/blob/HEAD/explorations/ralph-wiggum-loop-prototype.ts) handles a key part of this chapter's functionality:
```ts
* Check if tests pass
*/
-export function testsPass(command = 'npm test', options?: { timeout?: number; cwd?: string }): ValidationCheck {
+export function testsPassing(testCommand = 'npm test'): CompletionChecker {
return {
- id: 'tests-pass',
- name: 'Tests Pass',
async check() {
- const start = Date.now();
try {
- const { stdout, stderr } = await execAsync(command, {
- timeout: options?.timeout ?? 300000,
- cwd: options?.cwd,
- });
+ const { stdout, stderr } = await execAsync(testCommand, { timeout: 300000 });
return {
success: true,
message: 'All tests passed',
- details: { stdout: stdout.slice(-1000), stderr: stderr.slice(-500) },
- duration: Date.now() - start,
+ data: { stdout, stderr },
};
} catch (error: any) {
return {
success: false,
- message: `Tests failed: ${error.message}`,
- details: {
- stdout: error.stdout?.slice(-1000),
- stderr: error.stderr?.slice(-1000),
- exitCode: error.code,
- },
- duration: Date.now() - start,
+ message: error.message,
+ data: { stdout: error.stdout, stderr: error.stderr },
};
}
},
+ };
+}
+
+/**
+ * Check if build succeeds
+ */
+export function buildSucceeds(buildCommand = 'npm run build'): CompletionChecker {
+ return {
+ async check() {
+ try {
+ const { stdout, stderr } = await execAsync(buildCommand, { timeout: 600000 });
+ return {
```
This function is important because it defines how Mastra Tutorial: TypeScript Framework for AI Agents and Workflows implements the patterns covered in this chapter.
-### `explorations/network-validation-bridge.ts`
+### `explorations/ralph-wiggum-loop-prototype.ts`
-The `buildSucceeds` function in [`explorations/network-validation-bridge.ts`](https://github.com/mastra-ai/mastra/blob/HEAD/explorations/network-validation-bridge.ts) handles a key part of this chapter's functionality:
+The `buildSucceeds` function in [`explorations/ralph-wiggum-loop-prototype.ts`](https://github.com/mastra-ai/mastra/blob/HEAD/explorations/ralph-wiggum-loop-prototype.ts) handles a key part of this chapter's functionality:
```ts
* Check if build succeeds
*/
-export function buildSucceeds(
- command = 'npm run build',
- options?: { timeout?: number; cwd?: string },
-): ValidationCheck {
+export function buildSucceeds(buildCommand = 'npm run build'): CompletionChecker {
return {
- id: 'build-succeeds',
- name: 'Build Succeeds',
async check() {
- const start = Date.now();
try {
- const { stdout, stderr } = await execAsync(command, {
- timeout: options?.timeout ?? 600000,
- cwd: options?.cwd,
- });
+ const { stdout, stderr } = await execAsync(buildCommand, { timeout: 600000 });
return {
success: true,
- message: 'Build completed successfully',
- details: { stdout: stdout.slice(-500), stderr: stderr.slice(-500) },
- duration: Date.now() - start,
+ message: 'Build succeeded',
+ data: { stdout, stderr },
};
} catch (error: any) {
return {
success: false,
- message: `Build failed: ${error.message}`,
- details: {
- stdout: error.stdout?.slice(-1000),
- stderr: error.stderr?.slice(-1000),
- },
- duration: Date.now() - start,
+ message: error.message,
+ data: { stdout: error.stdout, stderr: error.stderr },
};
+ }
+ },
+ };
+}
+
+/**
+ * Check if lint passes
+ */
+export function lintClean(lintCommand = 'npm run lint'): CompletionChecker {
+ return {
+ async check() {
+ try {
+ const { stdout, stderr } = await execAsync(lintCommand, { timeout: 120000 });
+ return {
```
This function is important because it defines how Mastra Tutorial: TypeScript Framework for AI Agents and Workflows implements the patterns covered in this chapter.
-### `explorations/network-validation-bridge.ts`
+### `explorations/ralph-wiggum-loop-prototype.ts`
-The `lintPasses` function in [`explorations/network-validation-bridge.ts`](https://github.com/mastra-ai/mastra/blob/HEAD/explorations/network-validation-bridge.ts) handles a key part of this chapter's functionality:
+The `lintClean` function in [`explorations/ralph-wiggum-loop-prototype.ts`](https://github.com/mastra-ai/mastra/blob/HEAD/explorations/ralph-wiggum-loop-prototype.ts) handles a key part of this chapter's functionality:
```ts
* Check if lint passes
*/
-export function lintPasses(command = 'npm run lint', options?: { timeout?: number; cwd?: string }): ValidationCheck {
+export function lintClean(lintCommand = 'npm run lint'): CompletionChecker {
return {
- id: 'lint-passes',
- name: 'Lint Passes',
async check() {
- const start = Date.now();
try {
- const { stdout, stderr } = await execAsync(command, {
- timeout: options?.timeout ?? 120000,
- cwd: options?.cwd,
- });
+ const { stdout, stderr } = await execAsync(lintCommand, { timeout: 120000 });
return {
success: true,
message: 'No lint errors',
- details: { stdout: stdout.slice(-500) },
- duration: Date.now() - start,
+ data: { stdout, stderr },
};
} catch (error: any) {
return {
success: false,
- message: `Lint errors found: ${error.message}`,
- details: {
- stdout: error.stdout?.slice(-1000),
- stderr: error.stderr?.slice(-1000),
- },
- duration: Date.now() - start,
+ message: error.message,
+ data: { stdout: error.stdout, stderr: error.stderr },
};
}
},
};
+}
+
+/**
+ * Check if output contains a specific string/pattern
+ */
+export function outputContains(pattern: string | RegExp): CompletionChecker {
+ let lastOutput = '';
+ return {
+ async check() {
+ const matches = typeof pattern === 'string' ? lastOutput.includes(pattern) : pattern.test(lastOutput);
+
```
This function is important because it defines how Mastra Tutorial: TypeScript Framework for AI Agents and Workflows implements the patterns covered in this chapter.
-### `explorations/network-validation-bridge.ts`
+### `explorations/ralph-wiggum-loop-prototype.ts`
-The `typeChecks` function in [`explorations/network-validation-bridge.ts`](https://github.com/mastra-ai/mastra/blob/HEAD/explorations/network-validation-bridge.ts) handles a key part of this chapter's functionality:
+The `outputContains` function in [`explorations/ralph-wiggum-loop-prototype.ts`](https://github.com/mastra-ai/mastra/blob/HEAD/explorations/ralph-wiggum-loop-prototype.ts) handles a key part of this chapter's functionality:
```ts
- * Check if TypeScript compiles without errors
+ * Check if output contains a specific string/pattern
*/
-export function typeChecks(
- command = 'npx tsc --noEmit',
- options?: { timeout?: number; cwd?: string },
-): ValidationCheck {
+export function outputContains(pattern: string | RegExp): CompletionChecker {
+ let lastOutput = '';
return {
- id: 'type-checks',
- name: 'TypeScript Compiles',
async check() {
- const start = Date.now();
- try {
- const { stdout, stderr } = await execAsync(command, {
- timeout: options?.timeout ?? 300000,
- cwd: options?.cwd,
- });
- return {
- success: true,
- message: 'No type errors',
- details: { stdout: stdout.slice(-500) },
- duration: Date.now() - start,
- };
- } catch (error: any) {
- return {
- success: false,
- message: `Type errors found`,
- details: {
- stdout: error.stdout?.slice(-2000),
- stderr: error.stderr?.slice(-1000),
- },
- duration: Date.now() - start,
- };
+ const matches = typeof pattern === 'string' ? lastOutput.includes(pattern) : pattern.test(lastOutput);
+
+ return {
+ success: matches,
+ message: matches ? `Output contains pattern` : `Output does not contain pattern`,
+ };
+ },
+ // Helper to set output for checking
+ setOutput: (output: string) => {
+ lastOutput = output;
+ },
+ } as CompletionChecker & { setOutput: (output: string) => void };
+}
+
+/**
+ * Combine multiple checkers (all must pass)
+ */
+export function allCheckersPassing(...checkers: CompletionChecker[]): CompletionChecker {
+ return {
+ async check() {
+ const results = await Promise.all(checkers.map(c => c.check()));
+ const allPassed = results.every(r => r.success);
+
+ return {
+ success: allPassed,
+ message: results.map(r => r.message).join('; '),
```
This function is important because it defines how Mastra Tutorial: TypeScript Framework for AI Agents and Workflows implements the patterns covered in this chapter.
@@ -222,11 +220,11 @@ This function is important because it defines how Mastra Tutorial: TypeScript Fr
```mermaid
flowchart TD
- A[testsPass]
+ A[testsPassing]
B[buildSucceeds]
- C[lintPasses]
- D[typeChecks]
- E[customCheck]
+ C[lintClean]
+ D[outputContains]
+ E[allCheckersPassing]
A --> B
B --> C
C --> D
diff --git a/tutorials/mastra-tutorial/02-system-architecture.md b/tutorials/mastra-tutorial/02-system-architecture.md
index b66f2e20..94fd43ba 100644
--- a/tutorials/mastra-tutorial/02-system-architecture.md
+++ b/tutorials/mastra-tutorial/02-system-architecture.md
@@ -50,184 +50,181 @@ You now understand where to place logic in Mastra without mixing concerns.
Next: [Chapter 3: Agents and Tools](03-agents-and-tools.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `explorations/network-validation-bridge.ts`
+### `explorations/ralph-wiggum-loop-prototype.ts`
-The `fileContains` function in [`explorations/network-validation-bridge.ts`](https://github.com/mastra-ai/mastra/blob/HEAD/explorations/network-validation-bridge.ts) handles a key part of this chapter's functionality:
+The `executeAutonomousLoop` function in [`explorations/ralph-wiggum-loop-prototype.ts`](https://github.com/mastra-ai/mastra/blob/HEAD/explorations/ralph-wiggum-loop-prototype.ts) handles a key part of this chapter's functionality:
```ts
- * File contains pattern check
+ * Executes an autonomous loop with the given agent and configuration.
*/
-export function fileContains(path: string, pattern: string | RegExp): ValidationCheck {
- return {
- id: `file-contains-${path}`,
- name: `File Contains Pattern: ${path}`,
- async check() {
- const start = Date.now();
- try {
- const fs = await import('fs/promises');
- const content = await fs.readFile(path, 'utf-8');
- const matches = typeof pattern === 'string' ? content.includes(pattern) : pattern.test(content);
-
- return {
- success: matches,
- message: matches
- ? `File ${path} contains expected pattern`
- : `File ${path} does not contain expected pattern`,
- duration: Date.now() - start,
- };
- } catch (error: any) {
- return {
- success: false,
- message: `Could not read file ${path}: ${error.message}`,
- duration: Date.now() - start,
- };
+export async function executeAutonomousLoop(
+ agent: Agent,
+ config: AutonomousLoopConfig,
+ mastra?: Mastra,
+): Promise<AutonomousLoopResult> {
+ const iterations: IterationResult[] = [];
+ let totalTokens = 0;
+ const startTime = Date.now();
+
+ const contextWindow = config.contextWindow ?? 5;
+
+ for (let i = 0; i < config.maxIterations; i++) {
+ const iterationStartTime = Date.now();
+
+ // Notify iteration start
+ await config.onIterationStart?.(i + 1);
+
+ // Build context from previous iterations
+ const previousResults = iterations.slice(-contextWindow).map(r => ({
+ iteration: r.iteration,
+ success: r.success,
+ output: r.agentOutput,
+ error: r.error?.message,
+ }));
+
+ let contextualPrompt = config.prompt;
+ if (previousResults.length > 0) {
+ const historyContext = previousResults
+ .map(
+ r => `
+```
+
+This function is important because it defines how Mastra Tutorial: TypeScript Framework for AI Agents and Workflows implements the patterns covered in this chapter.
+
+### `explorations/ralph-wiggum-loop-prototype.ts`
+
+The `main` function in [`explorations/ralph-wiggum-loop-prototype.ts`](https://github.com/mastra-ai/mastra/blob/HEAD/explorations/ralph-wiggum-loop-prototype.ts) handles a key part of this chapter's functionality:
+
+```ts
+});
+
+async function main() {
+ const result = await executeAutonomousLoop(migrationAgent, {
+ prompt: 'Migrate all tests in src/__tests__ from Jest to Vitest',
+ completion: testsPassing('npm run test'),
+ maxIterations: 20,
+ iterationDelay: 1000,
+ onIterationStart: (i) => console.log(`\n🔄 Starting iteration ${i}...`),
+ onIteration: (r) => {
+ console.log(` ${r.success ? '✅' : '❌'} Iteration ${r.iteration}`);
+ console.log(` Tokens: ${r.tokensUsed}, Duration: ${r.duration}ms`);
+ if (r.completionCheck.message) {
+ console.log(` Message: ${r.completionCheck.message}`);
}
},
- };
+ });
+
+ console.log('\n' + '='.repeat(50));
+ console.log(`Result: ${result.success ? '✅ SUCCESS' : '❌ FAILED'}`);
+ console.log(`Total iterations: ${result.iterations.length}`);
+ console.log(`Total tokens: ${result.totalTokens}`);
+ console.log(`Total duration: ${result.totalDuration}ms`);
+ if (result.completionMessage) {
+ console.log(`Message: ${result.completionMessage}`);
+ }
}
-// ============================================================================
+main().catch(console.error);
+*/
+
```
This function is important because it defines how Mastra Tutorial: TypeScript Framework for AI Agents and Workflows implements the patterns covered in this chapter.
-### `explorations/network-validation-bridge.ts`
+### `explorations/ralph-wiggum-loop-prototype.ts`
-The `runValidation` function in [`explorations/network-validation-bridge.ts`](https://github.com/mastra-ai/mastra/blob/HEAD/explorations/network-validation-bridge.ts) handles a key part of this chapter's functionality:
+The `CompletionChecker` interface in [`explorations/ralph-wiggum-loop-prototype.ts`](https://github.com/mastra-ai/mastra/blob/HEAD/explorations/ralph-wiggum-loop-prototype.ts) handles a key part of this chapter's functionality:
```ts
// ============================================================================
-async function runValidation(
- config: NetworkValidationConfig,
-): Promise<{ passed: boolean; results: ValidationResult[] }> {
- const results: ValidationResult[] = [];
-
- if (config.parallel) {
- // Run all checks in parallel
- const checkResults = await Promise.all(config.checks.map(check => check.check()));
- results.push(...checkResults);
- } else {
- // Run checks sequentially (can short-circuit on failure for 'all' strategy)
- for (const check of config.checks) {
- const result = await check.check();
- results.push(result);
-
- // Short-circuit for 'all' strategy if a check fails
- if (config.strategy === 'all' && !result.success) {
- break;
- }
- // Short-circuit for 'any' strategy if a check passes
- if (config.strategy === 'any' && result.success) {
- break;
- }
- }
- }
+export interface CompletionChecker {
+ check: () => Promise<{ success: boolean; message?: string; data?: any }>;
+}
+
+export interface AutonomousLoopConfig {
+ /** The task prompt to send to the agent */
+ prompt: string;
+
+ /** How to determine if the task is complete */
+ completion: CompletionChecker;
+
+ /** Maximum number of iterations before giving up */
+ maxIterations: number;
- const passed = config.strategy === 'all' ? results.every(r => r.success) : results.some(r => r.success);
+ /** Optional: Maximum tokens to spend */
+ maxTokens?: number;
- return { passed, results };
+ /** Optional: Delay between iterations in ms */
+ iterationDelay?: number;
+
+ /** Optional: How many previous iteration results to include in context */
+ contextWindow?: number;
+
+ /** Optional: Called after each iteration */
+ onIteration?: (result: IterationResult) => void | Promise<void>;
+
+ /** Optional: Called when starting an iteration */
+ onIterationStart?: (iteration: number) => void | Promise<void>;
}
+
```
-This function is important because it defines how Mastra Tutorial: TypeScript Framework for AI Agents and Workflows implements the patterns covered in this chapter.
+This interface is important because it defines how Mastra Tutorial: TypeScript Framework for AI Agents and Workflows implements the patterns covered in this chapter.
-### `explorations/network-validation-bridge.ts`
+### `explorations/ralph-wiggum-loop-prototype.ts`
-The `createValidationTools` function in [`explorations/network-validation-bridge.ts`](https://github.com/mastra-ai/mastra/blob/HEAD/explorations/network-validation-bridge.ts) handles a key part of this chapter's functionality:
+The `AutonomousLoopConfig` interface in [`explorations/ralph-wiggum-loop-prototype.ts`](https://github.com/mastra-ai/mastra/blob/HEAD/explorations/ralph-wiggum-loop-prototype.ts) handles a key part of this chapter's functionality:
```ts
- * This allows the routing agent to call validation as a primitive
- */
-export function createValidationTools() {
- return {
- runTests: createTool({
- id: 'run-tests',
- description:
- 'Run the project test suite to verify changes work correctly. Call this after making code changes to ensure tests pass.',
- inputSchema: z.object({
- command: z.string().default('npm test').describe('The test command to run'),
- timeout: z.number().default(300000).describe('Timeout in milliseconds'),
- }),
- execute: async ({ command, timeout }) => {
- const check = testsPass(command, { timeout });
- return check.check();
- },
- }),
-
- runBuild: createTool({
- id: 'run-build',
- description: 'Build the project to verify there are no compilation errors. Call this after making code changes.',
- inputSchema: z.object({
- command: z.string().default('npm run build').describe('The build command to run'),
- timeout: z.number().default(600000).describe('Timeout in milliseconds'),
- }),
- execute: async ({ command, timeout }) => {
- const check = buildSucceeds(command, { timeout });
- return check.check();
- },
- }),
-
- runLint: createTool({
-```
+}
-This function is important because it defines how Mastra Tutorial: TypeScript Framework for AI Agents and Workflows implements the patterns covered in this chapter.
+export interface AutonomousLoopConfig {
+ /** The task prompt to send to the agent */
+ prompt: string;
-### `explorations/network-validation-bridge.ts`
+ /** How to determine if the task is complete */
+ completion: CompletionChecker;
-The `networkWithValidation` function in [`explorations/network-validation-bridge.ts`](https://github.com/mastra-ai/mastra/blob/HEAD/explorations/network-validation-bridge.ts) handles a key part of this chapter's functionality:
+ /** Maximum number of iterations before giving up */
+ maxIterations: number;
-```ts
- * to the existing Agent Network loop.
- */
-export async function networkWithValidation(
- agent: Agent,
- messages: MessageListInput,
- options: ValidatedNetworkOptions,
-) {
- const { maxIterations, validation, onIteration, ...networkOptions } = options;
-
- let iteration = 0;
- let isComplete = false;
- let lastResult: any = null;
-
- // Track validation feedback to pass to next iteration
- let validationFeedback: string | null = null;
-
- while (!isComplete && iteration < maxIterations) {
- iteration++;
- const iterationStart = Date.now();
-
- // Prepare messages with validation feedback from previous iteration
- let iterationMessages = messages;
- if (validationFeedback && iteration > 1) {
- // Append validation feedback to help the agent learn from failures
- const feedbackMessage = `
-[VALIDATION FEEDBACK FROM PREVIOUS ITERATION]
-The previous attempt was reviewed with automated validation.
-${validationFeedback}
-
-Please address these issues and continue working on the task.
-`;
+ /** Optional: Maximum tokens to spend */
+ maxTokens?: number;
+
+ /** Optional: Delay between iterations in ms */
+ iterationDelay?: number;
+
+ /** Optional: How many previous iteration results to include in context */
+ contextWindow?: number;
+ /** Optional: Called after each iteration */
+ onIteration?: (result: IterationResult) => void | Promise<void>;
+
+ /** Optional: Called when starting an iteration */
+ onIterationStart?: (iteration: number) => void | Promise<void>;
+}
+
+export interface IterationResult {
+ iteration: number;
+ success: boolean;
+ agentOutput: string;
```
-This function is important because it defines how Mastra Tutorial: TypeScript Framework for AI Agents and Workflows implements the patterns covered in this chapter.
+This interface is important because it defines how Mastra Tutorial: TypeScript Framework for AI Agents and Workflows implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[fileContains]
- B[runValidation]
- C[createValidationTools]
- D[networkWithValidation]
- E[ValidationCheck]
+ A[executeAutonomousLoop]
+ B[main]
+ C[CompletionChecker]
+ D[AutonomousLoopConfig]
+ E[IterationResult]
A --> B
B --> C
C --> D
diff --git a/tutorials/mastra-tutorial/03-agents-and-tools.md b/tutorials/mastra-tutorial/03-agents-and-tools.md
index 9a561f0e..f731b3d2 100644
--- a/tutorials/mastra-tutorial/03-agents-and-tools.md
+++ b/tutorials/mastra-tutorial/03-agents-and-tools.md
@@ -40,184 +40,180 @@ You now have a practical framework for building strong, bounded agents in Mastra
Next: [Chapter 4: Workflows and Control Flow](04-workflows-and-control-flow.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `explorations/network-validation-bridge.ts`
+### `scripts/ignore-example.js`
-The `NetworkValidationConfig` interface in [`explorations/network-validation-bridge.ts`](https://github.com/mastra-ai/mastra/blob/HEAD/explorations/network-validation-bridge.ts) handles a key part of this chapter's functionality:
+The `spawn` function in [`scripts/ignore-example.js`](https://github.com/mastra-ai/mastra/blob/HEAD/scripts/ignore-example.js) handles a key part of this chapter's functionality:
-```ts
+```js
+import { spawn as nodeSpawn } from 'child_process';
+import { readFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+
+const dir = process.argv[2];
+if (!dir) {
+ console.error('Usage: node scripts/ignore-example.js <directory>');
+ process.exit(1);
}
-export interface NetworkValidationConfig {
- /**
- * Array of validation checks to run
- */
- checks: ValidationCheck[];
-
- /**
- * How to combine check results:
- * - 'all': All checks must pass
- * - 'any': At least one check must pass
- * - 'weighted': Use weights (future)
- */
- strategy: 'all' | 'any';
-
- /**
- * How validation interacts with LLM completion assessment:
- * - 'verify': LLM says complete AND validation passes
- * - 'override': Only validation matters, ignore LLM
- * - 'llm-fallback': Try validation first, use LLM if no checks configured
- */
- mode: 'verify' | 'override' | 'llm-fallback';
-
- /**
- * Maximum time for all validation checks (ms)
- */
- timeout?: number;
-
- /**
- * Run validation in parallel or sequentially
- */
-```
+/**
+ * Promisified version of Node.js spawn function
+ *
+ * @param {string} command - The command to run
+ * @param {string[]} args - List of string arguments
+ * @param {import('child_process').SpawnOptions} options - Spawn options
+ * @returns {Promise<void>} Promise that resolves with the exit code when the process completes
+ */
+function spawn(command, args = [], options = {}) {
+ return new Promise((resolve, reject) => {
+ const childProcess = nodeSpawn(command, args, {
+ // stdio: 'inherit',
+ ...options,
+ });
-This interface is important because it defines how Mastra Tutorial: TypeScript Framework for AI Agents and Workflows implements the patterns covered in this chapter.
+ childProcess.on('error', error => {
+ reject(error);
+ });
-### `explorations/network-validation-bridge.ts`
+```
-The `ValidatedNetworkOptions` interface in [`explorations/network-validation-bridge.ts`](https://github.com/mastra-ai/mastra/blob/HEAD/explorations/network-validation-bridge.ts) handles a key part of this chapter's functionality:
+This function is important because it defines how Mastra Tutorial: TypeScript Framework for AI Agents and Workflows implements the patterns covered in this chapter.
-```ts
-}
+### `scripts/ignore-example.js`
-export interface ValidatedNetworkOptions {
- /**
- * Maximum iterations before stopping
- */
- maxIterations: number;
-
- /**
- * Validation configuration
- */
- validation?: NetworkValidationConfig;
-
- /**
- * Called after each iteration with validation results
- */
- onIteration?: (result: IterationStatus) => void | Promise<void>;
-
- /**
- * Thread ID for memory
- */
- threadId?: string;
-
- /**
- * Resource ID for memory
- */
- resourceId?: string;
-}
+The `findLinkedDependencies` function in [`scripts/ignore-example.js`](https://github.com/mastra-ai/mastra/blob/HEAD/scripts/ignore-example.js) handles a key part of this chapter's functionality:
-export interface IterationStatus {
- iteration: number;
- llmSaysComplete: boolean;
+```js
+ * @returns {Object} An object containing all linked dependencies
+ */
+function findLinkedDependencies(dir, protocol = 'link:') {
+ try {
+ // Read package.json from current working directory
+ const packageJson = JSON.parse(readFileSync(`${dir}/package.json`, 'utf8'));
+
+ // Initialize an object to store linked dependencies
+ const linkedDependencies = {};
+
+ // Check regular dependencies
+ if (packageJson.dependencies) {
+ for (const [name, version] of Object.entries(packageJson.dependencies)) {
+ if (typeof version === 'string' && version.startsWith(protocol)) {
+ linkedDependencies[name] = version;
+ }
+ }
+ }
+
+ // Check dev dependencies
+ if (packageJson.devDependencies) {
+ for (const [name, version] of Object.entries(packageJson.devDependencies)) {
+ if (typeof version === 'string' && version.startsWith(protocol)) {
+ linkedDependencies[name] = version;
+ }
+ }
+ }
+
+ // Check peer dependencies
+ if (packageJson.peerDependencies) {
+ for (const [name, version] of Object.entries(packageJson.peerDependencies)) {
+ if (typeof version === 'string' && version.startsWith(protocol)) {
```
-This interface is important because it defines how Mastra Tutorial: TypeScript Framework for AI Agents and Workflows implements the patterns covered in this chapter.
+This function is important because it defines how Mastra Tutorial: TypeScript Framework for AI Agents and Workflows implements the patterns covered in this chapter.
### `explorations/network-validation-bridge.ts`
-The `IterationStatus` interface in [`explorations/network-validation-bridge.ts`](https://github.com/mastra-ai/mastra/blob/HEAD/explorations/network-validation-bridge.ts) handles a key part of this chapter's functionality:
+The `testsPass` function in [`explorations/network-validation-bridge.ts`](https://github.com/mastra-ai/mastra/blob/HEAD/explorations/network-validation-bridge.ts) handles a key part of this chapter's functionality:
```ts
- * Called after each iteration with validation results
- */
- onIteration?: (result: IterationStatus) => void | Promise<void>;
-
- /**
- * Thread ID for memory
- */
- threadId?: string;
-
- /**
- * Resource ID for memory
- */
- resourceId?: string;
-}
-
-export interface IterationStatus {
- iteration: number;
- llmSaysComplete: boolean;
- validationPassed: boolean | null;
- validationResults: ValidationResult[];
- isComplete: boolean;
- primitive: {
- type: 'agent' | 'workflow' | 'tool' | 'none';
- id: string;
- };
- duration: number;
-}
-
-// ============================================================================
-// Validation Check Factories
-// ============================================================================
-
+ * Check if tests pass
+ */
+export function testsPass(command = 'npm test', options?: { timeout?: number; cwd?: string }): ValidationCheck {
+ return {
+ id: 'tests-pass',
+ name: 'Tests Pass',
+ async check() {
+ const start = Date.now();
+ try {
+ const { stdout, stderr } = await execAsync(command, {
+ timeout: options?.timeout ?? 300000,
+ cwd: options?.cwd,
+ });
+ return {
+ success: true,
+ message: 'All tests passed',
+ details: { stdout: stdout.slice(-1000), stderr: stderr.slice(-500) },
+ duration: Date.now() - start,
+ };
+ } catch (error: any) {
+ return {
+ success: false,
+ message: `Tests failed: ${error.message}`,
+ details: {
+ stdout: error.stdout?.slice(-1000),
+ stderr: error.stderr?.slice(-1000),
+ exitCode: error.code,
+ },
+ duration: Date.now() - start,
+ };
+ }
+ },
```
-This interface is important because it defines how Mastra Tutorial: TypeScript Framework for AI Agents and Workflows implements the patterns covered in this chapter.
+This function is important because it defines how Mastra Tutorial: TypeScript Framework for AI Agents and Workflows implements the patterns covered in this chapter.
-### `scripts/generate-package-docs.ts`
+### `explorations/network-validation-bridge.ts`
-The `or` class in [`scripts/generate-package-docs.ts`](https://github.com/mastra-ai/mastra/blob/HEAD/scripts/generate-package-docs.ts) handles a key part of this chapter's functionality:
+The `buildSucceeds` function in [`explorations/network-validation-bridge.ts`](https://github.com/mastra-ai/mastra/blob/HEAD/explorations/network-validation-bridge.ts) handles a key part of this chapter's functionality:
```ts
-#!/usr/bin/env npx tsx
-/**
- * Generates embedded documentation for Mastra packages.
- *
- * Uses docs/build/llms-manifest.json as the data source and copies llms.txt files to a flat structure in each package's dist/docs/references/ directory.
- *
- * Usage:
- * Add "build:docs": "pnpx tsx ../../scripts/generate-package-docs.ts", to your package.json scripts.
- * (Adjust the file path as needed based on your package location)
+ * Check if build succeeds
*/
-
-import fs from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-const MONOREPO_ROOT = path.join(__dirname, '..');
-
-interface ExportInfo {
- types: string;
- implementation: string;
- line?: number;
-}
-
-interface ModuleInfo {
- index: string;
- chunks: string[];
-}
-
-interface SourceMap {
- version: string;
+export function buildSucceeds(
+ command = 'npm run build',
+ options?: { timeout?: number; cwd?: string },
+): ValidationCheck {
+ return {
+ id: 'build-succeeds',
+ name: 'Build Succeeds',
+ async check() {
+ const start = Date.now();
+ try {
+ const { stdout, stderr } = await execAsync(command, {
+ timeout: options?.timeout ?? 600000,
+ cwd: options?.cwd,
+ });
+ return {
+ success: true,
+ message: 'Build completed successfully',
+ details: { stdout: stdout.slice(-500), stderr: stderr.slice(-500) },
+ duration: Date.now() - start,
+ };
+ } catch (error: any) {
+ return {
+ success: false,
+ message: `Build failed: ${error.message}`,
+ details: {
+ stdout: error.stdout?.slice(-1000),
+ stderr: error.stderr?.slice(-1000),
+ },
+ duration: Date.now() - start,
+ };
```
-This class is important because it defines how Mastra Tutorial: TypeScript Framework for AI Agents and Workflows implements the patterns covered in this chapter.
+This function is important because it defines how Mastra Tutorial: TypeScript Framework for AI Agents and Workflows implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[NetworkValidationConfig]
- B[ValidatedNetworkOptions]
- C[IterationStatus]
- D[or]
- E[cachedExists]
+ A[spawn]
+ B[findLinkedDependencies]
+ C[testsPass]
+ D[buildSucceeds]
+ E[lintPasses]
A --> B
B --> C
C --> D
diff --git a/tutorials/mastra-tutorial/04-workflows-and-control-flow.md b/tutorials/mastra-tutorial/04-workflows-and-control-flow.md
index 6cb462a4..64c58faa 100644
--- a/tutorials/mastra-tutorial/04-workflows-and-control-flow.md
+++ b/tutorials/mastra-tutorial/04-workflows-and-control-flow.md
@@ -44,170 +44,168 @@ You now know when and how to move from free-form agents to deterministic workflo
Next: [Chapter 5: Memory, RAG, and Context](05-memory-rag-and-context.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `scripts/generate-package-docs.ts`
+### `explorations/network-validation-bridge.ts`
-The `parseIndexExports` function in [`scripts/generate-package-docs.ts`](https://github.com/mastra-ai/mastra/blob/HEAD/scripts/generate-package-docs.ts) handles a key part of this chapter's functionality:
+The `customCheck` function in [`explorations/network-validation-bridge.ts`](https://github.com/mastra-ai/mastra/blob/HEAD/explorations/network-validation-bridge.ts) handles a key part of this chapter's functionality:
```ts
+ * Custom validation check from a function
+ */
+export function customCheck(
+ id: string,
+ name: string,
+ fn: () => Promise<{ success: boolean; message: string; details?: Record<string, unknown> }>,
+): ValidationCheck {
+ return {
+ id,
+ name,
+ async check() {
+ const start = Date.now();
+ const result = await fn();
+ return { ...result, duration: Date.now() - start };
+ },
+ };
}
-function parseIndexExports(indexPath: string): Map<string, { chunk: string; exportName: string }> {
- const exports = new Map<string, { chunk: string; exportName: string }>();
-
- if (!cachedExists(indexPath)) {
- return exports;
- }
-
- const content = fs.readFileSync(indexPath, 'utf-8');
-
- // Parse: export { Agent, TripWire } from '../chunk-IDD63DWQ.js';
- const regex = /export\s*\{\s*([^}]+)\s*\}\s*from\s*['"]([^'"]+)['"]/g;
- let match;
-
- while ((match = regex.exec(content)) !== null) {
- const names = match[1].split(',').map(n => n.trim().split(' as ')[0].trim());
- const chunkPath = match[2];
- const chunk = path.basename(chunkPath);
-
- for (const name of names) {
- if (name) {
- exports.set(name, { chunk, exportName: name });
- }
- }
- }
-
- return exports;
-}
-
-function findExportLine(chunkPath: string, exportName: string): number | undefined {
- const lines = getChunkLines(chunkPath);
+/**
+ * File exists check
+ */
+export function fileExists(path: string): ValidationCheck {
+ return {
+ id: `file-exists-${path}`,
+ name: `File Exists: ${path}`,
+ async check() {
+ const start = Date.now();
+ try {
+ const fs = await import('fs/promises');
+ await fs.access(path);
+ return {
+ success: true,
```
This function is important because it defines how Mastra Tutorial: TypeScript Framework for AI Agents and Workflows implements the patterns covered in this chapter.
-### `scripts/generate-package-docs.ts`
+### `explorations/network-validation-bridge.ts`
-The `findExportLine` function in [`scripts/generate-package-docs.ts`](https://github.com/mastra-ai/mastra/blob/HEAD/scripts/generate-package-docs.ts) handles a key part of this chapter's functionality:
+The `fileExists` function in [`explorations/network-validation-bridge.ts`](https://github.com/mastra-ai/mastra/blob/HEAD/explorations/network-validation-bridge.ts) handles a key part of this chapter's functionality:
```ts
-}
-
-function findExportLine(chunkPath: string, exportName: string): number | undefined {
- const lines = getChunkLines(chunkPath);
- if (!lines) return undefined;
-
- // Look for class or function definition
- const patterns = [
- new RegExp(`^var ${exportName} = class`),
- new RegExp(`^function ${exportName}\\s*\\(`),
- new RegExp(`^var ${exportName} = function`),
- new RegExp(`^var ${exportName} = \\(`), // Arrow function
- new RegExp(`^const ${exportName} = `),
- new RegExp(`^let ${exportName} = `),
- ];
-
- for (let i = 0; i < lines.length; i++) {
- for (const pattern of patterns) {
- if (pattern.test(lines[i])) {
- return i + 1; // 1-indexed
+ * File exists check
+ */
+export function fileExists(path: string): ValidationCheck {
+ return {
+ id: `file-exists-${path}`,
+ name: `File Exists: ${path}`,
+ async check() {
+ const start = Date.now();
+ try {
+ const fs = await import('fs/promises');
+ await fs.access(path);
+ return {
+ success: true,
+ message: `File ${path} exists`,
+ duration: Date.now() - start,
+ };
+ } catch {
+ return {
+ success: false,
+ message: `File ${path} does not exist`,
+ duration: Date.now() - start,
+ };
}
- }
- }
-
- return undefined;
+ },
+ };
}
-function generateSourceMap(packageRoot: string): SourceMap {
- const distDir = path.join(packageRoot, 'dist');
- const packageJson = getPackageJson(packageRoot);
-
- const sourceMap: SourceMap = {
+/**
+ * File contains pattern check
+ */
+export function fileContains(path: string, pattern: string | RegExp): ValidationCheck {
+ return {
```
This function is important because it defines how Mastra Tutorial: TypeScript Framework for AI Agents and Workflows implements the patterns covered in this chapter.
-### `scripts/generate-package-docs.ts`
+### `explorations/network-validation-bridge.ts`
-The `generateSourceMap` function in [`scripts/generate-package-docs.ts`](https://github.com/mastra-ai/mastra/blob/HEAD/scripts/generate-package-docs.ts) handles a key part of this chapter's functionality:
+The `fileContains` function in [`explorations/network-validation-bridge.ts`](https://github.com/mastra-ai/mastra/blob/HEAD/explorations/network-validation-bridge.ts) handles a key part of this chapter's functionality:
```ts
-}
-
-function generateSourceMap(packageRoot: string): SourceMap {
- const distDir = path.join(packageRoot, 'dist');
- const packageJson = getPackageJson(packageRoot);
-
- const sourceMap: SourceMap = {
- version: packageJson.version,
- package: packageJson.name,
- exports: {},
- modules: {},
+ * File contains pattern check
+ */
+export function fileContains(path: string, pattern: string | RegExp): ValidationCheck {
+ return {
+ id: `file-contains-${path}`,
+ name: `File Contains Pattern: ${path}`,
+ async check() {
+ const start = Date.now();
+ try {
+ const fs = await import('fs/promises');
+ const content = await fs.readFile(path, 'utf-8');
+ const matches = typeof pattern === 'string' ? content.includes(pattern) : pattern.test(content);
+
+ return {
+ success: matches,
+ message: matches
+ ? `File ${path} contains expected pattern`
+ : `File ${path} does not contain expected pattern`,
+ duration: Date.now() - start,
+ };
+ } catch (error: any) {
+ return {
+ success: false,
+ message: `Could not read file ${path}: ${error.message}`,
+ duration: Date.now() - start,
+ };
+ }
+ },
};
+}
- // Default modules to analyze
- const modules = [
- 'agent',
- 'tools',
- 'workflows',
- 'memory',
- 'stream',
- 'llm',
- 'mastra',
- 'mcp',
- 'evals',
- 'processors',
- 'storage',
- 'vector',
- 'voice',
- ];
-
- for (const mod of modules) {
- const indexPath = path.join(distDir, mod, 'index.js');
+// ============================================================================
```
This function is important because it defines how Mastra Tutorial: TypeScript Framework for AI Agents and Workflows implements the patterns covered in this chapter.
-### `scripts/generate-package-docs.ts`
+### `explorations/network-validation-bridge.ts`
-The `loadLlmsManifest` function in [`scripts/generate-package-docs.ts`](https://github.com/mastra-ai/mastra/blob/HEAD/scripts/generate-package-docs.ts) handles a key part of this chapter's functionality:
+The `runValidation` function in [`explorations/network-validation-bridge.ts`](https://github.com/mastra-ai/mastra/blob/HEAD/explorations/network-validation-bridge.ts) handles a key part of this chapter's functionality:
```ts
-}
-
-function loadLlmsManifest(): LlmsManifest {
- const manifestPath = path.join(MONOREPO_ROOT, 'docs/build/llms-manifest.json');
- if (!cachedExists(manifestPath)) {
- throw new Error('docs/build/llms-manifest.json not found. Run docs build first.');
+// ============================================================================
+
+async function runValidation(
+ config: NetworkValidationConfig,
+): Promise<{ passed: boolean; results: ValidationResult[] }> {
+ const results: ValidationResult[] = [];
+
+ if (config.parallel) {
+ // Run all checks in parallel
+ const checkResults = await Promise.all(config.checks.map(check => check.check()));
+ results.push(...checkResults);
+ } else {
+ // Run checks sequentially (can short-circuit on failure for 'all' strategy)
+ for (const check of config.checks) {
+ const result = await check.check();
+ results.push(result);
+
+ // Short-circuit for 'all' strategy if a check fails
+ if (config.strategy === 'all' && !result.success) {
+ break;
+ }
+ // Short-circuit for 'any' strategy if a check passes
+ if (config.strategy === 'any' && result.success) {
+ break;
+ }
+ }
}
- return JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
-}
-function generateFlatFileName(entry: ManifestEntry): string {
- // Convert: { category: "docs", folderPath: "agents/adding-voice" }
- // To: "docs-agents-adding-voice.md"
+ const passed = config.strategy === 'all' ? results.every(r => r.success) : results.some(r => r.success);
- if (!entry.folderPath) {
- // Root level doc: just use category
- return `${entry.category}.md`;
- }
-
- const pathPart = entry.folderPath.replace(/\//g, '-');
- return `${entry.category}-${pathPart}.md`;
+ return { passed, results };
}
-
-function generateSkillMd(packageName: string, version: string, entries: ManifestEntry[]): string {
- // Generate compliant name: lowercase, hyphens, max 64 chars
- // "@mastra/core" -> "mastra-core"
- const skillName = packageName.replace('@', '').replace('/', '-').toLowerCase();
-
- // Generate description (max 1024 chars)
- const description = `Documentation for ${packageName}. Use when working with ${packageName} APIs, configuration, or implementation.`;
-
- // Group entries by category
```
This function is important because it defines how Mastra Tutorial: TypeScript Framework for AI Agents and Workflows implements the patterns covered in this chapter.
@@ -217,11 +215,11 @@ This function is important because it defines how Mastra Tutorial: TypeScript Fr
```mermaid
flowchart TD
- A[parseIndexExports]
- B[findExportLine]
- C[generateSourceMap]
- D[loadLlmsManifest]
- E[generateFlatFileName]
+ A[customCheck]
+ B[fileExists]
+ C[fileContains]
+ D[runValidation]
+ E[createValidationTools]
A --> B
B --> C
C --> D
diff --git a/tutorials/mastra-tutorial/05-memory-rag-and-context.md b/tutorials/mastra-tutorial/05-memory-rag-and-context.md
index 3f280423..9ec634c0 100644
--- a/tutorials/mastra-tutorial/05-memory-rag-and-context.md
+++ b/tutorials/mastra-tutorial/05-memory-rag-and-context.md
@@ -39,184 +39,182 @@ You now have a maintainable context strategy for long-lived Mastra systems.
Next: [Chapter 6: MCP and Integration Patterns](06-mcp-and-integration-patterns.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `scripts/generate-package-docs.ts`
+### `explorations/network-validation-bridge.ts`
-The `copyDocumentation` function in [`scripts/generate-package-docs.ts`](https://github.com/mastra-ai/mastra/blob/HEAD/scripts/generate-package-docs.ts) handles a key part of this chapter's functionality:
+The `ValidationCheck` interface in [`explorations/network-validation-bridge.ts`](https://github.com/mastra-ai/mastra/blob/HEAD/explorations/network-validation-bridge.ts) handles a key part of this chapter's functionality:
```ts
-}
-
-function copyDocumentation(manifest: LlmsManifest, packageName: string, docsOutputDir: string): void {
- const entries = manifest.packages[packageName] || [];
- const referencesDir = path.join(docsOutputDir, 'references');
+// ============================================================================
- fs.mkdirSync(referencesDir, { recursive: true });
-
- for (const entry of entries) {
- const sourcePath = path.join(MONOREPO_ROOT, 'docs/build', entry.path);
- const targetFileName = generateFlatFileName(entry);
- const targetPath = path.join(referencesDir, targetFileName);
-
- if (cachedExists(sourcePath)) {
- fs.copyFileSync(sourcePath, targetPath);
- } else {
- console.warn(` Warning: Source not found: ${sourcePath}`);
- }
- }
+export interface ValidationCheck {
+ id: string;
+ name: string;
+ check: () => Promise<ValidationResult>;
}
-// Cache for package.json contents
-const packageJsonCache = new Map<string, { name: string; version: string }>();
-
-function getPackageJson(packageRoot: string): { name: string; version: string } {
- const cached = packageJsonCache.get(packageRoot);
- if (cached) return cached;
-
- const packageJsonPath = path.join(packageRoot, 'package.json');
- if (!cachedExists(packageJsonPath)) {
- throw new Error(`package.json not found in ${packageRoot}`);
- }
-```
-
-This function is important because it defines how Mastra Tutorial: TypeScript Framework for AI Agents and Workflows implements the patterns covered in this chapter.
-
-### `scripts/generate-package-docs.ts`
-
-The `getPackageJson` function in [`scripts/generate-package-docs.ts`](https://github.com/mastra-ai/mastra/blob/HEAD/scripts/generate-package-docs.ts) handles a key part of this chapter's functionality:
+export interface ValidationResult {
+ success: boolean;
+ message: string;
+ details?: Record<string, unknown>;
+ duration?: number;
+}
-```ts
-function generateSourceMap(packageRoot: string): SourceMap {
- const distDir = path.join(packageRoot, 'dist');
- const packageJson = getPackageJson(packageRoot);
-
- const sourceMap: SourceMap = {
- version: packageJson.version,
- package: packageJson.name,
- exports: {},
- modules: {},
- };
-
- // Default modules to analyze
- const modules = [
- 'agent',
- 'tools',
- 'workflows',
- 'memory',
- 'stream',
- 'llm',
- 'mastra',
- 'mcp',
- 'evals',
- 'processors',
- 'storage',
- 'vector',
- 'voice',
- ];
-
- for (const mod of modules) {
- const indexPath = path.join(distDir, mod, 'index.js');
-
- if (!cachedExists(indexPath)) {
+export interface NetworkValidationConfig {
+ /**
+ * Array of validation checks to run
+ */
+ checks: ValidationCheck[];
+
+ /**
+ * How to combine check results:
+ * - 'all': All checks must pass
+ * - 'any': At least one check must pass
+ * - 'weighted': Use weights (future)
+ */
+ strategy: 'all' | 'any';
+
+ /**
+ * How validation interacts with LLM completion assessment:
+ * - 'verify': LLM says complete AND validation passes
```
-This function is important because it defines how Mastra Tutorial: TypeScript Framework for AI Agents and Workflows implements the patterns covered in this chapter.
+This interface is important because it defines how Mastra Tutorial: TypeScript Framework for AI Agents and Workflows implements the patterns covered in this chapter.
-### `scripts/generate-package-docs.ts`
+### `explorations/network-validation-bridge.ts`
-The `generateDocsForPackage` function in [`scripts/generate-package-docs.ts`](https://github.com/mastra-ai/mastra/blob/HEAD/scripts/generate-package-docs.ts) handles a key part of this chapter's functionality:
+The `ValidationResult` interface in [`explorations/network-validation-bridge.ts`](https://github.com/mastra-ai/mastra/blob/HEAD/explorations/network-validation-bridge.ts) handles a key part of this chapter's functionality:
```ts
+ id: string;
+ name: string;
+ check: () => Promise<ValidationResult>;
}
-function generateDocsForPackage(packageName: string, packageRoot: string, manifest: LlmsManifest): void {
- const packageJson = getPackageJson(packageRoot);
- const docsOutputDir = path.join(packageRoot, 'dist', 'docs');
- const entries = manifest.packages[packageName];
+export interface ValidationResult {
+ success: boolean;
+ message: string;
+ details?: Record<string, unknown>;
+ duration?: number;
+}
- if (!entries || entries.length === 0) {
- console.warn(`No documentation found for ${packageName} in manifest`);
- return;
- }
+export interface NetworkValidationConfig {
+ /**
+ * Array of validation checks to run
+ */
+ checks: ValidationCheck[];
+
+ /**
+ * How to combine check results:
+ * - 'all': All checks must pass
+ * - 'any': At least one check must pass
+ * - 'weighted': Use weights (future)
+ */
+ strategy: 'all' | 'any';
+
+ /**
+ * How validation interacts with LLM completion assessment:
+ * - 'verify': LLM says complete AND validation passes
+ * - 'override': Only validation matters, ignore LLM
+ * - 'llm-fallback': Try validation first, use LLM if no checks configured
+ */
+```
- console.info(`\nGenerating documentation for ${packageName} (${entries.length} files)\n`);
+This interface is important because it defines how Mastra Tutorial: TypeScript Framework for AI Agents and Workflows implements the patterns covered in this chapter.
- // Clean and create directory structure
- if (cachedExists(docsOutputDir)) {
- fs.rmSync(docsOutputDir, { recursive: true });
- // Clear from cache since we deleted it
- existsCache.delete(docsOutputDir);
- }
- fs.mkdirSync(path.join(docsOutputDir, 'references'), { recursive: true });
- fs.mkdirSync(path.join(docsOutputDir, 'assets'), { recursive: true });
+### `explorations/network-validation-bridge.ts`
- // Step 1: Generate SOURCE_MAP.json in assets/
- const sourcemap = generateSourceMap(packageRoot);
- fs.writeFileSync(path.join(docsOutputDir, 'assets', 'SOURCE_MAP.json'), JSON.stringify(sourcemap, null, 2), 'utf-8');
+The `NetworkValidationConfig` interface in [`explorations/network-validation-bridge.ts`](https://github.com/mastra-ai/mastra/blob/HEAD/explorations/network-validation-bridge.ts) handles a key part of this chapter's functionality:
- // Step 2: Copy documentation files
- copyDocumentation(manifest, packageName, docsOutputDir);
+```ts
+}
- // Step 3: Generate SKILL.md
- const skillMd = generateSkillMd(packageName, packageJson.version, entries);
+export interface NetworkValidationConfig {
+ /**
+ * Array of validation checks to run
+ */
+ checks: ValidationCheck[];
+
+ /**
+ * How to combine check results:
+ * - 'all': All checks must pass
+ * - 'any': At least one check must pass
+ * - 'weighted': Use weights (future)
+ */
+ strategy: 'all' | 'any';
+
+ /**
+ * How validation interacts with LLM completion assessment:
+ * - 'verify': LLM says complete AND validation passes
+ * - 'override': Only validation matters, ignore LLM
+ * - 'llm-fallback': Try validation first, use LLM if no checks configured
+ */
+ mode: 'verify' | 'override' | 'llm-fallback';
+
+ /**
+ * Maximum time for all validation checks (ms)
+ */
+ timeout?: number;
+
+ /**
+ * Run validation in parallel or sequentially
+ */
```
-This function is important because it defines how Mastra Tutorial: TypeScript Framework for AI Agents and Workflows implements the patterns covered in this chapter.
+This interface is important because it defines how Mastra Tutorial: TypeScript Framework for AI Agents and Workflows implements the patterns covered in this chapter.
-### `scripts/generate-package-docs.ts`
+### `explorations/network-validation-bridge.ts`
-The `main` function in [`scripts/generate-package-docs.ts`](https://github.com/mastra-ai/mastra/blob/HEAD/scripts/generate-package-docs.ts) handles a key part of this chapter's functionality:
+The `ValidatedNetworkOptions` interface in [`explorations/network-validation-bridge.ts`](https://github.com/mastra-ai/mastra/blob/HEAD/explorations/network-validation-bridge.ts) handles a key part of this chapter's functionality:
```ts
-## When to use
-
-Use this skill whenever you are working with ${packageName} to obtain the domain-specific knowledge.
-
-## How to use
-
-Read the individual reference documents for detailed explanations and code examples.
-${docList}
-
-Read [assets/SOURCE_MAP.json](assets/SOURCE_MAP.json) for source code references.`;
}
-function copyDocumentation(manifest: LlmsManifest, packageName: string, docsOutputDir: string): void {
- const entries = manifest.packages[packageName] || [];
- const referencesDir = path.join(docsOutputDir, 'references');
-
- fs.mkdirSync(referencesDir, { recursive: true });
-
- for (const entry of entries) {
- const sourcePath = path.join(MONOREPO_ROOT, 'docs/build', entry.path);
- const targetFileName = generateFlatFileName(entry);
- const targetPath = path.join(referencesDir, targetFileName);
-
- if (cachedExists(sourcePath)) {
- fs.copyFileSync(sourcePath, targetPath);
- } else {
- console.warn(` Warning: Source not found: ${sourcePath}`);
- }
- }
+export interface ValidatedNetworkOptions {
+ /**
+ * Maximum iterations before stopping
+ */
+ maxIterations: number;
+
+ /**
+ * Validation configuration
+ */
+ validation?: NetworkValidationConfig;
+
+ /**
+ * Called after each iteration with validation results
+ */
+ onIteration?: (result: IterationStatus) => void | Promise<void>;
+
+ /**
+ * Thread ID for memory
+ */
+ threadId?: string;
+
+ /**
+ * Resource ID for memory
+ */
+ resourceId?: string;
}
-// Cache for package.json contents
+export interface IterationStatus {
+ iteration: number;
+ llmSaysComplete: boolean;
```
-This function is important because it defines how Mastra Tutorial: TypeScript Framework for AI Agents and Workflows implements the patterns covered in this chapter.
+This interface is important because it defines how Mastra Tutorial: TypeScript Framework for AI Agents and Workflows implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[copyDocumentation]
- B[getPackageJson]
- C[generateDocsForPackage]
- D[main]
- E[ExportInfo]
+ A[ValidationCheck]
+ B[ValidationResult]
+ C[NetworkValidationConfig]
+ D[ValidatedNetworkOptions]
+ E[IterationStatus]
A --> B
B --> C
C --> D
diff --git a/tutorials/mastra-tutorial/06-mcp-and-integration-patterns.md b/tutorials/mastra-tutorial/06-mcp-and-integration-patterns.md
index 5412f184..f74f1880 100644
--- a/tutorials/mastra-tutorial/06-mcp-and-integration-patterns.md
+++ b/tutorials/mastra-tutorial/06-mcp-and-integration-patterns.md
@@ -38,170 +38,168 @@ You now understand how to connect Mastra agents to broader MCP and application e
Next: [Chapter 7: Evals, Observability, and Quality](07-evals-observability-and-quality.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `scripts/generate-package-docs.ts`
-
-The `SourceMap` interface in [`scripts/generate-package-docs.ts`](https://github.com/mastra-ai/mastra/blob/HEAD/scripts/generate-package-docs.ts) handles a key part of this chapter's functionality:
-
-```ts
-}
-
-interface SourceMap {
- version: string;
- package: string;
- exports: Record<string, ExportInfo>;
- modules: Record<string, ModuleInfo>;
-}
-
-interface ManifestEntry {
- path: string; // e.g., "docs/agents/adding-voice/llms.txt"
- title: string;
- description?: string;
- category: string; // "docs", "reference", "guides", "models"
- folderPath: string; // e.g., "agents/adding-voice"
-}
-
-interface LlmsManifest {
- version: string;
- generatedAt: string;
- packages: Record<string, ManifestEntry[]>;
-}
+### `scripts/install-example.js`
-// Cache for chunk file contents and their pre-split lines
-const chunkCache = new Map<string, string[] | null>();
+The `findLinkedDependencies` function in [`scripts/install-example.js`](https://github.com/mastra-ai/mastra/blob/HEAD/scripts/install-example.js) handles a key part of this chapter's functionality:
-// Cache for file existence checks
-const existsCache = new Map<string, boolean>();
+```js
+ * @returns {Object} An object containing all linked dependencies
+ */
+function findLinkedDependencies(dir, protocol = 'link:') {
+ try {
+ // Read package.json from current working directory
+ const packageJson = JSON.parse(readFileSync(`${dir}/package.json`, 'utf8'));
+
+ // Initialize an object to store linked dependencies
+ const linkedDependencies = {};
+
+ // Check regular dependencies
+ if (packageJson.dependencies) {
+ for (const [name, version] of Object.entries(packageJson.dependencies)) {
+ if (typeof version === 'string' && version.startsWith(protocol)) {
+ linkedDependencies[name] = version;
+ }
+ }
+ }
+
+ // Check dev dependencies
+ if (packageJson.devDependencies) {
+ for (const [name, version] of Object.entries(packageJson.devDependencies)) {
+ if (typeof version === 'string' && version.startsWith(protocol)) {
+ linkedDependencies[name] = version;
+ }
+ }
+ }
-function cachedExists(filePath: string): boolean {
- const cached = existsCache.get(filePath);
- if (cached !== undefined) return cached;
+ // Check peer dependencies
+ if (packageJson.peerDependencies) {
+ for (const [name, version] of Object.entries(packageJson.peerDependencies)) {
+ if (typeof version === 'string' && version.startsWith(protocol)) {
```
-This interface is important because it defines how Mastra Tutorial: TypeScript Framework for AI Agents and Workflows implements the patterns covered in this chapter.
-
-### `scripts/generate-package-docs.ts`
+This function is important because it defines how Mastra Tutorial: TypeScript Framework for AI Agents and Workflows implements the patterns covered in this chapter.
-The `ManifestEntry` interface in [`scripts/generate-package-docs.ts`](https://github.com/mastra-ai/mastra/blob/HEAD/scripts/generate-package-docs.ts) handles a key part of this chapter's functionality:
+### `scripts/commonjs-tsc-fixer.js`
-```ts
-}
+The `slash` function in [`scripts/commonjs-tsc-fixer.js`](https://github.com/mastra-ai/mastra/blob/HEAD/scripts/commonjs-tsc-fixer.js) handles a key part of this chapter's functionality:
-interface ManifestEntry {
- path: string; // e.g., "docs/agents/adding-voice/llms.txt"
- title: string;
- description?: string;
- category: string; // "docs", "reference", "guides", "models"
- folderPath: string; // e.g., "agents/adding-voice"
-}
+```js
+import { globby } from 'globby';
-interface LlmsManifest {
- version: string;
- generatedAt: string;
- packages: Record<string, ManifestEntry[]>;
+/** Convert Windows backslashes to posix forward slashes */
+function slash(p) {
+ return p.replaceAll('\\', '/');
}
-// Cache for chunk file contents and their pre-split lines
-const chunkCache = new Map<string, string[] | null>();
+async function cleanupDtsFiles() {
+ const rootPath = process.cwd();
+ const files = await globby('./*.d.ts', { cwd: rootPath });
-// Cache for file existence checks
-const existsCache = new Map<string, boolean>();
-
-function cachedExists(filePath: string): boolean {
- const cached = existsCache.get(filePath);
- if (cached !== undefined) return cached;
- const exists = fs.existsSync(filePath);
- existsCache.set(filePath, exists);
- return exists;
+ for (const file of files) {
+ await rm(join(rootPath, file), { force: true });
+ }
}
-function getChunkLines(chunkPath: string): string[] | null {
- const cached = chunkCache.get(chunkPath);
-```
-
-This interface is important because it defines how Mastra Tutorial: TypeScript Framework for AI Agents and Workflows implements the patterns covered in this chapter.
+async function writeDtsFiles() {
+ const rootPath = process.cwd();
+ const packageJson = JSON.parse(await readFile(join(rootPath, 'package.json')));
-### `scripts/generate-package-docs.ts`
+ const exports = packageJson.exports;
-The `LlmsManifest` interface in [`scripts/generate-package-docs.ts`](https://github.com/mastra-ai/mastra/blob/HEAD/scripts/generate-package-docs.ts) handles a key part of this chapter's functionality:
+ // Handle specific path exports
+ for (const [key, value] of Object.entries(exports)) {
+ if (key !== '.' && value.require?.types) {
+ const pattern = value.require.types;
+ const matches = await globby(pattern, {
+ cwd: rootPath,
+ absolute: true,
+ });
-```ts
-}
+ for (const file of matches) {
+```
-interface LlmsManifest {
- version: string;
- generatedAt: string;
- packages: Record<string, ManifestEntry[]>;
-}
+This function is important because it defines how Mastra Tutorial: TypeScript Framework for AI Agents and Workflows implements the patterns covered in this chapter.
-// Cache for chunk file contents and their pre-split lines
-const chunkCache = new Map<string, string[] | null>();
+### `scripts/commonjs-tsc-fixer.js`
-// Cache for file existence checks
-const existsCache = new Map<string, boolean>();
+The `cleanupDtsFiles` function in [`scripts/commonjs-tsc-fixer.js`](https://github.com/mastra-ai/mastra/blob/HEAD/scripts/commonjs-tsc-fixer.js) handles a key part of this chapter's functionality:
-function cachedExists(filePath: string): boolean {
- const cached = existsCache.get(filePath);
- if (cached !== undefined) return cached;
- const exists = fs.existsSync(filePath);
- existsCache.set(filePath, exists);
- return exists;
+```js
}
-function getChunkLines(chunkPath: string): string[] | null {
- const cached = chunkCache.get(chunkPath);
- if (cached !== undefined) return cached;
+async function cleanupDtsFiles() {
+ const rootPath = process.cwd();
+ const files = await globby('./*.d.ts', { cwd: rootPath });
- if (!cachedExists(chunkPath)) {
- chunkCache.set(chunkPath, null);
- return null;
+ for (const file of files) {
+ await rm(join(rootPath, file), { force: true });
}
+}
- try {
+async function writeDtsFiles() {
+ const rootPath = process.cwd();
+ const packageJson = JSON.parse(await readFile(join(rootPath, 'package.json')));
+
+ const exports = packageJson.exports;
+
+ // Handle specific path exports
+ for (const [key, value] of Object.entries(exports)) {
+ if (key !== '.' && value.require?.types) {
+ const pattern = value.require.types;
+ const matches = await globby(pattern, {
+ cwd: rootPath,
+ absolute: true,
+ });
+
+ for (const file of matches) {
+ if (key.endsWith('*')) {
+ // For wildcard patterns, derive the subpath relative to dist/
+ const dir = dirname(file);
+ const distRoot = join(rootPath, 'dist');
+ const subPath = slash(relative(distRoot, dir));
```
-This interface is important because it defines how Mastra Tutorial: TypeScript Framework for AI Agents and Workflows implements the patterns covered in this chapter.
+This function is important because it defines how Mastra Tutorial: TypeScript Framework for AI Agents and Workflows implements the patterns covered in this chapter.
-### `explorations/ralph-wiggum-loop-prototype.ts`
+### `scripts/commonjs-tsc-fixer.js`
-The `testsPassing` function in [`explorations/ralph-wiggum-loop-prototype.ts`](https://github.com/mastra-ai/mastra/blob/HEAD/explorations/ralph-wiggum-loop-prototype.ts) handles a key part of this chapter's functionality:
+The `writeDtsFiles` function in [`scripts/commonjs-tsc-fixer.js`](https://github.com/mastra-ai/mastra/blob/HEAD/scripts/commonjs-tsc-fixer.js) handles a key part of this chapter's functionality:
-```ts
- * Check if tests pass
- */
-export function testsPassing(testCommand = 'npm test'): CompletionChecker {
- return {
- async check() {
- try {
- const { stdout, stderr } = await execAsync(testCommand, { timeout: 300000 });
- return {
- success: true,
- message: 'All tests passed',
- data: { stdout, stderr },
- };
- } catch (error: any) {
- return {
- success: false,
- message: error.message,
- data: { stdout: error.stdout, stderr: error.stderr },
- };
- }
- },
- };
+```js
}
-/**
- * Check if build succeeds
- */
-export function buildSucceeds(buildCommand = 'npm run build'): CompletionChecker {
- return {
- async check() {
- try {
- const { stdout, stderr } = await execAsync(buildCommand, { timeout: 600000 });
- return {
+async function writeDtsFiles() {
+ const rootPath = process.cwd();
+ const packageJson = JSON.parse(await readFile(join(rootPath, 'package.json')));
+
+ const exports = packageJson.exports;
+
+ // Handle specific path exports
+ for (const [key, value] of Object.entries(exports)) {
+ if (key !== '.' && value.require?.types) {
+ const pattern = value.require.types;
+ const matches = await globby(pattern, {
+ cwd: rootPath,
+ absolute: true,
+ });
+
+ for (const file of matches) {
+ if (key.endsWith('*')) {
+ // For wildcard patterns, derive the subpath relative to dist/
+ const dir = dirname(file);
+ const distRoot = join(rootPath, 'dist');
+ const subPath = slash(relative(distRoot, dir));
+ const filename = key.replace('*', subPath);
+
+ const targetPath = join(rootPath, filename) + '.d.ts';
+ await mkdir(dirname(targetPath), { recursive: true });
+
+ const relPath = slash(relative(dirname(targetPath), file)).replace('/index.d.ts', '');
+ await writeFile(targetPath, `export * from './${relPath}';`);
+ } else {
+ const targetPath = join(rootPath, key) + '.d.ts';
```
This function is important because it defines how Mastra Tutorial: TypeScript Framework for AI Agents and Workflows implements the patterns covered in this chapter.
@@ -211,11 +209,11 @@ This function is important because it defines how Mastra Tutorial: TypeScript Fr
```mermaid
flowchart TD
- A[SourceMap]
- B[ManifestEntry]
- C[LlmsManifest]
- D[testsPassing]
- E[buildSucceeds]
+ A[findLinkedDependencies]
+ B[slash]
+ C[cleanupDtsFiles]
+ D[writeDtsFiles]
+ E[or]
A --> B
B --> C
C --> D
diff --git a/tutorials/mastra-tutorial/07-evals-observability-and-quality.md b/tutorials/mastra-tutorial/07-evals-observability-and-quality.md
index 320f8398..d36ba677 100644
--- a/tutorials/mastra-tutorial/07-evals-observability-and-quality.md
+++ b/tutorials/mastra-tutorial/07-evals-observability-and-quality.md
@@ -40,170 +40,168 @@ You now have a measurable process for improving Mastra quality over time.
Next: [Chapter 8: Production Deployment and Scaling](08-production-deployment-and-scaling.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `explorations/ralph-wiggum-loop-prototype.ts`
+### `scripts/generate-package-docs.ts`
-The `outputContains` function in [`explorations/ralph-wiggum-loop-prototype.ts`](https://github.com/mastra-ai/mastra/blob/HEAD/explorations/ralph-wiggum-loop-prototype.ts) handles a key part of this chapter's functionality:
+The `getChunkLines` function in [`scripts/generate-package-docs.ts`](https://github.com/mastra-ai/mastra/blob/HEAD/scripts/generate-package-docs.ts) handles a key part of this chapter's functionality:
```ts
- * Check if output contains a specific string/pattern
- */
-export function outputContains(pattern: string | RegExp): CompletionChecker {
- let lastOutput = '';
- return {
- async check() {
- const matches = typeof pattern === 'string' ? lastOutput.includes(pattern) : pattern.test(lastOutput);
-
- return {
- success: matches,
- message: matches ? `Output contains pattern` : `Output does not contain pattern`,
- };
- },
- // Helper to set output for checking
- setOutput: (output: string) => {
- lastOutput = output;
- },
- } as CompletionChecker & { setOutput: (output: string) => void };
}
-/**
- * Combine multiple checkers (all must pass)
- */
-export function allCheckersPassing(...checkers: CompletionChecker[]): CompletionChecker {
- return {
- async check() {
- const results = await Promise.all(checkers.map(c => c.check()));
- const allPassed = results.every(r => r.success);
-
- return {
- success: allPassed,
- message: results.map(r => r.message).join('; '),
+function getChunkLines(chunkPath: string): string[] | null {
+ const cached = chunkCache.get(chunkPath);
+ if (cached !== undefined) return cached;
+
+ if (!cachedExists(chunkPath)) {
+ chunkCache.set(chunkPath, null);
+ return null;
+ }
+
+ try {
+ const stat = fs.statSync(chunkPath);
+ if (!stat.isFile()) {
+ chunkCache.set(chunkPath, null);
+ return null;
+ }
+ } catch {
+ chunkCache.set(chunkPath, null);
+ return null;
+ }
+
+ const content = fs.readFileSync(chunkPath, 'utf-8');
+ const lines = content.split('\n');
+ chunkCache.set(chunkPath, lines);
+ return lines;
+}
+
+function parseIndexExports(indexPath: string): Map<string, { chunk: string; exportName: string }> {
+ const exports = new Map<string, { chunk: string; exportName: string }>();
+
+ if (!cachedExists(indexPath)) {
```
This function is important because it defines how Mastra Tutorial: TypeScript Framework for AI Agents and Workflows implements the patterns covered in this chapter.
-### `explorations/ralph-wiggum-loop-prototype.ts`
+### `scripts/generate-package-docs.ts`
-The `allCheckersPassing` function in [`explorations/ralph-wiggum-loop-prototype.ts`](https://github.com/mastra-ai/mastra/blob/HEAD/explorations/ralph-wiggum-loop-prototype.ts) handles a key part of this chapter's functionality:
+The `parseIndexExports` function in [`scripts/generate-package-docs.ts`](https://github.com/mastra-ai/mastra/blob/HEAD/scripts/generate-package-docs.ts) handles a key part of this chapter's functionality:
```ts
- * Combine multiple checkers (all must pass)
- */
-export function allCheckersPassing(...checkers: CompletionChecker[]): CompletionChecker {
- return {
- async check() {
- const results = await Promise.all(checkers.map(c => c.check()));
- const allPassed = results.every(r => r.success);
-
- return {
- success: allPassed,
- message: results.map(r => r.message).join('; '),
- data: { results },
- };
- },
- };
}
-// ============================================================================
-// Core Implementation
-// ============================================================================
-
-/**
- * Creates an autonomous loop workflow for an agent.
- *
- * This implements the Ralph Wiggum pattern: the agent iterates on a task
- * until completion criteria are met or max iterations are reached.
- */
-export function createAutonomousLoopWorkflow(agent: Agent, mastra?: Mastra) {
- const iterationSchema = z.object({
- prompt: z.string(),
- iteration: z.number(),
- previousResults: z.array(
+function parseIndexExports(indexPath: string): Map<string, { chunk: string; exportName: string }> {
+ const exports = new Map<string, { chunk: string; exportName: string }>();
+
+ if (!cachedExists(indexPath)) {
+ return exports;
+ }
+
+ const content = fs.readFileSync(indexPath, 'utf-8');
+
+ // Parse: export { Agent, TripWire } from '../chunk-IDD63DWQ.js';
+ const regex = /export\s*\{\s*([^}]+)\s*\}\s*from\s*['"]([^'"]+)['"]/g;
+ let match;
+
+ while ((match = regex.exec(content)) !== null) {
+ const names = match[1].split(',').map(n => n.trim().split(' as ')[0].trim());
+ const chunkPath = match[2];
+ const chunk = path.basename(chunkPath);
+
+ for (const name of names) {
+ if (name) {
+ exports.set(name, { chunk, exportName: name });
+ }
+ }
+ }
+
+ return exports;
+}
+
+function findExportLine(chunkPath: string, exportName: string): number | undefined {
+ const lines = getChunkLines(chunkPath);
```
This function is important because it defines how Mastra Tutorial: TypeScript Framework for AI Agents and Workflows implements the patterns covered in this chapter.
-### `explorations/ralph-wiggum-loop-prototype.ts`
+### `scripts/generate-package-docs.ts`
-The `createAutonomousLoopWorkflow` function in [`explorations/ralph-wiggum-loop-prototype.ts`](https://github.com/mastra-ai/mastra/blob/HEAD/explorations/ralph-wiggum-loop-prototype.ts) handles a key part of this chapter's functionality:
+The `findExportLine` function in [`scripts/generate-package-docs.ts`](https://github.com/mastra-ai/mastra/blob/HEAD/scripts/generate-package-docs.ts) handles a key part of this chapter's functionality:
```ts
- * until completion criteria are met or max iterations are reached.
- */
-export function createAutonomousLoopWorkflow(agent: Agent, mastra?: Mastra) {
- const iterationSchema = z.object({
- prompt: z.string(),
- iteration: z.number(),
- previousResults: z.array(
- z.object({
- iteration: z.number(),
- success: z.boolean(),
- output: z.string(),
- error: z.string().optional(),
- }),
- ),
- isComplete: z.boolean(),
- completionMessage: z.string().optional(),
- });
-
- const agentStep = createStep({
- id: 'agent-iteration',
- inputSchema: iterationSchema,
- outputSchema: z.object({
- text: z.string(),
- iteration: z.number(),
- }),
- execute: async ({ inputData }) => {
- // Build context from previous iterations
- let contextualPrompt = inputData.prompt;
-
- if (inputData.previousResults.length > 0) {
- const historyContext = inputData.previousResults
- .slice(-5) // Last 5 iterations
+}
+
+function findExportLine(chunkPath: string, exportName: string): number | undefined {
+ const lines = getChunkLines(chunkPath);
+ if (!lines) return undefined;
+
+ // Look for class or function definition
+ const patterns = [
+ new RegExp(`^var ${exportName} = class`),
+ new RegExp(`^function ${exportName}\\s*\\(`),
+ new RegExp(`^var ${exportName} = function`),
+ new RegExp(`^var ${exportName} = \\(`), // Arrow function
+ new RegExp(`^const ${exportName} = `),
+ new RegExp(`^let ${exportName} = `),
+ ];
+
+ for (let i = 0; i < lines.length; i++) {
+ for (const pattern of patterns) {
+ if (pattern.test(lines[i])) {
+ return i + 1; // 1-indexed
+ }
+ }
+ }
+
+ return undefined;
+}
+
+function generateSourceMap(packageRoot: string): SourceMap {
+ const distDir = path.join(packageRoot, 'dist');
+ const packageJson = getPackageJson(packageRoot);
+
+ const sourceMap: SourceMap = {
```
This function is important because it defines how Mastra Tutorial: TypeScript Framework for AI Agents and Workflows implements the patterns covered in this chapter.
-### `explorations/ralph-wiggum-loop-prototype.ts`
+### `scripts/generate-package-docs.ts`
-The `executeAutonomousLoop` function in [`explorations/ralph-wiggum-loop-prototype.ts`](https://github.com/mastra-ai/mastra/blob/HEAD/explorations/ralph-wiggum-loop-prototype.ts) handles a key part of this chapter's functionality:
+The `generateSourceMap` function in [`scripts/generate-package-docs.ts`](https://github.com/mastra-ai/mastra/blob/HEAD/scripts/generate-package-docs.ts) handles a key part of this chapter's functionality:
```ts
- * Executes an autonomous loop with the given agent and configuration.
- */
-export async function executeAutonomousLoop(
- agent: Agent,
- config: AutonomousLoopConfig,
- mastra?: Mastra,
-): Promise<AutonomousLoopResult> {
- const iterations: IterationResult[] = [];
- let totalTokens = 0;
- const startTime = Date.now();
-
- const contextWindow = config.contextWindow ?? 5;
-
- for (let i = 0; i < config.maxIterations; i++) {
- const iterationStartTime = Date.now();
-
- // Notify iteration start
- await config.onIterationStart?.(i + 1);
-
- // Build context from previous iterations
- const previousResults = iterations.slice(-contextWindow).map(r => ({
- iteration: r.iteration,
- success: r.success,
- output: r.agentOutput,
- error: r.error?.message,
- }));
-
- let contextualPrompt = config.prompt;
- if (previousResults.length > 0) {
- const historyContext = previousResults
- .map(
- r => `
+}
+
+function generateSourceMap(packageRoot: string): SourceMap {
+ const distDir = path.join(packageRoot, 'dist');
+ const packageJson = getPackageJson(packageRoot);
+
+ const sourceMap: SourceMap = {
+ version: packageJson.version,
+ package: packageJson.name,
+ exports: {},
+ modules: {},
+ };
+
+ // Default modules to analyze
+ const modules = [
+ 'agent',
+ 'tools',
+ 'workflows',
+ 'memory',
+ 'stream',
+ 'llm',
+ 'mastra',
+ 'mcp',
+ 'evals',
+ 'processors',
+ 'storage',
+ 'vector',
+ 'voice',
+ ];
+
+ for (const mod of modules) {
+ const indexPath = path.join(distDir, mod, 'index.js');
```
This function is important because it defines how Mastra Tutorial: TypeScript Framework for AI Agents and Workflows implements the patterns covered in this chapter.
@@ -213,11 +211,11 @@ This function is important because it defines how Mastra Tutorial: TypeScript Fr
```mermaid
flowchart TD
- A[outputContains]
- B[allCheckersPassing]
- C[createAutonomousLoopWorkflow]
- D[executeAutonomousLoop]
- E[main]
+ A[getChunkLines]
+ B[parseIndexExports]
+ C[findExportLine]
+ D[generateSourceMap]
+ E[loadLlmsManifest]
A --> B
B --> C
C --> D
diff --git a/tutorials/mastra-tutorial/08-production-deployment-and-scaling.md b/tutorials/mastra-tutorial/08-production-deployment-and-scaling.md
index 102146c5..58e50a3d 100644
--- a/tutorials/mastra-tutorial/08-production-deployment-and-scaling.md
+++ b/tutorials/mastra-tutorial/08-production-deployment-and-scaling.md
@@ -46,168 +46,168 @@ This chapter turns Mastra apps from development projects into operated productio
You now have a deployment and operations baseline for running Mastra systems at production quality.
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `explorations/ralph-wiggum-loop-prototype.ts`
+### `scripts/generate-package-docs.ts`
-The `AutonomousLoopConfig` interface in [`explorations/ralph-wiggum-loop-prototype.ts`](https://github.com/mastra-ai/mastra/blob/HEAD/explorations/ralph-wiggum-loop-prototype.ts) handles a key part of this chapter's functionality:
+The `generateSkillMd` function in [`scripts/generate-package-docs.ts`](https://github.com/mastra-ai/mastra/blob/HEAD/scripts/generate-package-docs.ts) handles a key part of this chapter's functionality:
```ts
}
-export interface AutonomousLoopConfig {
- /** The task prompt to send to the agent */
- prompt: string;
+function generateSkillMd(packageName: string, version: string, entries: ManifestEntry[]): string {
+ // Generate compliant name: lowercase, hyphens, max 64 chars
+ // "@mastra/core" -> "mastra-core"
+ const skillName = packageName.replace('@', '').replace('/', '-').toLowerCase();
+
+ // Generate description (max 1024 chars)
+ const description = `Documentation for ${packageName}. Use when working with ${packageName} APIs, configuration, or implementation.`;
+
+ // Group entries by category
+ const grouped = new Map<string, ManifestEntry[]>();
+ for (const entry of entries) {
+ const cat = entry.category;
+ if (!grouped.has(cat)) grouped.set(cat, []);
+ grouped.get(cat)!.push(entry);
+ }
+
+ // Generate documentation list
+ let docList = '';
+ for (const [category, catEntries] of grouped) {
+ docList += `\n### ${category.charAt(0).toUpperCase() + category.slice(1)}\n\n`;
+ for (const entry of catEntries) {
+ const fileName = generateFlatFileName(entry);
+ docList += `- [${entry.title}](references/${fileName})${entry.description ? ` - ${entry.description}` : ''}\n`;
+ }
+ }
+
+ return `---
+name: ${skillName}
+description: ${description}
+metadata:
+```
- /** How to determine if the task is complete */
- completion: CompletionChecker;
+This function is important because it defines how Mastra Tutorial: TypeScript Framework for AI Agents and Workflows implements the patterns covered in this chapter.
- /** Maximum number of iterations before giving up */
- maxIterations: number;
+### `scripts/generate-package-docs.ts`
- /** Optional: Maximum tokens to spend */
- maxTokens?: number;
+The `copyDocumentation` function in [`scripts/generate-package-docs.ts`](https://github.com/mastra-ai/mastra/blob/HEAD/scripts/generate-package-docs.ts) handles a key part of this chapter's functionality:
- /** Optional: Delay between iterations in ms */
- iterationDelay?: number;
+```ts
+}
- /** Optional: How many previous iteration results to include in context */
- contextWindow?: number;
+function copyDocumentation(manifest: LlmsManifest, packageName: string, docsOutputDir: string): void {
+ const entries = manifest.packages[packageName] || [];
+ const referencesDir = path.join(docsOutputDir, 'references');
- /** Optional: Called after each iteration */
- onIteration?: (result: IterationResult) => void | Promise<void>;
+ fs.mkdirSync(referencesDir, { recursive: true });
- /** Optional: Called when starting an iteration */
- onIterationStart?: (iteration: number) => void | Promise<void>;
-}
+ for (const entry of entries) {
+ const sourcePath = path.join(MONOREPO_ROOT, 'docs/build', entry.path);
+ const targetFileName = generateFlatFileName(entry);
+ const targetPath = path.join(referencesDir, targetFileName);
-export interface IterationResult {
- iteration: number;
- success: boolean;
- agentOutput: string;
-```
+ if (cachedExists(sourcePath)) {
+ fs.copyFileSync(sourcePath, targetPath);
+ } else {
+ console.warn(` Warning: Source not found: ${sourcePath}`);
+ }
+ }
+}
-This interface is important because it defines how Mastra Tutorial: TypeScript Framework for AI Agents and Workflows implements the patterns covered in this chapter.
+// Cache for package.json contents
+const packageJsonCache = new Map<string, { name: string; version: string }>();
-### `explorations/ralph-wiggum-loop-prototype.ts`
+function getPackageJson(packageRoot: string): { name: string; version: string } {
+ const cached = packageJsonCache.get(packageRoot);
+ if (cached) return cached;
-The `IterationResult` interface in [`explorations/ralph-wiggum-loop-prototype.ts`](https://github.com/mastra-ai/mastra/blob/HEAD/explorations/ralph-wiggum-loop-prototype.ts) handles a key part of this chapter's functionality:
+ const packageJsonPath = path.join(packageRoot, 'package.json');
+ if (!cachedExists(packageJsonPath)) {
+ throw new Error(`package.json not found in ${packageRoot}`);
+ }
+```
-```ts
+This function is important because it defines how Mastra Tutorial: TypeScript Framework for AI Agents and Workflows implements the patterns covered in this chapter.
- /** Optional: Called after each iteration */
- onIteration?: (result: IterationResult) => void | Promise<void>;
+### `scripts/generate-package-docs.ts`
- /** Optional: Called when starting an iteration */
- onIterationStart?: (iteration: number) => void | Promise<void>;
-}
+The `getPackageJson` function in [`scripts/generate-package-docs.ts`](https://github.com/mastra-ai/mastra/blob/HEAD/scripts/generate-package-docs.ts) handles a key part of this chapter's functionality:
-export interface IterationResult {
- iteration: number;
- success: boolean;
- agentOutput: string;
- completionCheck: {
- success: boolean;
- message?: string;
+```ts
+function generateSourceMap(packageRoot: string): SourceMap {
+ const distDir = path.join(packageRoot, 'dist');
+ const packageJson = getPackageJson(packageRoot);
+
+ const sourceMap: SourceMap = {
+ version: packageJson.version,
+ package: packageJson.name,
+ exports: {},
+ modules: {},
};
- tokensUsed?: number;
- duration: number;
- error?: Error;
-}
-export interface AutonomousLoopResult {
- success: boolean;
- iterations: IterationResult[];
- totalTokens: number;
- totalDuration: number;
- finalOutput: string;
- completionMessage?: string;
-}
-
-// ============================================================================
-// Completion Checkers (Helpers)
+ // Default modules to analyze
+ const modules = [
+ 'agent',
+ 'tools',
+ 'workflows',
+ 'memory',
+ 'stream',
+ 'llm',
+ 'mastra',
+ 'mcp',
+ 'evals',
+ 'processors',
+ 'storage',
+ 'vector',
+ 'voice',
+ ];
+
+ for (const mod of modules) {
+ const indexPath = path.join(distDir, mod, 'index.js');
+
+ if (!cachedExists(indexPath)) {
```
-This interface is important because it defines how Mastra Tutorial: TypeScript Framework for AI Agents and Workflows implements the patterns covered in this chapter.
+This function is important because it defines how Mastra Tutorial: TypeScript Framework for AI Agents and Workflows implements the patterns covered in this chapter.
-### `explorations/ralph-wiggum-loop-prototype.ts`
+### `scripts/generate-package-docs.ts`
-The `AutonomousLoopResult` interface in [`explorations/ralph-wiggum-loop-prototype.ts`](https://github.com/mastra-ai/mastra/blob/HEAD/explorations/ralph-wiggum-loop-prototype.ts) handles a key part of this chapter's functionality:
+The `generateDocsForPackage` function in [`scripts/generate-package-docs.ts`](https://github.com/mastra-ai/mastra/blob/HEAD/scripts/generate-package-docs.ts) handles a key part of this chapter's functionality:
```ts
}
-export interface AutonomousLoopResult {
- success: boolean;
- iterations: IterationResult[];
- totalTokens: number;
- totalDuration: number;
- finalOutput: string;
- completionMessage?: string;
-}
-
-// ============================================================================
-// Completion Checkers (Helpers)
-// ============================================================================
-
-/**
- * Check if tests pass
- */
-export function testsPassing(testCommand = 'npm test'): CompletionChecker {
- return {
- async check() {
- try {
- const { stdout, stderr } = await execAsync(testCommand, { timeout: 300000 });
- return {
- success: true,
- message: 'All tests passed',
- data: { stdout, stderr },
- };
- } catch (error: any) {
- return {
- success: false,
- message: error.message,
-```
+function generateDocsForPackage(packageName: string, packageRoot: string, manifest: LlmsManifest): void {
+ const packageJson = getPackageJson(packageRoot);
+ const docsOutputDir = path.join(packageRoot, 'dist', 'docs');
+ const entries = manifest.packages[packageName];
-This interface is important because it defines how Mastra Tutorial: TypeScript Framework for AI Agents and Workflows implements the patterns covered in this chapter.
+ if (!entries || entries.length === 0) {
+ console.warn(`No documentation found for ${packageName} in manifest`);
+ return;
+ }
-### `scripts/ignore-example.js`
+ console.info(`\nGenerating documentation for ${packageName} (${entries.length} files)\n`);
-The `spawn` function in [`scripts/ignore-example.js`](https://github.com/mastra-ai/mastra/blob/HEAD/scripts/ignore-example.js) handles a key part of this chapter's functionality:
+ // Clean and create directory structure
+ if (cachedExists(docsOutputDir)) {
+ fs.rmSync(docsOutputDir, { recursive: true });
+ // Clear from cache since we deleted it
+ existsCache.delete(docsOutputDir);
+ }
+ fs.mkdirSync(path.join(docsOutputDir, 'references'), { recursive: true });
+ fs.mkdirSync(path.join(docsOutputDir, 'assets'), { recursive: true });
-```js
-import { spawn as nodeSpawn } from 'child_process';
-import { readFileSync } from 'fs';
-import { dirname, join } from 'path';
-import { fileURLToPath } from 'url';
-
-const dir = process.argv[2];
-if (!dir) {
- console.error('Usage: node scripts/ignore-example.js <directory>');
- process.exit(1);
-}
+ // Step 1: Generate SOURCE_MAP.json in assets/
+ const sourcemap = generateSourceMap(packageRoot);
+ fs.writeFileSync(path.join(docsOutputDir, 'assets', 'SOURCE_MAP.json'), JSON.stringify(sourcemap, null, 2), 'utf-8');
-/**
- * Promisified version of Node.js spawn function
- *
- * @param {string} command - The command to run
- * @param {string[]} args - List of string arguments
- * @param {import('child_process').SpawnOptions} options - Spawn options
- * @returns {Promise<void>} Promise that resolves with the exit code when the process completes
- */
-function spawn(command, args = [], options = {}) {
- return new Promise((resolve, reject) => {
- const childProcess = nodeSpawn(command, args, {
- // stdio: 'inherit',
- ...options,
- });
-
- childProcess.on('error', error => {
- reject(error);
- });
+ // Step 2: Copy documentation files
+ copyDocumentation(manifest, packageName, docsOutputDir);
+ // Step 3: Generate SKILL.md
+ const skillMd = generateSkillMd(packageName, packageJson.version, entries);
```
This function is important because it defines how Mastra Tutorial: TypeScript Framework for AI Agents and Workflows implements the patterns covered in this chapter.
@@ -217,11 +217,11 @@ This function is important because it defines how Mastra Tutorial: TypeScript Fr
```mermaid
flowchart TD
- A[AutonomousLoopConfig]
- B[IterationResult]
- C[AutonomousLoopResult]
- D[spawn]
- E[findLinkedDependencies]
+ A[generateSkillMd]
+ B[copyDocumentation]
+ C[getPackageJson]
+ D[generateDocsForPackage]
+ E[main]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-chrome-tutorial/01-getting-started-and-native-bridge-setup.md b/tutorials/mcp-chrome-tutorial/01-getting-started-and-native-bridge-setup.md
index 1777d1df..83777674 100644
--- a/tutorials/mcp-chrome-tutorial/01-getting-started-and-native-bridge-setup.md
+++ b/tutorials/mcp-chrome-tutorial/01-getting-started-and-native-bridge-setup.md
@@ -49,8 +49,6 @@ You now have MCP Chrome installed and reachable from an MCP client.
Next: [Chapter 2: Architecture and Component Boundaries](02-architecture-and-component-boundaries.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `app/chrome-extension/inject-scripts/element-picker.js`
diff --git a/tutorials/mcp-chrome-tutorial/02-architecture-and-component-boundaries.md b/tutorials/mcp-chrome-tutorial/02-architecture-and-component-boundaries.md
index 9c306843..4b8c8088 100644
--- a/tutorials/mcp-chrome-tutorial/02-architecture-and-component-boundaries.md
+++ b/tutorials/mcp-chrome-tutorial/02-architecture-and-component-boundaries.md
@@ -60,8 +60,6 @@ You now have a clear map of where browser actions, protocol logic, and AI proces
Next: [Chapter 3: Tool Surface: Browser, Network, and Interaction](03-tool-surface-browser-network-and-interaction.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `app/chrome-extension/inject-scripts/element-picker.js`
diff --git a/tutorials/mcp-chrome-tutorial/03-tool-surface-browser-network-and-interaction.md b/tutorials/mcp-chrome-tutorial/03-tool-surface-browser-network-and-interaction.md
index 18a30d16..7fc58d6b 100644
--- a/tutorials/mcp-chrome-tutorial/03-tool-surface-browser-network-and-interaction.md
+++ b/tutorials/mcp-chrome-tutorial/03-tool-surface-browser-network-and-interaction.md
@@ -46,184 +46,159 @@ You now understand how to map tasks to the right MCP Chrome tool group with lowe
Next: [Chapter 4: Semantic Search and Vector Processing](04-semantic-search-and-vector-processing.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `packages/shared/src/agent-types.ts`
+### `app/chrome-extension/utils/content-indexer.ts`
-The `AgentStatusEvent` interface in [`packages/shared/src/agent-types.ts`](https://github.com/hangwin/mcp-chrome/blob/HEAD/packages/shared/src/agent-types.ts) handles a key part of this chapter's functionality:
+The `to` class in [`app/chrome-extension/utils/content-indexer.ts`](https://github.com/hangwin/mcp-chrome/blob/HEAD/app/chrome-extension/utils/content-indexer.ts) handles a key part of this chapter's functionality:
```ts
-export type StreamTransport = 'sse' | 'websocket';
-
-export interface AgentStatusEvent {
- sessionId: string;
- status: 'starting' | 'ready' | 'running' | 'completed' | 'error' | 'cancelled';
- message?: string;
- requestId?: string;
-}
-
-export interface AgentConnectedEvent {
- sessionId: string;
- transport: StreamTransport;
- timestamp: string;
-}
-
-export interface AgentHeartbeatEvent {
- timestamp: string;
-}
-
-/** Usage statistics for a request */
-export interface AgentUsageStats {
- sessionId: string;
- requestId?: string;
- inputTokens: number;
- outputTokens: number;
- cacheReadInputTokens?: number;
- cacheCreationInputTokens?: number;
- totalCostUsd: number;
- durationMs: number;
- numTurns: number;
+/**
+ * Content index manager
+ * Responsible for automatically extracting, chunking and indexing tab content
+ */
+
+import { TextChunker } from './text-chunker';
+import { VectorDatabase, getGlobalVectorDatabase } from './vector-database';
+import {
+ SemanticSimilarityEngine,
+ SemanticSimilarityEngineProxy,
+ PREDEFINED_MODELS,
+ type ModelPreset,
+} from './semantic-similarity-engine';
+import { TOOL_MESSAGE_TYPES } from '@/common/message-types';
+
+export interface IndexingOptions {
+ autoIndex?: boolean;
+ maxChunksPerPage?: number;
+ skipDuplicates?: boolean;
}
+export class ContentIndexer {
+ private textChunker: TextChunker;
+ private vectorDatabase!: VectorDatabase;
+ private semanticEngine!: SemanticSimilarityEngine | SemanticSimilarityEngineProxy;
+ private isInitialized = false;
+ private isInitializing = false;
+ private initPromise: Promise<void> | null = null;
+ private indexedPages = new Set<string>();
+ private readonly options: Required<IndexingOptions>;
+
+ constructor(options?: IndexingOptions) {
```
-This interface is important because it defines how MCP Chrome Tutorial: Control Your Real Chrome Browser Through MCP implements the patterns covered in this chapter.
+This class is important because it defines how MCP Chrome Tutorial: Control Your Real Chrome Browser Through MCP implements the patterns covered in this chapter.
-### `packages/shared/src/agent-types.ts`
+### `app/chrome-extension/utils/content-indexer.ts`
-The `AgentConnectedEvent` interface in [`packages/shared/src/agent-types.ts`](https://github.com/hangwin/mcp-chrome/blob/HEAD/packages/shared/src/agent-types.ts) handles a key part of this chapter's functionality:
+The `getGlobalContentIndexer` function in [`app/chrome-extension/utils/content-indexer.ts`](https://github.com/hangwin/mcp-chrome/blob/HEAD/app/chrome-extension/utils/content-indexer.ts) handles a key part of this chapter's functionality:
```ts
+ * Get global ContentIndexer instance
+ */
+export function getGlobalContentIndexer(): ContentIndexer {
+ if (!globalContentIndexer) {
+ globalContentIndexer = new ContentIndexer();
+ }
+ return globalContentIndexer;
}
-export interface AgentConnectedEvent {
- sessionId: string;
- transport: StreamTransport;
- timestamp: string;
-}
-
-export interface AgentHeartbeatEvent {
- timestamp: string;
-}
-
-/** Usage statistics for a request */
-export interface AgentUsageStats {
- sessionId: string;
- requestId?: string;
- inputTokens: number;
- outputTokens: number;
- cacheReadInputTokens?: number;
- cacheCreationInputTokens?: number;
- totalCostUsd: number;
- durationMs: number;
- numTurns: number;
-}
-
-export type RealtimeEvent =
- | { type: 'message'; data: AgentMessage }
- | { type: 'status'; data: AgentStatusEvent }
- | { type: 'error'; error: string; data?: { sessionId?: string; requestId?: string } }
- | { type: 'connected'; data: AgentConnectedEvent }
- | { type: 'heartbeat'; data: AgentHeartbeatEvent }
- | { type: 'usage'; data: AgentUsageStats };
```
-This interface is important because it defines how MCP Chrome Tutorial: Control Your Real Chrome Browser Through MCP implements the patterns covered in this chapter.
+This function is important because it defines how MCP Chrome Tutorial: Control Your Real Chrome Browser Through MCP implements the patterns covered in this chapter.
-### `packages/shared/src/agent-types.ts`
+### `app/chrome-extension/utils/content-indexer.ts`
-The `AgentHeartbeatEvent` interface in [`packages/shared/src/agent-types.ts`](https://github.com/hangwin/mcp-chrome/blob/HEAD/packages/shared/src/agent-types.ts) handles a key part of this chapter's functionality:
+The `IndexingOptions` interface in [`app/chrome-extension/utils/content-indexer.ts`](https://github.com/hangwin/mcp-chrome/blob/HEAD/app/chrome-extension/utils/content-indexer.ts) handles a key part of this chapter's functionality:
```ts
-}
+import { TOOL_MESSAGE_TYPES } from '@/common/message-types';
-export interface AgentHeartbeatEvent {
- timestamp: string;
+export interface IndexingOptions {
+ autoIndex?: boolean;
+ maxChunksPerPage?: number;
+ skipDuplicates?: boolean;
}
-/** Usage statistics for a request */
-export interface AgentUsageStats {
- sessionId: string;
- requestId?: string;
- inputTokens: number;
- outputTokens: number;
- cacheReadInputTokens?: number;
- cacheCreationInputTokens?: number;
- totalCostUsd: number;
- durationMs: number;
- numTurns: number;
-}
-
-export type RealtimeEvent =
- | { type: 'message'; data: AgentMessage }
- | { type: 'status'; data: AgentStatusEvent }
- | { type: 'error'; error: string; data?: { sessionId?: string; requestId?: string } }
- | { type: 'connected'; data: AgentConnectedEvent }
- | { type: 'heartbeat'; data: AgentHeartbeatEvent }
- | { type: 'usage'; data: AgentUsageStats };
-
-// ============================================================
-// HTTP API Contracts
-// ============================================================
-
-export interface AgentAttachment {
+export class ContentIndexer {
+ private textChunker: TextChunker;
+ private vectorDatabase!: VectorDatabase;
+ private semanticEngine!: SemanticSimilarityEngine | SemanticSimilarityEngineProxy;
+ private isInitialized = false;
+ private isInitializing = false;
+ private initPromise: Promise<void> | null = null;
+ private indexedPages = new Set<string>();
+ private readonly options: Required<IndexingOptions>;
+
+ constructor(options?: IndexingOptions) {
+ this.options = {
+ autoIndex: true,
+ maxChunksPerPage: 50,
+ skipDuplicates: true,
+ ...options,
+ };
+
+ this.textChunker = new TextChunker();
+ }
+
+ /**
+ * Get current selected model configuration
+ */
```
This interface is important because it defines how MCP Chrome Tutorial: Control Your Real Chrome Browser Through MCP implements the patterns covered in this chapter.
-### `packages/shared/src/agent-types.ts`
+### `app/chrome-extension/common/web-editor-types.ts`
-The `AgentUsageStats` interface in [`packages/shared/src/agent-types.ts`](https://github.com/hangwin/mcp-chrome/blob/HEAD/packages/shared/src/agent-types.ts) handles a key part of this chapter's functionality:
+The `changes` class in [`app/chrome-extension/common/web-editor-types.ts`](https://github.com/hangwin/mcp-chrome/blob/HEAD/app/chrome-extension/common/web-editor-types.ts) handles a key part of this chapter's functionality:
```ts
-
-/** Usage statistics for a request */
-export interface AgentUsageStats {
- sessionId: string;
- requestId?: string;
- inputTokens: number;
- outputTokens: number;
- cacheReadInputTokens?: number;
- cacheCreationInputTokens?: number;
- totalCostUsd: number;
- durationMs: number;
- numTurns: number;
+ *
+ * Uses multiple strategies to locate elements, supporting:
+ * - HMR/DOM changes recovery
+ * - Cross-session persistence
+ * - Framework-agnostic identification
+ */
+export interface ElementLocator {
+ /** CSS selector candidates (ordered by specificity) */
+ selectors: string[];
+ /** Structural fingerprint for similarity matching */
+ fingerprint: string;
+ /** Framework debug information (React/Vue) */
+ debugSource?: DebugSource;
+ /** DOM tree path (child indices from root) */
+ path: number[];
+ /** iframe selector chain (from top to target frame) - Phase 4 */
+ frameChain?: string[];
+ /** Shadow DOM host selector chain - Phase 2 */
+ shadowHostChain?: string[];
}
-export type RealtimeEvent =
- | { type: 'message'; data: AgentMessage }
- | { type: 'status'; data: AgentStatusEvent }
- | { type: 'error'; error: string; data?: { sessionId?: string; requestId?: string } }
- | { type: 'connected'; data: AgentConnectedEvent }
- | { type: 'heartbeat'; data: AgentHeartbeatEvent }
- | { type: 'usage'; data: AgentUsageStats };
-
-// ============================================================
-// HTTP API Contracts
-// ============================================================
-
-export interface AgentAttachment {
- type: 'file' | 'image';
- name: string;
- mimeType: string;
- dataBase64: string;
-}
+// =============================================================================
+// Transaction System (Phase 1 - Basic Structure, Low Priority)
+// =============================================================================
+
+/** Transaction operation types */
+export type TransactionType = 'style' | 'text' | 'class' | 'move' | 'structure';
+
+/**
+ * Transaction snapshot for undo/redo
+ * Captures element state before/after changes
+ */
```
-This interface is important because it defines how MCP Chrome Tutorial: Control Your Real Chrome Browser Through MCP implements the patterns covered in this chapter.
+This class is important because it defines how MCP Chrome Tutorial: Control Your Real Chrome Browser Through MCP implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[AgentStatusEvent]
- B[AgentConnectedEvent]
- C[AgentHeartbeatEvent]
- D[AgentUsageStats]
- E[AgentAttachment]
+ A[to]
+ B[getGlobalContentIndexer]
+ C[IndexingOptions]
+ D[changes]
+ E[WebEditorState]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-chrome-tutorial/04-semantic-search-and-vector-processing.md b/tutorials/mcp-chrome-tutorial/04-semantic-search-and-vector-processing.md
index 56196ac3..9249d400 100644
--- a/tutorials/mcp-chrome-tutorial/04-semantic-search-and-vector-processing.md
+++ b/tutorials/mcp-chrome-tutorial/04-semantic-search-and-vector-processing.md
@@ -48,170 +48,168 @@ You now have a functional mental model for how semantic tab search works and whe
Next: [Chapter 5: Transport Modes and Client Configuration](05-transport-modes-and-client-configuration.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `packages/shared/src/agent-types.ts`
+### `app/chrome-extension/common/web-editor-types.ts`
-The `UpdateAgentSessionInput` interface in [`packages/shared/src/agent-types.ts`](https://github.com/hangwin/mcp-chrome/blob/HEAD/packages/shared/src/agent-types.ts) handles a key part of this chapter's functionality:
+The `DebugSource` interface in [`app/chrome-extension/common/web-editor-types.ts`](https://github.com/hangwin/mcp-chrome/blob/HEAD/app/chrome-extension/common/web-editor-types.ts) handles a key part of this chapter's functionality:
```ts
- * Options for updating a session.
+ * Extracted from React Fiber or Vue component instance
*/
-export interface UpdateAgentSessionInput {
- name?: string | null;
- model?: string | null;
- permissionMode?: string | null;
- allowDangerouslySkipPermissions?: boolean | null;
- systemPromptConfig?: AgentSystemPromptConfig | null;
- optionsConfig?: AgentSessionOptionsConfig | null;
-}
-
-// ============================================================
-// Stored Message (for persistence)
-// ============================================================
-
-export interface AgentStoredMessage {
- id: string;
- projectId: string;
- sessionId: string;
- conversationId?: string | null;
- role: AgentRole;
- content: string;
- messageType: AgentMessage['messageType'];
- metadata?: Record<string, unknown>;
- cliSource?: string | null;
- createdAt?: string;
- requestId?: string;
+export interface DebugSource {
+ /** Source file path */
+ file: string;
+ /** Line number (1-based) */
+ line?: number;
+ /** Column number (1-based) */
+ column?: number;
+ /** Component name (if available) */
+ componentName?: string;
}
-// ============================================================
-// Codex Engine Configuration
-// ============================================================
+/**
+ * Element Locator - Primary key for element identification
+ *
+ * Uses multiple strategies to locate elements, supporting:
+ * - HMR/DOM changes recovery
+ * - Cross-session persistence
+ * - Framework-agnostic identification
+ */
+export interface ElementLocator {
+ /** CSS selector candidates (ordered by specificity) */
+ selectors: string[];
+ /** Structural fingerprint for similarity matching */
+ fingerprint: string;
+ /** Framework debug information (React/Vue) */
+ debugSource?: DebugSource;
+ /** DOM tree path (child indices from root) */
+ path: number[];
+ /** iframe selector chain (from top to target frame) - Phase 4 */
+ frameChain?: string[];
```
This interface is important because it defines how MCP Chrome Tutorial: Control Your Real Chrome Browser Through MCP implements the patterns covered in this chapter.
-### `packages/shared/src/agent-types.ts`
+### `app/chrome-extension/common/web-editor-types.ts`
-The `AgentStoredMessage` interface in [`packages/shared/src/agent-types.ts`](https://github.com/hangwin/mcp-chrome/blob/HEAD/packages/shared/src/agent-types.ts) handles a key part of this chapter's functionality:
+The `ElementLocator` interface in [`app/chrome-extension/common/web-editor-types.ts`](https://github.com/hangwin/mcp-chrome/blob/HEAD/app/chrome-extension/common/web-editor-types.ts) handles a key part of this chapter's functionality:
```ts
-// ============================================================
-
-export interface AgentStoredMessage {
- id: string;
- projectId: string;
- sessionId: string;
- conversationId?: string | null;
- role: AgentRole;
- content: string;
- messageType: AgentMessage['messageType'];
- metadata?: Record<string, unknown>;
- cliSource?: string | null;
- createdAt?: string;
- requestId?: string;
+ * - Framework-agnostic identification
+ */
+export interface ElementLocator {
+ /** CSS selector candidates (ordered by specificity) */
+ selectors: string[];
+ /** Structural fingerprint for similarity matching */
+ fingerprint: string;
+ /** Framework debug information (React/Vue) */
+ debugSource?: DebugSource;
+ /** DOM tree path (child indices from root) */
+ path: number[];
+ /** iframe selector chain (from top to target frame) - Phase 4 */
+ frameChain?: string[];
+ /** Shadow DOM host selector chain - Phase 2 */
+ shadowHostChain?: string[];
}
-// ============================================================
-// Codex Engine Configuration
-// ============================================================
+// =============================================================================
+// Transaction System (Phase 1 - Basic Structure, Low Priority)
+// =============================================================================
-/**
- * Sandbox mode for Codex CLI execution.
- */
-export type CodexSandboxMode = 'read-only' | 'workspace-write' | 'danger-full-access';
+/** Transaction operation types */
+export type TransactionType = 'style' | 'text' | 'class' | 'move' | 'structure';
/**
- * Reasoning effort for Codex models.
- * - low/medium/high: supported by all models
- * - xhigh: only supported by gpt-5.2 and gpt-5.1-codex-max
+ * Transaction snapshot for undo/redo
+ * Captures element state before/after changes
*/
-export type CodexReasoningEffort = 'low' | 'medium' | 'high' | 'xhigh';
-
+export interface TransactionSnapshot {
+ /** Element locator for re-identification */
+ locator: ElementLocator;
+ /** innerHTML snapshot (for structure changes) */
```
This interface is important because it defines how MCP Chrome Tutorial: Control Your Real Chrome Browser Through MCP implements the patterns covered in this chapter.
-### `packages/shared/src/agent-types.ts`
+### `app/chrome-extension/common/web-editor-types.ts`
-The `CodexEngineConfig` interface in [`packages/shared/src/agent-types.ts`](https://github.com/hangwin/mcp-chrome/blob/HEAD/packages/shared/src/agent-types.ts) handles a key part of this chapter's functionality:
+The `TransactionSnapshot` interface in [`app/chrome-extension/common/web-editor-types.ts`](https://github.com/hangwin/mcp-chrome/blob/HEAD/app/chrome-extension/common/web-editor-types.ts) handles a key part of this chapter's functionality:
```ts
- * Only applicable when using CodexEngine.
- */
- codexConfig?: Partial<CodexEngineConfig>;
+ * Captures element state before/after changes
+ */
+export interface TransactionSnapshot {
+ /** Element locator for re-identification */
+ locator: ElementLocator;
+ /** innerHTML snapshot (for structure changes) */
+ html?: string;
+ /** Changed style properties */
+ styles?: Record<string, string>;
+ /** Class list tokens (from `class` attribute) */
+ classes?: string[];
+ /** Text content */
+ text?: string;
}
/**
- * Cached management information from Claude SDK.
+ * Move position data
+ * Captures a concrete insertion point under a parent element
*/
-export interface AgentManagementInfo {
- tools?: string[];
- agents?: string[];
- plugins?: Array<{ name: string; path?: string }>;
- skills?: string[];
- mcpServers?: Array<{ name: string; status: string }>;
- slashCommands?: string[];
- model?: string;
- permissionMode?: string;
- cwd?: string;
- outputStyle?: string;
- betas?: string[];
- claudeCodeVersion?: string;
- apiKeySource?: string;
- lastUpdated?: string;
+export interface MoveOperationData {
+ /** Target parent element locator */
+ parentLocator: ElementLocator;
+ /** Insert position index (among element children) */
+ insertIndex: number;
+ /** Anchor sibling element locator (for stable positioning) */
+ anchorLocator?: ElementLocator;
+ /** Position relative to anchor */
+ anchorPosition: 'before' | 'after';
}
/**
- * Agent session - represents an independent conversation within a project.
- */
-export interface AgentSession {
- id: string;
- projectId: string;
- engineName: AgentCliPreference;
+ * Move transaction data
```
This interface is important because it defines how MCP Chrome Tutorial: Control Your Real Chrome Browser Through MCP implements the patterns covered in this chapter.
-### `packages/shared/src/agent-types.ts`
+### `app/chrome-extension/common/web-editor-types.ts`
-The `AttachmentMetadata` interface in [`packages/shared/src/agent-types.ts`](https://github.com/hangwin/mcp-chrome/blob/HEAD/packages/shared/src/agent-types.ts) handles a key part of this chapter's functionality:
+The `MoveOperationData` interface in [`app/chrome-extension/common/web-editor-types.ts`](https://github.com/hangwin/mcp-chrome/blob/HEAD/app/chrome-extension/common/web-editor-types.ts) handles a key part of this chapter's functionality:
```ts
- * Metadata for a persisted attachment file.
+ * Captures a concrete insertion point under a parent element
+ */
+export interface MoveOperationData {
+ /** Target parent element locator */
+ parentLocator: ElementLocator;
+ /** Insert position index (among element children) */
+ insertIndex: number;
+ /** Anchor sibling element locator (for stable positioning) */
+ anchorLocator?: ElementLocator;
+ /** Position relative to anchor */
+ anchorPosition: 'before' | 'after';
+}
+
+/**
+ * Move transaction data
+ * Captures both source and destination for undo/redo
*/
-export interface AttachmentMetadata {
- /** Schema version for forward compatibility */
- version: number;
- /** Kind of attachment (e.g., 'image', 'file') */
- kind: string;
- /** Project ID this attachment belongs to */
- projectId: string;
- /** Message ID this attachment is associated with */
- messageId: string;
- /** Index of this attachment in the message */
- index: number;
- /** Persisted filename under project dir */
- filename: string;
- /** URL path to access this attachment */
- urlPath: string;
- /** MIME type of the attachment */
- mimeType: string;
- /** File size in bytes */
- sizeBytes: number;
- /** Original filename from upload */
- originalName: string;
- /** Timestamp when attachment was created */
- createdAt: string;
+export interface MoveTransactionData {
+ /** Original location before move */
+ from: MoveOperationData;
+ /** Target location after move */
+ to: MoveOperationData;
}
/**
- * Statistics for attachments in a single project.
+ * Structure operation data
+ * For wrap/unwrap/delete/duplicate operations (Phase 5.5)
*/
-export interface AttachmentProjectStats {
- projectId: string;
+export interface StructureOperationData {
+ /** Structure action type */
+ action: 'wrap' | 'unwrap' | 'delete' | 'duplicate';
+ /** Wrapper tag for wrap/unwrap actions */
```
This interface is important because it defines how MCP Chrome Tutorial: Control Your Real Chrome Browser Through MCP implements the patterns covered in this chapter.
@@ -221,11 +219,11 @@ This interface is important because it defines how MCP Chrome Tutorial: Control
```mermaid
flowchart TD
- A[UpdateAgentSessionInput]
- B[AgentStoredMessage]
- C[CodexEngineConfig]
- D[AttachmentMetadata]
- E[AttachmentProjectStats]
+ A[DebugSource]
+ B[ElementLocator]
+ C[TransactionSnapshot]
+ D[MoveOperationData]
+ E[MoveTransactionData]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-chrome-tutorial/05-transport-modes-and-client-configuration.md b/tutorials/mcp-chrome-tutorial/05-transport-modes-and-client-configuration.md
index 7e1e442e..243bacce 100644
--- a/tutorials/mcp-chrome-tutorial/05-transport-modes-and-client-configuration.md
+++ b/tutorials/mcp-chrome-tutorial/05-transport-modes-and-client-configuration.md
@@ -50,147 +50,168 @@ You now know how to align MCP Chrome transport configuration with client constra
Next: [Chapter 6: Visual Editor and Prompt Workflows](06-visual-editor-and-prompt-workflows.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `app/chrome-extension/utils/content-indexer.ts`
+### `app/chrome-extension/common/web-editor-types.ts`
-The `ContentIndexer` class in [`app/chrome-extension/utils/content-indexer.ts`](https://github.com/hangwin/mcp-chrome/blob/HEAD/app/chrome-extension/utils/content-indexer.ts) handles a key part of this chapter's functionality:
+The `WebEditorRevertElementResponse` interface in [`app/chrome-extension/common/web-editor-types.ts`](https://github.com/hangwin/mcp-chrome/blob/HEAD/app/chrome-extension/common/web-editor-types.ts) handles a key part of this chapter's functionality:
```ts
+ * Revert element response from content script.
+ */
+export interface WebEditorRevertElementResponse {
+ /** Whether the revert was successful */
+ success: boolean;
+ /** What was reverted (for UI feedback) */
+ reverted?: {
+ style?: boolean;
+ text?: boolean;
+ class?: boolean;
+ };
+ /** Error message if revert failed */
+ error?: string;
}
-export class ContentIndexer {
- private textChunker: TextChunker;
- private vectorDatabase!: VectorDatabase;
- private semanticEngine!: SemanticSimilarityEngine | SemanticSimilarityEngineProxy;
- private isInitialized = false;
- private isInitializing = false;
- private initPromise: Promise<void> | null = null;
- private indexedPages = new Set<string>();
- private readonly options: Required<IndexingOptions>;
-
- constructor(options?: IndexingOptions) {
- this.options = {
- autoIndex: true,
- maxChunksPerPage: 50,
- skipDuplicates: true,
- ...options,
- };
-
- this.textChunker = new TextChunker();
- }
+// =============================================================================
+// Selection Sync Types
+// =============================================================================
- /**
- * Get current selected model configuration
- */
- private async getCurrentModelConfig() {
- try {
- const result = await chrome.storage.local.get(['selectedModel', 'selectedVersion']);
- const selectedModel = (result.selectedModel as ModelPreset) || 'multilingual-e5-small';
- const selectedVersion =
- (result.selectedVersion as 'full' | 'quantized' | 'compressed') || 'quantized';
+/**
+ * Summary of currently selected element.
+ * Lightweight payload for selection sync (no transaction data).
+ */
+export interface SelectedElementSummary {
+ /** Stable element identifier */
+ elementKey: WebEditorElementKey;
+ /** Locator for element identification and highlighting */
+ locator: ElementLocator;
+ /** Short display label (e.g., "div#app") */
+ label: string;
+ /** Full label with context (e.g., "body > div#app") */
+ fullLabel: string;
```
-This class is important because it defines how MCP Chrome Tutorial: Control Your Real Chrome Browser Through MCP implements the patterns covered in this chapter.
+This interface is important because it defines how MCP Chrome Tutorial: Control Your Real Chrome Browser Through MCP implements the patterns covered in this chapter.
-### `app/chrome-extension/utils/content-indexer.ts`
+### `app/chrome-extension/common/web-editor-types.ts`
-The `to` class in [`app/chrome-extension/utils/content-indexer.ts`](https://github.com/hangwin/mcp-chrome/blob/HEAD/app/chrome-extension/utils/content-indexer.ts) handles a key part of this chapter's functionality:
+The `SelectedElementSummary` interface in [`app/chrome-extension/common/web-editor-types.ts`](https://github.com/hangwin/mcp-chrome/blob/HEAD/app/chrome-extension/common/web-editor-types.ts) handles a key part of this chapter's functionality:
```ts
-/**
- * Content index manager
- * Responsible for automatically extracting, chunking and indexing tab content
+ * Lightweight payload for selection sync (no transaction data).
*/
+export interface SelectedElementSummary {
+ /** Stable element identifier */
+ elementKey: WebEditorElementKey;
+ /** Locator for element identification and highlighting */
+ locator: ElementLocator;
+ /** Short display label (e.g., "div#app") */
+ label: string;
+ /** Full label with context (e.g., "body > div#app") */
+ fullLabel: string;
+ /** Tag name of the element */
+ tagName: string;
+ /** Timestamp for deduplication */
+ updatedAt: number;
+}
-import { TextChunker } from './text-chunker';
-import { VectorDatabase, getGlobalVectorDatabase } from './vector-database';
-import {
- SemanticSimilarityEngine,
- SemanticSimilarityEngineProxy,
- PREDEFINED_MODELS,
- type ModelPreset,
-} from './semantic-similarity-engine';
-import { TOOL_MESSAGE_TYPES } from '@/common/message-types';
-
-export interface IndexingOptions {
- autoIndex?: boolean;
- maxChunksPerPage?: number;
- skipDuplicates?: boolean;
+/**
+ * Selection change broadcast payload.
+ * Sent immediately when user selects/deselects elements (no debounce).
+ */
+export interface WebEditorSelectionChangedPayload {
+ /** Source tab ID (filled by background from sender.tab.id) */
+ tabId: number;
+ /** Currently selected element, or null if deselected */
+ selected: SelectedElementSummary | null;
+ /** Page URL for context */
+ pageUrl?: string;
}
-export class ContentIndexer {
- private textChunker: TextChunker;
- private vectorDatabase!: VectorDatabase;
- private semanticEngine!: SemanticSimilarityEngine | SemanticSimilarityEngineProxy;
- private isInitialized = false;
- private isInitializing = false;
- private initPromise: Promise<void> | null = null;
- private indexedPages = new Set<string>();
- private readonly options: Required<IndexingOptions>;
-
- constructor(options?: IndexingOptions) {
+// =============================================================================
+// Execution Cancel Types
```
-This class is important because it defines how MCP Chrome Tutorial: Control Your Real Chrome Browser Through MCP implements the patterns covered in this chapter.
+This interface is important because it defines how MCP Chrome Tutorial: Control Your Real Chrome Browser Through MCP implements the patterns covered in this chapter.
-### `app/chrome-extension/utils/content-indexer.ts`
+### `app/chrome-extension/common/web-editor-types.ts`
-The `getGlobalContentIndexer` function in [`app/chrome-extension/utils/content-indexer.ts`](https://github.com/hangwin/mcp-chrome/blob/HEAD/app/chrome-extension/utils/content-indexer.ts) handles a key part of this chapter's functionality:
+The `WebEditorSelectionChangedPayload` interface in [`app/chrome-extension/common/web-editor-types.ts`](https://github.com/hangwin/mcp-chrome/blob/HEAD/app/chrome-extension/common/web-editor-types.ts) handles a key part of this chapter's functionality:
```ts
- * Get global ContentIndexer instance
+ * Sent immediately when user selects/deselects elements (no debounce).
*/
-export function getGlobalContentIndexer(): ContentIndexer {
- if (!globalContentIndexer) {
- globalContentIndexer = new ContentIndexer();
- }
- return globalContentIndexer;
+export interface WebEditorSelectionChangedPayload {
+ /** Source tab ID (filled by background from sender.tab.id) */
+ tabId: number;
+ /** Currently selected element, or null if deselected */
+ selected: SelectedElementSummary | null;
+ /** Page URL for context */
+ pageUrl?: string;
}
+// =============================================================================
+// Execution Cancel Types
+// =============================================================================
+
+/**
+ * Payload for canceling an ongoing Apply execution.
+ * Sent from web-editor toolbar or sidepanel to background.
+ */
+export interface WebEditorCancelExecutionPayload {
+ /** Session ID of the execution to cancel */
+ sessionId: string;
+ /** Request ID of the execution to cancel */
+ requestId: string;
+}
+
+/**
+ * Response from cancel execution request.
+ */
+export interface WebEditorCancelExecutionResponse {
+ /** Whether the cancel request was successful */
+ success: boolean;
```
-This function is important because it defines how MCP Chrome Tutorial: Control Your Real Chrome Browser Through MCP implements the patterns covered in this chapter.
+This interface is important because it defines how MCP Chrome Tutorial: Control Your Real Chrome Browser Through MCP implements the patterns covered in this chapter.
-### `app/chrome-extension/utils/content-indexer.ts`
+### `app/chrome-extension/common/web-editor-types.ts`
-The `IndexingOptions` interface in [`app/chrome-extension/utils/content-indexer.ts`](https://github.com/hangwin/mcp-chrome/blob/HEAD/app/chrome-extension/utils/content-indexer.ts) handles a key part of this chapter's functionality:
+The `WebEditorCancelExecutionPayload` interface in [`app/chrome-extension/common/web-editor-types.ts`](https://github.com/hangwin/mcp-chrome/blob/HEAD/app/chrome-extension/common/web-editor-types.ts) handles a key part of this chapter's functionality:
```ts
-import { TOOL_MESSAGE_TYPES } from '@/common/message-types';
+ * Sent from web-editor toolbar or sidepanel to background.
+ */
+export interface WebEditorCancelExecutionPayload {
+ /** Session ID of the execution to cancel */
+ sessionId: string;
+ /** Request ID of the execution to cancel */
+ requestId: string;
+}
-export interface IndexingOptions {
- autoIndex?: boolean;
- maxChunksPerPage?: number;
- skipDuplicates?: boolean;
+/**
+ * Response from cancel execution request.
+ */
+export interface WebEditorCancelExecutionResponse {
+ /** Whether the cancel request was successful */
+ success: boolean;
+ /** Error message if cancellation failed */
+ error?: string;
}
-export class ContentIndexer {
- private textChunker: TextChunker;
- private vectorDatabase!: VectorDatabase;
- private semanticEngine!: SemanticSimilarityEngine | SemanticSimilarityEngineProxy;
- private isInitialized = false;
- private isInitializing = false;
- private initPromise: Promise<void> | null = null;
- private indexedPages = new Set<string>();
- private readonly options: Required<IndexingOptions>;
-
- constructor(options?: IndexingOptions) {
- this.options = {
- autoIndex: true,
- maxChunksPerPage: 50,
- skipDuplicates: true,
- ...options,
- };
-
- this.textChunker = new TextChunker();
- }
+// =============================================================================
+// Public API Interface
+// =============================================================================
- /**
- * Get current selected model configuration
- */
+/**
+ * Web Editor V2 Public API
+ * Exposed on window.__MCP_WEB_EDITOR_V2__
+ */
+export interface WebEditorV2Api {
+ /** Start the editor */
+ start: () => void;
+ /** Stop the editor */
+ stop: () => void;
```
This interface is important because it defines how MCP Chrome Tutorial: Control Your Real Chrome Browser Through MCP implements the patterns covered in this chapter.
@@ -200,11 +221,11 @@ This interface is important because it defines how MCP Chrome Tutorial: Control
```mermaid
flowchart TD
- A[ContentIndexer]
- B[to]
- C[getGlobalContentIndexer]
- D[IndexingOptions]
- E[changes]
+ A[WebEditorRevertElementResponse]
+ B[SelectedElementSummary]
+ C[WebEditorSelectionChangedPayload]
+ D[WebEditorCancelExecutionPayload]
+ E[WebEditorCancelExecutionResponse]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-chrome-tutorial/06-visual-editor-and-prompt-workflows.md b/tutorials/mcp-chrome-tutorial/06-visual-editor-and-prompt-workflows.md
index 1491be75..d59413eb 100644
--- a/tutorials/mcp-chrome-tutorial/06-visual-editor-and-prompt-workflows.md
+++ b/tutorials/mcp-chrome-tutorial/06-visual-editor-and-prompt-workflows.md
@@ -37,184 +37,182 @@ You now have a repeatable approach for combining visual planning and MCP tool ex
Next: [Chapter 7: Troubleshooting, Permissions, and Security](07-troubleshooting-permissions-and-security.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `app/chrome-extension/common/web-editor-types.ts`
-
-The `WebEditorV2StopResponse` interface in [`app/chrome-extension/common/web-editor-types.ts`](https://github.com/hangwin/mcp-chrome/blob/HEAD/app/chrome-extension/common/web-editor-types.ts) handles a key part of this chapter's functionality:
-
-```ts
-
-/** Stop response (V2) */
-export interface WebEditorV2StopResponse {
- active: boolean;
-}
-
-/** Union types for V2 type-safe message handling */
-export type WebEditorV2Request =
- | WebEditorV2PingRequest
- | WebEditorV2ToggleRequest
- | WebEditorV2StartRequest
- | WebEditorV2StopRequest;
-
-export type WebEditorV2Response =
- | WebEditorV2PingResponse
- | WebEditorV2ToggleResponse
- | WebEditorV2StartResponse
- | WebEditorV2StopResponse;
-
-// =============================================================================
-// Element Locator (Phase 1 - Basic Structure)
-// =============================================================================
-
-/**
- * Framework debug source information
- * Extracted from React Fiber or Vue component instance
- */
-export interface DebugSource {
- /** Source file path */
- file: string;
- /** Line number (1-based) */
- line?: number;
+### `app/chrome-extension/inject-scripts/interactive-elements-helper.js`
+
+The `createElementInfo` function in [`app/chrome-extension/inject-scripts/interactive-elements-helper.js`](https://github.com/hangwin/mcp-chrome/blob/HEAD/app/chrome-extension/inject-scripts/interactive-elements-helper.js) handles a key part of this chapter's functionality:
+
+```js
+ * Modified to handle the new 'text' type from the final fallback.
+ */
+ function createElementInfo(el, type, includeCoordinates, isInteractiveOverride = null) {
+ const isActuallyInteractive = isElementInteractive(el);
+ const info = {
+ type,
+ selector: generateSelector(el),
+ text: getAccessibleName(el) || el.textContent?.trim(),
+ isInteractive: isInteractiveOverride !== null ? isInteractiveOverride : isActuallyInteractive,
+ disabled: el.hasAttribute('disabled') || el.getAttribute('aria-disabled') === 'true',
+ };
+ if (includeCoordinates) {
+ const rect = el.getBoundingClientRect();
+ info.coordinates = {
+ x: rect.left + rect.width / 2,
+ y: rect.top + rect.height / 2,
+ rect: {
+ x: rect.x,
+ y: rect.y,
+ width: rect.width,
+ height: rect.height,
+ top: rect.top,
+ right: rect.right,
+ bottom: rect.bottom,
+ left: rect.left,
+ },
+ };
+ }
+ return info;
+ }
+
+ /**
```
-This interface is important because it defines how MCP Chrome Tutorial: Control Your Real Chrome Browser Through MCP implements the patterns covered in this chapter.
-
-### `app/chrome-extension/common/web-editor-types.ts`
-
-The `DebugSource` interface in [`app/chrome-extension/common/web-editor-types.ts`](https://github.com/hangwin/mcp-chrome/blob/HEAD/app/chrome-extension/common/web-editor-types.ts) handles a key part of this chapter's functionality:
-
-```ts
- * Extracted from React Fiber or Vue component instance
- */
-export interface DebugSource {
- /** Source file path */
- file: string;
- /** Line number (1-based) */
- line?: number;
- /** Column number (1-based) */
- column?: number;
- /** Component name (if available) */
- componentName?: string;
-}
+This function is important because it defines how MCP Chrome Tutorial: Control Your Real Chrome Browser Through MCP implements the patterns covered in this chapter.
+
+### `app/chrome-extension/inject-scripts/interactive-elements-helper.js`
+
+The `findInteractiveElements` function in [`app/chrome-extension/inject-scripts/interactive-elements-helper.js`](https://github.com/hangwin/mcp-chrome/blob/HEAD/app/chrome-extension/inject-scripts/interactive-elements-helper.js) handles a key part of this chapter's functionality:
+
+```js
+ * This is our high-performance Layer 1 search function.
+ */
+ function findInteractiveElements(options = {}) {
+ const { textQuery, includeCoordinates = true, types = Object.keys(ELEMENT_CONFIG) } = options;
+
+ const selectorsToFind = types
+ .map((type) => ELEMENT_CONFIG[type])
+ .filter(Boolean)
+ .join(', ');
+ if (!selectorsToFind) return [];
+
+ const targetElements = querySelectorAllDeep(selectorsToFind);
+ const uniqueElements = new Set(targetElements);
+ const results = [];
+
+ for (const el of uniqueElements) {
+ if (!isElementVisible(el) || !isElementInteractive(el)) continue;
+
+ const accessibleName = getAccessibleName(el);
+ if (textQuery && !fuzzyMatch(accessibleName, textQuery)) continue;
+
+ let elementType = 'unknown';
+ for (const [type, typeSelector] of Object.entries(ELEMENT_CONFIG)) {
+ if (el.matches(typeSelector)) {
+ elementType = type;
+ break;
+ }
+ }
+ results.push(createElementInfo(el, elementType, includeCoordinates));
+ }
+ return results;
+ }
+```
-/**
- * Element Locator - Primary key for element identification
- *
- * Uses multiple strategies to locate elements, supporting:
- * - HMR/DOM changes recovery
- * - Cross-session persistence
- * - Framework-agnostic identification
- */
-export interface ElementLocator {
- /** CSS selector candidates (ordered by specificity) */
- selectors: string[];
- /** Structural fingerprint for similarity matching */
- fingerprint: string;
- /** Framework debug information (React/Vue) */
- debugSource?: DebugSource;
- /** DOM tree path (child indices from root) */
- path: number[];
- /** iframe selector chain (from top to target frame) - Phase 4 */
- frameChain?: string[];
+This function is important because it defines how MCP Chrome Tutorial: Control Your Real Chrome Browser Through MCP implements the patterns covered in this chapter.
+
+### `app/chrome-extension/inject-scripts/interactive-elements-helper.js`
+
+The `findElementsByTextWithFallback` function in [`app/chrome-extension/inject-scripts/interactive-elements-helper.js`](https://github.com/hangwin/mcp-chrome/blob/HEAD/app/chrome-extension/inject-scripts/interactive-elements-helper.js) handles a key part of this chapter's functionality:
+
+```js
+ * @returns {ElementInfo[]}
+ */
+ function findElementsByTextWithFallback(options = {}) {
+ const { textQuery, includeCoordinates = true } = options;
+
+ if (!textQuery) {
+ return findInteractiveElements({ ...options, types: Object.keys(ELEMENT_CONFIG) });
+ }
+
+ // --- Layer 1: High-reliability search for interactive elements matching text ---
+ let results = findInteractiveElements({ ...options, types: Object.keys(ELEMENT_CONFIG) });
+ if (results.length > 0) {
+ return results;
+ }
+
+ // --- Layer 2: Find text, then find its interactive ancestor ---
+ const lowerCaseText = textQuery.toLowerCase();
+ const xPath = `//text()[contains(translate(., 'ABCDEFGHIJKLMNOPQRSTUVWXYZ', 'abcdefghijklmnopqrstuvwxyz'), '${lowerCaseText}')]`;
+ const textNodes = document.evaluate(
+ xPath,
+ document,
+ null,
+ XPathResult.ORDERED_NODE_SNAPSHOT_TYPE,
+ null,
+ );
+
+ const interactiveElements = new Set();
+ if (textNodes.snapshotLength > 0) {
+ for (let i = 0; i < textNodes.snapshotLength; i++) {
+ const parentElement = textNodes.snapshotItem(i).parentElement;
+ if (parentElement) {
+ const interactiveAncestor = parentElement.closest(ANY_INTERACTIVE_SELECTOR);
```
-This interface is important because it defines how MCP Chrome Tutorial: Control Your Real Chrome Browser Through MCP implements the patterns covered in this chapter.
+This function is important because it defines how MCP Chrome Tutorial: Control Your Real Chrome Browser Through MCP implements the patterns covered in this chapter.
-### `app/chrome-extension/common/web-editor-types.ts`
+### `app/chrome-extension/utils/simd-math-engine.ts`
-The `ElementLocator` interface in [`app/chrome-extension/common/web-editor-types.ts`](https://github.com/hangwin/mcp-chrome/blob/HEAD/app/chrome-extension/common/web-editor-types.ts) handles a key part of this chapter's functionality:
+The `SIMDMathEngine` class in [`app/chrome-extension/utils/simd-math-engine.ts`](https://github.com/hangwin/mcp-chrome/blob/HEAD/app/chrome-extension/utils/simd-math-engine.ts) handles a key part of this chapter's functionality:
```ts
- * - Framework-agnostic identification
- */
-export interface ElementLocator {
- /** CSS selector candidates (ordered by specificity) */
- selectors: string[];
- /** Structural fingerprint for similarity matching */
- fingerprint: string;
- /** Framework debug information (React/Vue) */
- debugSource?: DebugSource;
- /** DOM tree path (child indices from root) */
- path: number[];
- /** iframe selector chain (from top to target frame) - Phase 4 */
- frameChain?: string[];
- /** Shadow DOM host selector chain - Phase 2 */
- shadowHostChain?: string[];
}
-// =============================================================================
-// Transaction System (Phase 1 - Basic Structure, Low Priority)
-// =============================================================================
-
-/** Transaction operation types */
-export type TransactionType = 'style' | 'text' | 'class' | 'move' | 'structure';
-
-/**
- * Transaction snapshot for undo/redo
- * Captures element state before/after changes
- */
-export interface TransactionSnapshot {
- /** Element locator for re-identification */
- locator: ElementLocator;
- /** innerHTML snapshot (for structure changes) */
-```
+export class SIMDMathEngine {
+ private wasmModule: WasmModule | null = null;
+ private simdMath: SIMDMathWasm | null = null;
+ private isInitialized = false;
+ private isInitializing = false;
+ private initPromise: Promise<void> | null = null;
-This interface is important because it defines how MCP Chrome Tutorial: Control Your Real Chrome Browser Through MCP implements the patterns covered in this chapter.
+ private alignedBufferPool: Map<number, Float32Array[]> = new Map();
+ private maxPoolSize = 5;
-### `app/chrome-extension/common/web-editor-types.ts`
+ async initialize(): Promise<void> {
+ if (this.isInitialized) return;
+ if (this.isInitializing && this.initPromise) return this.initPromise;
-The `TransactionSnapshot` interface in [`app/chrome-extension/common/web-editor-types.ts`](https://github.com/hangwin/mcp-chrome/blob/HEAD/app/chrome-extension/common/web-editor-types.ts) handles a key part of this chapter's functionality:
+ this.isInitializing = true;
+ this.initPromise = this._doInitialize().finally(() => {
+ this.isInitializing = false;
+ });
-```ts
- * Captures element state before/after changes
- */
-export interface TransactionSnapshot {
- /** Element locator for re-identification */
- locator: ElementLocator;
- /** innerHTML snapshot (for structure changes) */
- html?: string;
- /** Changed style properties */
- styles?: Record<string, string>;
- /** Class list tokens (from `class` attribute) */
- classes?: string[];
- /** Text content */
- text?: string;
-}
+ return this.initPromise;
+ }
-/**
- * Move position data
- * Captures a concrete insertion point under a parent element
- */
-export interface MoveOperationData {
- /** Target parent element locator */
- parentLocator: ElementLocator;
- /** Insert position index (among element children) */
- insertIndex: number;
- /** Anchor sibling element locator (for stable positioning) */
- anchorLocator?: ElementLocator;
- /** Position relative to anchor */
- anchorPosition: 'before' | 'after';
-}
+ private async _doInitialize(): Promise<void> {
+ try {
+ console.log('SIMDMathEngine: Initializing WebAssembly module...');
+
+ const wasmUrl = chrome.runtime.getURL('workers/simd_math.js');
+ const wasmModule = await import(wasmUrl);
-/**
- * Move transaction data
+ const wasmInstance = await wasmModule.default();
```
-This interface is important because it defines how MCP Chrome Tutorial: Control Your Real Chrome Browser Through MCP implements the patterns covered in this chapter.
+This class is important because it defines how MCP Chrome Tutorial: Control Your Real Chrome Browser Through MCP implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[WebEditorV2StopResponse]
- B[DebugSource]
- C[ElementLocator]
- D[TransactionSnapshot]
- E[MoveOperationData]
+ A[createElementInfo]
+ B[findInteractiveElements]
+ C[findElementsByTextWithFallback]
+ D[SIMDMathEngine]
+ E[SIMDMathWasm]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-chrome-tutorial/07-troubleshooting-permissions-and-security.md b/tutorials/mcp-chrome-tutorial/07-troubleshooting-permissions-and-security.md
index 376b1ae2..21a8a82d 100644
--- a/tutorials/mcp-chrome-tutorial/07-troubleshooting-permissions-and-security.md
+++ b/tutorials/mcp-chrome-tutorial/07-troubleshooting-permissions-and-security.md
@@ -46,170 +46,168 @@ You now have a concrete troubleshooting and safety baseline for MCP Chrome opera
Next: [Chapter 8: Contribution, Release, and Runtime Operations](08-contribution-release-and-runtime-operations.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `app/chrome-extension/common/web-editor-types.ts`
+### `packages/shared/src/agent-types.ts`
-The `WebEditorRevertElementPayload` interface in [`app/chrome-extension/common/web-editor-types.ts`](https://github.com/hangwin/mcp-chrome/blob/HEAD/app/chrome-extension/common/web-editor-types.ts) handles a key part of this chapter's functionality:
+The `AgentActResponse` interface in [`packages/shared/src/agent-types.ts`](https://github.com/hangwin/mcp-chrome/blob/HEAD/packages/shared/src/agent-types.ts) handles a key part of this chapter's functionality:
```ts
- * Used for Phase 2 - Selective Undo (reverting individual element changes).
- */
-export interface WebEditorRevertElementPayload {
- /** Target tab ID */
- tabId: number;
- /** Element key to revert */
- elementKey: WebEditorElementKey;
}
-/**
- * Revert element response from content script.
- */
-export interface WebEditorRevertElementResponse {
- /** Whether the revert was successful */
- success: boolean;
- /** What was reverted (for UI feedback) */
- reverted?: {
- style?: boolean;
- text?: boolean;
- class?: boolean;
- };
- /** Error message if revert failed */
- error?: string;
+export interface AgentActResponse {
+ requestId: string;
+ sessionId: string;
+ status: 'accepted';
}
-// =============================================================================
-// Selection Sync Types
-// =============================================================================
-
-/**
- * Summary of currently selected element.
- * Lightweight payload for selection sync (no transaction data).
+// ============================================================
+// Project & Engine Types
+// ============================================================
+
+export interface AgentProject {
+ id: string;
+ name: string;
+ description?: string;
+ /**
+ * Absolute filesystem path for this project workspace.
+ */
+ rootPath: string;
+ preferredCli?: AgentCliPreference;
+ selectedModel?: string;
+ /**
+ * Active Claude session ID (UUID format) for session resumption.
+ * Captured from SDK's system/init message and used for the 'resume' parameter.
+ */
+ activeClaudeSessionId?: string;
+ /**
+ * Whether to use Claude Code Router (CCR) for this project.
+ * When enabled, the engine will auto-detect CCR configuration.
+ */
+ useCcr?: boolean;
```
This interface is important because it defines how MCP Chrome Tutorial: Control Your Real Chrome Browser Through MCP implements the patterns covered in this chapter.
-### `app/chrome-extension/common/web-editor-types.ts`
+### `packages/shared/src/agent-types.ts`
-The `WebEditorRevertElementResponse` interface in [`app/chrome-extension/common/web-editor-types.ts`](https://github.com/hangwin/mcp-chrome/blob/HEAD/app/chrome-extension/common/web-editor-types.ts) handles a key part of this chapter's functionality:
+The `AgentProject` interface in [`packages/shared/src/agent-types.ts`](https://github.com/hangwin/mcp-chrome/blob/HEAD/packages/shared/src/agent-types.ts) handles a key part of this chapter's functionality:
```ts
- * Revert element response from content script.
- */
-export interface WebEditorRevertElementResponse {
- /** Whether the revert was successful */
- success: boolean;
- /** What was reverted (for UI feedback) */
- reverted?: {
- style?: boolean;
- text?: boolean;
- class?: boolean;
- };
- /** Error message if revert failed */
- error?: string;
+// ============================================================
+
+export interface AgentProject {
+ id: string;
+ name: string;
+ description?: string;
+ /**
+ * Absolute filesystem path for this project workspace.
+ */
+ rootPath: string;
+ preferredCli?: AgentCliPreference;
+ selectedModel?: string;
+ /**
+ * Active Claude session ID (UUID format) for session resumption.
+ * Captured from SDK's system/init message and used for the 'resume' parameter.
+ */
+ activeClaudeSessionId?: string;
+ /**
+ * Whether to use Claude Code Router (CCR) for this project.
+ * When enabled, the engine will auto-detect CCR configuration.
+ */
+ useCcr?: boolean;
+ /**
+ * Whether to enable Chrome MCP integration for this project.
+ * Default: true
+ */
+ enableChromeMcp?: boolean;
+ createdAt: string;
+ updatedAt: string;
+ lastActiveAt?: string;
}
-// =============================================================================
-// Selection Sync Types
-// =============================================================================
-
-/**
- * Summary of currently selected element.
- * Lightweight payload for selection sync (no transaction data).
- */
-export interface SelectedElementSummary {
- /** Stable element identifier */
- elementKey: WebEditorElementKey;
- /** Locator for element identification and highlighting */
- locator: ElementLocator;
- /** Short display label (e.g., "div#app") */
- label: string;
- /** Full label with context (e.g., "body > div#app") */
- fullLabel: string;
```
This interface is important because it defines how MCP Chrome Tutorial: Control Your Real Chrome Browser Through MCP implements the patterns covered in this chapter.
-### `app/chrome-extension/common/web-editor-types.ts`
+### `packages/shared/src/agent-types.ts`
-The `SelectedElementSummary` interface in [`app/chrome-extension/common/web-editor-types.ts`](https://github.com/hangwin/mcp-chrome/blob/HEAD/app/chrome-extension/common/web-editor-types.ts) handles a key part of this chapter's functionality:
+The `AgentEngineInfo` interface in [`packages/shared/src/agent-types.ts`](https://github.com/hangwin/mcp-chrome/blob/HEAD/packages/shared/src/agent-types.ts) handles a key part of this chapter's functionality:
```ts
- * Lightweight payload for selection sync (no transaction data).
- */
-export interface SelectedElementSummary {
- /** Stable element identifier */
- elementKey: WebEditorElementKey;
- /** Locator for element identification and highlighting */
- locator: ElementLocator;
- /** Short display label (e.g., "div#app") */
- label: string;
- /** Full label with context (e.g., "body > div#app") */
- fullLabel: string;
- /** Tag name of the element */
- tagName: string;
- /** Timestamp for deduplication */
- updatedAt: number;
}
+export interface AgentEngineInfo {
+ name: string;
+ supportsMcp?: boolean;
+}
+
+// ============================================================
+// Session Types
+// ============================================================
+
/**
- * Selection change broadcast payload.
- * Sent immediately when user selects/deselects elements (no debounce).
+ * System prompt configuration for a session.
*/
-export interface WebEditorSelectionChangedPayload {
- /** Source tab ID (filled by background from sender.tab.id) */
- tabId: number;
- /** Currently selected element, or null if deselected */
- selected: SelectedElementSummary | null;
- /** Page URL for context */
- pageUrl?: string;
-}
+export type AgentSystemPromptConfig =
+ | { type: 'custom'; text: string }
+ | { type: 'preset'; preset: 'claude_code'; append?: string };
-// =============================================================================
-// Execution Cancel Types
+/**
+ * Tools configuration - can be a list of tool names or a preset.
+ */
+export type AgentToolsConfig = string[] | { type: 'preset'; preset: 'claude_code' };
+
+/**
+ * Session options configuration.
+ */
+export interface AgentSessionOptionsConfig {
+ settingSources?: string[];
+ allowedTools?: string[];
+ disallowedTools?: string[];
+ tools?: AgentToolsConfig;
+ betas?: string[];
```
This interface is important because it defines how MCP Chrome Tutorial: Control Your Real Chrome Browser Through MCP implements the patterns covered in this chapter.
-### `app/chrome-extension/common/web-editor-types.ts`
+### `packages/shared/src/agent-types.ts`
-The `WebEditorSelectionChangedPayload` interface in [`app/chrome-extension/common/web-editor-types.ts`](https://github.com/hangwin/mcp-chrome/blob/HEAD/app/chrome-extension/common/web-editor-types.ts) handles a key part of this chapter's functionality:
+The `AgentSessionOptionsConfig` interface in [`packages/shared/src/agent-types.ts`](https://github.com/hangwin/mcp-chrome/blob/HEAD/packages/shared/src/agent-types.ts) handles a key part of this chapter's functionality:
```ts
- * Sent immediately when user selects/deselects elements (no debounce).
+ * Session options configuration.
*/
-export interface WebEditorSelectionChangedPayload {
- /** Source tab ID (filled by background from sender.tab.id) */
- tabId: number;
- /** Currently selected element, or null if deselected */
- selected: SelectedElementSummary | null;
- /** Page URL for context */
- pageUrl?: string;
-}
-
-// =============================================================================
-// Execution Cancel Types
-// =============================================================================
-
-/**
- * Payload for canceling an ongoing Apply execution.
- * Sent from web-editor toolbar or sidepanel to background.
- */
-export interface WebEditorCancelExecutionPayload {
- /** Session ID of the execution to cancel */
- sessionId: string;
- /** Request ID of the execution to cancel */
- requestId: string;
+export interface AgentSessionOptionsConfig {
+ settingSources?: string[];
+ allowedTools?: string[];
+ disallowedTools?: string[];
+ tools?: AgentToolsConfig;
+ betas?: string[];
+ maxThinkingTokens?: number;
+ maxTurns?: number;
+ maxBudgetUsd?: number;
+ mcpServers?: Record<string, unknown>;
+ outputFormat?: Record<string, unknown>;
+ enableFileCheckpointing?: boolean;
+ sandbox?: Record<string, unknown>;
+ env?: Record<string, string>;
+ /**
+ * Optional Codex-specific configuration overrides.
+ * Only applicable when using CodexEngine.
+ */
+ codexConfig?: Partial<CodexEngineConfig>;
}
/**
- * Response from cancel execution request.
+ * Cached management information from Claude SDK.
*/
-export interface WebEditorCancelExecutionResponse {
- /** Whether the cancel request was successful */
- success: boolean;
+export interface AgentManagementInfo {
+ tools?: string[];
+ agents?: string[];
+ plugins?: Array<{ name: string; path?: string }>;
+ skills?: string[];
+ mcpServers?: Array<{ name: string; status: string }>;
```
This interface is important because it defines how MCP Chrome Tutorial: Control Your Real Chrome Browser Through MCP implements the patterns covered in this chapter.
@@ -219,11 +217,11 @@ This interface is important because it defines how MCP Chrome Tutorial: Control
```mermaid
flowchart TD
- A[WebEditorRevertElementPayload]
- B[WebEditorRevertElementResponse]
- C[SelectedElementSummary]
- D[WebEditorSelectionChangedPayload]
- E[WebEditorCancelExecutionPayload]
+ A[AgentActResponse]
+ B[AgentProject]
+ C[AgentEngineInfo]
+ D[AgentSessionOptionsConfig]
+ E[AgentManagementInfo]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-chrome-tutorial/08-contribution-release-and-runtime-operations.md b/tutorials/mcp-chrome-tutorial/08-contribution-release-and-runtime-operations.md
index b0affcc4..8be147db 100644
--- a/tutorials/mcp-chrome-tutorial/08-contribution-release-and-runtime-operations.md
+++ b/tutorials/mcp-chrome-tutorial/08-contribution-release-and-runtime-operations.md
@@ -38,183 +38,161 @@ You now have an end-to-end model for operating and evolving MCP Chrome in produc
Next: extend your MCP operations strategy with [MCP Inspector](../mcp-inspector-tutorial/) and [Firecrawl MCP Server](../firecrawl-mcp-server-tutorial/).
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `app/chrome-extension/inject-scripts/interactive-elements-helper.js`
-
-The `fuzzyMatch` function in [`app/chrome-extension/inject-scripts/interactive-elements-helper.js`](https://github.com/hangwin/mcp-chrome/blob/HEAD/app/chrome-extension/inject-scripts/interactive-elements-helper.js) handles a key part of this chapter's functionality:
-
-```js
- * @returns {boolean}
- */
- function fuzzyMatch(text, query) {
- if (!text || !query) return false;
- const lowerText = text.toLowerCase();
- const lowerQuery = query.toLowerCase();
- let textIndex = 0;
- let queryIndex = 0;
- while (textIndex < lowerText.length && queryIndex < lowerQuery.length) {
- if (lowerText[textIndex] === lowerQuery[queryIndex]) {
- queryIndex++;
- }
- textIndex++;
+### `packages/shared/src/agent-types.ts`
+
+The `AttachmentStatsResponse` interface in [`packages/shared/src/agent-types.ts`](https://github.com/hangwin/mcp-chrome/blob/HEAD/packages/shared/src/agent-types.ts) handles a key part of this chapter's functionality:
+
+```ts
+ * Response for attachment statistics endpoint.
+ */
+export interface AttachmentStatsResponse {
+ success: boolean;
+ rootDir: string;
+ totalFiles: number;
+ totalBytes: number;
+ projects: Array<
+ AttachmentProjectStats & {
+ projectName?: string;
+ existsInDb: boolean;
}
- return queryIndex === lowerQuery.length;
- }
-
- /**
- * Creates the standardized info object for an element.
- * Modified to handle the new 'text' type from the final fallback.
- */
- function createElementInfo(el, type, includeCoordinates, isInteractiveOverride = null) {
- const isActuallyInteractive = isElementInteractive(el);
- const info = {
- type,
- selector: generateSelector(el),
- text: getAccessibleName(el) || el.textContent?.trim(),
- isInteractive: isInteractiveOverride !== null ? isInteractiveOverride : isActuallyInteractive,
- disabled: el.hasAttribute('disabled') || el.getAttribute('aria-disabled') === 'true',
- };
- if (includeCoordinates) {
- const rect = el.getBoundingClientRect();
+ >;
+ orphanProjectIds: string[];
+}
+
+/**
+ * Request body for attachment cleanup endpoint.
+ */
+export interface AttachmentCleanupRequest {
+ /** If provided, cleanup only these projects. Otherwise cleanup all. */
+ projectIds?: string[];
+}
+
+/**
+ * Response for attachment cleanup endpoint.
+ */
+export interface AttachmentCleanupResponse {
+ success: boolean;
+ scope: 'project' | 'selected' | 'all';
+ removedFiles: number;
+ removedBytes: number;
```
-This function is important because it defines how MCP Chrome Tutorial: Control Your Real Chrome Browser Through MCP implements the patterns covered in this chapter.
-
-### `app/chrome-extension/inject-scripts/interactive-elements-helper.js`
-
-The `createElementInfo` function in [`app/chrome-extension/inject-scripts/interactive-elements-helper.js`](https://github.com/hangwin/mcp-chrome/blob/HEAD/app/chrome-extension/inject-scripts/interactive-elements-helper.js) handles a key part of this chapter's functionality:
-
-```js
- * Modified to handle the new 'text' type from the final fallback.
- */
- function createElementInfo(el, type, includeCoordinates, isInteractiveOverride = null) {
- const isActuallyInteractive = isElementInteractive(el);
- const info = {
- type,
- selector: generateSelector(el),
- text: getAccessibleName(el) || el.textContent?.trim(),
- isInteractive: isInteractiveOverride !== null ? isInteractiveOverride : isActuallyInteractive,
- disabled: el.hasAttribute('disabled') || el.getAttribute('aria-disabled') === 'true',
- };
- if (includeCoordinates) {
- const rect = el.getBoundingClientRect();
- info.coordinates = {
- x: rect.left + rect.width / 2,
- y: rect.top + rect.height / 2,
- rect: {
- x: rect.x,
- y: rect.y,
- width: rect.width,
- height: rect.height,
- top: rect.top,
- right: rect.right,
- bottom: rect.bottom,
- left: rect.left,
- },
- };
- }
- return info;
- }
-
- /**
+This interface is important because it defines how MCP Chrome Tutorial: Control Your Real Chrome Browser Through MCP implements the patterns covered in this chapter.
+
+### `packages/shared/src/agent-types.ts`
+
+The `AttachmentCleanupRequest` interface in [`packages/shared/src/agent-types.ts`](https://github.com/hangwin/mcp-chrome/blob/HEAD/packages/shared/src/agent-types.ts) handles a key part of this chapter's functionality:
+
+```ts
+ * Request body for attachment cleanup endpoint.
+ */
+export interface AttachmentCleanupRequest {
+ /** If provided, cleanup only these projects. Otherwise cleanup all. */
+ projectIds?: string[];
+}
+
+/**
+ * Response for attachment cleanup endpoint.
+ */
+export interface AttachmentCleanupResponse {
+ success: boolean;
+ scope: 'project' | 'selected' | 'all';
+ removedFiles: number;
+ removedBytes: number;
+ results: CleanupProjectResult[];
+}
+
+// ============================================================
+// Open Project Types
+// ============================================================
+
+/**
+ * Target application for opening a project directory.
+ */
+export type OpenProjectTarget = 'vscode' | 'terminal';
+
+/**
+ * Request body for open-project endpoint.
+ */
+export interface OpenProjectRequest {
+ /** Target application to open the project in */
```
-This function is important because it defines how MCP Chrome Tutorial: Control Your Real Chrome Browser Through MCP implements the patterns covered in this chapter.
-
-### `app/chrome-extension/inject-scripts/interactive-elements-helper.js`
-
-The `findInteractiveElements` function in [`app/chrome-extension/inject-scripts/interactive-elements-helper.js`](https://github.com/hangwin/mcp-chrome/blob/HEAD/app/chrome-extension/inject-scripts/interactive-elements-helper.js) handles a key part of this chapter's functionality:
-
-```js
- * This is our high-performance Layer 1 search function.
- */
- function findInteractiveElements(options = {}) {
- const { textQuery, includeCoordinates = true, types = Object.keys(ELEMENT_CONFIG) } = options;
-
- const selectorsToFind = types
- .map((type) => ELEMENT_CONFIG[type])
- .filter(Boolean)
- .join(', ');
- if (!selectorsToFind) return [];
+This interface is important because it defines how MCP Chrome Tutorial: Control Your Real Chrome Browser Through MCP implements the patterns covered in this chapter.
+
+### `packages/shared/src/agent-types.ts`
+
+The `AttachmentCleanupResponse` interface in [`packages/shared/src/agent-types.ts`](https://github.com/hangwin/mcp-chrome/blob/HEAD/packages/shared/src/agent-types.ts) handles a key part of this chapter's functionality:
+
+```ts
+ * Response for attachment cleanup endpoint.
+ */
+export interface AttachmentCleanupResponse {
+ success: boolean;
+ scope: 'project' | 'selected' | 'all';
+ removedFiles: number;
+ removedBytes: number;
+ results: CleanupProjectResult[];
+}
+
+// ============================================================
+// Open Project Types
+// ============================================================
+
+/**
+ * Target application for opening a project directory.
+ */
+export type OpenProjectTarget = 'vscode' | 'terminal';
+
+/**
+ * Request body for open-project endpoint.
+ */
+export interface OpenProjectRequest {
+ /** Target application to open the project in */
+ target: OpenProjectTarget;
+}
+
+/**
+ * Response for open-project endpoint.
+ */
+export type OpenProjectResponse = { success: true } | { success: false; error: string };
- const targetElements = querySelectorAllDeep(selectorsToFind);
- const uniqueElements = new Set(targetElements);
- const results = [];
-
- for (const el of uniqueElements) {
- if (!isElementVisible(el) || !isElementInteractive(el)) continue;
-
- const accessibleName = getAccessibleName(el);
- if (textQuery && !fuzzyMatch(accessibleName, textQuery)) continue;
-
- let elementType = 'unknown';
- for (const [type, typeSelector] of Object.entries(ELEMENT_CONFIG)) {
- if (el.matches(typeSelector)) {
- elementType = type;
- break;
- }
- }
- results.push(createElementInfo(el, elementType, includeCoordinates));
- }
- return results;
- }
```
-This function is important because it defines how MCP Chrome Tutorial: Control Your Real Chrome Browser Through MCP implements the patterns covered in this chapter.
+This interface is important because it defines how MCP Chrome Tutorial: Control Your Real Chrome Browser Through MCP implements the patterns covered in this chapter.
-### `app/chrome-extension/inject-scripts/interactive-elements-helper.js`
+### `packages/shared/src/agent-types.ts`
-The `findElementsByTextWithFallback` function in [`app/chrome-extension/inject-scripts/interactive-elements-helper.js`](https://github.com/hangwin/mcp-chrome/blob/HEAD/app/chrome-extension/inject-scripts/interactive-elements-helper.js) handles a key part of this chapter's functionality:
+The `OpenProjectRequest` interface in [`packages/shared/src/agent-types.ts`](https://github.com/hangwin/mcp-chrome/blob/HEAD/packages/shared/src/agent-types.ts) handles a key part of this chapter's functionality:
-```js
- * @returns {ElementInfo[]}
- */
- function findElementsByTextWithFallback(options = {}) {
- const { textQuery, includeCoordinates = true } = options;
+```ts
+ * Request body for open-project endpoint.
+ */
+export interface OpenProjectRequest {
+ /** Target application to open the project in */
+ target: OpenProjectTarget;
+}
- if (!textQuery) {
- return findInteractiveElements({ ...options, types: Object.keys(ELEMENT_CONFIG) });
- }
-
- // --- Layer 1: High-reliability search for interactive elements matching text ---
- let results = findInteractiveElements({ ...options, types: Object.keys(ELEMENT_CONFIG) });
- if (results.length > 0) {
- return results;
- }
+/**
+ * Response for open-project endpoint.
+ */
+export type OpenProjectResponse = { success: true } | { success: false; error: string };
- // --- Layer 2: Find text, then find its interactive ancestor ---
- const lowerCaseText = textQuery.toLowerCase();
- const xPath = `//text()[contains(translate(., 'ABCDEFGHIJKLMNOPQRSTUVWXYZ', 'abcdefghijklmnopqrstuvwxyz'), '${lowerCaseText}')]`;
- const textNodes = document.evaluate(
- xPath,
- document,
- null,
- XPathResult.ORDERED_NODE_SNAPSHOT_TYPE,
- null,
- );
-
- const interactiveElements = new Set();
- if (textNodes.snapshotLength > 0) {
- for (let i = 0; i < textNodes.snapshotLength; i++) {
- const parentElement = textNodes.snapshotItem(i).parentElement;
- if (parentElement) {
- const interactiveAncestor = parentElement.closest(ANY_INTERACTIVE_SELECTOR);
```
-This function is important because it defines how MCP Chrome Tutorial: Control Your Real Chrome Browser Through MCP implements the patterns covered in this chapter.
+This interface is important because it defines how MCP Chrome Tutorial: Control Your Real Chrome Browser Through MCP implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[fuzzyMatch]
- B[createElementInfo]
- C[findInteractiveElements]
- D[findElementsByTextWithFallback]
+ A[AttachmentStatsResponse]
+ B[AttachmentCleanupRequest]
+ C[AttachmentCleanupResponse]
+ D[OpenProjectRequest]
E[QuickPanelAIContext]
A --> B
B --> C
diff --git a/tutorials/mcp-csharp-sdk-tutorial/01-getting-started-and-package-selection.md b/tutorials/mcp-csharp-sdk-tutorial/01-getting-started-and-package-selection.md
index 09ba6a01..7e7a6b9d 100644
--- a/tutorials/mcp-csharp-sdk-tutorial/01-getting-started-and-package-selection.md
+++ b/tutorials/mcp-csharp-sdk-tutorial/01-getting-started-and-package-selection.md
@@ -48,47 +48,127 @@ You now have a package-level starting point that fits your runtime shape.
Next: [Chapter 2: Client/Server Hosting and stdio Basics](02-client-server-hosting-and-stdio-basics.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/ModelContextProtocol.Core/McpSessionHandler.cs`
+### `src/ModelContextProtocol.AspNetCore/StreamableHttpHandler.cs`
-The `McpSessionHandler` class in [`src/ModelContextProtocol.Core/McpSessionHandler.cs`](https://github.com/modelcontextprotocol/csharp-sdk/blob/HEAD/src/ModelContextProtocol.Core/McpSessionHandler.cs) handles a key part of this chapter's functionality:
+The `StreamableHttpHandler` class in [`src/ModelContextProtocol.AspNetCore/StreamableHttpHandler.cs`](https://github.com/modelcontextprotocol/csharp-sdk/blob/HEAD/src/ModelContextProtocol.AspNetCore/StreamableHttpHandler.cs) handles a key part of this chapter's functionality:
```cs
-/// Class for managing an MCP JSON-RPC session. This covers both MCP clients and servers.
-/// </summary>
-internal sealed partial class McpSessionHandler : IAsyncDisposable
+namespace ModelContextProtocol.AspNetCore;
+
+internal sealed class StreamableHttpHandler(
+ IOptions<McpServerOptions> mcpServerOptionsSnapshot,
+ IOptionsFactory<McpServerOptions> mcpServerOptionsFactory,
+ IOptions<HttpServerTransportOptions> httpServerTransportOptions,
+ StatefulSessionManager sessionManager,
+ IHostApplicationLifetime hostApplicationLifetime,
+ IServiceProvider applicationServices,
+ ILoggerFactory loggerFactory)
{
- private static readonly Histogram<double> s_clientSessionDuration = Diagnostics.CreateDurationHistogram(
- "mcp.client.session.duration", "The duration of the MCP session as observed on the MCP client.");
- private static readonly Histogram<double> s_serverSessionDuration = Diagnostics.CreateDurationHistogram(
- "mcp.server.session.duration", "The duration of the MCP session as observed on the MCP server.");
- private static readonly Histogram<double> s_clientOperationDuration = Diagnostics.CreateDurationHistogram(
- "mcp.client.operation.duration", "The duration of the MCP request or notification as observed on the sender from the time it was sent until the response or ack is received.");
- private static readonly Histogram<double> s_serverOperationDuration = Diagnostics.CreateDurationHistogram(
- "mcp.server.operation.duration", "MCP request or notification duration as observed on the receiver from the time it was received until the result or ack is sent.");
-
- /// <summary>The latest version of the protocol supported by this implementation.</summary>
- internal const string LatestProtocolVersion = "2025-11-25";
+ private const string McpSessionIdHeaderName = "Mcp-Session-Id";
+ private const string McpProtocolVersionHeaderName = "MCP-Protocol-Version";
+ private const string LastEventIdHeaderName = "Last-Event-ID";
/// <summary>
/// All protocol versions supported by this implementation.
- /// Keep in sync with s_supportedProtocolVersions in StreamableHttpHandler.
+ /// Keep in sync with McpSessionHandler.SupportedProtocolVersions in ModelContextProtocol.Core.
/// </summary>
- internal static readonly string[] SupportedProtocolVersions =
+ private static readonly HashSet<string> s_supportedProtocolVersions =
[
"2024-11-05",
"2025-03-26",
"2025-06-18",
- LatestProtocolVersion,
+ "2025-11-25",
];
+ private static readonly JsonTypeInfo<JsonRpcMessage> s_messageTypeInfo = GetRequiredJsonTypeInfo<JsonRpcMessage>();
+ private static readonly JsonTypeInfo<JsonRpcError> s_errorTypeInfo = GetRequiredJsonTypeInfo<JsonRpcError>();
+
+ private static bool AllowNewSessionForNonInitializeRequests { get; } =
+ AppContext.TryGetSwitch("ModelContextProtocol.AspNetCore.AllowNewSessionForNonInitializeRequests", out var enabled) && enabled;
+```
+
+This class is important because it defines how MCP C# SDK Tutorial: Production MCP in .NET with Hosting, ASP.NET Core, and Task Workflows implements the patterns covered in this chapter.
+
+### `samples/LongRunningTasks/FileBasedMcpTaskStore.cs`
+
+The `FileBasedMcpTaskStore` class in [`samples/LongRunningTasks/FileBasedMcpTaskStore.cs`](https://github.com/modelcontextprotocol/csharp-sdk/blob/HEAD/samples/LongRunningTasks/FileBasedMcpTaskStore.cs) handles a key part of this chapter's functionality:
+
+```cs
+/// </para>
+/// </remarks>
+public sealed partial class FileBasedMcpTaskStore : IMcpTaskStore
+{
+ private readonly string _storePath;
+ private readonly TimeSpan _executionTime;
+
/// <summary>
- /// Checks if the given protocol version supports priming events.
+ /// Initializes a new instance of the <see cref="FileBasedMcpTaskStore"/> class.
/// </summary>
- /// <param name="protocolVersion">The protocol version to check.</param>
+ /// <param name="storePath">The directory path where task files will be stored.</param>
+ /// <param name="executionTime">
+ /// The fixed execution time for all tasks. Tasks are reported as completed once this
+ /// duration has elapsed since creation. Defaults to 5 seconds.
+ /// </param>
+ public FileBasedMcpTaskStore(string storePath, TimeSpan? executionTime = null)
+ {
+ _storePath = storePath ?? throw new ArgumentNullException(nameof(storePath));
+ _executionTime = executionTime ?? TimeSpan.FromSeconds(5);
+ Directory.CreateDirectory(_storePath);
+ }
+
+ /// <inheritdoc/>
+ public async Task<McpTask> CreateTaskAsync(
+ McpTaskMetadata taskParams,
+ RequestId requestId,
+ JsonRpcRequest request,
+ string? sessionId = null,
+ CancellationToken cancellationToken = default)
+ {
+ var taskId = Guid.NewGuid().ToString("N");
+ var now = DateTimeOffset.UtcNow;
+```
+
+This class is important because it defines how MCP C# SDK Tutorial: Production MCP in .NET with Hosting, ASP.NET Core, and Task Workflows implements the patterns covered in this chapter.
+
+### `samples/LongRunningTasks/FileBasedMcpTaskStore.cs`
+
+The `JsonContext` class in [`samples/LongRunningTasks/FileBasedMcpTaskStore.cs`](https://github.com/modelcontextprotocol/csharp-sdk/blob/HEAD/samples/LongRunningTasks/FileBasedMcpTaskStore.cs) handles a key part of this chapter's functionality:
+
+```cs
+ ExecutionTime = _executionTime,
+ TimeToLive = taskParams.TimeToLive,
+ Result = JsonSerializer.SerializeToElement(request.Params, JsonContext.Default.JsonNode)
+ };
+
+ await WriteTaskEntryAsync(GetTaskFilePath(taskId), entry);
+
+ return ToMcpTask(entry);
+ }
+
+ /// <inheritdoc/>
+ public async Task<McpTask?> GetTaskAsync(
+ string taskId,
+ string? sessionId = null,
+ CancellationToken cancellationToken = default)
+ {
+ var entry = await ReadTaskEntryAsync(taskId);
+ if (entry is null)
+ {
+ return null;
+ }
+
+ // Session isolation
+ if (sessionId is not null && entry.SessionId != sessionId)
+ {
+ return null;
+ }
+
+ // Skip if TTL has expired
+ if (IsExpired(entry))
+ {
+ return null;
```
This class is important because it defines how MCP C# SDK Tutorial: Production MCP in .NET with Hosting, ASP.NET Core, and Task Workflows implements the patterns covered in this chapter.
@@ -134,97 +214,15 @@ internal static partial class UriTemplate
This class is important because it defines how MCP C# SDK Tutorial: Production MCP in .NET with Hosting, ASP.NET Core, and Task Workflows implements the patterns covered in this chapter.
-### `src/ModelContextProtocol.Core/UriTemplate.cs`
-
-The `UriTemplateComparer` class in [`src/ModelContextProtocol.Core/UriTemplate.cs`](https://github.com/modelcontextprotocol/csharp-sdk/blob/HEAD/src/ModelContextProtocol.Core/UriTemplate.cs) handles a key part of this chapter's functionality:
-
-```cs
- /// there to distinguish between different templates.
- /// </summary>
- internal sealed class UriTemplateComparer : IEqualityComparer<string>
- {
- public static IEqualityComparer<string> Instance { get; } = new UriTemplateComparer();
-
- public bool Equals(string? uriTemplate1, string? uriTemplate2)
- {
- if (TryParseAsNonTemplatedUri(uriTemplate1, out Uri? uri1) &&
- TryParseAsNonTemplatedUri(uriTemplate2, out Uri? uri2))
- {
- return uri1 == uri2;
- }
-
- return string.Equals(uriTemplate1, uriTemplate2, StringComparison.Ordinal);
- }
-
- public int GetHashCode([DisallowNull] string uriTemplate)
- {
- if (TryParseAsNonTemplatedUri(uriTemplate, out Uri? uri))
- {
- return uri.GetHashCode();
- }
- else
- {
- return StringComparer.Ordinal.GetHashCode(uriTemplate);
- }
- }
-
- private static bool TryParseAsNonTemplatedUri(string? uriTemplate, [NotNullWhen(true)] out Uri? uri)
- {
- if (uriTemplate is null || uriTemplate.Contains('{'))
-```
-
-This class is important because it defines how MCP C# SDK Tutorial: Production MCP in .NET with Hosting, ASP.NET Core, and Task Workflows implements the patterns covered in this chapter.
-
-### `src/ModelContextProtocol.Core/AIContentExtensions.cs`
-
-The `serves` class in [`src/ModelContextProtocol.Core/AIContentExtensions.cs`](https://github.com/modelcontextprotocol/csharp-sdk/blob/HEAD/src/ModelContextProtocol.Core/AIContentExtensions.cs) handles a key part of this chapter's functionality:
-
-```cs
-/// </summary>
-/// <remarks>
-/// This class serves as an adapter layer between Model Context Protocol (MCP) types and the <see cref="AIContent"/> model types
-/// from the Microsoft.Extensions.AI namespace.
-/// </remarks>
-public static class AIContentExtensions
-{
- /// <summary>
- /// Creates a sampling handler for use with <see cref="McpClientHandlers.SamplingHandler"/> that will
- /// satisfy sampling requests using the specified <see cref="IChatClient"/>.
- /// </summary>
- /// <param name="chatClient">The <see cref="IChatClient"/> with which to satisfy sampling requests.</param>
- /// <param name="serializerOptions">The <see cref="JsonSerializerOptions"/> to use for serializing user-provided objects. If <see langword="null"/>, <see cref="McpJsonUtilities.DefaultOptions"/> is used.</param>
- /// <returns>The created handler delegate that can be assigned to <see cref="McpClientHandlers.SamplingHandler"/>.</returns>
- /// <remarks>
- /// <para>
- /// This method creates a function that converts MCP message requests into chat client calls, enabling
- /// an MCP client to generate text or other content using an actual AI model via the provided chat client.
- /// </para>
- /// <para>
- /// The handler can process text messages, image messages, resource messages, and tool use/results as defined in the
- /// Model Context Protocol.
- /// </para>
- /// </remarks>
- /// <exception cref="ArgumentNullException"><paramref name="chatClient"/> is <see langword="null"/>.</exception>
- public static Func<CreateMessageRequestParams?, IProgress<ProgressNotificationValue>, CancellationToken, ValueTask<CreateMessageResult>> CreateSamplingHandler(
- this IChatClient chatClient,
- JsonSerializerOptions? serializerOptions = null)
- {
- Throw.IfNull(chatClient);
-
- serializerOptions ??= McpJsonUtilities.DefaultOptions;
-```
-
-This class is important because it defines how MCP C# SDK Tutorial: Production MCP in .NET with Hosting, ASP.NET Core, and Task Workflows implements the patterns covered in this chapter.
-
## How These Components Connect
```mermaid
flowchart TD
- A[McpSessionHandler]
- B[UriTemplate]
- C[UriTemplateComparer]
- D[serves]
+ A[StreamableHttpHandler]
+ B[FileBasedMcpTaskStore]
+ C[JsonContext]
+ D[UriTemplate]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-csharp-sdk-tutorial/02-client-server-hosting-and-stdio-basics.md b/tutorials/mcp-csharp-sdk-tutorial/02-client-server-hosting-and-stdio-basics.md
index 1aca4921..5eb06b38 100644
--- a/tutorials/mcp-csharp-sdk-tutorial/02-client-server-hosting-and-stdio-basics.md
+++ b/tutorials/mcp-csharp-sdk-tutorial/02-client-server-hosting-and-stdio-basics.md
@@ -38,183 +38,181 @@ You now have a working stdio baseline for .NET MCP development.
Next: [Chapter 3: ASP.NET Core HTTP Transport and Session Routing](03-aspnetcore-http-transport-and-session-routing.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/ModelContextProtocol.Core/AIContentExtensions.cs`
+### `src/ModelContextProtocol.Core/UriTemplate.cs`
+
+The `UriTemplateComparer` class in [`src/ModelContextProtocol.Core/UriTemplate.cs`](https://github.com/modelcontextprotocol/csharp-sdk/blob/HEAD/src/ModelContextProtocol.Core/UriTemplate.cs) handles a key part of this chapter's functionality:
+
+```cs
+ /// there to distinguish between different templates.
+ /// </summary>
+ internal sealed class UriTemplateComparer : IEqualityComparer<string>
+ {
+ public static IEqualityComparer<string> Instance { get; } = new UriTemplateComparer();
+
+ public bool Equals(string? uriTemplate1, string? uriTemplate2)
+ {
+ if (TryParseAsNonTemplatedUri(uriTemplate1, out Uri? uri1) &&
+ TryParseAsNonTemplatedUri(uriTemplate2, out Uri? uri2))
+ {
+ return uri1 == uri2;
+ }
+
+ return string.Equals(uriTemplate1, uriTemplate2, StringComparison.Ordinal);
+ }
+
+ public int GetHashCode([DisallowNull] string uriTemplate)
+ {
+ if (TryParseAsNonTemplatedUri(uriTemplate, out Uri? uri))
+ {
+ return uri.GetHashCode();
+ }
+ else
+ {
+ return StringComparer.Ordinal.GetHashCode(uriTemplate);
+ }
+ }
+
+ private static bool TryParseAsNonTemplatedUri(string? uriTemplate, [NotNullWhen(true)] out Uri? uri)
+ {
+ if (uriTemplate is null || uriTemplate.Contains('{'))
+```
+
+This class is important because it defines how MCP C# SDK Tutorial: Production MCP in .NET with Hosting, ASP.NET Core, and Task Workflows implements the patterns covered in this chapter.
+
+### `src/ModelContextProtocol.Core/McpJsonUtilities.cs`
-The `AIContentExtensions` class in [`src/ModelContextProtocol.Core/AIContentExtensions.cs`](https://github.com/modelcontextprotocol/csharp-sdk/blob/HEAD/src/ModelContextProtocol.Core/AIContentExtensions.cs) handles a key part of this chapter's functionality:
+The `McpJsonUtilities` class in [`src/ModelContextProtocol.Core/McpJsonUtilities.cs`](https://github.com/modelcontextprotocol/csharp-sdk/blob/HEAD/src/ModelContextProtocol.Core/McpJsonUtilities.cs) handles a key part of this chapter's functionality:
```cs
-/// from the Microsoft.Extensions.AI namespace.
-/// </remarks>
-public static class AIContentExtensions
+
+/// <summary>Provides a collection of utility methods for working with JSON data in the context of MCP.</summary>
+public static partial class McpJsonUtilities
{
/// <summary>
- /// Creates a sampling handler for use with <see cref="McpClientHandlers.SamplingHandler"/> that will
- /// satisfy sampling requests using the specified <see cref="IChatClient"/>.
+ /// Gets the <see cref="JsonSerializerOptions"/> singleton used as the default in JSON serialization operations.
/// </summary>
- /// <param name="chatClient">The <see cref="IChatClient"/> with which to satisfy sampling requests.</param>
- /// <param name="serializerOptions">The <see cref="JsonSerializerOptions"/> to use for serializing user-provided objects. If <see langword="null"/>, <see cref="McpJsonUtilities.DefaultOptions"/> is used.</param>
- /// <returns>The created handler delegate that can be assigned to <see cref="McpClientHandlers.SamplingHandler"/>.</returns>
/// <remarks>
/// <para>
- /// This method creates a function that converts MCP message requests into chat client calls, enabling
- /// an MCP client to generate text or other content using an actual AI model via the provided chat client.
+ /// For Native AOT or applications disabling <see cref="JsonSerializer.IsReflectionEnabledByDefault"/>, this instance
+ /// includes source generated contracts for all common exchange types contained in the ModelContextProtocol library.
/// </para>
/// <para>
- /// The handler can process text messages, image messages, resource messages, and tool use/results as defined in the
- /// Model Context Protocol.
+ /// It additionally turns on the following settings:
+ /// <list type="number">
+ /// <item>Enables <see cref="JsonSerializerDefaults.Web"/> defaults.</item>
+ /// <item>Enables <see cref="JsonIgnoreCondition.WhenWritingNull"/> as the default ignore condition for properties.</item>
+ /// <item>Enables <see cref="JsonNumberHandling.AllowReadingFromString"/> as the default number handling for number types.</item>
+ /// </list>
/// </para>
/// </remarks>
- /// <exception cref="ArgumentNullException"><paramref name="chatClient"/> is <see langword="null"/>.</exception>
- public static Func<CreateMessageRequestParams?, IProgress<ProgressNotificationValue>, CancellationToken, ValueTask<CreateMessageResult>> CreateSamplingHandler(
- this IChatClient chatClient,
- JsonSerializerOptions? serializerOptions = null)
- {
- Throw.IfNull(chatClient);
+ public static JsonSerializerOptions DefaultOptions { get; } = CreateDefaultOptions();
- serializerOptions ??= McpJsonUtilities.DefaultOptions;
-
- return async (requestParams, progress, cancellationToken) =>
- {
+ /// <summary>
+ /// Creates default options to use for MCP-related serialization.
+ /// </summary>
+ /// <returns>The configured options.</returns>
+ [UnconditionalSuppressMessage("ReflectionAnalysis", "IL3050:RequiresDynamicCode", Justification = "Converter is guarded by IsReflectionEnabledByDefault check.")]
+ [UnconditionalSuppressMessage("Trimming", "IL2026:Members annotated with 'RequiresUnreferencedCodeAttribute' require dynamic access", Justification = "Converter is guarded by IsReflectionEnabledByDefault check.")]
+ private static JsonSerializerOptions CreateDefaultOptions()
+ {
+ // Copy the configuration from the source generated context.
```
This class is important because it defines how MCP C# SDK Tutorial: Production MCP in .NET with Hosting, ASP.NET Core, and Task Workflows implements the patterns covered in this chapter.
-### `src/ModelContextProtocol.Core/AIContentExtensions.cs`
+### `src/ModelContextProtocol.Core/McpJsonUtilities.cs`
-The `ToolAIFunctionDeclaration` class in [`src/ModelContextProtocol.Core/AIContentExtensions.cs`](https://github.com/modelcontextprotocol/csharp-sdk/blob/HEAD/src/ModelContextProtocol.Core/AIContentExtensions.cs) handles a key part of this chapter's functionality:
+The `JsonContext` class in [`src/ModelContextProtocol.Core/McpJsonUtilities.cs`](https://github.com/modelcontextprotocol/csharp-sdk/blob/HEAD/src/ModelContextProtocol.Core/McpJsonUtilities.cs) handles a key part of this chapter's functionality:
```cs
- foreach (var tool in tools)
- {
- ((options ??= new()).Tools ??= []).Add(new ToolAIFunctionDeclaration(tool));
- }
-
- if (options.Tools is { Count: > 0 } && requestParams.ToolChoice is { } toolChoice)
- {
- options.ToolMode = toolChoice.Mode switch
- {
- ToolChoice.ModeAuto => ChatToolMode.Auto,
- ToolChoice.ModeRequired => ChatToolMode.RequireAny,
- ToolChoice.ModeNone => ChatToolMode.None,
- _ => null,
- };
- }
- }
-
- List<ChatMessage> messages = [];
- foreach (var sm in requestParams.Messages)
- {
- if (sm.Content?.Select(b => b.ToAIContent(serializerOptions)).OfType<AIContent>().ToList() is { Count: > 0 } aiContents)
- {
- ChatRole role =
- aiContents.All(static c => c is FunctionResultContent) ? ChatRole.Tool :
- sm.Role is Role.Assistant ? ChatRole.Assistant :
- ChatRole.User;
- messages.Add(new ChatMessage(role, aiContents));
- }
- }
-
- return (messages, options);
- }
+ {
+ // Copy the configuration from the source generated context.
+ JsonSerializerOptions options = new(JsonContext.Default.Options);
+
+ // Chain with all supported types from MEAI.
+ options.TypeInfoResolverChain.Add(AIJsonUtilities.DefaultOptions.TypeInfoResolver!);
+
+ // Add a converter for user-defined enums, if reflection is enabled by default.
+ if (JsonSerializer.IsReflectionEnabledByDefault)
+ {
+ options.Converters.Add(new JsonStringEnumConverter());
+ }
+
+ options.MakeReadOnly();
+ return options;
+ }
+
+ internal static JsonTypeInfo<T> GetTypeInfo<T>(this JsonSerializerOptions options) =>
+ (JsonTypeInfo<T>)options.GetTypeInfo(typeof(T));
+
+ internal static JsonElement DefaultMcpToolSchema { get; } = ParseJsonElement("""{"type":"object"}"""u8);
+ internal static object? AsObject(this JsonElement element) => element.ValueKind is JsonValueKind.Null ? null : element;
+
+ internal static bool IsValidMcpToolSchema(JsonElement element)
+ {
+ if (element.ValueKind is not JsonValueKind.Object)
+ {
+ return false;
+ }
+
+ foreach (JsonProperty property in element.EnumerateObject())
+ {
```
This class is important because it defines how MCP C# SDK Tutorial: Production MCP in .NET with Hosting, ASP.NET Core, and Task Workflows implements the patterns covered in this chapter.
-### `src/ModelContextProtocol.Analyzers/XmlToDescriptionGenerator.cs`
+### `src/ModelContextProtocol.AspNetCore/AuthorizationFilterSetup.cs`
-The `XmlToDescriptionGenerator` class in [`src/ModelContextProtocol.Analyzers/XmlToDescriptionGenerator.cs`](https://github.com/modelcontextprotocol/csharp-sdk/blob/HEAD/src/ModelContextProtocol.Analyzers/XmlToDescriptionGenerator.cs) handles a key part of this chapter's functionality:
+The `AuthorizationFilterSetup` class in [`src/ModelContextProtocol.AspNetCore/AuthorizationFilterSetup.cs`](https://github.com/modelcontextprotocol/csharp-sdk/blob/HEAD/src/ModelContextProtocol.AspNetCore/AuthorizationFilterSetup.cs) handles a key part of this chapter's functionality:
```cs
+/// Evaluates authorization policies from endpoint metadata.
/// </summary>
-[Generator]
-public sealed class XmlToDescriptionGenerator : IIncrementalGenerator
+internal sealed class AuthorizationFilterSetup(IAuthorizationPolicyProvider? policyProvider = null) : IConfigureOptions<McpServerOptions>, IPostConfigureOptions<McpServerOptions>
{
- private const string GeneratedFileName = "ModelContextProtocol.Descriptions.g.cs";
+ private static readonly string AuthorizationFilterInvokedKey = "ModelContextProtocol.AspNetCore.AuthorizationFilter.Invoked";
- /// <summary>
- /// A display format that produces fully-qualified type names with "global::" prefix
- /// and includes nullability annotations.
- /// </summary>
- private static readonly SymbolDisplayFormat s_fullyQualifiedFormatWithNullability =
- SymbolDisplayFormat.FullyQualifiedFormat.AddMiscellaneousOptions(
- SymbolDisplayMiscellaneousOptions.IncludeNullableReferenceTypeModifier);
-
- public void Initialize(IncrementalGeneratorInitializationContext context)
+ public void Configure(McpServerOptions options)
{
- // Extract method information for all MCP tools, prompts, and resources.
- // The transform extracts all necessary data upfront so the output doesn't depend on the compilation.
- var allMethods = CreateProviderForAttribute(context, McpAttributeNames.McpServerToolAttribute).Collect()
- .Combine(CreateProviderForAttribute(context, McpAttributeNames.McpServerPromptAttribute).Collect())
- .Combine(CreateProviderForAttribute(context, McpAttributeNames.McpServerResourceAttribute).Collect())
- .Select(static (tuple, _) =>
- {
- var ((tools, prompts), resources) = tuple;
- return new EquatableArray<MethodToGenerate>(tools.Concat(prompts).Concat(resources));
- });
-
- // Report diagnostics for all methods.
- context.RegisterSourceOutput(
- allMethods,
- static (spc, methods) =>
- {
-```
+ ConfigureListToolsFilter(options);
+ ConfigureCallToolFilter(options);
-This class is important because it defines how MCP C# SDK Tutorial: Production MCP in .NET with Hosting, ASP.NET Core, and Task Workflows implements the patterns covered in this chapter.
+ ConfigureListResourcesFilter(options);
+ ConfigureListResourceTemplatesFilter(options);
+ ConfigureReadResourceFilter(options);
+
+ ConfigureListPromptsFilter(options);
+ ConfigureGetPromptFilter(options);
+ }
-### `src/ModelContextProtocol.Analyzers/XmlToDescriptionGenerator.cs`
+ public void PostConfigure(string? name, McpServerOptions options)
+ {
+ CheckListToolsFilter(options);
+ CheckCallToolFilter(options);
-The `MethodToGenerate` interface in [`src/ModelContextProtocol.Analyzers/XmlToDescriptionGenerator.cs`](https://github.com/modelcontextprotocol/csharp-sdk/blob/HEAD/src/ModelContextProtocol.Analyzers/XmlToDescriptionGenerator.cs) handles a key part of this chapter's functionality:
+ CheckListResourcesFilter(options);
+ CheckListResourceTemplatesFilter(options);
+ CheckReadResourceFilter(options);
-```cs
- {
- var ((tools, prompts), resources) = tuple;
- return new EquatableArray<MethodToGenerate>(tools.Concat(prompts).Concat(resources));
- });
-
- // Report diagnostics for all methods.
- context.RegisterSourceOutput(
- allMethods,
- static (spc, methods) =>
- {
- foreach (var method in methods)
- {
- foreach (var diagnostic in method.Diagnostics)
- {
- spc.ReportDiagnostic(CreateDiagnostic(diagnostic));
- }
- }
- });
-
- // Generate source code only for methods that need generation.
- context.RegisterSourceOutput(
- allMethods.Select(static (methods, _) => new EquatableArray<MethodToGenerate>(methods.Where(m => m.NeedsGeneration))),
- static (spc, methods) =>
- {
- if (methods.Length > 0)
- {
- spc.AddSource(GeneratedFileName, SourceText.From(GenerateSourceFile(methods), Encoding.UTF8));
- }
- });
+ CheckListPromptsFilter(options);
+ CheckGetPromptFilter(options);
}
- private static Diagnostic CreateDiagnostic(DiagnosticInfo info) =>
```
-This interface is important because it defines how MCP C# SDK Tutorial: Production MCP in .NET with Hosting, ASP.NET Core, and Task Workflows implements the patterns covered in this chapter.
+This class is important because it defines how MCP C# SDK Tutorial: Production MCP in .NET with Hosting, ASP.NET Core, and Task Workflows implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[AIContentExtensions]
- B[ToolAIFunctionDeclaration]
- C[XmlToDescriptionGenerator]
- D[MethodToGenerate]
+ A[UriTemplateComparer]
+ B[McpJsonUtilities]
+ C[JsonContext]
+ D[AuthorizationFilterSetup]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-csharp-sdk-tutorial/03-aspnetcore-http-transport-and-session-routing.md b/tutorials/mcp-csharp-sdk-tutorial/03-aspnetcore-http-transport-and-session-routing.md
index 93ee6995..fdada258 100644
--- a/tutorials/mcp-csharp-sdk-tutorial/03-aspnetcore-http-transport-and-session-routing.md
+++ b/tutorials/mcp-csharp-sdk-tutorial/03-aspnetcore-http-transport-and-session-routing.md
@@ -39,163 +39,168 @@ You now have an HTTP architecture model for route-scoped MCP services in ASP.NET
Next: [Chapter 4: Tools, Prompts, Resources, and Filter Pipelines](04-tools-prompts-resources-and-filter-pipelines.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/ModelContextProtocol.Analyzers/XmlToDescriptionGenerator.cs`
+### `src/ModelContextProtocol.AspNetCore/AuthorizationFilterSetup.cs`
-The `ParameterInfo` interface in [`src/ModelContextProtocol.Analyzers/XmlToDescriptionGenerator.cs`](https://github.com/modelcontextprotocol/csharp-sdk/blob/HEAD/src/ModelContextProtocol.Analyzers/XmlToDescriptionGenerator.cs) handles a key part of this chapter's functionality:
+The `or` class in [`src/ModelContextProtocol.AspNetCore/AuthorizationFilterSetup.cs`](https://github.com/modelcontextprotocol/csharp-sdk/blob/HEAD/src/ModelContextProtocol.AspNetCore/AuthorizationFilterSetup.cs) handles a key part of this chapter's functionality:
```cs
- // Extract parameters
- var parameterSyntaxList = methodDeclaration.ParameterList.Parameters;
- ParameterInfo[] parameters = new ParameterInfo[methodSymbol.Parameters.Length];
- for (int i = 0; i < methodSymbol.Parameters.Length; i++)
- {
- var param = methodSymbol.Parameters[i];
- var paramSyntax = i < parameterSyntaxList.Count ? parameterSyntaxList[i] : null;
+using System.Diagnostics.CodeAnalysis;
+using System.Security.Claims;
+using Microsoft.AspNetCore.Authorization;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Options;
+using ModelContextProtocol.Protocol;
+using ModelContextProtocol.Server;
+
+namespace ModelContextProtocol.AspNetCore;
+
+/// <summary>
+/// Evaluates authorization policies from endpoint metadata.
+/// </summary>
+internal sealed class AuthorizationFilterSetup(IAuthorizationPolicyProvider? policyProvider = null) : IConfigureOptions<McpServerOptions>, IPostConfigureOptions<McpServerOptions>
+{
+ private static readonly string AuthorizationFilterInvokedKey = "ModelContextProtocol.AspNetCore.AuthorizationFilter.Invoked";
+
+ public void Configure(McpServerOptions options)
+ {
+ ConfigureListToolsFilter(options);
+ ConfigureCallToolFilter(options);
- parameters[i] = new ParameterInfo(
- ParameterType: param.Type.ToDisplayString(s_fullyQualifiedFormatWithNullability),
- Name: param.Name,
- HasDescriptionAttribute: descriptionAttribute is not null && HasAttribute(param, descriptionAttribute),
- XmlDescription: xmlDocs?.Parameters.TryGetValue(param.Name, out var pd) == true && !string.IsNullOrWhiteSpace(pd) ? pd : null,
- DefaultValue: paramSyntax?.Default?.ToFullString().Trim());
- }
+ ConfigureListResourcesFilter(options);
+ ConfigureListResourceTemplatesFilter(options);
+ ConfigureReadResourceFilter(options);
- return new MethodToGenerate(
- NeedsGeneration: true,
- TypeInfo: ExtractTypeInfo(methodSymbol.ContainingType),
- Modifiers: modifiersStr,
- ReturnType: returnType,
- MethodName: methodName,
- Parameters: new EquatableArray<ParameterInfo>(parameters),
- MethodDescription: needsMethodDescription ? xmlDocs?.MethodDescription : null,
- ReturnDescription: needsReturnDescription ? xmlDocs?.Returns : null,
- Diagnostics: diagnostics);
+ ConfigureListPromptsFilter(options);
+ ConfigureGetPromptFilter(options);
}
- /// <summary>Checks if XML documentation would generate any Description attributes for a method.</summary>
- private static bool HasGeneratableContent(XmlDocumentation xmlDocs, IMethodSymbol methodSymbol, INamedTypeSymbol descriptionAttribute)
+ public void PostConfigure(string? name, McpServerOptions options)
{
- if (!string.IsNullOrWhiteSpace(xmlDocs.MethodDescription) && !HasAttribute(methodSymbol, descriptionAttribute))
```
-This interface is important because it defines how MCP C# SDK Tutorial: Production MCP in .NET with Hosting, ASP.NET Core, and Task Workflows implements the patterns covered in this chapter.
+This class is important because it defines how MCP C# SDK Tutorial: Production MCP in .NET with Hosting, ASP.NET Core, and Task Workflows implements the patterns covered in this chapter.
### `src/ModelContextProtocol.Analyzers/XmlToDescriptionGenerator.cs`
-The `TypeInfo` interface in [`src/ModelContextProtocol.Analyzers/XmlToDescriptionGenerator.cs`](https://github.com/modelcontextprotocol/csharp-sdk/blob/HEAD/src/ModelContextProtocol.Analyzers/XmlToDescriptionGenerator.cs) handles a key part of this chapter's functionality:
+The `XmlToDescriptionGenerator` class in [`src/ModelContextProtocol.Analyzers/XmlToDescriptionGenerator.cs`](https://github.com/modelcontextprotocol/csharp-sdk/blob/HEAD/src/ModelContextProtocol.Analyzers/XmlToDescriptionGenerator.cs) handles a key part of this chapter's functionality:
```cs
- return new MethodToGenerate(
- NeedsGeneration: true,
- TypeInfo: ExtractTypeInfo(methodSymbol.ContainingType),
- Modifiers: modifiersStr,
- ReturnType: returnType,
- MethodName: methodName,
- Parameters: new EquatableArray<ParameterInfo>(parameters),
- MethodDescription: needsMethodDescription ? xmlDocs?.MethodDescription : null,
- ReturnDescription: needsReturnDescription ? xmlDocs?.Returns : null,
- Diagnostics: diagnostics);
- }
-
- /// <summary>Checks if XML documentation would generate any Description attributes for a method.</summary>
- private static bool HasGeneratableContent(XmlDocumentation xmlDocs, IMethodSymbol methodSymbol, INamedTypeSymbol descriptionAttribute)
+/// </summary>
+[Generator]
+public sealed class XmlToDescriptionGenerator : IIncrementalGenerator
+{
+ private const string GeneratedFileName = "ModelContextProtocol.Descriptions.g.cs";
+
+ /// <summary>
+ /// A display format that produces fully-qualified type names with "global::" prefix
+ /// and includes nullability annotations.
+ /// </summary>
+ private static readonly SymbolDisplayFormat s_fullyQualifiedFormatWithNullability =
+ SymbolDisplayFormat.FullyQualifiedFormat.AddMiscellaneousOptions(
+ SymbolDisplayMiscellaneousOptions.IncludeNullableReferenceTypeModifier);
+
+ public void Initialize(IncrementalGeneratorInitializationContext context)
{
- if (!string.IsNullOrWhiteSpace(xmlDocs.MethodDescription) && !HasAttribute(methodSymbol, descriptionAttribute))
- {
- return true;
- }
-
- if (!string.IsNullOrWhiteSpace(xmlDocs.Returns) &&
- methodSymbol.GetReturnTypeAttributes().All(attr => !SymbolEqualityComparer.Default.Equals(attr.AttributeClass, descriptionAttribute)))
- {
- return true;
- }
-
- foreach (var param in methodSymbol.Parameters)
- {
- if (!HasAttribute(param, descriptionAttribute) &&
- xmlDocs.Parameters.TryGetValue(param.Name, out var paramDoc) &&
- !string.IsNullOrWhiteSpace(paramDoc))
+ // Extract method information for all MCP tools, prompts, and resources.
+ // The transform extracts all necessary data upfront so the output doesn't depend on the compilation.
+ var allMethods = CreateProviderForAttribute(context, McpAttributeNames.McpServerToolAttribute).Collect()
+ .Combine(CreateProviderForAttribute(context, McpAttributeNames.McpServerPromptAttribute).Collect())
+ .Combine(CreateProviderForAttribute(context, McpAttributeNames.McpServerResourceAttribute).Collect())
+ .Select(static (tuple, _) =>
+ {
+ var ((tools, prompts), resources) = tuple;
+ return new EquatableArray<MethodToGenerate>(tools.Concat(prompts).Concat(resources));
+ });
+
+ // Report diagnostics for all methods.
+ context.RegisterSourceOutput(
+ allMethods,
+ static (spc, methods) =>
{
```
-This interface is important because it defines how MCP C# SDK Tutorial: Production MCP in .NET with Hosting, ASP.NET Core, and Task Workflows implements the patterns covered in this chapter.
+This class is important because it defines how MCP C# SDK Tutorial: Production MCP in .NET with Hosting, ASP.NET Core, and Task Workflows implements the patterns covered in this chapter.
### `src/ModelContextProtocol.Analyzers/XmlToDescriptionGenerator.cs`
-The `TypeDeclarationInfo` interface in [`src/ModelContextProtocol.Analyzers/XmlToDescriptionGenerator.cs`](https://github.com/modelcontextprotocol/csharp-sdk/blob/HEAD/src/ModelContextProtocol.Analyzers/XmlToDescriptionGenerator.cs) handles a key part of this chapter's functionality:
+The `MethodToGenerate` interface in [`src/ModelContextProtocol.Analyzers/XmlToDescriptionGenerator.cs`](https://github.com/modelcontextprotocol/csharp-sdk/blob/HEAD/src/ModelContextProtocol.Analyzers/XmlToDescriptionGenerator.cs) handles a key part of this chapter's functionality:
```cs
-
- // Build list of nested types from innermost to outermost
- var typesBuilder = ImmutableArray.CreateBuilder<TypeDeclarationInfo>();
- for (var current = typeSymbol; current is not null; current = current.ContainingType)
- {
- var typeDecl = current.DeclaringSyntaxReferences.FirstOrDefault()?.GetSyntax() as TypeDeclarationSyntax;
- string typeKeyword;
- if (typeDecl is RecordDeclarationSyntax rds)
{
- string classOrStruct = rds.ClassOrStructKeyword.ValueText;
- if (string.IsNullOrEmpty(classOrStruct))
+ var ((tools, prompts), resources) = tuple;
+ return new EquatableArray<MethodToGenerate>(tools.Concat(prompts).Concat(resources));
+ });
+
+ // Report diagnostics for all methods.
+ context.RegisterSourceOutput(
+ allMethods,
+ static (spc, methods) =>
+ {
+ foreach (var method in methods)
{
- classOrStruct = "class";
+ foreach (var diagnostic in method.Diagnostics)
+ {
+ spc.ReportDiagnostic(CreateDiagnostic(diagnostic));
+ }
}
- typeKeyword = $"{typeDecl.Keyword.ValueText} {classOrStruct}";
- }
- else
- {
- typeKeyword = typeDecl?.Keyword.ValueText ?? "class";
- }
+ });
- typesBuilder.Add(new TypeDeclarationInfo(current.Name, typeKeyword));
- }
-
- // Reverse to get outermost first
- typesBuilder.Reverse();
-
- string ns = typeSymbol.ContainingNamespace.IsGlobalNamespace ? "" : typeSymbol.ContainingNamespace.ToDisplayString();
- return new TypeInfo(ns, new EquatableArray<TypeDeclarationInfo>(typesBuilder.ToImmutable()));
+ // Generate source code only for methods that need generation.
+ context.RegisterSourceOutput(
+ allMethods.Select(static (methods, _) => new EquatableArray<MethodToGenerate>(methods.Where(m => m.NeedsGeneration))),
+ static (spc, methods) =>
+ {
+ if (methods.Length > 0)
+ {
+ spc.AddSource(GeneratedFileName, SourceText.From(GenerateSourceFile(methods), Encoding.UTF8));
+ }
+ });
}
- private static (XmlDocumentation? Docs, bool HasInvalidXml) TryExtractXmlDocumentation(IMethodSymbol methodSymbol)
+ private static Diagnostic CreateDiagnostic(DiagnosticInfo info) =>
```
This interface is important because it defines how MCP C# SDK Tutorial: Production MCP in .NET with Hosting, ASP.NET Core, and Task Workflows implements the patterns covered in this chapter.
### `src/ModelContextProtocol.Analyzers/XmlToDescriptionGenerator.cs`
-The `LocationInfo` interface in [`src/ModelContextProtocol.Analyzers/XmlToDescriptionGenerator.cs`](https://github.com/modelcontextprotocol/csharp-sdk/blob/HEAD/src/ModelContextProtocol.Analyzers/XmlToDescriptionGenerator.cs) handles a key part of this chapter's functionality:
+The `ParameterInfo` interface in [`src/ModelContextProtocol.Analyzers/XmlToDescriptionGenerator.cs`](https://github.com/modelcontextprotocol/csharp-sdk/blob/HEAD/src/ModelContextProtocol.Analyzers/XmlToDescriptionGenerator.cs) handles a key part of this chapter's functionality:
```cs
- /// causes issues when the generator returns cached data with locations from earlier compilations.
- /// </remarks>
- private readonly record struct LocationInfo(string FilePath, TextSpan TextSpan, LinePositionSpan LineSpan)
- {
- public static LocationInfo? FromLocation(Location? location) =>
- location is null || !location.IsInSource ? null :
- new LocationInfo(location.SourceTree?.FilePath ?? "", location.SourceSpan, location.GetLineSpan().Span);
-
- public Location ToLocation() =>
- Location.Create(FilePath, TextSpan, LineSpan);
- }
+ // Extract parameters
+ var parameterSyntaxList = methodDeclaration.ParameterList.Parameters;
+ ParameterInfo[] parameters = new ParameterInfo[methodSymbol.Parameters.Length];
+ for (int i = 0; i < methodSymbol.Parameters.Length; i++)
+ {
+ var param = methodSymbol.Parameters[i];
+ var paramSyntax = i < parameterSyntaxList.Count ? parameterSyntaxList[i] : null;
- /// <summary>Holds diagnostic information to be reported.</summary>
- private readonly record struct DiagnosticInfo(string Id, LocationInfo? Location, string MethodName)
- {
- public static DiagnosticInfo Create(string id, Location? location, string methodName) =>
- new(id, LocationInfo.FromLocation(location), methodName);
+ parameters[i] = new ParameterInfo(
+ ParameterType: param.Type.ToDisplayString(s_fullyQualifiedFormatWithNullability),
+ Name: param.Name,
+ HasDescriptionAttribute: descriptionAttribute is not null && HasAttribute(param, descriptionAttribute),
+ XmlDescription: xmlDocs?.Parameters.TryGetValue(param.Name, out var pd) == true && !string.IsNullOrWhiteSpace(pd) ? pd : null,
+ DefaultValue: paramSyntax?.Default?.ToFullString().Trim());
+ }
- public object?[] MessageArgs => [MethodName];
+ return new MethodToGenerate(
+ NeedsGeneration: true,
+ TypeInfo: ExtractTypeInfo(methodSymbol.ContainingType),
+ Modifiers: modifiersStr,
+ ReturnType: returnType,
+ MethodName: methodName,
+ Parameters: new EquatableArray<ParameterInfo>(parameters),
+ MethodDescription: needsMethodDescription ? xmlDocs?.MethodDescription : null,
+ ReturnDescription: needsReturnDescription ? xmlDocs?.Returns : null,
+ Diagnostics: diagnostics);
}
- /// <summary>Holds extracted XML documentation for a method (used only during extraction, not cached).</summary>
- private sealed record XmlDocumentation(string MethodDescription, string Returns, Dictionary<string, string> Parameters);
-}
-
+ /// <summary>Checks if XML documentation would generate any Description attributes for a method.</summary>
+ private static bool HasGeneratableContent(XmlDocumentation xmlDocs, IMethodSymbol methodSymbol, INamedTypeSymbol descriptionAttribute)
+ {
+ if (!string.IsNullOrWhiteSpace(xmlDocs.MethodDescription) && !HasAttribute(methodSymbol, descriptionAttribute))
```
This interface is important because it defines how MCP C# SDK Tutorial: Production MCP in .NET with Hosting, ASP.NET Core, and Task Workflows implements the patterns covered in this chapter.
@@ -205,10 +210,10 @@ This interface is important because it defines how MCP C# SDK Tutorial: Producti
```mermaid
flowchart TD
- A[ParameterInfo]
- B[TypeInfo]
- C[TypeDeclarationInfo]
- D[LocationInfo]
+ A[or]
+ B[XmlToDescriptionGenerator]
+ C[MethodToGenerate]
+ D[ParameterInfo]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-csharp-sdk-tutorial/04-tools-prompts-resources-and-filter-pipelines.md b/tutorials/mcp-csharp-sdk-tutorial/04-tools-prompts-resources-and-filter-pipelines.md
index c7b1df10..c9610592 100644
--- a/tutorials/mcp-csharp-sdk-tutorial/04-tools-prompts-resources-and-filter-pipelines.md
+++ b/tutorials/mcp-csharp-sdk-tutorial/04-tools-prompts-resources-and-filter-pipelines.md
@@ -40,183 +40,174 @@ You now have an extensibility model for primitives and filters that stays predic
Next: [Chapter 5: Logging, Progress, Elicitation, and Tasks](05-logging-progress-elicitation-and-tasks.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `src/ModelContextProtocol.Analyzers/XmlToDescriptionGenerator.cs`
-The `DiagnosticInfo` interface in [`src/ModelContextProtocol.Analyzers/XmlToDescriptionGenerator.cs`](https://github.com/modelcontextprotocol/csharp-sdk/blob/HEAD/src/ModelContextProtocol.Analyzers/XmlToDescriptionGenerator.cs) handles a key part of this chapter's functionality:
+The `TypeInfo` interface in [`src/ModelContextProtocol.Analyzers/XmlToDescriptionGenerator.cs`](https://github.com/modelcontextprotocol/csharp-sdk/blob/HEAD/src/ModelContextProtocol.Analyzers/XmlToDescriptionGenerator.cs) handles a key part of this chapter's functionality:
```cs
+ return new MethodToGenerate(
+ NeedsGeneration: true,
+ TypeInfo: ExtractTypeInfo(methodSymbol.ContainingType),
+ Modifiers: modifiersStr,
+ ReturnType: returnType,
+ MethodName: methodName,
+ Parameters: new EquatableArray<ParameterInfo>(parameters),
+ MethodDescription: needsMethodDescription ? xmlDocs?.MethodDescription : null,
+ ReturnDescription: needsReturnDescription ? xmlDocs?.Returns : null,
+ Diagnostics: diagnostics);
}
- private static Diagnostic CreateDiagnostic(DiagnosticInfo info) =>
- Diagnostic.Create(info.Id switch
+ /// <summary>Checks if XML documentation would generate any Description attributes for a method.</summary>
+ private static bool HasGeneratableContent(XmlDocumentation xmlDocs, IMethodSymbol methodSymbol, INamedTypeSymbol descriptionAttribute)
+ {
+ if (!string.IsNullOrWhiteSpace(xmlDocs.MethodDescription) && !HasAttribute(methodSymbol, descriptionAttribute))
{
- "MCP001" => Diagnostics.InvalidXmlDocumentation,
- "MCP002" => Diagnostics.McpMethodMustBePartial,
- _ => throw new InvalidOperationException($"Unknown diagnostic ID: {info.Id}")
- }, info.Location?.ToLocation(), info.MessageArgs);
-
- private static IncrementalValuesProvider<MethodToGenerate> CreateProviderForAttribute(
- IncrementalGeneratorInitializationContext context,
- string attributeMetadataName) =>
- context.SyntaxProvider.ForAttributeWithMetadataName(
- attributeMetadataName,
- static (node, _) => node is MethodDeclarationSyntax,
- static (ctx, _) => ExtractMethodInfo((MethodDeclarationSyntax)ctx.TargetNode, (IMethodSymbol)ctx.TargetSymbol, ctx.SemanticModel.Compilation));
+ return true;
+ }
- private static MethodToGenerate ExtractMethodInfo(
- MethodDeclarationSyntax methodDeclaration,
- IMethodSymbol methodSymbol,
- Compilation compilation)
- {
- bool isPartial = methodDeclaration.Modifiers.Any(SyntaxKind.PartialKeyword);
- var descriptionAttribute = compilation.GetTypeByMetadataName(McpAttributeNames.DescriptionAttribute);
+ if (!string.IsNullOrWhiteSpace(xmlDocs.Returns) &&
+ methodSymbol.GetReturnTypeAttributes().All(attr => !SymbolEqualityComparer.Default.Equals(attr.AttributeClass, descriptionAttribute)))
+ {
+ return true;
+ }
- // Try to extract XML documentation
- var (xmlDocs, hasInvalidXml) = TryExtractXmlDocumentation(methodSymbol);
-
- // For non-partial methods, check if we should report a diagnostic
- if (!isPartial)
+ foreach (var param in methodSymbol.Parameters)
{
+ if (!HasAttribute(param, descriptionAttribute) &&
+ xmlDocs.Parameters.TryGetValue(param.Name, out var paramDoc) &&
+ !string.IsNullOrWhiteSpace(paramDoc))
+ {
```
This interface is important because it defines how MCP C# SDK Tutorial: Production MCP in .NET with Hosting, ASP.NET Core, and Task Workflows implements the patterns covered in this chapter.
-### `src/ModelContextProtocol.AspNetCore/StreamableHttpHandler.cs`
+### `src/ModelContextProtocol.Analyzers/XmlToDescriptionGenerator.cs`
-The `StreamableHttpHandler` class in [`src/ModelContextProtocol.AspNetCore/StreamableHttpHandler.cs`](https://github.com/modelcontextprotocol/csharp-sdk/blob/HEAD/src/ModelContextProtocol.AspNetCore/StreamableHttpHandler.cs) handles a key part of this chapter's functionality:
+The `TypeDeclarationInfo` interface in [`src/ModelContextProtocol.Analyzers/XmlToDescriptionGenerator.cs`](https://github.com/modelcontextprotocol/csharp-sdk/blob/HEAD/src/ModelContextProtocol.Analyzers/XmlToDescriptionGenerator.cs) handles a key part of this chapter's functionality:
```cs
-namespace ModelContextProtocol.AspNetCore;
-
-internal sealed class StreamableHttpHandler(
- IOptions<McpServerOptions> mcpServerOptionsSnapshot,
- IOptionsFactory<McpServerOptions> mcpServerOptionsFactory,
- IOptions<HttpServerTransportOptions> httpServerTransportOptions,
- StatefulSessionManager sessionManager,
- IHostApplicationLifetime hostApplicationLifetime,
- IServiceProvider applicationServices,
- ILoggerFactory loggerFactory)
-{
- private const string McpSessionIdHeaderName = "Mcp-Session-Id";
- private const string McpProtocolVersionHeaderName = "MCP-Protocol-Version";
- private const string LastEventIdHeaderName = "Last-Event-ID";
-
- /// <summary>
- /// All protocol versions supported by this implementation.
- /// Keep in sync with McpSessionHandler.SupportedProtocolVersions in ModelContextProtocol.Core.
- /// </summary>
- private static readonly HashSet<string> s_supportedProtocolVersions =
- [
- "2024-11-05",
- "2025-03-26",
- "2025-06-18",
- "2025-11-25",
- ];
-
- private static readonly JsonTypeInfo<JsonRpcMessage> s_messageTypeInfo = GetRequiredJsonTypeInfo<JsonRpcMessage>();
- private static readonly JsonTypeInfo<JsonRpcError> s_errorTypeInfo = GetRequiredJsonTypeInfo<JsonRpcError>();
-
- private static bool AllowNewSessionForNonInitializeRequests { get; } =
- AppContext.TryGetSwitch("ModelContextProtocol.AspNetCore.AllowNewSessionForNonInitializeRequests", out var enabled) && enabled;
+
+ // Build list of nested types from innermost to outermost
+ var typesBuilder = ImmutableArray.CreateBuilder<TypeDeclarationInfo>();
+ for (var current = typeSymbol; current is not null; current = current.ContainingType)
+ {
+ var typeDecl = current.DeclaringSyntaxReferences.FirstOrDefault()?.GetSyntax() as TypeDeclarationSyntax;
+ string typeKeyword;
+ if (typeDecl is RecordDeclarationSyntax rds)
+ {
+ string classOrStruct = rds.ClassOrStructKeyword.ValueText;
+ if (string.IsNullOrEmpty(classOrStruct))
+ {
+ classOrStruct = "class";
+ }
+ typeKeyword = $"{typeDecl.Keyword.ValueText} {classOrStruct}";
+ }
+ else
+ {
+ typeKeyword = typeDecl?.Keyword.ValueText ?? "class";
+ }
+
+ typesBuilder.Add(new TypeDeclarationInfo(current.Name, typeKeyword));
+ }
+
+ // Reverse to get outermost first
+ typesBuilder.Reverse();
+
+ string ns = typeSymbol.ContainingNamespace.IsGlobalNamespace ? "" : typeSymbol.ContainingNamespace.ToDisplayString();
+ return new TypeInfo(ns, new EquatableArray<TypeDeclarationInfo>(typesBuilder.ToImmutable()));
+ }
+
+ private static (XmlDocumentation? Docs, bool HasInvalidXml) TryExtractXmlDocumentation(IMethodSymbol methodSymbol)
```
-This class is important because it defines how MCP C# SDK Tutorial: Production MCP in .NET with Hosting, ASP.NET Core, and Task Workflows implements the patterns covered in this chapter.
+This interface is important because it defines how MCP C# SDK Tutorial: Production MCP in .NET with Hosting, ASP.NET Core, and Task Workflows implements the patterns covered in this chapter.
-### `samples/LongRunningTasks/FileBasedMcpTaskStore.cs`
+### `src/ModelContextProtocol.Analyzers/XmlToDescriptionGenerator.cs`
-The `FileBasedMcpTaskStore` class in [`samples/LongRunningTasks/FileBasedMcpTaskStore.cs`](https://github.com/modelcontextprotocol/csharp-sdk/blob/HEAD/samples/LongRunningTasks/FileBasedMcpTaskStore.cs) handles a key part of this chapter's functionality:
+The `LocationInfo` interface in [`src/ModelContextProtocol.Analyzers/XmlToDescriptionGenerator.cs`](https://github.com/modelcontextprotocol/csharp-sdk/blob/HEAD/src/ModelContextProtocol.Analyzers/XmlToDescriptionGenerator.cs) handles a key part of this chapter's functionality:
```cs
-/// </para>
-/// </remarks>
-public sealed partial class FileBasedMcpTaskStore : IMcpTaskStore
-{
- private readonly string _storePath;
- private readonly TimeSpan _executionTime;
-
- /// <summary>
- /// Initializes a new instance of the <see cref="FileBasedMcpTaskStore"/> class.
- /// </summary>
- /// <param name="storePath">The directory path where task files will be stored.</param>
- /// <param name="executionTime">
- /// The fixed execution time for all tasks. Tasks are reported as completed once this
- /// duration has elapsed since creation. Defaults to 5 seconds.
- /// </param>
- public FileBasedMcpTaskStore(string storePath, TimeSpan? executionTime = null)
+ /// causes issues when the generator returns cached data with locations from earlier compilations.
+ /// </remarks>
+ private readonly record struct LocationInfo(string FilePath, TextSpan TextSpan, LinePositionSpan LineSpan)
{
- _storePath = storePath ?? throw new ArgumentNullException(nameof(storePath));
- _executionTime = executionTime ?? TimeSpan.FromSeconds(5);
- Directory.CreateDirectory(_storePath);
+ public static LocationInfo? FromLocation(Location? location) =>
+ location is null || !location.IsInSource ? null :
+ new LocationInfo(location.SourceTree?.FilePath ?? "", location.SourceSpan, location.GetLineSpan().Span);
+
+ public Location ToLocation() =>
+ Location.Create(FilePath, TextSpan, LineSpan);
}
- /// <inheritdoc/>
- public async Task<McpTask> CreateTaskAsync(
- McpTaskMetadata taskParams,
- RequestId requestId,
- JsonRpcRequest request,
- string? sessionId = null,
- CancellationToken cancellationToken = default)
+ /// <summary>Holds diagnostic information to be reported.</summary>
+ private readonly record struct DiagnosticInfo(string Id, LocationInfo? Location, string MethodName)
{
- var taskId = Guid.NewGuid().ToString("N");
- var now = DateTimeOffset.UtcNow;
-```
+ public static DiagnosticInfo Create(string id, Location? location, string methodName) =>
+ new(id, LocationInfo.FromLocation(location), methodName);
-This class is important because it defines how MCP C# SDK Tutorial: Production MCP in .NET with Hosting, ASP.NET Core, and Task Workflows implements the patterns covered in this chapter.
+ public object?[] MessageArgs => [MethodName];
+ }
-### `samples/LongRunningTasks/FileBasedMcpTaskStore.cs`
+ /// <summary>Holds extracted XML documentation for a method (used only during extraction, not cached).</summary>
+ private sealed record XmlDocumentation(string MethodDescription, string Returns, Dictionary<string, string> Parameters);
+}
-The `JsonContext` class in [`samples/LongRunningTasks/FileBasedMcpTaskStore.cs`](https://github.com/modelcontextprotocol/csharp-sdk/blob/HEAD/samples/LongRunningTasks/FileBasedMcpTaskStore.cs) handles a key part of this chapter's functionality:
+```
-```cs
- ExecutionTime = _executionTime,
- TimeToLive = taskParams.TimeToLive,
- Result = JsonSerializer.SerializeToElement(request.Params, JsonContext.Default.JsonNode)
- };
+This interface is important because it defines how MCP C# SDK Tutorial: Production MCP in .NET with Hosting, ASP.NET Core, and Task Workflows implements the patterns covered in this chapter.
- await WriteTaskEntryAsync(GetTaskFilePath(taskId), entry);
+### `src/ModelContextProtocol.Analyzers/XmlToDescriptionGenerator.cs`
+
+The `DiagnosticInfo` interface in [`src/ModelContextProtocol.Analyzers/XmlToDescriptionGenerator.cs`](https://github.com/modelcontextprotocol/csharp-sdk/blob/HEAD/src/ModelContextProtocol.Analyzers/XmlToDescriptionGenerator.cs) handles a key part of this chapter's functionality:
- return ToMcpTask(entry);
+```cs
}
- /// <inheritdoc/>
- public async Task<McpTask?> GetTaskAsync(
- string taskId,
- string? sessionId = null,
- CancellationToken cancellationToken = default)
- {
- var entry = await ReadTaskEntryAsync(taskId);
- if (entry is null)
+ private static Diagnostic CreateDiagnostic(DiagnosticInfo info) =>
+ Diagnostic.Create(info.Id switch
{
- return null;
- }
+ "MCP001" => Diagnostics.InvalidXmlDocumentation,
+ "MCP002" => Diagnostics.McpMethodMustBePartial,
+ _ => throw new InvalidOperationException($"Unknown diagnostic ID: {info.Id}")
+ }, info.Location?.ToLocation(), info.MessageArgs);
- // Session isolation
- if (sessionId is not null && entry.SessionId != sessionId)
- {
- return null;
- }
+ private static IncrementalValuesProvider<MethodToGenerate> CreateProviderForAttribute(
+ IncrementalGeneratorInitializationContext context,
+ string attributeMetadataName) =>
+ context.SyntaxProvider.ForAttributeWithMetadataName(
+ attributeMetadataName,
+ static (node, _) => node is MethodDeclarationSyntax,
+ static (ctx, _) => ExtractMethodInfo((MethodDeclarationSyntax)ctx.TargetNode, (IMethodSymbol)ctx.TargetSymbol, ctx.SemanticModel.Compilation));
+
+ private static MethodToGenerate ExtractMethodInfo(
+ MethodDeclarationSyntax methodDeclaration,
+ IMethodSymbol methodSymbol,
+ Compilation compilation)
+ {
+ bool isPartial = methodDeclaration.Modifiers.Any(SyntaxKind.PartialKeyword);
+ var descriptionAttribute = compilation.GetTypeByMetadataName(McpAttributeNames.DescriptionAttribute);
- // Skip if TTL has expired
- if (IsExpired(entry))
+ // Try to extract XML documentation
+ var (xmlDocs, hasInvalidXml) = TryExtractXmlDocumentation(methodSymbol);
+
+ // For non-partial methods, check if we should report a diagnostic
+ if (!isPartial)
{
- return null;
```
-This class is important because it defines how MCP C# SDK Tutorial: Production MCP in .NET with Hosting, ASP.NET Core, and Task Workflows implements the patterns covered in this chapter.
+This interface is important because it defines how MCP C# SDK Tutorial: Production MCP in .NET with Hosting, ASP.NET Core, and Task Workflows implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[DiagnosticInfo]
- B[StreamableHttpHandler]
- C[FileBasedMcpTaskStore]
- D[JsonContext]
+ A[TypeInfo]
+ B[TypeDeclarationInfo]
+ C[LocationInfo]
+ D[DiagnosticInfo]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-csharp-sdk-tutorial/05-logging-progress-elicitation-and-tasks.md b/tutorials/mcp-csharp-sdk-tutorial/05-logging-progress-elicitation-and-tasks.md
index d8c51caa..1038f029 100644
--- a/tutorials/mcp-csharp-sdk-tutorial/05-logging-progress-elicitation-and-tasks.md
+++ b/tutorials/mcp-csharp-sdk-tutorial/05-logging-progress-elicitation-and-tasks.md
@@ -41,138 +41,139 @@ You now have a plan for operating advanced MCP capability flows with better dura
Next: [Chapter 6: OAuth-Protected MCP Servers and Clients](06-oauth-protected-mcp-servers-and-clients.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/ModelContextProtocol.AspNetCore/AuthorizationFilterSetup.cs`
+### `src/ModelContextProtocol.Core/AIContentExtensions.cs`
-The `AuthorizationFilterSetup` class in [`src/ModelContextProtocol.AspNetCore/AuthorizationFilterSetup.cs`](https://github.com/modelcontextprotocol/csharp-sdk/blob/HEAD/src/ModelContextProtocol.AspNetCore/AuthorizationFilterSetup.cs) handles a key part of this chapter's functionality:
+The `serves` class in [`src/ModelContextProtocol.Core/AIContentExtensions.cs`](https://github.com/modelcontextprotocol/csharp-sdk/blob/HEAD/src/ModelContextProtocol.Core/AIContentExtensions.cs) handles a key part of this chapter's functionality:
```cs
-/// Evaluates authorization policies from endpoint metadata.
/// </summary>
-internal sealed class AuthorizationFilterSetup(IAuthorizationPolicyProvider? policyProvider = null) : IConfigureOptions<McpServerOptions>, IPostConfigureOptions<McpServerOptions>
+/// <remarks>
+/// This class serves as an adapter layer between Model Context Protocol (MCP) types and the <see cref="AIContent"/> model types
+/// from the Microsoft.Extensions.AI namespace.
+/// </remarks>
+public static class AIContentExtensions
{
- private static readonly string AuthorizationFilterInvokedKey = "ModelContextProtocol.AspNetCore.AuthorizationFilter.Invoked";
-
- public void Configure(McpServerOptions options)
- {
- ConfigureListToolsFilter(options);
- ConfigureCallToolFilter(options);
-
- ConfigureListResourcesFilter(options);
- ConfigureListResourceTemplatesFilter(options);
- ConfigureReadResourceFilter(options);
-
- ConfigureListPromptsFilter(options);
- ConfigureGetPromptFilter(options);
- }
-
- public void PostConfigure(string? name, McpServerOptions options)
+ /// <summary>
+ /// Creates a sampling handler for use with <see cref="McpClientHandlers.SamplingHandler"/> that will
+ /// satisfy sampling requests using the specified <see cref="IChatClient"/>.
+ /// </summary>
+ /// <param name="chatClient">The <see cref="IChatClient"/> with which to satisfy sampling requests.</param>
+ /// <param name="serializerOptions">The <see cref="JsonSerializerOptions"/> to use for serializing user-provided objects. If <see langword="null"/>, <see cref="McpJsonUtilities.DefaultOptions"/> is used.</param>
+ /// <returns>The created handler delegate that can be assigned to <see cref="McpClientHandlers.SamplingHandler"/>.</returns>
+ /// <remarks>
+ /// <para>
+ /// This method creates a function that converts MCP message requests into chat client calls, enabling
+ /// an MCP client to generate text or other content using an actual AI model via the provided chat client.
+ /// </para>
+ /// <para>
+ /// The handler can process text messages, image messages, resource messages, and tool use/results as defined in the
+ /// Model Context Protocol.
+ /// </para>
+ /// </remarks>
+ /// <exception cref="ArgumentNullException"><paramref name="chatClient"/> is <see langword="null"/>.</exception>
+ public static Func<CreateMessageRequestParams?, IProgress<ProgressNotificationValue>, CancellationToken, ValueTask<CreateMessageResult>> CreateSamplingHandler(
+ this IChatClient chatClient,
+ JsonSerializerOptions? serializerOptions = null)
{
- CheckListToolsFilter(options);
- CheckCallToolFilter(options);
-
- CheckListResourcesFilter(options);
- CheckListResourceTemplatesFilter(options);
- CheckReadResourceFilter(options);
-
- CheckListPromptsFilter(options);
- CheckGetPromptFilter(options);
- }
+ Throw.IfNull(chatClient);
+ serializerOptions ??= McpJsonUtilities.DefaultOptions;
```
This class is important because it defines how MCP C# SDK Tutorial: Production MCP in .NET with Hosting, ASP.NET Core, and Task Workflows implements the patterns covered in this chapter.
-### `src/ModelContextProtocol.AspNetCore/AuthorizationFilterSetup.cs`
+### `src/ModelContextProtocol.Core/AIContentExtensions.cs`
-The `or` class in [`src/ModelContextProtocol.AspNetCore/AuthorizationFilterSetup.cs`](https://github.com/modelcontextprotocol/csharp-sdk/blob/HEAD/src/ModelContextProtocol.AspNetCore/AuthorizationFilterSetup.cs) handles a key part of this chapter's functionality:
+The `AIContentExtensions` class in [`src/ModelContextProtocol.Core/AIContentExtensions.cs`](https://github.com/modelcontextprotocol/csharp-sdk/blob/HEAD/src/ModelContextProtocol.Core/AIContentExtensions.cs) handles a key part of this chapter's functionality:
```cs
-using System.Diagnostics.CodeAnalysis;
-using System.Security.Claims;
-using Microsoft.AspNetCore.Authorization;
-using Microsoft.Extensions.DependencyInjection;
-using Microsoft.Extensions.Options;
-using ModelContextProtocol.Protocol;
-using ModelContextProtocol.Server;
-
-namespace ModelContextProtocol.AspNetCore;
-
-/// <summary>
-/// Evaluates authorization policies from endpoint metadata.
-/// </summary>
-internal sealed class AuthorizationFilterSetup(IAuthorizationPolicyProvider? policyProvider = null) : IConfigureOptions<McpServerOptions>, IPostConfigureOptions<McpServerOptions>
+/// from the Microsoft.Extensions.AI namespace.
+/// </remarks>
+public static class AIContentExtensions
{
- private static readonly string AuthorizationFilterInvokedKey = "ModelContextProtocol.AspNetCore.AuthorizationFilter.Invoked";
-
- public void Configure(McpServerOptions options)
+ /// <summary>
+ /// Creates a sampling handler for use with <see cref="McpClientHandlers.SamplingHandler"/> that will
+ /// satisfy sampling requests using the specified <see cref="IChatClient"/>.
+ /// </summary>
+ /// <param name="chatClient">The <see cref="IChatClient"/> with which to satisfy sampling requests.</param>
+ /// <param name="serializerOptions">The <see cref="JsonSerializerOptions"/> to use for serializing user-provided objects. If <see langword="null"/>, <see cref="McpJsonUtilities.DefaultOptions"/> is used.</param>
+ /// <returns>The created handler delegate that can be assigned to <see cref="McpClientHandlers.SamplingHandler"/>.</returns>
+ /// <remarks>
+ /// <para>
+ /// This method creates a function that converts MCP message requests into chat client calls, enabling
+ /// an MCP client to generate text or other content using an actual AI model via the provided chat client.
+ /// </para>
+ /// <para>
+ /// The handler can process text messages, image messages, resource messages, and tool use/results as defined in the
+ /// Model Context Protocol.
+ /// </para>
+ /// </remarks>
+ /// <exception cref="ArgumentNullException"><paramref name="chatClient"/> is <see langword="null"/>.</exception>
+ public static Func<CreateMessageRequestParams?, IProgress<ProgressNotificationValue>, CancellationToken, ValueTask<CreateMessageResult>> CreateSamplingHandler(
+ this IChatClient chatClient,
+ JsonSerializerOptions? serializerOptions = null)
{
- ConfigureListToolsFilter(options);
- ConfigureCallToolFilter(options);
-
- ConfigureListResourcesFilter(options);
- ConfigureListResourceTemplatesFilter(options);
- ConfigureReadResourceFilter(options);
+ Throw.IfNull(chatClient);
- ConfigureListPromptsFilter(options);
- ConfigureGetPromptFilter(options);
- }
+ serializerOptions ??= McpJsonUtilities.DefaultOptions;
- public void PostConfigure(string? name, McpServerOptions options)
- {
+ return async (requestParams, progress, cancellationToken) =>
+ {
```
This class is important because it defines how MCP C# SDK Tutorial: Production MCP in .NET with Hosting, ASP.NET Core, and Task Workflows implements the patterns covered in this chapter.
-### `src/ModelContextProtocol.Core/NotificationHandlers.cs`
+### `src/ModelContextProtocol.Core/AIContentExtensions.cs`
-The `NotificationHandlers` class in [`src/ModelContextProtocol.Core/NotificationHandlers.cs`](https://github.com/modelcontextprotocol/csharp-sdk/blob/HEAD/src/ModelContextProtocol.Core/NotificationHandlers.cs) handles a key part of this chapter's functionality:
+The `ToolAIFunctionDeclaration` class in [`src/ModelContextProtocol.Core/AIContentExtensions.cs`](https://github.com/modelcontextprotocol/csharp-sdk/blob/HEAD/src/ModelContextProtocol.Core/AIContentExtensions.cs) handles a key part of this chapter's functionality:
```cs
-
-/// <summary>Provides thread-safe storage for notification handlers.</summary>
-internal sealed class NotificationHandlers
-{
- /// <summary>A dictionary of linked lists of registrations, indexed by the notification method.</summary>
- private readonly Dictionary<string, Registration> _handlers = [];
-
- /// <summary>Gets the object to be used for all synchronization.</summary>
- private object SyncObj => _handlers;
-
- /// <summary>
- /// Registers a collection of notification handlers at once.
- /// </summary>
- /// <param name="handlers">
- /// A collection of notification method names paired with their corresponding handler functions.
- /// Each key in the collection is a notification method name, and each value is a handler function
- /// that will be invoked when a notification with that method name is received.
- /// </param>
- /// <remarks>
- /// <para>
- /// This method is typically used during client or server initialization to register
- /// all notification handlers provided in capabilities.
- /// </para>
- /// <para>
- /// Registrations completed with this method are permanent and non-removable.
- /// This differs from handlers registered with <see cref="Register"/> which can be temporary.
- /// </para>
- /// <para>
- /// When multiple handlers are registered for the same method, all handlers will be invoked
- /// in reverse order of registration (newest first) when a notification is received.
- /// </para>
- /// <para>
+ foreach (var tool in tools)
+ {
+ ((options ??= new()).Tools ??= []).Add(new ToolAIFunctionDeclaration(tool));
+ }
+
+ if (options.Tools is { Count: > 0 } && requestParams.ToolChoice is { } toolChoice)
+ {
+ options.ToolMode = toolChoice.Mode switch
+ {
+ ToolChoice.ModeAuto => ChatToolMode.Auto,
+ ToolChoice.ModeRequired => ChatToolMode.RequireAny,
+ ToolChoice.ModeNone => ChatToolMode.None,
+ _ => null,
+ };
+ }
+ }
+
+ List<ChatMessage> messages = [];
+ foreach (var sm in requestParams.Messages)
+ {
+ if (sm.Content?.Select(b => b.ToAIContent(serializerOptions)).OfType<AIContent>().ToList() is { Count: > 0 } aiContents)
+ {
+ ChatRole role =
+ aiContents.All(static c => c is FunctionResultContent) ? ChatRole.Tool :
+ sm.Role is Role.Assistant ? ChatRole.Assistant :
+ ChatRole.User;
+ messages.Add(new ChatMessage(role, aiContents));
+ }
+ }
+
+ return (messages, options);
+ }
```
This class is important because it defines how MCP C# SDK Tutorial: Production MCP in .NET with Hosting, ASP.NET Core, and Task Workflows implements the patterns covered in this chapter.
### `src/ModelContextProtocol.Core/NotificationHandlers.cs`
-The `Registration` class in [`src/ModelContextProtocol.Core/NotificationHandlers.cs`](https://github.com/modelcontextprotocol/csharp-sdk/blob/HEAD/src/ModelContextProtocol.Core/NotificationHandlers.cs) handles a key part of this chapter's functionality:
+The `NotificationHandlers` class in [`src/ModelContextProtocol.Core/NotificationHandlers.cs`](https://github.com/modelcontextprotocol/csharp-sdk/blob/HEAD/src/ModelContextProtocol.Core/NotificationHandlers.cs) handles a key part of this chapter's functionality:
```cs
+
+/// <summary>Provides thread-safe storage for notification handlers.</summary>
+internal sealed class NotificationHandlers
{
/// <summary>A dictionary of linked lists of registrations, indexed by the notification method.</summary>
private readonly Dictionary<string, Registration> _handlers = [];
@@ -202,9 +203,6 @@ The `Registration` class in [`src/ModelContextProtocol.Core/NotificationHandlers
/// in reverse order of registration (newest first) when a notification is received.
/// </para>
/// <para>
- /// The registered handlers will be invoked by <see cref="InvokeHandlers"/> when a notification
- /// with the corresponding method name is received.
- /// </para>
```
This class is important because it defines how MCP C# SDK Tutorial: Production MCP in .NET with Hosting, ASP.NET Core, and Task Workflows implements the patterns covered in this chapter.
@@ -214,10 +212,10 @@ This class is important because it defines how MCP C# SDK Tutorial: Production M
```mermaid
flowchart TD
- A[AuthorizationFilterSetup]
- B[or]
- C[NotificationHandlers]
- D[Registration]
+ A[serves]
+ B[AIContentExtensions]
+ C[ToolAIFunctionDeclaration]
+ D[NotificationHandlers]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-csharp-sdk-tutorial/06-oauth-protected-mcp-servers-and-clients.md b/tutorials/mcp-csharp-sdk-tutorial/06-oauth-protected-mcp-servers-and-clients.md
index 89e9edc6..f82d09ee 100644
--- a/tutorials/mcp-csharp-sdk-tutorial/06-oauth-protected-mcp-servers-and-clients.md
+++ b/tutorials/mcp-csharp-sdk-tutorial/06-oauth-protected-mcp-servers-and-clients.md
@@ -39,129 +39,86 @@ You now have a concrete pattern for securing C# MCP servers and clients with OAu
Next: [Chapter 7: Diagnostics, Versioning, and Breaking-Change Management](07-diagnostics-versioning-and-breaking-change-management.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/ModelContextProtocol.Core/McpSession.Methods.cs`
+### `src/ModelContextProtocol.Core/NotificationHandlers.cs`
-The `McpSession` class in [`src/ModelContextProtocol.Core/McpSession.Methods.cs`](https://github.com/modelcontextprotocol/csharp-sdk/blob/HEAD/src/ModelContextProtocol.Core/McpSession.Methods.cs) handles a key part of this chapter's functionality:
+The `Registration` class in [`src/ModelContextProtocol.Core/NotificationHandlers.cs`](https://github.com/modelcontextprotocol/csharp-sdk/blob/HEAD/src/ModelContextProtocol.Core/NotificationHandlers.cs) handles a key part of this chapter's functionality:
```cs
-namespace ModelContextProtocol;
-
-public abstract partial class McpSession : IAsyncDisposable
{
- /// <summary>
- /// Sends a JSON-RPC request and attempts to deserialize the result to <typeparamref name="TResult"/>.
- /// </summary>
- /// <typeparam name="TParameters">The type of the request parameters to serialize from.</typeparam>
- /// <typeparam name="TResult">The type of the result to deserialize to.</typeparam>
- /// <param name="method">The JSON-RPC method name to invoke.</param>
- /// <param name="parameters">The request parameters.</param>
- /// <param name="requestId">The request ID for the request.</param>
- /// <param name="serializerOptions">The options governing request serialization.</param>
- /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
- /// <returns>A task that represents the asynchronous operation. The task result contains the deserialized result.</returns>
- /// <exception cref="ArgumentNullException"><paramref name="method"/> is <see langword="null"/>.</exception>
- /// <exception cref="ArgumentException"><paramref name="method"/> is empty or composed entirely of whitespace.</exception>
- /// <exception cref="McpException">The request failed or the server returned an error response.</exception>
- public ValueTask<TResult> SendRequestAsync<TParameters, TResult>(
- string method,
- TParameters parameters,
- JsonSerializerOptions? serializerOptions = null,
- RequestId requestId = default,
- CancellationToken cancellationToken = default)
- where TResult : notnull
- {
- serializerOptions ??= McpJsonUtilities.DefaultOptions;
- serializerOptions.MakeReadOnly();
-
- return SendRequestAsync(
- method,
- parameters,
-```
+ /// <summary>A dictionary of linked lists of registrations, indexed by the notification method.</summary>
+ private readonly Dictionary<string, Registration> _handlers = [];
-This class is important because it defines how MCP C# SDK Tutorial: Production MCP in .NET with Hosting, ASP.NET Core, and Task Workflows implements the patterns covered in this chapter.
-
-### `src/ModelContextProtocol.Core/McpJsonUtilities.cs`
+ /// <summary>Gets the object to be used for all synchronization.</summary>
+ private object SyncObj => _handlers;
-The `McpJsonUtilities` class in [`src/ModelContextProtocol.Core/McpJsonUtilities.cs`](https://github.com/modelcontextprotocol/csharp-sdk/blob/HEAD/src/ModelContextProtocol.Core/McpJsonUtilities.cs) handles a key part of this chapter's functionality:
-
-```cs
-
-/// <summary>Provides a collection of utility methods for working with JSON data in the context of MCP.</summary>
-public static partial class McpJsonUtilities
-{
/// <summary>
- /// Gets the <see cref="JsonSerializerOptions"/> singleton used as the default in JSON serialization operations.
+ /// Registers a collection of notification handlers at once.
/// </summary>
+ /// <param name="handlers">
+ /// A collection of notification method names paired with their corresponding handler functions.
+ /// Each key in the collection is a notification method name, and each value is a handler function
+ /// that will be invoked when a notification with that method name is received.
+ /// </param>
/// <remarks>
/// <para>
- /// For Native AOT or applications disabling <see cref="JsonSerializer.IsReflectionEnabledByDefault"/>, this instance
- /// includes source generated contracts for all common exchange types contained in the ModelContextProtocol library.
+ /// This method is typically used during client or server initialization to register
+ /// all notification handlers provided in capabilities.
/// </para>
/// <para>
- /// It additionally turns on the following settings:
- /// <list type="number">
- /// <item>Enables <see cref="JsonSerializerDefaults.Web"/> defaults.</item>
- /// <item>Enables <see cref="JsonIgnoreCondition.WhenWritingNull"/> as the default ignore condition for properties.</item>
- /// <item>Enables <see cref="JsonNumberHandling.AllowReadingFromString"/> as the default number handling for number types.</item>
- /// </list>
+ /// Registrations completed with this method are permanent and non-removable.
+ /// This differs from handlers registered with <see cref="Register"/> which can be temporary.
+ /// </para>
+ /// <para>
+ /// When multiple handlers are registered for the same method, all handlers will be invoked
+ /// in reverse order of registration (newest first) when a notification is received.
+ /// </para>
+ /// <para>
+ /// The registered handlers will be invoked by <see cref="InvokeHandlers"/> when a notification
+ /// with the corresponding method name is received.
/// </para>
- /// </remarks>
- public static JsonSerializerOptions DefaultOptions { get; } = CreateDefaultOptions();
-
- /// <summary>
- /// Creates default options to use for MCP-related serialization.
- /// </summary>
- /// <returns>The configured options.</returns>
- [UnconditionalSuppressMessage("ReflectionAnalysis", "IL3050:RequiresDynamicCode", Justification = "Converter is guarded by IsReflectionEnabledByDefault check.")]
- [UnconditionalSuppressMessage("Trimming", "IL2026:Members annotated with 'RequiresUnreferencedCodeAttribute' require dynamic access", Justification = "Converter is guarded by IsReflectionEnabledByDefault check.")]
- private static JsonSerializerOptions CreateDefaultOptions()
- {
- // Copy the configuration from the source generated context.
```
This class is important because it defines how MCP C# SDK Tutorial: Production MCP in .NET with Hosting, ASP.NET Core, and Task Workflows implements the patterns covered in this chapter.
-### `src/ModelContextProtocol.Core/McpJsonUtilities.cs`
+### `src/ModelContextProtocol.AspNetCore/HttpServerTransportOptions.cs`
-The `JsonContext` class in [`src/ModelContextProtocol.Core/McpJsonUtilities.cs`](https://github.com/modelcontextprotocol/csharp-sdk/blob/HEAD/src/ModelContextProtocol.Core/McpJsonUtilities.cs) handles a key part of this chapter's functionality:
+The `HttpServerTransportOptions` class in [`src/ModelContextProtocol.AspNetCore/HttpServerTransportOptions.cs`](https://github.com/modelcontextprotocol/csharp-sdk/blob/HEAD/src/ModelContextProtocol.AspNetCore/HttpServerTransportOptions.cs) handles a key part of this chapter's functionality:
```cs
- {
- // Copy the configuration from the source generated context.
- JsonSerializerOptions options = new(JsonContext.Default.Options);
-
- // Chain with all supported types from MEAI.
- options.TypeInfoResolverChain.Add(AIJsonUtilities.DefaultOptions.TypeInfoResolver!);
-
- // Add a converter for user-defined enums, if reflection is enabled by default.
- if (JsonSerializer.IsReflectionEnabledByDefault)
- {
- options.Converters.Add(new JsonStringEnumConverter());
- }
-
- options.MakeReadOnly();
- return options;
- }
-
- internal static JsonTypeInfo<T> GetTypeInfo<T>(this JsonSerializerOptions options) =>
- (JsonTypeInfo<T>)options.GetTypeInfo(typeof(T));
-
- internal static JsonElement DefaultMcpToolSchema { get; } = ParseJsonElement("""{"type":"object"}"""u8);
- internal static object? AsObject(this JsonElement element) => element.ValueKind is JsonValueKind.Null ? null : element;
-
- internal static bool IsValidMcpToolSchema(JsonElement element)
- {
- if (element.ValueKind is not JsonValueKind.Object)
- {
- return false;
- }
+/// For details on the Streamable HTTP transport, see the <see href="https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#streamable-http">protocol specification</see>.
+/// </remarks>
+public class HttpServerTransportOptions
+{
+ /// <summary>
+ /// Gets or sets an optional asynchronous callback to configure per-session <see cref="McpServerOptions"/>
+ /// with access to the <see cref="HttpContext"/> of the request that initiated the session.
+ /// </summary>
+ /// <remarks>
+ /// In stateful mode (the default), this callback is invoked once per session when the client sends the
+ /// <c>initialize</c> request. In <see cref="Stateless"/> mode, it is invoked on <b>every HTTP request</b>
+ /// because each request creates a fresh server context.
+ /// </remarks>
+ public Func<HttpContext, McpServerOptions, CancellationToken, Task>? ConfigureSessionOptions { get; set; }
- foreach (JsonProperty property in element.EnumerateObject())
- {
+ /// <summary>
+ /// Gets or sets an optional asynchronous callback for running new MCP sessions manually.
+ /// </summary>
+ /// <remarks>
+ /// This callback is useful for running logic before a session starts and after it completes.
+ /// <para>
+ /// The <see cref="HttpContext"/> parameter comes from the request that initiated the session (e.g., the
+ /// initialize request) and may not be usable after <see cref="McpServer.RunAsync"/> starts, since that
+ /// request will have already completed.
+ /// </para>
+ /// <para>
+ /// Consider using <see cref="ConfigureSessionOptions"/> instead, which provides access to the
+ /// <see cref="HttpContext"/> of the initializing request with fewer known issues.
+ /// </para>
+ /// <para>
+ /// This API is experimental and may be removed or change signatures in a future release.
+ /// </para>
```
This class is important because it defines how MCP C# SDK Tutorial: Production MCP in .NET with Hosting, ASP.NET Core, and Task Workflows implements the patterns covered in this chapter.
@@ -207,15 +164,56 @@ internal sealed partial class StatefulSessionManager(
This class is important because it defines how MCP C# SDK Tutorial: Production MCP in .NET with Hosting, ASP.NET Core, and Task Workflows implements the patterns covered in this chapter.
+### `src/ModelContextProtocol.Analyzers/CS1066Suppressor.cs`
+
+The `CS1066Suppressor` class in [`src/ModelContextProtocol.Analyzers/CS1066Suppressor.cs`](https://github.com/modelcontextprotocol/csharp-sdk/blob/HEAD/src/ModelContextProtocol.Analyzers/CS1066Suppressor.cs) handles a key part of this chapter's functionality:
+
+```cs
+/// </remarks>
+[DiagnosticAnalyzer(LanguageNames.CSharp)]
+public sealed class CS1066Suppressor : DiagnosticSuppressor
+{
+ private static readonly SuppressionDescriptor McpToolSuppression = new(
+ id: "MCP_CS1066_TOOL",
+ suppressedDiagnosticId: "CS1066",
+ justification: "Default values on MCP tool method implementing declarations are copied to the generated defining declaration by the source generator.");
+
+ private static readonly SuppressionDescriptor McpPromptSuppression = new(
+ id: "MCP_CS1066_PROMPT",
+ suppressedDiagnosticId: "CS1066",
+ justification: "Default values on MCP prompt method implementing declarations are copied to the generated defining declaration by the source generator.");
+
+ private static readonly SuppressionDescriptor McpResourceSuppression = new(
+ id: "MCP_CS1066_RESOURCE",
+ suppressedDiagnosticId: "CS1066",
+ justification: "Default values on MCP resource method implementing declarations are copied to the generated defining declaration by the source generator.");
+
+ /// <inheritdoc/>
+ public override ImmutableArray<SuppressionDescriptor> SupportedSuppressions =>
+ ImmutableArray.Create(McpToolSuppression, McpPromptSuppression, McpResourceSuppression);
+
+ /// <inheritdoc/>
+ public override void ReportSuppressions(SuppressionAnalysisContext context)
+ {
+ // Cache semantic models and attribute symbols per syntax tree/compilation to avoid redundant calls
+ Dictionary<SyntaxTree, SemanticModel>? semanticModelCache = null;
+ INamedTypeSymbol? mcpToolAttribute = null;
+ INamedTypeSymbol? mcpPromptAttribute = null;
+ INamedTypeSymbol? mcpResourceAttribute = null;
+ bool attributesResolved = false;
+```
+
+This class is important because it defines how MCP C# SDK Tutorial: Production MCP in .NET with Hosting, ASP.NET Core, and Task Workflows implements the patterns covered in this chapter.
+
## How These Components Connect
```mermaid
flowchart TD
- A[McpSession]
- B[McpJsonUtilities]
- C[JsonContext]
- D[StatefulSessionManager]
+ A[Registration]
+ B[HttpServerTransportOptions]
+ C[StatefulSessionManager]
+ D[CS1066Suppressor]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-csharp-sdk-tutorial/07-diagnostics-versioning-and-breaking-change-management.md b/tutorials/mcp-csharp-sdk-tutorial/07-diagnostics-versioning-and-breaking-change-management.md
index 32826e19..5bde150d 100644
--- a/tutorials/mcp-csharp-sdk-tutorial/07-diagnostics-versioning-and-breaking-change-management.md
+++ b/tutorials/mcp-csharp-sdk-tutorial/07-diagnostics-versioning-and-breaking-change-management.md
@@ -39,88 +39,127 @@ You now have a change-management model for keeping C# MCP deployments stable whi
Next: [Chapter 8: Testing, Operations, and Contribution Workflows](08-testing-operations-and-contribution-workflows.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/ModelContextProtocol.AspNetCore/HttpServerTransportOptions.cs`
+### `src/ModelContextProtocol.Core/McpSession.cs`
-The `HttpServerTransportOptions` class in [`src/ModelContextProtocol.AspNetCore/HttpServerTransportOptions.cs`](https://github.com/modelcontextprotocol/csharp-sdk/blob/HEAD/src/ModelContextProtocol.AspNetCore/HttpServerTransportOptions.cs) handles a key part of this chapter's functionality:
+The `for` class in [`src/ModelContextProtocol.Core/McpSession.cs`](https://github.com/modelcontextprotocol/csharp-sdk/blob/HEAD/src/ModelContextProtocol.Core/McpSession.cs) handles a key part of this chapter's functionality:
```cs
-/// For details on the Streamable HTTP transport, see the <see href="https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#streamable-http">protocol specification</see>.
+/// <item>Sending JSON-RPC requests and receiving responses.</item>
+/// <item>Sending notifications to the connected session.</item>
+/// <item>Registering handlers for receiving notifications.</item>
+/// </list>
+/// </para>
+/// <para>
+/// <see cref="McpSession"/> serves as the base class for both <see cref="McpClient"/> and
+/// <see cref="McpServer"/>, providing the common functionality needed for MCP protocol
+/// communication. Most applications will use these more specific interfaces rather than working with
+/// <see cref="McpSession"/> directly.
+/// </para>
+/// <para>
+/// All MCP sessions should be properly disposed after use as they implement <see cref="IAsyncDisposable"/>.
+/// </para>
/// </remarks>
-public class HttpServerTransportOptions
+public abstract partial class McpSession : IAsyncDisposable
{
+ /// <summary>Gets an identifier associated with the current MCP session.</summary>
+ /// <remarks>
+ /// Typically populated in transports supporting multiple sessions, such as Streamable HTTP or SSE.
+ /// Can return <see langword="null"/> if the session hasn't initialized or if the transport doesn't
+ /// support multiple sessions (as is the case with STDIO).
+ /// </remarks>
+ public abstract string? SessionId { get; }
+
/// <summary>
- /// Gets or sets an optional asynchronous callback to configure per-session <see cref="McpServerOptions"/>
- /// with access to the <see cref="HttpContext"/> of the request that initiated the session.
+ /// Gets the negotiated protocol version for the current MCP session.
/// </summary>
- public Func<HttpContext, McpServerOptions, CancellationToken, Task>? ConfigureSessionOptions { get; set; }
+ /// <remarks>
+ /// Returns the protocol version negotiated during session initialization,
+ /// or <see langword="null"/> if initialization hasn't yet occurred.
+ /// </remarks>
+```
+
+This class is important because it defines how MCP C# SDK Tutorial: Production MCP in .NET with Hosting, ASP.NET Core, and Task Workflows implements the patterns covered in this chapter.
+
+### `src/ModelContextProtocol.Core/McpSession.cs`
+
+The `McpSession` class in [`src/ModelContextProtocol.Core/McpSession.cs`](https://github.com/modelcontextprotocol/csharp-sdk/blob/HEAD/src/ModelContextProtocol.Core/McpSession.cs) handles a key part of this chapter's functionality:
+
+```cs
+/// </para>
+/// <para>
+/// <see cref="McpSession"/> serves as the base class for both <see cref="McpClient"/> and
+/// <see cref="McpServer"/>, providing the common functionality needed for MCP protocol
+/// communication. Most applications will use these more specific interfaces rather than working with
+/// <see cref="McpSession"/> directly.
+/// </para>
+/// <para>
+/// All MCP sessions should be properly disposed after use as they implement <see cref="IAsyncDisposable"/>.
+/// </para>
+/// </remarks>
+public abstract partial class McpSession : IAsyncDisposable
+{
+ /// <summary>Gets an identifier associated with the current MCP session.</summary>
+ /// <remarks>
+ /// Typically populated in transports supporting multiple sessions, such as Streamable HTTP or SSE.
+ /// Can return <see langword="null"/> if the session hasn't initialized or if the transport doesn't
+ /// support multiple sessions (as is the case with STDIO).
+ /// </remarks>
+ public abstract string? SessionId { get; }
/// <summary>
- /// Gets or sets an optional asynchronous callback for running new MCP sessions manually.
+ /// Gets the negotiated protocol version for the current MCP session.
/// </summary>
/// <remarks>
- /// This callback is useful for running logic before a session starts and after it completes.
- /// <para>
- /// The <see cref="HttpContext"/> parameter comes from the request that initiated the session (e.g., the
- /// initialize request) and may not be usable after <see cref="McpServer.RunAsync"/> starts, since that
- /// request will have already completed.
- /// </para>
- /// <para>
- /// Consider using <see cref="ConfigureSessionOptions"/> instead, which provides access to the
- /// <see cref="HttpContext"/> of the initializing request with fewer known issues.
- /// </para>
- /// <para>
- /// This API is experimental and may be removed or change signatures in a future release.
- /// </para>
+ /// Returns the protocol version negotiated during session initialization,
+ /// or <see langword="null"/> if initialization hasn't yet occurred.
/// </remarks>
- [System.Diagnostics.CodeAnalysis.Experimental(Experimentals.RunSessionHandler_DiagnosticId, UrlFormat = Experimentals.RunSessionHandler_Url)]
- public Func<HttpContext, McpServer, CancellationToken, Task>? RunSessionHandler { get; set; }
+ public abstract string? NegotiatedProtocolVersion { get; }
/// <summary>
+ /// Sends a JSON-RPC request to the connected session and waits for a response.
```
This class is important because it defines how MCP C# SDK Tutorial: Production MCP in .NET with Hosting, ASP.NET Core, and Task Workflows implements the patterns covered in this chapter.
-### `src/ModelContextProtocol.Analyzers/CS1066Suppressor.cs`
+### `src/ModelContextProtocol.Core/McpSession.cs`
-The `CS1066Suppressor` class in [`src/ModelContextProtocol.Analyzers/CS1066Suppressor.cs`](https://github.com/modelcontextprotocol/csharp-sdk/blob/HEAD/src/ModelContextProtocol.Analyzers/CS1066Suppressor.cs) handles a key part of this chapter's functionality:
+The `that` class in [`src/ModelContextProtocol.Core/McpSession.cs`](https://github.com/modelcontextprotocol/csharp-sdk/blob/HEAD/src/ModelContextProtocol.Core/McpSession.cs) handles a key part of this chapter's functionality:
```cs
-/// </remarks>
-[DiagnosticAnalyzer(LanguageNames.CSharp)]
-public sealed class CS1066Suppressor : DiagnosticSuppressor
-{
- private static readonly SuppressionDescriptor McpToolSuppression = new(
- id: "MCP_CS1066_TOOL",
- suppressedDiagnosticId: "CS1066",
- justification: "Default values on MCP tool method implementing declarations are copied to the generated defining declaration by the source generator.");
-
- private static readonly SuppressionDescriptor McpPromptSuppression = new(
- id: "MCP_CS1066_PROMPT",
- suppressedDiagnosticId: "CS1066",
- justification: "Default values on MCP prompt method implementing declarations are copied to the generated defining declaration by the source generator.");
-
- private static readonly SuppressionDescriptor McpResourceSuppression = new(
- id: "MCP_CS1066_RESOURCE",
- suppressedDiagnosticId: "CS1066",
- justification: "Default values on MCP resource method implementing declarations are copied to the generated defining declaration by the source generator.");
-
- /// <inheritdoc/>
- public override ImmutableArray<SuppressionDescriptor> SupportedSuppressions =>
- ImmutableArray.Create(McpToolSuppression, McpPromptSuppression, McpResourceSuppression);
-
- /// <inheritdoc/>
- public override void ReportSuppressions(SuppressionAnalysisContext context)
- {
- // Cache semantic models and attribute symbols per syntax tree/compilation to avoid redundant calls
- Dictionary<SyntaxTree, SemanticModel>? semanticModelCache = null;
- INamedTypeSymbol? mcpToolAttribute = null;
- INamedTypeSymbol? mcpPromptAttribute = null;
- INamedTypeSymbol? mcpResourceAttribute = null;
- bool attributesResolved = false;
+ /// <remarks>
+ /// This method provides low-level access to send raw JSON-RPC requests. For most use cases,
+ /// consider using the strongly-typed methods that provide a more convenient API.
+ /// </remarks>
+ public abstract Task<JsonRpcResponse> SendRequestAsync(JsonRpcRequest request, CancellationToken cancellationToken = default);
+
+ /// <summary>
+ /// Sends a JSON-RPC message to the connected session.
+ /// </summary>
+ /// <param name="message">
+ /// The JSON-RPC message to send. This can be any type that implements JsonRpcMessage, such as
+ /// JsonRpcRequest, JsonRpcResponse, JsonRpcNotification, or JsonRpcError.
+ /// </param>
+ /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+ /// <returns>A task that represents the asynchronous send operation.</returns>
+ /// <exception cref="InvalidOperationException">The transport is not connected.</exception>
+ /// <exception cref="ArgumentNullException"><paramref name="message"/> is <see langword="null"/>.</exception>
+ /// <remarks>
+ /// <para>
+ /// This method provides low-level access to send any JSON-RPC message. For specific message types,
+ /// consider using the higher-level methods such as <see cref="SendRequestAsync"/> or methods
+ /// on this class that provide a simpler API.
+ /// </para>
+ /// <para>
+ /// The method serializes the message and transmits it using the underlying transport mechanism.
+ /// </para>
+ /// </remarks>
+ public abstract Task SendMessageAsync(JsonRpcMessage message, CancellationToken cancellationToken = default);
+
+ /// <summary>Registers a handler to be invoked when a notification for the specified method is received.</summary>
+ /// <param name="method">The notification method.</param>
+ /// <param name="handler">The handler to be invoked.</param>
```
This class is important because it defines how MCP C# SDK Tutorial: Production MCP in .NET with Hosting, ASP.NET Core, and Task Workflows implements the patterns covered in this chapter.
@@ -166,56 +205,15 @@ internal sealed class StreamableHttpSession(
This class is important because it defines how MCP C# SDK Tutorial: Production MCP in .NET with Hosting, ASP.NET Core, and Task Workflows implements the patterns covered in this chapter.
-### `src/ModelContextProtocol.AspNetCore/StreamableHttpSession.cs`
-
-The `UnreferenceDisposable` class in [`src/ModelContextProtocol.AspNetCore/StreamableHttpSession.cs`](https://github.com/modelcontextprotocol/csharp-sdk/blob/HEAD/src/ModelContextProtocol.AspNetCore/StreamableHttpSession.cs) handles a key part of this chapter's functionality:
-
-```cs
- }
-
- return new UnreferenceDisposable(this);
- }
-
- /// <summary>
- /// Ensures the session is registered with the session manager without acquiring a reference.
- /// No-ops if the session is already started.
- /// </summary>
- public async ValueTask EnsureStartedAsync(CancellationToken cancellationToken)
- {
- bool needsStart;
- lock (_stateLock)
- {
- needsStart = _state == SessionState.Uninitialized;
- if (needsStart)
- {
- _state = SessionState.Started;
- }
- }
-
- if (needsStart)
- {
- await sessionManager.StartNewSessionAsync(this, cancellationToken);
-
- // Session is registered with 0 references (idle), so reflect that in the idle count.
- sessionManager.IncrementIdleSessionCount();
- }
- }
-
- public bool TryStartGetRequest() => Interlocked.Exchange(ref _getRequestStarted, 1) == 0;
- public bool HasSameUserId(ClaimsPrincipal user) => userId == StreamableHttpHandler.GetUserIdClaim(user);
-```
-
-This class is important because it defines how MCP C# SDK Tutorial: Production MCP in .NET with Hosting, ASP.NET Core, and Task Workflows implements the patterns covered in this chapter.
-
## How These Components Connect
```mermaid
flowchart TD
- A[HttpServerTransportOptions]
- B[CS1066Suppressor]
- C[StreamableHttpSession]
- D[UnreferenceDisposable]
+ A[for]
+ B[McpSession]
+ C[that]
+ D[StreamableHttpSession]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-csharp-sdk-tutorial/08-testing-operations-and-contribution-workflows.md b/tutorials/mcp-csharp-sdk-tutorial/08-testing-operations-and-contribution-workflows.md
index dfce0ad1..bf27d36f 100644
--- a/tutorials/mcp-csharp-sdk-tutorial/08-testing-operations-and-contribution-workflows.md
+++ b/tutorials/mcp-csharp-sdk-tutorial/08-testing-operations-and-contribution-workflows.md
@@ -39,12 +39,51 @@ You now have a practical operations and contribution framework for long-term C#
Next: Continue with [MCP Use Tutorial](../mcp-use-tutorial/)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `src/ModelContextProtocol.AspNetCore/StreamableHttpSession.cs`
+The `UnreferenceDisposable` class in [`src/ModelContextProtocol.AspNetCore/StreamableHttpSession.cs`](https://github.com/modelcontextprotocol/csharp-sdk/blob/HEAD/src/ModelContextProtocol.AspNetCore/StreamableHttpSession.cs) handles a key part of this chapter's functionality:
+
+```cs
+ }
+
+ return new UnreferenceDisposable(this);
+ }
+
+ /// <summary>
+ /// Ensures the session is registered with the session manager without acquiring a reference.
+ /// No-ops if the session is already started.
+ /// </summary>
+ public async ValueTask EnsureStartedAsync(CancellationToken cancellationToken)
+ {
+ bool needsStart;
+ lock (_stateLock)
+ {
+ needsStart = _state == SessionState.Uninitialized;
+ if (needsStart)
+ {
+ _state = SessionState.Started;
+ }
+ }
+
+ if (needsStart)
+ {
+ await sessionManager.StartNewSessionAsync(this, cancellationToken);
+
+ // Session is registered with 0 references (idle), so reflect that in the idle count.
+ sessionManager.IncrementIdleSessionCount();
+ }
+ }
+
+ public bool TryStartGetRequest() => Interlocked.Exchange(ref _getRequestStarted, 1) == 0;
+ public bool HasSameUserId(ClaimsPrincipal user) => userId == StreamableHttpHandler.GetUserIdClaim(user);
+```
+
+This class is important because it defines how MCP C# SDK Tutorial: Production MCP in .NET with Hosting, ASP.NET Core, and Task Workflows implements the patterns covered in this chapter.
+
+### `src/ModelContextProtocol.AspNetCore/StreamableHttpSession.cs`
+
The `SessionState` interface in [`src/ModelContextProtocol.AspNetCore/StreamableHttpSession.cs`](https://github.com/modelcontextprotocol/csharp-sdk/blob/HEAD/src/ModelContextProtocol.AspNetCore/StreamableHttpSession.cs) handles a key part of this chapter's functionality:
```cs
@@ -84,125 +123,84 @@ The `SessionState` interface in [`src/ModelContextProtocol.AspNetCore/Streamable
This interface is important because it defines how MCP C# SDK Tutorial: Production MCP in .NET with Hosting, ASP.NET Core, and Task Workflows implements the patterns covered in this chapter.
-### `src/ModelContextProtocol.Core/McpSession.cs`
+### `src/Common/Experimentals.cs`
-The `for` class in [`src/ModelContextProtocol.Core/McpSession.cs`](https://github.com/modelcontextprotocol/csharp-sdk/blob/HEAD/src/ModelContextProtocol.Core/McpSession.cs) handles a key part of this chapter's functionality:
+The `Experimentals` class in [`src/Common/Experimentals.cs`](https://github.com/modelcontextprotocol/csharp-sdk/blob/HEAD/src/Common/Experimentals.cs) handles a key part of this chapter's functionality:
```cs
-/// <item>Sending JSON-RPC requests and receiving responses.</item>
-/// <item>Sending notifications to the connected session.</item>
-/// <item>Registering handlers for receiving notifications.</item>
-/// </list>
-/// </para>
-/// <para>
-/// <see cref="McpSession"/> serves as the base class for both <see cref="McpClient"/> and
-/// <see cref="McpServer"/>, providing the common functionality needed for MCP protocol
-/// communication. Most applications will use these more specific interfaces rather than working with
-/// <see cref="McpSession"/> directly.
-/// </para>
-/// <para>
-/// All MCP sessions should be properly disposed after use as they implement <see cref="IAsyncDisposable"/>.
/// </para>
/// </remarks>
-public abstract partial class McpSession : IAsyncDisposable
+internal static class Experimentals
{
- /// <summary>Gets an identifier associated with the current MCP session.</summary>
- /// <remarks>
- /// Typically populated in transports supporting multiple sessions, such as Streamable HTTP or SSE.
- /// Can return <see langword="null"/> if the session hasn't initialized or if the transport doesn't
- /// support multiple sessions (as is the case with STDIO).
- /// </remarks>
- public abstract string? SessionId { get; }
-
/// <summary>
- /// Gets the negotiated protocol version for the current MCP session.
+ /// Diagnostic ID for the experimental MCP Tasks feature.
/// </summary>
- /// <remarks>
- /// Returns the protocol version negotiated during session initialization,
- /// or <see langword="null"/> if initialization hasn't yet occurred.
- /// </remarks>
-```
-
-This class is important because it defines how MCP C# SDK Tutorial: Production MCP in .NET with Hosting, ASP.NET Core, and Task Workflows implements the patterns covered in this chapter.
-
-### `src/ModelContextProtocol.Core/McpSession.cs`
+ public const string Tasks_DiagnosticId = "MCPEXP001";
-The `McpSession` class in [`src/ModelContextProtocol.Core/McpSession.cs`](https://github.com/modelcontextprotocol/csharp-sdk/blob/HEAD/src/ModelContextProtocol.Core/McpSession.cs) handles a key part of this chapter's functionality:
+ /// <summary>
+ /// Message for the experimental MCP Tasks feature.
+ /// </summary>
+ public const string Tasks_Message = "The Tasks feature is experimental per the MCP specification and is subject to change.";
-```cs
-/// </para>
-/// <para>
-/// <see cref="McpSession"/> serves as the base class for both <see cref="McpClient"/> and
-/// <see cref="McpServer"/>, providing the common functionality needed for MCP protocol
-/// communication. Most applications will use these more specific interfaces rather than working with
-/// <see cref="McpSession"/> directly.
-/// </para>
-/// <para>
-/// All MCP sessions should be properly disposed after use as they implement <see cref="IAsyncDisposable"/>.
-/// </para>
-/// </remarks>
-public abstract partial class McpSession : IAsyncDisposable
-{
- /// <summary>Gets an identifier associated with the current MCP session.</summary>
- /// <remarks>
- /// Typically populated in transports supporting multiple sessions, such as Streamable HTTP or SSE.
- /// Can return <see langword="null"/> if the session hasn't initialized or if the transport doesn't
- /// support multiple sessions (as is the case with STDIO).
- /// </remarks>
- public abstract string? SessionId { get; }
+ /// <summary>
+ /// URL for the experimental MCP Tasks feature.
+ /// </summary>
+ public const string Tasks_Url = "https://github.com/modelcontextprotocol/csharp-sdk/blob/main/docs/list-of-diagnostics.md#mcpexp001";
/// <summary>
- /// Gets the negotiated protocol version for the current MCP session.
+ /// Diagnostic ID for the experimental MCP Extensions feature.
/// </summary>
/// <remarks>
- /// Returns the protocol version negotiated during session initialization,
- /// or <see langword="null"/> if initialization hasn't yet occurred.
+ /// This uses the same diagnostic ID as <see cref="Tasks_DiagnosticId"/> because both
+ /// Tasks and Extensions are covered by the same MCPEXP001 diagnostic for experimental
+ /// MCP features. Having separate constants improves code clarity while maintaining a
+ /// single diagnostic suppression point.
/// </remarks>
- public abstract string? NegotiatedProtocolVersion { get; }
+ public const string Extensions_DiagnosticId = "MCPEXP001";
/// <summary>
- /// Sends a JSON-RPC request to the connected session and waits for a response.
+ /// Message for the experimental MCP Extensions feature.
```
This class is important because it defines how MCP C# SDK Tutorial: Production MCP in .NET with Hosting, ASP.NET Core, and Task Workflows implements the patterns covered in this chapter.
-### `src/ModelContextProtocol.Core/McpSession.cs`
+### `src/ModelContextProtocol.AspNetCore/SseHandler.cs`
-The `that` class in [`src/ModelContextProtocol.Core/McpSession.cs`](https://github.com/modelcontextprotocol/csharp-sdk/blob/HEAD/src/ModelContextProtocol.Core/McpSession.cs) handles a key part of this chapter's functionality:
+The `SseHandler` class in [`src/ModelContextProtocol.AspNetCore/SseHandler.cs`](https://github.com/modelcontextprotocol/csharp-sdk/blob/HEAD/src/ModelContextProtocol.AspNetCore/SseHandler.cs) handles a key part of this chapter's functionality:
```cs
- /// <remarks>
- /// This method provides low-level access to send raw JSON-RPC requests. For most use cases,
- /// consider using the strongly-typed methods that provide a more convenient API.
- /// </remarks>
- public abstract Task<JsonRpcResponse> SendRequestAsync(JsonRpcRequest request, CancellationToken cancellationToken = default);
+namespace ModelContextProtocol.AspNetCore;
+
+internal sealed class SseHandler(
+ IOptions<McpServerOptions> mcpServerOptionsSnapshot,
+ IOptionsFactory<McpServerOptions> mcpServerOptionsFactory,
+ IOptions<HttpServerTransportOptions> httpMcpServerOptions,
+ IHostApplicationLifetime hostApplicationLifetime,
+ ILoggerFactory loggerFactory)
+{
+ private readonly ConcurrentDictionary<string, SseSession> _sessions = new(StringComparer.Ordinal);
- /// <summary>
- /// Sends a JSON-RPC message to the connected session.
- /// </summary>
- /// <param name="message">
- /// The JSON-RPC message to send. This can be any type that implements JsonRpcMessage, such as
- /// JsonRpcRequest, JsonRpcResponse, JsonRpcNotification, or JsonRpcError.
- /// </param>
- /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
- /// <returns>A task that represents the asynchronous send operation.</returns>
- /// <exception cref="InvalidOperationException">The transport is not connected.</exception>
- /// <exception cref="ArgumentNullException"><paramref name="message"/> is <see langword="null"/>.</exception>
- /// <remarks>
- /// <para>
- /// This method provides low-level access to send any JSON-RPC message. For specific message types,
- /// consider using the higher-level methods such as <see cref="SendRequestAsync"/> or methods
- /// on this class that provide a simpler API.
- /// </para>
- /// <para>
- /// The method serializes the message and transmits it using the underlying transport mechanism.
- /// </para>
- /// </remarks>
- public abstract Task SendMessageAsync(JsonRpcMessage message, CancellationToken cancellationToken = default);
+ public async Task HandleSseRequestAsync(HttpContext context)
+ {
+ var sessionId = StreamableHttpHandler.MakeNewSessionId();
+
+ // If the server is shutting down, we need to cancel all SSE connections immediately without waiting for HostOptions.ShutdownTimeout
+ // which defaults to 30 seconds.
+ using var sseCts = CancellationTokenSource.CreateLinkedTokenSource(context.RequestAborted, hostApplicationLifetime.ApplicationStopping);
+ var cancellationToken = sseCts.Token;
+
+ StreamableHttpHandler.InitializeSseResponse(context);
- /// <summary>Registers a handler to be invoked when a notification for the specified method is received.</summary>
- /// <param name="method">The notification method.</param>
- /// <param name="handler">The handler to be invoked.</param>
+ var requestPath = (context.Request.PathBase + context.Request.Path).ToString();
+ var endpointPattern = requestPath[..(requestPath.LastIndexOf('/') + 1)];
+ await using var transport = new SseResponseStreamTransport(context.Response.Body, $"{endpointPattern}message?sessionId={sessionId}", sessionId);
+
+ var userIdClaim = StreamableHttpHandler.GetUserIdClaim(context.User);
+ var sseSession = new SseSession(transport, userIdClaim);
+
+ if (!_sessions.TryAdd(sessionId, sseSession))
+ {
+ throw new UnreachableException($"Unreachable given good entropy! Session with ID '{sessionId}' has already been created.");
```
This class is important because it defines how MCP C# SDK Tutorial: Production MCP in .NET with Hosting, ASP.NET Core, and Task Workflows implements the patterns covered in this chapter.
@@ -212,10 +210,10 @@ This class is important because it defines how MCP C# SDK Tutorial: Production M
```mermaid
flowchart TD
- A[SessionState]
- B[for]
- C[McpSession]
- D[that]
+ A[UnreferenceDisposable]
+ B[SessionState]
+ C[Experimentals]
+ D[SseHandler]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-docs-repo-tutorial/01-getting-started-and-archive-context.md b/tutorials/mcp-docs-repo-tutorial/01-getting-started-and-archive-context.md
index 4629cce7..ee6e563f 100644
--- a/tutorials/mcp-docs-repo-tutorial/01-getting-started-and-archive-context.md
+++ b/tutorials/mcp-docs-repo-tutorial/01-getting-started-and-archive-context.md
@@ -5,82 +5,106 @@ nav_order: 1
parent: MCP Docs Repo Tutorial
---
-
# Chapter 1: Getting Started and Archive Context
-Welcome to **Chapter 1: Getting Started and Archive Context**. In this part of **MCP Docs Repo Tutorial: Navigating the Archived MCP Documentation Repository**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
+This chapter defines the current role of the `modelcontextprotocol/docs` repository, why it is archived, and how teams should calibrate their trust in its content relative to the authoritative upstream source.
+## Learning Goals
-This chapter defines the current role of the archived docs repository.
+- Identify the archive status and practical implications for new MCP projects
+- Map when archived docs are useful versus when active docs are required
+- Avoid treating archived content as authoritative for recent protocol changes
+- Establish source-of-truth expectations across your engineering team
-## Learning Goals
+## What the Repository Is
-- identify the archive status and practical implications
-- map when archived docs are useful vs when active docs are required
-- avoid treating archived content as authoritative for new protocol changes
-- establish source-of-truth expectations for your team
+The `modelcontextprotocol/docs` repository is an **archived** snapshot of the Mintlify-hosted MCP documentation site. It captured the documentation as it existed when the content was migrated to the canonical `modelcontextprotocol/modelcontextprotocol` monorepo. The repo is read-only — no new issues, pull requests, or releases are accepted here.
-## Source References
+The live documentation website at `modelcontextprotocol.io` is now driven by the monorepo. The archived repo preserves the Mintlify site structure (`.mdx` pages, `docs.json` navigation config, image assets) for reference and historical study.
-- [Docs Repository README](https://github.com/modelcontextprotocol/docs/blob/main/README.md)
-- [Canonical Docs Location](https://github.com/modelcontextprotocol/modelcontextprotocol/tree/main/docs)
+## Archive Status Decision Tree
-## Summary
+```mermaid
+flowchart TD
+ Q1{Is your question about\ncurrent MCP protocol behavior?}
+ Q1 -- Yes --> ACTIVE[Use modelcontextprotocol/modelcontextprotocol\nand the live docs site]
+ Q1 -- No --> Q2{Is this a historical reference,\ncontext, or terminology check?}
+ Q2 -- Yes --> ARCHIVE[Archived docs are appropriate\nfor background context]
+ Q2 -- No --> Q3{Are you building a migration\nguide or auditing old content?}
+ Q3 -- Yes --> BOTH[Use archived docs to identify\ndiffs; confirm with active docs]
+ Q3 -- No --> ACTIVE
+```
-You now have a clear scope boundary for using archived docs safely.
+## Source-of-Truth Map
-Next: [Chapter 2: Repository Layout and Canonical Migration Path](02-repository-layout-and-canonical-migration-path.md)
+| Resource | Status | Use Case |
+|:---------|:-------|:---------|
+| `modelcontextprotocol/docs` (this repo) | Archived | Historical reference, migration auditing |
+| `modelcontextprotocol/modelcontextprotocol/docs` | Active | Protocol spec, concepts, current guidance |
+| `modelcontextprotocol.io` (live site) | Active | End-user and developer documentation |
+| SDK repositories (`python-sdk`, `typescript-sdk`) | Active | Language-specific implementation guides |
+
+## Repository File Layout
+
+The archive preserves the full Mintlify project structure:
-## Source Code Walkthrough
-
-### `docs.json`
-
-The `docs` module in [`docs.json`](https://github.com/modelcontextprotocol/docs/blob/HEAD/docs.json) handles a key part of this chapter's functionality:
-
-```json
-{
- "$schema": "https://mintlify.com/docs.json",
- "theme": "willow",
- "name": "Model Context Protocol",
- "colors": {
- "primary": "#09090b",
- "light": "#FAFAFA",
- "dark": "#09090b"
- },
- "favicon": "/favicon.svg",
- "navigation": {
- "tabs": [
- {
- "tab": "Documentation",
- "groups": [
- {
- "group": "Get Started",
- "pages": [
- "introduction",
- {
- "group": "Quickstart",
- "pages": [
- "quickstart/server",
- "quickstart/client",
- "quickstart/user"
- ]
- },
- "examples",
- "clients"
- ]
- },
- {
- "group": "Tutorials",
- "pages": [
- "tutorials/building-mcp-with-llms",
```
+docs/ # conceptual guides (architecture, tools, resources, etc.)
+quickstart/ # user/server/client onboarding flows
+tutorials/ # building MCP servers and clients
+development/ # roadmap and update history
+docs.json # Mintlify site navigation configuration
+introduction.mdx # top-level introduction page
+clients.mdx # client ecosystem compatibility matrix
+examples.mdx # reference example index
+```
+
+## Why the Archive Matters
+
+Even though the repository is frozen, the content has high value for several use cases:
-This module is important because it defines how MCP Docs Repo Tutorial: Navigating the Archived MCP Documentation Repository implements the patterns covered in this chapter.
+1. **Conceptual grounding** — The `docs/concepts/` pages (architecture, tools, resources, prompts, transports, sampling, roots) provide stable conceptual prose that complements the protocol specification.
+2. **Onboarding history** — The `quickstart/` flows capture patterns that many existing tutorials and blog posts reference.
+3. **Client ecosystem context** — `clients.mdx` contains a client feature matrix useful for compatibility planning.
+4. **Migration source** — Teams moving internal docs from the old site structure benefit from having this reference.
+## What the Archive Does Not Cover
-## How These Components Connect
+- Protocol changes after the migration cutoff date
+- New SDK features (Python, TypeScript, Java, etc.)
+- Updated transport specifications (StreamableHTTP was added post-migration)
+- Security advisories or breaking changes published post-archive
+
+## Repository Content Diagram
```mermaid
-flowchart TD
- A[docs]
+graph LR
+ ROOT[modelcontextprotocol/docs]
+ ROOT --> CONCEPTS[docs/concepts/\narchitecture · tools · resources\nprompts · transports · sampling · roots]
+ ROOT --> QUICK[quickstart/\nuser · server · client]
+ ROOT --> TOOLS[docs/tools/\ndebugging · inspector]
+ ROOT --> DEV[development/\nroadmap · updates · contributing]
+ ROOT --> TUT[tutorials/\nbuilding-a-client-node\nbuilding-mcp-with-llms]
+ ROOT --> META[docs.json · clients.mdx\nexamples.mdx · introduction.mdx]
```
+
+## Practical Onboarding Checklist
+
+Before using archived docs in your project or team:
+
+- [ ] Confirm you have the active docs URL bookmarked (`modelcontextprotocol.io`)
+- [ ] Identify which sections of the archive you need (concepts, quickstart, tooling)
+- [ ] Flag any links or commands you extract with an "archived — verify against active docs" annotation
+- [ ] Set a team policy: archived docs are read-only reference, never source-of-truth for protocol behavior
+
+## Source References
+
+- [Docs Repository README](https://github.com/modelcontextprotocol/docs/blob/main/README.md)
+- [Canonical Docs Location (Active)](https://github.com/modelcontextprotocol/modelcontextprotocol/tree/main/docs)
+- [Mintlify Navigation Config](https://github.com/modelcontextprotocol/docs/blob/main/docs.json)
+
+## Summary
+
+The `modelcontextprotocol/docs` repo is a frozen Mintlify site snapshot. Its conceptual guides, quickstart flows, client matrix, and tooling docs retain high reference value — but all protocol-behavior questions and new development should reference the active canonical source. Set this expectation explicitly with your team before pointing anyone at archived content.
+
+Next: [Chapter 2: Repository Layout and Canonical Migration Path](02-repository-layout-and-canonical-migration-path.md)
diff --git a/tutorials/mcp-docs-repo-tutorial/02-repository-layout-and-canonical-migration-path.md b/tutorials/mcp-docs-repo-tutorial/02-repository-layout-and-canonical-migration-path.md
index 577f5613..b4c3eb4f 100644
--- a/tutorials/mcp-docs-repo-tutorial/02-repository-layout-and-canonical-migration-path.md
+++ b/tutorials/mcp-docs-repo-tutorial/02-repository-layout-and-canonical-migration-path.md
@@ -5,92 +5,152 @@ nav_order: 2
parent: MCP Docs Repo Tutorial
---
-
# Chapter 2: Repository Layout and Canonical Migration Path
-Welcome to **Chapter 2: Repository Layout and Canonical Migration Path**. In this part of **MCP Docs Repo Tutorial: Navigating the Archived MCP Documentation Repository**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
-
-
-This chapter maps content areas and migration strategy between archived and active docs repositories.
+This chapter maps every content area in the archived docs repository, explains its function, and gives a concrete migration checklist for teams who need to move internal documentation links from this archive to the active canonical source.
## Learning Goals
-- navigate major content areas (concepts, quickstarts, tools, tutorials)
-- decide migration priorities for internal documentation links
-- reduce broken references during docs transitions
-- keep teams aligned on active update channels
-
-## Layout Overview
-
-| Area | Use Today |
-|:-----|:----------|
-| quickstart/ | historical onboarding reference |
-| docs/concepts/ | conceptual background and terminology |
-| docs/tools/ | practical debugging and inspector guidance |
-| development/ | historical roadmap/update context |
-
-## Source References
-
-- [Introduction](https://github.com/modelcontextprotocol/docs/blob/main/introduction.mdx)
-- [Development Roadmap](https://github.com/modelcontextprotocol/docs/blob/main/development/roadmap.mdx)
-- [Development Updates](https://github.com/modelcontextprotocol/docs/blob/main/development/updates.mdx)
-
-## Summary
-
-You now have a migration-aware map of archived docs content.
-
-Next: [Chapter 3: Quickstart Flows: User, Server, and Client](03-quickstart-flows-user-server-and-client.md)
+- Navigate the major content areas: concepts, quickstarts, tools, tutorials, SDK docs
+- Decide migration priorities when updating internal documentation links
+- Reduce broken references during documentation transitions
+- Keep teams aligned on active update channels and file naming conventions
-## Source Code Walkthrough
+## Full Content Map
-### `docs.json`
+```mermaid
+graph TD
+ ROOT[modelcontextprotocol/docs root]
+
+ ROOT --> INTRO[introduction.mdx\nTop-level entry point]
+ ROOT --> CLIENTS[clients.mdx\nClient feature matrix]
+ ROOT --> EXAMPLES[examples.mdx\nReference example index]
+
+ ROOT --> QS[quickstart/]
+ QS --> QSU[user.mdx]
+ QS --> QSS[server.mdx]
+ QS --> QSC[client.mdx]
+
+ ROOT --> CONCEPTS[docs/concepts/]
+ CONCEPTS --> CA[architecture.mdx]
+ CONCEPTS --> CT[tools.mdx]
+ CONCEPTS --> CR[resources.mdx]
+ CONCEPTS --> CP[prompts.mdx]
+ CONCEPTS --> CTRANS[transports.mdx]
+ CONCEPTS --> CS[sampling.mdx]
+ CONCEPTS --> CRO[roots.mdx]
+
+ ROOT --> TOOLING[docs/tools/]
+ TOOLING --> TI[inspector.mdx]
+ TOOLING --> TD[debugging.mdx]
+
+ ROOT --> DEV[development/]
+ DEV --> DR[roadmap.mdx]
+ DEV --> DU[updates.mdx]
+ DEV --> DC[contributing.mdx]
+
+ ROOT --> TUT[tutorials/]
+ TUT --> TN[building-a-client-node.mdx]
+ TUT --> TL[building-mcp-with-llms.mdx]
+
+ ROOT --> SDK[sdk/java/]
+ SDK --> SJO[mcp-overview.mdx]
+ SDK --> SJC[mcp-client.mdx]
+ SDK --> SJS[mcp-server.mdx]
+```
-The `docs` module in [`docs.json`](https://github.com/modelcontextprotocol/docs/blob/HEAD/docs.json) handles a key part of this chapter's functionality:
+## Content Area Reference Table
+
+| Area | Path | Historical Use | Active Replacement |
+|:-----|:-----|:---------------|:-------------------|
+| Introduction | `introduction.mdx` | Entry-point prose | `modelcontextprotocol/modelcontextprotocol/docs` |
+| Client Matrix | `clients.mdx` | Ecosystem compatibility | Active `clients.mdx` in monorepo |
+| Examples | `examples.mdx` | Reference example index | Active `examples.mdx` in monorepo |
+| Quickstart: User | `quickstart/user.mdx` | End-user setup | Active quickstart in monorepo |
+| Quickstart: Server | `quickstart/server.mdx` | Server onboarding | Active quickstart in monorepo |
+| Quickstart: Client | `quickstart/client.mdx` | Client onboarding | Active quickstart in monorepo |
+| Architecture | `docs/concepts/architecture.mdx` | Protocol lifecycle model | Active concepts in monorepo |
+| Tools | `docs/concepts/tools.mdx` | Tool primitive semantics | Active concepts in monorepo |
+| Resources | `docs/concepts/resources.mdx` | Resource model | Active concepts in monorepo |
+| Prompts | `docs/concepts/prompts.mdx` | Prompt primitive | Active concepts in monorepo |
+| Transports | `docs/concepts/transports.mdx` | Transport options | Active concepts (includes StreamableHTTP) |
+| Sampling | `docs/concepts/sampling.mdx` | Human-in-the-loop model | Active concepts in monorepo |
+| Roots | `docs/concepts/roots.mdx` | Context boundary model | Active concepts in monorepo |
+| Inspector | `docs/tools/inspector.mdx` | Inspector usage | Active tooling docs in monorepo |
+| Debugging | `docs/tools/debugging.mdx` | Claude Desktop debugging | Active tooling docs in monorepo |
+| Roadmap | `development/roadmap.mdx` | Historical roadmap | GitHub Discussions / Issues |
+| Updates | `development/updates.mdx` | Changelog history | GitHub releases |
+| Contributing | `development/contributing.mdx` | Contribution guide | `CONTRIBUTING.md` in monorepo |
+| Node Client Tutorial | `tutorials/building-a-client-node.mdx` | TypeScript client guide | Active TypeScript SDK docs |
+| LLM-assisted Building | `tutorials/building-mcp-with-llms.mdx` | LLM-aided server building | Active tutorial in monorepo |
+| Java Overview | `sdk/java/mcp-overview.mdx` | Java SDK overview | Java SDK repository |
+
+## Mintlify Navigation Config (`docs.json`)
+
+The `docs.json` file is the Mintlify site configuration — it controls navigation tabs, page groupings, and sidebar ordering. This is **not** a runtime config or a protocol file; it is purely the documentation site's CMS configuration.
```json
{
"$schema": "https://mintlify.com/docs.json",
"theme": "willow",
"name": "Model Context Protocol",
- "colors": {
- "primary": "#09090b",
- "light": "#FAFAFA",
- "dark": "#09090b"
- },
- "favicon": "/favicon.svg",
"navigation": {
"tabs": [
{
"tab": "Documentation",
"groups": [
- {
- "group": "Get Started",
- "pages": [
- "introduction",
- {
- "group": "Quickstart",
- "pages": [
- "quickstart/server",
- "quickstart/client",
- "quickstart/user"
- ]
- },
- "examples",
- "clients"
- ]
- },
- {
- "group": "Tutorials",
- "pages": [
- "tutorials/building-mcp-with-llms",
+ { "group": "Get Started", "pages": ["introduction", "quickstart/server", ...] },
+ { "group": "Concepts", "pages": ["docs/concepts/architecture", ...] },
+ { "group": "Tutorials", "pages": ["tutorials/building-mcp-with-llms", ...] }
+ ]
+ },
+ { "tab": "SDKs", ... },
+ { "tab": "Tools", ... }
+ ]
+ }
+}
```
-This module is important because it defines how MCP Docs Repo Tutorial: Navigating the Archived MCP Documentation Repository implements the patterns covered in this chapter.
+Key `docs.json` facts:
+- `"theme": "willow"` — Mintlify theme, has no protocol significance
+- Navigation order reflects the original documentation hierarchy
+- Tab groupings show how content was categorized for end-users
+- Useful for auditing which pages existed and what order they appeared in
+## Migration Priority Framework
-## How These Components Connect
+When migrating internal links from this archive to active documentation:
```mermaid
-flowchart TD
- A[docs]
+flowchart LR
+ A[Identify archived link] --> B{Is this a concept\nor protocol explanation?}
+ B -- Yes --> C[High priority:\nUpdate to active monorepo link]
+ B -- No --> D{Is it a quickstart\nor tutorial?}
+ D -- Yes --> E[High priority:\nActive docs have updated versions]
+ D -- No --> F{Is it roadmap/updates\nor historical context?}
+ F -- Yes --> G[Low priority:\nCan remain as archive reference]
+ F -- Historical --> H[Keep as-is with archive annotation]
```
+
+### Migration Checklist
+
+- [ ] Audit all internal documentation for `github.com/modelcontextprotocol/docs` links
+- [ ] Replace concept page links with monorepo equivalents
+- [ ] Replace quickstart links — note that the server quickstart now includes multiple language tabs
+- [ ] Replace tooling links — inspector and debugging pages have been updated with new screenshots
+- [ ] Archive historical context links (roadmap, updates) with a note that they are frozen
+- [ ] Verify that Java SDK links point to the `modelcontextprotocol/java-sdk` repository, not this archive
+
+## Source References
+
+- [Introduction](https://github.com/modelcontextprotocol/docs/blob/main/introduction.mdx)
+- [Development Roadmap](https://github.com/modelcontextprotocol/docs/blob/main/development/roadmap.mdx)
+- [Development Updates](https://github.com/modelcontextprotocol/docs/blob/main/development/updates.mdx)
+- [docs.json Navigation Config](https://github.com/modelcontextprotocol/docs/blob/main/docs.json)
+- [Active Canonical Docs](https://github.com/modelcontextprotocol/modelcontextprotocol/tree/main/docs)
+
+## Summary
+
+Every file in the archived repo has a direct counterpart in the active monorepo. The `docs.json` config is a Mintlify site artifact (not a protocol file) that maps the original navigation hierarchy — useful for auditing coverage during migration but irrelevant to protocol behavior. Use the content area table and migration checklist above to methodically transition any internal documentation that references this archive.
+
+Next: [Chapter 3: Quickstart Flows: User, Server, and Client](03-quickstart-flows-user-server-and-client.md)
diff --git a/tutorials/mcp-docs-repo-tutorial/03-quickstart-flows-user-server-and-client.md b/tutorials/mcp-docs-repo-tutorial/03-quickstart-flows-user-server-and-client.md
index 04b72589..6d08fe07 100644
--- a/tutorials/mcp-docs-repo-tutorial/03-quickstart-flows-user-server-and-client.md
+++ b/tutorials/mcp-docs-repo-tutorial/03-quickstart-flows-user-server-and-client.md
@@ -5,83 +5,159 @@ nav_order: 3
parent: MCP Docs Repo Tutorial
---
-
# Chapter 3: Quickstart Flows: User, Server, and Client
-Welcome to **Chapter 3: Quickstart Flows: User, Server, and Client**. In this part of **MCP Docs Repo Tutorial: Navigating the Archived MCP Documentation Repository**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
+This chapter examines the three onboarding paths preserved in the archived quickstart section: the user flow (connecting an MCP server to Claude Desktop), the server flow (building and running a Python server), and the client flow (building a TypeScript MCP client).
+## Learning Goals
-This chapter highlights onboarding flows preserved in archived quickstart docs.
+- Compare user, server, and client onboarding paths and their distinct audiences
+- Identify reusable setup and troubleshooting patterns across runtimes
+- Use archived quickstart content as baseline context when reviewing active doc updates
+- Avoid outdated command and configuration assumptions from the frozen content
-## Learning Goals
+## The Three Quickstart Audiences
-- compare user, server, and client onboarding paths
-- identify reusable setup/troubleshooting patterns across runtimes
-- use quickstart material as baseline context for active docs updates
-- avoid outdated command/config assumptions
+```mermaid
+graph LR
+ QS[Quickstart Flows]
+ QS --> USER[User Quickstart\nquickstart/user.mdx\nAudience: non-developer end-users]
+ QS --> SERVER[Server Quickstart\nquickstart/server.mdx\nAudience: server implementors]
+ QS --> CLIENT[Client Quickstart\nquickstart/client.mdx\nAudience: client/host developers]
+
+ USER --> UD[Goal: connect an MCP server\nto Claude Desktop with no code]
+ SERVER --> SD[Goal: build a Python server\nwith tools, resources, prompts]
+ CLIENT --> CD[Goal: build a TypeScript client\nthat calls MCP servers]
+```
-## Source References
+## User Quickstart (`quickstart/user.mdx`)
-- [Quickstart: User](https://github.com/modelcontextprotocol/docs/blob/main/quickstart/user.mdx)
-- [Quickstart: Server](https://github.com/modelcontextprotocol/docs/blob/main/quickstart/server.mdx)
-- [Quickstart: Client](https://github.com/modelcontextprotocol/docs/blob/main/quickstart/client.mdx)
+The user quickstart targets non-developers who want to use an existing MCP server — specifically the `filesystem` server bundled with Claude Desktop.
-## Summary
+Key steps preserved in this flow:
+1. Install Claude Desktop (macOS or Windows)
+2. Open `claude_desktop_config.json` and add an entry under `mcpServers`
+3. Restart Claude Desktop
+4. Verify the MCP hammer icon appears in the UI
+5. Invoke a tool call in conversation
-You now have a quickstart-oriented onboarding map for archived MCP docs.
+Example config snippet from the archived page:
+```json
+{
+ "mcpServers": {
+ "filesystem": {
+ "command": "npx",
+ "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/Desktop"]
+ }
+ }
+}
+```
-Next: [Chapter 4: Core Concepts: Architecture, Tools, Resources, Prompts](04-core-concepts-architecture-tools-resources-prompts.md)
+**Archive note**: The `npx -y` pattern and config path remain valid in the active docs. The filesystem server package name is unchanged.
-## Source Code Walkthrough
+## Server Quickstart (`quickstart/server.mdx`)
-### `docs.json`
+The server quickstart walks a developer through building a minimal "weather" MCP server in Python using the `mcp` SDK. This was the primary onboarding path for Python server developers.
-The `docs` module in [`docs.json`](https://github.com/modelcontextprotocol/docs/blob/HEAD/docs.json) handles a key part of this chapter's functionality:
+Typical flow:
+1. Install `uv` package manager
+2. Create project with `uv init` and add `mcp[cli]` dependency
+3. Define a tool using `@mcp.tool()` decorator
+4. Register a resource with `@mcp.resource()`
+5. Run with `mcp dev server.py` for inspector testing
+6. Add to Claude Desktop config
-```json
-{
- "$schema": "https://mintlify.com/docs.json",
- "theme": "willow",
- "name": "Model Context Protocol",
- "colors": {
- "primary": "#09090b",
- "light": "#FAFAFA",
- "dark": "#09090b"
- },
- "favicon": "/favicon.svg",
- "navigation": {
- "tabs": [
- {
- "tab": "Documentation",
- "groups": [
- {
- "group": "Get Started",
- "pages": [
- "introduction",
- {
- "group": "Quickstart",
- "pages": [
- "quickstart/server",
- "quickstart/client",
- "quickstart/user"
- ]
- },
- "examples",
- "clients"
- ]
- },
- {
- "group": "Tutorials",
- "pages": [
- "tutorials/building-mcp-with-llms",
+```python
+# Pattern from archived server quickstart
+import mcp.server.fastmcp as fastmcp
+
+mcp = fastmcp.FastMCP("weather")
+
+@mcp.tool()
+async def get_current_weather(city: str) -> str:
+ """Get current weather for a city."""
+ # implementation
+ return f"Weather for {city}: 72F, sunny"
+
+if __name__ == "__main__":
+ mcp.run()
+```
+
+**Archive note**: The `FastMCP` decorator API is still the recommended path in active docs. The `mcp dev` command (MCP CLI) is a current tool.
+
+## Client Quickstart (`quickstart/client.mdx`)
+
+The client quickstart shows how to connect to any MCP server via TypeScript using the `@modelcontextprotocol/sdk` package.
+
+Core pattern:
+1. Install `@modelcontextprotocol/sdk`
+2. Instantiate a `Client` with capability declarations
+3. Connect via `StdioClientTransport` (stdio-based server)
+4. Call `listTools()` then `callTool()`
+5. Handle structured results
+
+```typescript
+// Pattern from archived client quickstart
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+
+const client = new Client({ name: "my-client", version: "1.0.0" });
+const transport = new StdioClientTransport({
+ command: "python",
+ args: ["server.py"]
+});
+
+await client.connect(transport);
+const tools = await client.listTools();
+const result = await client.callTool({ name: "get_current_weather", arguments: { city: "NYC" } });
```
-This module is important because it defines how MCP Docs Repo Tutorial: Navigating the Archived MCP Documentation Repository implements the patterns covered in this chapter.
+**Archive note**: The TypeScript SDK import paths changed significantly in v2 (the split-package model). The active docs cover the new import paths. Do not use the archived import paths for new projects.
+
+## Quickstart Content Comparison
+
+| Dimension | User | Server | Client |
+|:----------|:-----|:-------|:-------|
+| Audience | End-user | Backend developer | Client/host developer |
+| Language | No code | Python | TypeScript |
+| Transport | Stdio (Claude Desktop) | Stdio | Stdio (dev) |
+| Primary artifact | Config file | `server.py` | `client.ts` |
+| Archive relevance | High — config format is stable | High — FastMCP API is current | Medium — import paths changed in v2 |
+## What Changed After the Archive Cutoff
-## How These Components Connect
+The server quickstart in active docs now covers multiple languages (Python, TypeScript, Java) in tabbed views. The archived page is Python-only. If you are directing a TypeScript or Java server developer, send them to the active docs.
+
+The client quickstart in active docs reflects the v2 TypeScript SDK with the split-package model (`@modelcontextprotocol/client`). The archived page uses the v1 monolithic import path.
```mermaid
flowchart TD
- A[docs]
+ ARCH[Archived Quickstart]
+ ARCH --> PY[Python server only\nMonolithic TS SDK imports\nStdio transport focus]
+
+ ACTIVE[Active Quickstart]
+ ACTIVE --> MULTI[Python + TypeScript + Java servers\nSplit-package TS SDK\nStreamableHTTP transport included]
+
+ ARCH -.->|migration target| ACTIVE
```
+
+## Reusable Patterns from the Archives
+
+Despite the staleness of specific commands, these patterns from the archived quickstarts remain valid:
+
+- The `claude_desktop_config.json` schema (`mcpServers`, `command`, `args`, `env`)
+- The separation of concerns: hosts configure servers, servers implement primitives, clients call them
+- The `mcp dev <server.py>` development workflow
+- The three-primitive model: tools (callable), resources (readable), prompts (templatable)
+
+## Source References
+
+- [Quickstart: User](https://github.com/modelcontextprotocol/docs/blob/main/quickstart/user.mdx)
+- [Quickstart: Server](https://github.com/modelcontextprotocol/docs/blob/main/quickstart/server.mdx)
+- [Quickstart: Client](https://github.com/modelcontextprotocol/docs/blob/main/quickstart/client.mdx)
+
+## Summary
+
+The three archived quickstart flows each target a distinct audience. The user flow (Claude Desktop config) remains highly accurate. The server flow (Python + FastMCP) is current. The client flow's TypeScript import paths are outdated for v2 SDK users. Extract patterns and conceptual flows from the archive, but verify specific commands and import paths against active documentation before using them in new projects.
+
+Next: [Chapter 4: Core Concepts: Architecture, Tools, Resources, Prompts](04-core-concepts-architecture-tools-resources-prompts.md)
diff --git a/tutorials/mcp-docs-repo-tutorial/04-core-concepts-architecture-tools-resources-prompts.md b/tutorials/mcp-docs-repo-tutorial/04-core-concepts-architecture-tools-resources-prompts.md
index 6efcd696..6b9aef10 100644
--- a/tutorials/mcp-docs-repo-tutorial/04-core-concepts-architecture-tools-resources-prompts.md
+++ b/tutorials/mcp-docs-repo-tutorial/04-core-concepts-architecture-tools-resources-prompts.md
@@ -5,84 +5,165 @@ nav_order: 4
parent: MCP Docs Repo Tutorial
---
-
# Chapter 4: Core Concepts: Architecture, Tools, Resources, Prompts
-Welcome to **Chapter 4: Core Concepts: Architecture, Tools, Resources, Prompts**. In this part of **MCP Docs Repo Tutorial: Navigating the Archived MCP Documentation Repository**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
+This chapter examines the four foundational conceptual guides in `docs/concepts/`: architecture, tools, resources, and prompts. These pages provide the most stable content in the archive — the underlying protocol model has not fundamentally changed even after the migration cutoff.
+## Learning Goals
-This chapter focuses on foundational conceptual guides that remain broadly useful.
+- Refresh the protocol architecture and lifecycle model from the archived concepts
+- Align tool, resource, and prompt semantics across implementations and teams
+- Apply concept docs when reviewing SDK-specific behavior or writing integration tests
+- Avoid conceptual drift in internal documentation and team onboarding materials
-## Learning Goals
+## Architecture (`docs/concepts/architecture.mdx`)
-- refresh protocol architecture and lifecycle model
-- align tool/resource/prompt semantics across implementations
-- apply concept docs when reviewing SDK-specific behavior
-- avoid conceptual drift in internal docs and team onboarding
+The architecture concept page describes the three-role model that underlies every MCP interaction.
-## Source References
+```mermaid
+graph LR
+ HOST[Host\ne.g., Claude Desktop\nCursor IDE]
+ CLIENT[MCP Client\nembedded in Host]
+ SERVER[MCP Server\nprovides capabilities]
+
+ HOST --> CLIENT
+ CLIENT <-->|MCP protocol\njson-rpc 2.0| SERVER
+ SERVER --> CAP[Capabilities:\nTools · Resources · Prompts]
+```
-- [Architecture Concepts](https://github.com/modelcontextprotocol/docs/blob/main/docs/concepts/architecture.mdx)
-- [Tools Concepts](https://github.com/modelcontextprotocol/docs/blob/main/docs/concepts/tools.mdx)
-- [Resources Concepts](https://github.com/modelcontextprotocol/docs/blob/main/docs/concepts/resources.mdx)
-- [Prompts Concepts](https://github.com/modelcontextprotocol/docs/blob/main/docs/concepts/prompts.mdx)
+Key points from the archived architecture doc:
+- **Host**: The application the end-user runs (Claude Desktop, an IDE). Embeds one or more clients.
+- **Client**: Manages a single connection to one server. Handles capability negotiation.
+- **Server**: Exposes tools, resources, and/or prompts. Stateless or stateful depending on implementation.
+- **Connection lifecycle**: Initialize → capability exchange → request/response loop → shutdown.
-## Summary
+The JSON-RPC 2.0 message format is the wire protocol for all exchanges:
+```json
+{ "jsonrpc": "2.0", "method": "tools/call", "params": { "name": "...", "arguments": {} }, "id": 1 }
+```
-You now have a concept-level baseline for MCP system reasoning.
+## Tools (`docs/concepts/tools.mdx`)
-Next: [Chapter 5: Advanced Concepts: Transports, Sampling, and Roots](05-advanced-concepts-transports-sampling-and-roots.md)
+Tools are callable functions exposed by a server. A tool has a name, an optional description, and a JSON Schema input definition. The LLM decides when to invoke a tool; the host confirms (in hosts that require approval).
-## Source Code Walkthrough
+```mermaid
+sequenceDiagram
+ participant LLM
+ participant Host
+ participant Client
+ participant Server
+
+ LLM->>Host: I want to call tool X with args Y
+ Host->>Host: (optional) user approval
+ Host->>Client: callTool(X, Y)
+ Client->>Server: tools/call {name: X, arguments: Y}
+ Server-->>Client: result content
+ Client-->>Host: result
+ Host-->>LLM: tool result injected into context
+```
-### `docs.json`
+Tool registration pattern (from archived Python examples):
+```python
+@mcp.tool()
+async def search_documents(query: str, limit: int = 10) -> list[dict]:
+ """Search the document store for relevant results."""
+ return await db.search(query, limit=limit)
+```
-The `docs` module in [`docs.json`](https://github.com/modelcontextprotocol/docs/blob/HEAD/docs.json) handles a key part of this chapter's functionality:
+Key tool design principles from the archived concepts:
+- Tools should be **idempotent** where possible; document side effects clearly
+- Descriptions drive LLM selection — write them as instructions, not just labels
+- Input schemas should be strict — required fields, typed properties, clear descriptions
-```json
-{
- "$schema": "https://mintlify.com/docs.json",
- "theme": "willow",
- "name": "Model Context Protocol",
- "colors": {
- "primary": "#09090b",
- "light": "#FAFAFA",
- "dark": "#09090b"
- },
- "favicon": "/favicon.svg",
- "navigation": {
- "tabs": [
- {
- "tab": "Documentation",
- "groups": [
- {
- "group": "Get Started",
- "pages": [
- "introduction",
- {
- "group": "Quickstart",
- "pages": [
- "quickstart/server",
- "quickstart/client",
- "quickstart/user"
- ]
- },
- "examples",
- "clients"
- ]
- },
- {
- "group": "Tutorials",
- "pages": [
- "tutorials/building-mcp-with-llms",
+## Resources (`docs/concepts/resources.mdx`)
+
+Resources are URI-addressed data blobs that a server exposes for a client to read. Unlike tools (which are invoked), resources are fetched. Resources can be static (files, database rows) or dynamic (live feeds, computed views).
+
+```mermaid
+graph LR
+ CLIENT[Client]
+ CLIENT -->|resources/list| SERVER[Server]
+ SERVER -->|resource URIs| CLIENT
+ CLIENT -->|resources/read\nuri: file:///notes/1| SERVER
+ SERVER -->|content blob| CLIENT
+
+ SERVER --> SUBS[Optional:\nresources/subscribe\nfor change notifications]
+```
+
+Resource URI scheme (from archived examples):
+```
+file:///path/to/file # file system resources
+note:///notes/{id} # application-defined scheme
+db:///table/{row_id} # database record resource
+```
+
+Resources return content blobs typed as `text/plain`, `application/json`, `image/*`, etc. The client and host decide how to inject resource content into the LLM context — a resource itself has no say in this.
+
+## Prompts (`docs/concepts/prompts.mdx`)
+
+Prompts are server-defined message templates with typed arguments. They allow servers to package reusable prompt structures that clients can render in conversation context. Unlike tools, prompts are not executed server-side; they return message content for the client to use.
+
+```mermaid
+sequenceDiagram
+ participant User
+ participant Host
+ participant Client
+ participant Server
+
+ User->>Host: Select "summarize" prompt
+ Host->>Client: getPrompt("summarize", {document: "..."})
+ Client->>Server: prompts/get {name: "summarize", arguments: {document: "..."}}
+ Server-->>Client: messages array
+ Client-->>Host: rendered messages
+ Host->>Host: inject into conversation context
```
-This module is important because it defines how MCP Docs Repo Tutorial: Navigating the Archived MCP Documentation Repository implements the patterns covered in this chapter.
+Prompt definition pattern (from archived examples):
+```python
+@mcp.prompt()
+def summarize_document(document: str) -> list[Message]:
+ """Generate a document summary."""
+ return [
+ UserMessage(f"Please summarize the following document:\n\n{document}")
+ ]
+```
+Prompts are registered with argument schemas and descriptions, enabling UIs to build dynamic forms for prompt parameterization.
-## How These Components Connect
+## The Three Primitives Together
```mermaid
-flowchart TD
- A[docs]
+graph TD
+ SERVER[MCP Server]
+ SERVER --> TOOLS[Tools\nCallable functions\nLLM decides when to call\nSide-effectful OK]
+ SERVER --> RESOURCES[Resources\nURI-addressed data\nClient reads on demand\nStateless reads]
+ SERVER --> PROMPTS[Prompts\nMessage templates\nUser/UI selects\nReturns messages, not execution]
+
+ TOOLS --> EX1[search_documents\nrun_query\ncreate_issue]
+ RESOURCES --> EX2[file:///notes/1\ndb:///users/42\nnotes:///list]
+ PROMPTS --> EX3[summarize_document\ngenerate_pr_description\nexplain_code]
```
+
+## Concept Stability Assessment
+
+The archived concept docs are the most stable content in the repo. The three-primitive model (tools/resources/prompts) and the three-role architecture (host/client/server) are unchanged in the active protocol.
+
+| Concept Area | Archive Accuracy | What Changed |
+|:-------------|:-----------------|:-------------|
+| Architecture model | High | Elicitation added post-archive |
+| Tool semantics | High | Output schemas added post-archive |
+| Resource model | High | Resource size field added post-archive |
+| Prompt model | High | No significant changes |
+
+## Source References
+
+- [Architecture Concepts](https://github.com/modelcontextprotocol/docs/blob/main/docs/concepts/architecture.mdx)
+- [Tools Concepts](https://github.com/modelcontextprotocol/docs/blob/main/docs/concepts/tools.mdx)
+- [Resources Concepts](https://github.com/modelcontextprotocol/docs/blob/main/docs/concepts/resources.mdx)
+- [Prompts Concepts](https://github.com/modelcontextprotocol/docs/blob/main/docs/concepts/prompts.mdx)
+
+## Summary
+
+The four core concept pages are the most reliable content in the archive. Architecture, tool, resource, and prompt semantics are foundational and largely unchanged. Use these pages for team onboarding, internal glossary definitions, and as a reference when reviewing implementation behavior — but check the active docs for any additions (output schemas, elicitation, resource size hints) added after the archive cutoff.
+
+Next: [Chapter 5: Advanced Concepts: Transports, Sampling, and Roots](05-advanced-concepts-transports-sampling-and-roots.md)
diff --git a/tutorials/mcp-docs-repo-tutorial/05-advanced-concepts-transports-sampling-and-roots.md b/tutorials/mcp-docs-repo-tutorial/05-advanced-concepts-transports-sampling-and-roots.md
index e6aeb0f6..dfd774af 100644
--- a/tutorials/mcp-docs-repo-tutorial/05-advanced-concepts-transports-sampling-and-roots.md
+++ b/tutorials/mcp-docs-repo-tutorial/05-advanced-concepts-transports-sampling-and-roots.md
@@ -5,83 +5,166 @@ nav_order: 5
parent: MCP Docs Repo Tutorial
---
-
# Chapter 5: Advanced Concepts: Transports, Sampling, and Roots
-Welcome to **Chapter 5: Advanced Concepts: Transports, Sampling, and Roots**. In this part of **MCP Docs Repo Tutorial: Navigating the Archived MCP Documentation Repository**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
+This chapter covers the three advanced concept pages that govern how data moves between clients and servers (transports), how servers can invoke LLM inference on their behalf (sampling), and how clients communicate workspace context (roots). These are production-relevant design decisions that the archived concepts explain well — with one significant caveat on transports.
+## Learning Goals
-This chapter covers advanced protocol topics that influence real-world architecture decisions.
+- Evaluate transport options and their security and deployment tradeoffs
+- Understand the sampling workflow and human-in-the-loop control model
+- Reason about roots and context boundaries in client-server interactions
+- Apply best-practice constraints in production architecture decisions
-## Learning Goals
+## Transports (`docs/concepts/transports.mdx`)
-- evaluate transport options and security tradeoffs
-- understand sampling workflows and human-in-the-loop controls
-- reason about roots/context boundaries in client-server interactions
-- apply best-practice constraints in production design
+Transports define how JSON-RPC messages travel between client and server. The archived docs cover two transports: **stdio** and **SSE (HTTP)**. The active docs add a third: **StreamableHTTP**, which is now the recommended remote transport.
-## Source References
+### Stdio Transport
-- [Transports Concepts](https://github.com/modelcontextprotocol/docs/blob/main/docs/concepts/transports.mdx)
-- [Sampling Concepts](https://github.com/modelcontextprotocol/docs/blob/main/docs/concepts/sampling.mdx)
-- [Roots Concepts](https://github.com/modelcontextprotocol/docs/blob/main/docs/concepts/roots.mdx)
+Used for local processes. The host spawns the server as a child process; communication is via stdin/stdout. This is the dominant model for desktop MCP clients (Claude Desktop, Cursor).
-## Summary
+```mermaid
+sequenceDiagram
+ participant Host
+ participant Client
+ participant ServerProcess
+
+ Host->>ServerProcess: spawn subprocess
+ Client->>ServerProcess: JSON-RPC via stdin
+ ServerProcess-->>Client: JSON-RPC via stdout
+ Note over Host,ServerProcess: stderr used for logs (not protocol)
+```
-You now have an advanced concept map for transport and context-design decisions.
+Stdio advantages:
+- No network exposure — lowest attack surface for local-only servers
+- Simple process lifecycle tied to host application
+- No port management or firewall rules needed
-Next: [Chapter 6: Tooling Docs: Inspector and Debugging](06-tooling-docs-inspector-and-debugging.md)
+### SSE Transport (Archived)
-## Source Code Walkthrough
+The archived docs describe an HTTP+SSE pattern where the server exposes an HTTP endpoint; the client posts requests and receives responses as SSE events. **This pattern is superseded by StreamableHTTP in the current protocol.**
+
+```mermaid
+sequenceDiagram
+ participant Client
+ participant Server
+
+ Client->>Server: GET /sse (establish SSE stream)
+ Server-->>Client: SSE events (server→client messages)
+ Client->>Server: POST /messages (client→server requests)
+ Server-->>Client: HTTP 200 acknowledgment
+ Server-->>Client: SSE event (response)
+```
+
+**Archive warning**: If your architecture uses the SSE transport pattern documented here, verify against active docs. The active protocol specifies StreamableHTTP as the canonical HTTP transport, which uses a single bidirectional HTTP+SSE channel rather than two separate endpoints.
+
+### Transport Selection Guide
+
+| Scenario | Recommended Transport | Notes |
+|:---------|:---------------------|:------|
+| Local desktop app (Claude Desktop, Cursor) | Stdio | Subprocess model, lowest friction |
+| Remote hosted server | StreamableHTTP (active docs) | SSE pattern is legacy |
+| Testing and development | Stdio via `mcp dev` | Inspector uses stdio by default |
+| Multi-tenant cloud service | StreamableHTTP with auth | Active docs, not covered in archive |
+
+## Sampling (`docs/concepts/sampling.mdx`)
+
+Sampling is the mechanism by which an MCP server can request the host to perform LLM inference. This allows servers to build agentic workflows without holding API keys or managing LLM connections directly.
+
+```mermaid
+sequenceDiagram
+ participant Server
+ participant Client
+ participant Host
+ participant LLM
+
+ Server->>Client: sampling/createMessage\n{messages, modelPrefs, maxTokens}
+ Client->>Host: forward sampling request
+ Host->>Host: apply safety policy\n(may show to user)
+ Host->>LLM: call LLM with messages
+ LLM-->>Host: completion
+ Host->>Host: apply post-sampling filter
+ Host-->>Client: sampling result
+ Client-->>Server: completion content
+```
-### `docs.json`
+Key design points from the archived sampling concept:
-The `docs` module in [`docs.json`](https://github.com/modelcontextprotocol/docs/blob/HEAD/docs.json) handles a key part of this chapter's functionality:
+1. **Human in the loop** — Hosts are expected to show sampling requests to users before executing them in sensitive contexts. The server has no guarantee the request will be executed as-is.
+2. **Model preferences** — Servers can specify `modelPreferences` (cost vs. intelligence tradeoffs) but the host makes the final model selection.
+3. **Capability negotiation** — Clients only advertise the `sampling` capability if the host supports it; servers must check before calling.
+Sampling enables a class of server behaviors impossible without it:
+- Recursive agent loops (server calls LLM, processes result, calls LLM again)
+- Tool-to-LLM pipelines (fetch resource → summarize via LLM → return to user)
+- Quality checks (run tool → validate output via LLM → retry if needed)
+
+```python
+# Server requesting a sampling call (Python SDK pattern)
+result = await ctx.sample(
+ messages=[{"role": "user", "content": f"Summarize: {document}"}],
+ max_tokens=500
+)
+summary = result.content.text
+```
+
+## Roots (`docs/concepts/roots.mdx`)
+
+Roots allow clients to inform servers about which parts of the file system (or other URI namespaces) are relevant to the current workspace. This gives servers context about scope without requiring servers to guess or enumerate.
+
+```mermaid
+graph LR
+ CLIENT[MCP Client]
+ CLIENT -->|roots/list response\n[file:///project/src, file:///docs]| SERVER[MCP Server]
+ SERVER --> SCOPED[Server scopes operations\nto declared root URIs]
+ SERVER --> RESP[Respects boundaries:\nnever reads outside roots]
+```
+
+Example roots declaration from the archived concept:
```json
{
- "$schema": "https://mintlify.com/docs.json",
- "theme": "willow",
- "name": "Model Context Protocol",
- "colors": {
- "primary": "#09090b",
- "light": "#FAFAFA",
- "dark": "#09090b"
- },
- "favicon": "/favicon.svg",
- "navigation": {
- "tabs": [
- {
- "tab": "Documentation",
- "groups": [
- {
- "group": "Get Started",
- "pages": [
- "introduction",
- {
- "group": "Quickstart",
- "pages": [
- "quickstart/server",
- "quickstart/client",
- "quickstart/user"
- ]
- },
- "examples",
- "clients"
- ]
- },
- {
- "group": "Tutorials",
- "pages": [
- "tutorials/building-mcp-with-llms",
+ "roots": [
+ { "uri": "file:///home/user/project", "name": "My Project" },
+ { "uri": "file:///home/user/notes", "name": "Notes" }
+ ]
+}
```
-This module is important because it defines how MCP Docs Repo Tutorial: Navigating the Archived MCP Documentation Repository implements the patterns covered in this chapter.
+Roots use cases:
+- File system servers that should only operate within declared project directories
+- Code analysis servers scoped to the active workspace
+- Servers that need to construct resource URIs relative to the workspace root
+Roots are advisory — the server should respect them, but the protocol does not enforce hard boundaries. Well-behaved servers validate that all resource URIs fall within declared roots.
-## How These Components Connect
+## Advanced Concept Stability
```mermaid
-flowchart TD
- A[docs]
+graph LR
+ STABLE[Highly Stable\nin Archive]
+ PARTIAL[Partially Outdated]
+
+ STABLE --> SAMPLING[Sampling model\nand capability negotiation]
+ STABLE --> ROOTS[Roots model\nand URI scoping]
+ PARTIAL --> TRANSPORT[Transport docs:\nSSE pattern is legacy,\nStreamableHTTP is current]
```
+
+| Concept | Archive Accuracy | Key Gap |
+|:--------|:-----------------|:--------|
+| Stdio transport | High | No gaps |
+| SSE/HTTP transport | Low | StreamableHTTP supersedes this in active docs |
+| Sampling | High | Active docs add elicitation (server-initiated input) |
+| Roots | High | No significant changes |
+
+## Source References
+
+- [Transports Concepts](https://github.com/modelcontextprotocol/docs/blob/main/docs/concepts/transports.mdx)
+- [Sampling Concepts](https://github.com/modelcontextprotocol/docs/blob/main/docs/concepts/sampling.mdx)
+- [Roots Concepts](https://github.com/modelcontextprotocol/docs/blob/main/docs/concepts/roots.mdx)
+
+## Summary
+
+Transports, sampling, and roots are the three advanced levers in MCP architecture. The archived transport docs are partially outdated — the SSE pattern is superseded by StreamableHTTP, so verify against active docs for any remote deployment design. Sampling and roots concepts are stable and accurately described in the archive. Use this chapter as a lens for evaluating where archived guidance is safe to use directly versus where you must check the current spec.
+
+Next: [Chapter 6: Tooling Docs: Inspector and Debugging](06-tooling-docs-inspector-and-debugging.md)
diff --git a/tutorials/mcp-docs-repo-tutorial/06-tooling-docs-inspector-and-debugging.md b/tutorials/mcp-docs-repo-tutorial/06-tooling-docs-inspector-and-debugging.md
index 2cf06227..aa849d37 100644
--- a/tutorials/mcp-docs-repo-tutorial/06-tooling-docs-inspector-and-debugging.md
+++ b/tutorials/mcp-docs-repo-tutorial/06-tooling-docs-inspector-and-debugging.md
@@ -5,82 +5,147 @@ nav_order: 6
parent: MCP Docs Repo Tutorial
---
-
# Chapter 6: Tooling Docs: Inspector and Debugging
-Welcome to **Chapter 6: Tooling Docs: Inspector and Debugging**. In this part of **MCP Docs Repo Tutorial: Navigating the Archived MCP Documentation Repository**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
+This chapter extracts practical debugging workflows from the archived `docs/tools/` section, covering the MCP Inspector and Claude Desktop debugging guidance. These pages describe developer tooling that remains mostly current — the Inspector is an actively maintained project.
+## Learning Goals
-This chapter extracts practical debugging workflows from archived tooling guides.
+- Apply Inspector usage patterns for server validation and development testing
+- Use debugging workflows for Claude Desktop and local server diagnostics
+- Structure log collection and troubleshooting steps for faster issue resolution
+- Translate archived guidance to current tooling versions safely
-## Learning Goals
+## MCP Inspector (`docs/tools/inspector.mdx`)
-- apply inspector usage patterns for server validation
-- use debugging workflows for Claude Desktop and local server diagnostics
-- structure logs and troubleshooting steps for faster issue resolution
-- translate archived guidance to current tooling versions safely
+The MCP Inspector is a browser-based developer tool that connects to any MCP server via stdio and provides an interactive UI for exercising tools, browsing resources, and testing prompts.
-## Source References
+```mermaid
+graph LR
+ DEV[Developer]
+ DEV -->|npx @modelcontextprotocol/inspector| INSPECTOR[Inspector\nBrowser UI\nlocalhost:5173]
+ INSPECTOR -->|stdio| SERVER[MCP Server\ne.g., python server.py]
+
+ INSPECTOR --> TOOLS_TAB[Tools Tab:\nlist + call tools]
+ INSPECTOR --> RES_TAB[Resources Tab:\nlist + read resources]
+ INSPECTOR --> PROMPT_TAB[Prompts Tab:\nlist + get prompts]
+ INSPECTOR --> LOG_TAB[Messages Tab:\nraw JSON-RPC log]
+```
-- [Inspector Guide](https://github.com/modelcontextprotocol/docs/blob/main/docs/tools/inspector.mdx)
-- [Debugging Guide](https://github.com/modelcontextprotocol/docs/blob/main/docs/tools/debugging.mdx)
+### Launching the Inspector
-## Summary
+```bash
+# Connect to a Python server
+npx @modelcontextprotocol/inspector python server.py
-You now have a tooling-oriented debugging model grounded in MCP documentation guidance.
+# Connect to a Node.js server
+npx @modelcontextprotocol/inspector node build/index.js
-Next: [Chapter 7: Tutorial Assets and Client Ecosystem Matrix](07-tutorial-assets-and-client-ecosystem-matrix.md)
+# Connect to a uvx-based server
+npx @modelcontextprotocol/inspector uvx my-mcp-server
+```
-## Source Code Walkthrough
-
-### `docs.json`
-
-The `docs` module in [`docs.json`](https://github.com/modelcontextprotocol/docs/blob/HEAD/docs.json) handles a key part of this chapter's functionality:
-
-```json
-{
- "$schema": "https://mintlify.com/docs.json",
- "theme": "willow",
- "name": "Model Context Protocol",
- "colors": {
- "primary": "#09090b",
- "light": "#FAFAFA",
- "dark": "#09090b"
- },
- "favicon": "/favicon.svg",
- "navigation": {
- "tabs": [
- {
- "tab": "Documentation",
- "groups": [
- {
- "group": "Get Started",
- "pages": [
- "introduction",
- {
- "group": "Quickstart",
- "pages": [
- "quickstart/server",
- "quickstart/client",
- "quickstart/user"
- ]
- },
- "examples",
- "clients"
- ]
- },
- {
- "group": "Tutorials",
- "pages": [
- "tutorials/building-mcp-with-llms",
+The Inspector launches a web server on `localhost:5173` and opens the browser UI. The `--` separator passes arguments to the server process:
+
+```bash
+npx @modelcontextprotocol/inspector python server.py -- --debug --port 8080
```
-This module is important because it defines how MCP Docs Repo Tutorial: Navigating the Archived MCP Documentation Repository implements the patterns covered in this chapter.
+### Inspector Workflow
+The typical development loop with the Inspector:
-## How These Components Connect
+1. **List capabilities**: Navigate to Tools, Resources, and Prompts tabs to verify registration
+2. **Call a tool**: Select a tool, fill in arguments via the generated form, observe response
+3. **Read a resource**: Enter a URI in the Resources tab and inspect the content blob
+4. **Test a prompt**: Select a prompt, provide arguments, review the rendered message array
+5. **Monitor raw messages**: Use the Messages tab to see every JSON-RPC request and response
```mermaid
flowchart TD
- A[docs]
+ LAUNCH[Launch Inspector\nnpx @modelcontextprotocol/inspector python server.py]
+ LAUNCH --> CONNECT[Inspector connects\nvia stdio]
+ CONNECT --> INIT[initialize handshake\ncapability negotiation]
+ INIT --> BROWSE[Browse capabilities\ntools / resources / prompts]
+ BROWSE --> TEST[Invoke tool or read resource]
+ TEST --> INSPECT[Inspect response\nin Messages tab]
+ INSPECT --> FIX[Fix server code]
+ FIX --> RELAUNCH[Re-launch Inspector]
+ RELAUNCH --> BROWSE
+```
+
+### What the Inspector Validates
+
+- Tool registration (name, description, input schema shape)
+- Resource URI scheme and content type handling
+- Prompt argument binding and message output structure
+- Error responses (malformed args, missing resources)
+- Raw JSON-RPC compliance (valid `id`, `jsonrpc: "2.0"`, proper result/error shape)
+
+## Debugging Guide (`docs/tools/debugging.mdx`)
+
+The debugging guide covers diagnosing integration failures when a server is connected through Claude Desktop or another host application.
+
+### Log Collection Points
+
+```mermaid
+graph TD
+ PROBLEM[Issue: tool not appearing or failing]
+ PROBLEM --> CLAUDE_LOGS[1. Check Claude Desktop logs]
+ PROBLEM --> SERVER_LOGS[2. Check server stderr output]
+ PROBLEM --> MCP_LOGS[3. Check MCP log file]
+
+ CLAUDE_LOGS --> MAC_PATH[macOS: ~/Library/Logs/Claude/\nmcp-server-{name}.log]
+ CLAUDE_LOGS --> WIN_PATH[Windows: %APPDATA%\Claude\logs\]
+ SERVER_LOGS --> STDERR[Server writes debug to stderr\nnever to stdout\nstdout is reserved for JSON-RPC]
+ MCP_LOGS --> COMBINED[Combined protocol trace]
+```
+
+**Critical debugging rule**: MCP servers communicating via stdio must **never** write to stdout except for JSON-RPC responses. Any `print()` statement, logging handler, or library that writes to stdout will corrupt the protocol stream. All diagnostic output must go to stderr.
+
+### Debugging Checklist from the Archive
+
+1. **Verify config syntax** — `claude_desktop_config.json` must be valid JSON; a single missing comma prevents all servers from loading
+2. **Check process spawn** — Look for the server process in Activity Monitor (macOS) or Task Manager (Windows) after starting Claude Desktop
+3. **Read the MCP log** — `mcp-server-{name}.log` contains the full JSON-RPC trace; look for `initialize` request and response
+4. **Test in Inspector first** — If a server works in Inspector but fails in Claude Desktop, the issue is the config or the host environment
+5. **Check stderr** — Server stderr is captured to `mcp-server-{name}.log`; add explicit debug logging to key handlers
+
+### Common Failure Patterns
+
+| Symptom | Likely Cause | Fix |
+|:--------|:-------------|:----|
+| Server not in tool list | Config syntax error or process spawn failure | Validate JSON, check logs |
+| Tool appears but calls fail | Handler throws unhandled exception | Add try/except with proper error response |
+| Intermittent failures | Race condition in async handler | Audit async/await hygiene |
+| Garbled responses | stdout pollution | Move all logging to stderr |
+| "Method not found" error | Tool name mismatch between registration and call | Verify exact name string |
+
+### Development vs. Production Debugging
+
+The archived debug guide focuses on local development with Claude Desktop. For production deployments on HTTP transports, the debugging approach shifts:
+
+```mermaid
+graph LR
+ DEV[Development\nClaude Desktop + stdio]
+ PROD[Production\nHTTP transport + hosted server]
+
+ DEV --> D1[Check log files on local machine]
+ DEV --> D2[Use Inspector for interactive testing]
+ DEV --> D3[Attach debugger to server process]
+
+ PROD --> P1[Structured logging to observability platform]
+ PROD --> P2[Trace request/response pairs via request IDs]
+ PROD --> P3[Alert on error rate from tools/call]
```
+
+## Source References
+
+- [Inspector Guide](https://github.com/modelcontextprotocol/docs/blob/main/docs/tools/inspector.mdx)
+- [Debugging Guide](https://github.com/modelcontextprotocol/docs/blob/main/docs/tools/debugging.mdx)
+
+## Summary
+
+The Inspector and debugging pages are among the most directly usable content in the archive. The Inspector launch pattern (`npx @modelcontextprotocol/inspector`) is current. The debugging log locations and the stdout-must-be-clean rule are both valid and important. Use the Inspector as the primary development validation tool and follow the log collection checklist for Claude Desktop integration failures.
+
+Next: [Chapter 7: Tutorial Assets and Client Ecosystem Matrix](07-tutorial-assets-and-client-ecosystem-matrix.md)
diff --git a/tutorials/mcp-docs-repo-tutorial/07-tutorial-assets-and-client-ecosystem-matrix.md b/tutorials/mcp-docs-repo-tutorial/07-tutorial-assets-and-client-ecosystem-matrix.md
index 3bec71ee..71024c5b 100644
--- a/tutorials/mcp-docs-repo-tutorial/07-tutorial-assets-and-client-ecosystem-matrix.md
+++ b/tutorials/mcp-docs-repo-tutorial/07-tutorial-assets-and-client-ecosystem-matrix.md
@@ -5,83 +5,168 @@ nav_order: 7
parent: MCP Docs Repo Tutorial
---
-
# Chapter 7: Tutorial Assets and Client Ecosystem Matrix
-Welcome to **Chapter 7: Tutorial Assets and Client Ecosystem Matrix**. In this part of **MCP Docs Repo Tutorial: Navigating the Archived MCP Documentation Repository**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
+This chapter examines the two tutorial pages and the client ecosystem matrix (`clients.mdx`) preserved in the archive. These resources provide implementation guidance and compatibility context that remains useful for planning and validation workflows — with appropriate caveats about the rapidly evolving client landscape.
+## Learning Goals
-This chapter focuses on ecosystem coverage context from tutorial and client-matrix content.
+- Use the client feature matrix for compatibility planning across MCP hosts
+- Interpret tutorial assets as implementation references while accounting for API changes
+- Prioritize client-target testing by feature support profiles
+- Keep compatibility assumptions documented and actively updated
-## Learning Goals
+## Client Ecosystem Matrix (`clients.mdx`)
-- use client feature matrices for compatibility planning
-- interpret tutorial assets as implementation references, not guarantees
-- prioritize client-target testing by feature support profiles
-- keep compatibility assumptions documented and testable
+The `clients.mdx` page contains a comprehensive matrix of MCP clients (hosts) and the MCP features each supports. This is invaluable for understanding which capabilities your server can rely on versus which require fallbacks.
-## Source References
+```mermaid
+graph TD
+ CLIENTS[MCP Clients Matrix]
+ CLIENTS --> FULL[Full-featured hosts\nClaude Desktop, Claude.ai]
+ CLIENTS --> PARTIAL[Partial support hosts\nCursor, Windsurf, Zed, etc.]
+ CLIENTS --> MINIMAL[Tool-only hosts\nIDEs with basic MCP integration]
+
+ FULL --> F1[Tools + Resources + Prompts\n+ Sampling + Roots]
+ PARTIAL --> P1[Tools always supported\nResources/Prompts vary]
+ MINIMAL --> M1[tools/list + tools/call only]
+```
-- [Client Ecosystem Matrix](https://github.com/modelcontextprotocol/docs/blob/main/clients.mdx)
-- [Building a Client (Node)](https://github.com/modelcontextprotocol/docs/blob/main/tutorials/building-a-client-node.mdx)
-- [Building MCP with LLMs](https://github.com/modelcontextprotocol/docs/blob/main/tutorials/building-mcp-with-llms.mdx)
+### Feature Support by Capability
-## Summary
+Based on the archived matrix, tool calls (`tools/list`, `tools/call`) are the most universally supported capability. Resources and prompts have narrower support. Sampling support is limited to clients that have explicit LLM integration.
-You now have a framework for using archived ecosystem docs in planning and validation workflows.
+| Capability | Broad Support | Notes |
+|:-----------|:-------------|:------|
+| `tools/list` + `tools/call` | Yes — near universal | Safe to rely on in all clients |
+| `resources/list` + `resources/read` | Partial | Claude Desktop, some IDE clients |
+| `prompts/list` + `prompts/get` | Partial | Claude Desktop, fewer IDEs |
+| `sampling/createMessage` | Narrow | Requires host LLM integration |
+| `roots/list` | Narrow | Context-aware clients (IDEs) |
-Next: [Chapter 8: Contribution Governance and Documentation Operations](08-contribution-governance-and-documentation-operations.md)
+### Using the Matrix for Server Design
-## Source Code Walkthrough
-
-### `docs.json`
-
-The `docs` module in [`docs.json`](https://github.com/modelcontextprotocol/docs/blob/HEAD/docs.json) handles a key part of this chapter's functionality:
-
-```json
-{
- "$schema": "https://mintlify.com/docs.json",
- "theme": "willow",
- "name": "Model Context Protocol",
- "colors": {
- "primary": "#09090b",
- "light": "#FAFAFA",
- "dark": "#09090b"
- },
- "favicon": "/favicon.svg",
- "navigation": {
- "tabs": [
- {
- "tab": "Documentation",
- "groups": [
- {
- "group": "Get Started",
- "pages": [
- "introduction",
- {
- "group": "Quickstart",
- "pages": [
- "quickstart/server",
- "quickstart/client",
- "quickstart/user"
- ]
- },
- "examples",
- "clients"
- ]
- },
- {
- "group": "Tutorials",
- "pages": [
- "tutorials/building-mcp-with-llms",
+```mermaid
+flowchart TD
+ TARGET{What clients will\nuse your server?}
+ TARGET --> ALL[All clients]
+ TARGET --> DESKTOP[Claude Desktop primarily]
+ TARGET --> IDE[IDE-first: Cursor, Windsurf]
+
+ ALL --> TOOLS_ONLY[Design as tools-only server\nfor maximum compatibility]
+ DESKTOP --> FULL_PRIM[Use tools + resources + prompts\nSampling is available]
+ IDE --> TOOLS_ROOTS[Use tools + roots awareness\nResources may be available]
```
-This module is important because it defines how MCP Docs Repo Tutorial: Navigating the Archived MCP Documentation Repository implements the patterns covered in this chapter.
+**Practical rule**: If you want your server to work in any MCP client without configuration, implement tools only. Add resources and prompts as progressive enhancements for clients that support them.
+### Matrix Staleness Warning
-## How These Components Connect
+The archived matrix captures the client landscape as of the archive cutoff. The MCP client ecosystem has grown significantly since then. Notable additions post-archive:
+- Additional IDE integrations (VS Code extensions, JetBrains plugins)
+- New web-based clients
+- API-based client libraries
+
+Always check the active `clients.mdx` in the monorepo for the current list.
+
+## Tutorial: Building a Client in Node.js (`tutorials/building-a-client-node.mdx`)
+
+This tutorial guides developers through building a full MCP client in TypeScript/Node.js that can connect to any stdio-based server and interactively call tools.
+
+Key implementation steps from the archived tutorial:
+1. Create a `Client` instance with name and version
+2. Instantiate a `StdioClientTransport` pointing at the server binary
+3. Call `client.connect()` to run the initialize handshake
+4. Call `client.listTools()` to enumerate available tools
+5. Build an interactive loop: read user input → call tool → print result
+
+```typescript
+// Archived Node.js client pattern (v1 imports — use active docs for v2)
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+
+const transport = new StdioClientTransport({
+ command: process.argv[2],
+ args: process.argv.slice(3)
+});
+
+const client = new Client({ name: "tutorial-client", version: "1.0.0" }, {
+ capabilities: { sampling: {} }
+});
+
+await client.connect(transport);
+
+const { tools } = await client.listTools();
+console.log("Available tools:", tools.map(t => t.name));
+```
+
+**Import path note**: The v2 TypeScript SDK uses split packages (`@modelcontextprotocol/client`, `@modelcontextprotocol/core`). The import paths above are from the v1 monolithic package and will fail with the v2 SDK. See the active TypeScript SDK docs for current imports.
```mermaid
-flowchart TD
- A[docs]
+sequenceDiagram
+ participant Tutorial Client
+ participant Server Process
+
+ Tutorial Client->>Server Process: spawn subprocess
+ Tutorial Client->>Server Process: initialize request
+ Server Process-->>Tutorial Client: initialize response + capabilities
+ Tutorial Client->>Server Process: tools/list
+ Server Process-->>Tutorial Client: tool definitions
+ Tutorial Client->>Tutorial Client: present tools to user
+ Tutorial Client->>Server Process: tools/call {name, arguments}
+ Server Process-->>Tutorial Client: tool result
+ Tutorial Client->>Tutorial Client: display result
```
+
+## Tutorial: Building MCP with LLMs (`tutorials/building-mcp-with-llms.mdx`)
+
+This tutorial takes a different angle — using an LLM (Claude) to assist in writing MCP server code. The workflow is:
+
+1. Paste the MCP specification into context
+2. Describe your desired tool, resource, or prompt behavior
+3. Have the LLM generate the handler implementation
+4. Test with Inspector, iterate
+
+```mermaid
+flowchart LR
+ SPEC[MCP Spec + SDK Docs\nas LLM context]
+ SPEC --> LLM[Claude / other LLM]
+ LLM --> CODE[Generated server code]
+ CODE --> INSPECT[Test in MCP Inspector]
+ INSPECT --> ITERATE{Works?}
+ ITERATE -- No --> FEEDBACK[Feed error back to LLM]
+ FEEDBACK --> LLM
+ ITERATE -- Yes --> INTEGRATE[Integrate into project]
+```
+
+Key recommendation from the archived tutorial: Provide the LLM with the complete spec context (the specification markdown) and SDK-specific examples. Generic prompts without spec context produce poor results.
+
+**Relevance today**: This workflow remains valid and is explicitly encouraged in the active docs. The active tutorial at `modelcontextprotocol.io/tutorials/building-mcp-with-llms` provides updated spec reference links.
+
+## Putting the Matrix and Tutorials Together
+
+The client matrix and tutorials form a complete planning toolkit:
+
+- **Client matrix** → decide which primitives to implement
+- **Node client tutorial** → validate your server against a custom client
+- **LLM-assisted tutorial** → accelerate server implementation
+
+```mermaid
+graph TD
+ PLAN[Plan: consult client matrix\nfor capability targeting]
+ PLAN --> BUILD[Build: use LLM-assisted\ntutorial for implementation]
+ BUILD --> TEST[Test: build custom client\nfollowing Node tutorial to validate]
+ TEST --> SHIP[Ship: target clients match\nexpected capability profile]
+```
+
+## Source References
+
+- [Client Ecosystem Matrix](https://github.com/modelcontextprotocol/docs/blob/main/clients.mdx)
+- [Building a Client (Node)](https://github.com/modelcontextprotocol/docs/blob/main/tutorials/building-a-client-node.mdx)
+- [Building MCP with LLMs](https://github.com/modelcontextprotocol/docs/blob/main/tutorials/building-mcp-with-llms.mdx)
+
+## Summary
+
+The client matrix is essential for capability targeting — use it to decide which primitives are worth implementing for your audience. The Node client tutorial illustrates the initialization and tool-call loop clearly, but update the import paths for v2 SDK. The LLM-assisted building tutorial is one of the most durable pieces of the archive — its workflow is still recommended in active docs.
+
+Next: [Chapter 8: Contribution Governance and Documentation Operations](08-contribution-governance-and-documentation-operations.md)
diff --git a/tutorials/mcp-docs-repo-tutorial/08-contribution-governance-and-documentation-operations.md b/tutorials/mcp-docs-repo-tutorial/08-contribution-governance-and-documentation-operations.md
index fd492d57..8ce017c1 100644
--- a/tutorials/mcp-docs-repo-tutorial/08-contribution-governance-and-documentation-operations.md
+++ b/tutorials/mcp-docs-repo-tutorial/08-contribution-governance-and-documentation-operations.md
@@ -5,82 +5,141 @@ nav_order: 8
parent: MCP Docs Repo Tutorial
---
-
# Chapter 8: Contribution Governance and Documentation Operations
-Welcome to **Chapter 8: Contribution Governance and Documentation Operations**. In this part of **MCP Docs Repo Tutorial: Navigating the Archived MCP Documentation Repository**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
+This final chapter defines governance controls for teams maintaining internal MCP documentation around an archived upstream source — and explains where external contributions to MCP documentation should actually go.
+## Learning Goals
-This chapter defines governance controls for teams maintaining internal MCP docs around archived upstream content.
+- Route external documentation contributions to the correct active repositories
+- Maintain internal docs synchronization with canonical MCP documentation
+- Establish review and versioning policies for docs-derived architecture guidance
+- Prevent stale archive content from overriding current specification updates
-## Learning Goals
+## Where Contributions Should Go
-- route external documentation contributions to active repositories correctly
-- maintain internal docs synchronization with canonical MCP docs
-- establish review and versioning policies for docs-derived architecture guidance
-- prevent stale archive content from overriding current specification updates
+The `modelcontextprotocol/docs` repository is **read-only**. It does not accept issues or pull requests. All documentation contributions to the MCP project must target the active repositories:
-## Source References
+```mermaid
+flowchart TD
+ CONTRIB[Contributor wants to improve MCP docs]
+ CONTRIB --> Q1{What type of change?}
+
+ Q1 --> PROTO[Protocol spec\nor concept update]
+ Q1 --> SDK[Language SDK docs\nor examples]
+ Q1 --> SITE[Website copy\nor navigation]
+ Q1 --> TOOL[Inspector or\ntooling docs]
+
+ PROTO --> MONOREPO[modelcontextprotocol/modelcontextprotocol\nOpen issue or PR against docs/ directory]
+ SDK --> SDKREPO[Respective SDK repo:\npython-sdk · typescript-sdk · java-sdk]
+ SITE --> MONOREPO
+ TOOL --> INSPECTOR[modelcontextprotocol/inspector\nfor Inspector-specific issues]
+```
-- [Archived Docs Contributing Guide](https://github.com/modelcontextprotocol/docs/blob/main/CONTRIBUTING.md)
-- [Active MCP Docs Location](https://github.com/modelcontextprotocol/modelcontextprotocol/tree/main/docs)
+## Internal Docs Governance Model
-## Summary
+For teams building on MCP who maintain internal documentation derived from or referencing MCP sources:
-You now have a governance model for documentation operations across archived and active MCP sources.
+### Ownership Structure
-Return to the [MCP Docs Repo Tutorial index](README.md).
+```mermaid
+graph TD
+ INTERNAL[Internal MCP Documentation]
+ INTERNAL --> ARCH[Architecture Decision Records\nOwner: Platform team\nReview cycle: quarterly]
+ INTERNAL --> GUIDE[Integration Guides\nOwner: API/integration team\nReview cycle: on SDK major release]
+ INTERNAL --> ONBOARD[Onboarding Docs\nOwner: Enablement team\nReview cycle: semiannual]
+ INTERNAL --> REF[Reference links to upstream\nOwner: All — flag when archived links are cited]
+```
+
+### Synchronization Policy
+
+Internal documentation that references MCP concepts should follow a synchronization cadence:
+
+| Trigger | Action |
+|:--------|:-------|
+| New MCP SDK major version | Review and update all import path references |
+| Protocol specification change | Update architecture docs and concept glossary |
+| New official transport (e.g., StreamableHTTP) | Update transport choice guidance |
+| New client added to ecosystem matrix | Review capability targeting assumptions |
+| Archive notice on any MCP repo | Flag all internal links to that repo for migration |
+
+### Preventing Stale Content Propagation
+
+The most common failure mode is copying content from an archived source into internal documentation without marking it as requiring verification. Mitigation practices:
+
+1. **Link annotations**: Any link to `github.com/modelcontextprotocol/docs` in internal docs must be annotated with `[archived]` and the date last verified
+2. **Deprecation lint**: Add a CI check that flags archived GitHub URLs in documentation files
+3. **Canonical link policy**: Prefer links to `modelcontextprotocol.io` (live site) over GitHub source links where possible; the live site always reflects the current active state
+4. **Scheduled review**: Quarterly audit of all MCP-referencing documentation against the active monorepo
-## Source Code Walkthrough
-
-### `docs.json`
-
-The `docs` module in [`docs.json`](https://github.com/modelcontextprotocol/docs/blob/HEAD/docs.json) handles a key part of this chapter's functionality:
-
-```json
-{
- "$schema": "https://mintlify.com/docs.json",
- "theme": "willow",
- "name": "Model Context Protocol",
- "colors": {
- "primary": "#09090b",
- "light": "#FAFAFA",
- "dark": "#09090b"
- },
- "favicon": "/favicon.svg",
- "navigation": {
- "tabs": [
- {
- "tab": "Documentation",
- "groups": [
- {
- "group": "Get Started",
- "pages": [
- "introduction",
- {
- "group": "Quickstart",
- "pages": [
- "quickstart/server",
- "quickstart/client",
- "quickstart/user"
- ]
- },
- "examples",
- "clients"
- ]
- },
- {
- "group": "Tutorials",
- "pages": [
- "tutorials/building-mcp-with-llms",
+```mermaid
+flowchart LR
+ LINT[CI: lint for archived URLs]
+ LINT --> FAIL{Found archived\nlink without annotation?}
+ FAIL -- Yes --> BLOCK[Block merge\nRequire annotation or migration]
+ FAIL -- No --> PASS[Pass]
+ PASS --> SCHEDULE[Quarterly: human review\nof all annotated archived links]
+ SCHEDULE --> MIGRATE[Migrate links that\nhave active equivalents]
```
-This module is important because it defines how MCP Docs Repo Tutorial: Navigating the Archived MCP Documentation Repository implements the patterns covered in this chapter.
+## Archived Contributing Guide (`development/contributing.mdx`)
+
+The archived CONTRIBUTING.md and the `development/contributing.mdx` page describe the original documentation contribution process for the Mintlify site. Now that the site is migrated, this content is historical.
+
+Key governance elements preserved in the archived contributing guide:
+- Page format conventions (MDX + Mintlify component syntax)
+- Frontmatter requirements (title, description)
+- Image and asset naming conventions
+- Review process expectations
+
+These conventions are still useful as a baseline for teams building their own documentation infrastructure using Mintlify or similar platforms.
+
+## Documentation Operations Checklist
+For teams operating on MCP at scale:
-## How These Components Connect
+### Initial Setup
+- [ ] Identify which internal docs reference the `modelcontextprotocol/docs` archive
+- [ ] Annotate every archived link with `[archived — verify against modelcontextprotocol.io]`
+- [ ] Establish ownership assignments for each internal doc category
+- [ ] Set up quarterly review calendar entries
+
+### Ongoing Operations
+- [ ] Monitor `modelcontextprotocol/modelcontextprotocol` releases for spec changes
+- [ ] Subscribe to SDK release feeds (Python SDK, TypeScript SDK)
+- [ ] Track MCP Inspector releases for tooling doc updates
+- [ ] Review client ecosystem matrix every six months
+
+### Migration Completion Criteria
+- [ ] Zero unverified links to `github.com/modelcontextprotocol/docs` in internal docs
+- [ ] All concept references point to active monorepo or live site
+- [ ] All SDK import paths match current major version
+- [ ] Transport documentation references StreamableHTTP for remote scenarios
+
+## Governance Summary Diagram
```mermaid
-flowchart TD
- A[docs]
+graph TD
+ ARCHIVED_REPO[modelcontextprotocol/docs\nArchived — read-only]
+ ACTIVE_REPO[modelcontextprotocol/modelcontextprotocol\nActive — protocol + spec + docs]
+ SDK_REPOS[SDK Repositories\npython-sdk · typescript-sdk · java-sdk]
+ INTERNAL[Internal Team Docs]
+
+ ARCHIVED_REPO -.->|historical reference only| INTERNAL
+ ACTIVE_REPO -->|source of truth| INTERNAL
+ SDK_REPOS -->|implementation guidance| INTERNAL
+ INTERNAL -->|contributions| ACTIVE_REPO
+ INTERNAL -->|bug reports + feature requests| SDK_REPOS
```
+
+## Source References
+
+- [Archived Docs Contributing Guide](https://github.com/modelcontextprotocol/docs/blob/main/CONTRIBUTING.md)
+- [Active MCP Docs Location](https://github.com/modelcontextprotocol/modelcontextprotocol/tree/main/docs)
+- [MCP Monorepo Contributing Guide](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/CONTRIBUTING.md)
+
+## Summary
+
+The archived repository accepts no contributions. All documentation improvements for MCP go to the active monorepo or the respective SDK repositories. Internally, treat archived content as a read-only historical reference with explicit annotations. Establish a synchronization policy driven by protocol and SDK releases, not by time alone. The governance checklist in this chapter gives your team a concrete starting point for managing MCP documentation across its full lifecycle.
+
+Return to the [MCP Docs Repo Tutorial index](README.md).
diff --git a/tutorials/mcp-ext-apps-tutorial/01-getting-started-and-spec-orientation.md b/tutorials/mcp-ext-apps-tutorial/01-getting-started-and-spec-orientation.md
index 19c68f4f..55beeb8d 100644
--- a/tutorials/mcp-ext-apps-tutorial/01-getting-started-and-spec-orientation.md
+++ b/tutorials/mcp-ext-apps-tutorial/01-getting-started-and-spec-orientation.md
@@ -40,170 +40,168 @@ You now have the baseline needed to evaluate and implement MCP Apps flows.
Next: [Chapter 2: MCP Apps Architecture and Lifecycle](02-mcp-apps-architecture-and-lifecycle.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/app-bridge.examples.ts`
-
-The `with` class in [`src/app-bridge.examples.ts`](https://github.com/modelcontextprotocol/ext-apps/blob/HEAD/src/app-bridge.examples.ts) handles a key part of this chapter's functionality:
+### `docs/patterns.tsx`
-```ts
+The `pollingVanillaJs` function in [`docs/patterns.tsx`](https://github.com/modelcontextprotocol/ext-apps/blob/HEAD/docs/patterns.tsx) handles a key part of this chapter's functionality:
-/**
- * Example: Basic usage of the AppBridge class with PostMessageTransport.
+```tsx
+ * Example: Polling for live data (Vanilla JS)
*/
-async function AppBridge_basicUsage(serverTransport: Transport) {
- //#region AppBridge_basicUsage
- // Create MCP client for the server
- const client = new Client({
- name: "MyHost",
- version: "1.0.0",
- });
- await client.connect(serverTransport);
-
- // Create bridge for the View
- const bridge = new AppBridge(
- client,
- { name: "MyHost", version: "1.0.0" },
- { openLinks: {}, serverTools: {}, logging: {} },
- );
-
- // Set up iframe and connect
- const iframe = document.getElementById("app") as HTMLIFrameElement;
- const transport = new PostMessageTransport(
- iframe.contentWindow!,
- iframe.contentWindow!,
- );
-
- bridge.oninitialized = () => {
- console.log("View initialized");
- // Now safe to send tool input
- bridge.sendToolInput({ arguments: { location: "NYC" } });
+function pollingVanillaJs(app: App, updateUI: (data: unknown) => void) {
+ //#region pollingVanillaJs
+ let intervalId: number | null = null;
+
+ async function poll() {
+ const result = await app.callServerTool({
+ name: "poll-data",
+ arguments: {},
+ });
+ updateUI(result.structuredContent);
+ }
+
+ function startPolling() {
+ if (intervalId !== null) return;
+ poll();
+ intervalId = window.setInterval(poll, 2000);
+ }
+
+ function stopPolling() {
+ if (intervalId === null) return;
+ clearInterval(intervalId);
+ intervalId = null;
+ }
+
+ // Clean up when host tears down the view
+ app.onteardown = async () => {
+ stopPolling();
+ return {};
};
+ //#endregion pollingVanillaJs
```
-This class is important because it defines how MCP Ext Apps Tutorial: Building Interactive MCP Apps and Hosts implements the patterns covered in this chapter.
+This function is important because it defines how MCP Ext Apps Tutorial: Building Interactive MCP Apps and Hosts implements the patterns covered in this chapter.
-### `src/app-bridge.examples.ts`
+### `docs/patterns.tsx`
-The `AppBridge_basicUsage` function in [`src/app-bridge.examples.ts`](https://github.com/modelcontextprotocol/ext-apps/blob/HEAD/src/app-bridge.examples.ts) handles a key part of this chapter's functionality:
+The `poll` function in [`docs/patterns.tsx`](https://github.com/modelcontextprotocol/ext-apps/blob/HEAD/docs/patterns.tsx) handles a key part of this chapter's functionality:
-```ts
- * Example: Basic usage of the AppBridge class with PostMessageTransport.
+```tsx
+ * Example: Polling for live data (Vanilla JS)
*/
-async function AppBridge_basicUsage(serverTransport: Transport) {
- //#region AppBridge_basicUsage
- // Create MCP client for the server
- const client = new Client({
- name: "MyHost",
- version: "1.0.0",
- });
- await client.connect(serverTransport);
-
- // Create bridge for the View
- const bridge = new AppBridge(
- client,
- { name: "MyHost", version: "1.0.0" },
- { openLinks: {}, serverTools: {}, logging: {} },
- );
-
- // Set up iframe and connect
- const iframe = document.getElementById("app") as HTMLIFrameElement;
- const transport = new PostMessageTransport(
- iframe.contentWindow!,
- iframe.contentWindow!,
- );
-
- bridge.oninitialized = () => {
- console.log("View initialized");
- // Now safe to send tool input
- bridge.sendToolInput({ arguments: { location: "NYC" } });
+function pollingVanillaJs(app: App, updateUI: (data: unknown) => void) {
+ //#region pollingVanillaJs
+ let intervalId: number | null = null;
+
+ async function poll() {
+ const result = await app.callServerTool({
+ name: "poll-data",
+ arguments: {},
+ });
+ updateUI(result.structuredContent);
+ }
+
+ function startPolling() {
+ if (intervalId !== null) return;
+ poll();
+ intervalId = window.setInterval(poll, 2000);
+ }
+
+ function stopPolling() {
+ if (intervalId === null) return;
+ clearInterval(intervalId);
+ intervalId = null;
+ }
+
+ // Clean up when host tears down the view
+ app.onteardown = async () => {
+ stopPolling();
+ return {};
};
-
- await bridge.connect(transport);
+ //#endregion pollingVanillaJs
```
This function is important because it defines how MCP Ext Apps Tutorial: Building Interactive MCP Apps and Hosts implements the patterns covered in this chapter.
-### `src/app-bridge.examples.ts`
+### `docs/patterns.tsx`
-The `AppBridge_constructor_withMcpClient` function in [`src/app-bridge.examples.ts`](https://github.com/modelcontextprotocol/ext-apps/blob/HEAD/src/app-bridge.examples.ts) handles a key part of this chapter's functionality:
+The `startPolling` function in [`docs/patterns.tsx`](https://github.com/modelcontextprotocol/ext-apps/blob/HEAD/docs/patterns.tsx) handles a key part of this chapter's functionality:
-```ts
- * Example: Creating an AppBridge with an MCP client for automatic forwarding.
- */
-function AppBridge_constructor_withMcpClient(mcpClient: Client) {
- //#region AppBridge_constructor_withMcpClient
- const bridge = new AppBridge(
- mcpClient,
- { name: "MyHost", version: "1.0.0" },
- { openLinks: {}, serverTools: {}, logging: {} },
- );
- //#endregion AppBridge_constructor_withMcpClient
-}
+```tsx
+ }
-/**
- * Example: Creating an AppBridge without an MCP client, using manual handlers.
- */
-function AppBridge_constructor_withoutMcpClient() {
- //#region AppBridge_constructor_withoutMcpClient
- const bridge = new AppBridge(
- null,
- { name: "MyHost", version: "1.0.0" },
- { openLinks: {}, serverTools: {}, logging: {} },
- );
- bridge.oncalltool = async (params, extra) => {
- // Handle tool calls manually
- return { content: [] };
+ function startPolling() {
+ if (intervalId !== null) return;
+ poll();
+ intervalId = window.setInterval(poll, 2000);
+ }
+
+ function stopPolling() {
+ if (intervalId === null) return;
+ clearInterval(intervalId);
+ intervalId = null;
+ }
+
+ // Clean up when host tears down the view
+ app.onteardown = async () => {
+ stopPolling();
+ return {};
};
- //#endregion AppBridge_constructor_withoutMcpClient
+ //#endregion pollingVanillaJs
}
/**
- * Example: Check View capabilities after initialization.
+ * Example: Polling for live data (React)
*/
+function pollingReact(
+ app: App | null, // via useApp()
+) {
+ const [data, setData] = useState<unknown>();
+
+ //#region pollingReact
+ useEffect(() => {
```
This function is important because it defines how MCP Ext Apps Tutorial: Building Interactive MCP Apps and Hosts implements the patterns covered in this chapter.
-### `src/app-bridge.examples.ts`
+### `docs/patterns.tsx`
-The `AppBridge_constructor_withoutMcpClient` function in [`src/app-bridge.examples.ts`](https://github.com/modelcontextprotocol/ext-apps/blob/HEAD/src/app-bridge.examples.ts) handles a key part of this chapter's functionality:
+The `stopPolling` function in [`docs/patterns.tsx`](https://github.com/modelcontextprotocol/ext-apps/blob/HEAD/docs/patterns.tsx) handles a key part of this chapter's functionality:
-```ts
- * Example: Creating an AppBridge without an MCP client, using manual handlers.
- */
-function AppBridge_constructor_withoutMcpClient() {
- //#region AppBridge_constructor_withoutMcpClient
- const bridge = new AppBridge(
- null,
- { name: "MyHost", version: "1.0.0" },
- { openLinks: {}, serverTools: {}, logging: {} },
- );
- bridge.oncalltool = async (params, extra) => {
- // Handle tool calls manually
- return { content: [] };
- };
- //#endregion AppBridge_constructor_withoutMcpClient
-}
+```tsx
+ }
-/**
- * Example: Check View capabilities after initialization.
- */
-function AppBridge_getAppCapabilities_checkAfterInit(bridge: AppBridge) {
- //#region AppBridge_getAppCapabilities_checkAfterInit
- bridge.oninitialized = () => {
- const caps = bridge.getAppCapabilities();
- if (caps?.tools) {
- console.log("View provides tools");
- }
+ function stopPolling() {
+ if (intervalId === null) return;
+ clearInterval(intervalId);
+ intervalId = null;
+ }
+
+ // Clean up when host tears down the view
+ app.onteardown = async () => {
+ stopPolling();
+ return {};
};
- //#endregion AppBridge_getAppCapabilities_checkAfterInit
+ //#endregion pollingVanillaJs
}
/**
- * Example: Log View information after initialization.
+ * Example: Polling for live data (React)
+ */
+function pollingReact(
+ app: App | null, // via useApp()
+) {
+ const [data, setData] = useState<unknown>();
+
+ //#region pollingReact
+ useEffect(() => {
+ if (!app) return;
+ let cancelled = false;
+
+ async function poll() {
+ const result = await app!.callServerTool({
+ name: "poll-data",
```
This function is important because it defines how MCP Ext Apps Tutorial: Building Interactive MCP Apps and Hosts implements the patterns covered in this chapter.
@@ -213,11 +211,11 @@ This function is important because it defines how MCP Ext Apps Tutorial: Buildin
```mermaid
flowchart TD
- A[with]
- B[AppBridge_basicUsage]
- C[AppBridge_constructor_withMcpClient]
- D[AppBridge_constructor_withoutMcpClient]
- E[AppBridge_getAppCapabilities_checkAfterInit]
+ A[pollingVanillaJs]
+ B[poll]
+ C[startPolling]
+ D[stopPolling]
+ E[pollingReact]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-ext-apps-tutorial/02-mcp-apps-architecture-and-lifecycle.md b/tutorials/mcp-ext-apps-tutorial/02-mcp-apps-architecture-and-lifecycle.md
index 7de40a06..7ecc4f8e 100644
--- a/tutorials/mcp-ext-apps-tutorial/02-mcp-apps-architecture-and-lifecycle.md
+++ b/tutorials/mcp-ext-apps-tutorial/02-mcp-apps-architecture-and-lifecycle.md
@@ -39,170 +39,168 @@ You now have a lifecycle model for MCP Apps interactions across server, host, an
Next: [Chapter 3: App SDK: UI Resources and Tool Linkage](03-app-sdk-ui-resources-and-tool-linkage.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/app-bridge.examples.ts`
+### `docs/patterns.tsx`
-The `AppBridge_teardownResource_gracefulShutdown` function in [`src/app-bridge.examples.ts`](https://github.com/modelcontextprotocol/ext-apps/blob/HEAD/src/app-bridge.examples.ts) handles a key part of this chapter's functionality:
+The `DataChunk` interface in [`docs/patterns.tsx`](https://github.com/modelcontextprotocol/ext-apps/blob/HEAD/docs/patterns.tsx) handles a key part of this chapter's functionality:
-```ts
- * Example: Gracefully tear down the View before unmounting.
- */
-async function AppBridge_teardownResource_gracefulShutdown(
- bridge: AppBridge,
- iframe: HTMLIFrameElement,
-) {
- //#region AppBridge_teardownResource_gracefulShutdown
- try {
- await bridge.teardownResource({});
- // View is ready, safe to unmount iframe
- iframe.remove();
- } catch (error) {
- console.error("Teardown failed:", error);
- }
- //#endregion AppBridge_teardownResource_gracefulShutdown
-}
-
-/**
- * Example: Update theme when user toggles dark mode.
- */
-function AppBridge_setHostContext_updateTheme(bridge: AppBridge) {
- //#region AppBridge_setHostContext_updateTheme
- bridge.setHostContext({ theme: "dark" });
- //#endregion AppBridge_setHostContext_updateTheme
-}
+```tsx
+ //#region chunkedDataServer
+ // Define the chunk response schema
+ const DataChunkSchema = z.object({
+ bytes: z.string(), // base64-encoded data
+ offset: z.number(),
+ byteCount: z.number(),
+ totalBytes: z.number(),
+ hasMore: z.boolean(),
+ });
-/**
- * Example: Update multiple context fields at once.
- */
-function AppBridge_setHostContext_updateMultiple(bridge: AppBridge) {
- //#region AppBridge_setHostContext_updateMultiple
- bridge.setHostContext({
+ const MAX_CHUNK_BYTES = 500 * 1024; // 500KB per chunk
+
+ registerAppTool(
+ server,
+ "read_data_bytes",
+ {
+ title: "Read Data Bytes",
+ description: "Load binary data in chunks",
+ inputSchema: {
+ id: z.string().describe("Resource identifier"),
+ offset: z.number().min(0).default(0).describe("Byte offset"),
+ byteCount: z
+ .number()
+ .default(MAX_CHUNK_BYTES)
+ .describe("Bytes to read"),
+ },
+ outputSchema: DataChunkSchema,
+ // Hidden from model - only callable by the App
+ _meta: { ui: { visibility: ["app"] } },
+ },
+ async ({ id, offset, byteCount }): Promise<CallToolResult> => {
+ const data = await loadData(id); // Your data loading logic
```
-This function is important because it defines how MCP Ext Apps Tutorial: Building Interactive MCP Apps and Hosts implements the patterns covered in this chapter.
+This interface is important because it defines how MCP Ext Apps Tutorial: Building Interactive MCP Apps and Hosts implements the patterns covered in this chapter.
-### `src/app-bridge.examples.ts`
+### `src/app.examples.ts`
-The `AppBridge_setHostContext_updateTheme` function in [`src/app-bridge.examples.ts`](https://github.com/modelcontextprotocol/ext-apps/blob/HEAD/src/app-bridge.examples.ts) handles a key part of this chapter's functionality:
+The `with` class in [`src/app.examples.ts`](https://github.com/modelcontextprotocol/ext-apps/blob/HEAD/src/app.examples.ts) handles a key part of this chapter's functionality:
```ts
- * Example: Update theme when user toggles dark mode.
- */
-function AppBridge_setHostContext_updateTheme(bridge: AppBridge) {
- //#region AppBridge_setHostContext_updateTheme
- bridge.setHostContext({ theme: "dark" });
- //#endregion AppBridge_setHostContext_updateTheme
-}
/**
- * Example: Update multiple context fields at once.
+ * Example: Modern format for registering tools with UI (recommended).
*/
-function AppBridge_setHostContext_updateMultiple(bridge: AppBridge) {
- //#region AppBridge_setHostContext_updateMultiple
- bridge.setHostContext({
- theme: "dark",
- containerDimensions: { maxHeight: 600, width: 800 },
- });
- //#endregion AppBridge_setHostContext_updateMultiple
+function RESOURCE_URI_META_KEY_modernFormat(
+ server: McpServer,
+ handler: ToolCallback,
+) {
+ //#region RESOURCE_URI_META_KEY_modernFormat
+ // Preferred: Use registerAppTool with nested ui.resourceUri
+ registerAppTool(
+ server,
+ "weather",
+ {
+ description: "Get weather forecast",
+ _meta: {
+ ui: { resourceUri: "ui://weather/forecast" },
+ },
+ },
+ handler,
+ );
+ //#endregion RESOURCE_URI_META_KEY_modernFormat
}
/**
- * Example: Send tool input after initialization.
+ * Example: Legacy format using RESOURCE_URI_META_KEY (deprecated).
*/
-function AppBridge_sendToolInput_afterInit(bridge: AppBridge) {
- //#region AppBridge_sendToolInput_afterInit
- bridge.oninitialized = () => {
- bridge.sendToolInput({
- arguments: { location: "New York", units: "metric" },
- });
- };
- //#endregion AppBridge_sendToolInput_afterInit
-}
+function RESOURCE_URI_META_KEY_legacyFormat(
+ server: McpServer,
+ handler: ToolCallback,
+) {
+ //#region RESOURCE_URI_META_KEY_legacyFormat
```
-This function is important because it defines how MCP Ext Apps Tutorial: Building Interactive MCP Apps and Hosts implements the patterns covered in this chapter.
+This class is important because it defines how MCP Ext Apps Tutorial: Building Interactive MCP Apps and Hosts implements the patterns covered in this chapter.
-### `src/app-bridge.examples.ts`
+### `src/app.examples.ts`
-The `AppBridge_setHostContext_updateMultiple` function in [`src/app-bridge.examples.ts`](https://github.com/modelcontextprotocol/ext-apps/blob/HEAD/src/app-bridge.examples.ts) handles a key part of this chapter's functionality:
+The `RESOURCE_URI_META_KEY_modernFormat` function in [`src/app.examples.ts`](https://github.com/modelcontextprotocol/ext-apps/blob/HEAD/src/app.examples.ts) handles a key part of this chapter's functionality:
```ts
- * Example: Update multiple context fields at once.
- */
-function AppBridge_setHostContext_updateMultiple(bridge: AppBridge) {
- //#region AppBridge_setHostContext_updateMultiple
- bridge.setHostContext({
- theme: "dark",
- containerDimensions: { maxHeight: 600, width: 800 },
- });
- //#endregion AppBridge_setHostContext_updateMultiple
-}
-
-/**
- * Example: Send tool input after initialization.
+ * Example: Modern format for registering tools with UI (recommended).
*/
-function AppBridge_sendToolInput_afterInit(bridge: AppBridge) {
- //#region AppBridge_sendToolInput_afterInit
- bridge.oninitialized = () => {
- bridge.sendToolInput({
- arguments: { location: "New York", units: "metric" },
- });
- };
- //#endregion AppBridge_sendToolInput_afterInit
+function RESOURCE_URI_META_KEY_modernFormat(
+ server: McpServer,
+ handler: ToolCallback,
+) {
+ //#region RESOURCE_URI_META_KEY_modernFormat
+ // Preferred: Use registerAppTool with nested ui.resourceUri
+ registerAppTool(
+ server,
+ "weather",
+ {
+ description: "Get weather forecast",
+ _meta: {
+ ui: { resourceUri: "ui://weather/forecast" },
+ },
+ },
+ handler,
+ );
+ //#endregion RESOURCE_URI_META_KEY_modernFormat
}
/**
- * Example: Stream partial arguments as they arrive.
+ * Example: Legacy format using RESOURCE_URI_META_KEY (deprecated).
*/
-function AppBridge_sendToolInputPartial_streaming(bridge: AppBridge) {
- //#region AppBridge_sendToolInputPartial_streaming
- // As streaming progresses...
- bridge.sendToolInputPartial({ arguments: { loc: "N" } });
- bridge.sendToolInputPartial({ arguments: { location: "New" } });
+function RESOURCE_URI_META_KEY_legacyFormat(
+ server: McpServer,
+ handler: ToolCallback,
+) {
+ //#region RESOURCE_URI_META_KEY_legacyFormat
+ // Deprecated: Direct use of RESOURCE_URI_META_KEY
+ server.registerTool(
```
This function is important because it defines how MCP Ext Apps Tutorial: Building Interactive MCP Apps and Hosts implements the patterns covered in this chapter.
-### `src/app-bridge.examples.ts`
+### `src/app.examples.ts`
-The `AppBridge_sendToolInput_afterInit` function in [`src/app-bridge.examples.ts`](https://github.com/modelcontextprotocol/ext-apps/blob/HEAD/src/app-bridge.examples.ts) handles a key part of this chapter's functionality:
+The `RESOURCE_URI_META_KEY_legacyFormat` function in [`src/app.examples.ts`](https://github.com/modelcontextprotocol/ext-apps/blob/HEAD/src/app.examples.ts) handles a key part of this chapter's functionality:
```ts
- * Example: Send tool input after initialization.
- */
-function AppBridge_sendToolInput_afterInit(bridge: AppBridge) {
- //#region AppBridge_sendToolInput_afterInit
- bridge.oninitialized = () => {
- bridge.sendToolInput({
- arguments: { location: "New York", units: "metric" },
- });
- };
- //#endregion AppBridge_sendToolInput_afterInit
-}
-
-/**
- * Example: Stream partial arguments as they arrive.
+ * Example: Legacy format using RESOURCE_URI_META_KEY (deprecated).
*/
-function AppBridge_sendToolInputPartial_streaming(bridge: AppBridge) {
- //#region AppBridge_sendToolInputPartial_streaming
- // As streaming progresses...
- bridge.sendToolInputPartial({ arguments: { loc: "N" } });
- bridge.sendToolInputPartial({ arguments: { location: "New" } });
- bridge.sendToolInputPartial({ arguments: { location: "New York" } });
-
- // When complete, send final input
- bridge.sendToolInput({
- arguments: { location: "New York", units: "metric" },
- });
- //#endregion AppBridge_sendToolInputPartial_streaming
+function RESOURCE_URI_META_KEY_legacyFormat(
+ server: McpServer,
+ handler: ToolCallback,
+) {
+ //#region RESOURCE_URI_META_KEY_legacyFormat
+ // Deprecated: Direct use of RESOURCE_URI_META_KEY
+ server.registerTool(
+ "weather",
+ {
+ description: "Get weather forecast",
+ _meta: {
+ [RESOURCE_URI_META_KEY]: "ui://weather/forecast",
+ },
+ },
+ handler,
+ );
+ //#endregion RESOURCE_URI_META_KEY_legacyFormat
}
/**
- * Example: Send tool result after execution.
+ * Example: How hosts check for RESOURCE_URI_META_KEY metadata (must support both formats).
*/
+function RESOURCE_URI_META_KEY_hostSide(tool: Tool) {
+ //#region RESOURCE_URI_META_KEY_hostSide
+ // Hosts should check both modern and legacy formats
+ const meta = tool._meta;
+ const uiMeta = meta?.ui as McpUiToolMeta | undefined;
+ const legacyUri = meta?.[RESOURCE_URI_META_KEY] as string | undefined;
+ const uiUri = uiMeta?.resourceUri ?? legacyUri;
+ if (typeof uiUri === "string" && uiUri.startsWith("ui://")) {
```
This function is important because it defines how MCP Ext Apps Tutorial: Building Interactive MCP Apps and Hosts implements the patterns covered in this chapter.
@@ -212,11 +210,11 @@ This function is important because it defines how MCP Ext Apps Tutorial: Buildin
```mermaid
flowchart TD
- A[AppBridge_teardownResource_gracefulShutdown]
- B[AppBridge_setHostContext_updateTheme]
- C[AppBridge_setHostContext_updateMultiple]
- D[AppBridge_sendToolInput_afterInit]
- E[AppBridge_sendToolInputPartial_streaming]
+ A[DataChunk]
+ B[with]
+ C[RESOURCE_URI_META_KEY_modernFormat]
+ D[RESOURCE_URI_META_KEY_legacyFormat]
+ E[RESOURCE_URI_META_KEY_hostSide]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-ext-apps-tutorial/03-app-sdk-ui-resources-and-tool-linkage.md b/tutorials/mcp-ext-apps-tutorial/03-app-sdk-ui-resources-and-tool-linkage.md
index 3e701476..7d5c5c77 100644
--- a/tutorials/mcp-ext-apps-tutorial/03-app-sdk-ui-resources-and-tool-linkage.md
+++ b/tutorials/mcp-ext-apps-tutorial/03-app-sdk-ui-resources-and-tool-linkage.md
@@ -39,170 +39,168 @@ You now have an app-side implementation model for tool-linked MCP UI resources.
Next: [Chapter 4: Host Bridge and Context Management](04-host-bridge-and-context-management.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `docs/patterns.tsx`
+### `src/app.examples.ts`
-The `binaryBlobResourceServer` function in [`docs/patterns.tsx`](https://github.com/modelcontextprotocol/ext-apps/blob/HEAD/docs/patterns.tsx) handles a key part of this chapter's functionality:
+The `App_oncalltool_handleFromHost` function in [`src/app.examples.ts`](https://github.com/modelcontextprotocol/ext-apps/blob/HEAD/src/app.examples.ts) handles a key part of this chapter's functionality:
-```tsx
- * Example: Serving binary blobs via resources (server-side)
+```ts
+ * Example: Handle tool calls from the host.
*/
-function binaryBlobResourceServer(
- server: McpServer,
- getVideoData: (id: string) => Promise<ArrayBuffer>,
-) {
- //#region binaryBlobResourceServer
- server.registerResource(
- "Video",
- new ResourceTemplate("video://{id}", { list: undefined }),
- {
- description: "Video data served as base64 blob",
- mimeType: "video/mp4",
- },
- async (uri, { id }): Promise<ReadResourceResult> => {
- // Fetch or load your binary data
- const idString = Array.isArray(id) ? id[0] : id;
- const buffer = await getVideoData(idString);
- const blob = Buffer.from(buffer).toString("base64");
-
- return { contents: [{ uri: uri.href, mimeType: "video/mp4", blob }] };
- },
- );
- //#endregion binaryBlobResourceServer
+function App_oncalltool_handleFromHost(app: App) {
+ //#region App_oncalltool_handleFromHost
+ app.oncalltool = async (params, extra) => {
+ if (params.name === "greet") {
+ const name = params.arguments?.name ?? "World";
+ return { content: [{ type: "text", text: `Hello, ${name}!` }] };
+ }
+ throw new Error(`Unknown tool: ${params.name}`);
+ };
+ //#endregion App_oncalltool_handleFromHost
}
/**
- * Example: Serving binary blobs via resources (client-side)
+ * Example: Return available tools from the onlisttools handler.
*/
-async function binaryBlobResourceClient(app: App, videoId: string) {
- //#region binaryBlobResourceClient
- const result = await app.request(
+function App_onlisttools_returnTools(app: App) {
+ //#region App_onlisttools_returnTools
+ app.onlisttools = async (params, extra) => {
+ return {
+ tools: [
+ { name: "greet", inputSchema: { type: "object" as const } },
+ { name: "calculate", inputSchema: { type: "object" as const } },
+ { name: "format", inputSchema: { type: "object" as const } },
+ ],
+ };
+ };
+ //#endregion App_onlisttools_returnTools
+}
+
+/**
```
This function is important because it defines how MCP Ext Apps Tutorial: Building Interactive MCP Apps and Hosts implements the patterns covered in this chapter.
-### `docs/patterns.tsx`
+### `src/app.examples.ts`
-The `binaryBlobResourceClient` function in [`docs/patterns.tsx`](https://github.com/modelcontextprotocol/ext-apps/blob/HEAD/docs/patterns.tsx) handles a key part of this chapter's functionality:
+The `App_onlisttools_returnTools` function in [`src/app.examples.ts`](https://github.com/modelcontextprotocol/ext-apps/blob/HEAD/src/app.examples.ts) handles a key part of this chapter's functionality:
-```tsx
- * Example: Serving binary blobs via resources (client-side)
+```ts
+ * Example: Return available tools from the onlisttools handler.
*/
-async function binaryBlobResourceClient(app: App, videoId: string) {
- //#region binaryBlobResourceClient
- const result = await app.request(
- { method: "resources/read", params: { uri: `video://${videoId}` } },
- ReadResourceResultSchema,
- );
-
- const content = result.contents[0];
- if (!content || !("blob" in content)) {
- throw new Error("Resource did not contain blob data");
- }
-
- const videoEl = document.querySelector("video")!;
- videoEl.src = `data:${content.mimeType!};base64,${content.blob}`;
- //#endregion binaryBlobResourceClient
+function App_onlisttools_returnTools(app: App) {
+ //#region App_onlisttools_returnTools
+ app.onlisttools = async (params, extra) => {
+ return {
+ tools: [
+ { name: "greet", inputSchema: { type: "object" as const } },
+ { name: "calculate", inputSchema: { type: "object" as const } },
+ { name: "format", inputSchema: { type: "object" as const } },
+ ],
+ };
+ };
+ //#endregion App_onlisttools_returnTools
}
/**
- * Example: Adapting to host context (theme, CSS variables, fonts, safe areas)
+ * Example: Fetch updated weather data using callServerTool.
*/
-function hostContextVanillaJs(app: App, mainEl: HTMLElement) {
- //#region hostContextVanillaJs
- function applyHostContext(ctx: McpUiHostContext) {
- if (ctx.theme) {
- applyDocumentTheme(ctx.theme);
+async function App_callServerTool_fetchWeather(app: App) {
+ //#region App_callServerTool_fetchWeather
+ try {
+ const result = await app.callServerTool({
+ name: "get_weather",
+ arguments: { location: "Tokyo" },
+ });
+ if (result.isError) {
+ console.error("Tool returned error:", result.content);
+ } else {
+ console.log(result.content);
}
- if (ctx.styles?.variables) {
- applyHostStyleVariables(ctx.styles.variables);
- }
- if (ctx.styles?.css?.fonts) {
+ } catch (error) {
```
This function is important because it defines how MCP Ext Apps Tutorial: Building Interactive MCP Apps and Hosts implements the patterns covered in this chapter.
-### `docs/patterns.tsx`
+### `src/app.examples.ts`
-The `hostContextVanillaJs` function in [`docs/patterns.tsx`](https://github.com/modelcontextprotocol/ext-apps/blob/HEAD/docs/patterns.tsx) handles a key part of this chapter's functionality:
+The `App_callServerTool_fetchWeather` function in [`src/app.examples.ts`](https://github.com/modelcontextprotocol/ext-apps/blob/HEAD/src/app.examples.ts) handles a key part of this chapter's functionality:
-```tsx
- * Example: Adapting to host context (theme, CSS variables, fonts, safe areas)
+```ts
+ * Example: Fetch updated weather data using callServerTool.
*/
-function hostContextVanillaJs(app: App, mainEl: HTMLElement) {
- //#region hostContextVanillaJs
- function applyHostContext(ctx: McpUiHostContext) {
- if (ctx.theme) {
- applyDocumentTheme(ctx.theme);
- }
- if (ctx.styles?.variables) {
- applyHostStyleVariables(ctx.styles.variables);
- }
- if (ctx.styles?.css?.fonts) {
- applyHostFonts(ctx.styles.css.fonts);
- }
- if (ctx.safeAreaInsets) {
- mainEl.style.paddingTop = `${ctx.safeAreaInsets.top}px`;
- mainEl.style.paddingRight = `${ctx.safeAreaInsets.right}px`;
- mainEl.style.paddingBottom = `${ctx.safeAreaInsets.bottom}px`;
- mainEl.style.paddingLeft = `${ctx.safeAreaInsets.left}px`;
+async function App_callServerTool_fetchWeather(app: App) {
+ //#region App_callServerTool_fetchWeather
+ try {
+ const result = await app.callServerTool({
+ name: "get_weather",
+ arguments: { location: "Tokyo" },
+ });
+ if (result.isError) {
+ console.error("Tool returned error:", result.content);
+ } else {
+ console.log(result.content);
}
+ } catch (error) {
+ console.error("Tool call failed:", error);
}
+ //#endregion App_callServerTool_fetchWeather
+}
- // Apply when host context changes
- app.onhostcontextchanged = applyHostContext;
-
- // Apply initial context after connecting
- app.connect().then(() => {
- const ctx = app.getHostContext();
- if (ctx) {
- applyHostContext(ctx);
- }
- });
+/**
+ * Example: Read a video resource and play it.
+ */
+async function App_readServerResource_playVideo(
+ app: App,
+ videoElement: HTMLVideoElement,
+) {
+ //#region App_readServerResource_playVideo
+ try {
+ const result = await app.readServerResource({
+ uri: "videos://bunny-1mb",
+ });
```
This function is important because it defines how MCP Ext Apps Tutorial: Building Interactive MCP Apps and Hosts implements the patterns covered in this chapter.
-### `docs/patterns.tsx`
+### `src/app.examples.ts`
-The `applyHostContext` function in [`docs/patterns.tsx`](https://github.com/modelcontextprotocol/ext-apps/blob/HEAD/docs/patterns.tsx) handles a key part of this chapter's functionality:
+The `App_readServerResource_playVideo` function in [`src/app.examples.ts`](https://github.com/modelcontextprotocol/ext-apps/blob/HEAD/src/app.examples.ts) handles a key part of this chapter's functionality:
-```tsx
-function hostContextVanillaJs(app: App, mainEl: HTMLElement) {
- //#region hostContextVanillaJs
- function applyHostContext(ctx: McpUiHostContext) {
- if (ctx.theme) {
- applyDocumentTheme(ctx.theme);
- }
- if (ctx.styles?.variables) {
- applyHostStyleVariables(ctx.styles.variables);
- }
- if (ctx.styles?.css?.fonts) {
- applyHostFonts(ctx.styles.css.fonts);
- }
- if (ctx.safeAreaInsets) {
- mainEl.style.paddingTop = `${ctx.safeAreaInsets.top}px`;
- mainEl.style.paddingRight = `${ctx.safeAreaInsets.right}px`;
- mainEl.style.paddingBottom = `${ctx.safeAreaInsets.bottom}px`;
- mainEl.style.paddingLeft = `${ctx.safeAreaInsets.left}px`;
+```ts
+ * Example: Read a video resource and play it.
+ */
+async function App_readServerResource_playVideo(
+ app: App,
+ videoElement: HTMLVideoElement,
+) {
+ //#region App_readServerResource_playVideo
+ try {
+ const result = await app.readServerResource({
+ uri: "videos://bunny-1mb",
+ });
+ const content = result.contents[0];
+ if (content && "blob" in content) {
+ const binary = Uint8Array.from(atob(content.blob), (c) =>
+ c.charCodeAt(0),
+ );
+ const url = URL.createObjectURL(
+ new Blob([binary], { type: content.mimeType || "video/mp4" }),
+ );
+ videoElement.src = url;
+ videoElement.play();
}
+ } catch (error) {
+ console.error("Failed to read resource:", error);
}
-
- // Apply when host context changes
- app.onhostcontextchanged = applyHostContext;
-
- // Apply initial context after connecting
- app.connect().then(() => {
- const ctx = app.getHostContext();
- if (ctx) {
- applyHostContext(ctx);
- }
- });
- //#endregion hostContextVanillaJs
+ //#endregion App_readServerResource_playVideo
}
+
+/**
+ * Example: Discover available videos and build a picker UI.
+ */
+async function App_listServerResources_buildPicker(
```
This function is important because it defines how MCP Ext Apps Tutorial: Building Interactive MCP Apps and Hosts implements the patterns covered in this chapter.
@@ -212,11 +210,11 @@ This function is important because it defines how MCP Ext Apps Tutorial: Buildin
```mermaid
flowchart TD
- A[binaryBlobResourceServer]
- B[binaryBlobResourceClient]
- C[hostContextVanillaJs]
- D[applyHostContext]
- E[hostContextReact]
+ A[App_oncalltool_handleFromHost]
+ B[App_onlisttools_returnTools]
+ C[App_callServerTool_fetchWeather]
+ D[App_readServerResource_playVideo]
+ E[App_listServerResources_buildPicker]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-ext-apps-tutorial/04-host-bridge-and-context-management.md b/tutorials/mcp-ext-apps-tutorial/04-host-bridge-and-context-management.md
index 701852b3..47a93fec 100644
--- a/tutorials/mcp-ext-apps-tutorial/04-host-bridge-and-context-management.md
+++ b/tutorials/mcp-ext-apps-tutorial/04-host-bridge-and-context-management.md
@@ -41,170 +41,168 @@ You now have a host-bridge model for secure MCP Apps embedding.
Next: [Chapter 5: Patterns, Security, and Performance](05-patterns-security-and-performance.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `scripts/sync-snippets.ts`
-The `LabeledCodeFence` interface in [`scripts/sync-snippets.ts`](https://github.com/modelcontextprotocol/ext-apps/blob/HEAD/scripts/sync-snippets.ts) handles a key part of this chapter's functionality:
+The `processFile` function in [`scripts/sync-snippets.ts`](https://github.com/modelcontextprotocol/ext-apps/blob/HEAD/scripts/sync-snippets.ts) handles a key part of this chapter's functionality:
```ts
- * Represents a labeled code fence found in a source file.
- */
-interface LabeledCodeFence {
- /** Optional display filename (e.g., "my-app.ts") */
- displayName?: string;
- /** Relative path to the example file (e.g., "./app.examples.ts") */
- examplePath: string;
- /** Region name (e.g., "App_basicUsage"), or undefined for whole file */
- regionName?: string;
- /** Language from the code fence (e.g., "ts", "json", "yaml") */
- language: string;
- /** Character index of the opening fence line start */
- openingFenceStart: number;
- /** Character index after the opening fence line (after newline) */
- openingFenceEnd: number;
- /** Character index of the closing fence line start */
- closingFenceStart: number;
- /** The JSDoc line prefix extracted from context (e.g., " * ") */
- linePrefix: string;
-}
-
-/**
- * Cache for example file regions to avoid re-reading files.
- * Key: `${absoluteExamplePath}#${regionName}` (empty regionName for whole file)
- * Value: extracted code string
+ * @returns The processing result
*/
-type RegionCache = Map<string, string>;
-
-/**
- * Processing result for a source file.
- */
-interface FileProcessingResult {
+function processFile(
+ filePath: string,
+ cache: RegionCache,
+ mode: FileMode,
+): FileProcessingResult {
+ const result: FileProcessingResult = {
+ filePath,
+ modified: false,
+ snippetsProcessed: 0,
+ errors: [],
+ };
+
+ let content: string;
+ try {
+ content = readFileSync(filePath, "utf-8");
+ } catch (err) {
+ result.errors.push(`Failed to read file: ${err}`);
+ return result;
+ }
+
+ let fences: LabeledCodeFence[];
+ try {
+ fences = findLabeledCodeFences(content, filePath, mode);
+ } catch (err) {
+ result.errors.push(err instanceof Error ? err.message : String(err));
+ return result;
+ }
+
+ if (fences.length === 0) {
+ return result;
```
-This interface is important because it defines how MCP Ext Apps Tutorial: Building Interactive MCP Apps and Hosts implements the patterns covered in this chapter.
+This function is important because it defines how MCP Ext Apps Tutorial: Building Interactive MCP Apps and Hosts implements the patterns covered in this chapter.
### `scripts/sync-snippets.ts`
-The `FileProcessingResult` interface in [`scripts/sync-snippets.ts`](https://github.com/modelcontextprotocol/ext-apps/blob/HEAD/scripts/sync-snippets.ts) handles a key part of this chapter's functionality:
+The `findSourceFiles` function in [`scripts/sync-snippets.ts`](https://github.com/modelcontextprotocol/ext-apps/blob/HEAD/scripts/sync-snippets.ts) handles a key part of this chapter's functionality:
```ts
- * Processing result for a source file.
+ * @returns Array of absolute file paths
*/
-interface FileProcessingResult {
- filePath: string;
- modified: boolean;
- snippetsProcessed: number;
- errors: string[];
-}
+function findSourceFiles(dir: string): string[] {
+ const files: string[] = [];
+ const entries = readdirSync(dir, { withFileTypes: true, recursive: true });
-// JSDoc patterns - for code fences inside JSDoc comments with " * " prefix
-// Matches: <prefix>```<lang> [displayName] source="<path>" or source="<path>#<region>"
-// Example: " * ```ts my-app.ts source="./app.examples.ts#App_basicUsage""
-// Example: " * ```ts source="./app.examples.ts#App_basicUsage""
-// Example: " * ```ts source="./complete-example.ts"" (whole file)
-const JSDOC_LABELED_FENCE_PATTERN =
- /^(\s*\*\s*)```(\w+)(?:\s+(\S+))?\s+source="([^"#]+)(?:#([^"]+))?"/;
-const JSDOC_CLOSING_FENCE_PATTERN = /^(\s*\*\s*)```\s*$/;
-
-// Markdown patterns - for plain code fences in markdown files (no prefix)
-// Matches: ```<lang> [displayName] source="<path>" or source="<path>#<region>"
-// Example: ```tsx source="./patterns.tsx#chunkedDataServer"
-// Example: ```tsx source="./complete-example.tsx" (whole file)
-const MARKDOWN_LABELED_FENCE_PATTERN =
- /^```(\w+)(?:\s+(\S+))?\s+source="([^"#]+)(?:#([^"]+))?"/;
-const MARKDOWN_CLOSING_FENCE_PATTERN = /^```\s*$/;
-
-/**
- * Find all labeled code fences in a source file.
- * @param content The file content
- * @param filePath The file path (for error messages)
- * @param mode The processing mode (jsdoc or markdown)
- * @returns Array of labeled code fence references
+ for (const entry of entries) {
+ if (!entry.isFile()) continue;
+
+ const name = entry.name;
+
+ // Only process .ts and .tsx files
+ if (!name.endsWith(".ts") && !name.endsWith(".tsx")) continue;
+
+ // Exclude example files, test files
+ if (name.endsWith(".examples.ts") || name.endsWith(".examples.tsx"))
+ continue;
+ if (name.endsWith(".test.ts")) continue;
+
+ // Get the relative path from the parent directory
+ const parentPath = entry.parentPath;
+
+ // Exclude generated directory
+ if (parentPath.includes("/generated") || parentPath.includes("\\generated"))
+ continue;
+
+ const fullPath = join(parentPath, name);
+ files.push(fullPath);
+ }
+
+ return files;
+}
```
-This interface is important because it defines how MCP Ext Apps Tutorial: Building Interactive MCP Apps and Hosts implements the patterns covered in this chapter.
+This function is important because it defines how MCP Ext Apps Tutorial: Building Interactive MCP Apps and Hosts implements the patterns covered in this chapter.
-### `src/app.examples.ts`
+### `scripts/sync-snippets.ts`
-The `with` class in [`src/app.examples.ts`](https://github.com/modelcontextprotocol/ext-apps/blob/HEAD/src/app.examples.ts) handles a key part of this chapter's functionality:
+The `findMarkdownFiles` function in [`scripts/sync-snippets.ts`](https://github.com/modelcontextprotocol/ext-apps/blob/HEAD/scripts/sync-snippets.ts) handles a key part of this chapter's functionality:
```ts
-
-/**
- * Example: Modern format for registering tools with UI (recommended).
+ * @returns Array of absolute file paths
*/
-function RESOURCE_URI_META_KEY_modernFormat(
- server: McpServer,
- handler: ToolCallback,
-) {
- //#region RESOURCE_URI_META_KEY_modernFormat
- // Preferred: Use registerAppTool with nested ui.resourceUri
- registerAppTool(
- server,
- "weather",
- {
- description: "Get weather forecast",
- _meta: {
- ui: { resourceUri: "ui://weather/forecast" },
- },
- },
- handler,
- );
- //#endregion RESOURCE_URI_META_KEY_modernFormat
+function findMarkdownFiles(dir: string): string[] {
+ const files: string[] = [];
+ const entries = readdirSync(dir, { withFileTypes: true, recursive: true });
+
+ for (const entry of entries) {
+ if (!entry.isFile()) continue;
+
+ // Only process .md files
+ if (!entry.name.endsWith(".md")) continue;
+
+ const fullPath = join(entry.parentPath, entry.name);
+ files.push(fullPath);
+ }
+
+ return files;
}
-/**
- * Example: Legacy format using RESOURCE_URI_META_KEY (deprecated).
- */
-function RESOURCE_URI_META_KEY_legacyFormat(
- server: McpServer,
- handler: ToolCallback,
-) {
- //#region RESOURCE_URI_META_KEY_legacyFormat
+async function main() {
+ console.log("🔧 Syncing code snippets from example files...\n");
+
+ const cache: RegionCache = new Map();
+ const results: FileProcessingResult[] = [];
+
+ // Process TypeScript source files (JSDoc mode)
+ const sourceFiles = findSourceFiles(SRC_DIR);
+ for (const filePath of sourceFiles) {
+ const result = processFile(filePath, cache, "jsdoc");
+ results.push(result);
+ }
+
```
-This class is important because it defines how MCP Ext Apps Tutorial: Building Interactive MCP Apps and Hosts implements the patterns covered in this chapter.
+This function is important because it defines how MCP Ext Apps Tutorial: Building Interactive MCP Apps and Hosts implements the patterns covered in this chapter.
-### `src/app.examples.ts`
+### `scripts/sync-snippets.ts`
-The `RESOURCE_URI_META_KEY_modernFormat` function in [`src/app.examples.ts`](https://github.com/modelcontextprotocol/ext-apps/blob/HEAD/src/app.examples.ts) handles a key part of this chapter's functionality:
+The `main` function in [`scripts/sync-snippets.ts`](https://github.com/modelcontextprotocol/ext-apps/blob/HEAD/scripts/sync-snippets.ts) handles a key part of this chapter's functionality:
```ts
- * Example: Modern format for registering tools with UI (recommended).
- */
-function RESOURCE_URI_META_KEY_modernFormat(
- server: McpServer,
- handler: ToolCallback,
-) {
- //#region RESOURCE_URI_META_KEY_modernFormat
- // Preferred: Use registerAppTool with nested ui.resourceUri
- registerAppTool(
- server,
- "weather",
- {
- description: "Get weather forecast",
- _meta: {
- ui: { resourceUri: "ui://weather/forecast" },
- },
- },
- handler,
- );
- //#endregion RESOURCE_URI_META_KEY_modernFormat
}
-/**
- * Example: Legacy format using RESOURCE_URI_META_KEY (deprecated).
- */
-function RESOURCE_URI_META_KEY_legacyFormat(
- server: McpServer,
- handler: ToolCallback,
-) {
- //#region RESOURCE_URI_META_KEY_legacyFormat
- // Deprecated: Direct use of RESOURCE_URI_META_KEY
- server.registerTool(
+async function main() {
+ console.log("🔧 Syncing code snippets from example files...\n");
+
+ const cache: RegionCache = new Map();
+ const results: FileProcessingResult[] = [];
+
+ // Process TypeScript source files (JSDoc mode)
+ const sourceFiles = findSourceFiles(SRC_DIR);
+ for (const filePath of sourceFiles) {
+ const result = processFile(filePath, cache, "jsdoc");
+ results.push(result);
+ }
+
+ // Process markdown documentation files
+ const markdownFiles = findMarkdownFiles(DOCS_DIR);
+ for (const filePath of markdownFiles) {
+ const result = processFile(filePath, cache, "markdown");
+ results.push(result);
+ }
+
+ // Report results
+ const modified = results.filter((r) => r.modified);
+ const errors = results.flatMap((r) => r.errors);
+
+ if (modified.length > 0) {
+ console.log(`✅ Modified ${modified.length} file(s):`);
+ for (const r of modified) {
+ console.log(` ${r.filePath} (${r.snippetsProcessed} snippet(s))`);
+ }
+ } else {
```
This function is important because it defines how MCP Ext Apps Tutorial: Building Interactive MCP Apps and Hosts implements the patterns covered in this chapter.
@@ -214,11 +212,11 @@ This function is important because it defines how MCP Ext Apps Tutorial: Buildin
```mermaid
flowchart TD
- A[LabeledCodeFence]
- B[FileProcessingResult]
- C[with]
- D[RESOURCE_URI_META_KEY_modernFormat]
- E[RESOURCE_URI_META_KEY_legacyFormat]
+ A[processFile]
+ B[findSourceFiles]
+ C[findMarkdownFiles]
+ D[main]
+ E[LabeledCodeFence]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-ext-apps-tutorial/05-patterns-security-and-performance.md b/tutorials/mcp-ext-apps-tutorial/05-patterns-security-and-performance.md
index cca28f8f..fd344364 100644
--- a/tutorials/mcp-ext-apps-tutorial/05-patterns-security-and-performance.md
+++ b/tutorials/mcp-ext-apps-tutorial/05-patterns-security-and-performance.md
@@ -40,170 +40,168 @@ You now have a practical pattern library for secure, performant MCP Apps.
Next: [Chapter 6: Testing, Local Hosts, and Integration Workflows](06-testing-local-hosts-and-integration-workflows.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/app.examples.ts`
+### `src/app-bridge.examples.ts`
-The `closeConnections` function in [`src/app.examples.ts`](https://github.com/modelcontextprotocol/ext-apps/blob/HEAD/src/app.examples.ts) handles a key part of this chapter's functionality:
+The `AppBridge_onreadresource_returnResource` function in [`src/app-bridge.examples.ts`](https://github.com/modelcontextprotocol/ext-apps/blob/HEAD/src/app-bridge.examples.ts) handles a key part of this chapter's functionality:
```ts
- app.onteardown = async () => {
- await saveState();
- closeConnections();
- console.log("App ready for teardown");
- return {};
- };
- //#endregion App_onteardown_performCleanup
-}
-
-// Stubs for example
-declare function saveState(): Promise<void>;
-declare function closeConnections(): void;
-
-/**
- * Example: Handle tool calls from the host.
+ * Example: Forward read resource requests to the MCP server.
*/
-function App_oncalltool_handleFromHost(app: App) {
- //#region App_oncalltool_handleFromHost
- app.oncalltool = async (params, extra) => {
- if (params.name === "greet") {
- const name = params.arguments?.name ?? "World";
- return { content: [{ type: "text", text: `Hello, ${name}!` }] };
- }
- throw new Error(`Unknown tool: ${params.name}`);
+function AppBridge_onreadresource_returnResource(
+ bridge: AppBridge,
+ mcpClient: Client,
+) {
+ //#region AppBridge_onreadresource_returnResource
+ bridge.onreadresource = async (params, extra) => {
+ return mcpClient.request(
+ { method: "resources/read", params },
+ ReadResourceResultSchema,
+ { signal: extra.signal },
+ );
};
- //#endregion App_oncalltool_handleFromHost
+ //#endregion AppBridge_onreadresource_returnResource
}
/**
- * Example: Return available tools from the onlisttools handler.
+ * Example: Forward list prompts requests to the MCP server.
*/
-function App_onlisttools_returnTools(app: App) {
+function AppBridge_onlistprompts_returnPrompts(
+ bridge: AppBridge,
+ mcpClient: Client,
+) {
+ //#region AppBridge_onlistprompts_returnPrompts
+ bridge.onlistprompts = async (params, extra) => {
+ return mcpClient.request(
+ { method: "prompts/list", params },
+ ListPromptsResultSchema,
+ { signal: extra.signal },
+ );
+ };
```
This function is important because it defines how MCP Ext Apps Tutorial: Building Interactive MCP Apps and Hosts implements the patterns covered in this chapter.
-### `src/app.examples.ts`
+### `src/app-bridge.examples.ts`
-The `App_oncalltool_handleFromHost` function in [`src/app.examples.ts`](https://github.com/modelcontextprotocol/ext-apps/blob/HEAD/src/app.examples.ts) handles a key part of this chapter's functionality:
+The `AppBridge_onlistprompts_returnPrompts` function in [`src/app-bridge.examples.ts`](https://github.com/modelcontextprotocol/ext-apps/blob/HEAD/src/app-bridge.examples.ts) handles a key part of this chapter's functionality:
```ts
- * Example: Handle tool calls from the host.
+ * Example: Forward list prompts requests to the MCP server.
*/
-function App_oncalltool_handleFromHost(app: App) {
- //#region App_oncalltool_handleFromHost
- app.oncalltool = async (params, extra) => {
- if (params.name === "greet") {
- const name = params.arguments?.name ?? "World";
- return { content: [{ type: "text", text: `Hello, ${name}!` }] };
- }
- throw new Error(`Unknown tool: ${params.name}`);
+function AppBridge_onlistprompts_returnPrompts(
+ bridge: AppBridge,
+ mcpClient: Client,
+) {
+ //#region AppBridge_onlistprompts_returnPrompts
+ bridge.onlistprompts = async (params, extra) => {
+ return mcpClient.request(
+ { method: "prompts/list", params },
+ ListPromptsResultSchema,
+ { signal: extra.signal },
+ );
};
- //#endregion App_oncalltool_handleFromHost
+ //#endregion AppBridge_onlistprompts_returnPrompts
}
/**
- * Example: Return available tools from the onlisttools handler.
+ * Example: Handle ping requests from the View.
*/
-function App_onlisttools_returnTools(app: App) {
- //#region App_onlisttools_returnTools
- app.onlisttools = async (params, extra) => {
- return {
- tools: ["greet", "calculate", "format"],
- };
+function AppBridge_onping_handleRequest(bridge: AppBridge) {
+ //#region AppBridge_onping_handleRequest
+ bridge.onping = (params, extra) => {
+ console.log("Received ping from view");
};
- //#endregion App_onlisttools_returnTools
+ //#endregion AppBridge_onping_handleRequest
}
/**
- * Example: Fetch updated weather data using callServerTool.
+ * Example: Handle size change notifications from the View.
*/
-async function App_callServerTool_fetchWeather(app: App) {
- //#region App_callServerTool_fetchWeather
+function AppBridge_onsizechange_handleResize(
```
This function is important because it defines how MCP Ext Apps Tutorial: Building Interactive MCP Apps and Hosts implements the patterns covered in this chapter.
-### `src/app.examples.ts`
+### `src/app-bridge.examples.ts`
-The `App_onlisttools_returnTools` function in [`src/app.examples.ts`](https://github.com/modelcontextprotocol/ext-apps/blob/HEAD/src/app.examples.ts) handles a key part of this chapter's functionality:
+The `AppBridge_onping_handleRequest` function in [`src/app-bridge.examples.ts`](https://github.com/modelcontextprotocol/ext-apps/blob/HEAD/src/app-bridge.examples.ts) handles a key part of this chapter's functionality:
```ts
- * Example: Return available tools from the onlisttools handler.
+ * Example: Handle ping requests from the View.
*/
-function App_onlisttools_returnTools(app: App) {
- //#region App_onlisttools_returnTools
- app.onlisttools = async (params, extra) => {
- return {
- tools: ["greet", "calculate", "format"],
- };
+function AppBridge_onping_handleRequest(bridge: AppBridge) {
+ //#region AppBridge_onping_handleRequest
+ bridge.onping = (params, extra) => {
+ console.log("Received ping from view");
};
- //#endregion App_onlisttools_returnTools
+ //#endregion AppBridge_onping_handleRequest
}
/**
- * Example: Fetch updated weather data using callServerTool.
+ * Example: Handle size change notifications from the View.
*/
-async function App_callServerTool_fetchWeather(app: App) {
- //#region App_callServerTool_fetchWeather
- try {
- const result = await app.callServerTool({
- name: "get_weather",
- arguments: { location: "Tokyo" },
- });
- if (result.isError) {
- console.error("Tool returned error:", result.content);
- } else {
- console.log(result.content);
+function AppBridge_onsizechange_handleResize(
+ bridge: AppBridge,
+ iframe: HTMLIFrameElement,
+) {
+ //#region AppBridge_onsizechange_handleResize
+ bridge.onsizechange = ({ width, height }) => {
+ if (width != null) {
+ iframe.style.width = `${width}px`;
+ }
+ if (height != null) {
+ iframe.style.height = `${height}px`;
}
- } catch (error) {
- console.error("Tool call failed:", error);
- }
- //#endregion App_callServerTool_fetchWeather
+ };
+ //#endregion AppBridge_onsizechange_handleResize
}
+
+/**
+ * Example: Handle display mode requests from the View.
+ */
```
This function is important because it defines how MCP Ext Apps Tutorial: Building Interactive MCP Apps and Hosts implements the patterns covered in this chapter.
-### `src/app.examples.ts`
+### `src/app-bridge.examples.ts`
-The `App_callServerTool_fetchWeather` function in [`src/app.examples.ts`](https://github.com/modelcontextprotocol/ext-apps/blob/HEAD/src/app.examples.ts) handles a key part of this chapter's functionality:
+The `AppBridge_onsizechange_handleResize` function in [`src/app-bridge.examples.ts`](https://github.com/modelcontextprotocol/ext-apps/blob/HEAD/src/app-bridge.examples.ts) handles a key part of this chapter's functionality:
```ts
- * Example: Fetch updated weather data using callServerTool.
+ * Example: Handle size change notifications from the View.
*/
-async function App_callServerTool_fetchWeather(app: App) {
- //#region App_callServerTool_fetchWeather
- try {
- const result = await app.callServerTool({
- name: "get_weather",
- arguments: { location: "Tokyo" },
- });
- if (result.isError) {
- console.error("Tool returned error:", result.content);
- } else {
- console.log(result.content);
+function AppBridge_onsizechange_handleResize(
+ bridge: AppBridge,
+ iframe: HTMLIFrameElement,
+) {
+ //#region AppBridge_onsizechange_handleResize
+ bridge.onsizechange = ({ width, height }) => {
+ if (width != null) {
+ iframe.style.width = `${width}px`;
+ }
+ if (height != null) {
+ iframe.style.height = `${height}px`;
}
- } catch (error) {
- console.error("Tool call failed:", error);
- }
- //#endregion App_callServerTool_fetchWeather
+ };
+ //#endregion AppBridge_onsizechange_handleResize
}
/**
- * Example: Read a video resource and play it.
+ * Example: Handle display mode requests from the View.
*/
-async function App_readServerResource_playVideo(
- app: App,
- videoElement: HTMLVideoElement,
+function AppBridge_onrequestdisplaymode_handleRequest(
+ bridge: AppBridge,
+ currentDisplayMode: McpUiDisplayMode,
+ availableDisplayModes: McpUiDisplayMode[],
) {
- //#region App_readServerResource_playVideo
- try {
- const result = await app.readServerResource({
- uri: "videos://bunny-1mb",
- });
+ //#region AppBridge_onrequestdisplaymode_handleRequest
+ bridge.onrequestdisplaymode = async ({ mode }, extra) => {
+ if (availableDisplayModes.includes(mode)) {
+ currentDisplayMode = mode;
+ }
+ return { mode: currentDisplayMode };
```
This function is important because it defines how MCP Ext Apps Tutorial: Building Interactive MCP Apps and Hosts implements the patterns covered in this chapter.
@@ -213,11 +211,11 @@ This function is important because it defines how MCP Ext Apps Tutorial: Buildin
```mermaid
flowchart TD
- A[closeConnections]
- B[App_oncalltool_handleFromHost]
- C[App_onlisttools_returnTools]
- D[App_callServerTool_fetchWeather]
- E[App_readServerResource_playVideo]
+ A[AppBridge_onreadresource_returnResource]
+ B[AppBridge_onlistprompts_returnPrompts]
+ C[AppBridge_onping_handleRequest]
+ D[AppBridge_onsizechange_handleResize]
+ E[AppBridge_onrequestdisplaymode_handleRequest]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-ext-apps-tutorial/06-testing-local-hosts-and-integration-workflows.md b/tutorials/mcp-ext-apps-tutorial/06-testing-local-hosts-and-integration-workflows.md
index 13d13d33..5af96c00 100644
--- a/tutorials/mcp-ext-apps-tutorial/06-testing-local-hosts-and-integration-workflows.md
+++ b/tutorials/mcp-ext-apps-tutorial/06-testing-local-hosts-and-integration-workflows.md
@@ -40,164 +40,182 @@ You now have a repeatable validation workflow for MCP Apps integration quality.
Next: [Chapter 7: Agent Skills and OpenAI Apps Migration](07-agent-skills-and-openai-apps-migration.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/message-transport.examples.ts`
+### `src/events.ts`
-The `PostMessageTransport_constructor_host` function in [`src/message-transport.examples.ts`](https://github.com/modelcontextprotocol/ext-apps/blob/HEAD/src/message-transport.examples.ts) handles a key part of this chapter's functionality:
+The `side` class in [`src/events.ts`](https://github.com/modelcontextprotocol/ext-apps/blob/HEAD/src/events.ts) handles a key part of this chapter's functionality:
```ts
- * Example: Creating transport for host (constructor only).
+ *
+ * When a notification arrives for a mapped event:
+ * 1. {@link onEventDispatch `onEventDispatch`} (subclass side-effects)
+ * 2. The singular `on*` handler (if set)
+ * 3. All `addEventListener` listeners in insertion order
+ *
+ * ### Double-set protection
+ *
+ * Direct calls to {@link setRequestHandler `setRequestHandler`} /
+ * {@link setNotificationHandler `setNotificationHandler`} throw if a handler
+ * for the same method has already been registered (through any path), so
+ * accidental overwrites surface as errors instead of silent bugs.
+ *
+ * @typeParam EventMap - Maps event names to the listener's `params` type.
*/
-function PostMessageTransport_constructor_host() {
- //#region PostMessageTransport_constructor_host
- const iframe = document.getElementById("app-iframe") as HTMLIFrameElement;
- const transport = new PostMessageTransport(
- iframe.contentWindow!,
- iframe.contentWindow!,
- );
- //#endregion PostMessageTransport_constructor_host
-}
-
+export abstract class ProtocolWithEvents<
+ SendRequestT extends Request,
+ SendNotificationT extends Notification,
+ SendResultT extends Result,
+ EventMap extends Record<string, unknown>,
+> extends Protocol<SendRequestT, SendNotificationT, SendResultT> {
+ private _registeredMethods = new Set<string>();
+ private _eventSlots = new Map<keyof EventMap, EventSlot>();
+
+ /**
+ * Event name → notification schema. Subclasses populate this so that
+ * the event system can lazily register a dispatcher with the correct
+ * schema on first use.
+ */
+ protected abstract readonly eventSchemas: {
+ [K in keyof EventMap]: MethodSchema;
+ };
```
-This function is important because it defines how MCP Ext Apps Tutorial: Building Interactive MCP Apps and Hosts implements the patterns covered in this chapter.
+This class is important because it defines how MCP Ext Apps Tutorial: Building Interactive MCP Apps and Hosts implements the patterns covered in this chapter.
-### `scripts/generate-schemas.ts`
+### `src/events.ts`
-The `main` function in [`scripts/generate-schemas.ts`](https://github.com/modelcontextprotocol/ext-apps/blob/HEAD/scripts/generate-schemas.ts) handles a key part of this chapter's functionality:
+The `ProtocolWithEvents` class in [`src/events.ts`](https://github.com/modelcontextprotocol/ext-apps/blob/HEAD/src/events.ts) handles a key part of this chapter's functionality:
```ts
-];
-
-async function main() {
- console.log("🔧 Generating Zod schemas from spec.types.ts...\n");
-
- const sourceText = readFileSync(SPEC_TYPES_FILE, "utf-8");
-
- const result = generate({
- sourceText,
- keepComments: true,
- skipParseJSDoc: false,
- // Generate PascalCase schema names: McpUiOpenLinkRequest → McpUiOpenLinkRequestSchema
- getSchemaName: (typeName: string) => `${typeName}Schema`,
- });
-
- if (result.errors.length > 0) {
- console.error("❌ Generation errors:");
- for (const error of result.errors) {
- console.error(` - ${error}`);
- }
- process.exit(1);
- }
-
- if (result.hasCircularDependencies) {
- console.warn("⚠️ Warning: Circular dependencies detected in types");
- }
-
- let schemasContent = result.getZodSchemasFile("../spec.types.js");
- schemasContent = postProcess(schemasContent);
-
- writeFileSync(SCHEMA_OUTPUT_FILE, schemasContent, "utf-8");
- console.log(`✅ Written: ${SCHEMA_OUTPUT_FILE}`);
-```
+ * @typeParam EventMap - Maps event names to the listener's `params` type.
+ */
+export abstract class ProtocolWithEvents<
+ SendRequestT extends Request,
+ SendNotificationT extends Notification,
+ SendResultT extends Result,
+ EventMap extends Record<string, unknown>,
+> extends Protocol<SendRequestT, SendNotificationT, SendResultT> {
+ private _registeredMethods = new Set<string>();
+ private _eventSlots = new Map<keyof EventMap, EventSlot>();
+
+ /**
+ * Event name → notification schema. Subclasses populate this so that
+ * the event system can lazily register a dispatcher with the correct
+ * schema on first use.
+ */
+ protected abstract readonly eventSchemas: {
+ [K in keyof EventMap]: MethodSchema;
+ };
-This function is important because it defines how MCP Ext Apps Tutorial: Building Interactive MCP Apps and Hosts implements the patterns covered in this chapter.
+ /**
+ * Called once per incoming notification, before any handlers or listeners
+ * fire. Subclasses may override to perform side effects such as merging
+ * notification params into cached state.
+ */
+ protected onEventDispatch<K extends keyof EventMap>(
+ _event: K,
+ _params: EventMap[K],
+ ): void {}
-### `scripts/generate-schemas.ts`
+ // ── Event system (DOM model) ────────────────────────────────────────
-The `generateJsonSchema` function in [`scripts/generate-schemas.ts`](https://github.com/modelcontextprotocol/ext-apps/blob/HEAD/scripts/generate-schemas.ts) handles a key part of this chapter's functionality:
+```
-```ts
+This class is important because it defines how MCP Ext Apps Tutorial: Building Interactive MCP Apps and Hosts implements the patterns covered in this chapter.
- // Generate JSON Schema from the Zod schemas
- await generateJsonSchema();
+### `src/events.ts`
- console.log("\n🎉 Schema generation complete!");
-}
+The `fields` class in [`src/events.ts`](https://github.com/modelcontextprotocol/ext-apps/blob/HEAD/src/events.ts) handles a key part of this chapter's functionality:
-/**
- * Generate JSON Schema from the Zod schemas.
- * Uses dynamic import to load the generated schemas after they're written.
- */
-async function generateJsonSchema() {
- // Dynamic import of the generated schemas
- // tsx handles TypeScript imports at runtime
- const schemas = await import("../src/generated/schema.js");
-
- const jsonSchema: {
- $schema: string;
- $id: string;
- title: string;
- description: string;
- $defs: Record<string, unknown>;
- } = {
- $schema: "https://json-schema.org/draft/2020-12/schema",
- $id: "https://modelcontextprotocol.io/ext-apps/schema.json",
- title: "MCP Apps Protocol",
- description: "JSON Schema for MCP Apps UI protocol messages",
- $defs: {},
+```ts
+ // ── Handler registration with double-set protection ─────────────────
+
+ // The two overrides below are arrow-function class fields rather than
+ // prototype methods so that Protocol's constructor — which registers its
+ // own ping/cancelled/progress handlers via `this.setRequestHandler`
+ // before our fields initialize — hits the base implementation and skips
+ // tracking. Converting these to proper methods would crash with
+ // `_registeredMethods` undefined during super().
+
+ /**
+ * Registers a request handler. Throws if a handler for the same method
+ * has already been registered — use the `on*` setter (replace semantics)
+ * or `addEventListener` (multi-listener) for notification events.
+ *
+ * @throws {Error} if a handler for this method is already registered.
+ */
+ override setRequestHandler: Protocol<
+ SendRequestT,
+ SendNotificationT,
+ SendResultT
+ >["setRequestHandler"] = (schema, handler) => {
+ this._assertMethodNotRegistered(schema, "setRequestHandler");
+ super.setRequestHandler(schema, handler);
};
- // Convert each exported Zod schema to JSON Schema
- for (const [name, schema] of Object.entries(schemas)) {
+ /**
+ * Registers a notification handler. Throws if a handler for the same
+ * method has already been registered — use the `on*` setter (replace
+ * semantics) or `addEventListener` (multi-listener) for mapped events.
+ *
+ * @throws {Error} if a handler for this method is already registered.
+ */
```
-This function is important because it defines how MCP Ext Apps Tutorial: Building Interactive MCP Apps and Hosts implements the patterns covered in this chapter.
+This class is important because it defines how MCP Ext Apps Tutorial: Building Interactive MCP Apps and Hosts implements the patterns covered in this chapter.
-### `scripts/generate-schemas.ts`
+### `src/events.ts`
-The `postProcess` function in [`scripts/generate-schemas.ts`](https://github.com/modelcontextprotocol/ext-apps/blob/HEAD/scripts/generate-schemas.ts) handles a key part of this chapter's functionality:
+The `EventSlot` interface in [`src/events.ts`](https://github.com/modelcontextprotocol/ext-apps/blob/HEAD/src/events.ts) handles a key part of this chapter's functionality:
```ts
-
- let schemasContent = result.getZodSchemasFile("../spec.types.js");
- schemasContent = postProcess(schemasContent);
-
- writeFileSync(SCHEMA_OUTPUT_FILE, schemasContent, "utf-8");
- console.log(`✅ Written: ${SCHEMA_OUTPUT_FILE}`);
-
- const testsContent = result.getIntegrationTestFile(
- "../spec.types.js",
- "./schema.js",
- );
- if (testsContent) {
- const processedTests = postProcessTests(testsContent);
- writeFileSync(SCHEMA_TEST_OUTPUT_FILE, processedTests, "utf-8");
- console.log(`✅ Written: ${SCHEMA_TEST_OUTPUT_FILE}`);
- }
-
- // Generate JSON Schema from the Zod schemas
- await generateJsonSchema();
-
- console.log("\n🎉 Schema generation complete!");
+ * where `el.onclick` and `el.addEventListener("click", …)` coexist.
+ */
+interface EventSlot<T = unknown> {
+ onHandler?: ((params: T) => void) | undefined;
+ listeners: ((params: T) => void)[];
}
/**
- * Generate JSON Schema from the Zod schemas.
- * Uses dynamic import to load the generated schemas after they're written.
- */
-async function generateJsonSchema() {
- // Dynamic import of the generated schemas
- // tsx handles TypeScript imports at runtime
- const schemas = await import("../src/generated/schema.js");
-
+ * Intermediate base class that adds DOM-style event support on top of the
+ * MCP SDK's `Protocol`.
+ *
+ * The base `Protocol` class stores one handler per method:
+ * `setRequestHandler()` and `setNotificationHandler()` replace any existing
+ * handler for the same method silently. This class introduces a two-channel
+ * event model inspired by the DOM:
+ *
+ * ### Singular `on*` handler (like `el.onclick`)
+ *
+ * Subclasses expose `get`/`set` pairs that delegate to
+ * {@link setEventHandler `setEventHandler`} /
+ * {@link getEventHandler `getEventHandler`}. Assigning replaces the previous
+ * handler; assigning `undefined` clears it. `addEventListener` listeners are
+ * unaffected.
+ *
+ * ### Multi-listener (`addEventListener` / `removeEventListener`)
+ *
+ * Append to a per-event listener array. Listeners fire in insertion order
+ * after the singular `on*` handler.
+ *
+ * ### Dispatch order
+ *
+ * When a notification arrives for a mapped event:
```
-This function is important because it defines how MCP Ext Apps Tutorial: Building Interactive MCP Apps and Hosts implements the patterns covered in this chapter.
+This interface is important because it defines how MCP Ext Apps Tutorial: Building Interactive MCP Apps and Hosts implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[PostMessageTransport_constructor_host]
- B[main]
- C[generateJsonSchema]
- D[postProcess]
- E[replaceRecordAndWithPassthrough]
+ A[side]
+ B[ProtocolWithEvents]
+ C[fields]
+ D[EventSlot]
+ E[for]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-ext-apps-tutorial/07-agent-skills-and-openai-apps-migration.md b/tutorials/mcp-ext-apps-tutorial/07-agent-skills-and-openai-apps-migration.md
index 7c6ca017..70597dd4 100644
--- a/tutorials/mcp-ext-apps-tutorial/07-agent-skills-and-openai-apps-migration.md
+++ b/tutorials/mcp-ext-apps-tutorial/07-agent-skills-and-openai-apps-migration.md
@@ -39,184 +39,182 @@ You now have a migration-aware adoption strategy for MCP Apps.
Next: [Chapter 8: Release Strategy and Production Operations](08-release-strategy-and-production-operations.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `examples/budget-allocator-server/server.ts`
+### `src/server/index.ts`
-The `generateHistory` function in [`examples/budget-allocator-server/server.ts`](https://github.com/modelcontextprotocol/ext-apps/blob/HEAD/examples/budget-allocator-server/server.ts) handles a key part of this chapter's functionality:
+The `computeAppDomainForClaude` function in [`src/server/index.ts`](https://github.com/modelcontextprotocol/ext-apps/blob/HEAD/src/server/index.ts) handles a key part of this chapter's functionality:
```ts
- * Generate 24 months of historical allocation data with realistic trends
- */
-function generateHistory(
- categories: BudgetCategoryInternal[],
-): HistoricalMonth[] {
- const months: HistoricalMonth[] = [];
- const now = new Date();
- const random = seededRandom(42); // Fixed seed for reproducibility
-
- for (let i = 23; i >= 0; i--) {
- const date = new Date(now);
- date.setMonth(date.getMonth() - i);
- const monthStr = `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, "0")}`;
-
- const rawAllocations: Record<string, number> = {};
-
- for (const cat of categories) {
- // Start from default, apply trend over time, add noise
- const monthsFromStart = 23 - i;
- const trend = monthsFromStart * cat.trendPerMonth;
- const noise = (random() - 0.5) * 3; // +/- 1.5%
- rawAllocations[cat.id] = Math.max(
- 0,
- Math.min(100, cat.defaultPercent + trend + noise),
- );
- }
-
- // Normalize to 100%
- const total = Object.values(rawAllocations).reduce((a, b) => a + b, 0);
- const allocations: Record<string, number> = {};
- for (const id of Object.keys(rawAllocations)) {
- allocations[id] = Math.round((rawAllocations[id] / total) * 1000) / 10;
+ * ```ts source="./index.examples.ts#registerAppResource_withDomain"
+ * // Computes a stable origin from an MCP server URL for hosting in Claude.
+ * function computeAppDomainForClaude(mcpServerUrl: string): string {
+ * const hash = crypto
+ * .createHash("sha256")
+ * .update(mcpServerUrl)
+ * .digest("hex")
+ * .slice(0, 32);
+ * return `${hash}.claudemcpcontent.com`;
+ * }
+ *
+ * const APP_DOMAIN = computeAppDomainForClaude("https://example.com/mcp");
+ *
+ * registerAppResource(
+ * server,
+ * "Company Dashboard",
+ * "ui://dashboard/view.html",
+ * {
+ * description: "Internal dashboard with company data",
+ * },
+ * async () => ({
+ * contents: [
+ * {
+ * uri: "ui://dashboard/view.html",
+ * mimeType: RESOURCE_MIME_TYPE,
+ * text: dashboardHtml,
+ * _meta: {
+ * ui: {
+ * // CSP: tell browser the app is allowed to make requests
+ * csp: {
+ * connectDomains: ["https://api.example.com"],
+ * },
```
This function is important because it defines how MCP Ext Apps Tutorial: Building Interactive MCP Apps and Hosts implements the patterns covered in this chapter.
-### `examples/budget-allocator-server/server.ts`
+### `src/server/index.ts`
-The `formatBudgetSummary` function in [`examples/budget-allocator-server/server.ts`](https://github.com/modelcontextprotocol/ext-apps/blob/HEAD/examples/budget-allocator-server/server.ts) handles a key part of this chapter's functionality:
+The `registerAppResource` function in [`src/server/index.ts`](https://github.com/modelcontextprotocol/ext-apps/blob/HEAD/src/server/index.ts) handles a key part of this chapter's functionality:
```ts
-// ---------------------------------------------------------------------------
-
-function formatBudgetSummary(data: BudgetDataResponse): string {
- const lines: string[] = [
- "Budget Allocator Configuration",
- "==============================",
- "",
- `Default Budget: ${data.config.currencySymbol}${data.config.defaultBudget.toLocaleString()}`,
- `Available Presets: ${data.config.presetBudgets.map((b) => `${data.config.currencySymbol}${b.toLocaleString()}`).join(", ")}`,
- "",
- "Categories:",
- ...data.config.categories.map(
- (c) => ` - ${c.name}: ${c.defaultPercent}% default`,
- ),
- "",
- `Historical Data: ${data.analytics.history.length} months`,
- `Benchmark Stages: ${data.analytics.stages.join(", ")}`,
- `Default Stage: ${data.analytics.defaultStage}`,
- ];
- return lines.join("\n");
-}
-
-// ---------------------------------------------------------------------------
-// MCP Server Setup
-// ---------------------------------------------------------------------------
-
-const resourceUri = "ui://budget-allocator/mcp-app.html";
-
-/**
- * Creates a new MCP server instance with tools and resources registered.
- * Each HTTP session needs its own server instance because McpServer only supports one transport.
+ *
+ * // Register the HTML resource the tool references
+ * registerAppResource(
+ * server,
+ * "Weather View",
+ * "ui://weather/view.html",
+ * {},
+ * readCallback,
+ * );
+ * ```
*/
+
+import {
+ RESOURCE_URI_META_KEY,
+ RESOURCE_MIME_TYPE,
+ McpUiResourceCsp,
+ McpUiResourceMeta,
+ McpUiToolMeta,
+ McpUiClientCapabilities,
+} from "../app.js";
+import type {
+ BaseToolCallback,
+ McpServer,
+ RegisteredTool,
+ ResourceMetadata,
+ ToolCallback,
+ ReadResourceCallback as _ReadResourceCallback,
+ RegisteredResource,
+} from "@modelcontextprotocol/sdk/server/mcp.js";
+import type {
+ AnySchema,
+ ZodRawShapeCompat,
```
This function is important because it defines how MCP Ext Apps Tutorial: Building Interactive MCP Apps and Hosts implements the patterns covered in this chapter.
-### `examples/budget-allocator-server/server.ts`
+### `src/server/index.ts`
-The `createServer` function in [`examples/budget-allocator-server/server.ts`](https://github.com/modelcontextprotocol/ext-apps/blob/HEAD/examples/budget-allocator-server/server.ts) handles a key part of this chapter's functionality:
+The `getUiCapability` function in [`src/server/index.ts`](https://github.com/modelcontextprotocol/ext-apps/blob/HEAD/src/server/index.ts) handles a key part of this chapter's functionality:
```ts
- * Each HTTP session needs its own server instance because McpServer only supports one transport.
+ *
+ * @example Check for MCP Apps support in server initialization
+ * ```ts source="./index.examples.ts#getUiCapability_checkSupport"
+ * server.server.oninitialized = () => {
+ * const clientCapabilities = server.server.getClientCapabilities();
+ * const uiCap = getUiCapability(clientCapabilities);
+ *
+ * if (uiCap?.mimeTypes?.includes(RESOURCE_MIME_TYPE)) {
+ * // App-enhanced tool
+ * registerAppTool(
+ * server,
+ * "weather",
+ * {
+ * description: "Get weather information with interactive dashboard",
+ * _meta: { ui: { resourceUri: "ui://weather/dashboard" } },
+ * },
+ * weatherHandler,
+ * );
+ * } else {
+ * // Text-only fallback
+ * server.registerTool(
+ * "weather",
+ * {
+ * description: "Get weather information",
+ * },
+ * textWeatherHandler,
+ * );
+ * }
+ * };
+ * ```
*/
-export function createServer(): McpServer {
- const server = new McpServer({
- name: "Budget Allocator Server",
- version: "1.0.0",
- });
-
- registerAppTool(
- server,
- "get-budget-data",
- {
- title: "Get Budget Data",
- description:
- "Returns budget configuration with 24 months of historical allocations and industry benchmarks by company stage",
- inputSchema: {},
- outputSchema: BudgetDataResponseSchema,
- _meta: { ui: { resourceUri } },
- },
- async (): Promise<CallToolResult> => {
- const response: BudgetDataResponse = {
- config: {
- categories: CATEGORIES.map(({ id, name, color, defaultPercent }) => ({
- id,
- name,
- color,
- defaultPercent,
- })),
- presetBudgets: [50000, 100000, 250000, 500000],
- defaultBudget: 100000,
- currency: "USD",
- currencySymbol: "$",
+export function getUiCapability(
```
This function is important because it defines how MCP Ext Apps Tutorial: Building Interactive MCP Apps and Hosts implements the patterns covered in this chapter.
-### `examples/scenario-modeler-server/server.ts`
+### `src/server/index.ts`
-The `calculateProjections` function in [`examples/scenario-modeler-server/server.ts`](https://github.com/modelcontextprotocol/ext-apps/blob/HEAD/examples/scenario-modeler-server/server.ts) handles a key part of this chapter's functionality:
+The `ToolConfig` interface in [`src/server/index.ts`](https://github.com/modelcontextprotocol/ext-apps/blob/HEAD/src/server/index.ts) handles a key part of this chapter's functionality:
```ts
-// ============================================================================
-
-function calculateProjections(inputs: ScenarioInputs): MonthlyProjection[] {
- const {
- startingMRR,
- monthlyGrowthRate,
- monthlyChurnRate,
- grossMargin,
- fixedCosts,
- } = inputs;
-
- const netGrowthRate = (monthlyGrowthRate - monthlyChurnRate) / 100;
- const projections: MonthlyProjection[] = [];
- let cumulativeRevenue = 0;
-
- for (let month = 1; month <= 12; month++) {
- const mrr = startingMRR * Math.pow(1 + netGrowthRate, month);
- const grossProfit = mrr * (grossMargin / 100);
- const netProfit = grossProfit - fixedCosts;
- cumulativeRevenue += mrr;
-
- projections.push({
- month,
- mrr,
- grossProfit,
- netProfit,
- cumulativeRevenue,
- });
- }
-
- return projections;
+/**
+ * Base tool configuration matching the standard MCP server tool options.
+ * Extended by {@link McpUiAppToolConfig `McpUiAppToolConfig`} to add UI metadata requirements.
+ */
+export interface ToolConfig {
+ title?: string;
+ description?: string;
+ inputSchema?: ZodRawShapeCompat | AnySchema;
+ outputSchema?: ZodRawShapeCompat | AnySchema;
+ annotations?: ToolAnnotations;
+ _meta?: Record<string, unknown>;
}
+
+/**
+ * Configuration for tools that render an interactive UI.
+ *
+ * Extends {@link ToolConfig `ToolConfig`} with a required `_meta` field that specifies UI metadata.
+ * The UI resource can be specified in two ways:
+ * - `_meta.ui.resourceUri` (preferred)
+ * - `_meta["ui/resourceUri"]` (deprecated, for backward compatibility)
+ *
+ * @see {@link registerAppTool `registerAppTool`} for the recommended way to register app tools
+ */
+export interface McpUiAppToolConfig extends ToolConfig {
+ _meta: {
+ [key: string]: unknown;
+ } & (
+ | {
+ ui: McpUiToolMeta;
+ }
+ | {
+ /**
```
-This function is important because it defines how MCP Ext Apps Tutorial: Building Interactive MCP Apps and Hosts implements the patterns covered in this chapter.
+This interface is important because it defines how MCP Ext Apps Tutorial: Building Interactive MCP Apps and Hosts implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[generateHistory]
- B[formatBudgetSummary]
- C[createServer]
- D[calculateProjections]
- E[calculateSummary]
+ A[computeAppDomainForClaude]
+ B[registerAppResource]
+ C[getUiCapability]
+ D[ToolConfig]
+ E[McpUiAppToolConfig]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-ext-apps-tutorial/08-release-strategy-and-production-operations.md b/tutorials/mcp-ext-apps-tutorial/08-release-strategy-and-production-operations.md
index 6cf44852..b2b08df6 100644
--- a/tutorials/mcp-ext-apps-tutorial/08-release-strategy-and-production-operations.md
+++ b/tutorials/mcp-ext-apps-tutorial/08-release-strategy-and-production-operations.md
@@ -41,142 +41,136 @@ You now have a production operations framework for MCP Apps across app and host
Return to the [MCP Ext Apps Tutorial index](README.md).
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `examples/map-server/server.ts`
+### `examples/budget-allocator-server/server.ts`
-The `geocodeWithNominatim` function in [`examples/map-server/server.ts`](https://github.com/modelcontextprotocol/ext-apps/blob/HEAD/examples/map-server/server.ts) handles a key part of this chapter's functionality:
+The `createServer` function in [`examples/budget-allocator-server/server.ts`](https://github.com/modelcontextprotocol/ext-apps/blob/HEAD/examples/budget-allocator-server/server.ts) handles a key part of this chapter's functionality:
```ts
- * Query Nominatim geocoding API with rate limiting
+ * Each HTTP session needs its own server instance because McpServer only supports one transport.
*/
-async function geocodeWithNominatim(query: string): Promise<NominatimResult[]> {
- // Respect rate limit
- const now = Date.now();
- const timeSinceLastRequest = now - lastNominatimRequest;
- if (timeSinceLastRequest < NOMINATIM_RATE_LIMIT_MS) {
- await new Promise((resolve) =>
- setTimeout(resolve, NOMINATIM_RATE_LIMIT_MS - timeSinceLastRequest),
- );
- }
- lastNominatimRequest = Date.now();
-
- const params = new URLSearchParams({
- q: query,
- format: "json",
- limit: "5",
+export function createServer(): McpServer {
+ const server = new McpServer({
+ name: "Budget Allocator Server",
+ version: "1.0.0",
});
- const response = await fetch(
- `https://nominatim.openstreetmap.org/search?${params}`,
+ registerAppTool(
+ server,
+ "get-budget-data",
{
- headers: {
- "User-Agent":
- "MCP-CesiumMap-Example/1.0 (https://github.com/modelcontextprotocol)",
- },
+ title: "Get Budget Data",
+ description:
+ "Returns budget configuration with 24 months of historical allocations and industry benchmarks by company stage",
+ inputSchema: {},
+ outputSchema: BudgetDataResponseSchema,
+ _meta: { ui: { resourceUri } },
},
- );
-
- if (!response.ok) {
- throw new Error(
- `Nominatim API error: ${response.status} ${response.statusText}`,
+ async (): Promise<CallToolResult> => {
+ const response: BudgetDataResponse = {
+ config: {
+ categories: CATEGORIES.map(({ id, name, color, defaultPercent }) => ({
+ id,
+ name,
+ color,
+ defaultPercent,
+ })),
+ presetBudgets: [50000, 100000, 250000, 500000],
+ defaultBudget: 100000,
+ currency: "USD",
+ currencySymbol: "$",
```
This function is important because it defines how MCP Ext Apps Tutorial: Building Interactive MCP Apps and Hosts implements the patterns covered in this chapter.
-### `examples/map-server/server.ts`
+### `src/server/index.examples.ts`
-The `createServer` function in [`examples/map-server/server.ts`](https://github.com/modelcontextprotocol/ext-apps/blob/HEAD/examples/map-server/server.ts) handles a key part of this chapter's functionality:
+The `fetchWeather` function in [`src/server/index.examples.ts`](https://github.com/modelcontextprotocol/ext-apps/blob/HEAD/src/server/index.examples.ts) handles a key part of this chapter's functionality:
```ts
- * Each HTTP session needs its own server instance because McpServer only supports one transport.
- */
-export function createServer(): McpServer {
- const server = new McpServer({
- name: "CesiumJS Map Server",
- version: "1.0.0",
- });
- // CSP configuration for external tile sources
- const cspMeta = {
- ui: {
- csp: {
- // Allow fetching tiles from OSM (tiles + geocoding) and Cesium assets
- connectDomains: [
- "https://*.openstreetmap.org", // OSM tiles + Nominatim geocoding
- "https://cesium.com",
- "https://*.cesium.com",
- ],
- // Allow loading tile images, scripts, and Cesium CDN resources
- resourceDomains: [
- "https://*.openstreetmap.org", // OSM map tiles (covers tile.openstreetmap.org)
- "https://cesium.com",
- "https://*.cesium.com",
- ],
- },
- },
- };
+// Stubs for external functions used in examples
+declare function fetchWeather(
+ location: string,
+): Promise<{ temp: number; conditions: string }>;
+declare function getCart(): Promise<{ items: unknown[]; total: number }>;
+declare function updateCartItem(
+ itemId: string,
+ quantity: number,
+): Promise<{ items: unknown[]; total: number }>;
- // Register the CesiumJS map resource with CSP for external tile sources
- registerAppResource(
+/**
+ * Example: Module overview showing basic registration of tools and resources.
+ */
+function index_overview(
+ server: McpServer,
+ toolCallback: ToolCallback,
+ readCallback: ReadResourceCallback,
+) {
+ //#region index_overview
+ // Register a tool that displays a view
+ registerAppTool(
server,
- resourceUri,
+ "weather",
+ {
+ description: "Get weather forecast",
+ _meta: { ui: { resourceUri: "ui://weather/view.html" } },
+ },
+ toolCallback,
+ );
+
+ // Register the HTML resource the tool references
```
This function is important because it defines how MCP Ext Apps Tutorial: Building Interactive MCP Apps and Hosts implements the patterns covered in this chapter.
-### `examples/map-server/server.ts`
+### `src/server/index.examples.ts`
-The `NominatimResult` interface in [`examples/map-server/server.ts`](https://github.com/modelcontextprotocol/ext-apps/blob/HEAD/examples/map-server/server.ts) handles a key part of this chapter's functionality:
+The `getCart` function in [`src/server/index.examples.ts`](https://github.com/modelcontextprotocol/ext-apps/blob/HEAD/src/server/index.examples.ts) handles a key part of this chapter's functionality:
```ts
-
-// Nominatim API response type
-interface NominatimResult {
- place_id: number;
- licence: string;
- osm_type: string;
- osm_id: number;
- lat: string;
- lon: string;
- display_name: string;
- boundingbox: [string, string, string, string]; // [south, north, west, east]
- class: string;
- type: string;
- importance: number;
-}
-
-// Rate limiting for Nominatim (1 request per second per their usage policy)
-let lastNominatimRequest = 0;
-const NOMINATIM_RATE_LIMIT_MS = 1100; // 1.1 seconds to be safe
+ location: string,
+): Promise<{ temp: number; conditions: string }>;
+declare function getCart(): Promise<{ items: unknown[]; total: number }>;
+declare function updateCartItem(
+ itemId: string,
+ quantity: number,
+): Promise<{ items: unknown[]; total: number }>;
/**
- * Query Nominatim geocoding API with rate limiting
+ * Example: Module overview showing basic registration of tools and resources.
*/
-async function geocodeWithNominatim(query: string): Promise<NominatimResult[]> {
- // Respect rate limit
- const now = Date.now();
- const timeSinceLastRequest = now - lastNominatimRequest;
- if (timeSinceLastRequest < NOMINATIM_RATE_LIMIT_MS) {
- await new Promise((resolve) =>
- setTimeout(resolve, NOMINATIM_RATE_LIMIT_MS - timeSinceLastRequest),
- );
- }
+function index_overview(
+ server: McpServer,
+ toolCallback: ToolCallback,
+ readCallback: ReadResourceCallback,
+) {
+ //#region index_overview
+ // Register a tool that displays a view
+ registerAppTool(
+ server,
+ "weather",
+ {
+ description: "Get weather forecast",
+ _meta: { ui: { resourceUri: "ui://weather/view.html" } },
+ },
+ toolCallback,
+ );
+
+ // Register the HTML resource the tool references
+ registerAppResource(
+ server,
+ "Weather View",
```
-This interface is important because it defines how MCP Ext Apps Tutorial: Building Interactive MCP Apps and Hosts implements the patterns covered in this chapter.
+This function is important because it defines how MCP Ext Apps Tutorial: Building Interactive MCP Apps and Hosts implements the patterns covered in this chapter.
### `src/server/index.examples.ts`
-The `fetchWeather` function in [`src/server/index.examples.ts`](https://github.com/modelcontextprotocol/ext-apps/blob/HEAD/src/server/index.examples.ts) handles a key part of this chapter's functionality:
+The `updateCartItem` function in [`src/server/index.examples.ts`](https://github.com/modelcontextprotocol/ext-apps/blob/HEAD/src/server/index.examples.ts) handles a key part of this chapter's functionality:
```ts
-
-// Stubs for external functions used in examples
-declare function fetchWeather(
- location: string,
): Promise<{ temp: number; conditions: string }>;
declare function getCart(): Promise<{ items: unknown[]; total: number }>;
declare function updateCartItem(
@@ -205,6 +199,10 @@ function index_overview(
);
// Register the HTML resource the tool references
+ registerAppResource(
+ server,
+ "Weather View",
+ "ui://weather/view.html",
```
This function is important because it defines how MCP Ext Apps Tutorial: Building Interactive MCP Apps and Hosts implements the patterns covered in this chapter.
@@ -214,11 +212,11 @@ This function is important because it defines how MCP Ext Apps Tutorial: Buildin
```mermaid
flowchart TD
- A[geocodeWithNominatim]
- B[createServer]
- C[NominatimResult]
- D[fetchWeather]
- E[getCart]
+ A[createServer]
+ B[fetchWeather]
+ C[getCart]
+ D[updateCartItem]
+ E[index_overview]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-go-sdk-tutorial/01-getting-started-and-sdk-package-map.md b/tutorials/mcp-go-sdk-tutorial/01-getting-started-and-sdk-package-map.md
index 50024898..b881ba87 100644
--- a/tutorials/mcp-go-sdk-tutorial/01-getting-started-and-sdk-package-map.md
+++ b/tutorials/mcp-go-sdk-tutorial/01-getting-started-and-sdk-package-map.md
@@ -50,170 +50,168 @@ You now have a clean package and module baseline for Go MCP development.
Next: [Chapter 2: Client/Server Lifecycle and Session Management](02-client-server-lifecycle-and-session-management.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `mcp/content.go`
+### `auth/authorization_code.go`
-The `MarshalJSON` function in [`mcp/content.go`](https://github.com/modelcontextprotocol/go-sdk/blob/HEAD/mcp/content.go) handles a key part of this chapter's functionality:
+The `TokenSource` function in [`auth/authorization_code.go`](https://github.com/modelcontextprotocol/go-sdk/blob/HEAD/auth/authorization_code.go) handles a key part of this chapter's functionality:
```go
-// TODO(findleyr): update JSON marshalling of all content types to preserve required fields.
-// (See [TextContent.MarshalJSON], which handles this for text content).
-
-package mcp
-
-import (
- "encoding/json"
- "fmt"
-
- internaljson "github.com/modelcontextprotocol/go-sdk/internal/json"
-)
-
-// A Content is a [TextContent], [ImageContent], [AudioContent],
-// [ResourceLink], [EmbeddedResource], [ToolUseContent], or [ToolResultContent].
-//
-// Note: [ToolUseContent] and [ToolResultContent] are only valid in sampling
-// message contexts (CreateMessageParams/CreateMessageResult).
-type Content interface {
- MarshalJSON() ([]byte, error)
- fromWire(*wireContent)
+ // tokenSource is the token source to use for authorization.
+ tokenSource oauth2.TokenSource
}
-// TextContent is a textual content.
-type TextContent struct {
- Text string
- Meta Meta
- Annotations *Annotations
+var _ OAuthHandler = (*AuthorizationCodeHandler)(nil)
+
+func (h *AuthorizationCodeHandler) TokenSource(ctx context.Context) (oauth2.TokenSource, error) {
+ return h.tokenSource, nil
}
-func (c *TextContent) MarshalJSON() ([]byte, error) {
- // Custom wire format to ensure the required "text" field is always included, even when empty.
+// NewAuthorizationCodeHandler creates a new AuthorizationCodeHandler.
+// It performs validation of the configuration and returns an error if it is invalid.
+// The passed config is consumed by the handler and should not be modified after.
+func NewAuthorizationCodeHandler(config *AuthorizationCodeHandlerConfig) (*AuthorizationCodeHandler, error) {
+ if config == nil {
+ return nil, errors.New("config must be provided")
+ }
+ if config.ClientIDMetadataDocumentConfig == nil &&
+ config.PreregisteredClient == nil &&
+ config.DynamicClientRegistrationConfig == nil {
+ return nil, errors.New("at least one client registration configuration must be provided")
+ }
+ if config.AuthorizationCodeFetcher == nil {
+ return nil, errors.New("AuthorizationCodeFetcher is required")
+ }
+ if config.ClientIDMetadataDocumentConfig != nil && !isNonRootHTTPSURL(config.ClientIDMetadataDocumentConfig.URL) {
+ return nil, fmt.Errorf("client ID metadata document URL must be a non-root HTTPS URL")
+ }
+ if config.PreregisteredClient != nil {
+ if err := config.PreregisteredClient.Validate(); err != nil {
+ return nil, fmt.Errorf("invalid PreregisteredClient configuration: %w", err)
```
This function is important because it defines how MCP Go SDK Tutorial: Building Robust MCP Clients and Servers in Go implements the patterns covered in this chapter.
-### `mcp/content.go`
+### `auth/authorization_code.go`
-The `fromWire` function in [`mcp/content.go`](https://github.com/modelcontextprotocol/go-sdk/blob/HEAD/mcp/content.go) handles a key part of this chapter's functionality:
+The `NewAuthorizationCodeHandler` function in [`auth/authorization_code.go`](https://github.com/modelcontextprotocol/go-sdk/blob/HEAD/auth/authorization_code.go) handles a key part of this chapter's functionality:
```go
-type Content interface {
- MarshalJSON() ([]byte, error)
- fromWire(*wireContent)
}
-// TextContent is a textual content.
-type TextContent struct {
- Text string
- Meta Meta
- Annotations *Annotations
-}
-
-func (c *TextContent) MarshalJSON() ([]byte, error) {
- // Custom wire format to ensure the required "text" field is always included, even when empty.
- wire := struct {
- Type string `json:"type"`
- Text string `json:"text"`
- Meta Meta `json:"_meta,omitempty"`
- Annotations *Annotations `json:"annotations,omitempty"`
- }{
- Type: "text",
- Text: c.Text,
- Meta: c.Meta,
- Annotations: c.Annotations,
- }
- return json.Marshal(wire)
-}
-
-func (c *TextContent) fromWire(wire *wireContent) {
- c.Text = wire.Text
- c.Meta = wire.Meta
- c.Annotations = wire.Annotations
+// NewAuthorizationCodeHandler creates a new AuthorizationCodeHandler.
+// It performs validation of the configuration and returns an error if it is invalid.
+// The passed config is consumed by the handler and should not be modified after.
+func NewAuthorizationCodeHandler(config *AuthorizationCodeHandlerConfig) (*AuthorizationCodeHandler, error) {
+ if config == nil {
+ return nil, errors.New("config must be provided")
+ }
+ if config.ClientIDMetadataDocumentConfig == nil &&
+ config.PreregisteredClient == nil &&
+ config.DynamicClientRegistrationConfig == nil {
+ return nil, errors.New("at least one client registration configuration must be provided")
+ }
+ if config.AuthorizationCodeFetcher == nil {
+ return nil, errors.New("AuthorizationCodeFetcher is required")
+ }
+ if config.ClientIDMetadataDocumentConfig != nil && !isNonRootHTTPSURL(config.ClientIDMetadataDocumentConfig.URL) {
+ return nil, fmt.Errorf("client ID metadata document URL must be a non-root HTTPS URL")
+ }
+ if config.PreregisteredClient != nil {
+ if err := config.PreregisteredClient.Validate(); err != nil {
+ return nil, fmt.Errorf("invalid PreregisteredClient configuration: %w", err)
+ }
+ }
+ dCfg := config.DynamicClientRegistrationConfig
+ if dCfg != nil {
+ if dCfg.Metadata == nil {
+ return nil, errors.New("dynamic client registration requires non-nil Metadata")
+ }
+ if len(dCfg.Metadata.RedirectURIs) == 0 {
+ return nil, errors.New("Metadata.RedirectURIs is required for dynamic client registration")
```
This function is important because it defines how MCP Go SDK Tutorial: Building Robust MCP Clients and Servers in Go implements the patterns covered in this chapter.
-### `mcp/content.go`
+### `auth/authorization_code.go`
-The `MarshalJSON` function in [`mcp/content.go`](https://github.com/modelcontextprotocol/go-sdk/blob/HEAD/mcp/content.go) handles a key part of this chapter's functionality:
+The `isNonRootHTTPSURL` function in [`auth/authorization_code.go`](https://github.com/modelcontextprotocol/go-sdk/blob/HEAD/auth/authorization_code.go) handles a key part of this chapter's functionality:
```go
-
-// TODO(findleyr): update JSON marshalling of all content types to preserve required fields.
-// (See [TextContent.MarshalJSON], which handles this for text content).
-
-package mcp
-
-import (
- "encoding/json"
- "fmt"
-
- internaljson "github.com/modelcontextprotocol/go-sdk/internal/json"
-)
-
-// A Content is a [TextContent], [ImageContent], [AudioContent],
-// [ResourceLink], [EmbeddedResource], [ToolUseContent], or [ToolResultContent].
-//
-// Note: [ToolUseContent] and [ToolResultContent] are only valid in sampling
-// message contexts (CreateMessageParams/CreateMessageResult).
-type Content interface {
- MarshalJSON() ([]byte, error)
- fromWire(*wireContent)
-}
-
-// TextContent is a textual content.
-type TextContent struct {
- Text string
- Meta Meta
- Annotations *Annotations
-}
-
-func (c *TextContent) MarshalJSON() ([]byte, error) {
- // Custom wire format to ensure the required "text" field is always included, even when empty.
+ return nil, errors.New("AuthorizationCodeFetcher is required")
+ }
+ if config.ClientIDMetadataDocumentConfig != nil && !isNonRootHTTPSURL(config.ClientIDMetadataDocumentConfig.URL) {
+ return nil, fmt.Errorf("client ID metadata document URL must be a non-root HTTPS URL")
+ }
+ if config.PreregisteredClient != nil {
+ if err := config.PreregisteredClient.Validate(); err != nil {
+ return nil, fmt.Errorf("invalid PreregisteredClient configuration: %w", err)
+ }
+ }
+ dCfg := config.DynamicClientRegistrationConfig
+ if dCfg != nil {
+ if dCfg.Metadata == nil {
+ return nil, errors.New("dynamic client registration requires non-nil Metadata")
+ }
+ if len(dCfg.Metadata.RedirectURIs) == 0 {
+ return nil, errors.New("Metadata.RedirectURIs is required for dynamic client registration")
+ }
+ if config.RedirectURL == "" {
+ config.RedirectURL = dCfg.Metadata.RedirectURIs[0]
+ } else if !slices.Contains(dCfg.Metadata.RedirectURIs, config.RedirectURL) {
+ return nil, fmt.Errorf("RedirectURL %q is not in the list of allowed redirect URIs for dynamic client registration", config.RedirectURL)
+ }
+ }
+ if config.RedirectURL == "" {
+ // If the RedirectURL was supposed to be set by the dynamic client registration,
+ // it should have been set by now. Otherwise, it is required.
+ return nil, errors.New("RedirectURL is required")
+ }
+ if config.Client == nil {
+ config.Client = http.DefaultClient
+ }
```
This function is important because it defines how MCP Go SDK Tutorial: Building Robust MCP Clients and Servers in Go implements the patterns covered in this chapter.
-### `mcp/content.go`
+### `auth/authorization_code.go`
-The `fromWire` function in [`mcp/content.go`](https://github.com/modelcontextprotocol/go-sdk/blob/HEAD/mcp/content.go) handles a key part of this chapter's functionality:
+The `Authorize` function in [`auth/authorization_code.go`](https://github.com/modelcontextprotocol/go-sdk/blob/HEAD/auth/authorization_code.go) handles a key part of this chapter's functionality:
```go
-type Content interface {
- MarshalJSON() ([]byte, error)
- fromWire(*wireContent)
}
-// TextContent is a textual content.
-type TextContent struct {
- Text string
- Meta Meta
- Annotations *Annotations
-}
+// Authorize performs the authorization flow.
+// It is designed to perform the whole Authorization Code Grant flow.
+// On success, [AuthorizationCodeHandler.TokenSource] will return a token source with the fetched token.
+func (h *AuthorizationCodeHandler) Authorize(ctx context.Context, req *http.Request, resp *http.Response) error {
+ defer resp.Body.Close()
+ defer io.Copy(io.Discard, resp.Body)
-func (c *TextContent) MarshalJSON() ([]byte, error) {
- // Custom wire format to ensure the required "text" field is always included, even when empty.
- wire := struct {
- Type string `json:"type"`
- Text string `json:"text"`
- Meta Meta `json:"_meta,omitempty"`
- Annotations *Annotations `json:"annotations,omitempty"`
- }{
- Type: "text",
- Text: c.Text,
- Meta: c.Meta,
- Annotations: c.Annotations,
- }
- return json.Marshal(wire)
-}
+ wwwChallenges, err := oauthex.ParseWWWAuthenticate(resp.Header[http.CanonicalHeaderKey("WWW-Authenticate")])
+ if err != nil {
+ return fmt.Errorf("failed to parse WWW-Authenticate header: %v", err)
+ }
-func (c *TextContent) fromWire(wire *wireContent) {
- c.Text = wire.Text
- c.Meta = wire.Meta
- c.Annotations = wire.Annotations
+ if resp.StatusCode == http.StatusForbidden && errorFromChallenges(wwwChallenges) != "insufficient_scope" {
+ // We only want to perform step-up authorization for insufficient_scope errors.
+ // Returning nil, so that the call is retried immediately and the response
+ // is handled appropriately by the connection.
+ // Step-up authorization is defined at
+ // https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#step-up-authorization-flow
+ return nil
+ }
+
+ prm, err := h.getProtectedResourceMetadata(ctx, wwwChallenges, req.URL.String())
+ if err != nil {
+ return err
+ }
+
+ asm, err := GetAuthServerMetadata(ctx, prm.AuthorizationServers[0], h.config.Client)
+ if err != nil {
+ return fmt.Errorf("failed to get authorization server metadata: %w", err)
+ }
```
This function is important because it defines how MCP Go SDK Tutorial: Building Robust MCP Clients and Servers in Go implements the patterns covered in this chapter.
@@ -223,11 +221,11 @@ This function is important because it defines how MCP Go SDK Tutorial: Building
```mermaid
flowchart TD
- A[MarshalJSON]
- B[fromWire]
- C[MarshalJSON]
- D[fromWire]
- E[MarshalJSON]
+ A[TokenSource]
+ B[NewAuthorizationCodeHandler]
+ C[isNonRootHTTPSURL]
+ D[Authorize]
+ E[resourceMetadataURLFromChallenges]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-go-sdk-tutorial/02-client-server-lifecycle-and-session-management.md b/tutorials/mcp-go-sdk-tutorial/02-client-server-lifecycle-and-session-management.md
index 9152524c..e911c6a4 100644
--- a/tutorials/mcp-go-sdk-tutorial/02-client-server-lifecycle-and-session-management.md
+++ b/tutorials/mcp-go-sdk-tutorial/02-client-server-lifecycle-and-session-management.md
@@ -46,184 +46,182 @@ You now have lifecycle patterns that reduce race conditions and hanging sessions
Next: [Chapter 3: Transports: stdio, Streamable HTTP, and Custom Flows](03-transports-stdio-streamable-http-and-custom-flows.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `mcp/sse.go`
+### `mcp/content.go`
-The `Write` function in [`mcp/sse.go`](https://github.com/modelcontextprotocol/go-sdk/blob/HEAD/mcp/sse.go) handles a key part of this chapter's functionality:
+The `fromWire` function in [`mcp/content.go`](https://github.com/modelcontextprotocol/go-sdk/blob/HEAD/mcp/content.go) handles a key part of this chapter's functionality:
```go
-// Therefore, the each new GET request hands off its responsewriter to an
-// [SSEServerTransport] type that abstracts the transport as follows:
-// - Write writes a new event to the responseWriter, or fails if the GET has
-// exited.
-// - Read reads off a message queue that is pushed to via POST requests.
-// - Close causes the hanging GET to exit.
-
-// SSEHandler is an http.Handler that serves SSE-based MCP sessions as defined by
-// the [2024-11-05 version] of the MCP spec.
-//
-// [2024-11-05 version]: https://modelcontextprotocol.io/specification/2024-11-05/basic/transports
-type SSEHandler struct {
- getServer func(request *http.Request) *Server
- opts SSEOptions
- onConnection func(*ServerSession) // for testing; must not block
-
- mu sync.Mutex
- sessions map[string]*SSEServerTransport
+type Content interface {
+ MarshalJSON() ([]byte, error)
+ fromWire(*wireContent)
+}
+
+// TextContent is a textual content.
+type TextContent struct {
+ Text string
+ Meta Meta
+ Annotations *Annotations
+}
+
+func (c *TextContent) MarshalJSON() ([]byte, error) {
+ // Custom wire format to ensure the required "text" field is always included, even when empty.
+ wire := struct {
+ Type string `json:"type"`
+ Text string `json:"text"`
+ Meta Meta `json:"_meta,omitempty"`
+ Annotations *Annotations `json:"annotations,omitempty"`
+ }{
+ Type: "text",
+ Text: c.Text,
+ Meta: c.Meta,
+ Annotations: c.Annotations,
+ }
+ return json.Marshal(wire)
}
-// SSEOptions specifies options for an [SSEHandler].
-// for now, it is empty, but may be extended in future.
-// https://github.com/modelcontextprotocol/go-sdk/issues/507
-type SSEOptions struct{}
-
-// NewSSEHandler returns a new [SSEHandler] that creates and manages MCP
-// sessions created via incoming HTTP requests.
-//
-// Sessions are created when the client issues a GET request to the server,
-// which must accept text/event-stream responses (server-sent events).
-// For each such request, a new [SSEServerTransport] is created with a distinct
-// messages endpoint, and connected to the server returned by getServer.
+func (c *TextContent) fromWire(wire *wireContent) {
+ c.Text = wire.Text
+ c.Meta = wire.Meta
+ c.Annotations = wire.Annotations
```
This function is important because it defines how MCP Go SDK Tutorial: Building Robust MCP Clients and Servers in Go implements the patterns covered in this chapter.
-### `mcp/sse.go`
+### `mcp/content.go`
-The `Close` function in [`mcp/sse.go`](https://github.com/modelcontextprotocol/go-sdk/blob/HEAD/mcp/sse.go) handles a key part of this chapter's functionality:
+The `unmarshalContent` function in [`mcp/content.go`](https://github.com/modelcontextprotocol/go-sdk/blob/HEAD/mcp/content.go) handles a key part of this chapter's functionality:
```go
-// exited.
-// - Read reads off a message queue that is pushed to via POST requests.
-// - Close causes the hanging GET to exit.
-
-// SSEHandler is an http.Handler that serves SSE-based MCP sessions as defined by
-// the [2024-11-05 version] of the MCP spec.
-//
-// [2024-11-05 version]: https://modelcontextprotocol.io/specification/2024-11-05/basic/transports
-type SSEHandler struct {
- getServer func(request *http.Request) *Server
- opts SSEOptions
- onConnection func(*ServerSession) // for testing; must not block
-
- mu sync.Mutex
- sessions map[string]*SSEServerTransport
}
-// SSEOptions specifies options for an [SSEHandler].
-// for now, it is empty, but may be extended in future.
-// https://github.com/modelcontextprotocol/go-sdk/issues/507
-type SSEOptions struct{}
-
-// NewSSEHandler returns a new [SSEHandler] that creates and manages MCP
-// sessions created via incoming HTTP requests.
-//
-// Sessions are created when the client issues a GET request to the server,
-// which must accept text/event-stream responses (server-sent events).
-// For each such request, a new [SSEServerTransport] is created with a distinct
-// messages endpoint, and connected to the server returned by getServer.
-// The SSEHandler also handles requests to the message endpoints, by
-// delegating them to the relevant server transport.
-//
+// unmarshalContent unmarshals JSON that is either a single content object or
+// an array of content objects. A single object is wrapped in a one-element slice.
+func unmarshalContent(raw json.RawMessage, allow map[string]bool) ([]Content, error) {
+ if len(raw) == 0 || string(raw) == "null" {
+ return nil, fmt.Errorf("nil content")
+ }
+ // Try array first, then fall back to single object.
+ var wires []*wireContent
+ if err := internaljson.Unmarshal(raw, &wires); err == nil {
+ return contentsFromWire(wires, allow)
+ }
+ var wire wireContent
+ if err := internaljson.Unmarshal(raw, &wire); err != nil {
+ return nil, err
+ }
+ c, err := contentFromWire(&wire, allow)
+ if err != nil {
+ return nil, err
+ }
+ return []Content{c}, nil
+}
+
+func contentsFromWire(wires []*wireContent, allow map[string]bool) ([]Content, error) {
+ blocks := make([]Content, 0, len(wires))
+ for _, wire := range wires {
+ block, err := contentFromWire(wire, allow)
+ if err != nil {
+ return nil, err
+ }
+ blocks = append(blocks, block)
```
This function is important because it defines how MCP Go SDK Tutorial: Building Robust MCP Clients and Servers in Go implements the patterns covered in this chapter.
-### `mcp/sse.go`
+### `mcp/content.go`
-The `for` interface in [`mcp/sse.go`](https://github.com/modelcontextprotocol/go-sdk/blob/HEAD/mcp/sse.go) handles a key part of this chapter's functionality:
+The `contentsFromWire` function in [`mcp/content.go`](https://github.com/modelcontextprotocol/go-sdk/blob/HEAD/mcp/content.go) handles a key part of this chapter's functionality:
```go
-)
-
-// This file implements support for SSE (HTTP with server-sent events)
-// transport server and client.
-// https://modelcontextprotocol.io/specification/2024-11-05/basic/transports
-//
-// The transport is simple, at least relative to the new streamable transport
-// introduced in the 2025-03-26 version of the spec. In short:
-//
-// 1. Sessions are initiated via a hanging GET request, which streams
-// server->client messages as SSE 'message' events.
-// 2. The first event in the SSE stream must be an 'endpoint' event that
-// informs the client of the session endpoint.
-// 3. The client POSTs client->server messages to the session endpoint.
-//
-// Therefore, the each new GET request hands off its responsewriter to an
-// [SSEServerTransport] type that abstracts the transport as follows:
-// - Write writes a new event to the responseWriter, or fails if the GET has
-// exited.
-// - Read reads off a message queue that is pushed to via POST requests.
-// - Close causes the hanging GET to exit.
-
-// SSEHandler is an http.Handler that serves SSE-based MCP sessions as defined by
-// the [2024-11-05 version] of the MCP spec.
-//
-// [2024-11-05 version]: https://modelcontextprotocol.io/specification/2024-11-05/basic/transports
-type SSEHandler struct {
- getServer func(request *http.Request) *Server
- opts SSEOptions
- onConnection func(*ServerSession) // for testing; must not block
-
- mu sync.Mutex
+ var wires []*wireContent
+ if err := internaljson.Unmarshal(raw, &wires); err == nil {
+ return contentsFromWire(wires, allow)
+ }
+ var wire wireContent
+ if err := internaljson.Unmarshal(raw, &wire); err != nil {
+ return nil, err
+ }
+ c, err := contentFromWire(&wire, allow)
+ if err != nil {
+ return nil, err
+ }
+ return []Content{c}, nil
+}
+
+func contentsFromWire(wires []*wireContent, allow map[string]bool) ([]Content, error) {
+ blocks := make([]Content, 0, len(wires))
+ for _, wire := range wires {
+ block, err := contentFromWire(wire, allow)
+ if err != nil {
+ return nil, err
+ }
+ blocks = append(blocks, block)
+ }
+ return blocks, nil
+}
+
+func contentFromWire(wire *wireContent, allow map[string]bool) (Content, error) {
+ if wire == nil {
+ return nil, fmt.Errorf("nil content")
+ }
+ if allow != nil && !allow[wire.Type] {
```
-This interface is important because it defines how MCP Go SDK Tutorial: Building Robust MCP Clients and Servers in Go implements the patterns covered in this chapter.
+This function is important because it defines how MCP Go SDK Tutorial: Building Robust MCP Clients and Servers in Go implements the patterns covered in this chapter.
-### `mcp/sse.go`
+### `mcp/content.go`
-The `from` interface in [`mcp/sse.go`](https://github.com/modelcontextprotocol/go-sdk/blob/HEAD/mcp/sse.go) handles a key part of this chapter's functionality:
+The `contentFromWire` function in [`mcp/content.go`](https://github.com/modelcontextprotocol/go-sdk/blob/HEAD/mcp/content.go) handles a key part of this chapter's functionality:
```go
-// When connected, it returns the following [Connection] implementation:
-// - Writes are SSE 'message' events to the GET response.
-// - Reads are received from POSTs to the session endpoint, via
-// [SSEServerTransport.ServeHTTP].
-// - Close terminates the hanging GET.
-//
-// The transport is itself an [http.Handler]. It is the caller's responsibility
-// to ensure that the resulting transport serves HTTP requests on the given
-// session endpoint.
-//
-// Each SSEServerTransport may be connected (via [Server.Connect]) at most
-// once, since [SSEServerTransport.ServeHTTP] serves messages to the connected
-// session.
-//
-// Most callers should instead use an [SSEHandler], which transparently handles
-// the delegation to SSEServerTransports.
-type SSEServerTransport struct {
- // Endpoint is the endpoint for this session, where the client can POST
- // messages.
- Endpoint string
-
- // Response is the hanging response body to the incoming GET request.
- Response http.ResponseWriter
-
- // incoming is the queue of incoming messages.
- // It is never closed, and by convention, incoming is non-nil if and only if
- // the transport is connected.
- incoming chan jsonrpc.Message
-
- // We must guard both pushes to the incoming queue and writes to the response
- // writer, because incoming POST requests are arbitrarily concurrent and we
- // need to ensure we don't write push to the queue, or write to the
+ c.IsError = wire.IsError
+ c.Meta = wire.Meta
+ // Content is handled separately in contentFromWire due to nested content
+}
+
+// ResourceContents contains the contents of a specific resource or
+// sub-resource.
+type ResourceContents struct {
+ URI string `json:"uri"`
+ MIMEType string `json:"mimeType,omitempty"`
+ Text string `json:"text,omitempty"`
+ Blob []byte `json:"blob,omitzero"`
+ Meta Meta `json:"_meta,omitempty"`
+}
+
+// wireContent is the wire format for content.
+// It represents the protocol types TextContent, ImageContent, AudioContent,
+// ResourceLink, EmbeddedResource, ToolUseContent, and ToolResultContent.
+// The Type field distinguishes them. In the protocol, each type has a constant
+// value for the field.
+type wireContent struct {
+ Type string `json:"type"`
+ Text string `json:"text,omitempty"` // TextContent
+ MIMEType string `json:"mimeType,omitempty"` // ImageContent, AudioContent, ResourceLink
+ Data []byte `json:"data,omitempty"` // ImageContent, AudioContent
+ Resource *ResourceContents `json:"resource,omitempty"` // EmbeddedResource
+ URI string `json:"uri,omitempty"` // ResourceLink
+ Name string `json:"name,omitempty"` // ResourceLink, ToolUseContent
+ Title string `json:"title,omitempty"` // ResourceLink
+ Description string `json:"description,omitempty"` // ResourceLink
+ Size *int64 `json:"size,omitempty"` // ResourceLink
+ Meta Meta `json:"_meta,omitempty"` // all types
```
-This interface is important because it defines how MCP Go SDK Tutorial: Building Robust MCP Clients and Servers in Go implements the patterns covered in this chapter.
+This function is important because it defines how MCP Go SDK Tutorial: Building Robust MCP Clients and Servers in Go implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[Write]
- B[Close]
- C[for]
- D[from]
- E[Empty]
+ A[fromWire]
+ B[unmarshalContent]
+ C[contentsFromWire]
+ D[contentFromWire]
+ E[NewSSEHandler]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-go-sdk-tutorial/03-transports-stdio-streamable-http-and-custom-flows.md b/tutorials/mcp-go-sdk-tutorial/03-transports-stdio-streamable-http-and-custom-flows.md
index 8bb86343..293dd788 100644
--- a/tutorials/mcp-go-sdk-tutorial/03-transports-stdio-streamable-http-and-custom-flows.md
+++ b/tutorials/mcp-go-sdk-tutorial/03-transports-stdio-streamable-http-and-custom-flows.md
@@ -46,170 +46,168 @@ You now have a transport strategy that is aligned with Go SDK behavior and opera
Next: [Chapter 4: Building Tools, Resources, and Prompts in Go](04-building-tools-resources-and-prompts-in-go.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `mcp/shared.go`
+### `mcp/client.go`
-The `setProgressToken` function in [`mcp/shared.go`](https://github.com/modelcontextprotocol/go-sdk/blob/HEAD/mcp/shared.go) handles a key part of this chapter's functionality:
+The `Error` function in [`mcp/client.go`](https://github.com/modelcontextprotocol/go-sdk/blob/HEAD/mcp/client.go) handles a key part of this chapter's functionality:
```go
-}
-func setProgressToken(p Params, pt any) {
- switch pt.(type) {
- // Support int32 and int64 for atomic.IntNN.
- case int, int32, int64, string:
- default:
- panic(fmt.Sprintf("progress token %v is of type %[1]T, not int or string", pt))
- }
- m := p.GetMeta()
- if m == nil {
- m = map[string]any{}
- p.SetMeta(m)
- }
- m[progressTokenKey] = pt
+// TODO: Consider exporting this type and its field.
+type unsupportedProtocolVersionError struct {
+ version string
}
-// A Request is a method request with parameters and additional information, such as the session.
-// Request is implemented by [*ClientRequest] and [*ServerRequest].
-type Request interface {
- isRequest()
- GetSession() Session
- GetParams() Params
- // GetExtra returns the Extra field for ServerRequests, and nil for ClientRequests.
- GetExtra() *RequestExtra
+func (e unsupportedProtocolVersionError) Error() string {
+ return fmt.Sprintf("unsupported protocol version: %q", e.version)
}
-// A ClientRequest is a request to a client.
-type ClientRequest[P Params] struct {
- Session *ClientSession
- Params P
+// ClientSessionOptions is reserved for future use.
+type ClientSessionOptions struct {
+ // protocolVersion overrides the protocol version sent in the initialize
+ // request, for testing. If empty, latestProtocolVersion is used.
+ protocolVersion string
}
+
+func (c *Client) capabilities(protocolVersion string) *ClientCapabilities {
+ // Start with user-provided capabilities as defaults, or use SDK defaults.
+ var caps *ClientCapabilities
+ if c.opts.Capabilities != nil {
+ // Deep copy the user-provided capabilities to avoid mutation.
+ caps = c.opts.Capabilities.clone()
+ } else {
+ // SDK defaults: roots with listChanged.
+ // (this was the default behavior at v1.0.0, and so cannot be changed)
+ caps = &ClientCapabilities{
+ RootsV2: &RootCapabilities{
+ ListChanged: true,
+ },
+ }
+ }
```
This function is important because it defines how MCP Go SDK Tutorial: Building Robust MCP Clients and Servers in Go implements the patterns covered in this chapter.
-### `mcp/shared.go`
+### `mcp/client.go`
-The `startKeepalive` function in [`mcp/shared.go`](https://github.com/modelcontextprotocol/go-sdk/blob/HEAD/mcp/shared.go) handles a key part of this chapter's functionality:
+The `capabilities` function in [`mcp/client.go`](https://github.com/modelcontextprotocol/go-sdk/blob/HEAD/mcp/client.go) handles a key part of this chapter's functionality:
```go
-}
-
-// startKeepalive starts the keepalive mechanism for a session.
-// It assigns the cancel function to the provided cancelPtr and starts a goroutine
-// that sends ping messages at the specified interval.
-func startKeepalive(session keepaliveSession, interval time.Duration, cancelPtr *context.CancelFunc) {
- ctx, cancel := context.WithCancel(context.Background())
- // Assign cancel function before starting goroutine to avoid race condition.
- // We cannot return it because the caller may need to cancel during the
- // window between goroutine scheduling and function return.
- *cancelPtr = cancel
-
- go func() {
- ticker := time.NewTicker(interval)
- defer ticker.Stop()
-
- for {
- select {
- case <-ctx.Done():
- return
- case <-ticker.C:
- pingCtx, pingCancel := context.WithTimeout(context.Background(), interval/2)
- err := session.Ping(pingCtx, nil)
- pingCancel()
- if err != nil {
- // Ping failed, close the session
- _ = session.Close()
- return
- }
- }
- }
- }()
+ // overrides the inferred capability.
+ ElicitationHandler func(context.Context, *ElicitRequest) (*ElicitResult, error)
+ // Capabilities optionally configures the client's default capabilities,
+ // before any capabilities are inferred from other configuration.
+ //
+ // If Capabilities is nil, the default client capabilities are
+ // {"roots":{"listChanged":true}}, for historical reasons. Setting
+ // Capabilities to a non-nil value overrides this default. As a special case,
+ // to work around #607, Capabilities.Roots is ignored: set
+ // Capabilities.RootsV2 to configure the roots capability. This allows the
+ // "roots" capability to be disabled entirely.
+ //
+ // For example:
+ // - To disable the "roots" capability, use &ClientCapabilities{}
+ // - To configure "roots", but disable "listChanged" notifications, use
+ // &ClientCapabilities{RootsV2:&RootCapabilities{}}.
+ //
+ // # Interaction with capability inference
+ //
+ // Sampling and elicitation capabilities are automatically added when their
+ // corresponding handlers are set, with the default value described at
+ // [ClientOptions.CreateMessageHandler] and
+ // [ClientOptions.ElicitationHandler]. If the Sampling or Elicitation fields
+ // are set in the Capabilities field, their values override the inferred
+ // value.
+ //
+ // For example, to advertise sampling with tools and context support:
+ //
+ // Capabilities: &ClientCapabilities{
+ // Sampling: &SamplingCapabilities{
+ // Tools: &SamplingToolsCapabilities{},
+ // Context: &SamplingContextCapabilities{},
```
This function is important because it defines how MCP Go SDK Tutorial: Building Robust MCP Clients and Servers in Go implements the patterns covered in this chapter.
-### `mcp/shared.go`
+### `mcp/client.go`
-The `the` interface in [`mcp/shared.go`](https://github.com/modelcontextprotocol/go-sdk/blob/HEAD/mcp/shared.go) handles a key part of this chapter's functionality:
+The `Connect` function in [`mcp/client.go`](https://github.com/modelcontextprotocol/go-sdk/blob/HEAD/mcp/client.go) handles a key part of this chapter's functionality:
```go
-// Copyright 2025 The Go MCP SDK Authors. All rights reserved.
-// Use of this source code is governed by an MIT-style
-// license that can be found in the LICENSE file.
-// This file contains code shared between client and server, including
-// method handler and middleware definitions.
+// A Client is an MCP client, which may be connected to an MCP server
+// using the [Client.Connect] method.
+type Client struct {
+ impl *Implementation
+ opts ClientOptions
+ mu sync.Mutex
+ roots *featureSet[*Root]
+ sessions []*ClientSession
+ sendingMethodHandler_ MethodHandler
+ receivingMethodHandler_ MethodHandler
+}
+
+// NewClient creates a new [Client].
//
-// Much of this is here so that we can factor out commonalities using
-// generics. If this becomes unwieldy, it can perhaps be simplified with
-// reflection.
-
-package mcp
-
-import (
- "context"
- "encoding/json"
- "fmt"
- "log/slog"
- "net/http"
- "reflect"
- "slices"
- "strings"
- "time"
-
- "github.com/modelcontextprotocol/go-sdk/auth"
- internaljson "github.com/modelcontextprotocol/go-sdk/internal/json"
- "github.com/modelcontextprotocol/go-sdk/internal/jsonrpc2"
- "github.com/modelcontextprotocol/go-sdk/jsonrpc"
-)
-
-const (
- // latestProtocolVersion is the latest protocol version that this version of
+// Use [Client.Connect] to connect it to an MCP server.
+//
+// The first argument must not be nil.
+//
+// If non-nil, the provided options configure the Client.
+func NewClient(impl *Implementation, options *ClientOptions) *Client {
+ if impl == nil {
+ panic("nil Implementation")
+ }
+ var opts ClientOptions
+ if options != nil {
+ opts = *options
+ }
+ options = nil // prevent reuse
+
+ if opts.CreateMessageHandler != nil && opts.CreateMessageWithToolsHandler != nil {
+ panic("cannot set both CreateMessageHandler and CreateMessageWithToolsHandler; use CreateMessageWithToolsHandler for tool support, or CreateMessageHandler for basic sampling")
```
-This interface is important because it defines how MCP Go SDK Tutorial: Building Robust MCP Clients and Servers in Go implements the patterns covered in this chapter.
+This function is important because it defines how MCP Go SDK Tutorial: Building Robust MCP Clients and Servers in Go implements the patterns covered in this chapter.
-### `auth/authorization_code.go`
+### `mcp/client.go`
-The `isOAuthHandler` function in [`auth/authorization_code.go`](https://github.com/modelcontextprotocol/go-sdk/blob/HEAD/auth/authorization_code.go) handles a key part of this chapter's functionality:
+The `InitializeResult` function in [`mcp/client.go`](https://github.com/modelcontextprotocol/go-sdk/blob/HEAD/mcp/client.go) handles a key part of this chapter's functionality:
```go
-var _ OAuthHandler = (*AuthorizationCodeHandler)(nil)
-
-func (h *AuthorizationCodeHandler) isOAuthHandler() {}
-
-func (h *AuthorizationCodeHandler) TokenSource(ctx context.Context) (oauth2.TokenSource, error) {
- return h.tokenSource, nil
-}
-
-// NewAuthorizationCodeHandler creates a new AuthorizationCodeHandler.
-// It performs validation of the configuration and returns an error if it is invalid.
-// The passed config is consumed by the handler and should not be modified after.
-func NewAuthorizationCodeHandler(config *AuthorizationCodeHandlerConfig) (*AuthorizationCodeHandler, error) {
- if config == nil {
- return nil, errors.New("config must be provided")
}
- if config.ClientIDMetadataDocumentConfig == nil &&
- config.PreregisteredClientConfig == nil &&
- config.DynamicClientRegistrationConfig == nil {
- return nil, errors.New("at least one client registration configuration must be provided")
+ req := &InitializeRequest{Session: cs, Params: params}
+ res, err := handleSend[*InitializeResult](ctx, methodInitialize, req)
+ if err != nil {
+ _ = cs.Close()
+ return nil, err
}
- if config.AuthorizationCodeFetcher == nil {
- return nil, errors.New("AuthorizationCodeFetcher is required")
+ if !slices.Contains(supportedProtocolVersions, res.ProtocolVersion) {
+ return nil, unsupportedProtocolVersionError{res.ProtocolVersion}
}
- if config.ClientIDMetadataDocumentConfig != nil && !isNonRootHTTPSURL(config.ClientIDMetadataDocumentConfig.URL) {
- return nil, fmt.Errorf("client ID metadata document URL must be a non-root HTTPS URL")
+ cs.state.InitializeResult = res
+ if hc, ok := cs.mcpConn.(clientConnection); ok {
+ hc.sessionUpdated(cs.state)
}
- preCfg := config.PreregisteredClientConfig
- if preCfg != nil {
- if preCfg.ClientSecretAuthConfig == nil {
- return nil, errors.New("ClientSecretAuthConfig is required for pre-registered client")
- }
- if preCfg.ClientSecretAuthConfig.ClientID == "" || preCfg.ClientSecretAuthConfig.ClientSecret == "" {
+ req2 := &initializedClientRequest{Session: cs, Params: &InitializedParams{}}
+ if err := handleNotify(ctx, notificationInitialized, req2); err != nil {
+ _ = cs.Close()
+ return nil, err
+ }
+
+ if c.opts.KeepAlive > 0 {
+ cs.startKeepalive(c.opts.KeepAlive)
+ }
+
+ return cs, nil
+}
+
+// A ClientSession is a logical connection with an MCP server. Its
+// methods can be used to send requests or notifications to the server. Create
+// a session by calling [Client.Connect].
+//
+// Call [ClientSession.Close] to close the connection, or await server
```
This function is important because it defines how MCP Go SDK Tutorial: Building Robust MCP Clients and Servers in Go implements the patterns covered in this chapter.
@@ -219,11 +217,11 @@ This function is important because it defines how MCP Go SDK Tutorial: Building
```mermaid
flowchart TD
- A[setProgressToken]
- B[startKeepalive]
- C[the]
- D[isOAuthHandler]
- E[TokenSource]
+ A[Error]
+ B[capabilities]
+ C[Connect]
+ D[InitializeResult]
+ E[ID]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-go-sdk-tutorial/04-building-tools-resources-and-prompts-in-go.md b/tutorials/mcp-go-sdk-tutorial/04-building-tools-resources-and-prompts-in-go.md
index a5c8c4d3..26c7a775 100644
--- a/tutorials/mcp-go-sdk-tutorial/04-building-tools-resources-and-prompts-in-go.md
+++ b/tutorials/mcp-go-sdk-tutorial/04-building-tools-resources-and-prompts-in-go.md
@@ -46,170 +46,168 @@ You now have a repeatable way to build server primitives that stay understandabl
Next: [Chapter 5: Client Capabilities: Roots, Sampling, and Elicitation](05-client-capabilities-roots-sampling-and-elicitation.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `mcp/transport.go`
+### `mcp/client.go`
-The `Close` function in [`mcp/transport.go`](https://github.com/modelcontextprotocol/go-sdk/blob/HEAD/mcp/transport.go) handles a key part of this chapter's functionality:
+The `handle` function in [`mcp/client.go`](https://github.com/modelcontextprotocol/go-sdk/blob/HEAD/mcp/client.go) handles a key part of this chapter's functionality:
```go
-)
-
-// ErrConnectionClosed is returned when sending a message to a connection that
-// is closed or in the process of closing.
-var ErrConnectionClosed = errors.New("connection closed")
-
-// ErrSessionMissing is returned when the session is known to not be present on
-// the server.
-var ErrSessionMissing = errors.New("session not found")
-
-// A Transport is used to create a bidirectional connection between MCP client
-// and server.
-//
-// Transports should be used for at most one call to [Server.Connect] or
-// [Client.Connect].
-type Transport interface {
- // Connect returns the logical JSON-RPC connection..
+ // Logger may be set to a non-nil value to enable logging of client activity.
+ Logger *slog.Logger
+ // CreateMessageHandler handles incoming requests for sampling/createMessage.
//
- // It is called exactly once by [Server.Connect] or [Client.Connect].
- Connect(ctx context.Context) (Connection, error)
-}
-
-// A Connection is a logical bidirectional JSON-RPC connection.
-type Connection interface {
- // Read reads the next message to process off the connection.
+ // Setting CreateMessageHandler to a non-nil value automatically causes the
+ // client to advertise the sampling capability, with default value
+ // &SamplingCapabilities{}. If [ClientOptions.Capabilities] is set and has a
+ // non nil value for [ClientCapabilities.Sampling], that value overrides the
+ // inferred capability.
+ CreateMessageHandler func(context.Context, *CreateMessageRequest) (*CreateMessageResult, error)
+ // CreateMessageWithToolsHandler handles incoming sampling/createMessage
+ // requests that may involve tool use. It returns
+ // [CreateMessageWithToolsResult], which supports array content for parallel
+ // tool calls.
//
- // Connections must allow Read to be called concurrently with Close. In
- // particular, calling Close should unblock a Read waiting for input.
- Read(context.Context) (jsonrpc.Message, error)
-
- // Write writes a new message to the connection.
+ // Setting this handler causes the client to advertise the sampling
+ // capability with tools support (sampling.tools). As with
+ // [CreateMessageHandler], [ClientOptions.Capabilities].Sampling overrides
+ // the inferred capability.
+ //
+ // It is a panic to set both CreateMessageHandler and
+ // CreateMessageWithToolsHandler.
+ CreateMessageWithToolsHandler func(context.Context, *CreateMessageWithToolsRequest) (*CreateMessageWithToolsResult, error)
+ // ElicitationHandler handles incoming requests for elicitation/create.
//
+ // Setting ElicitationHandler to a non-nil value automatically causes the
+ // client to advertise the elicitation capability, with default value
+ // &ElicitationCapabilities{}. If [ClientOptions.Capabilities] is set and has
+ // a non nil value for [ClientCapabilities.ELicitattion], that value
+ // overrides the inferred capability.
+ ElicitationHandler func(context.Context, *ElicitRequest) (*ElicitResult, error)
+ // Capabilities optionally configures the client's default capabilities,
```
This function is important because it defines how MCP Go SDK Tutorial: Building Robust MCP Clients and Servers in Go implements the patterns covered in this chapter.
-### `mcp/transport.go`
+### `mcp/client.go`
-The `Read` function in [`mcp/transport.go`](https://github.com/modelcontextprotocol/go-sdk/blob/HEAD/mcp/transport.go) handles a key part of this chapter's functionality:
+The `sendingMethodHandler` function in [`mcp/client.go`](https://github.com/modelcontextprotocol/go-sdk/blob/HEAD/mcp/client.go) handles a key part of this chapter's functionality:
```go
-// A Connection is a logical bidirectional JSON-RPC connection.
-type Connection interface {
- // Read reads the next message to process off the connection.
- //
- // Connections must allow Read to be called concurrently with Close. In
- // particular, calling Close should unblock a Read waiting for input.
- Read(context.Context) (jsonrpc.Message, error)
-
- // Write writes a new message to the connection.
- //
- // Write may be called concurrently, as calls or responses may occur
- // concurrently in user code.
- Write(context.Context, jsonrpc.Message) error
-
- // Close closes the connection. It is implicitly called whenever a Read or
- // Write fails.
- //
- // Close may be called multiple times, potentially concurrently.
- Close() error
-
- // TODO(#148): remove SessionID from this interface.
- SessionID() string
+ roots *featureSet[*Root]
+ sessions []*ClientSession
+ sendingMethodHandler_ MethodHandler
+ receivingMethodHandler_ MethodHandler
}
-// A ClientConnection is a [Connection] that is specific to the MCP client.
+// NewClient creates a new [Client].
//
-// If client connections implement this interface, they may receive information
-// about changes to the client session.
+// Use [Client.Connect] to connect it to an MCP server.
//
-// TODO: should this interface be exported?
-type clientConnection interface {
- Connection
+// The first argument must not be nil.
+//
+// If non-nil, the provided options configure the Client.
+func NewClient(impl *Implementation, options *ClientOptions) *Client {
+ if impl == nil {
+ panic("nil Implementation")
+ }
+ var opts ClientOptions
+ if options != nil {
+ opts = *options
+ }
+ options = nil // prevent reuse
+
+ if opts.CreateMessageHandler != nil && opts.CreateMessageWithToolsHandler != nil {
+ panic("cannot set both CreateMessageHandler and CreateMessageWithToolsHandler; use CreateMessageWithToolsHandler for tool support, or CreateMessageHandler for basic sampling")
+ }
+ if opts.Logger == nil { // ensure we have a logger
+ opts.Logger = ensureLogger(nil)
+ }
+
+ return &Client{
+ impl: impl,
```
This function is important because it defines how MCP Go SDK Tutorial: Building Robust MCP Clients and Servers in Go implements the patterns covered in this chapter.
-### `mcp/transport.go`
+### `mcp/client.go`
-The `Write` function in [`mcp/transport.go`](https://github.com/modelcontextprotocol/go-sdk/blob/HEAD/mcp/transport.go) handles a key part of this chapter's functionality:
+The `receivingMethodHandler` function in [`mcp/client.go`](https://github.com/modelcontextprotocol/go-sdk/blob/HEAD/mcp/client.go) handles a key part of this chapter's functionality:
```go
- Read(context.Context) (jsonrpc.Message, error)
-
- // Write writes a new message to the connection.
- //
- // Write may be called concurrently, as calls or responses may occur
- // concurrently in user code.
- Write(context.Context, jsonrpc.Message) error
-
- // Close closes the connection. It is implicitly called whenever a Read or
- // Write fails.
- //
- // Close may be called multiple times, potentially concurrently.
- Close() error
-
- // TODO(#148): remove SessionID from this interface.
- SessionID() string
+ sessions []*ClientSession
+ sendingMethodHandler_ MethodHandler
+ receivingMethodHandler_ MethodHandler
}
-// A ClientConnection is a [Connection] that is specific to the MCP client.
+// NewClient creates a new [Client].
//
-// If client connections implement this interface, they may receive information
-// about changes to the client session.
+// Use [Client.Connect] to connect it to an MCP server.
//
-// TODO: should this interface be exported?
-type clientConnection interface {
- Connection
-
- // sessionUpdated is called whenever the client session state changes.
- sessionUpdated(clientSessionState)
-}
-
-// A serverConnection is a Connection that is specific to the MCP server.
+// The first argument must not be nil.
+//
+// If non-nil, the provided options configure the Client.
+func NewClient(impl *Implementation, options *ClientOptions) *Client {
+ if impl == nil {
+ panic("nil Implementation")
+ }
+ var opts ClientOptions
+ if options != nil {
+ opts = *options
+ }
+ options = nil // prevent reuse
+
+ if opts.CreateMessageHandler != nil && opts.CreateMessageWithToolsHandler != nil {
+ panic("cannot set both CreateMessageHandler and CreateMessageWithToolsHandler; use CreateMessageWithToolsHandler for tool support, or CreateMessageHandler for basic sampling")
+ }
+ if opts.Logger == nil { // ensure we have a logger
+ opts.Logger = ensureLogger(nil)
+ }
+
+ return &Client{
+ impl: impl,
+ opts: opts,
```
This function is important because it defines how MCP Go SDK Tutorial: Building Robust MCP Clients and Servers in Go implements the patterns covered in this chapter.
-### `mcp/transport.go`
+### `mcp/client.go`
-The `Close` function in [`mcp/transport.go`](https://github.com/modelcontextprotocol/go-sdk/blob/HEAD/mcp/transport.go) handles a key part of this chapter's functionality:
+The `getConn` function in [`mcp/client.go`](https://github.com/modelcontextprotocol/go-sdk/blob/HEAD/mcp/client.go) handles a key part of this chapter's functionality:
```go
-)
+}
-// ErrConnectionClosed is returned when sending a message to a connection that
-// is closed or in the process of closing.
-var ErrConnectionClosed = errors.New("connection closed")
+// getConn implements [Session.getConn].
+func (cs *ClientSession) getConn() *jsonrpc2.Connection { return cs.conn }
-// ErrSessionMissing is returned when the session is known to not be present on
-// the server.
-var ErrSessionMissing = errors.New("session not found")
+func (*ClientSession) ping(context.Context, *PingParams) (*emptyResult, error) {
+ return &emptyResult{}, nil
+}
-// A Transport is used to create a bidirectional connection between MCP client
-// and server.
+// cancel is a placeholder: cancellation is handled the jsonrpc2 package.
//
-// Transports should be used for at most one call to [Server.Connect] or
-// [Client.Connect].
-type Transport interface {
- // Connect returns the logical JSON-RPC connection..
- //
- // It is called exactly once by [Server.Connect] or [Client.Connect].
- Connect(ctx context.Context) (Connection, error)
+// It should never be invoked in practice because cancellation is preempted,
+// but having its signature here facilitates the construction of methodInfo
+// that can be used to validate incoming cancellation notifications.
+func (*ClientSession) cancel(context.Context, *CancelledParams) (Result, error) {
+ return nil, nil
}
-// A Connection is a logical bidirectional JSON-RPC connection.
-type Connection interface {
- // Read reads the next message to process off the connection.
- //
- // Connections must allow Read to be called concurrently with Close. In
- // particular, calling Close should unblock a Read waiting for input.
- Read(context.Context) (jsonrpc.Message, error)
+func newClientRequest[P Params](cs *ClientSession, params P) *ClientRequest[P] {
+ return &ClientRequest[P]{Session: cs, Params: params}
+}
- // Write writes a new message to the connection.
- //
+// Ping makes an MCP "ping" request to the server.
+func (cs *ClientSession) Ping(ctx context.Context, params *PingParams) error {
+ _, err := handleSend[*emptyResult](ctx, methodPing, newClientRequest(cs, orZero[Params](params)))
+ return err
+}
+
+// ListPrompts lists prompts that are currently available on the server.
+func (cs *ClientSession) ListPrompts(ctx context.Context, params *ListPromptsParams) (*ListPromptsResult, error) {
+ return handleSend[*ListPromptsResult](ctx, methodListPrompts, newClientRequest(cs, orZero[Params](params)))
+}
```
This function is important because it defines how MCP Go SDK Tutorial: Building Robust MCP Clients and Servers in Go implements the patterns covered in this chapter.
@@ -219,11 +217,11 @@ This function is important because it defines how MCP Go SDK Tutorial: Building
```mermaid
flowchart TD
- A[Close]
- B[Read]
- C[Write]
- D[Close]
- E[newIOConn]
+ A[handle]
+ B[sendingMethodHandler]
+ C[receivingMethodHandler]
+ D[getConn]
+ E[Ping]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-go-sdk-tutorial/05-client-capabilities-roots-sampling-and-elicitation.md b/tutorials/mcp-go-sdk-tutorial/05-client-capabilities-roots-sampling-and-elicitation.md
index 54dac0dc..6bff4088 100644
--- a/tutorials/mcp-go-sdk-tutorial/05-client-capabilities-roots-sampling-and-elicitation.md
+++ b/tutorials/mcp-go-sdk-tutorial/05-client-capabilities-roots-sampling-and-elicitation.md
@@ -46,184 +46,182 @@ You now have a client capability model that keeps advanced features controlled a
Next: [Chapter 6: Auth, Security, and Runtime Hardening](06-auth-security-and-runtime-hardening.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `mcp/client.go`
-The `shouldSendListChangedNotification` function in [`mcp/client.go`](https://github.com/modelcontextprotocol/go-sdk/blob/HEAD/mcp/client.go) handles a key part of this chapter's functionality:
+The `Prompts` function in [`mcp/client.go`](https://github.com/modelcontextprotocol/go-sdk/blob/HEAD/mcp/client.go) handles a key part of this chapter's functionality:
```go
- if change() {
- // Check if listChanged is enabled for this notification type.
- if c.shouldSendListChangedNotification(notification) {
- sessions = slices.Clone(c.sessions)
- }
- }
- c.mu.Unlock()
- notifySessions(sessions, notification, params, c.opts.Logger)
}
-// shouldSendListChangedNotification checks if the client's capabilities allow
-// sending the given list-changed notification.
-func (c *Client) shouldSendListChangedNotification(notification string) bool {
- // Get effective capabilities (considering user-provided defaults).
- caps := c.opts.Capabilities
-
- switch notification {
- case notificationRootsListChanged:
- // If user didn't specify capabilities, default behavior sends notifications.
- if caps == nil {
- return true
- }
- // Check RootsV2 first (preferred), then fall back to Roots.
- if caps.RootsV2 != nil {
- return caps.RootsV2.ListChanged
- }
- return caps.Roots.ListChanged
- default:
- // Unknown notification, allow by default.
- return true
+// ListPrompts lists prompts that are currently available on the server.
+func (cs *ClientSession) ListPrompts(ctx context.Context, params *ListPromptsParams) (*ListPromptsResult, error) {
+ return handleSend[*ListPromptsResult](ctx, methodListPrompts, newClientRequest(cs, orZero[Params](params)))
+}
+
+// GetPrompt gets a prompt from the server.
+func (cs *ClientSession) GetPrompt(ctx context.Context, params *GetPromptParams) (*GetPromptResult, error) {
+ return handleSend[*GetPromptResult](ctx, methodGetPrompt, newClientRequest(cs, orZero[Params](params)))
+}
+
+// ListTools lists tools that are currently available on the server.
+func (cs *ClientSession) ListTools(ctx context.Context, params *ListToolsParams) (*ListToolsResult, error) {
+ return handleSend[*ListToolsResult](ctx, methodListTools, newClientRequest(cs, orZero[Params](params)))
+}
+
+// CallTool calls the tool with the given parameters.
+//
+// The params.Arguments can be any value that marshals into a JSON object.
+func (cs *ClientSession) CallTool(ctx context.Context, params *CallToolParams) (*CallToolResult, error) {
+ if params == nil {
+ params = new(CallToolParams)
+ }
+ if params.Arguments == nil {
+ // Avoid sending nil over the wire.
+ params.Arguments = map[string]any{}
}
+ return handleSend[*CallToolResult](ctx, methodCallTool, newClientRequest(cs, orZero[Params](params)))
}
+
+func (cs *ClientSession) SetLoggingLevel(ctx context.Context, params *SetLoggingLevelParams) error {
```
This function is important because it defines how MCP Go SDK Tutorial: Building Robust MCP Clients and Servers in Go implements the patterns covered in this chapter.
### `mcp/client.go`
-The `listRoots` function in [`mcp/client.go`](https://github.com/modelcontextprotocol/go-sdk/blob/HEAD/mcp/client.go) handles a key part of this chapter's functionality:
+The `validation` interface in [`mcp/client.go`](https://github.com/modelcontextprotocol/go-sdk/blob/HEAD/mcp/client.go) handles a key part of this chapter's functionality:
```go
+ return nil, &jsonrpc.Error{Code: jsonrpc.CodeInvalidParams, Message: "URL must be set for URL elicitation"}
+ }
+ // No schema validation for URL mode, just pass through to handler.
+ return c.opts.ElicitationHandler(ctx, req)
+ default:
+ return nil, &jsonrpc.Error{Code: jsonrpc.CodeInvalidParams, Message: fmt.Sprintf("unsupported elicitation mode: %q", mode)}
+ }
}
-func (c *Client) listRoots(_ context.Context, req *ListRootsRequest) (*ListRootsResult, error) {
- c.mu.Lock()
- defer c.mu.Unlock()
- roots := slices.Collect(c.roots.all())
- if roots == nil {
- roots = []*Root{} // avoid JSON null
+// validateElicitSchema validates that the schema conforms to MCP elicitation schema requirements.
+// Per the MCP specification, elicitation schemas are limited to flat objects with primitive properties only.
+func validateElicitSchema(wireSchema any) (*jsonschema.Schema, error) {
+ if wireSchema == nil {
+ return nil, nil // nil schema is allowed
}
- return &ListRootsResult{
- Roots: roots,
- }, nil
-}
-func (c *Client) createMessage(ctx context.Context, req *CreateMessageWithToolsRequest) (*CreateMessageWithToolsResult, error) {
- if c.opts.CreateMessageWithToolsHandler != nil {
- return c.opts.CreateMessageWithToolsHandler(ctx, req)
+ var schema *jsonschema.Schema
+ if err := remarshal(wireSchema, &schema); err != nil {
+ return nil, err
}
- if c.opts.CreateMessageHandler != nil {
- // Downconvert the request for the basic handler.
- baseParams, err := req.Params.toBase()
- if err != nil {
- return nil, err
- }
- baseReq := &CreateMessageRequest{
- Session: req.Session,
- Params: baseParams,
- }
- res, err := c.opts.CreateMessageHandler(ctx, baseReq)
- if err != nil {
- return nil, err
- }
+ if schema == nil {
+ return nil, nil
+ }
+
+ // The root schema must be of type "object" if specified
+ if schema.Type != "" && schema.Type != "object" {
+ return nil, fmt.Errorf("elicit schema must be of type 'object', got %q", schema.Type)
+ }
+
+ // Check if the schema has properties
+ if schema.Properties != nil {
+ for propName, propSchema := range schema.Properties {
```
-This function is important because it defines how MCP Go SDK Tutorial: Building Robust MCP Clients and Servers in Go implements the patterns covered in this chapter.
+This interface is important because it defines how MCP Go SDK Tutorial: Building Robust MCP Clients and Servers in Go implements the patterns covered in this chapter.
### `mcp/client.go`
-The `createMessage` function in [`mcp/client.go`](https://github.com/modelcontextprotocol/go-sdk/blob/HEAD/mcp/client.go) handles a key part of this chapter's functionality:
+The `values` interface in [`mcp/client.go`](https://github.com/modelcontextprotocol/go-sdk/blob/HEAD/mcp/client.go) handles a key part of this chapter's functionality:
```go
- // Logger may be set to a non-nil value to enable logging of client activity.
- Logger *slog.Logger
- // CreateMessageHandler handles incoming requests for sampling/createMessage.
+ // [ClientOptions.CreateMessageHandler] and
+ // [ClientOptions.ElicitationHandler]. If the Sampling or Elicitation fields
+ // are set in the Capabilities field, their values override the inferred
+ // value.
//
- // Setting CreateMessageHandler to a non-nil value automatically causes the
- // client to advertise the sampling capability, with default value
- // &SamplingCapabilities{}. If [ClientOptions.Capabilities] is set and has a
- // non nil value for [ClientCapabilities.Sampling], that value overrides the
- // inferred capability.
- CreateMessageHandler func(context.Context, *CreateMessageRequest) (*CreateMessageResult, error)
- // CreateMessageWithToolsHandler handles incoming sampling/createMessage
- // requests that may involve tool use. It returns
- // [CreateMessageWithToolsResult], which supports array content for parallel
- // tool calls.
+ // For example, to advertise sampling with tools and context support:
//
- // Setting this handler causes the client to advertise the sampling
- // capability with tools support (sampling.tools). As with
- // [CreateMessageHandler], [ClientOptions.Capabilities].Sampling overrides
- // the inferred capability.
+ // Capabilities: &ClientCapabilities{
+ // Sampling: &SamplingCapabilities{
+ // Tools: &SamplingToolsCapabilities{},
+ // Context: &SamplingContextCapabilities{},
+ // },
+ // }
//
- // It is a panic to set both CreateMessageHandler and
- // CreateMessageWithToolsHandler.
- CreateMessageWithToolsHandler func(context.Context, *CreateMessageWithToolsRequest) (*CreateMessageWithToolsResult, error)
- // ElicitationHandler handles incoming requests for elicitation/create.
+ // Or to configure elicitation modes:
//
- // Setting ElicitationHandler to a non-nil value automatically causes the
- // client to advertise the elicitation capability, with default value
- // &ElicitationCapabilities{}. If [ClientOptions.Capabilities] is set and has
- // a non nil value for [ClientCapabilities.ELicitattion], that value
- // overrides the inferred capability.
- ElicitationHandler func(context.Context, *ElicitRequest) (*ElicitResult, error)
- // Capabilities optionally configures the client's default capabilities,
+ // Capabilities: &ClientCapabilities{
+ // Elicitation: &ElicitationCapabilities{
+ // Form: &FormElicitationCapabilities{},
+ // URL: &URLElicitationCapabilities{},
+ // },
+ // }
+ //
+ // Conversely, if Capabilities does not set a field (for example, if the
+ // Elicitation field is nil), the inferred capability will be used.
+ Capabilities *ClientCapabilities
+ // ElicitationCompleteHandler handles incoming notifications for notifications/elicitation/complete.
+ ElicitationCompleteHandler func(context.Context, *ElicitationCompleteNotificationRequest)
+ // Handlers for notifications from the server.
+ ToolListChangedHandler func(context.Context, *ToolListChangedRequest)
+ PromptListChangedHandler func(context.Context, *PromptListChangedRequest)
+ ResourceListChangedHandler func(context.Context, *ResourceListChangedRequest)
```
-This function is important because it defines how MCP Go SDK Tutorial: Building Robust MCP Clients and Servers in Go implements the patterns covered in this chapter.
+This interface is important because it defines how MCP Go SDK Tutorial: Building Robust MCP Clients and Servers in Go implements the patterns covered in this chapter.
### `mcp/client.go`
-The `urlElicitationMiddleware` function in [`mcp/client.go`](https://github.com/modelcontextprotocol/go-sdk/blob/HEAD/mcp/client.go) handles a key part of this chapter's functionality:
+The `length` interface in [`mcp/client.go`](https://github.com/modelcontextprotocol/go-sdk/blob/HEAD/mcp/client.go) handles a key part of this chapter's functionality:
```go
-}
-
-// urlElicitationMiddleware returns middleware that automatically handles URL elicitation
-// required errors by executing the elicitation handler, waiting for completion notifications,
-// and retrying the operation.
-//
-// This middleware should be added to clients that want automatic URL elicitation handling:
-//
-// client := mcp.NewClient(impl, opts)
-// client.AddSendingMiddleware(mcp.urlElicitationMiddleware())
-//
-// TODO(rfindley): this isn't strictly necessary for the SEP, but may be
-// useful. Propose exporting it.
-func urlElicitationMiddleware() Middleware {
- return func(next MethodHandler) MethodHandler {
- return func(ctx context.Context, method string, req Request) (Result, error) {
- // Call the underlying handler.
- res, err := next(ctx, method, req)
- if err == nil {
- return res, nil
+ }
+ // Enum values themselves are validated by the JSON schema library
+ // Validate legacy enumNames if present - must match enum length.
+ if propSchema.Extra != nil {
+ if enumNamesRaw, exists := propSchema.Extra["enumNames"]; exists {
+ // Type check enumNames - should be a slice
+ if enumNamesSlice, ok := enumNamesRaw.([]any); ok {
+ if len(enumNamesSlice) != len(propSchema.Enum) {
+ return fmt.Errorf("elicit schema property %q has %d enum values but %d enumNames, they must match", propName, len(propSchema.Enum), len(enumNamesSlice))
+ }
+ } else {
+ return fmt.Errorf("elicit schema property %q has invalid enumNames type, must be an array", propName)
+ }
}
-
- // Check if this is a URL elicitation required error.
- var rpcErr *jsonrpc.Error
- if !errors.As(err, &rpcErr) || rpcErr.Code != CodeURLElicitationRequired {
- return res, err
+ }
+ return nil
+ }
+ // Handle new style of titled enums.
+ if propSchema.OneOf != nil {
+ for _, entry := range propSchema.OneOf {
+ if err := validateTitledEnumEntry(entry); err != nil {
+ return fmt.Errorf("elicit schema property %q oneOf has invalid entry: %v", propName, err)
}
+ }
+ return nil
+ }
- // Notifications don't support retries.
- if strings.HasPrefix(method, "notifications/") {
- return res, err
- }
+ // Validate format if specified - only specific formats are allowed
+ if propSchema.Format != "" {
+ allowedFormats := map[string]bool{
+ "email": true,
+ "uri": true,
```
-This function is important because it defines how MCP Go SDK Tutorial: Building Robust MCP Clients and Servers in Go implements the patterns covered in this chapter.
+This interface is important because it defines how MCP Go SDK Tutorial: Building Robust MCP Clients and Servers in Go implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[shouldSendListChangedNotification]
- B[listRoots]
- C[createMessage]
- D[urlElicitationMiddleware]
- E[elicit]
+ A[Prompts]
+ B[validation]
+ C[values]
+ D[length]
+ E[values]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-go-sdk-tutorial/06-auth-security-and-runtime-hardening.md b/tutorials/mcp-go-sdk-tutorial/06-auth-security-and-runtime-hardening.md
index 2801551a..8c81d123 100644
--- a/tutorials/mcp-go-sdk-tutorial/06-auth-security-and-runtime-hardening.md
+++ b/tutorials/mcp-go-sdk-tutorial/06-auth-security-and-runtime-hardening.md
@@ -48,170 +48,168 @@ You now have an implementation-level auth and security baseline for Go MCP deplo
Next: [Chapter 7: Testing, Troubleshooting, and Rough Edges](07-testing-troubleshooting-and-rough-edges.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `mcp/client.go`
+### `mcp/transport.go`
-The `Complete` function in [`mcp/client.go`](https://github.com/modelcontextprotocol/go-sdk/blob/HEAD/mcp/client.go) handles a key part of this chapter's functionality:
+The `addBatch` function in [`mcp/transport.go`](https://github.com/modelcontextprotocol/go-sdk/blob/HEAD/mcp/transport.go) handles a key part of this chapter's functionality:
```go
- // Elicitation field is nil), the inferred capability will be used.
- Capabilities *ClientCapabilities
- // ElicitationCompleteHandler handles incoming notifications for notifications/elicitation/complete.
- ElicitationCompleteHandler func(context.Context, *ElicitationCompleteNotificationRequest)
- // Handlers for notifications from the server.
- ToolListChangedHandler func(context.Context, *ToolListChangedRequest)
- PromptListChangedHandler func(context.Context, *PromptListChangedRequest)
- ResourceListChangedHandler func(context.Context, *ResourceListChangedRequest)
- ResourceUpdatedHandler func(context.Context, *ResourceUpdatedNotificationRequest)
- LoggingMessageHandler func(context.Context, *LoggingMessageRequest)
- ProgressNotificationHandler func(context.Context, *ProgressNotificationClientRequest)
- // If non-zero, defines an interval for regular "ping" requests.
- // If the peer fails to respond to pings originating from the keepalive check,
- // the session is automatically closed.
- KeepAlive time.Duration
}
-// bind implements the binder[*ClientSession] interface, so that Clients can
-// be connected using [connect].
-func (c *Client) bind(mcpConn Connection, conn *jsonrpc2.Connection, state *clientSessionState, onClose func()) *ClientSession {
- assert(mcpConn != nil && conn != nil, "nil connection")
- cs := &ClientSession{conn: conn, mcpConn: mcpConn, client: c, onClose: onClose}
- if state != nil {
- cs.state = *state
+// addBatch records a msgBatch for an incoming batch payload.
+// It returns an error if batch is malformed, containing previously seen IDs.
+//
+// See [msgBatch] for more.
+func (t *ioConn) addBatch(batch *msgBatch) error {
+ t.batchMu.Lock()
+ defer t.batchMu.Unlock()
+ for id := range batch.unresolved {
+ if _, ok := t.batches[id]; ok {
+ return fmt.Errorf("%w: batch contains previously seen request %v", jsonrpc2.ErrInvalidRequest, id.Raw())
+ }
}
- c.mu.Lock()
- defer c.mu.Unlock()
- c.sessions = append(c.sessions, cs)
- return cs
-}
-
-// disconnect implements the binder[*Client] interface, so that
+ for id := range batch.unresolved {
+ if t.batches == nil {
+ t.batches = make(map[jsonrpc2.ID]*msgBatch)
+ }
+ t.batches[id] = batch
+ }
+ return nil
+}
+
+// updateBatch records a response in the message batch tracking the
+// corresponding incoming call, if any.
+//
+// The second result reports whether resp was part of a batch. If this is true,
+// the first result is nil if the batch is still incomplete, or the full set of
+// batch responses if resp completed the batch.
+func (t *ioConn) updateBatch(resp *jsonrpc.Response) ([]*jsonrpc.Response, bool) {
+ t.batchMu.Lock()
+ defer t.batchMu.Unlock()
```
This function is important because it defines how MCP Go SDK Tutorial: Building Robust MCP Clients and Servers in Go implements the patterns covered in this chapter.
-### `mcp/client.go`
+### `mcp/transport.go`
-The `Subscribe` function in [`mcp/client.go`](https://github.com/modelcontextprotocol/go-sdk/blob/HEAD/mcp/client.go) handles a key part of this chapter's functionality:
+The `updateBatch` function in [`mcp/transport.go`](https://github.com/modelcontextprotocol/go-sdk/blob/HEAD/mcp/transport.go) handles a key part of this chapter's functionality:
```go
}
-// Subscribe sends a "resources/subscribe" request to the server, asking for
-// notifications when the specified resource changes.
-func (cs *ClientSession) Subscribe(ctx context.Context, params *SubscribeParams) error {
- _, err := handleSend[*emptyResult](ctx, methodSubscribe, newClientRequest(cs, orZero[Params](params)))
- return err
-}
-
-// Unsubscribe sends a "resources/unsubscribe" request to the server, cancelling
-// a previous subscription.
-func (cs *ClientSession) Unsubscribe(ctx context.Context, params *UnsubscribeParams) error {
- _, err := handleSend[*emptyResult](ctx, methodUnsubscribe, newClientRequest(cs, orZero[Params](params)))
- return err
-}
-
-func (c *Client) callToolChangedHandler(ctx context.Context, req *ToolListChangedRequest) (Result, error) {
- if h := c.opts.ToolListChangedHandler; h != nil {
- h(ctx, req)
+// updateBatch records a response in the message batch tracking the
+// corresponding incoming call, if any.
+//
+// The second result reports whether resp was part of a batch. If this is true,
+// the first result is nil if the batch is still incomplete, or the full set of
+// batch responses if resp completed the batch.
+func (t *ioConn) updateBatch(resp *jsonrpc.Response) ([]*jsonrpc.Response, bool) {
+ t.batchMu.Lock()
+ defer t.batchMu.Unlock()
+
+ if batch, ok := t.batches[resp.ID]; ok {
+ idx, ok := batch.unresolved[resp.ID]
+ if !ok {
+ panic("internal error: inconsistent batches")
+ }
+ batch.responses[idx] = resp
+ delete(batch.unresolved, resp.ID)
+ delete(t.batches, resp.ID)
+ if len(batch.unresolved) == 0 {
+ return batch.responses, true
+ }
+ return nil, true
}
- return nil, nil
+ return nil, false
}
-func (c *Client) callPromptChangedHandler(ctx context.Context, req *PromptListChangedRequest) (Result, error) {
- if h := c.opts.PromptListChangedHandler; h != nil {
- h(ctx, req)
- }
- return nil, nil
-}
-
-func (c *Client) callResourceChangedHandler(ctx context.Context, req *ResourceListChangedRequest) (Result, error) {
- if h := c.opts.ResourceListChangedHandler; h != nil {
+// A msgBatch records information about an incoming batch of jsonrpc.2 calls.
+//
+// The jsonrpc.2 spec (https://www.jsonrpc.org/specification#batch) says:
+//
```
This function is important because it defines how MCP Go SDK Tutorial: Building Robust MCP Clients and Servers in Go implements the patterns covered in this chapter.
-### `mcp/client.go`
+### `mcp/transport.go`
-The `Unsubscribe` function in [`mcp/client.go`](https://github.com/modelcontextprotocol/go-sdk/blob/HEAD/mcp/client.go) handles a key part of this chapter's functionality:
+The `Read` function in [`mcp/transport.go`](https://github.com/modelcontextprotocol/go-sdk/blob/HEAD/mcp/transport.go) handles a key part of this chapter's functionality:
```go
-}
-
-// Unsubscribe sends a "resources/unsubscribe" request to the server, cancelling
-// a previous subscription.
-func (cs *ClientSession) Unsubscribe(ctx context.Context, params *UnsubscribeParams) error {
- _, err := handleSend[*emptyResult](ctx, methodUnsubscribe, newClientRequest(cs, orZero[Params](params)))
- return err
-}
-
-func (c *Client) callToolChangedHandler(ctx context.Context, req *ToolListChangedRequest) (Result, error) {
- if h := c.opts.ToolListChangedHandler; h != nil {
- h(ctx, req)
- }
- return nil, nil
-}
-
-func (c *Client) callPromptChangedHandler(ctx context.Context, req *PromptListChangedRequest) (Result, error) {
- if h := c.opts.PromptListChangedHandler; h != nil {
- h(ctx, req)
- }
- return nil, nil
-}
-
-func (c *Client) callResourceChangedHandler(ctx context.Context, req *ResourceListChangedRequest) (Result, error) {
- if h := c.opts.ResourceListChangedHandler; h != nil {
- h(ctx, req)
- }
- return nil, nil
-}
-
-func (c *Client) callResourceUpdatedHandler(ctx context.Context, req *ResourceUpdatedNotificationRequest) (Result, error) {
- if h := c.opts.ResourceUpdatedHandler; h != nil {
+// A Connection is a logical bidirectional JSON-RPC connection.
+type Connection interface {
+ // Read reads the next message to process off the connection.
+ //
+ // Connections must allow Read to be called concurrently with Close. In
+ // particular, calling Close should unblock a Read waiting for input.
+ Read(context.Context) (jsonrpc.Message, error)
+
+ // Write writes a new message to the connection.
+ //
+ // Write may be called concurrently, as calls or responses may occur
+ // concurrently in user code.
+ Write(context.Context, jsonrpc.Message) error
+
+ // Close closes the connection. It is implicitly called whenever a Read or
+ // Write fails.
+ //
+ // Close may be called multiple times, potentially concurrently.
+ Close() error
+
+ // TODO(#148): remove SessionID from this interface.
+ SessionID() string
+}
+
+// A ClientConnection is a [Connection] that is specific to the MCP client.
+//
+// If client connections implement this interface, they may receive information
+// about changes to the client session.
+//
+// TODO: should this interface be exported?
+type clientConnection interface {
+ Connection
```
This function is important because it defines how MCP Go SDK Tutorial: Building Robust MCP Clients and Servers in Go implements the patterns covered in this chapter.
-### `mcp/client.go`
+### `mcp/transport.go`
-The `callToolChangedHandler` function in [`mcp/client.go`](https://github.com/modelcontextprotocol/go-sdk/blob/HEAD/mcp/client.go) handles a key part of this chapter's functionality:
+The `readBatch` function in [`mcp/transport.go`](https://github.com/modelcontextprotocol/go-sdk/blob/HEAD/mcp/transport.go) handles a key part of this chapter's functionality:
```go
- methodElicit: newClientMethodInfo(clientMethod((*Client).elicit), missingParamsOK),
- notificationCancelled: newClientMethodInfo(clientSessionMethod((*ClientSession).cancel), notification|missingParamsOK),
- notificationToolListChanged: newClientMethodInfo(clientMethod((*Client).callToolChangedHandler), notification|missingParamsOK),
- notificationPromptListChanged: newClientMethodInfo(clientMethod((*Client).callPromptChangedHandler), notification|missingParamsOK),
- notificationResourceListChanged: newClientMethodInfo(clientMethod((*Client).callResourceChangedHandler), notification|missingParamsOK),
- notificationResourceUpdated: newClientMethodInfo(clientMethod((*Client).callResourceUpdatedHandler), notification|missingParamsOK),
- notificationLoggingMessage: newClientMethodInfo(clientMethod((*Client).callLoggingHandler), notification),
- notificationProgress: newClientMethodInfo(clientSessionMethod((*ClientSession).callProgressNotificationHandler), notification),
- notificationElicitationComplete: newClientMethodInfo(clientMethod((*Client).callElicitationCompleteHandler), notification|missingParamsOK),
-}
-
-func (cs *ClientSession) sendingMethodInfos() map[string]methodInfo {
- return serverMethodInfos
-}
-
-func (cs *ClientSession) receivingMethodInfos() map[string]methodInfo {
- return clientMethodInfos
-}
-
-func (cs *ClientSession) handle(ctx context.Context, req *jsonrpc.Request) (any, error) {
- if req.IsCall() {
- jsonrpc2.Async(ctx)
}
- return handleReceive(ctx, cs, req)
-}
-func (cs *ClientSession) sendingMethodHandler() MethodHandler {
- cs.client.mu.Lock()
- defer cs.client.mu.Unlock()
- return cs.client.sendingMethodHandler_
-}
+ msgs, batch, err := readBatch(raw)
+ if err != nil {
+ return nil, err
+ }
+ var protocolVersion string
+ t.sessionMu.Lock()
+ protocolVersion = t.protocolVersion
+ t.sessionMu.Unlock()
+ if batch && protocolVersion >= protocolVersion20250618 {
+ return nil, fmt.Errorf("JSON-RPC batching is not supported in %s and later (request version: %s)", protocolVersion20250618, protocolVersion)
+ }
+ t.queue = msgs[1:]
+
+ if batch {
+ var respBatch *msgBatch // track incoming requests in the batch
+ for _, msg := range msgs {
+ if req, ok := msg.(*jsonrpc.Request); ok {
+ if respBatch == nil {
+ respBatch = &msgBatch{
+ unresolved: make(map[jsonrpc2.ID]int),
+ }
+ }
+ if _, ok := respBatch.unresolved[req.ID]; ok {
+ return nil, fmt.Errorf("duplicate message ID %q", req.ID)
+ }
+ respBatch.unresolved[req.ID] = len(respBatch.responses)
+ respBatch.responses = append(respBatch.responses, nil)
+ }
+ }
```
This function is important because it defines how MCP Go SDK Tutorial: Building Robust MCP Clients and Servers in Go implements the patterns covered in this chapter.
@@ -221,11 +219,11 @@ This function is important because it defines how MCP Go SDK Tutorial: Building
```mermaid
flowchart TD
- A[Complete]
- B[Subscribe]
- C[Unsubscribe]
- D[callToolChangedHandler]
- E[callPromptChangedHandler]
+ A[addBatch]
+ B[updateBatch]
+ C[Read]
+ D[readBatch]
+ E[Write]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-go-sdk-tutorial/07-testing-troubleshooting-and-rough-edges.md b/tutorials/mcp-go-sdk-tutorial/07-testing-troubleshooting-and-rough-edges.md
index 7aa17894..49b418ab 100644
--- a/tutorials/mcp-go-sdk-tutorial/07-testing-troubleshooting-and-rough-edges.md
+++ b/tutorials/mcp-go-sdk-tutorial/07-testing-troubleshooting-and-rough-edges.md
@@ -45,170 +45,168 @@ You now have a disciplined debugging approach and awareness of v1 API edges that
Next: [Chapter 8: Conformance, Operations, and Upgrade Strategy](08-conformance-operations-and-upgrade-strategy.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `oauthex/resource_meta.go`
+### `mcp/event.go`
-The `ParseWWWAuthenticate` function in [`oauthex/resource_meta.go`](https://github.com/modelcontextprotocol/go-sdk/blob/HEAD/oauthex/resource_meta.go) handles a key part of this chapter's functionality:
+The `NewMemoryEventStore` function in [`mcp/event.go`](https://github.com/modelcontextprotocol/go-sdk/blob/HEAD/mcp/event.go) handles a key part of this chapter's functionality:
```go
- return nil, nil
- }
- cs, err := ParseWWWAuthenticate(headers)
- if err != nil {
- return nil, err
- }
- metadataURL := resourceMetadataURL(cs)
- if metadataURL == "" {
- return nil, nil
+const defaultMaxBytes = 10 << 20 // 10 MiB
+
+// NewMemoryEventStore creates a [MemoryEventStore] with the default value
+// for MaxBytes.
+func NewMemoryEventStore(opts *MemoryEventStoreOptions) *MemoryEventStore {
+ return &MemoryEventStore{
+ maxBytes: defaultMaxBytes,
+ store: make(map[string]map[string]*dataList),
}
- return GetProtectedResourceMetadata(ctx, metadataURL, serverURL, c)
}
-// resourceMetadataURL returns a resource metadata URL from the given "WWW-Authenticate" header challenges,
-// or the empty string if there is none.
-func resourceMetadataURL(cs []Challenge) string {
- for _, c := range cs {
- if u := c.Params["resource_metadata"]; u != "" {
- return u
- }
- }
- return ""
+// Open implements [EventStore.Open]. It ensures that the underlying data
+// structures for the given session are initialized and ready for use.
+func (s *MemoryEventStore) Open(_ context.Context, sessionID, streamID string) error {
+ s.mu.Lock()
+ defer s.mu.Unlock()
+ s.init(sessionID, streamID)
+ return nil
}
-// GetProtectedResourceMetadataFromID issues a GET request to retrieve protected resource
-// metadata from a resource server.
-// The metadataURL is typically a URL with a host:port and possibly a path.
-// The resourceURL is the resource URI the metadataURL is for.
-// The following checks are performed:
-// - The metadataURL must use HTTPS or be a local address.
-// - The resource field of the resulting metadata must match the resourceURL.
-// - The authorization_servers field of the resulting metadata is checked for dangerous URL schemes.
+// init is an internal helper function that ensures the nested map structure for a
+// given sessionID and streamID exists, creating it if necessary. It returns the
+// dataList associated with the specified IDs.
+// Requires s.mu.
+func (s *MemoryEventStore) init(sessionID, streamID string) *dataList {
+ streamMap, ok := s.store[sessionID]
+ if !ok {
+ streamMap = make(map[string]*dataList)
+ s.store[sessionID] = streamMap
+ }
+ dl, ok := streamMap[streamID]
+ if !ok {
```
This function is important because it defines how MCP Go SDK Tutorial: Building Robust MCP Clients and Servers in Go implements the patterns covered in this chapter.
-### `oauthex/resource_meta.go`
+### `mcp/event.go`
-The `splitChallenges` function in [`oauthex/resource_meta.go`](https://github.com/modelcontextprotocol/go-sdk/blob/HEAD/oauthex/resource_meta.go) handles a key part of this chapter's functionality:
+The `Open` function in [`mcp/event.go`](https://github.com/modelcontextprotocol/go-sdk/blob/HEAD/mcp/event.go) handles a key part of this chapter's functionality:
```go
- var challenges []Challenge
- for _, h := range headers {
- challengeStrings, err := splitChallenges(h)
- if err != nil {
- return nil, err
- }
- for _, cs := range challengeStrings {
- if strings.TrimSpace(cs) == "" {
- continue
- }
- challenge, err := parseSingleChallenge(cs)
- if err != nil {
- return nil, fmt.Errorf("failed to parse challenge %q: %w", cs, err)
- }
- challenges = append(challenges, challenge)
- }
- }
- return challenges, nil
+// All of an EventStore's methods must be safe for use by multiple goroutines.
+type EventStore interface {
+ // Open is called when a new stream is created. It may be used to ensure that
+ // the underlying data structure for the stream is initialized, making it
+ // ready to store and replay event streams.
+ Open(_ context.Context, sessionID, streamID string) error
+
+ // Append appends data for an outgoing event to given stream, which is part of the
+ // given session.
+ Append(_ context.Context, sessionID, streamID string, data []byte) error
+
+ // After returns an iterator over the data for the given session and stream, beginning
+ // just after the given index.
+ //
+ // Once the iterator yields a non-nil error, it will stop.
+ // After's iterator must return an error immediately if any data after index was
+ // dropped; it must not return partial results.
+ // The stream must have been opened previously (see [EventStore.Open]).
+ After(_ context.Context, sessionID, streamID string, index int) iter.Seq2[[]byte, error]
+
+ // SessionClosed informs the store that the given session is finished, along
+ // with all of its streams.
+ //
+ // A store cannot rely on this method being called for cleanup. It should institute
+ // additional mechanisms, such as timeouts, to reclaim storage.
+ SessionClosed(_ context.Context, sessionID string) error
+
+ // There is no StreamClosed method. A server doesn't know when a stream is finished, because
+ // the client can always send a GET with a Last-Event-ID referring to the stream.
}
-// splitChallenges splits a header value containing one or more challenges.
-// It correctly handles commas within quoted strings and distinguishes between
-// commas separating auth-params and commas separating challenges.
-func splitChallenges(header string) ([]string, error) {
- var challenges []string
- inQuotes := false
- start := 0
- for i, r := range header {
- if r == '"' {
- if i > 0 && header[i-1] != '\\' {
- inQuotes = !inQuotes
- } else if i == 0 {
+// A dataList is a list of []byte.
```
This function is important because it defines how MCP Go SDK Tutorial: Building Robust MCP Clients and Servers in Go implements the patterns covered in this chapter.
-### `oauthex/resource_meta.go`
+### `mcp/event.go`
-The `parseSingleChallenge` function in [`oauthex/resource_meta.go`](https://github.com/modelcontextprotocol/go-sdk/blob/HEAD/oauthex/resource_meta.go) handles a key part of this chapter's functionality:
+The `init` function in [`mcp/event.go`](https://github.com/modelcontextprotocol/go-sdk/blob/HEAD/mcp/event.go) handles a key part of this chapter's functionality:
```go
- continue
- }
- challenge, err := parseSingleChallenge(cs)
- if err != nil {
- return nil, fmt.Errorf("failed to parse challenge %q: %w", cs, err)
- }
- challenges = append(challenges, challenge)
- }
- }
- return challenges, nil
+type EventStore interface {
+ // Open is called when a new stream is created. It may be used to ensure that
+ // the underlying data structure for the stream is initialized, making it
+ // ready to store and replay event streams.
+ Open(_ context.Context, sessionID, streamID string) error
+
+ // Append appends data for an outgoing event to given stream, which is part of the
+ // given session.
+ Append(_ context.Context, sessionID, streamID string, data []byte) error
+
+ // After returns an iterator over the data for the given session and stream, beginning
+ // just after the given index.
+ //
+ // Once the iterator yields a non-nil error, it will stop.
+ // After's iterator must return an error immediately if any data after index was
+ // dropped; it must not return partial results.
+ // The stream must have been opened previously (see [EventStore.Open]).
+ After(_ context.Context, sessionID, streamID string, index int) iter.Seq2[[]byte, error]
+
+ // SessionClosed informs the store that the given session is finished, along
+ // with all of its streams.
+ //
+ // A store cannot rely on this method being called for cleanup. It should institute
+ // additional mechanisms, such as timeouts, to reclaim storage.
+ SessionClosed(_ context.Context, sessionID string) error
+
+ // There is no StreamClosed method. A server doesn't know when a stream is finished, because
+ // the client can always send a GET with a Last-Event-ID referring to the stream.
}
-// splitChallenges splits a header value containing one or more challenges.
-// It correctly handles commas within quoted strings and distinguishes between
-// commas separating auth-params and commas separating challenges.
-func splitChallenges(header string) ([]string, error) {
- var challenges []string
- inQuotes := false
- start := 0
- for i, r := range header {
- if r == '"' {
- if i > 0 && header[i-1] != '\\' {
- inQuotes = !inQuotes
- } else if i == 0 {
- // A challenge begins with an auth-scheme, which is a token, which cannot contain
- // a quote.
- return nil, errors.New(`challenge begins with '"'`)
- }
- } else if r == ',' && !inQuotes {
- // This is a potential challenge separator.
- // A new challenge does not start with `key=value`.
- // We check if the part after the comma looks like a parameter.
+// A dataList is a list of []byte.
+// The zero dataList is ready to use.
```
This function is important because it defines how MCP Go SDK Tutorial: Building Robust MCP Clients and Servers in Go implements the patterns covered in this chapter.
-### `oauthex/auth_meta.go`
+### `mcp/event.go`
-The `GetAuthServerMeta` function in [`oauthex/auth_meta.go`](https://github.com/modelcontextprotocol/go-sdk/blob/HEAD/oauthex/auth_meta.go) handles a key part of this chapter's functionality:
+The `Append` function in [`mcp/event.go`](https://github.com/modelcontextprotocol/go-sdk/blob/HEAD/mcp/event.go) handles a key part of this chapter's functionality:
```go
+ Open(_ context.Context, sessionID, streamID string) error
+
+ // Append appends data for an outgoing event to given stream, which is part of the
+ // given session.
+ Append(_ context.Context, sessionID, streamID string, data []byte) error
+
+ // After returns an iterator over the data for the given session and stream, beginning
+ // just after the given index.
+ //
+ // Once the iterator yields a non-nil error, it will stop.
+ // After's iterator must return an error immediately if any data after index was
+ // dropped; it must not return partial results.
+ // The stream must have been opened previously (see [EventStore.Open]).
+ After(_ context.Context, sessionID, streamID string, index int) iter.Seq2[[]byte, error]
+
+ // SessionClosed informs the store that the given session is finished, along
+ // with all of its streams.
+ //
+ // A store cannot rely on this method being called for cleanup. It should institute
+ // additional mechanisms, such as timeouts, to reclaim storage.
+ SessionClosed(_ context.Context, sessionID string) error
+
+ // There is no StreamClosed method. A server doesn't know when a stream is finished, because
+ // the client can always send a GET with a Last-Event-ID referring to the stream.
}
-// GetAuthServerMeta issues a GET request to retrieve authorization server metadata
-// from an OAuth authorization server with the given metadataURL.
-//
-// It follows [RFC 8414]:
-// - The metadataURL must use HTTPS or be a local address.
-// - The Issuer field is checked against metadataURL.Issuer.
-//
-// It also verifies that the authorization server supports PKCE and that the URLs
-// in the metadata don't use dangerous schemes.
-//
-// It returns an error if the request fails with a non-4xx status code or the fetched
-// metadata doesn't pass security validations.
-// It returns nil if the request fails with a 4xx status code.
-//
-// [RFC 8414]: https://tools.ietf.org/html/rfc8414
-func GetAuthServerMeta(ctx context.Context, metadataURL, issuer string, c *http.Client) (*AuthServerMeta, error) {
- // Only allow HTTP for local addresses (testing or development purposes).
- if err := checkHTTPSOrLoopback(metadataURL); err != nil {
- return nil, fmt.Errorf("metadataURL: %v", err)
- }
- asm, err := getJSON[AuthServerMeta](ctx, c, metadataURL, 1<<20)
- if err != nil {
- var httpErr *httpStatusError
- if errors.As(err, &httpErr) {
- if 400 <= httpErr.StatusCode && httpErr.StatusCode < 500 {
- return nil, nil
- }
- }
- return nil, fmt.Errorf("%v", err) // Do not expose error types.
- }
+// A dataList is a list of []byte.
+// The zero dataList is ready to use.
+type dataList struct {
+ size int // total size of data bytes
+ first int // the stream index of the first element in data
+ data [][]byte
```
This function is important because it defines how MCP Go SDK Tutorial: Building Robust MCP Clients and Servers in Go implements the patterns covered in this chapter.
@@ -218,11 +216,11 @@ This function is important because it defines how MCP Go SDK Tutorial: Building
```mermaid
flowchart TD
- A[ParseWWWAuthenticate]
- B[splitChallenges]
- C[parseSingleChallenge]
- D[GetAuthServerMeta]
- E[validateAuthServerMetaURLs]
+ A[NewMemoryEventStore]
+ B[Open]
+ C[init]
+ D[Append]
+ E[After]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-go-sdk-tutorial/08-conformance-operations-and-upgrade-strategy.md b/tutorials/mcp-go-sdk-tutorial/08-conformance-operations-and-upgrade-strategy.md
index e6ac97d5..3be662a3 100644
--- a/tutorials/mcp-go-sdk-tutorial/08-conformance-operations-and-upgrade-strategy.md
+++ b/tutorials/mcp-go-sdk-tutorial/08-conformance-operations-and-upgrade-strategy.md
@@ -48,149 +48,168 @@ You now have an operations-ready model for validating and evolving Go SDK MCP de
Next: Continue with [MCP TypeScript SDK Tutorial](../mcp-typescript-sdk-tutorial/)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `mcp/resource.go`
+### `mcp/logging.go`
-The `fileRoot` function in [`mcp/resource.go`](https://github.com/modelcontextprotocol/go-sdk/blob/HEAD/mcp/resource.go) handles a key part of this chapter's functionality:
+The `init` function in [`mcp/logging.go`](https://github.com/modelcontextprotocol/go-sdk/blob/HEAD/mcp/logging.go) handles a key part of this chapter's functionality:
```go
-}
+var mcpToSlog = make(map[LoggingLevel]slog.Level)
-// fileRoots transforms the Roots obtained from the client into absolute paths on
-// the local filesystem.
-// TODO(jba): expose this functionality to user ResourceHandlers,
-// so they don't have to repeat it.
-func fileRoots(rawRoots []*Root) ([]string, error) {
- var fileRoots []string
- for _, r := range rawRoots {
- fr, err := fileRoot(r)
- if err != nil {
- return nil, err
- }
- fileRoots = append(fileRoots, fr)
+func init() {
+ for sl, ml := range slogToMCP {
+ mcpToSlog[ml] = sl
}
- return fileRoots, nil
}
-// fileRoot returns the absolute path for Root.
-func fileRoot(root *Root) (_ string, err error) {
- defer util.Wrapf(&err, "root %q", root.URI)
-
- // Convert to absolute file path.
- rurl, err := url.Parse(root.URI)
- if err != nil {
- return "", err
+func slogLevelToMCP(sl slog.Level) LoggingLevel {
+ if ml, ok := slogToMCP[sl]; ok {
+ return ml
}
- if rurl.Scheme != "file" {
- return "", errors.New("not a file URI")
+ return "debug" // for lack of a better idea
+}
+
+func mcpLevelToSlog(ll LoggingLevel) slog.Level {
+ if sl, ok := mcpToSlog[ll]; ok {
+ return sl
}
- if rurl.Path == "" {
- // A more specific error than the one below, to catch the
+ // TODO: is there a better default?
+ return LevelDebug
+}
+
+// compareLevels behaves like [cmp.Compare] for [LoggingLevel]s.
+func compareLevels(l1, l2 LoggingLevel) int {
+ return cmp.Compare(mcpLevelToSlog(l1), mcpLevelToSlog(l2))
+}
+
+// LoggingHandlerOptions are options for a LoggingHandler.
+type LoggingHandlerOptions struct {
+ // The value for the "logger" field of logging notifications.
+ LoggerName string
```
This function is important because it defines how MCP Go SDK Tutorial: Building Robust MCP Clients and Servers in Go implements the patterns covered in this chapter.
-### `mcp/resource.go`
+### `mcp/logging.go`
-The `Matches` function in [`mcp/resource.go`](https://github.com/modelcontextprotocol/go-sdk/blob/HEAD/mcp/resource.go) handles a key part of this chapter's functionality:
+The `slogLevelToMCP` function in [`mcp/logging.go`](https://github.com/modelcontextprotocol/go-sdk/blob/HEAD/mcp/logging.go) handles a key part of this chapter's functionality:
```go
}
-// Matches reports whether the receiver's uri template matches the uri.
-func (sr *serverResourceTemplate) Matches(uri string) bool {
- tmpl, err := uritemplate.New(sr.resourceTemplate.URITemplate)
- if err != nil {
- return false
+func slogLevelToMCP(sl slog.Level) LoggingLevel {
+ if ml, ok := slogToMCP[sl]; ok {
+ return ml
}
- return tmpl.Regexp().MatchString(uri)
+ return "debug" // for lack of a better idea
+}
+
+func mcpLevelToSlog(ll LoggingLevel) slog.Level {
+ if sl, ok := mcpToSlog[ll]; ok {
+ return sl
+ }
+ // TODO: is there a better default?
+ return LevelDebug
+}
+
+// compareLevels behaves like [cmp.Compare] for [LoggingLevel]s.
+func compareLevels(l1, l2 LoggingLevel) int {
+ return cmp.Compare(mcpLevelToSlog(l1), mcpLevelToSlog(l2))
+}
+
+// LoggingHandlerOptions are options for a LoggingHandler.
+type LoggingHandlerOptions struct {
+ // The value for the "logger" field of logging notifications.
+ LoggerName string
+ // Limits the rate at which log messages are sent.
+ // Excess messages are dropped.
+ // If zero, there is no rate limiting.
+ MinInterval time.Duration
}
```
This function is important because it defines how MCP Go SDK Tutorial: Building Robust MCP Clients and Servers in Go implements the patterns covered in this chapter.
-### `auth/auth.go`
+### `mcp/logging.go`
-The `TokenInfoFromContext` function in [`auth/auth.go`](https://github.com/modelcontextprotocol/go-sdk/blob/HEAD/auth/auth.go) handles a key part of this chapter's functionality:
+The `mcpLevelToSlog` function in [`mcp/logging.go`](https://github.com/modelcontextprotocol/go-sdk/blob/HEAD/mcp/logging.go) handles a key part of this chapter's functionality:
```go
-type tokenInfoKey struct{}
+}
-// TokenInfoFromContext returns the [TokenInfo] stored in ctx, or nil if none.
-func TokenInfoFromContext(ctx context.Context) *TokenInfo {
- ti := ctx.Value(tokenInfoKey{})
- if ti == nil {
- return nil
+func mcpLevelToSlog(ll LoggingLevel) slog.Level {
+ if sl, ok := mcpToSlog[ll]; ok {
+ return sl
}
- return ti.(*TokenInfo)
-}
-
-// RequireBearerToken returns a piece of middleware that verifies a bearer token using the verifier.
-// If verification succeeds, the [TokenInfo] is added to the request's context and the request proceeds.
-// If verification fails, the request fails with a 401 Unauthenticated, and the WWW-Authenticate header
-// is populated to enable [protected resource metadata].
-//
-// [protected resource metadata]: https://datatracker.ietf.org/doc/rfc9728
-func RequireBearerToken(verifier TokenVerifier, opts *RequireBearerTokenOptions) func(http.Handler) http.Handler {
- // Based on typescript-sdk/src/server/auth/middleware/bearerAuth.ts.
-
- return func(handler http.Handler) http.Handler {
- return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
- tokenInfo, errmsg, code := verify(r, verifier, opts)
- if code != 0 {
- if code == http.StatusUnauthorized || code == http.StatusForbidden {
- if opts != nil {
- var params []string
- if opts.ResourceMetadataURL != "" {
- params = append(params, fmt.Sprintf("resource_metadata=%q", opts.ResourceMetadataURL))
- }
- if len(opts.Scopes) > 0 {
- params = append(params, fmt.Sprintf("scope=%q", strings.Join(opts.Scopes, " ")))
+ // TODO: is there a better default?
+ return LevelDebug
+}
+
+// compareLevels behaves like [cmp.Compare] for [LoggingLevel]s.
+func compareLevels(l1, l2 LoggingLevel) int {
+ return cmp.Compare(mcpLevelToSlog(l1), mcpLevelToSlog(l2))
+}
+
+// LoggingHandlerOptions are options for a LoggingHandler.
+type LoggingHandlerOptions struct {
+ // The value for the "logger" field of logging notifications.
+ LoggerName string
+ // Limits the rate at which log messages are sent.
+ // Excess messages are dropped.
+ // If zero, there is no rate limiting.
+ MinInterval time.Duration
+}
+
+// A LoggingHandler is a [slog.Handler] for MCP.
+type LoggingHandler struct {
+ opts LoggingHandlerOptions
+ ss *ServerSession
+ // Ensures that the buffer reset is atomic with the write (see Handle).
+ // A pointer so that clones share the mutex. See
+ // https://github.com/golang/example/blob/master/slog-handler-guide/README.md#getting-the-mutex-right.
```
This function is important because it defines how MCP Go SDK Tutorial: Building Robust MCP Clients and Servers in Go implements the patterns covered in this chapter.
-### `auth/auth.go`
+### `mcp/logging.go`
-The `RequireBearerToken` function in [`auth/auth.go`](https://github.com/modelcontextprotocol/go-sdk/blob/HEAD/auth/auth.go) handles a key part of this chapter's functionality:
+The `compareLevels` function in [`mcp/logging.go`](https://github.com/modelcontextprotocol/go-sdk/blob/HEAD/mcp/logging.go) handles a key part of this chapter's functionality:
```go
-type TokenVerifier func(ctx context.Context, token string, req *http.Request) (*TokenInfo, error)
-
-// RequireBearerTokenOptions are options for [RequireBearerToken].
-type RequireBearerTokenOptions struct {
- // The URL for the resource server metadata OAuth flow, to be returned as part
- // of the WWW-Authenticate header.
- ResourceMetadataURL string
- // The required scopes.
- Scopes []string
}
-type tokenInfoKey struct{}
+// compareLevels behaves like [cmp.Compare] for [LoggingLevel]s.
+func compareLevels(l1, l2 LoggingLevel) int {
+ return cmp.Compare(mcpLevelToSlog(l1), mcpLevelToSlog(l2))
+}
-// TokenInfoFromContext returns the [TokenInfo] stored in ctx, or nil if none.
-func TokenInfoFromContext(ctx context.Context) *TokenInfo {
- ti := ctx.Value(tokenInfoKey{})
- if ti == nil {
- return nil
- }
- return ti.(*TokenInfo)
+// LoggingHandlerOptions are options for a LoggingHandler.
+type LoggingHandlerOptions struct {
+ // The value for the "logger" field of logging notifications.
+ LoggerName string
+ // Limits the rate at which log messages are sent.
+ // Excess messages are dropped.
+ // If zero, there is no rate limiting.
+ MinInterval time.Duration
}
-// RequireBearerToken returns a piece of middleware that verifies a bearer token using the verifier.
-// If verification succeeds, the [TokenInfo] is added to the request's context and the request proceeds.
-// If verification fails, the request fails with a 401 Unauthenticated, and the WWW-Authenticate header
-// is populated to enable [protected resource metadata].
-//
-// [protected resource metadata]: https://datatracker.ietf.org/doc/rfc9728
-func RequireBearerToken(verifier TokenVerifier, opts *RequireBearerTokenOptions) func(http.Handler) http.Handler {
- // Based on typescript-sdk/src/server/auth/middleware/bearerAuth.ts.
+// A LoggingHandler is a [slog.Handler] for MCP.
+type LoggingHandler struct {
+ opts LoggingHandlerOptions
+ ss *ServerSession
+ // Ensures that the buffer reset is atomic with the write (see Handle).
+ // A pointer so that clones share the mutex. See
+ // https://github.com/golang/example/blob/master/slog-handler-guide/README.md#getting-the-mutex-right.
+ mu *sync.Mutex
+ lastMessageSent time.Time // for rate-limiting
+ buf *bytes.Buffer
+ handler slog.Handler
+}
- return func(handler http.Handler) http.Handler {
+// ensureLogger returns l if non-nil, otherwise a discard logger.
+func ensureLogger(l *slog.Logger) *slog.Logger {
```
This function is important because it defines how MCP Go SDK Tutorial: Building Robust MCP Clients and Servers in Go implements the patterns covered in this chapter.
@@ -200,11 +219,11 @@ This function is important because it defines how MCP Go SDK Tutorial: Building
```mermaid
flowchart TD
- A[fileRoot]
- B[Matches]
- C[TokenInfoFromContext]
- D[RequireBearerToken]
- E[verify]
+ A[init]
+ B[slogLevelToMCP]
+ C[mcpLevelToSlog]
+ D[compareLevels]
+ E[ensureLogger]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-inspector-tutorial/01-getting-started.md b/tutorials/mcp-inspector-tutorial/01-getting-started.md
index 9c253a95..9e5ace4a 100644
--- a/tutorials/mcp-inspector-tutorial/01-getting-started.md
+++ b/tutorials/mcp-inspector-tutorial/01-getting-started.md
@@ -52,8 +52,6 @@ You now have a working Inspector baseline with validated server connectivity.
Next: [Chapter 2: Architecture, Transports, and Session Model](02-architecture-transports-and-session-model.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `cli/src/index.ts`
diff --git a/tutorials/mcp-inspector-tutorial/02-architecture-transports-and-session-model.md b/tutorials/mcp-inspector-tutorial/02-architecture-transports-and-session-model.md
index 785cf71a..09272452 100644
--- a/tutorials/mcp-inspector-tutorial/02-architecture-transports-and-session-model.md
+++ b/tutorials/mcp-inspector-tutorial/02-architecture-transports-and-session-model.md
@@ -54,8 +54,6 @@ You now have a transport-first mental model for debugging with Inspector.
Next: [Chapter 3: UI Debugging Workflows: Tools, Resources, Prompts](03-ui-debugging-workflows-tools-resources-prompts.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `cli/src/index.ts`
diff --git a/tutorials/mcp-inspector-tutorial/03-ui-debugging-workflows-tools-resources-prompts.md b/tutorials/mcp-inspector-tutorial/03-ui-debugging-workflows-tools-resources-prompts.md
index b76c1a46..dbfa4e52 100644
--- a/tutorials/mcp-inspector-tutorial/03-ui-debugging-workflows-tools-resources-prompts.md
+++ b/tutorials/mcp-inspector-tutorial/03-ui-debugging-workflows-tools-resources-prompts.md
@@ -44,56 +44,99 @@ You now have a practical, repeatable UI workflow for MCP server debugging.
Next: [Chapter 4: CLI Mode, Automation, and CI Loops](04-cli-mode-automation-and-ci-loops.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `client/bin/start.js`
+### `cli/src/transport.ts`
-The `delay` function in [`client/bin/start.js`](https://github.com/modelcontextprotocol/inspector/blob/HEAD/client/bin/start.js) handles a key part of this chapter's functionality:
+The `createStdioTransport` function in [`cli/src/transport.ts`](https://github.com/modelcontextprotocol/inspector/blob/HEAD/cli/src/transport.ts) handles a key part of this chapter's functionality:
-```js
-const DEFAULT_MCP_PROXY_LISTEN_PORT = "6277";
+```ts
+};
-function delay(ms) {
- return new Promise((resolve) => setTimeout(resolve, ms, true));
-}
+function createStdioTransport(options: TransportOptions): Transport {
+ let args: string[] = [];
-function getClientUrl(port, authDisabled, sessionToken, serverPort) {
- const host = process.env.HOST || "localhost";
- const baseUrl = `http://${host}:${port}`;
-
- const params = new URLSearchParams();
- if (serverPort && serverPort !== DEFAULT_MCP_PROXY_LISTEN_PORT) {
- params.set("MCP_PROXY_PORT", serverPort);
+ if (options.args !== undefined) {
+ args = options.args;
}
- if (!authDisabled) {
- params.set("MCP_PROXY_AUTH_TOKEN", sessionToken);
+
+ const processEnv: Record<string, string> = {};
+
+ for (const [key, value] of Object.entries(process.env)) {
+ if (value !== undefined) {
+ processEnv[key] = value;
+ }
}
- return params.size > 0 ? `${baseUrl}/?${params.toString()}` : baseUrl;
+
+ const defaultEnv = getDefaultEnvironment();
+
+ const env: Record<string, string> = {
+ ...defaultEnv,
+ ...processEnv,
+ };
+
+ const { cmd: actualCommand, args: actualArgs } = findActualExecutable(
+ options.command ?? "",
+ args,
+ );
+
+ return new StdioClientTransport({
+ command: actualCommand,
+ args: actualArgs,
+```
+
+This function is important because it defines how MCP Inspector Tutorial: Debugging and Validating MCP Servers implements the patterns covered in this chapter.
+
+### `cli/src/transport.ts`
+
+The `createTransport` function in [`cli/src/transport.ts`](https://github.com/modelcontextprotocol/inspector/blob/HEAD/cli/src/transport.ts) handles a key part of this chapter's functionality:
+
+```ts
}
-async function startDevServer(serverOptions) {
- const {
- SERVER_PORT,
- CLIENT_PORT,
- sessionToken,
- envVars,
- abort,
- transport,
- serverUrl,
- } = serverOptions;
- const serverCommand = "npx";
- const serverArgs = ["tsx", "watch", "--clear-screen=false", "src/index.ts"];
+export function createTransport(options: TransportOptions): Transport {
+ const { transportType } = options;
+
+ try {
+ if (transportType === "stdio") {
+ return createStdioTransport(options);
+ }
+
+ // If not STDIO, then it must be either SSE or HTTP.
+ if (!options.url) {
+ throw new Error("URL must be provided for SSE or HTTP transport types.");
+ }
+ const url = new URL(options.url);
+
+ if (transportType === "sse") {
+ const transportOptions = options.headers
+ ? {
+ requestInit: {
+ headers: options.headers,
+ },
+ }
+ : undefined;
+ return new SSEClientTransport(url, transportOptions);
+ }
+
+ if (transportType === "http") {
+ const transportOptions = options.headers
+ ? {
+ requestInit: {
+ headers: options.headers,
```
This function is important because it defines how MCP Inspector Tutorial: Debugging and Validating MCP Servers implements the patterns covered in this chapter.
### `client/bin/start.js`
-The `getClientUrl` function in [`client/bin/start.js`](https://github.com/modelcontextprotocol/inspector/blob/HEAD/client/bin/start.js) handles a key part of this chapter's functionality:
+The `delay` function in [`client/bin/start.js`](https://github.com/modelcontextprotocol/inspector/blob/HEAD/client/bin/start.js) handles a key part of this chapter's functionality:
```js
+const DEFAULT_MCP_PROXY_LISTEN_PORT = "6277";
+
+function delay(ms) {
+ return new Promise((resolve) => setTimeout(resolve, ms, true));
}
function getClientUrl(port, authDisabled, sessionToken, serverPort) {
@@ -122,51 +165,6 @@ async function startDevServer(serverOptions) {
} = serverOptions;
const serverCommand = "npx";
const serverArgs = ["tsx", "watch", "--clear-screen=false", "src/index.ts"];
- const isWindows = process.platform === "win32";
-
- const spawnOptions = {
- cwd: resolve(__dirname, "../..", "server"),
-```
-
-This function is important because it defines how MCP Inspector Tutorial: Debugging and Validating MCP Servers implements the patterns covered in this chapter.
-
-### `client/bin/start.js`
-
-The `startDevServer` function in [`client/bin/start.js`](https://github.com/modelcontextprotocol/inspector/blob/HEAD/client/bin/start.js) handles a key part of this chapter's functionality:
-
-```js
-}
-
-async function startDevServer(serverOptions) {
- const {
- SERVER_PORT,
- CLIENT_PORT,
- sessionToken,
- envVars,
- abort,
- transport,
- serverUrl,
- } = serverOptions;
- const serverCommand = "npx";
- const serverArgs = ["tsx", "watch", "--clear-screen=false", "src/index.ts"];
- const isWindows = process.platform === "win32";
-
- const spawnOptions = {
- cwd: resolve(__dirname, "../..", "server"),
- env: {
- ...process.env,
- SERVER_PORT,
- CLIENT_PORT,
- MCP_PROXY_AUTH_TOKEN: sessionToken,
- MCP_ENV_VARS: JSON.stringify(envVars),
- ...(transport ? { MCP_TRANSPORT: transport } : {}),
- ...(serverUrl ? { MCP_SERVER_URL: serverUrl } : {}),
- },
- signal: abort.signal,
- echoOutput: true,
- };
-
- // For Windows, we need to ignore stdin to simulate < NUL
```
This function is important because it defines how MCP Inspector Tutorial: Debugging and Validating MCP Servers implements the patterns covered in this chapter.
@@ -176,9 +174,9 @@ This function is important because it defines how MCP Inspector Tutorial: Debugg
```mermaid
flowchart TD
- A[delay]
- B[getClientUrl]
- C[startDevServer]
+ A[createStdioTransport]
+ B[createTransport]
+ C[delay]
A --> B
B --> C
```
diff --git a/tutorials/mcp-inspector-tutorial/04-cli-mode-automation-and-ci-loops.md b/tutorials/mcp-inspector-tutorial/04-cli-mode-automation-and-ci-loops.md
index cf1abf6d..64ac3e16 100644
--- a/tutorials/mcp-inspector-tutorial/04-cli-mode-automation-and-ci-loops.md
+++ b/tutorials/mcp-inspector-tutorial/04-cli-mode-automation-and-ci-loops.md
@@ -53,129 +53,127 @@ You can now automate Inspector-based checks in build and release pipelines.
Next: [Chapter 5: Security, Auth, and Network Hardening](05-security-auth-and-network-hardening.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `client/bin/start.js`
-The `startProdServer` function in [`client/bin/start.js`](https://github.com/modelcontextprotocol/inspector/blob/HEAD/client/bin/start.js) handles a key part of this chapter's functionality:
+The `getClientUrl` function in [`client/bin/start.js`](https://github.com/modelcontextprotocol/inspector/blob/HEAD/client/bin/start.js) handles a key part of this chapter's functionality:
```js
}
-async function startProdServer(serverOptions) {
+function getClientUrl(port, authDisabled, sessionToken, serverPort) {
+ const host = process.env.HOST || "localhost";
+ const baseUrl = `http://${host}:${port}`;
+
+ const params = new URLSearchParams();
+ if (serverPort && serverPort !== DEFAULT_MCP_PROXY_LISTEN_PORT) {
+ params.set("MCP_PROXY_PORT", serverPort);
+ }
+ if (!authDisabled) {
+ params.set("MCP_PROXY_AUTH_TOKEN", sessionToken);
+ }
+ return params.size > 0 ? `${baseUrl}/?${params.toString()}` : baseUrl;
+}
+
+async function startDevServer(serverOptions) {
const {
SERVER_PORT,
CLIENT_PORT,
sessionToken,
envVars,
abort,
- command,
- mcpServerArgs,
transport,
serverUrl,
} = serverOptions;
- const inspectorServerPath = resolve(
- __dirname,
- "../..",
- "server",
- "build",
- "index.js",
- );
+ const serverCommand = "npx";
+ const serverArgs = ["tsx", "watch", "--clear-screen=false", "src/index.ts"];
+ const isWindows = process.platform === "win32";
- const server = spawnPromise(
- "node",
- [
- inspectorServerPath,
- ...(command ? [`--command=${command}`] : []),
- ...(mcpServerArgs && mcpServerArgs.length > 0
- ? [`--args=${mcpServerArgs.join(" ")}`]
- : []),
- ...(transport ? [`--transport=${transport}`] : []),
- ...(serverUrl ? [`--server-url=${serverUrl}`] : []),
+ const spawnOptions = {
+ cwd: resolve(__dirname, "../..", "server"),
```
This function is important because it defines how MCP Inspector Tutorial: Debugging and Validating MCP Servers implements the patterns covered in this chapter.
### `client/bin/start.js`
-The `startDevClient` function in [`client/bin/start.js`](https://github.com/modelcontextprotocol/inspector/blob/HEAD/client/bin/start.js) handles a key part of this chapter's functionality:
+The `startDevServer` function in [`client/bin/start.js`](https://github.com/modelcontextprotocol/inspector/blob/HEAD/client/bin/start.js) handles a key part of this chapter's functionality:
```js
}
-async function startDevClient(clientOptions) {
+async function startDevServer(serverOptions) {
const {
- CLIENT_PORT,
SERVER_PORT,
- authDisabled,
+ CLIENT_PORT,
sessionToken,
+ envVars,
abort,
- cancelled,
- } = clientOptions;
- const clientCommand = "npx";
- const host = process.env.HOST || "localhost";
- const clientArgs = ["vite", "--port", CLIENT_PORT, "--host", host];
+ transport,
+ serverUrl,
+ } = serverOptions;
+ const serverCommand = "npx";
+ const serverArgs = ["tsx", "watch", "--clear-screen=false", "src/index.ts"];
const isWindows = process.platform === "win32";
const spawnOptions = {
- cwd: resolve(__dirname, ".."),
- env: { ...process.env, CLIENT_PORT },
+ cwd: resolve(__dirname, "../..", "server"),
+ env: {
+ ...process.env,
+ SERVER_PORT,
+ CLIENT_PORT,
+ MCP_PROXY_AUTH_TOKEN: sessionToken,
+ MCP_ENV_VARS: JSON.stringify(envVars),
+ ...(transport ? { MCP_TRANSPORT: transport } : {}),
+ ...(serverUrl ? { MCP_SERVER_URL: serverUrl } : {}),
+ },
signal: abort.signal,
echoOutput: true,
};
- // For Windows, we need to ignore stdin to prevent hanging
- if (isWindows) {
- spawnOptions.stdio = ["ignore", "pipe", "pipe"];
- }
-
- const client = spawn(clientCommand, clientArgs, spawnOptions);
-
- const url = getClientUrl(
- CLIENT_PORT,
+ // For Windows, we need to ignore stdin to simulate < NUL
```
This function is important because it defines how MCP Inspector Tutorial: Debugging and Validating MCP Servers implements the patterns covered in this chapter.
### `client/bin/start.js`
-The `startProdClient` function in [`client/bin/start.js`](https://github.com/modelcontextprotocol/inspector/blob/HEAD/client/bin/start.js) handles a key part of this chapter's functionality:
+The `startProdServer` function in [`client/bin/start.js`](https://github.com/modelcontextprotocol/inspector/blob/HEAD/client/bin/start.js) handles a key part of this chapter's functionality:
```js
}
-async function startProdClient(clientOptions) {
+async function startProdServer(serverOptions) {
const {
- CLIENT_PORT,
SERVER_PORT,
- authDisabled,
+ CLIENT_PORT,
sessionToken,
+ envVars,
abort,
- cancelled,
- } = clientOptions;
- const inspectorClientPath = resolve(
+ command,
+ mcpServerArgs,
+ transport,
+ serverUrl,
+ } = serverOptions;
+ const inspectorServerPath = resolve(
__dirname,
"../..",
- "client",
- "bin",
- "client.js",
- );
-
- const url = getClientUrl(
- CLIENT_PORT,
- authDisabled,
- sessionToken,
- SERVER_PORT,
+ "server",
+ "build",
+ "index.js",
);
- await spawnPromise("node", [inspectorClientPath], {
- env: {
- ...process.env,
- CLIENT_PORT,
- INSPECTOR_URL: url,
- },
+ const server = spawnPromise(
+ "node",
+ [
+ inspectorServerPath,
+ ...(command ? [`--command=${command}`] : []),
+ ...(mcpServerArgs && mcpServerArgs.length > 0
+ ? [`--args=${mcpServerArgs.join(" ")}`]
+ : []),
+ ...(transport ? [`--transport=${transport}`] : []),
+ ...(serverUrl ? [`--server-url=${serverUrl}`] : []),
```
This function is important because it defines how MCP Inspector Tutorial: Debugging and Validating MCP Servers implements the patterns covered in this chapter.
@@ -185,9 +183,9 @@ This function is important because it defines how MCP Inspector Tutorial: Debugg
```mermaid
flowchart TD
- A[startProdServer]
- B[startDevClient]
- C[startProdClient]
+ A[getClientUrl]
+ B[startDevServer]
+ C[startProdServer]
A --> B
B --> C
```
diff --git a/tutorials/mcp-inspector-tutorial/05-security-auth-and-network-hardening.md b/tutorials/mcp-inspector-tutorial/05-security-auth-and-network-hardening.md
index 34bc85b5..f74fb200 100644
--- a/tutorials/mcp-inspector-tutorial/05-security-auth-and-network-hardening.md
+++ b/tutorials/mcp-inspector-tutorial/05-security-auth-and-network-hardening.md
@@ -45,12 +45,92 @@ You now have a concrete baseline for safer Inspector operation.
Next: [Chapter 6: Configuration, Timeouts, and Runtime Tuning](06-configuration-timeouts-and-runtime-tuning.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `client/bin/start.js`
+The `startDevClient` function in [`client/bin/start.js`](https://github.com/modelcontextprotocol/inspector/blob/HEAD/client/bin/start.js) handles a key part of this chapter's functionality:
+
+```js
+}
+
+async function startDevClient(clientOptions) {
+ const {
+ CLIENT_PORT,
+ SERVER_PORT,
+ authDisabled,
+ sessionToken,
+ abort,
+ cancelled,
+ } = clientOptions;
+ const clientCommand = "npx";
+ const host = process.env.HOST || "localhost";
+ const clientArgs = ["vite", "--port", CLIENT_PORT, "--host", host];
+ const isWindows = process.platform === "win32";
+
+ const spawnOptions = {
+ cwd: resolve(__dirname, ".."),
+ env: { ...process.env, CLIENT_PORT },
+ signal: abort.signal,
+ echoOutput: true,
+ };
+
+ // For Windows, we need to ignore stdin to prevent hanging
+ if (isWindows) {
+ spawnOptions.stdio = ["ignore", "pipe", "pipe"];
+ }
+
+ const client = spawn(clientCommand, clientArgs, spawnOptions);
+
+ const url = getClientUrl(
+ CLIENT_PORT,
+```
+
+This function is important because it defines how MCP Inspector Tutorial: Debugging and Validating MCP Servers implements the patterns covered in this chapter.
+
+### `client/bin/start.js`
+
+The `startProdClient` function in [`client/bin/start.js`](https://github.com/modelcontextprotocol/inspector/blob/HEAD/client/bin/start.js) handles a key part of this chapter's functionality:
+
+```js
+}
+
+async function startProdClient(clientOptions) {
+ const {
+ CLIENT_PORT,
+ SERVER_PORT,
+ authDisabled,
+ sessionToken,
+ abort,
+ cancelled,
+ } = clientOptions;
+ const inspectorClientPath = resolve(
+ __dirname,
+ "../..",
+ "client",
+ "bin",
+ "client.js",
+ );
+
+ const url = getClientUrl(
+ CLIENT_PORT,
+ authDisabled,
+ sessionToken,
+ SERVER_PORT,
+ );
+
+ await spawnPromise("node", [inspectorClientPath], {
+ env: {
+ ...process.env,
+ CLIENT_PORT,
+ INSPECTOR_URL: url,
+ },
+```
+
+This function is important because it defines how MCP Inspector Tutorial: Debugging and Validating MCP Servers implements the patterns covered in this chapter.
+
+### `client/bin/start.js`
+
The `main` function in [`client/bin/start.js`](https://github.com/modelcontextprotocol/inspector/blob/HEAD/client/bin/start.js) handles a key part of this chapter's functionality:
```js
@@ -90,96 +170,14 @@ async function main() {
This function is important because it defines how MCP Inspector Tutorial: Debugging and Validating MCP Servers implements the patterns covered in this chapter.
-### `cli/src/cli.ts`
-
-The `handleError` function in [`cli/src/cli.ts`](https://github.com/modelcontextprotocol/inspector/blob/HEAD/cli/src/cli.ts) handles a key part of this chapter's functionality:
-
-```ts
- };
-
-function handleError(error: unknown): never {
- let message: string;
-
- if (error instanceof Error) {
- message = error.message;
- } else if (typeof error === "string") {
- message = error;
- } else {
- message = "Unknown error";
- }
-
- console.error(message);
-
- process.exit(1);
-}
-
-function delay(ms: number): Promise<void> {
- return new Promise((resolve) => setTimeout(resolve, ms, true));
-}
-
-async function runWebClient(args: Args): Promise<void> {
- // Path to the client entry point
- const inspectorClientPath = resolve(
- __dirname,
- "../../",
- "client",
- "bin",
- "start.js",
- );
-
-```
-
-This function is important because it defines how MCP Inspector Tutorial: Debugging and Validating MCP Servers implements the patterns covered in this chapter.
-
-### `cli/src/cli.ts`
-
-The `delay` function in [`cli/src/cli.ts`](https://github.com/modelcontextprotocol/inspector/blob/HEAD/cli/src/cli.ts) handles a key part of this chapter's functionality:
-
-```ts
-}
-
-function delay(ms: number): Promise<void> {
- return new Promise((resolve) => setTimeout(resolve, ms, true));
-}
-
-async function runWebClient(args: Args): Promise<void> {
- // Path to the client entry point
- const inspectorClientPath = resolve(
- __dirname,
- "../../",
- "client",
- "bin",
- "start.js",
- );
-
- const abort = new AbortController();
- let cancelled: boolean = false;
- process.on("SIGINT", () => {
- cancelled = true;
- abort.abort();
- });
-
- // Build arguments to pass to start.js
- const startArgs: string[] = [];
-
- // Pass environment variables
- for (const [key, value] of Object.entries(args.envArgs)) {
- startArgs.push("-e", `${key}=${value}`);
- }
-
- // Pass transport type if specified
-```
-
-This function is important because it defines how MCP Inspector Tutorial: Debugging and Validating MCP Servers implements the patterns covered in this chapter.
-
## How These Components Connect
```mermaid
flowchart TD
- A[main]
- B[handleError]
- C[delay]
+ A[startDevClient]
+ B[startProdClient]
+ C[main]
A --> B
B --> C
```
diff --git a/tutorials/mcp-inspector-tutorial/06-configuration-timeouts-and-runtime-tuning.md b/tutorials/mcp-inspector-tutorial/06-configuration-timeouts-and-runtime-tuning.md
index efef5ee5..304fdc7e 100644
--- a/tutorials/mcp-inspector-tutorial/06-configuration-timeouts-and-runtime-tuning.md
+++ b/tutorials/mcp-inspector-tutorial/06-configuration-timeouts-and-runtime-tuning.md
@@ -45,15 +45,58 @@ You now have a runtime tuning approach that reduces false failures and stalled s
Next: [Chapter 7: Inspector in Server Development Lifecycle](07-inspector-in-server-development-lifecycle.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `cli/src/cli.ts`
-The `runWebClient` function in [`cli/src/cli.ts`](https://github.com/modelcontextprotocol/inspector/blob/HEAD/cli/src/cli.ts) handles a key part of this chapter's functionality:
+The `handleError` function in [`cli/src/cli.ts`](https://github.com/modelcontextprotocol/inspector/blob/HEAD/cli/src/cli.ts) handles a key part of this chapter's functionality:
```ts
+ };
+
+function handleError(error: unknown): never {
+ let message: string;
+
+ if (error instanceof Error) {
+ message = error.message;
+ } else if (typeof error === "string") {
+ message = error;
+ } else {
+ message = "Unknown error";
+ }
+
+ console.error(message);
+
+ process.exit(1);
+}
+
+function delay(ms: number): Promise<void> {
+ return new Promise((resolve) => setTimeout(resolve, ms, true));
+}
+
+async function runWebClient(args: Args): Promise<void> {
+ // Path to the client entry point
+ const inspectorClientPath = resolve(
+ __dirname,
+ "../../",
+ "client",
+ "bin",
+ "start.js",
+ );
+
+```
+
+This function is important because it defines how MCP Inspector Tutorial: Debugging and Validating MCP Servers implements the patterns covered in this chapter.
+
+### `cli/src/cli.ts`
+
+The `delay` function in [`cli/src/cli.ts`](https://github.com/modelcontextprotocol/inspector/blob/HEAD/cli/src/cli.ts) handles a key part of this chapter's functionality:
+
+```ts
+}
+
+function delay(ms: number): Promise<void> {
+ return new Promise((resolve) => setTimeout(resolve, ms, true));
}
async function runWebClient(args: Args): Promise<void> {
@@ -82,91 +125,46 @@ async function runWebClient(args: Args): Promise<void> {
}
// Pass transport type if specified
- if (args.transport) {
- startArgs.push("--transport", args.transport);
- }
-
```
This function is important because it defines how MCP Inspector Tutorial: Debugging and Validating MCP Servers implements the patterns covered in this chapter.
### `cli/src/cli.ts`
-The `runCli` function in [`cli/src/cli.ts`](https://github.com/modelcontextprotocol/inspector/blob/HEAD/cli/src/cli.ts) handles a key part of this chapter's functionality:
+The `runWebClient` function in [`cli/src/cli.ts`](https://github.com/modelcontextprotocol/inspector/blob/HEAD/cli/src/cli.ts) handles a key part of this chapter's functionality:
```ts
}
-async function runCli(args: Args): Promise<void> {
- const projectRoot = resolve(__dirname, "..");
- const cliPath = resolve(projectRoot, "build", "index.js");
+async function runWebClient(args: Args): Promise<void> {
+ // Path to the client entry point
+ const inspectorClientPath = resolve(
+ __dirname,
+ "../../",
+ "client",
+ "bin",
+ "start.js",
+ );
const abort = new AbortController();
-
- let cancelled = false;
-
+ let cancelled: boolean = false;
process.on("SIGINT", () => {
cancelled = true;
abort.abort();
});
- try {
- // Build CLI arguments
- const cliArgs = [cliPath];
-
- // Add target URL/command first
- cliArgs.push(args.command, ...args.args);
-
- // Add transport flag if specified
- if (args.transport && args.transport !== "stdio") {
- // Convert streamable-http back to http for CLI mode
- const cliTransport =
- args.transport === "streamable-http" ? "http" : args.transport;
- cliArgs.push("--transport", cliTransport);
- }
-
- // Add headers if specified
- if (args.headers) {
-```
-
-This function is important because it defines how MCP Inspector Tutorial: Debugging and Validating MCP Servers implements the patterns covered in this chapter.
-
-### `cli/src/cli.ts`
-
-The `loadConfigFile` function in [`cli/src/cli.ts`](https://github.com/modelcontextprotocol/inspector/blob/HEAD/cli/src/cli.ts) handles a key part of this chapter's functionality:
-
-```ts
-}
-
-function loadConfigFile(configPath: string, serverName: string): ServerConfig {
- try {
- const resolvedConfigPath = path.isAbsolute(configPath)
- ? configPath
- : path.resolve(process.cwd(), configPath);
-
- if (!fs.existsSync(resolvedConfigPath)) {
- throw new Error(`Config file not found: ${resolvedConfigPath}`);
- }
-
- const configContent = fs.readFileSync(resolvedConfigPath, "utf8");
- const parsedConfig = JSON.parse(configContent);
-
- if (!parsedConfig.mcpServers || !parsedConfig.mcpServers[serverName]) {
- const availableServers = Object.keys(parsedConfig.mcpServers || {}).join(
- ", ",
- );
- throw new Error(
- `Server '${serverName}' not found in config file. Available servers: ${availableServers}`,
- );
- }
+ // Build arguments to pass to start.js
+ const startArgs: string[] = [];
- const serverConfig = parsedConfig.mcpServers[serverName];
+ // Pass environment variables
+ for (const [key, value] of Object.entries(args.envArgs)) {
+ startArgs.push("-e", `${key}=${value}`);
+ }
- return serverConfig;
- } catch (err: unknown) {
- if (err instanceof SyntaxError) {
- throw new Error(`Invalid JSON in config file: ${err.message}`);
- }
+ // Pass transport type if specified
+ if (args.transport) {
+ startArgs.push("--transport", args.transport);
+ }
```
@@ -177,9 +175,9 @@ This function is important because it defines how MCP Inspector Tutorial: Debugg
```mermaid
flowchart TD
- A[runWebClient]
- B[runCli]
- C[loadConfigFile]
+ A[handleError]
+ B[delay]
+ C[runWebClient]
A --> B
B --> C
```
diff --git a/tutorials/mcp-inspector-tutorial/07-inspector-in-server-development-lifecycle.md b/tutorials/mcp-inspector-tutorial/07-inspector-in-server-development-lifecycle.md
index d3d9bcdf..6a9b91f5 100644
--- a/tutorials/mcp-inspector-tutorial/07-inspector-in-server-development-lifecycle.md
+++ b/tutorials/mcp-inspector-tutorial/07-inspector-in-server-development-lifecycle.md
@@ -46,129 +46,127 @@ You now have an integration model for using Inspector as a consistent part of se
Next: [Chapter 8: Production Ops, Testing, and Contribution](08-production-ops-testing-and-contribution.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `cli/src/cli.ts`
-The `parseKeyValuePair` function in [`cli/src/cli.ts`](https://github.com/modelcontextprotocol/inspector/blob/HEAD/cli/src/cli.ts) handles a key part of this chapter's functionality:
+The `runCli` function in [`cli/src/cli.ts`](https://github.com/modelcontextprotocol/inspector/blob/HEAD/cli/src/cli.ts) handles a key part of this chapter's functionality:
```ts
}
-function parseKeyValuePair(
- value: string,
- previous: Record<string, string> = {},
-): Record<string, string> {
- const parts = value.split("=");
- const key = parts[0];
- const val = parts.slice(1).join("=");
+async function runCli(args: Args): Promise<void> {
+ const projectRoot = resolve(__dirname, "..");
+ const cliPath = resolve(projectRoot, "build", "index.js");
- if (val === undefined || val === "") {
- throw new Error(
- `Invalid parameter format: ${value}. Use key=value format.`,
- );
- }
+ const abort = new AbortController();
- return { ...previous, [key as string]: val };
-}
+ let cancelled = false;
-function parseHeaderPair(
- value: string,
- previous: Record<string, string> = {},
-): Record<string, string> {
- const colonIndex = value.indexOf(":");
+ process.on("SIGINT", () => {
+ cancelled = true;
+ abort.abort();
+ });
- if (colonIndex === -1) {
- throw new Error(
- `Invalid header format: ${value}. Use "HeaderName: Value" format.`,
- );
- }
+ try {
+ // Build CLI arguments
+ const cliArgs = [cliPath];
- const key = value.slice(0, colonIndex).trim();
+ // Add target URL/command first
+ cliArgs.push(args.command, ...args.args);
+
+ // Add transport flag if specified
+ if (args.transport && args.transport !== "stdio") {
+ // Convert streamable-http back to http for CLI mode
+ const cliTransport =
+ args.transport === "streamable-http" ? "http" : args.transport;
+ cliArgs.push("--transport", cliTransport);
+ }
+
+ // Add headers if specified
+ if (args.headers) {
```
This function is important because it defines how MCP Inspector Tutorial: Debugging and Validating MCP Servers implements the patterns covered in this chapter.
### `cli/src/cli.ts`
-The `parseHeaderPair` function in [`cli/src/cli.ts`](https://github.com/modelcontextprotocol/inspector/blob/HEAD/cli/src/cli.ts) handles a key part of this chapter's functionality:
+The `loadConfigFile` function in [`cli/src/cli.ts`](https://github.com/modelcontextprotocol/inspector/blob/HEAD/cli/src/cli.ts) handles a key part of this chapter's functionality:
```ts
}
-function parseHeaderPair(
- value: string,
- previous: Record<string, string> = {},
-): Record<string, string> {
- const colonIndex = value.indexOf(":");
+function loadConfigFile(configPath: string, serverName: string): ServerConfig {
+ try {
+ const resolvedConfigPath = path.isAbsolute(configPath)
+ ? configPath
+ : path.resolve(process.cwd(), configPath);
- if (colonIndex === -1) {
- throw new Error(
- `Invalid header format: ${value}. Use "HeaderName: Value" format.`,
- );
- }
+ if (!fs.existsSync(resolvedConfigPath)) {
+ throw new Error(`Config file not found: ${resolvedConfigPath}`);
+ }
- const key = value.slice(0, colonIndex).trim();
- const val = value.slice(colonIndex + 1).trim();
+ const configContent = fs.readFileSync(resolvedConfigPath, "utf8");
+ const parsedConfig = JSON.parse(configContent);
- if (key === "" || val === "") {
- throw new Error(
- `Invalid header format: ${value}. Use "HeaderName: Value" format.`,
- );
- }
+ if (!parsedConfig.mcpServers || !parsedConfig.mcpServers[serverName]) {
+ const availableServers = Object.keys(parsedConfig.mcpServers || {}).join(
+ ", ",
+ );
+ throw new Error(
+ `Server '${serverName}' not found in config file. Available servers: ${availableServers}`,
+ );
+ }
- return { ...previous, [key]: val };
-}
+ const serverConfig = parsedConfig.mcpServers[serverName];
-function parseArgs(): Args {
- const program = new Command();
+ return serverConfig;
+ } catch (err: unknown) {
+ if (err instanceof SyntaxError) {
+ throw new Error(`Invalid JSON in config file: ${err.message}`);
+ }
- const argSeparatorIndex = process.argv.indexOf("--");
- let preArgs = process.argv;
- let postArgs: string[] = [];
```
This function is important because it defines how MCP Inspector Tutorial: Debugging and Validating MCP Servers implements the patterns covered in this chapter.
### `cli/src/cli.ts`
-The `parseArgs` function in [`cli/src/cli.ts`](https://github.com/modelcontextprotocol/inspector/blob/HEAD/cli/src/cli.ts) handles a key part of this chapter's functionality:
+The `parseKeyValuePair` function in [`cli/src/cli.ts`](https://github.com/modelcontextprotocol/inspector/blob/HEAD/cli/src/cli.ts) handles a key part of this chapter's functionality:
```ts
}
-function parseArgs(): Args {
- const program = new Command();
+function parseKeyValuePair(
+ value: string,
+ previous: Record<string, string> = {},
+): Record<string, string> {
+ const parts = value.split("=");
+ const key = parts[0];
+ const val = parts.slice(1).join("=");
+
+ if (val === undefined || val === "") {
+ throw new Error(
+ `Invalid parameter format: ${value}. Use key=value format.`,
+ );
+ }
- const argSeparatorIndex = process.argv.indexOf("--");
- let preArgs = process.argv;
- let postArgs: string[] = [];
+ return { ...previous, [key as string]: val };
+}
+
+function parseHeaderPair(
+ value: string,
+ previous: Record<string, string> = {},
+): Record<string, string> {
+ const colonIndex = value.indexOf(":");
- if (argSeparatorIndex !== -1) {
- preArgs = process.argv.slice(0, argSeparatorIndex);
- postArgs = process.argv.slice(argSeparatorIndex + 1);
+ if (colonIndex === -1) {
+ throw new Error(
+ `Invalid header format: ${value}. Use "HeaderName: Value" format.`,
+ );
}
- program
- .name("inspector-bin")
- .allowExcessArguments()
- .allowUnknownOption()
- .option(
- "-e <env>",
- "environment variables in KEY=VALUE format",
- parseKeyValuePair,
- {},
- )
- .option("--config <path>", "config file path")
- .option("--server <n>", "server name from config file")
- .option("--cli", "enable CLI mode")
- .option("--transport <type>", "transport type (stdio, sse, http)")
- .option("--server-url <url>", "server URL for SSE/HTTP transport")
- .option(
- "--header <headers...>",
- 'HTTP headers as "HeaderName: Value" pairs (for HTTP/SSE transports)',
+ const key = value.slice(0, colonIndex).trim();
```
This function is important because it defines how MCP Inspector Tutorial: Debugging and Validating MCP Servers implements the patterns covered in this chapter.
@@ -178,9 +176,9 @@ This function is important because it defines how MCP Inspector Tutorial: Debugg
```mermaid
flowchart TD
- A[parseKeyValuePair]
- B[parseHeaderPair]
- C[parseArgs]
+ A[runCli]
+ B[loadConfigFile]
+ C[parseKeyValuePair]
A --> B
B --> C
```
diff --git a/tutorials/mcp-inspector-tutorial/08-production-ops-testing-and-contribution.md b/tutorials/mcp-inspector-tutorial/08-production-ops-testing-and-contribution.md
index 737353f6..ef34dc57 100644
--- a/tutorials/mcp-inspector-tutorial/08-production-ops-testing-and-contribution.md
+++ b/tutorials/mcp-inspector-tutorial/08-production-ops-testing-and-contribution.md
@@ -39,12 +39,92 @@ You now have a production-oriented approach for operating Inspector and contribu
Next: Continue with [MCP Registry Tutorial](../mcp-registry-tutorial/)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `cli/src/cli.ts`
+The `parseHeaderPair` function in [`cli/src/cli.ts`](https://github.com/modelcontextprotocol/inspector/blob/HEAD/cli/src/cli.ts) handles a key part of this chapter's functionality:
+
+```ts
+}
+
+function parseHeaderPair(
+ value: string,
+ previous: Record<string, string> = {},
+): Record<string, string> {
+ const colonIndex = value.indexOf(":");
+
+ if (colonIndex === -1) {
+ throw new Error(
+ `Invalid header format: ${value}. Use "HeaderName: Value" format.`,
+ );
+ }
+
+ const key = value.slice(0, colonIndex).trim();
+ const val = value.slice(colonIndex + 1).trim();
+
+ if (key === "" || val === "") {
+ throw new Error(
+ `Invalid header format: ${value}. Use "HeaderName: Value" format.`,
+ );
+ }
+
+ return { ...previous, [key]: val };
+}
+
+function parseArgs(): Args {
+ const program = new Command();
+
+ const argSeparatorIndex = process.argv.indexOf("--");
+ let preArgs = process.argv;
+ let postArgs: string[] = [];
+```
+
+This function is important because it defines how MCP Inspector Tutorial: Debugging and Validating MCP Servers implements the patterns covered in this chapter.
+
+### `cli/src/cli.ts`
+
+The `parseArgs` function in [`cli/src/cli.ts`](https://github.com/modelcontextprotocol/inspector/blob/HEAD/cli/src/cli.ts) handles a key part of this chapter's functionality:
+
+```ts
+}
+
+function parseArgs(): Args {
+ const program = new Command();
+
+ const argSeparatorIndex = process.argv.indexOf("--");
+ let preArgs = process.argv;
+ let postArgs: string[] = [];
+
+ if (argSeparatorIndex !== -1) {
+ preArgs = process.argv.slice(0, argSeparatorIndex);
+ postArgs = process.argv.slice(argSeparatorIndex + 1);
+ }
+
+ program
+ .name("inspector-bin")
+ .allowExcessArguments()
+ .allowUnknownOption()
+ .option(
+ "-e <env>",
+ "environment variables in KEY=VALUE format",
+ parseKeyValuePair,
+ {},
+ )
+ .option("--config <path>", "config file path")
+ .option("--server <n>", "server name from config file")
+ .option("--cli", "enable CLI mode")
+ .option("--transport <type>", "transport type (stdio, sse, http)")
+ .option("--server-url <url>", "server URL for SSE/HTTP transport")
+ .option(
+ "--header <headers...>",
+ 'HTTP headers as "HeaderName: Value" pairs (for HTTP/SSE transports)',
+```
+
+This function is important because it defines how MCP Inspector Tutorial: Debugging and Validating MCP Servers implements the patterns covered in this chapter.
+
+### `cli/src/cli.ts`
+
The `main` function in [`cli/src/cli.ts`](https://github.com/modelcontextprotocol/inspector/blob/HEAD/cli/src/cli.ts) handles a key part of this chapter's functionality:
```ts
@@ -84,96 +164,14 @@ The `main` function in [`cli/src/cli.ts`](https://github.com/modelcontextprotoco
This function is important because it defines how MCP Inspector Tutorial: Debugging and Validating MCP Servers implements the patterns covered in this chapter.
-### `cli/src/transport.ts`
-
-The `createStdioTransport` function in [`cli/src/transport.ts`](https://github.com/modelcontextprotocol/inspector/blob/HEAD/cli/src/transport.ts) handles a key part of this chapter's functionality:
-
-```ts
-};
-
-function createStdioTransport(options: TransportOptions): Transport {
- let args: string[] = [];
-
- if (options.args !== undefined) {
- args = options.args;
- }
-
- const processEnv: Record<string, string> = {};
-
- for (const [key, value] of Object.entries(process.env)) {
- if (value !== undefined) {
- processEnv[key] = value;
- }
- }
-
- const defaultEnv = getDefaultEnvironment();
-
- const env: Record<string, string> = {
- ...defaultEnv,
- ...processEnv,
- };
-
- const { cmd: actualCommand, args: actualArgs } = findActualExecutable(
- options.command ?? "",
- args,
- );
-
- return new StdioClientTransport({
- command: actualCommand,
- args: actualArgs,
-```
-
-This function is important because it defines how MCP Inspector Tutorial: Debugging and Validating MCP Servers implements the patterns covered in this chapter.
-
-### `cli/src/transport.ts`
-
-The `createTransport` function in [`cli/src/transport.ts`](https://github.com/modelcontextprotocol/inspector/blob/HEAD/cli/src/transport.ts) handles a key part of this chapter's functionality:
-
-```ts
-}
-
-export function createTransport(options: TransportOptions): Transport {
- const { transportType } = options;
-
- try {
- if (transportType === "stdio") {
- return createStdioTransport(options);
- }
-
- // If not STDIO, then it must be either SSE or HTTP.
- if (!options.url) {
- throw new Error("URL must be provided for SSE or HTTP transport types.");
- }
- const url = new URL(options.url);
-
- if (transportType === "sse") {
- const transportOptions = options.headers
- ? {
- requestInit: {
- headers: options.headers,
- },
- }
- : undefined;
- return new SSEClientTransport(url, transportOptions);
- }
-
- if (transportType === "http") {
- const transportOptions = options.headers
- ? {
- requestInit: {
- headers: options.headers,
-```
-
-This function is important because it defines how MCP Inspector Tutorial: Debugging and Validating MCP Servers implements the patterns covered in this chapter.
-
## How These Components Connect
```mermaid
flowchart TD
- A[main]
- B[createStdioTransport]
- C[createTransport]
+ A[parseHeaderPair]
+ B[parseArgs]
+ C[main]
A --> B
B --> C
```
diff --git a/tutorials/mcp-java-sdk-tutorial/01-getting-started-and-module-selection.md b/tutorials/mcp-java-sdk-tutorial/01-getting-started-and-module-selection.md
index aa977065..e6f9924a 100644
--- a/tutorials/mcp-java-sdk-tutorial/01-getting-started-and-module-selection.md
+++ b/tutorials/mcp-java-sdk-tutorial/01-getting-started-and-module-selection.md
@@ -47,18 +47,16 @@ You now have a stable Java MCP baseline and module decision model.
Next: [Chapter 2: SDK Architecture: Reactive Model and JSON Layer](02-sdk-architecture-reactive-model-and-json-layer.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessServerFeatures.java`
+### `mcp-core/src/main/java/io/modelcontextprotocol/server/McpServerFeatures.java`
-The `McpStatelessServerFeatures` class in [`mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessServerFeatures.java`](https://github.com/modelcontextprotocol/java-sdk/blob/HEAD/mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessServerFeatures.java) handles a key part of this chapter's functionality:
+The `McpServerFeatures` class in [`mcp-core/src/main/java/io/modelcontextprotocol/server/McpServerFeatures.java`](https://github.com/modelcontextprotocol/java-sdk/blob/HEAD/mcp-core/src/main/java/io/modelcontextprotocol/server/McpServerFeatures.java) handles a key part of this chapter's functionality:
```java
- * @author Christian Tzolov
+ * @author Jihoon Kim
*/
-public class McpStatelessServerFeatures {
+public class McpServerFeatures {
/**
* Asynchronous server features specification.
@@ -67,16 +65,18 @@ public class McpStatelessServerFeatures {
* @param serverCapabilities The server capabilities
* @param tools The list of tool specifications
* @param resources The map of resource specifications
- * @param resourceTemplates The map of resource templates
+ * @param resourceTemplates The list of resource templates
* @param prompts The map of prompt specifications
+ * @param rootsChangeConsumers The list of consumers that will be notified when the
+ * roots list changes
* @param instructions The server instructions text
*/
record Async(McpSchema.Implementation serverInfo, McpSchema.ServerCapabilities serverCapabilities,
- List<McpStatelessServerFeatures.AsyncToolSpecification> tools,
- Map<String, AsyncResourceSpecification> resources,
- Map<String, McpStatelessServerFeatures.AsyncResourceTemplateSpecification> resourceTemplates,
- Map<String, McpStatelessServerFeatures.AsyncPromptSpecification> prompts,
- Map<McpSchema.CompleteReference, McpStatelessServerFeatures.AsyncCompletionSpecification> completions,
+ List<McpServerFeatures.AsyncToolSpecification> tools, Map<String, AsyncResourceSpecification> resources,
+ Map<String, McpServerFeatures.AsyncResourceTemplateSpecification> resourceTemplates,
+ Map<String, McpServerFeatures.AsyncPromptSpecification> prompts,
+ Map<McpSchema.CompleteReference, McpServerFeatures.AsyncCompletionSpecification> completions,
+ List<BiFunction<McpAsyncServerExchange, List<McpSchema.Root>, Mono<Void>>> rootsChangeConsumers,
String instructions) {
/**
@@ -86,15 +86,13 @@ public class McpStatelessServerFeatures {
* @param tools The list of tool specifications
* @param resources The map of resource specifications
* @param resourceTemplates The map of resource templates
- * @param prompts The map of prompt specifications
- * @param instructions The server instructions text
```
This class is important because it defines how MCP Java SDK Tutorial: Building MCP Clients and Servers with Reactor, Servlet, and Spring implements the patterns covered in this chapter.
-### `mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessServerFeatures.java`
+### `mcp-core/src/main/java/io/modelcontextprotocol/server/McpServerFeatures.java`
-The `Builder` class in [`mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessServerFeatures.java`](https://github.com/modelcontextprotocol/java-sdk/blob/HEAD/mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessServerFeatures.java) handles a key part of this chapter's functionality:
+The `Builder` class in [`mcp-core/src/main/java/io/modelcontextprotocol/server/McpServerFeatures.java`](https://github.com/modelcontextprotocol/java-sdk/blob/HEAD/mcp-core/src/main/java/io/modelcontextprotocol/server/McpServerFeatures.java) handles a key part of this chapter's functionality:
```java
@@ -105,7 +103,7 @@ The `Builder` class in [`mcp-core/src/main/java/io/modelcontextprotocol/server/M
private McpSchema.Tool tool;
- private BiFunction<McpTransportContext, CallToolRequest, Mono<McpSchema.CallToolResult>> callHandler;
+ private BiFunction<McpAsyncServerExchange, McpSchema.CallToolRequest, Mono<McpSchema.CallToolResult>> callHandler;
/**
* Sets the tool definition.
@@ -124,7 +122,7 @@ The `Builder` class in [`mcp-core/src/main/java/io/modelcontextprotocol/server/M
* @return this builder instance
*/
public Builder callHandler(
- BiFunction<McpTransportContext, CallToolRequest, Mono<McpSchema.CallToolResult>> callHandler) {
+ BiFunction<McpAsyncServerExchange, McpSchema.CallToolRequest, Mono<McpSchema.CallToolResult>> callHandler) {
this.callHandler = callHandler;
return this;
}
@@ -133,9 +131,9 @@ The `Builder` class in [`mcp-core/src/main/java/io/modelcontextprotocol/server/M
This class is important because it defines how MCP Java SDK Tutorial: Building MCP Clients and Servers with Reactor, Servlet, and Spring implements the patterns covered in this chapter.
-### `mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessServerFeatures.java`
+### `mcp-core/src/main/java/io/modelcontextprotocol/server/McpServerFeatures.java`
-The `Builder` class in [`mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessServerFeatures.java`](https://github.com/modelcontextprotocol/java-sdk/blob/HEAD/mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessServerFeatures.java) handles a key part of this chapter's functionality:
+The `Builder` class in [`mcp-core/src/main/java/io/modelcontextprotocol/server/McpServerFeatures.java`](https://github.com/modelcontextprotocol/java-sdk/blob/HEAD/mcp-core/src/main/java/io/modelcontextprotocol/server/McpServerFeatures.java) handles a key part of this chapter's functionality:
```java
@@ -146,7 +144,7 @@ The `Builder` class in [`mcp-core/src/main/java/io/modelcontextprotocol/server/M
private McpSchema.Tool tool;
- private BiFunction<McpTransportContext, CallToolRequest, Mono<McpSchema.CallToolResult>> callHandler;
+ private BiFunction<McpAsyncServerExchange, McpSchema.CallToolRequest, Mono<McpSchema.CallToolResult>> callHandler;
/**
* Sets the tool definition.
@@ -165,7 +163,7 @@ The `Builder` class in [`mcp-core/src/main/java/io/modelcontextprotocol/server/M
* @return this builder instance
*/
public Builder callHandler(
- BiFunction<McpTransportContext, CallToolRequest, Mono<McpSchema.CallToolResult>> callHandler) {
+ BiFunction<McpAsyncServerExchange, McpSchema.CallToolRequest, Mono<McpSchema.CallToolResult>> callHandler) {
this.callHandler = callHandler;
return this;
}
@@ -220,7 +218,7 @@ This class is important because it defines how MCP Java SDK Tutorial: Building M
```mermaid
flowchart TD
- A[McpStatelessServerFeatures]
+ A[McpServerFeatures]
B[Builder]
C[Builder]
D[McpAsyncServer]
diff --git a/tutorials/mcp-java-sdk-tutorial/02-sdk-architecture-reactive-model-and-json-layer.md b/tutorials/mcp-java-sdk-tutorial/02-sdk-architecture-reactive-model-and-json-layer.md
index 430d7075..20971c28 100644
--- a/tutorials/mcp-java-sdk-tutorial/02-sdk-architecture-reactive-model-and-json-layer.md
+++ b/tutorials/mcp-java-sdk-tutorial/02-sdk-architecture-reactive-model-and-json-layer.md
@@ -46,97 +46,142 @@ You now understand why Java SDK core abstractions are shaped for bidirectional a
Next: [Chapter 3: Client Transports and Connection Strategy](03-client-transports-and-connection-strategy.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `mcp-core/src/main/java/io/modelcontextprotocol/client/McpClient.java`
+### `mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessServerFeatures.java`
-The `serves` class in [`mcp-core/src/main/java/io/modelcontextprotocol/client/McpClient.java`](https://github.com/modelcontextprotocol/java-sdk/blob/HEAD/mcp-core/src/main/java/io/modelcontextprotocol/client/McpClient.java) handles a key part of this chapter's functionality:
+The `Builder` class in [`mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessServerFeatures.java`](https://github.com/modelcontextprotocol/java-sdk/blob/HEAD/mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessServerFeatures.java) handles a key part of this chapter's functionality:
```java
- *
- * <p>
- * This class serves as the main entry point for establishing connections with MCP
- * servers, implementing the client-side of the MCP specification. The protocol follows a
- * client-server architecture where:
- * <ul>
- * <li>The client (this implementation) initiates connections and sends requests
- * <li>The server responds to requests and provides access to tools and resources
- * <li>Communication occurs through a transport layer (e.g., stdio, SSE) using JSON-RPC
- * 2.0
- * </ul>
- *
- * <p>
- * The class provides factory methods to create either:
- * <ul>
- * <li>{@link McpAsyncClient} for non-blocking operations with CompletableFuture responses
- * <li>{@link McpSyncClient} for blocking operations with direct responses
- * </ul>
- *
- * <p>
- * Example of creating a basic synchronous client: <pre>{@code
- * McpClient.sync(transport)
- * .requestTimeout(Duration.ofSeconds(5))
- * .build();
- * }</pre>
- *
- * Example of creating a basic asynchronous client: <pre>{@code
- * McpClient.async(transport)
- * .requestTimeout(Duration.ofSeconds(5))
- * .build();
- * }</pre>
- *
+
+ /**
+ * Builder for creating AsyncToolSpecification instances.
+ */
+ public static class Builder {
+
+ private McpSchema.Tool tool;
+
+ private BiFunction<McpTransportContext, CallToolRequest, Mono<McpSchema.CallToolResult>> callHandler;
+
+ /**
+ * Sets the tool definition.
+ * @param tool The tool definition including name, description, and parameter
+ * schema
+ * @return this builder instance
+ */
+ public Builder tool(McpSchema.Tool tool) {
+ this.tool = tool;
+ return this;
+ }
+
+ /**
+ * Sets the call tool handler function.
+ * @param callHandler The function that implements the tool's logic
+ * @return this builder instance
+ */
+ public Builder callHandler(
+ BiFunction<McpTransportContext, CallToolRequest, Mono<McpSchema.CallToolResult>> callHandler) {
+ this.callHandler = callHandler;
+ return this;
+ }
+
```
This class is important because it defines how MCP Java SDK Tutorial: Building MCP Clients and Servers with Reactor, Servlet, and Spring implements the patterns covered in this chapter.
-### `mcp-core/src/main/java/io/modelcontextprotocol/client/McpClient.java`
+### `mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessServerFeatures.java`
-The `provides` class in [`mcp-core/src/main/java/io/modelcontextprotocol/client/McpClient.java`](https://github.com/modelcontextprotocol/java-sdk/blob/HEAD/mcp-core/src/main/java/io/modelcontextprotocol/client/McpClient.java) handles a key part of this chapter's functionality:
+The `Builder` class in [`mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessServerFeatures.java`](https://github.com/modelcontextprotocol/java-sdk/blob/HEAD/mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessServerFeatures.java) handles a key part of this chapter's functionality:
```java
- * <ul>
- * <li>The client (this implementation) initiates connections and sends requests
- * <li>The server responds to requests and provides access to tools and resources
- * <li>Communication occurs through a transport layer (e.g., stdio, SSE) using JSON-RPC
- * 2.0
- * </ul>
- *
- * <p>
- * The class provides factory methods to create either:
- * <ul>
- * <li>{@link McpAsyncClient} for non-blocking operations with CompletableFuture responses
- * <li>{@link McpSyncClient} for blocking operations with direct responses
- * </ul>
- *
- * <p>
- * Example of creating a basic synchronous client: <pre>{@code
- * McpClient.sync(transport)
- * .requestTimeout(Duration.ofSeconds(5))
- * .build();
- * }</pre>
- *
- * Example of creating a basic asynchronous client: <pre>{@code
- * McpClient.async(transport)
- * .requestTimeout(Duration.ofSeconds(5))
- * .build();
- * }</pre>
- *
- * <p>
- * Example with advanced asynchronous configuration: <pre>{@code
- * McpClient.async(transport)
- * .requestTimeout(Duration.ofSeconds(10))
- * .capabilities(new ClientCapabilities(...))
+
+ /**
+ * Builder for creating AsyncToolSpecification instances.
+ */
+ public static class Builder {
+
+ private McpSchema.Tool tool;
+
+ private BiFunction<McpTransportContext, CallToolRequest, Mono<McpSchema.CallToolResult>> callHandler;
+
+ /**
+ * Sets the tool definition.
+ * @param tool The tool definition including name, description, and parameter
+ * schema
+ * @return this builder instance
+ */
+ public Builder tool(McpSchema.Tool tool) {
+ this.tool = tool;
+ return this;
+ }
+
+ /**
+ * Sets the call tool handler function.
+ * @param callHandler The function that implements the tool's logic
+ * @return this builder instance
+ */
+ public Builder callHandler(
+ BiFunction<McpTransportContext, CallToolRequest, Mono<McpSchema.CallToolResult>> callHandler) {
+ this.callHandler = callHandler;
+ return this;
+ }
+
+```
+
+This class is important because it defines how MCP Java SDK Tutorial: Building MCP Clients and Servers with Reactor, Servlet, and Spring implements the patterns covered in this chapter.
+
+### `mcp-core/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java`
+
+The `McpAsyncClient` class in [`mcp-core/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java`](https://github.com/modelcontextprotocol/java-sdk/blob/HEAD/mcp-core/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java) handles a key part of this chapter's functionality:
+
+```java
+ * @see McpClientTransport
+ */
+public class McpAsyncClient {
+
+ private static final Logger logger = LoggerFactory.getLogger(McpAsyncClient.class);
+
+ private static final TypeRef<Void> VOID_TYPE_REFERENCE = new TypeRef<>() {
+ };
+
+ public static final TypeRef<Object> OBJECT_TYPE_REF = new TypeRef<>() {
+ };
+
+ public static final TypeRef<PaginatedRequest> PAGINATED_REQUEST_TYPE_REF = new TypeRef<>() {
+ };
+
+ public static final TypeRef<McpSchema.InitializeResult> INITIALIZE_RESULT_TYPE_REF = new TypeRef<>() {
+ };
+
+ public static final TypeRef<CreateMessageRequest> CREATE_MESSAGE_REQUEST_TYPE_REF = new TypeRef<>() {
+ };
+
+ public static final TypeRef<LoggingMessageNotification> LOGGING_MESSAGE_NOTIFICATION_TYPE_REF = new TypeRef<>() {
+ };
+
+ public static final TypeRef<McpSchema.ProgressNotification> PROGRESS_NOTIFICATION_TYPE_REF = new TypeRef<>() {
+ };
+
+ public static final String NEGOTIATED_PROTOCOL_VERSION = "io.modelcontextprotocol.client.negotiated-protocol-version";
+
+ /**
+ * Client capabilities.
+ */
```
This class is important because it defines how MCP Java SDK Tutorial: Building MCP Clients and Servers with Reactor, Servlet, and Spring implements the patterns covered in this chapter.
### `mcp-core/src/main/java/io/modelcontextprotocol/client/McpClient.java`
-The `follows` class in [`mcp-core/src/main/java/io/modelcontextprotocol/client/McpClient.java`](https://github.com/modelcontextprotocol/java-sdk/blob/HEAD/mcp-core/src/main/java/io/modelcontextprotocol/client/McpClient.java) handles a key part of this chapter's functionality:
+The `for` class in [`mcp-core/src/main/java/io/modelcontextprotocol/client/McpClient.java`](https://github.com/modelcontextprotocol/java-sdk/blob/HEAD/mcp-core/src/main/java/io/modelcontextprotocol/client/McpClient.java) handles a key part of this chapter's functionality:
```java
+
+/**
+ * Factory class for creating Model Context Protocol (MCP) clients. MCP is a protocol that
+ * enables AI models to interact with external tools and resources through a standardized
+ * interface.
+ *
* <p>
* This class serves as the main entry point for establishing connections with MCP
* servers, implementing the client-side of the MCP specification. The protocol follows a
@@ -163,53 +208,6 @@ The `follows` class in [`mcp-core/src/main/java/io/modelcontextprotocol/client/M
* }</pre>
*
* Example of creating a basic asynchronous client: <pre>{@code
- * McpClient.async(transport)
- * .requestTimeout(Duration.ofSeconds(5))
- * .build();
- * }</pre>
- *
- * <p>
-```
-
-This class is important because it defines how MCP Java SDK Tutorial: Building MCP Clients and Servers with Reactor, Servlet, and Spring implements the patterns covered in this chapter.
-
-### `mcp-core/src/main/java/io/modelcontextprotocol/client/McpClient.java`
-
-The `SyncSpec` class in [`mcp-core/src/main/java/io/modelcontextprotocol/client/McpClient.java`](https://github.com/modelcontextprotocol/java-sdk/blob/HEAD/mcp-core/src/main/java/io/modelcontextprotocol/client/McpClient.java) handles a key part of this chapter's functionality:
-
-```java
- * @throws IllegalArgumentException if transport is null
- */
- static SyncSpec sync(McpClientTransport transport) {
- return new SyncSpec(transport);
- }
-
- /**
- * Start building an asynchronous MCP client with the specified transport layer. The
- * asynchronous MCP client provides non-blocking operations. Asynchronous clients
- * return reactive primitives (Mono/Flux) immediately, allowing for concurrent
- * operations and reactive programming patterns. The transport layer handles the
- * low-level communication between client and server using protocols like stdio or
- * Server-Sent Events (SSE).
- * @param transport The transport layer implementation for MCP communication. Common
- * implementations include {@code StdioClientTransport} for stdio-based communication
- * and {@code SseClientTransport} for SSE-based communication.
- * @return A new builder instance for configuring the client
- * @throws IllegalArgumentException if transport is null
- */
- static AsyncSpec async(McpClientTransport transport) {
- return new AsyncSpec(transport);
- }
-
- /**
- * Synchronous client specification. This class follows the builder pattern to provide
- * a fluent API for setting up clients with custom configurations.
- *
- * <p>
- * The builder supports configuration of:
- * <ul>
- * <li>Transport layer for client-server communication
- * <li>Request timeouts for operation boundaries
```
This class is important because it defines how MCP Java SDK Tutorial: Building MCP Clients and Servers with Reactor, Servlet, and Spring implements the patterns covered in this chapter.
@@ -219,11 +217,11 @@ This class is important because it defines how MCP Java SDK Tutorial: Building M
```mermaid
flowchart TD
- A[serves]
- B[provides]
- C[follows]
- D[SyncSpec]
- E[follows]
+ A[Builder]
+ B[Builder]
+ C[McpAsyncClient]
+ D[for]
+ E[serves]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-java-sdk-tutorial/03-client-transports-and-connection-strategy.md b/tutorials/mcp-java-sdk-tutorial/03-client-transports-and-connection-strategy.md
index d52ef488..2ce84774 100644
--- a/tutorials/mcp-java-sdk-tutorial/03-client-transports-and-connection-strategy.md
+++ b/tutorials/mcp-java-sdk-tutorial/03-client-transports-and-connection-strategy.md
@@ -41,170 +41,168 @@ You now have a transport selection framework for Java clients that balances simp
Next: [Chapter 4: Server Transports and Deployment Patterns](04-server-transports-and-deployment-patterns.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `mcp-core/src/main/java/io/modelcontextprotocol/client/McpClient.java`
-The `McpClient` interface in [`mcp-core/src/main/java/io/modelcontextprotocol/client/McpClient.java`](https://github.com/modelcontextprotocol/java-sdk/blob/HEAD/mcp-core/src/main/java/io/modelcontextprotocol/client/McpClient.java) handles a key part of this chapter's functionality:
+The `follows` class in [`mcp-core/src/main/java/io/modelcontextprotocol/client/McpClient.java`](https://github.com/modelcontextprotocol/java-sdk/blob/HEAD/mcp-core/src/main/java/io/modelcontextprotocol/client/McpClient.java) handles a key part of this chapter's functionality:
```java
-import io.modelcontextprotocol.json.McpJsonDefaults;
-import io.modelcontextprotocol.json.schema.JsonSchemaValidator;
-import io.modelcontextprotocol.spec.McpClientTransport;
-import io.modelcontextprotocol.spec.McpSchema;
-import io.modelcontextprotocol.spec.McpSchema.ClientCapabilities;
-import io.modelcontextprotocol.spec.McpSchema.CreateMessageRequest;
-import io.modelcontextprotocol.spec.McpSchema.CreateMessageResult;
-import io.modelcontextprotocol.spec.McpSchema.ElicitRequest;
-import io.modelcontextprotocol.spec.McpSchema.ElicitResult;
-import io.modelcontextprotocol.spec.McpSchema.Implementation;
-import io.modelcontextprotocol.spec.McpSchema.Root;
-import io.modelcontextprotocol.spec.McpTransport;
-import io.modelcontextprotocol.util.Assert;
-import reactor.core.publisher.Mono;
-
-import java.time.Duration;
-import java.util.ArrayList;
-import java.util.HashMap;
-import java.util.List;
-import java.util.Map;
-import java.util.function.Consumer;
-import java.util.function.Function;
-import java.util.function.Supplier;
-
-/**
- * Factory class for creating Model Context Protocol (MCP) clients. MCP is a protocol that
- * enables AI models to interact with external tools and resources through a standardized
- * interface.
- *
* <p>
* This class serves as the main entry point for establishing connections with MCP
* servers, implementing the client-side of the MCP specification. The protocol follows a
+ * client-server architecture where:
+ * <ul>
+ * <li>The client (this implementation) initiates connections and sends requests
+ * <li>The server responds to requests and provides access to tools and resources
+ * <li>Communication occurs through a transport layer (e.g., stdio, SSE) using JSON-RPC
+ * 2.0
+ * </ul>
+ *
+ * <p>
+ * The class provides factory methods to create either:
+ * <ul>
+ * <li>{@link McpAsyncClient} for non-blocking operations with CompletableFuture responses
+ * <li>{@link McpSyncClient} for blocking operations with direct responses
+ * </ul>
+ *
+ * <p>
+ * Example of creating a basic synchronous client: <pre>{@code
+ * McpClient.sync(transport)
+ * .requestTimeout(Duration.ofSeconds(5))
+ * .build();
+ * }</pre>
+ *
+ * Example of creating a basic asynchronous client: <pre>{@code
+ * McpClient.async(transport)
+ * .requestTimeout(Duration.ofSeconds(5))
+ * .build();
+ * }</pre>
+ *
+ * <p>
```
-This interface is important because it defines how MCP Java SDK Tutorial: Building MCP Clients and Servers with Reactor, Servlet, and Spring implements the patterns covered in this chapter.
+This class is important because it defines how MCP Java SDK Tutorial: Building MCP Clients and Servers with Reactor, Servlet, and Spring implements the patterns covered in this chapter.
-### `mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java`
+### `mcp-core/src/main/java/io/modelcontextprotocol/client/McpClient.java`
-The `McpStatelessAsyncServer` class in [`mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java`](https://github.com/modelcontextprotocol/java-sdk/blob/HEAD/mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java) handles a key part of this chapter's functionality:
+The `SyncSpec` class in [`mcp-core/src/main/java/io/modelcontextprotocol/client/McpClient.java`](https://github.com/modelcontextprotocol/java-sdk/blob/HEAD/mcp-core/src/main/java/io/modelcontextprotocol/client/McpClient.java) handles a key part of this chapter's functionality:
```java
- * @author Dariusz Jędrzejczyk
- */
-public class McpStatelessAsyncServer {
-
- private static final Logger logger = LoggerFactory.getLogger(McpStatelessAsyncServer.class);
-
- private final McpStatelessServerTransport mcpTransportProvider;
-
- private final McpJsonMapper jsonMapper;
-
- private final McpSchema.ServerCapabilities serverCapabilities;
-
- private final McpSchema.Implementation serverInfo;
-
- private final String instructions;
-
- private final CopyOnWriteArrayList<McpStatelessServerFeatures.AsyncToolSpecification> tools = new CopyOnWriteArrayList<>();
-
- private final ConcurrentHashMap<String, McpStatelessServerFeatures.AsyncResourceTemplateSpecification> resourceTemplates = new ConcurrentHashMap<>();
-
- private final ConcurrentHashMap<String, McpStatelessServerFeatures.AsyncResourceSpecification> resources = new ConcurrentHashMap<>();
-
- private final ConcurrentHashMap<String, McpStatelessServerFeatures.AsyncPromptSpecification> prompts = new ConcurrentHashMap<>();
-
- private final ConcurrentHashMap<McpSchema.CompleteReference, McpStatelessServerFeatures.AsyncCompletionSpecification> completions = new ConcurrentHashMap<>();
-
- private List<String> protocolVersions;
-
- private McpUriTemplateManagerFactory uriTemplateManagerFactory = new DefaultMcpUriTemplateManagerFactory();
+ * @throws IllegalArgumentException if transport is null
+ */
+ static SyncSpec sync(McpClientTransport transport) {
+ return new SyncSpec(transport);
+ }
- private final JsonSchemaValidator jsonSchemaValidator;
+ /**
+ * Start building an asynchronous MCP client with the specified transport layer. The
+ * asynchronous MCP client provides non-blocking operations. Asynchronous clients
+ * return reactive primitives (Mono/Flux) immediately, allowing for concurrent
+ * operations and reactive programming patterns. The transport layer handles the
+ * low-level communication between client and server using protocols like stdio or
+ * Server-Sent Events (SSE).
+ * @param transport The transport layer implementation for MCP communication. Common
+ * implementations include {@code StdioClientTransport} for stdio-based communication
+ * and {@code SseClientTransport} for SSE-based communication.
+ * @return A new builder instance for configuring the client
+ * @throws IllegalArgumentException if transport is null
+ */
+ static AsyncSpec async(McpClientTransport transport) {
+ return new AsyncSpec(transport);
+ }
+ /**
+ * Synchronous client specification. This class follows the builder pattern to provide
+ * a fluent API for setting up clients with custom configurations.
+ *
+ * <p>
+ * The builder supports configuration of:
+ * <ul>
+ * <li>Transport layer for client-server communication
+ * <li>Request timeouts for operation boundaries
```
This class is important because it defines how MCP Java SDK Tutorial: Building MCP Clients and Servers with Reactor, Servlet, and Spring implements the patterns covered in this chapter.
-### `mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java`
+### `mcp-core/src/main/java/io/modelcontextprotocol/client/McpClient.java`
-The `StructuredOutputCallToolHandler` class in [`mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java`](https://github.com/modelcontextprotocol/java-sdk/blob/HEAD/mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java) handles a key part of this chapter's functionality:
+The `follows` class in [`mcp-core/src/main/java/io/modelcontextprotocol/client/McpClient.java`](https://github.com/modelcontextprotocol/java-sdk/blob/HEAD/mcp-core/src/main/java/io/modelcontextprotocol/client/McpClient.java) handles a key part of this chapter's functionality:
```java
- McpStatelessServerFeatures.AsyncToolSpecification toolSpecification) {
-
- if (toolSpecification.callHandler() instanceof StructuredOutputCallToolHandler) {
- // If the tool is already wrapped, return it as is
- return toolSpecification;
- }
-
- if (toolSpecification.tool().outputSchema() == null) {
- // If the tool does not have an output schema, return it as is
- return toolSpecification;
- }
-
- return new McpStatelessServerFeatures.AsyncToolSpecification(toolSpecification.tool(),
- new StructuredOutputCallToolHandler(jsonSchemaValidator, toolSpecification.tool().outputSchema(),
- toolSpecification.callHandler()));
- }
-
- private static class StructuredOutputCallToolHandler
- implements BiFunction<McpTransportContext, McpSchema.CallToolRequest, Mono<McpSchema.CallToolResult>> {
-
- private final BiFunction<McpTransportContext, McpSchema.CallToolRequest, Mono<McpSchema.CallToolResult>> delegateHandler;
-
- private final JsonSchemaValidator jsonSchemaValidator;
-
- private final Map<String, Object> outputSchema;
-
- public StructuredOutputCallToolHandler(JsonSchemaValidator jsonSchemaValidator,
- Map<String, Object> outputSchema,
- BiFunction<McpTransportContext, McpSchema.CallToolRequest, Mono<McpSchema.CallToolResult>> delegateHandler) {
-
- Assert.notNull(jsonSchemaValidator, "JsonSchemaValidator must not be null");
- Assert.notNull(delegateHandler, "Delegate call tool result handler must not be null");
+ * <p>
+ * This class serves as the main entry point for establishing connections with MCP
+ * servers, implementing the client-side of the MCP specification. The protocol follows a
+ * client-server architecture where:
+ * <ul>
+ * <li>The client (this implementation) initiates connections and sends requests
+ * <li>The server responds to requests and provides access to tools and resources
+ * <li>Communication occurs through a transport layer (e.g., stdio, SSE) using JSON-RPC
+ * 2.0
+ * </ul>
+ *
+ * <p>
+ * The class provides factory methods to create either:
+ * <ul>
+ * <li>{@link McpAsyncClient} for non-blocking operations with CompletableFuture responses
+ * <li>{@link McpSyncClient} for blocking operations with direct responses
+ * </ul>
+ *
+ * <p>
+ * Example of creating a basic synchronous client: <pre>{@code
+ * McpClient.sync(transport)
+ * .requestTimeout(Duration.ofSeconds(5))
+ * .build();
+ * }</pre>
+ *
+ * Example of creating a basic asynchronous client: <pre>{@code
+ * McpClient.async(transport)
+ * .requestTimeout(Duration.ofSeconds(5))
+ * .build();
+ * }</pre>
+ *
+ * <p>
```
This class is important because it defines how MCP Java SDK Tutorial: Building MCP Clients and Servers with Reactor, Servlet, and Spring implements the patterns covered in this chapter.
-### `mcp-core/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java`
+### `mcp-core/src/main/java/io/modelcontextprotocol/client/McpClient.java`
-The `McpAsyncClient` class in [`mcp-core/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java`](https://github.com/modelcontextprotocol/java-sdk/blob/HEAD/mcp-core/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java) handles a key part of this chapter's functionality:
+The `AsyncSpec` class in [`mcp-core/src/main/java/io/modelcontextprotocol/client/McpClient.java`](https://github.com/modelcontextprotocol/java-sdk/blob/HEAD/mcp-core/src/main/java/io/modelcontextprotocol/client/McpClient.java) handles a key part of this chapter's functionality:
```java
- * @see McpClientTransport
- */
-public class McpAsyncClient {
-
- private static final Logger logger = LoggerFactory.getLogger(McpAsyncClient.class);
-
- private static final TypeRef<Void> VOID_TYPE_REFERENCE = new TypeRef<>() {
- };
-
- public static final TypeRef<Object> OBJECT_TYPE_REF = new TypeRef<>() {
- };
-
- public static final TypeRef<PaginatedRequest> PAGINATED_REQUEST_TYPE_REF = new TypeRef<>() {
- };
+ * @throws IllegalArgumentException if transport is null
+ */
+ static AsyncSpec async(McpClientTransport transport) {
+ return new AsyncSpec(transport);
+ }
- public static final TypeRef<McpSchema.InitializeResult> INITIALIZE_RESULT_TYPE_REF = new TypeRef<>() {
- };
+ /**
+ * Synchronous client specification. This class follows the builder pattern to provide
+ * a fluent API for setting up clients with custom configurations.
+ *
+ * <p>
+ * The builder supports configuration of:
+ * <ul>
+ * <li>Transport layer for client-server communication
+ * <li>Request timeouts for operation boundaries
+ * <li>Client capabilities for feature negotiation
+ * <li>Client implementation details for version tracking
+ * <li>Root URIs for resource access
+ * <li>Change notification handlers for tools, resources, and prompts
+ * <li>Custom message sampling logic
+ * </ul>
+ */
+ class SyncSpec {
- public static final TypeRef<CreateMessageRequest> CREATE_MESSAGE_REQUEST_TYPE_REF = new TypeRef<>() {
- };
+ private final McpClientTransport transport;
- public static final TypeRef<LoggingMessageNotification> LOGGING_MESSAGE_NOTIFICATION_TYPE_REF = new TypeRef<>() {
- };
+ private Duration requestTimeout = Duration.ofSeconds(20); // Default timeout
- public static final TypeRef<McpSchema.ProgressNotification> PROGRESS_NOTIFICATION_TYPE_REF = new TypeRef<>() {
- };
+ private Duration initializationTimeout = Duration.ofSeconds(20);
- public static final String NEGOTIATED_PROTOCOL_VERSION = "io.modelcontextprotocol.client.negotiated-protocol-version";
+ private ClientCapabilities capabilities;
- /**
- * Client capabilities.
- */
```
This class is important because it defines how MCP Java SDK Tutorial: Building MCP Clients and Servers with Reactor, Servlet, and Spring implements the patterns covered in this chapter.
@@ -214,11 +212,11 @@ This class is important because it defines how MCP Java SDK Tutorial: Building M
```mermaid
flowchart TD
- A[McpClient]
- B[McpStatelessAsyncServer]
- C[StructuredOutputCallToolHandler]
- D[McpAsyncClient]
- E[McpServerFeatures]
+ A[follows]
+ B[SyncSpec]
+ C[follows]
+ D[AsyncSpec]
+ E[McpClient]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-java-sdk-tutorial/04-server-transports-and-deployment-patterns.md b/tutorials/mcp-java-sdk-tutorial/04-server-transports-and-deployment-patterns.md
index 0588cd1a..649591de 100644
--- a/tutorials/mcp-java-sdk-tutorial/04-server-transports-and-deployment-patterns.md
+++ b/tutorials/mcp-java-sdk-tutorial/04-server-transports-and-deployment-patterns.md
@@ -40,47 +40,45 @@ You now have deployment-level transport guidance for selecting the right Java ru
Next: [Chapter 5: Tools, Resources, Prompts, and Schema Validation](05-tools-resources-prompts-and-schema-validation.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `mcp-core/src/main/java/io/modelcontextprotocol/server/McpServerFeatures.java`
+### `mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java`
-The `Builder` class in [`mcp-core/src/main/java/io/modelcontextprotocol/server/McpServerFeatures.java`](https://github.com/modelcontextprotocol/java-sdk/blob/HEAD/mcp-core/src/main/java/io/modelcontextprotocol/server/McpServerFeatures.java) handles a key part of this chapter's functionality:
+The `StructuredOutputCallToolHandler` class in [`mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java`](https://github.com/modelcontextprotocol/java-sdk/blob/HEAD/mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessAsyncServer.java) handles a key part of this chapter's functionality:
```java
+ McpStatelessServerFeatures.AsyncToolSpecification toolSpecification) {
+
+ if (toolSpecification.callHandler() instanceof StructuredOutputCallToolHandler) {
+ // If the tool is already wrapped, return it as is
+ return toolSpecification;
+ }
+
+ if (toolSpecification.tool().outputSchema() == null) {
+ // If the tool does not have an output schema, return it as is
+ return toolSpecification;
+ }
+
+ return new McpStatelessServerFeatures.AsyncToolSpecification(toolSpecification.tool(),
+ new StructuredOutputCallToolHandler(jsonSchemaValidator, toolSpecification.tool().outputSchema(),
+ toolSpecification.callHandler()));
+ }
+
+ private static class StructuredOutputCallToolHandler
+ implements BiFunction<McpTransportContext, McpSchema.CallToolRequest, Mono<McpSchema.CallToolResult>> {
+
+ private final BiFunction<McpTransportContext, McpSchema.CallToolRequest, Mono<McpSchema.CallToolResult>> delegateHandler;
+
+ private final JsonSchemaValidator jsonSchemaValidator;
+
+ private final Map<String, Object> outputSchema;
- /**
- * Builder for creating AsyncToolSpecification instances.
- */
- public static class Builder {
-
- private McpSchema.Tool tool;
-
- private BiFunction<McpAsyncServerExchange, McpSchema.CallToolRequest, Mono<McpSchema.CallToolResult>> callHandler;
-
- /**
- * Sets the tool definition.
- * @param tool The tool definition including name, description, and parameter
- * schema
- * @return this builder instance
- */
- public Builder tool(McpSchema.Tool tool) {
- this.tool = tool;
- return this;
- }
-
- /**
- * Sets the call tool handler function.
- * @param callHandler The function that implements the tool's logic
- * @return this builder instance
- */
- public Builder callHandler(
- BiFunction<McpAsyncServerExchange, McpSchema.CallToolRequest, Mono<McpSchema.CallToolResult>> callHandler) {
- this.callHandler = callHandler;
- return this;
- }
+ public StructuredOutputCallToolHandler(JsonSchemaValidator jsonSchemaValidator,
+ Map<String, Object> outputSchema,
+ BiFunction<McpTransportContext, McpSchema.CallToolRequest, Mono<McpSchema.CallToolResult>> delegateHandler) {
+ Assert.notNull(jsonSchemaValidator, "JsonSchemaValidator must not be null");
+ Assert.notNull(delegateHandler, "Delegate call tool result handler must not be null");
```
This class is important because it defines how MCP Java SDK Tutorial: Building MCP Clients and Servers with Reactor, Servlet, and Spring implements the patterns covered in this chapter.
@@ -213,11 +211,11 @@ This class is important because it defines how MCP Java SDK Tutorial: Building M
```mermaid
flowchart TD
- A[Builder]
+ A[StructuredOutputCallToolHandler]
B[delegates]
C[converts]
D[McpSyncServer]
- E[provides]
+ E[LifecycleInitializer]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-java-sdk-tutorial/05-tools-resources-prompts-and-schema-validation.md b/tutorials/mcp-java-sdk-tutorial/05-tools-resources-prompts-and-schema-validation.md
index e512ccdb..c659c711 100644
--- a/tutorials/mcp-java-sdk-tutorial/05-tools-resources-prompts-and-schema-validation.md
+++ b/tutorials/mcp-java-sdk-tutorial/05-tools-resources-prompts-and-schema-validation.md
@@ -39,15 +39,104 @@ You now have a quality model for Java MCP primitives that improves interoperabil
Next: [Chapter 6: Security, Authorization, and Runtime Controls](06-security-authorization-and-runtime-controls.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
+### `mcp-core/src/main/java/io/modelcontextprotocol/client/LifecycleInitializer.java`
+
+The `Initialization` interface in [`mcp-core/src/main/java/io/modelcontextprotocol/client/LifecycleInitializer.java`](https://github.com/modelcontextprotocol/java-sdk/blob/HEAD/mcp-core/src/main/java/io/modelcontextprotocol/client/LifecycleInitializer.java) handles a key part of this chapter's functionality:
+
+```java
+ * </ul>
+ *
+ * <b>Client Initialization Process</b>
+ * <p>
+ * The client MUST initiate this phase by sending an initialize request containing:
+ * <ul>
+ * <li>Protocol version supported</li>
+ * <li>Client capabilities</li>
+ * <li>Client implementation information</li>
+ * </ul>
+ *
+ * <p>
+ * After successful initialization, the client MUST send an initialized notification to
+ * indicate it is ready to begin normal operations.
+ *
+ * <b>Server Response</b>
+ * <p>
+ * The server MUST respond with its own capabilities and information.
+ *
+ * <b>Protocol Version Negotiation</b>
+ * <p>
+ * In the initialize request, the client MUST send a protocol version it supports. This
+ * SHOULD be the latest version supported by the client.
+ *
+ * <p>
+ * If the server supports the requested protocol version, it MUST respond with the same
+ * version. Otherwise, the server MUST respond with another protocol version it supports.
+ * This SHOULD be the latest version supported by the server.
+ *
+ * <p>
+ * If the client does not support the version in the server's response, it SHOULD
+ * disconnect.
+```
+
+This interface is important because it defines how MCP Java SDK Tutorial: Building MCP Clients and Servers with Reactor, Servlet, and Spring implements the patterns covered in this chapter.
+
### `mcp-core/src/main/java/io/modelcontextprotocol/client/McpClientFeatures.java`
-The `McpClientFeatures` class in [`mcp-core/src/main/java/io/modelcontextprotocol/client/McpClientFeatures.java`](https://github.com/modelcontextprotocol/java-sdk/blob/HEAD/mcp-core/src/main/java/io/modelcontextprotocol/client/McpClientFeatures.java) handles a key part of this chapter's functionality:
+The `provides` class in [`mcp-core/src/main/java/io/modelcontextprotocol/client/McpClientFeatures.java`](https://github.com/modelcontextprotocol/java-sdk/blob/HEAD/mcp-core/src/main/java/io/modelcontextprotocol/client/McpClientFeatures.java) handles a key part of this chapter's functionality:
+
+```java
+/**
+ * Representation of features and capabilities for Model Context Protocol (MCP) clients.
+ * This class provides two record types for managing client features:
+ * <ul>
+ * <li>{@link Async} for non-blocking operations with Project Reactor's Mono responses
+ * <li>{@link Sync} for blocking operations with direct responses
+ * </ul>
+ *
+ * <p>
+ * Each feature specification includes:
+ * <ul>
+ * <li>Client implementation information and capabilities
+ * <li>Root URI mappings for resource access
+ * <li>Change notification handlers for tools, resources, and prompts
+ * <li>Logging message consumers
+ * <li>Message sampling handlers for request processing
+ * </ul>
+ *
+ * <p>
+ * The class supports conversion between synchronous and asynchronous specifications
+ * through the {@link Async#fromSync} method, which ensures proper handling of blocking
+ * operations in non-blocking contexts by scheduling them on a bounded elastic scheduler.
+ *
+ * @author Dariusz Jędrzejczyk
+ * @see McpClient
+ * @see McpSchema.Implementation
+ * @see McpSchema.ClientCapabilities
+ */
+class McpClientFeatures {
+
+ /**
+ * Asynchronous client features specification providing the capabilities and request
+```
+
+This class is important because it defines how MCP Java SDK Tutorial: Building MCP Clients and Servers with Reactor, Servlet, and Spring implements the patterns covered in this chapter.
+
+### `mcp-core/src/main/java/io/modelcontextprotocol/client/McpClientFeatures.java`
+
+The `supports` class in [`mcp-core/src/main/java/io/modelcontextprotocol/client/McpClientFeatures.java`](https://github.com/modelcontextprotocol/java-sdk/blob/HEAD/mcp-core/src/main/java/io/modelcontextprotocol/client/McpClientFeatures.java) handles a key part of this chapter's functionality:
```java
+ *
+ * <p>
+ * The class supports conversion between synchronous and asynchronous specifications
+ * through the {@link Async#fromSync} method, which ensures proper handling of blocking
+ * operations in non-blocking contexts by scheduling them on a bounded elastic scheduler.
+ *
+ * @author Dariusz Jędrzejczyk
+ * @see McpClient
+ * @see McpSchema.Implementation
* @see McpSchema.ClientCapabilities
*/
class McpClientFeatures {
@@ -71,152 +160,61 @@ class McpClientFeatures {
record Async(McpSchema.Implementation clientInfo, McpSchema.ClientCapabilities clientCapabilities,
Map<String, McpSchema.Root> roots, List<Function<List<McpSchema.Tool>, Mono<Void>>> toolsChangeConsumers,
List<Function<List<McpSchema.Resource>, Mono<Void>>> resourcesChangeConsumers,
- List<Function<List<McpSchema.ResourceContents>, Mono<Void>>> resourcesUpdateConsumers,
- List<Function<List<McpSchema.Prompt>, Mono<Void>>> promptsChangeConsumers,
- List<Function<McpSchema.LoggingMessageNotification, Mono<Void>>> loggingConsumers,
- List<Function<McpSchema.ProgressNotification, Mono<Void>>> progressConsumers,
- Function<McpSchema.CreateMessageRequest, Mono<McpSchema.CreateMessageResult>> samplingHandler,
- Function<McpSchema.ElicitRequest, Mono<McpSchema.ElicitResult>> elicitationHandler,
- boolean enableCallToolSchemaCaching) {
-
- /**
```
This class is important because it defines how MCP Java SDK Tutorial: Building MCP Clients and Servers with Reactor, Servlet, and Spring implements the patterns covered in this chapter.
-### `mcp-core/src/main/java/io/modelcontextprotocol/client/LifecycleInitializer.java`
+### `mcp-core/src/main/java/io/modelcontextprotocol/client/McpClientFeatures.java`
-The `LifecycleInitializer` class in [`mcp-core/src/main/java/io/modelcontextprotocol/client/LifecycleInitializer.java`](https://github.com/modelcontextprotocol/java-sdk/blob/HEAD/mcp-core/src/main/java/io/modelcontextprotocol/client/LifecycleInitializer.java) handles a key part of this chapter's functionality:
+The `McpClientFeatures` class in [`mcp-core/src/main/java/io/modelcontextprotocol/client/McpClientFeatures.java`](https://github.com/modelcontextprotocol/java-sdk/blob/HEAD/mcp-core/src/main/java/io/modelcontextprotocol/client/McpClientFeatures.java) handles a key part of this chapter's functionality:
```java
- * </ul>
+ * @see McpSchema.ClientCapabilities
*/
-class LifecycleInitializer {
-
- private static final Logger logger = LoggerFactory.getLogger(LifecycleInitializer.class);
-
- /**
- * The MCP session supplier that manages bidirectional JSON-RPC communication between
- * clients and servers.
- */
- private final Function<ContextView, McpClientSession> sessionSupplier;
-
- private final McpSchema.ClientCapabilities clientCapabilities;
-
- private final McpSchema.Implementation clientInfo;
-
- private List<String> protocolVersions;
-
- private final AtomicReference<DefaultInitialization> initializationRef = new AtomicReference<>();
-
- /**
- * The max timeout to await for the client-server connection to be initialized.
- */
- private final Duration initializationTimeout;
-
- /**
- * Post-initialization hook to perform additional operations after every successful
- * initialization.
- */
- private final Function<Initialization, Mono<Void>> postInitializationHook;
-
- public LifecycleInitializer(McpSchema.ClientCapabilities clientCapabilities, McpSchema.Implementation clientInfo,
-```
-
-This class is important because it defines how MCP Java SDK Tutorial: Building MCP Clients and Servers with Reactor, Servlet, and Spring implements the patterns covered in this chapter.
-
-### `mcp-core/src/main/java/io/modelcontextprotocol/client/LifecycleInitializer.java`
-
-The `DefaultInitialization` class in [`mcp-core/src/main/java/io/modelcontextprotocol/client/LifecycleInitializer.java`](https://github.com/modelcontextprotocol/java-sdk/blob/HEAD/mcp-core/src/main/java/io/modelcontextprotocol/client/LifecycleInitializer.java) handles a key part of this chapter's functionality:
-
-```java
- private List<String> protocolVersions;
-
- private final AtomicReference<DefaultInitialization> initializationRef = new AtomicReference<>();
+class McpClientFeatures {
/**
- * The max timeout to await for the client-server connection to be initialized.
+ * Asynchronous client features specification providing the capabilities and request
+ * and notification handlers.
+ *
+ * @param clientInfo the client implementation information.
+ * @param clientCapabilities the client capabilities.
+ * @param roots the roots.
+ * @param toolsChangeConsumers the tools change consumers.
+ * @param resourcesChangeConsumers the resources change consumers.
+ * @param promptsChangeConsumers the prompts change consumers.
+ * @param loggingConsumers the logging consumers.
+ * @param progressConsumers the progress consumers.
+ * @param samplingHandler the sampling handler.
+ * @param elicitationHandler the elicitation handler.
+ * @param enableCallToolSchemaCaching whether to enable call tool schema caching.
*/
- private final Duration initializationTimeout;
+ record Async(McpSchema.Implementation clientInfo, McpSchema.ClientCapabilities clientCapabilities,
+ Map<String, McpSchema.Root> roots, List<Function<List<McpSchema.Tool>, Mono<Void>>> toolsChangeConsumers,
+ List<Function<List<McpSchema.Resource>, Mono<Void>>> resourcesChangeConsumers,
+ List<Function<List<McpSchema.ResourceContents>, Mono<Void>>> resourcesUpdateConsumers,
+ List<Function<List<McpSchema.Prompt>, Mono<Void>>> promptsChangeConsumers,
+ List<Function<McpSchema.LoggingMessageNotification, Mono<Void>>> loggingConsumers,
+ List<Function<McpSchema.ProgressNotification, Mono<Void>>> progressConsumers,
+ Function<McpSchema.CreateMessageRequest, Mono<McpSchema.CreateMessageResult>> samplingHandler,
+ Function<McpSchema.ElicitRequest, Mono<McpSchema.ElicitResult>> elicitationHandler,
+ boolean enableCallToolSchemaCaching) {
- /**
- * Post-initialization hook to perform additional operations after every successful
- * initialization.
- */
- private final Function<Initialization, Mono<Void>> postInitializationHook;
-
- public LifecycleInitializer(McpSchema.ClientCapabilities clientCapabilities, McpSchema.Implementation clientInfo,
- List<String> protocolVersions, Duration initializationTimeout,
- Function<ContextView, McpClientSession> sessionSupplier,
- Function<Initialization, Mono<Void>> postInitializationHook) {
-
- Assert.notNull(sessionSupplier, "Session supplier must not be null");
- Assert.notNull(clientCapabilities, "Client capabilities must not be null");
- Assert.notNull(clientInfo, "Client info must not be null");
- Assert.notEmpty(protocolVersions, "Protocol versions must not be empty");
- Assert.notNull(initializationTimeout, "Initialization timeout must not be null");
- Assert.notNull(postInitializationHook, "Post-initialization hook must not be null");
-
- this.sessionSupplier = sessionSupplier;
- this.clientCapabilities = clientCapabilities;
- this.clientInfo = clientInfo;
- this.protocolVersions = Collections.unmodifiableList(new ArrayList<>(protocolVersions));
- this.initializationTimeout = initializationTimeout;
+ /**
```
This class is important because it defines how MCP Java SDK Tutorial: Building MCP Clients and Servers with Reactor, Servlet, and Spring implements the patterns covered in this chapter.
-### `mcp-core/src/main/java/io/modelcontextprotocol/client/LifecycleInitializer.java`
-
-The `Initialization` interface in [`mcp-core/src/main/java/io/modelcontextprotocol/client/LifecycleInitializer.java`](https://github.com/modelcontextprotocol/java-sdk/blob/HEAD/mcp-core/src/main/java/io/modelcontextprotocol/client/LifecycleInitializer.java) handles a key part of this chapter's functionality:
-
-```java
- * </ul>
- *
- * <b>Client Initialization Process</b>
- * <p>
- * The client MUST initiate this phase by sending an initialize request containing:
- * <ul>
- * <li>Protocol version supported</li>
- * <li>Client capabilities</li>
- * <li>Client implementation information</li>
- * </ul>
- *
- * <p>
- * After successful initialization, the client MUST send an initialized notification to
- * indicate it is ready to begin normal operations.
- *
- * <b>Server Response</b>
- * <p>
- * The server MUST respond with its own capabilities and information.
- *
- * <b>Protocol Version Negotiation</b>
- * <p>
- * In the initialize request, the client MUST send a protocol version it supports. This
- * SHOULD be the latest version supported by the client.
- *
- * <p>
- * If the server supports the requested protocol version, it MUST respond with the same
- * version. Otherwise, the server MUST respond with another protocol version it supports.
- * This SHOULD be the latest version supported by the server.
- *
- * <p>
- * If the client does not support the version in the server's response, it SHOULD
- * disconnect.
-```
-
-This interface is important because it defines how MCP Java SDK Tutorial: Building MCP Clients and Servers with Reactor, Servlet, and Spring implements the patterns covered in this chapter.
-
## How These Components Connect
```mermaid
flowchart TD
- A[McpClientFeatures]
- B[LifecycleInitializer]
- C[DefaultInitialization]
- D[Initialization]
- E[McpAsyncServerExchange]
+ A[Initialization]
+ B[provides]
+ C[supports]
+ D[McpClientFeatures]
+ E[provides]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-java-sdk-tutorial/06-security-authorization-and-runtime-controls.md b/tutorials/mcp-java-sdk-tutorial/06-security-authorization-and-runtime-controls.md
index 31dea93e..29ae4aef 100644
--- a/tutorials/mcp-java-sdk-tutorial/06-security-authorization-and-runtime-controls.md
+++ b/tutorials/mcp-java-sdk-tutorial/06-security-authorization-and-runtime-controls.md
@@ -40,170 +40,168 @@ You now have a security baseline for Java MCP services that is compatible with f
Next: [Chapter 7: Conformance Testing and Quality Workflows](07-conformance-testing-and-quality-workflows.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `mcp-core/src/main/java/io/modelcontextprotocol/util/KeepAliveScheduler.java`
+### `mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessSyncServer.java`
-The `for` class in [`mcp-core/src/main/java/io/modelcontextprotocol/util/KeepAliveScheduler.java`](https://github.com/modelcontextprotocol/java-sdk/blob/HEAD/mcp-core/src/main/java/io/modelcontextprotocol/util/KeepAliveScheduler.java) handles a key part of this chapter's functionality:
+The `McpStatelessSyncServer` class in [`mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessSyncServer.java`](https://github.com/modelcontextprotocol/java-sdk/blob/HEAD/mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessSyncServer.java) handles a key part of this chapter's functionality:
```java
-
-/**
- * A utility class for scheduling regular keep-alive calls to maintain connections. It
- * sends periodic keep-alive, ping, messages to connected mcp clients to prevent idle
- * timeouts.
- *
- * The pings are sent to all active mcp sessions at regular intervals.
- *
- * @author Christian Tzolov
+ * @author Dariusz Jędrzejczyk
*/
-public class KeepAliveScheduler {
+public class McpStatelessSyncServer {
- private static final Logger logger = LoggerFactory.getLogger(KeepAliveScheduler.class);
+ private static final Logger logger = LoggerFactory.getLogger(McpStatelessSyncServer.class);
- private static final TypeRef<Object> OBJECT_TYPE_REF = new TypeRef<>() {
- };
+ private final McpStatelessAsyncServer asyncServer;
- /** Initial delay before the first keepAlive call */
- private final Duration initialDelay;
+ private final boolean immediateExecution;
- /** Interval between subsequent keepAlive calls */
- private final Duration interval;
-
- /** The scheduler used for executing keepAlive calls */
- private final Scheduler scheduler;
+ McpStatelessSyncServer(McpStatelessAsyncServer asyncServer, boolean immediateExecution) {
+ this.asyncServer = asyncServer;
+ this.immediateExecution = immediateExecution;
+ }
- /** The current state of the scheduler */
- private final AtomicBoolean isRunning = new AtomicBoolean(false);
+ /**
+ * Get the server capabilities that define the supported features and functionality.
+ * @return The server capabilities
+ */
+ public McpSchema.ServerCapabilities getServerCapabilities() {
+ return this.asyncServer.getServerCapabilities();
+ }
- /** The current subscription for the keepAlive calls */
- private Disposable currentSubscription;
+ /**
+ * Get the server implementation information.
+ * @return The server implementation details
+ */
+ public McpSchema.Implementation getServerInfo() {
+ return this.asyncServer.getServerInfo();
+ }
+ /**
```
This class is important because it defines how MCP Java SDK Tutorial: Building MCP Clients and Servers with Reactor, Servlet, and Spring implements the patterns covered in this chapter.
-### `mcp-core/src/main/java/io/modelcontextprotocol/util/KeepAliveScheduler.java`
+### `mcp-core/src/main/java/io/modelcontextprotocol/client/McpSyncClient.java`
-The `KeepAliveScheduler` class in [`mcp-core/src/main/java/io/modelcontextprotocol/util/KeepAliveScheduler.java`](https://github.com/modelcontextprotocol/java-sdk/blob/HEAD/mcp-core/src/main/java/io/modelcontextprotocol/util/KeepAliveScheduler.java) handles a key part of this chapter's functionality:
+The `McpSyncClient` class in [`mcp-core/src/main/java/io/modelcontextprotocol/client/McpSyncClient.java`](https://github.com/modelcontextprotocol/java-sdk/blob/HEAD/mcp-core/src/main/java/io/modelcontextprotocol/client/McpSyncClient.java) handles a key part of this chapter's functionality:
```java
- * @author Christian Tzolov
+ * @see McpSchema
*/
-public class KeepAliveScheduler {
-
- private static final Logger logger = LoggerFactory.getLogger(KeepAliveScheduler.class);
-
- private static final TypeRef<Object> OBJECT_TYPE_REF = new TypeRef<>() {
- };
+public class McpSyncClient implements AutoCloseable {
- /** Initial delay before the first keepAlive call */
- private final Duration initialDelay;
+ private static final Logger logger = LoggerFactory.getLogger(McpSyncClient.class);
- /** Interval between subsequent keepAlive calls */
- private final Duration interval;
+ // TODO: Consider providing a client config to set this properly
+ // this is currently a concern only because AutoCloseable is used - perhaps it
+ // is not a requirement?
+ private static final long DEFAULT_CLOSE_TIMEOUT_MS = 10_000L;
- /** The scheduler used for executing keepAlive calls */
- private final Scheduler scheduler;
+ private final McpAsyncClient delegate;
- /** The current state of the scheduler */
- private final AtomicBoolean isRunning = new AtomicBoolean(false);
+ private final Supplier<McpTransportContext> contextProvider;
- /** The current subscription for the keepAlive calls */
- private Disposable currentSubscription;
-
- // TODO Currently we do not support the streams (streamable http session created by
- // http post/get)
-
- /** Supplier for reactive McpSession instances */
- private final Supplier<Flux<McpSession>> mcpSessions;
+ /**
+ * Create a new McpSyncClient with the given delegate.
+ * @param delegate the asynchronous kernel on top of which this synchronous client
+ * provides a blocking API.
+ * @param contextProvider the supplier of context before calling any non-blocking
+ * operation on underlying delegate
+ */
+ McpSyncClient(McpAsyncClient delegate, Supplier<McpTransportContext> contextProvider) {
+ Assert.notNull(delegate, "The delegate can not be null");
+ Assert.notNull(contextProvider, "The contextProvider can not be null");
+ this.delegate = delegate;
+ this.contextProvider = contextProvider;
+ }
/**
- * Creates a KeepAliveScheduler with a custom scheduler, initial delay, interval and a
+ * Get the current initialization result.
+ * @return the initialization result.
```
This class is important because it defines how MCP Java SDK Tutorial: Building MCP Clients and Servers with Reactor, Servlet, and Spring implements the patterns covered in this chapter.
-### `mcp-core/src/main/java/io/modelcontextprotocol/util/KeepAliveScheduler.java`
+### `mcp-core/src/main/java/io/modelcontextprotocol/server/McpSyncServerExchange.java`
-The `for` class in [`mcp-core/src/main/java/io/modelcontextprotocol/util/KeepAliveScheduler.java`](https://github.com/modelcontextprotocol/java-sdk/blob/HEAD/mcp-core/src/main/java/io/modelcontextprotocol/util/KeepAliveScheduler.java) handles a key part of this chapter's functionality:
+The `McpSyncServerExchange` class in [`mcp-core/src/main/java/io/modelcontextprotocol/server/McpSyncServerExchange.java`](https://github.com/modelcontextprotocol/java-sdk/blob/HEAD/mcp-core/src/main/java/io/modelcontextprotocol/server/McpSyncServerExchange.java) handles a key part of this chapter's functionality:
```java
-
-/**
- * A utility class for scheduling regular keep-alive calls to maintain connections. It
- * sends periodic keep-alive, ping, messages to connected mcp clients to prevent idle
- * timeouts.
- *
- * The pings are sent to all active mcp sessions at regular intervals.
- *
* @author Christian Tzolov
*/
-public class KeepAliveScheduler {
-
- private static final Logger logger = LoggerFactory.getLogger(KeepAliveScheduler.class);
-
- private static final TypeRef<Object> OBJECT_TYPE_REF = new TypeRef<>() {
- };
+public class McpSyncServerExchange {
- /** Initial delay before the first keepAlive call */
- private final Duration initialDelay;
+ private final McpAsyncServerExchange exchange;
- /** Interval between subsequent keepAlive calls */
- private final Duration interval;
-
- /** The scheduler used for executing keepAlive calls */
- private final Scheduler scheduler;
+ /**
+ * Create a new synchronous exchange with the client using the provided asynchronous
+ * implementation as a delegate.
+ * @param exchange The asynchronous exchange to delegate to.
+ */
+ public McpSyncServerExchange(McpAsyncServerExchange exchange) {
+ this.exchange = exchange;
+ }
- /** The current state of the scheduler */
- private final AtomicBoolean isRunning = new AtomicBoolean(false);
+ /**
+ * Provides the Session ID
+ * @return session ID
+ */
+ public String sessionId() {
+ return this.exchange.sessionId();
+ }
- /** The current subscription for the keepAlive calls */
- private Disposable currentSubscription;
+ /**
+ * Get the client capabilities that define the supported features and functionality.
+ * @return The client capabilities
+ */
+ public McpSchema.ClientCapabilities getClientCapabilities() {
+ return this.exchange.getClientCapabilities();
+ }
+ /**
```
This class is important because it defines how MCP Java SDK Tutorial: Building MCP Clients and Servers with Reactor, Servlet, and Spring implements the patterns covered in this chapter.
-### `mcp-core/src/main/java/io/modelcontextprotocol/util/KeepAliveScheduler.java`
+### `mcp-core/src/main/java/io/modelcontextprotocol/util/Utils.java`
-The `Builder` class in [`mcp-core/src/main/java/io/modelcontextprotocol/util/KeepAliveScheduler.java`](https://github.com/modelcontextprotocol/java-sdk/blob/HEAD/mcp-core/src/main/java/io/modelcontextprotocol/util/KeepAliveScheduler.java) handles a key part of this chapter's functionality:
+The `Utils` class in [`mcp-core/src/main/java/io/modelcontextprotocol/util/Utils.java`](https://github.com/modelcontextprotocol/java-sdk/blob/HEAD/mcp-core/src/main/java/io/modelcontextprotocol/util/Utils.java) handles a key part of this chapter's functionality:
```java
+ */
+
+public final class Utils {
/**
- * Creates a new Builder instance for constructing KeepAliveScheduler.
- * @return A new Builder instance
+ * Check whether the given {@code String} contains actual <em>text</em>.
+ * <p>
+ * More specifically, this method returns {@code true} if the {@code String} is not
+ * {@code null}, its length is greater than 0, and it contains at least one
+ * non-whitespace character.
+ * @param str the {@code String} to check (may be {@code null})
+ * @return {@code true} if the {@code String} is not {@code null}, its length is
+ * greater than 0, and it does not contain whitespace only
+ * @see Character#isWhitespace
*/
- public static Builder builder(Supplier<Flux<McpSession>> mcpSessions) {
- return new Builder(mcpSessions);
+ public static boolean hasText(@Nullable String str) {
+ return (str != null && !str.isBlank());
}
/**
- * Starts regular keepAlive calls with sessions supplier.
- * @return Disposable to control the scheduled execution
+ * Return {@code true} if the supplied Collection is {@code null} or empty. Otherwise,
+ * return {@code false}.
+ * @param collection the Collection to check
+ * @return whether the given Collection is empty
*/
- public Disposable start() {
- if (this.isRunning.compareAndSet(false, true)) {
-
- this.currentSubscription = Flux.interval(this.initialDelay, this.interval, this.scheduler)
- .doOnNext(tick -> {
- this.mcpSessions.get()
- .flatMap(session -> session.sendRequest(McpSchema.METHOD_PING, null, OBJECT_TYPE_REF)
- .doOnError(e -> logger.warn("Failed to send keep-alive ping to session {}: {}", session,
- e.getMessage()))
- .onErrorComplete())
- .subscribe();
- })
- .doOnCancel(() -> this.isRunning.set(false))
- .doOnComplete(() -> this.isRunning.set(false))
- .onErrorComplete(error -> {
- logger.error("KeepAlive scheduler error", error);
- this.isRunning.set(false);
- return true;
- })
+ public static boolean isEmpty(@Nullable Collection<?> collection) {
+ return (collection == null || collection.isEmpty());
+ }
+
+ /**
+ * Return {@code true} if the supplied Map is {@code null} or empty. Otherwise, return
+ * {@code false}.
```
This class is important because it defines how MCP Java SDK Tutorial: Building MCP Clients and Servers with Reactor, Servlet, and Spring implements the patterns covered in this chapter.
@@ -213,11 +211,11 @@ This class is important because it defines how MCP Java SDK Tutorial: Building M
```mermaid
flowchart TD
- A[for]
- B[KeepAliveScheduler]
- C[for]
- D[Builder]
- E[provides]
+ A[McpStatelessSyncServer]
+ B[McpSyncClient]
+ C[McpSyncServerExchange]
+ D[Utils]
+ E[ToolNameValidator]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-java-sdk-tutorial/07-conformance-testing-and-quality-workflows.md b/tutorials/mcp-java-sdk-tutorial/07-conformance-testing-and-quality-workflows.md
index d1e94005..527f5183 100644
--- a/tutorials/mcp-java-sdk-tutorial/07-conformance-testing-and-quality-workflows.md
+++ b/tutorials/mcp-java-sdk-tutorial/07-conformance-testing-and-quality-workflows.md
@@ -39,129 +39,127 @@ You now have a repeatable testing process for preventing protocol regressions in
Next: [Chapter 8: Spring Integration and Upgrade Strategy](08-spring-integration-and-upgrade-strategy.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessSyncServer.java`
+### `mcp-core/src/main/java/io/modelcontextprotocol/util/Assert.java`
-The `McpStatelessSyncServer` class in [`mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessSyncServer.java`](https://github.com/modelcontextprotocol/java-sdk/blob/HEAD/mcp-core/src/main/java/io/modelcontextprotocol/server/McpStatelessSyncServer.java) handles a key part of this chapter's functionality:
+The `providing` class in [`mcp-core/src/main/java/io/modelcontextprotocol/util/Assert.java`](https://github.com/modelcontextprotocol/java-sdk/blob/HEAD/mcp-core/src/main/java/io/modelcontextprotocol/util/Assert.java) handles a key part of this chapter's functionality:
```java
- * @author Dariusz Jędrzejczyk
- */
-public class McpStatelessSyncServer {
-
- private static final Logger logger = LoggerFactory.getLogger(McpStatelessSyncServer.class);
-
- private final McpStatelessAsyncServer asyncServer;
-
- private final boolean immediateExecution;
- McpStatelessSyncServer(McpStatelessAsyncServer asyncServer, boolean immediateExecution) {
- this.asyncServer = asyncServer;
- this.immediateExecution = immediateExecution;
- }
+/**
+ * Utility class providing assertion methods for parameter validation.
+ */
+public final class Assert {
/**
- * Get the server capabilities that define the supported features and functionality.
- * @return The server capabilities
+ * Assert that the collection is not {@code null} and not empty.
+ * @param collection the collection to check
+ * @param message the exception message to use if the assertion fails
+ * @throws IllegalArgumentException if the collection is {@code null} or empty
*/
- public McpSchema.ServerCapabilities getServerCapabilities() {
- return this.asyncServer.getServerCapabilities();
+ public static void notEmpty(@Nullable Collection<?> collection, String message) {
+ if (collection == null || collection.isEmpty()) {
+ throw new IllegalArgumentException(message);
+ }
}
/**
- * Get the server implementation information.
- * @return The server implementation details
+ * Assert that an object is not {@code null}.
+ *
+ * <pre class="code">
+ * Assert.notNull(clazz, "The class must not be null");
+ * </pre>
+ * @param object the object to check
+ * @param message the exception message to use if the assertion fails
+ * @throws IllegalArgumentException if the object is {@code null}
*/
- public McpSchema.Implementation getServerInfo() {
- return this.asyncServer.getServerInfo();
- }
-
- /**
+ public static void notNull(@Nullable Object object, String message) {
+ if (object == null) {
+ throw new IllegalArgumentException(message);
+ }
```
This class is important because it defines how MCP Java SDK Tutorial: Building MCP Clients and Servers with Reactor, Servlet, and Spring implements the patterns covered in this chapter.
-### `mcp-core/src/main/java/io/modelcontextprotocol/server/McpSyncServerExchange.java`
+### `mcp-core/src/main/java/io/modelcontextprotocol/util/Assert.java`
-The `McpSyncServerExchange` class in [`mcp-core/src/main/java/io/modelcontextprotocol/server/McpSyncServerExchange.java`](https://github.com/modelcontextprotocol/java-sdk/blob/HEAD/mcp-core/src/main/java/io/modelcontextprotocol/server/McpSyncServerExchange.java) handles a key part of this chapter's functionality:
+The `Assert` class in [`mcp-core/src/main/java/io/modelcontextprotocol/util/Assert.java`](https://github.com/modelcontextprotocol/java-sdk/blob/HEAD/mcp-core/src/main/java/io/modelcontextprotocol/util/Assert.java) handles a key part of this chapter's functionality:
```java
+
+/**
+ * Assertion utility class that assists in validating arguments.
+ *
* @author Christian Tzolov
*/
-public class McpSyncServerExchange {
- private final McpAsyncServerExchange exchange;
-
- /**
- * Create a new synchronous exchange with the client using the provided asynchronous
- * implementation as a delegate.
- * @param exchange The asynchronous exchange to delegate to.
- */
- public McpSyncServerExchange(McpAsyncServerExchange exchange) {
- this.exchange = exchange;
- }
-
- /**
- * Provides the Session ID
- * @return session ID
- */
- public String sessionId() {
- return this.exchange.sessionId();
- }
+/**
+ * Utility class providing assertion methods for parameter validation.
+ */
+public final class Assert {
/**
- * Get the client capabilities that define the supported features and functionality.
- * @return The client capabilities
+ * Assert that the collection is not {@code null} and not empty.
+ * @param collection the collection to check
+ * @param message the exception message to use if the assertion fails
+ * @throws IllegalArgumentException if the collection is {@code null} or empty
*/
- public McpSchema.ClientCapabilities getClientCapabilities() {
- return this.exchange.getClientCapabilities();
+ public static void notEmpty(@Nullable Collection<?> collection, String message) {
+ if (collection == null || collection.isEmpty()) {
+ throw new IllegalArgumentException(message);
+ }
}
/**
+ * Assert that an object is not {@code null}.
+ *
+ * <pre class="code">
+ * Assert.notNull(clazz, "The class must not be null");
+ * </pre>
+ * @param object the object to check
+ * @param message the exception message to use if the assertion fails
```
This class is important because it defines how MCP Java SDK Tutorial: Building MCP Clients and Servers with Reactor, Servlet, and Spring implements the patterns covered in this chapter.
-### `mcp-core/src/main/java/io/modelcontextprotocol/util/Utils.java`
+### `mcp-core/src/main/java/io/modelcontextprotocol/util/Assert.java`
-The `Utils` class in [`mcp-core/src/main/java/io/modelcontextprotocol/util/Utils.java`](https://github.com/modelcontextprotocol/java-sdk/blob/HEAD/mcp-core/src/main/java/io/modelcontextprotocol/util/Utils.java) handles a key part of this chapter's functionality:
+The `must` class in [`mcp-core/src/main/java/io/modelcontextprotocol/util/Assert.java`](https://github.com/modelcontextprotocol/java-sdk/blob/HEAD/mcp-core/src/main/java/io/modelcontextprotocol/util/Assert.java) handles a key part of this chapter's functionality:
```java
- */
-
-public final class Utils {
-
- /**
- * Check whether the given {@code String} contains actual <em>text</em>.
- * <p>
- * More specifically, this method returns {@code true} if the {@code String} is not
- * {@code null}, its length is greater than 0, and it contains at least one
- * non-whitespace character.
- * @param str the {@code String} to check (may be {@code null})
- * @return {@code true} if the {@code String} is not {@code null}, its length is
- * greater than 0, and it does not contain whitespace only
- * @see Character#isWhitespace
+ *
+ * <pre class="code">
+ * Assert.notNull(clazz, "The class must not be null");
+ * </pre>
+ * @param object the object to check
+ * @param message the exception message to use if the assertion fails
+ * @throws IllegalArgumentException if the object is {@code null}
*/
- public static boolean hasText(@Nullable String str) {
- return (str != null && !str.isBlank());
+ public static void notNull(@Nullable Object object, String message) {
+ if (object == null) {
+ throw new IllegalArgumentException(message);
+ }
}
/**
- * Return {@code true} if the supplied Collection is {@code null} or empty. Otherwise,
- * return {@code false}.
- * @param collection the Collection to check
- * @return whether the given Collection is empty
+ * Assert that the given String contains valid text content; that is, it must not be
+ * {@code null} and must contain at least one non-whitespace character.
+ * <pre class="code">Assert.hasText(name, "'name' must not be empty");</pre>
+ * @param text the String to check
+ * @param message the exception message to use if the assertion fails
+ * @throws IllegalArgumentException if the text does not contain valid text content
*/
- public static boolean isEmpty(@Nullable Collection<?> collection) {
- return (collection == null || collection.isEmpty());
+ public static void hasText(@Nullable String text, String message) {
+ if (!hasText(text)) {
+ throw new IllegalArgumentException(message);
+ }
}
/**
- * Return {@code true} if the supplied Map is {@code null} or empty. Otherwise, return
- * {@code false}.
+ * Check whether the given {@code String} contains actual <em>text</em>.
+ * <p>
+ * More specifically, this method returns {@code true} if the {@code String} is not
```
This class is important because it defines how MCP Java SDK Tutorial: Building MCP Clients and Servers with Reactor, Servlet, and Spring implements the patterns covered in this chapter.
@@ -212,9 +210,9 @@ This class is important because it defines how MCP Java SDK Tutorial: Building M
```mermaid
flowchart TD
- A[McpStatelessSyncServer]
- B[McpSyncServerExchange]
- C[Utils]
+ A[providing]
+ B[Assert]
+ C[must]
D[is]
E[is]
A --> B
diff --git a/tutorials/mcp-java-sdk-tutorial/08-spring-integration-and-upgrade-strategy.md b/tutorials/mcp-java-sdk-tutorial/08-spring-integration-and-upgrade-strategy.md
index 992d718e..30b19738 100644
--- a/tutorials/mcp-java-sdk-tutorial/08-spring-integration-and-upgrade-strategy.md
+++ b/tutorials/mcp-java-sdk-tutorial/08-spring-integration-and-upgrade-strategy.md
@@ -40,8 +40,6 @@ You now have a long-term operations model for combining Java core MCP and Spring
Next: Continue with [MCP C# SDK Tutorial](../mcp-csharp-sdk-tutorial/)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `mcp-core/src/main/java/io/modelcontextprotocol/json/McpJsonDefaults.java`
@@ -85,125 +83,125 @@ public class McpJsonDefaults {
This class is important because it defines how MCP Java SDK Tutorial: Building MCP Clients and Servers with Reactor, Servlet, and Spring implements the patterns covered in this chapter.
-### `mcp-core/src/main/java/io/modelcontextprotocol/util/Assert.java`
+### `mcp-core/src/main/java/io/modelcontextprotocol/json/McpJsonMapper.java`
-The `that` class in [`mcp-core/src/main/java/io/modelcontextprotocol/util/Assert.java`](https://github.com/modelcontextprotocol/java-sdk/blob/HEAD/mcp-core/src/main/java/io/modelcontextprotocol/util/Assert.java) handles a key part of this chapter's functionality:
+The `McpJsonMapper` interface in [`mcp-core/src/main/java/io/modelcontextprotocol/json/McpJsonMapper.java`](https://github.com/modelcontextprotocol/java-sdk/blob/HEAD/mcp-core/src/main/java/io/modelcontextprotocol/json/McpJsonMapper.java) handles a key part of this chapter's functionality:
```java
-
-/**
- * Assertion utility class that assists in validating arguments.
- *
- * @author Christian Tzolov
+ * io.modelcontextprotocol.spec.json.jackson.JacksonJsonMapper.
*/
+public interface McpJsonMapper {
-/**
- * Utility class providing assertion methods for parameter validation.
- */
-public final class Assert {
+ /**
+ * Deserialize JSON string into a target type.
+ * @param content JSON as String
+ * @param type target class
+ * @return deserialized instance
+ * @param <T> generic type
+ * @throws IOException on parse errors
+ */
+ <T> T readValue(String content, Class<T> type) throws IOException;
/**
- * Assert that the collection is not {@code null} and not empty.
- * @param collection the collection to check
- * @param message the exception message to use if the assertion fails
- * @throws IllegalArgumentException if the collection is {@code null} or empty
+ * Deserialize JSON bytes into a target type.
+ * @param content JSON as bytes
+ * @param type target class
+ * @return deserialized instance
+ * @param <T> generic type
+ * @throws IOException on parse errors
*/
- public static void notEmpty(@Nullable Collection<?> collection, String message) {
- if (collection == null || collection.isEmpty()) {
- throw new IllegalArgumentException(message);
- }
- }
+ <T> T readValue(byte[] content, Class<T> type) throws IOException;
/**
- * Assert that an object is not {@code null}.
- *
- * <pre class="code">
- * Assert.notNull(clazz, "The class must not be null");
- * </pre>
- * @param object the object to check
- * @param message the exception message to use if the assertion fails
+ * Deserialize JSON string into a parameterized target type.
+ * @param content JSON as String
+ * @param type parameterized type reference
+ * @return deserialized instance
+ * @param <T> generic type
+ * @throws IOException on parse errors
+ */
```
-This class is important because it defines how MCP Java SDK Tutorial: Building MCP Clients and Servers with Reactor, Servlet, and Spring implements the patterns covered in this chapter.
+This interface is important because it defines how MCP Java SDK Tutorial: Building MCP Clients and Servers with Reactor, Servlet, and Spring implements the patterns covered in this chapter.
-### `mcp-core/src/main/java/io/modelcontextprotocol/util/Assert.java`
+### `mcp-core/src/main/java/io/modelcontextprotocol/server/DefaultMcpStatelessServerHandler.java`
-The `providing` class in [`mcp-core/src/main/java/io/modelcontextprotocol/util/Assert.java`](https://github.com/modelcontextprotocol/java-sdk/blob/HEAD/mcp-core/src/main/java/io/modelcontextprotocol/util/Assert.java) handles a key part of this chapter's functionality:
+The `DefaultMcpStatelessServerHandler` class in [`mcp-core/src/main/java/io/modelcontextprotocol/server/DefaultMcpStatelessServerHandler.java`](https://github.com/modelcontextprotocol/java-sdk/blob/HEAD/mcp-core/src/main/java/io/modelcontextprotocol/server/DefaultMcpStatelessServerHandler.java) handles a key part of this chapter's functionality:
```java
+import java.util.Map;
-/**
- * Utility class providing assertion methods for parameter validation.
- */
-public final class Assert {
+class DefaultMcpStatelessServerHandler implements McpStatelessServerHandler {
- /**
- * Assert that the collection is not {@code null} and not empty.
- * @param collection the collection to check
- * @param message the exception message to use if the assertion fails
- * @throws IllegalArgumentException if the collection is {@code null} or empty
- */
- public static void notEmpty(@Nullable Collection<?> collection, String message) {
- if (collection == null || collection.isEmpty()) {
- throw new IllegalArgumentException(message);
- }
+ private static final Logger logger = LoggerFactory.getLogger(DefaultMcpStatelessServerHandler.class);
+
+ Map<String, McpStatelessRequestHandler<?>> requestHandlers;
+
+ Map<String, McpStatelessNotificationHandler> notificationHandlers;
+
+ public DefaultMcpStatelessServerHandler(Map<String, McpStatelessRequestHandler<?>> requestHandlers,
+ Map<String, McpStatelessNotificationHandler> notificationHandlers) {
+ this.requestHandlers = requestHandlers;
+ this.notificationHandlers = notificationHandlers;
}
- /**
- * Assert that an object is not {@code null}.
- *
- * <pre class="code">
- * Assert.notNull(clazz, "The class must not be null");
- * </pre>
- * @param object the object to check
- * @param message the exception message to use if the assertion fails
- * @throws IllegalArgumentException if the object is {@code null}
- */
- public static void notNull(@Nullable Object object, String message) {
- if (object == null) {
- throw new IllegalArgumentException(message);
+ @Override
+ public Mono<McpSchema.JSONRPCResponse> handleRequest(McpTransportContext transportContext,
+ McpSchema.JSONRPCRequest request) {
+ McpStatelessRequestHandler<?> requestHandler = this.requestHandlers.get(request.method());
+ if (requestHandler == null) {
+ return Mono.error(McpError.builder(McpSchema.ErrorCodes.METHOD_NOT_FOUND)
+ .message("Missing handler for request type: " + request.method())
+ .build());
}
+ return requestHandler.handle(transportContext, request.params())
+ .map(result -> new McpSchema.JSONRPCResponse(McpSchema.JSONRPC_VERSION, request.id(), result, null))
+ .onErrorResume(t -> {
+ McpSchema.JSONRPCResponse.JSONRPCError error;
+ if (t instanceof McpError mcpError && mcpError.getJsonRpcError() != null) {
+ error = mcpError.getJsonRpcError();
+ }
```
This class is important because it defines how MCP Java SDK Tutorial: Building MCP Clients and Servers with Reactor, Servlet, and Spring implements the patterns covered in this chapter.
-### `mcp-core/src/main/java/io/modelcontextprotocol/util/Assert.java`
+### `mcp-core/src/main/java/io/modelcontextprotocol/util/McpServiceLoader.java`
-The `Assert` class in [`mcp-core/src/main/java/io/modelcontextprotocol/util/Assert.java`](https://github.com/modelcontextprotocol/java-sdk/blob/HEAD/mcp-core/src/main/java/io/modelcontextprotocol/util/Assert.java) handles a key part of this chapter's functionality:
+The `are` class in [`mcp-core/src/main/java/io/modelcontextprotocol/util/McpServiceLoader.java`](https://github.com/modelcontextprotocol/java-sdk/blob/HEAD/mcp-core/src/main/java/io/modelcontextprotocol/util/McpServiceLoader.java) handles a key part of this chapter's functionality:
```java
/**
- * Assertion utility class that assists in validating arguments.
+ * Instance of this class are intended to be used differently in OSGi and non-OSGi
+ * environments. In all non-OSGi environments the supplier member will be
+ * <code>null</code> and the serviceLoad method will be called to use the
+ * ServiceLoader.load to find the first instance of the supplier (assuming one is present
+ * in the runtime), cache it, and call the supplier's get method.
+ * <p>
+ * In OSGi environments, the Service component runtime (scr) will call the setSupplier
+ * method upon bundle activation (assuming one is present in the runtime), and subsequent
+ * calls will use the given supplier instance rather than the ServiceLoader.load.
*
- * @author Christian Tzolov
+ * @param <S> the type of the supplier
+ * @param <R> the type of the supplier result/returned value
*/
+public class McpServiceLoader<S extends Supplier<R>, R> {
-/**
- * Utility class providing assertion methods for parameter validation.
- */
-public final class Assert {
+ private Class<S> supplierType;
- /**
- * Assert that the collection is not {@code null} and not empty.
- * @param collection the collection to check
- * @param message the exception message to use if the assertion fails
- * @throws IllegalArgumentException if the collection is {@code null} or empty
- */
- public static void notEmpty(@Nullable Collection<?> collection, String message) {
- if (collection == null || collection.isEmpty()) {
- throw new IllegalArgumentException(message);
- }
+ private S supplier;
+
+ private R supplierResult;
+
+ public void setSupplier(S supplier) {
+ this.supplier = supplier;
+ this.supplierResult = null;
}
- /**
- * Assert that an object is not {@code null}.
- *
- * <pre class="code">
- * Assert.notNull(clazz, "The class must not be null");
- * </pre>
- * @param object the object to check
- * @param message the exception message to use if the assertion fails
+ public void unsetSupplier(S supplier) {
+ this.supplier = null;
+ this.supplierResult = null;
+ }
```
This class is important because it defines how MCP Java SDK Tutorial: Building MCP Clients and Servers with Reactor, Servlet, and Spring implements the patterns covered in this chapter.
@@ -214,10 +212,10 @@ This class is important because it defines how MCP Java SDK Tutorial: Building M
```mermaid
flowchart TD
A[McpJsonDefaults]
- B[that]
- C[providing]
- D[Assert]
- E[must]
+ B[McpJsonMapper]
+ C[DefaultMcpStatelessServerHandler]
+ D[are]
+ E[McpServiceLoader]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-kotlin-sdk-tutorial/01-getting-started-and-module-selection.md b/tutorials/mcp-kotlin-sdk-tutorial/01-getting-started-and-module-selection.md
index 98236067..6ed64c91 100644
--- a/tutorials/mcp-kotlin-sdk-tutorial/01-getting-started-and-module-selection.md
+++ b/tutorials/mcp-kotlin-sdk-tutorial/01-getting-started-and-module-selection.md
@@ -47,114 +47,112 @@ You now have a stable Kotlin baseline and module selection model.
Next: [Chapter 2: Core Protocol Model and Module Architecture](02-core-protocol-model-and-module-architecture.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/ExperimentalMcpApi.kt`
+### `kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/InternalMcpApi.kt`
-The `ExperimentalMcpApi` class in [`kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/ExperimentalMcpApi.kt`](https://github.com/modelcontextprotocol/kotlin-sdk/blob/HEAD/kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/ExperimentalMcpApi.kt) handles a key part of this chapter's functionality:
+The `InternalMcpApi` class in [`kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/InternalMcpApi.kt`](https://github.com/modelcontextprotocol/kotlin-sdk/blob/HEAD/kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/InternalMcpApi.kt) handles a key part of this chapter's functionality:
```kt
)
@Retention(AnnotationRetention.BINARY)
-public annotation class ExperimentalMcpApi
+public annotation class InternalMcpApi
```
This class is important because it defines how MCP Kotlin SDK Tutorial: Building Multiplatform MCP Clients and Servers implements the patterns covered in this chapter.
-### `kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/InternalMcpApi.kt`
+### `kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/ExperimentalMcpApi.kt`
-The `InternalMcpApi` class in [`kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/InternalMcpApi.kt`](https://github.com/modelcontextprotocol/kotlin-sdk/blob/HEAD/kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/InternalMcpApi.kt) handles a key part of this chapter's functionality:
+The `ExperimentalMcpApi` class in [`kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/ExperimentalMcpApi.kt`](https://github.com/modelcontextprotocol/kotlin-sdk/blob/HEAD/kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/ExperimentalMcpApi.kt) handles a key part of this chapter's functionality:
```kt
)
@Retention(AnnotationRetention.BINARY)
-public annotation class InternalMcpApi
+public annotation class ExperimentalMcpApi
```
This class is important because it defines how MCP Kotlin SDK Tutorial: Building Multiplatform MCP Clients and Servers implements the patterns covered in this chapter.
-### `kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/shared/Protocol.kt`
+### `kotlin-sdk-server/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/StreamableHttpServerTransport.kt`
-The `ProtocolOptions` class in [`kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/shared/Protocol.kt`](https://github.com/modelcontextprotocol/kotlin-sdk/blob/HEAD/kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/shared/Protocol.kt) handles a key part of this chapter's functionality:
+The `SessionContext` class in [`kotlin-sdk-server/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/StreamableHttpServerTransport.kt`](https://github.com/modelcontextprotocol/kotlin-sdk/blob/HEAD/kotlin-sdk-server/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/StreamableHttpServerTransport.kt) handles a key part of this chapter's functionality:
```kt
- * Additional initialization options.
+ * Otherwise, the session is not null.
*/
-public open class ProtocolOptions(
- /**
- * Whether to restrict emitted requests to only those that the remote side has indicated
- * that they can handle, through their advertised capabilities.
- *
- * Note that this DOES NOT affect checking of _local_ side capabilities, as it is
- * considered a logic error to mis-specify those.
- *
- * Currently, this defaults to false, for backwards compatibility with SDK versions
- * that did not advertise capabilities correctly.
- * In the future, this will default to true.
- */
- public var enforceStrictCapabilities: Boolean = false,
-
- public var timeout: Duration = DEFAULT_REQUEST_TIMEOUT,
-)
+private data class SessionContext(val session: ServerSSESession?, val call: ApplicationCall)
/**
- * The default request timeout.
+ * Server transport for Streamable HTTP: this implements the MCP Streamable HTTP transport specification.
+ * It supports both SSE streaming and direct HTTP responses.
+ *
+ * In stateful mode:
+ * - Session ID is generated and included in response headers
+ * - Session ID is always included in initialization responses
+ * - Requests with invalid session IDs are rejected with 404 Not Found
+ * - Non-initialization requests without a session ID are rejected with 400 Bad Request
+ * - State is maintained in-memory (connections, message history)
+ *
+ * In stateless mode:
+ * - No Session ID is included in any responses
+ * - No session validation is performed
+ *
+ * @param configuration Transport configuration. See [Configuration] for available options.
+ * @property sessionId session identifier assigned after initialization, or `null` in stateless mode
*/
-public val DEFAULT_REQUEST_TIMEOUT: Duration = 60.seconds
+@OptIn(ExperimentalUuidApi::class, ExperimentalAtomicApi::class)
+@Suppress("TooManyFunctions")
+public class StreamableHttpServerTransport(private val configuration: Configuration) : AbstractTransport() {
-/**
- * Options that can be given per request.
- *
- * @property relatedRequestId if present,
- * `relatedRequestId` is used to indicate to the transport which incoming request to associate this outgoing message with.
- * @property resumptionToken the resumption token used to continue long-running requests that were interrupted.
- * This allows clients to reconnect and continue from where they left off, if supported by the transport.
- * @property onResumptionToken a callback that is invoked when the resumption token changes, if supported by the transport.
+ @Deprecated("Use default constructor with explicit Configuration()")
+ public constructor() : this(configuration = Configuration())
+
+ /**
+ * Secondary constructor for `StreamableHttpServerTransport` that simplifies initialization by directly taking the
+ * configurable parameters without requiring a `Configuration` instance.
```
This class is important because it defines how MCP Kotlin SDK Tutorial: Building Multiplatform MCP Clients and Servers implements the patterns covered in this chapter.
-### `kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/shared/Protocol.kt`
+### `kotlin-sdk-server/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/StreamableHttpServerTransport.kt`
-The `RequestOptions` class in [`kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/shared/Protocol.kt`](https://github.com/modelcontextprotocol/kotlin-sdk/blob/HEAD/kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/shared/Protocol.kt) handles a key part of this chapter's functionality:
+The `StreamableHttpServerTransport` class in [`kotlin-sdk-server/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/StreamableHttpServerTransport.kt`](https://github.com/modelcontextprotocol/kotlin-sdk/blob/HEAD/kotlin-sdk-server/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/StreamableHttpServerTransport.kt) handles a key part of this chapter's functionality:
```kt
- * If not specified, `DEFAULT_REQUEST_TIMEOUT` will be used as the timeout.
+/**
+ * A holder for an active request call.
+ * If [StreamableHttpServerTransport.Configuration.enableJsonResponse] is true, the session is null.
+ * Otherwise, the session is not null.
*/
-public class RequestOptions(
- relatedRequestId: RequestId? = null,
- resumptionToken: String? = null,
- onResumptionToken: ((String) -> Unit)? = null,
- public val onProgress: ProgressCallback? = null,
- public val timeout: Duration = DEFAULT_REQUEST_TIMEOUT,
-) : TransportSendOptions(relatedRequestId, resumptionToken, onResumptionToken) {
- public operator fun component4(): ProgressCallback? = onProgress
- public operator fun component5(): Duration = timeout
-
- public fun copy(
- relatedRequestId: RequestId? = this.relatedRequestId,
- resumptionToken: String? = this.resumptionToken,
- onResumptionToken: ((String) -> Unit)? = this.onResumptionToken,
- onProgress: ProgressCallback? = this.onProgress,
- timeout: Duration = this.timeout,
- ): RequestOptions = RequestOptions(relatedRequestId, resumptionToken, onResumptionToken, onProgress, timeout)
-
- override fun equals(other: Any?): Boolean {
- if (this === other) return true
- if (other == null || this::class != other::class) return false
- if (!super.equals(other)) return false
-
- other as RequestOptions
-
- return onProgress == other.onProgress && timeout == other.timeout
- }
-
- override fun hashCode(): Int {
- var result = super.hashCode()
+private data class SessionContext(val session: ServerSSESession?, val call: ApplicationCall)
+
+/**
+ * Server transport for Streamable HTTP: this implements the MCP Streamable HTTP transport specification.
+ * It supports both SSE streaming and direct HTTP responses.
+ *
+ * In stateful mode:
+ * - Session ID is generated and included in response headers
+ * - Session ID is always included in initialization responses
+ * - Requests with invalid session IDs are rejected with 404 Not Found
+ * - Non-initialization requests without a session ID are rejected with 400 Bad Request
+ * - State is maintained in-memory (connections, message history)
+ *
+ * In stateless mode:
+ * - No Session ID is included in any responses
+ * - No session validation is performed
+ *
+ * @param configuration Transport configuration. See [Configuration] for available options.
+ * @property sessionId session identifier assigned after initialization, or `null` in stateless mode
+ */
+@OptIn(ExperimentalUuidApi::class, ExperimentalAtomicApi::class)
+@Suppress("TooManyFunctions")
+public class StreamableHttpServerTransport(private val configuration: Configuration) : AbstractTransport() {
+
+ @Deprecated("Use default constructor with explicit Configuration()")
+ public constructor() : this(configuration = Configuration())
+
```
This class is important because it defines how MCP Kotlin SDK Tutorial: Building Multiplatform MCP Clients and Servers implements the patterns covered in this chapter.
@@ -164,11 +162,11 @@ This class is important because it defines how MCP Kotlin SDK Tutorial: Building
```mermaid
flowchart TD
- A[ExperimentalMcpApi]
- B[InternalMcpApi]
- C[ProtocolOptions]
- D[RequestOptions]
- E[RequestHandlerExtra]
+ A[InternalMcpApi]
+ B[ExperimentalMcpApi]
+ C[SessionContext]
+ D[StreamableHttpServerTransport]
+ E[Configuration]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-kotlin-sdk-tutorial/02-core-protocol-model-and-module-architecture.md b/tutorials/mcp-kotlin-sdk-tutorial/02-core-protocol-model-and-module-architecture.md
index 304f322b..0eb7dab9 100644
--- a/tutorials/mcp-kotlin-sdk-tutorial/02-core-protocol-model-and-module-architecture.md
+++ b/tutorials/mcp-kotlin-sdk-tutorial/02-core-protocol-model-and-module-architecture.md
@@ -47,170 +47,168 @@ You now have a clear module-level mental model for Kotlin MCP architecture decis
Next: [Chapter 3: Client Runtime and Capability Negotiation](03-client-runtime-and-capability-negotiation.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `kotlin-sdk-server/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/StreamableHttpServerTransport.kt`
+### `kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/shared/Protocol.kt`
-The `StreamableHttpServerTransport` class in [`kotlin-sdk-server/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/StreamableHttpServerTransport.kt`](https://github.com/modelcontextprotocol/kotlin-sdk/blob/HEAD/kotlin-sdk-server/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/StreamableHttpServerTransport.kt) handles a key part of this chapter's functionality:
+The `RequestOptions` class in [`kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/shared/Protocol.kt`](https://github.com/modelcontextprotocol/kotlin-sdk/blob/HEAD/kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/shared/Protocol.kt) handles a key part of this chapter's functionality:
```kt
-/**
- * A holder for an active request call.
- * If [StreamableHttpServerTransport.Configuration.enableJsonResponse] is true, the session is null.
- * Otherwise, the session is not null.
- */
-private data class SessionContext(val session: ServerSSESession?, val call: ApplicationCall)
-
-/**
- * Server transport for Streamable HTTP: this implements the MCP Streamable HTTP transport specification.
- * It supports both SSE streaming and direct HTTP responses.
- *
- * In stateful mode:
- * - Session ID is generated and included in response headers
- * - Session ID is always included in initialization responses
- * - Requests with invalid session IDs are rejected with 404 Not Found
- * - Non-initialization requests without a session ID are rejected with 400 Bad Request
- * - State is maintained in-memory (connections, message history)
- *
- * In stateless mode:
- * - No Session ID is included in any responses
- * - No session validation is performed
- *
- * @param configuration Transport configuration. See [Configuration] for available options.
+ * If not specified, `DEFAULT_REQUEST_TIMEOUT` will be used as the timeout.
*/
-@OptIn(ExperimentalUuidApi::class, ExperimentalAtomicApi::class)
-@Suppress("TooManyFunctions")
-public class StreamableHttpServerTransport(private val configuration: Configuration) : AbstractTransport() {
-
- @Deprecated("Use default constructor with explicit Configuration()")
- public constructor() : this(configuration = Configuration())
-
- /**
+public class RequestOptions(
+ relatedRequestId: RequestId? = null,
+ resumptionToken: String? = null,
+ onResumptionToken: ((String) -> Unit)? = null,
+ public val onProgress: ProgressCallback? = null,
+ public val timeout: Duration = DEFAULT_REQUEST_TIMEOUT,
+) : TransportSendOptions(relatedRequestId, resumptionToken, onResumptionToken) {
+ /** Destructuring component for [onProgress]. */
+ public operator fun component4(): ProgressCallback? = onProgress
+
+ /** Destructuring component for [timeout]. */
+ public operator fun component5(): Duration = timeout
+
+ /** Creates a copy of this [RequestOptions] with the specified fields replaced. */
+ public fun copy(
+ relatedRequestId: RequestId? = this.relatedRequestId,
+ resumptionToken: String? = this.resumptionToken,
+ onResumptionToken: ((String) -> Unit)? = this.onResumptionToken,
+ onProgress: ProgressCallback? = this.onProgress,
+ timeout: Duration = this.timeout,
+ ): RequestOptions = RequestOptions(relatedRequestId, resumptionToken, onResumptionToken, onProgress, timeout)
+
+ override fun equals(other: Any?): Boolean {
+ if (this === other) return true
+ if (other == null || this::class != other::class) return false
+ if (!super.equals(other)) return false
+
+ other as RequestOptions
+
+ return onProgress == other.onProgress && timeout == other.timeout
```
This class is important because it defines how MCP Kotlin SDK Tutorial: Building Multiplatform MCP Clients and Servers implements the patterns covered in this chapter.
-### `kotlin-sdk-server/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/StreamableHttpServerTransport.kt`
+### `kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/shared/Protocol.kt`
-The `Configuration` class in [`kotlin-sdk-server/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/StreamableHttpServerTransport.kt`](https://github.com/modelcontextprotocol/kotlin-sdk/blob/HEAD/kotlin-sdk-server/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/StreamableHttpServerTransport.kt) handles a key part of this chapter's functionality:
+The `RequestHandlerExtra` class in [`kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/shared/Protocol.kt`](https://github.com/modelcontextprotocol/kotlin-sdk/blob/HEAD/kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/shared/Protocol.kt) handles a key part of this chapter's functionality:
```kt
-/**
- * A holder for an active request call.
- * If [StreamableHttpServerTransport.Configuration.enableJsonResponse] is true, the session is null.
- * Otherwise, the session is not null.
+ * Extra data given to request handlers.
*/
-private data class SessionContext(val session: ServerSSESession?, val call: ApplicationCall)
+public class RequestHandlerExtra
+
+internal val COMPLETED = CompletableDeferred(Unit).also { it.complete(Unit) }
/**
- * Server transport for Streamable HTTP: this implements the MCP Streamable HTTP transport specification.
- * It supports both SSE streaming and direct HTTP responses.
- *
- * In stateful mode:
- * - Session ID is generated and included in response headers
- * - Session ID is always included in initialization responses
- * - Requests with invalid session IDs are rejected with 404 Not Found
- * - Non-initialization requests without a session ID are rejected with 400 Bad Request
- * - State is maintained in-memory (connections, message history)
- *
- * In stateless mode:
- * - No Session ID is included in any responses
- * - No session validation is performed
+ * Implements MCP protocol framing on top of a pluggable transport, including
+ * features like request/response linking, notifications, and progress.
*
- * @param configuration Transport configuration. See [Configuration] for available options.
+ * @property transport the active transport, or `null` if not connected
+ * @property requestHandlers registered request handlers keyed by method name
+ * @property notificationHandlers registered notification handlers keyed by method name
+ * @property responseHandlers pending response handlers keyed by request ID
+ * @property progressHandlers registered progress callbacks keyed by progress token
*/
-@OptIn(ExperimentalUuidApi::class, ExperimentalAtomicApi::class)
-@Suppress("TooManyFunctions")
-public class StreamableHttpServerTransport(private val configuration: Configuration) : AbstractTransport() {
+public abstract class Protocol(@PublishedApi internal val options: ProtocolOptions?) {
+ public var transport: Transport? = null
+ private set
+
+ private val _requestHandlers:
+ AtomicRef<PersistentMap<String, suspend (JSONRPCRequest, RequestHandlerExtra) -> RequestResult?>> =
+ atomic(persistentMapOf())
+ public val requestHandlers: Map<
+ String,
+ suspend (
+ request: JSONRPCRequest,
+ extra: RequestHandlerExtra,
+ ) -> RequestResult?,
+ >
+ get() = _requestHandlers.value
- @Deprecated("Use default constructor with explicit Configuration()")
- public constructor() : this(configuration = Configuration())
-
- /**
```
This class is important because it defines how MCP Kotlin SDK Tutorial: Building Multiplatform MCP Clients and Servers implements the patterns covered in this chapter.
-### `kotlin-sdk-server/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/Server.kt`
+### `kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/shared/Protocol.kt`
-The `ServerOptions` class in [`kotlin-sdk-server/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/Server.kt`](https://github.com/modelcontextprotocol/kotlin-sdk/blob/HEAD/kotlin-sdk-server/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/Server.kt) handles a key part of this chapter's functionality:
+The `Protocol` class in [`kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/shared/Protocol.kt`](https://github.com/modelcontextprotocol/kotlin-sdk/blob/HEAD/kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/shared/Protocol.kt) handles a key part of this chapter's functionality:
```kt
- * for matching resource URIs against registered templates. Defaults to [PathSegmentTemplateMatcher.factory].
+ * @property timeout default timeout for outgoing requests
*/
-public class ServerOptions(
- public val capabilities: ServerCapabilities,
- enforceStrictCapabilities: Boolean = true,
- public val resourceTemplateMatcherFactory: ResourceTemplateMatcherFactory = PathSegmentTemplateMatcher.factory,
-) : ProtocolOptions(enforceStrictCapabilities = enforceStrictCapabilities) {
- @JvmOverloads
- public constructor(
- capabilities: ServerCapabilities,
- enforceStrictCapabilities: Boolean = true,
- ) : this(capabilities, enforceStrictCapabilities, PathSegmentTemplateMatcher.factory)
-}
+public open class ProtocolOptions(
+ /**
+ * Whether to restrict emitted requests to only those that the remote side has indicated
+ * that they can handle, through their advertised capabilities.
+ *
+ * Note that this DOES NOT affect checking of _local_ side capabilities, as it is
+ * considered a logic error to mis-specify those.
+ *
+ * Currently, this defaults to false, for backwards compatibility with SDK versions
+ * that did not advertise capabilities correctly.
+ * In the future, this will default to true.
+ */
+ public var enforceStrictCapabilities: Boolean = false,
+
+ public var timeout: Duration = DEFAULT_REQUEST_TIMEOUT,
+)
/**
- * An MCP server is responsible for storing features and handling new connections.
- *
- * This server automatically responds to the initialization flow as initiated by the client.
- * You can register tools, prompts, and resources using [addTool], [addPrompt], and [addResource].
- * The server will then automatically handle listing and retrieval requests from the client.
- *
- * In case the server supports feature list notification or resource substitution,
- * the server will automatically send notifications for all connected clients.
- * Currently, after subscription to a resource, the server will NOT send the subscription confirmation
- * as this response schema is not defined in the protocol.
- *
- * @param serverInfo Information about this server implementation (name, version).
- * @param options Configuration options for the server.
- * @param instructionsProvider Optional provider for instructions from the server to the client about how to use
- * this server. The provider is called each time a new session is started to support dynamic instructions.
- * @param block A block to configure the mcp server.
+ * The default request timeout.
*/
+public val DEFAULT_REQUEST_TIMEOUT: Duration = 60.seconds
+
+/**
+ * Options that can be given per request.
+ *
+ * @property relatedRequestId if present,
+ * `relatedRequestId` is used to indicate to the transport which incoming request to associate this outgoing message with.
+ * @property resumptionToken the resumption token used to continue long-running requests that were interrupted.
+ * This allows clients to reconnect and continue from where they left off, if supported by the transport.
+ * @property onResumptionToken a callback that is invoked when the resumption token changes, if supported by the transport.
```
This class is important because it defines how MCP Kotlin SDK Tutorial: Building Multiplatform MCP Clients and Servers implements the patterns covered in this chapter.
-### `kotlin-sdk-server/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/Server.kt`
+### `kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/notification.kt`
-The `Server` class in [`kotlin-sdk-server/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/Server.kt`](https://github.com/modelcontextprotocol/kotlin-sdk/blob/HEAD/kotlin-sdk-server/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/Server.kt) handles a key part of this chapter's functionality:
+The `BaseNotificationParams` class in [`kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/notification.kt`](https://github.com/modelcontextprotocol/kotlin-sdk/blob/HEAD/kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/notification.kt) handles a key part of this chapter's functionality:
```kt
-import io.modelcontextprotocol.kotlin.sdk.types.ResourceTemplate
-import io.modelcontextprotocol.kotlin.sdk.types.ResourceUpdatedNotification
-import io.modelcontextprotocol.kotlin.sdk.types.ServerCapabilities
-import io.modelcontextprotocol.kotlin.sdk.types.SubscribeRequest
-import io.modelcontextprotocol.kotlin.sdk.types.TextContent
-import io.modelcontextprotocol.kotlin.sdk.types.Tool
-import io.modelcontextprotocol.kotlin.sdk.types.ToolAnnotations
-import io.modelcontextprotocol.kotlin.sdk.types.ToolExecution
-import io.modelcontextprotocol.kotlin.sdk.types.ToolSchema
-import io.modelcontextprotocol.kotlin.sdk.types.UnsubscribeRequest
-import io.modelcontextprotocol.kotlin.sdk.utils.MatchResult
-import io.modelcontextprotocol.kotlin.sdk.utils.PathSegmentTemplateMatcher
-import io.modelcontextprotocol.kotlin.sdk.utils.ResourceTemplateMatcher
-import io.modelcontextprotocol.kotlin.sdk.utils.ResourceTemplateMatcherFactory
-import kotlinx.coroutines.CancellationException
-import kotlinx.coroutines.Deferred
-import kotlinx.serialization.json.JsonObject
-import kotlinx.serialization.json.buildJsonObject
-import kotlinx.serialization.json.put
-import kotlin.jvm.JvmOverloads
-import kotlin.time.ExperimentalTime
-
-private val logger = KotlinLogging.logger {}
+ */
+@Serializable
+public data class BaseNotificationParams(@SerialName("_meta") override val meta: JsonObject? = null) :
+ NotificationParams
/**
- * Configuration options for the MCP server.
+ * Represents a progress notification.
*
- * @property capabilities The capabilities this server supports.
- * @property enforceStrictCapabilities Whether to strictly enforce capabilities when interacting with clients.
- * @property resourceTemplateMatcherFactory The factory used to create [ResourceTemplateMatcher] instances
- * for matching resource URIs against registered templates. Defaults to [PathSegmentTemplateMatcher.factory].
+ * @property progress The progress thus far. This should increase every time progress is made,
+ * even if the total is unknown.
+ * @property total Total number of items to a process (or total progress required), if known.
+ * @property message An optional message describing the current progress.
*/
+@Serializable
+public class Progress(
+ public val progress: Double,
+ public val total: Double? = null,
+ public val message: String? = null,
+)
+
+// ============================================================================
+// Custom Notification
+// ============================================================================
+
+/**
+ * Represents a custom notification method that is not part of the core MCP specification.
+ *
+ * The MCP protocol allows implementations to define custom methods for extending functionality.
+ * This class captures such custom notifications while preserving all their data.
+ *
+ * @property method The custom method name. By convention, custom methods often contain
+ * organization-specific prefixes (e.g., "mycompany/custom_event").
```
This class is important because it defines how MCP Kotlin SDK Tutorial: Building Multiplatform MCP Clients and Servers implements the patterns covered in this chapter.
@@ -220,11 +218,11 @@ This class is important because it defines how MCP Kotlin SDK Tutorial: Building
```mermaid
flowchart TD
- A[StreamableHttpServerTransport]
- B[Configuration]
- C[ServerOptions]
- D[Server]
- E[ServerSession]
+ A[RequestOptions]
+ B[RequestHandlerExtra]
+ C[Protocol]
+ D[BaseNotificationParams]
+ E[Progress]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-kotlin-sdk-tutorial/03-client-runtime-and-capability-negotiation.md b/tutorials/mcp-kotlin-sdk-tutorial/03-client-runtime-and-capability-negotiation.md
index e7b60f3d..f9e62755 100644
--- a/tutorials/mcp-kotlin-sdk-tutorial/03-client-runtime-and-capability-negotiation.md
+++ b/tutorials/mcp-kotlin-sdk-tutorial/03-client-runtime-and-capability-negotiation.md
@@ -46,170 +46,168 @@ You now know how to run capability-safe client workflows in Kotlin.
Next: [Chapter 4: Server Runtime, Primitives, and Feature Registration](04-server-runtime-primitives-and-feature-registration.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `kotlin-sdk-client/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/client/StreamableHttpClientTransport.kt`
+### `kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/notification.kt`
-The `ConnectResult` interface in [`kotlin-sdk-client/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/client/StreamableHttpClientTransport.kt`](https://github.com/modelcontextprotocol/kotlin-sdk/blob/HEAD/kotlin-sdk-client/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/client/StreamableHttpClientTransport.kt) handles a key part of this chapter's functionality:
+The `LoggingMessageNotificationParams` class in [`kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/notification.kt`](https://github.com/modelcontextprotocol/kotlin-sdk/blob/HEAD/kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/notification.kt) handles a key part of this chapter's functionality:
```kt
- Exception("Streamable HTTP error: $message")
-
-private sealed interface ConnectResult {
- data class Success(val session: ClientSSESession) : ConnectResult
- data object NonRetryable : ConnectResult
- data object Failed : ConnectResult
+ */
+@Serializable
+public data class LoggingMessageNotification(override val params: LoggingMessageNotificationParams) :
+ ServerNotification {
+ @EncodeDefault
+ override val method: Method = Method.Defined.NotificationsMessage
}
/**
- * Client transport for Streamable HTTP: this implements the MCP Streamable HTTP transport specification.
- * It will connect to a server using HTTP POST for sending messages and HTTP GET with Server-Sent Events
- * for receiving messages.
+ * Parameters for a notifications/message notification.
+ *
+ * @property level The severity of this log message.
+ * @property data The data to be logged, such as a string message or an object.
+ * Any JSON serializable type is allowed here.
+ * @property logger An optional name of the logger issuing this message.
+ * @property meta Optional metadata for this notification.
*/
-@Suppress("TooManyFunctions")
-public class StreamableHttpClientTransport(
- private val client: HttpClient,
- private val url: String,
- private val reconnectionOptions: ReconnectionOptions = ReconnectionOptions(),
- private val requestBuilder: HttpRequestBuilder.() -> Unit = {},
-) : AbstractClientTransport() {
-
- @Deprecated(
- "Use constructor with ReconnectionOptions",
- replaceWith = ReplaceWith(
- "StreamableHttpClientTransport(client, url, " +
- "ReconnectionOptions(initialReconnectionDelay = reconnectionTime ?: 1.seconds), requestBuilder)",
- "kotlin.time.Duration.Companion.seconds",
- "io.modelcontextprotocol.kotlin.sdk.client.ReconnectionOptions",
- ),
- )
- public constructor(
- client: HttpClient,
+@Serializable
+public data class LoggingMessageNotificationParams(
+ val level: LoggingLevel,
+ val data: JsonElement,
+ val logger: String? = null,
+ @SerialName("_meta")
+ override val meta: JsonObject? = null,
+) : NotificationParams
+
+// ============================================================================
+// Progress Notification
+// ============================================================================
+
+/**
+ * An out-of-band notification used to inform the receiver of a progress update for a long-running request.
```
-This interface is important because it defines how MCP Kotlin SDK Tutorial: Building Multiplatform MCP Clients and Servers implements the patterns covered in this chapter.
+This class is important because it defines how MCP Kotlin SDK Tutorial: Building Multiplatform MCP Clients and Servers implements the patterns covered in this chapter.
-### `kotlin-sdk-server/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/FeatureNotificationService.kt`
+### `kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/notification.kt`
-The `NotificationEvent` class in [`kotlin-sdk-server/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/FeatureNotificationService.kt`](https://github.com/modelcontextprotocol/kotlin-sdk/blob/HEAD/kotlin-sdk-server/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/FeatureNotificationService.kt) handles a key part of this chapter's functionality:
+The `ProgressNotification` class in [`kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/notification.kt`](https://github.com/modelcontextprotocol/kotlin-sdk/blob/HEAD/kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/notification.kt) handles a key part of this chapter's functionality:
```kt
- * @property timestamp A timestamp for the event.
- */
-private sealed class NotificationEvent(open val timestamp: Long)
-
-/**
- * Represents an event for a notification.
- *
- * @property notification The notification associated with the event.
*/
-private class SendEvent(override val timestamp: Long, val notification: Notification) : NotificationEvent(timestamp)
-
-/** Represents an event marking the end of notification processing. */
-private class EndEvent(override val timestamp: Long) : NotificationEvent(timestamp)
+@Serializable
+public data class ProgressNotification(override val params: ProgressNotificationParams) :
+ ClientNotification,
+ ServerNotification {
+ @EncodeDefault
+ override val method: Method = Method.Defined.NotificationsProgress
+}
/**
- * Represents a job that handles session-specific notifications, processing events
- * and delivering relevant notifications to the associated session.
+ * Parameters for a notifications/progress notification.
*
- * This class listens to a stream of notification events and processes them
- * based on the event type and the resource subscriptions associated with the session.
- * It allows subscribing to or unsubscribing from specific resource keys for granular
- * notification handling. The job can also be canceled to stop processing further events.
- * Notification with timestamps older than the starting timestamp are skipped.
+ * @property progressToken The progress token which was given in the initial request,
+ * used to associate this notification with the request that is proceeding.
+ * @property progress The progress thus far. This should increase every time progress is made,
+ * even if the total is unknown.
+ * @property total Total number of items to process (or total progress required), if known.
+ * @property message An optional message describing the current progress.
+ * @property meta Optional metadata for this notification.
*/
-private class SessionNotificationJob {
- private val job: Job
- private val resourceSubscriptions = atomic(persistentMapOf<FeatureKey, Long>())
- private val logger = KotlinLogging.logger {}
-
- /**
- * Constructor for the SessionNotificationJob, responsible for processing notification events
- * and dispatching appropriate notifications to the provided server session. The job operates
+@Serializable
+public data class ProgressNotificationParams(
+ val progressToken: ProgressToken,
+ val progress: Double,
+ val total: Double? = null,
+ val message: String? = null,
+ @SerialName("_meta")
+ override val meta: JsonObject? = null,
+) : NotificationParams
+
+// ============================================================================
+// Prompts List Changed Notification
```
This class is important because it defines how MCP Kotlin SDK Tutorial: Building Multiplatform MCP Clients and Servers implements the patterns covered in this chapter.
-### `kotlin-sdk-server/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/FeatureNotificationService.kt`
+### `kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/notification.kt`
-The `SendEvent` class in [`kotlin-sdk-server/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/FeatureNotificationService.kt`](https://github.com/modelcontextprotocol/kotlin-sdk/blob/HEAD/kotlin-sdk-server/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/FeatureNotificationService.kt) handles a key part of this chapter's functionality:
+The `ProgressNotificationParams` class in [`kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/notification.kt`](https://github.com/modelcontextprotocol/kotlin-sdk/blob/HEAD/kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/notification.kt) handles a key part of this chapter's functionality:
```kt
- * @property notification The notification associated with the event.
*/
-private class SendEvent(override val timestamp: Long, val notification: Notification) : NotificationEvent(timestamp)
-
-/** Represents an event marking the end of notification processing. */
-private class EndEvent(override val timestamp: Long) : NotificationEvent(timestamp)
+@Serializable
+public data class ProgressNotification(override val params: ProgressNotificationParams) :
+ ClientNotification,
+ ServerNotification {
+ @EncodeDefault
+ override val method: Method = Method.Defined.NotificationsProgress
+}
/**
- * Represents a job that handles session-specific notifications, processing events
- * and delivering relevant notifications to the associated session.
+ * Parameters for a notifications/progress notification.
*
- * This class listens to a stream of notification events and processes them
- * based on the event type and the resource subscriptions associated with the session.
- * It allows subscribing to or unsubscribing from specific resource keys for granular
- * notification handling. The job can also be canceled to stop processing further events.
- * Notification with timestamps older than the starting timestamp are skipped.
+ * @property progressToken The progress token which was given in the initial request,
+ * used to associate this notification with the request that is proceeding.
+ * @property progress The progress thus far. This should increase every time progress is made,
+ * even if the total is unknown.
+ * @property total Total number of items to process (or total progress required), if known.
+ * @property message An optional message describing the current progress.
+ * @property meta Optional metadata for this notification.
*/
-private class SessionNotificationJob {
- private val job: Job
- private val resourceSubscriptions = atomic(persistentMapOf<FeatureKey, Long>())
- private val logger = KotlinLogging.logger {}
-
- /**
- * Constructor for the SessionNotificationJob, responsible for processing notification events
- * and dispatching appropriate notifications to the provided server session. The job operates
- * within the given coroutine scope and begins handling events starting from the specified
- * timestamp.
- *
- * @param session The server session where notifications will be dispatched.
- * @param scope The coroutine scope in which this job operates.
- * @param events A shared flow of notification events that the job listens to.
- * @param fromTimestamp The timestamp from which the job starts processing events.
+@Serializable
+public data class ProgressNotificationParams(
+ val progressToken: ProgressToken,
+ val progress: Double,
+ val total: Double? = null,
+ val message: String? = null,
+ @SerialName("_meta")
+ override val meta: JsonObject? = null,
+) : NotificationParams
+
+// ============================================================================
+// Prompts List Changed Notification
```
This class is important because it defines how MCP Kotlin SDK Tutorial: Building Multiplatform MCP Clients and Servers implements the patterns covered in this chapter.
-### `kotlin-sdk-server/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/FeatureNotificationService.kt`
+### `kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/notification.kt`
-The `EndEvent` class in [`kotlin-sdk-server/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/FeatureNotificationService.kt`](https://github.com/modelcontextprotocol/kotlin-sdk/blob/HEAD/kotlin-sdk-server/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/FeatureNotificationService.kt) handles a key part of this chapter's functionality:
+The `PromptListChangedNotification` class in [`kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/notification.kt`](https://github.com/modelcontextprotocol/kotlin-sdk/blob/HEAD/kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/notification.kt) handles a key part of this chapter's functionality:
```kt
+ */
+@Serializable
+public data class PromptListChangedNotification(override val params: BaseNotificationParams? = null) :
+ ServerNotification {
+ @EncodeDefault
+ override val method: Method = Method.Defined.NotificationsPromptsListChanged
+}
-/** Represents an event marking the end of notification processing. */
-private class EndEvent(override val timestamp: Long) : NotificationEvent(timestamp)
+// ============================================================================
+// Resources List Changed Notification
+// ============================================================================
/**
- * Represents a job that handles session-specific notifications, processing events
- * and delivering relevant notifications to the associated session.
+ * An optional notification from the server to the client,
+ * informing it that the list of resources it can read from has changed.
+ *
+ * Servers may issue this without any previous subscription from the client.
+ * Sent only if the server's [ServerCapabilities.resources] has `listChanged = true`.
*
- * This class listens to a stream of notification events and processes them
- * based on the event type and the resource subscriptions associated with the session.
- * It allows subscribing to or unsubscribing from specific resource keys for granular
- * notification handling. The job can also be canceled to stop processing further events.
- * Notification with timestamps older than the starting timestamp are skipped.
+ * @property params Optional notification parameters containing metadata.
*/
-private class SessionNotificationJob {
- private val job: Job
- private val resourceSubscriptions = atomic(persistentMapOf<FeatureKey, Long>())
- private val logger = KotlinLogging.logger {}
-
- /**
- * Constructor for the SessionNotificationJob, responsible for processing notification events
- * and dispatching appropriate notifications to the provided server session. The job operates
- * within the given coroutine scope and begins handling events starting from the specified
- * timestamp.
- *
- * @param session The server session where notifications will be dispatched.
- * @param scope The coroutine scope in which this job operates.
- * @param events A shared flow of notification events that the job listens to.
- * @param fromTimestamp The timestamp from which the job starts processing events.
- */
- constructor(
- session: ServerSession,
+@Serializable
+public data class ResourceListChangedNotification(override val params: BaseNotificationParams? = null) :
+ ServerNotification {
+ @EncodeDefault
+ override val method: Method = Method.Defined.NotificationsResourcesListChanged
+}
+
+// ============================================================================
+// Resource Updated Notification
+// ============================================================================
+
```
This class is important because it defines how MCP Kotlin SDK Tutorial: Building Multiplatform MCP Clients and Servers implements the patterns covered in this chapter.
@@ -219,11 +217,11 @@ This class is important because it defines how MCP Kotlin SDK Tutorial: Building
```mermaid
flowchart TD
- A[ConnectResult]
- B[NotificationEvent]
- C[SendEvent]
- D[EndEvent]
- E[listens]
+ A[LoggingMessageNotificationParams]
+ B[ProgressNotification]
+ C[ProgressNotificationParams]
+ D[PromptListChangedNotification]
+ E[ResourceListChangedNotification]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-kotlin-sdk-tutorial/04-server-runtime-primitives-and-feature-registration.md b/tutorials/mcp-kotlin-sdk-tutorial/04-server-runtime-primitives-and-feature-registration.md
index 5ccc9b00..1bf03bf9 100644
--- a/tutorials/mcp-kotlin-sdk-tutorial/04-server-runtime-primitives-and-feature-registration.md
+++ b/tutorials/mcp-kotlin-sdk-tutorial/04-server-runtime-primitives-and-feature-registration.md
@@ -47,184 +47,182 @@ You now have a server-side primitive model that is consistent with MCP capabilit
Next: [Chapter 5: Transports: stdio, Streamable HTTP, SSE, and WebSocket](05-transports-stdio-streamable-http-sse-and-websocket.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/resources.kt`
+### `kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/notification.kt`
-The `ResourceTemplateReference` class in [`kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/resources.kt`](https://github.com/modelcontextprotocol/kotlin-sdk/blob/HEAD/kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/resources.kt) handles a key part of this chapter's functionality:
+The `TaskStatusNotification` class in [`kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/notification.kt`](https://github.com/modelcontextprotocol/kotlin-sdk/blob/HEAD/kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/notification.kt) handles a key part of this chapter's functionality:
```kt
*/
@Serializable
-public data class ResourceTemplateReference(val uri: String) : Reference {
+public data class TaskStatusNotification(override val params: TaskStatusNotificationParams? = null) :
+ ClientNotification,
+ ServerNotification {
@EncodeDefault
- public override val type: ReferenceType = ReferenceType.ResourceTemplate
-}
-
-/**
- * The contents of a specific resource or sub-resource.
- *
- * @property uri The URI of this resource.
- * @property mimeType The MIME type of this resource, if known.
- * @property meta Optional metadata for this response.
- */
-@Serializable(with = ResourceContentsPolymorphicSerializer::class)
-public sealed interface ResourceContents : WithMeta {
- public val uri: String
- public val mimeType: String?
+ override val method: Method = Method.Defined.NotificationsTasksStatus
}
/**
- * Represents the text contents of a resource.
+ * Parameters for a notifications/tasks/status notification.
*
- * @property text The text of the item.
- * This must only be set if the item can actually be represented as text (not binary data).
- * @property uri The URI of this resource.
- * @property mimeType The MIME type of this resource, if known.
+ * @property taskId The task identifier.
+ * @property status Current task state.
+ * @property statusMessage Optional human-readable message describing the current task state.
+ * @property createdAt ISO 8601 timestamp when the task was created.
+ * @property lastUpdatedAt ISO 8601 timestamp when the task was last updated.
+ * @property ttl Actual retention duration from creation in milliseconds, null for unlimited.
+ * @property pollInterval Suggested polling interval in milliseconds.
+ * @property meta Optional metadata for this notification.
*/
@Serializable
-public data class TextResourceContents(
- val text: String,
- override val uri: String,
+public data class TaskStatusNotificationParams(
+ override val taskId: String,
+ override val status: TaskStatus,
+ override val statusMessage: String? = null,
+ override val createdAt: String,
+ override val lastUpdatedAt: String,
+ override val ttl: Long?,
+ override val pollInterval: Long? = null,
+ @SerialName("_meta") override val meta: JsonObject? = null,
+) : NotificationParams,
```
This class is important because it defines how MCP Kotlin SDK Tutorial: Building Multiplatform MCP Clients and Servers implements the patterns covered in this chapter.
-### `kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/resources.kt`
+### `kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/notification.kt`
-The `TextResourceContents` class in [`kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/resources.kt`](https://github.com/modelcontextprotocol/kotlin-sdk/blob/HEAD/kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/resources.kt) handles a key part of this chapter's functionality:
+The `TaskStatusNotificationParams` class in [`kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/notification.kt`](https://github.com/modelcontextprotocol/kotlin-sdk/blob/HEAD/kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/notification.kt) handles a key part of this chapter's functionality:
```kt
*/
@Serializable
-public data class TextResourceContents(
- val text: String,
- override val uri: String,
- override val mimeType: String? = null,
- @SerialName("_meta")
- override val meta: JsonObject? = null,
-) : ResourceContents
+public data class TaskStatusNotification(override val params: TaskStatusNotificationParams? = null) :
+ ClientNotification,
+ ServerNotification {
+ @EncodeDefault
+ override val method: Method = Method.Defined.NotificationsTasksStatus
+}
/**
- * The contents of a specific resource or sub-resource.
+ * Parameters for a notifications/tasks/status notification.
*
- * @property blob A base64-encoded string representing the binary data of the item.
- * @property uri The URI of this resource.
- * @property mimeType The MIME type of this resource, if known.
+ * @property taskId The task identifier.
+ * @property status Current task state.
+ * @property statusMessage Optional human-readable message describing the current task state.
+ * @property createdAt ISO 8601 timestamp when the task was created.
+ * @property lastUpdatedAt ISO 8601 timestamp when the task was last updated.
+ * @property ttl Actual retention duration from creation in milliseconds, null for unlimited.
+ * @property pollInterval Suggested polling interval in milliseconds.
+ * @property meta Optional metadata for this notification.
*/
@Serializable
-public data class BlobResourceContents(
- val blob: String,
- override val uri: String,
- override val mimeType: String? = null,
- @SerialName("_meta")
- override val meta: JsonObject? = null,
-) : ResourceContents
-
-/**
- * Represents resource contents with unknown or unspecified data.
- *
- * @property uri The URI of this resource.
- * @property mimeType The MIME type of this resource, if known.
- */
+public data class TaskStatusNotificationParams(
+ override val taskId: String,
+ override val status: TaskStatus,
+ override val statusMessage: String? = null,
+ override val createdAt: String,
+ override val lastUpdatedAt: String,
+ override val ttl: Long?,
+ override val pollInterval: Long? = null,
+ @SerialName("_meta") override val meta: JsonObject? = null,
+) : NotificationParams,
```
This class is important because it defines how MCP Kotlin SDK Tutorial: Building Multiplatform MCP Clients and Servers implements the patterns covered in this chapter.
-### `kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/resources.kt`
+### `kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/notification.kt`
-The `BlobResourceContents` class in [`kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/resources.kt`](https://github.com/modelcontextprotocol/kotlin-sdk/blob/HEAD/kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/resources.kt) handles a key part of this chapter's functionality:
+The `Notification` interface in [`kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/notification.kt`](https://github.com/modelcontextprotocol/kotlin-sdk/blob/HEAD/kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/notification.kt) handles a key part of this chapter's functionality:
```kt
+ * @property params optional notification parameters
*/
-@Serializable
-public data class BlobResourceContents(
- val blob: String,
- override val uri: String,
- override val mimeType: String? = null,
- @SerialName("_meta")
- override val meta: JsonObject? = null,
-) : ResourceContents
+@Serializable(with = NotificationPolymorphicSerializer::class)
+public sealed interface Notification {
+ public val method: Method
+ public val params: NotificationParams?
+}
/**
- * Represents resource contents with unknown or unspecified data.
- *
- * @property uri The URI of this resource.
- * @property mimeType The MIME type of this resource, if known.
+ * Represents a notification sent by the client.
*/
-@Serializable
-public data class UnknownResourceContents(
- override val uri: String,
- override val mimeType: String? = null,
- @SerialName("_meta")
- override val meta: JsonObject? = null,
-) : ResourceContents
+@Serializable(with = ClientNotificationPolymorphicSerializer::class)
+public sealed interface ClientNotification : Notification
-// ============================================================================
-// resources/list
-// ============================================================================
+/**
+ * Represents a notification sent by the server.
+ */
+@Serializable(with = ServerNotificationPolymorphicSerializer::class)
+public sealed interface ServerNotification : Notification
/**
- * Sent from the client to request a list of resources the server has.
+ * Interface for notification parameter types.
*
- * Resources are data sources that the server can provide access to, such as files,
+ * @property meta Optional metadata for the notification.
+ */
+@Serializable
+public sealed interface NotificationParams : WithMeta
+
+/**
+ * Base parameters for notifications that only contain metadata.
+ */
+@Serializable
```
-This class is important because it defines how MCP Kotlin SDK Tutorial: Building Multiplatform MCP Clients and Servers implements the patterns covered in this chapter.
+This interface is important because it defines how MCP Kotlin SDK Tutorial: Building Multiplatform MCP Clients and Servers implements the patterns covered in this chapter.
-### `kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/resources.kt`
+### `kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/notification.kt`
-The `UnknownResourceContents` class in [`kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/resources.kt`](https://github.com/modelcontextprotocol/kotlin-sdk/blob/HEAD/kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/resources.kt) handles a key part of this chapter's functionality:
+The `ClientNotification` interface in [`kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/notification.kt`](https://github.com/modelcontextprotocol/kotlin-sdk/blob/HEAD/kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/notification.kt) handles a key part of this chapter's functionality:
```kt
+ * Represents a notification sent by the client.
*/
-@Serializable
-public data class UnknownResourceContents(
- override val uri: String,
- override val mimeType: String? = null,
- @SerialName("_meta")
- override val meta: JsonObject? = null,
-) : ResourceContents
+@Serializable(with = ClientNotificationPolymorphicSerializer::class)
+public sealed interface ClientNotification : Notification
-// ============================================================================
-// resources/list
-// ============================================================================
+/**
+ * Represents a notification sent by the server.
+ */
+@Serializable(with = ServerNotificationPolymorphicSerializer::class)
+public sealed interface ServerNotification : Notification
/**
- * Sent from the client to request a list of resources the server has.
+ * Interface for notification parameter types.
*
- * Resources are data sources that the server can provide access to, such as files,
- * database entries, API responses, or other structured data.
- *
- * @property params Optional pagination parameters to control which page of results to return.
+ * @property meta Optional metadata for the notification.
*/
@Serializable
-public data class ListResourcesRequest(override val params: PaginatedRequestParams? = null) :
- ClientRequest,
- PaginatedRequest {
- @EncodeDefault
- override val method: Method = Method.Defined.ResourcesList
+public sealed interface NotificationParams : WithMeta
- /**
- * Secondary constructor for creating a [ListResourcesRequest] instance
- * using optional cursor and metadata parameters.
- *
+/**
+ * Base parameters for notifications that only contain metadata.
+ */
+@Serializable
+public data class BaseNotificationParams(@SerialName("_meta") override val meta: JsonObject? = null) :
+ NotificationParams
+
+/**
+ * Represents a progress notification.
+ *
+ * @property progress The progress thus far. This should increase every time progress is made,
+ * even if the total is unknown.
+ * @property total Total number of items to a process (or total progress required), if known.
```
-This class is important because it defines how MCP Kotlin SDK Tutorial: Building Multiplatform MCP Clients and Servers implements the patterns covered in this chapter.
+This interface is important because it defines how MCP Kotlin SDK Tutorial: Building Multiplatform MCP Clients and Servers implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[ResourceTemplateReference]
- B[TextResourceContents]
- C[BlobResourceContents]
- D[UnknownResourceContents]
- E[ListResourcesRequest]
+ A[TaskStatusNotification]
+ B[TaskStatusNotificationParams]
+ C[Notification]
+ D[ClientNotification]
+ E[ServerNotification]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-kotlin-sdk-tutorial/05-transports-stdio-streamable-http-sse-and-websocket.md b/tutorials/mcp-kotlin-sdk-tutorial/05-transports-stdio-streamable-http-sse-and-websocket.md
index 5a3e26d3..71e5e141 100644
--- a/tutorials/mcp-kotlin-sdk-tutorial/05-transports-stdio-streamable-http-sse-and-websocket.md
+++ b/tutorials/mcp-kotlin-sdk-tutorial/05-transports-stdio-streamable-http-sse-and-websocket.md
@@ -47,87 +47,85 @@ You now have a practical framework for choosing Kotlin MCP transports by workloa
Next: [Chapter 6: Advanced Client Features: Roots, Sampling, and Elicitation](06-advanced-client-features-roots-sampling-and-elicitation.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/resources.kt`
+### `kotlin-sdk-server/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/ServerSession.kt`
-The `SubscribeRequestParams` class in [`kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/resources.kt`](https://github.com/modelcontextprotocol/kotlin-sdk/blob/HEAD/kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/resources.kt) handles a key part of this chapter's functionality:
+The `ServerSession` class in [`kotlin-sdk-server/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/ServerSession.kt`](https://github.com/modelcontextprotocol/kotlin-sdk/blob/HEAD/kotlin-sdk-server/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/ServerSession.kt) handles a key part of this chapter's functionality:
```kt
*/
-@Serializable
-public data class SubscribeRequest(override val params: SubscribeRequestParams) : ClientRequest {
- @EncodeDefault
- override val method: Method = Method.Defined.ResourcesSubscribe
+@Suppress("TooManyFunctions")
+public open class ServerSession(
+ protected val serverInfo: Implementation,
+ options: ServerOptions,
+ protected val instructions: String?,
+) : Protocol(options) {
+
+ @OptIn(ExperimentalUuidApi::class)
+ public val sessionId: String = Uuid.random().toString()
+
+ private var _onInitialized: (() -> Unit) = {}
+
+ private var _onClose: () -> Unit = {}
+
+ private val _clientCapabilities: AtomicRef<ClientCapabilities?> = atomic(null)
+ private val _clientVersion: AtomicRef<Implementation?> = atomic(null)
/**
- * The URI of the resource to subscribe to.
+ * The client's reported capabilities after initialization.
*/
- public val uri: String
- get() = params.uri
+ public val clientCapabilities: ClientCapabilities? get() = _clientCapabilities.value
/**
- * Metadata for this request. May include a progressToken for out-of-band progress notifications.
+ * The client's version information after initialization.
*/
- public val meta: RequestMeta?
- get() = params.meta
-
- @Deprecated(
- message = "Use the constructor with SubscribeRequestParams property instead",
- replaceWith = ReplaceWith("ReadResourceRequest(SubscribeRequestParams(uri, meta))"),
- level = DeprecationLevel.ERROR,
- )
- public constructor(
- uri: String,
- meta: RequestMeta? = null,
- ) : this(SubscribeRequestParams(uri, meta))
-}
+ public val clientVersion: Implementation? get() = _clientVersion.value
-/**
- * Parameters for a resources/subscribe request.
- *
+ /**
+ * The capabilities supported by the server, related to the session.
+ */
+ private val serverCapabilities = options.capabilities
```
This class is important because it defines how MCP Kotlin SDK Tutorial: Building Multiplatform MCP Clients and Servers implements the patterns covered in this chapter.
### `kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/resources.kt`
-The `UnsubscribeRequest` class in [`kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/resources.kt`](https://github.com/modelcontextprotocol/kotlin-sdk/blob/HEAD/kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/resources.kt) handles a key part of this chapter's functionality:
+The `Resource` class in [`kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/resources.kt`](https://github.com/modelcontextprotocol/kotlin-sdk/blob/HEAD/kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/resources.kt) handles a key part of this chapter's functionality:
```kt
*/
@Serializable
-public data class UnsubscribeRequest(override val params: UnsubscribeRequestParams) : ClientRequest {
- @EncodeDefault
- override val method: Method = Method.Defined.ResourcesUnsubscribe
-
- /**
- * The URI of the resource to unsubscribe from.
- */
- public val uri: String
- get() = params.uri
-
- /**
- * Metadata for this request. May include a progressToken for out-of-band progress notifications.
- */
- public val meta: RequestMeta?
- get() = params.meta
-
- public constructor(
- uri: String,
- meta: RequestMeta? = null,
- ) : this(UnsubscribeRequestParams(uri, meta))
-}
+public sealed interface ResourceLike : WithMeta
/**
- * Parameters for a resources/unsubscribe request.
+ * A known resource that the server is capable of reading.
+ *
+ * Resources represent data sources such as files, database entries, API responses,
+ * or other structured data that can be read by clients.
*
- * @property uri The URI of the resource to unsubscribe from. This should match
- * a URI from a previous [SubscribeRequest].
- * @property meta Optional metadata for this request. May include a progressToken for
- * out-of-band progress notifications.
+ * @property uri The URI of this resource. Can use any protocol scheme (`file://`, `http://`, etc.).
+ * @property name The programmatic identifier for this resource.
+ * Intended for logical use and API identification. If [title] is not provided,
+ * this should be used as a fallback display name.
+ * @property description A description of what this resource represents.
+ * Clients can use this to improve the LLM's understanding of available resources.
+ * It can be thought of like a "hint" to the model.
+ * @property mimeType The MIME type of this resource, if known (e.g., "text/plain", "application/json", "image/png").
+ * @property size The size of the raw resource content in bytes
+ * (i.e., before base64 encoding or any tokenization), if known.
+ * Hosts can use this to display file sizes and estimate context window usage.
+ * @property title Optional human-readable display name for this resource.
+ * Intended for UI and end-user contexts, optimized to be easily understood
+ * even by those unfamiliar with domain-specific terminology.
+ * If not provided, [name] should be used for display purposes.
+ * @property annotations Optional annotations for the client. Provides additional metadata and hints
+ * about how to use or display this resource.
+ * @property icons Optional set of sized icons that clients can display in their user interface.
+ * Clients MUST support at least PNG and JPEG formats.
+ * Clients SHOULD also support SVG and WebP formats.
+ * @property meta Optional metadata for this resource.
*/
```
@@ -135,82 +133,82 @@ This class is important because it defines how MCP Kotlin SDK Tutorial: Building
### `kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/resources.kt`
-The `UnsubscribeRequestParams` class in [`kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/resources.kt`](https://github.com/modelcontextprotocol/kotlin-sdk/blob/HEAD/kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/resources.kt) handles a key part of this chapter's functionality:
+The `ResourceTemplate` class in [`kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/resources.kt`](https://github.com/modelcontextprotocol/kotlin-sdk/blob/HEAD/kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/resources.kt) handles a key part of this chapter's functionality:
```kt
*/
@Serializable
-public data class UnsubscribeRequest(override val params: UnsubscribeRequestParams) : ClientRequest {
- @EncodeDefault
- override val method: Method = Method.Defined.ResourcesUnsubscribe
-
- /**
- * The URI of the resource to unsubscribe from.
- */
- public val uri: String
- get() = params.uri
-
- /**
- * Metadata for this request. May include a progressToken for out-of-band progress notifications.
- */
- public val meta: RequestMeta?
- get() = params.meta
-
- public constructor(
- uri: String,
- meta: RequestMeta? = null,
- ) : this(UnsubscribeRequestParams(uri, meta))
-}
+public data class ResourceTemplate(
+ val uriTemplate: String,
+ val name: String,
+ val description: String? = null,
+ val mimeType: String? = null,
+ val title: String? = null,
+ val annotations: Annotations? = null,
+ val icons: List<Icon>? = null,
+ @SerialName("_meta")
+ override val meta: JsonObject? = null,
+) : WithMeta
/**
- * Parameters for a resources/unsubscribe request.
+ * A reference to a resource or resource template definition.
*
- * @property uri The URI of the resource to unsubscribe from. This should match
- * a URI from a previous [SubscribeRequest].
- * @property meta Optional metadata for this request. May include a progressToken for
- * out-of-band progress notifications.
+ * Used in completion requests and other contexts where a resource needs to be referenced
+ * without including its full definition. The URI can be either a specific resource URI
+ * or a URI template pattern.
+ *
+ * @property uri The URI or URI template of the resource.
+ * Can be a specific resource URI (e.g., `file:///home/user/doc.txt`)
+ * or a URI template with parameters (e.g., `file:///{path}`).
*/
+@Serializable
+public data class ResourceTemplateReference(val uri: String) : Reference {
+ @EncodeDefault
+ public override val type: ReferenceType = ReferenceType.ResourceTemplate
+}
+
+/**
```
This class is important because it defines how MCP Kotlin SDK Tutorial: Building Multiplatform MCP Clients and Servers implements the patterns covered in this chapter.
### `kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/resources.kt`
-The `ListResourceTemplatesRequest` class in [`kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/resources.kt`](https://github.com/modelcontextprotocol/kotlin-sdk/blob/HEAD/kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/resources.kt) handles a key part of this chapter's functionality:
+The `ResourceTemplateReference` class in [`kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/resources.kt`](https://github.com/modelcontextprotocol/kotlin-sdk/blob/HEAD/kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/resources.kt) handles a key part of this chapter's functionality:
```kt
*/
@Serializable
-public data class ListResourceTemplatesRequest(override val params: PaginatedRequestParams? = null) :
- ClientRequest,
- PaginatedRequest {
+public data class ResourceTemplateReference(val uri: String) : Reference {
@EncodeDefault
- override val method: Method = Method.Defined.ResourcesTemplatesList
+ public override val type: ReferenceType = ReferenceType.ResourceTemplate
+}
- /**
- * Secondary constructor for creating a [ListResourceTemplatesRequest] instance
- * using optional cursor and metadata parameters.
- *
- * This constructor simplifies the creation of the [ListResourceTemplatesRequest] by allowing a cursor
- * and metadata to be provided.
- *
- * @param cursor Optional cursor string to specify the starting point of the paginated request.
- * @param meta Optional metadata associated with the request.
- */
- @Deprecated(
- message = "Use the constructor with PaginatedRequestParams property instead",
- replaceWith = ReplaceWith("ListResourceTemplatesRequest(PaginatedRequestParams(cursor, meta))"),
- level = DeprecationLevel.ERROR,
- )
- public constructor(
- cursor: String?,
- meta: RequestMeta? = null,
- ) : this(paginatedRequestParams(cursor, meta))
+/**
+ * The contents of a specific resource or sub-resource.
+ *
+ * @property uri The URI of this resource.
+ * @property mimeType The MIME type of this resource, if known.
+ * @property meta Optional metadata for this response.
+ */
+@Serializable(with = ResourceContentsPolymorphicSerializer::class)
+public sealed interface ResourceContents : WithMeta {
+ public val uri: String
+ public val mimeType: String?
}
/**
- * The server's response to a [ListResourceTemplatesRequest] from the client.
+ * Represents the text contents of a resource.
*
+ * @property text The text of the item.
+ * This must only be set if the item can actually be represented as text (not binary data).
+ * @property uri The URI of this resource.
+ * @property mimeType The MIME type of this resource, if known.
+ */
+@Serializable
+public data class TextResourceContents(
+ val text: String,
+ override val uri: String,
```
This class is important because it defines how MCP Kotlin SDK Tutorial: Building Multiplatform MCP Clients and Servers implements the patterns covered in this chapter.
@@ -220,11 +218,11 @@ This class is important because it defines how MCP Kotlin SDK Tutorial: Building
```mermaid
flowchart TD
- A[SubscribeRequestParams]
- B[UnsubscribeRequest]
- C[UnsubscribeRequestParams]
- D[ListResourceTemplatesRequest]
- E[ListResourceTemplatesResult]
+ A[ServerSession]
+ B[Resource]
+ C[ResourceTemplate]
+ D[ResourceTemplateReference]
+ E[TextResourceContents]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-kotlin-sdk-tutorial/06-advanced-client-features-roots-sampling-and-elicitation.md b/tutorials/mcp-kotlin-sdk-tutorial/06-advanced-client-features-roots-sampling-and-elicitation.md
index b148c837..00b03aef 100644
--- a/tutorials/mcp-kotlin-sdk-tutorial/06-advanced-client-features-roots-sampling-and-elicitation.md
+++ b/tutorials/mcp-kotlin-sdk-tutorial/06-advanced-client-features-roots-sampling-and-elicitation.md
@@ -39,170 +39,168 @@ You now have a control-oriented strategy for advanced Kotlin client capabilities
Next: [Chapter 7: Testing, Conformance, and Operational Diagnostics](07-testing-conformance-and-operational-diagnostics.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/notification.kt`
+### `kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/resources.kt`
-The `Progress` class in [`kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/notification.kt`](https://github.com/modelcontextprotocol/kotlin-sdk/blob/HEAD/kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/notification.kt) handles a key part of this chapter's functionality:
+The `ReadResourceResult` class in [`kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/resources.kt`](https://github.com/modelcontextprotocol/kotlin-sdk/blob/HEAD/kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/resources.kt) handles a key part of this chapter's functionality:
```kt
*/
@Serializable
-public class Progress(
- public val progress: Double,
- public val total: Double? = null,
- public val message: String? = null,
-)
+public data class ReadResourceResult(
+ val contents: List<ResourceContents>,
+ @SerialName("_meta")
+ override val meta: JsonObject? = null,
+) : ServerResult
// ============================================================================
-// Custom Notification
+// resources/subscribe
// ============================================================================
/**
- * Represents a custom notification method that is not part of the core MCP specification.
+ * Sent from the client to request resources/updated notifications from the server
+ * whenever a particular resource changes.
*
- * The MCP protocol allows implementations to define custom methods for extending functionality.
- * This class captures such custom notifications while preserving all their data.
+ * After subscribing, the server will send [ResourceUpdatedNotification] messages
+ * whenever the subscribed resource is modified. This requires the server to support
+ * the `subscribe` capability in [ServerCapabilities.resources].
*
- * @property method The custom method name. By convention, custom methods often contain
- * organization-specific prefixes (e.g., "mycompany/custom_event").
- * @property params Raw JSON parameters for the custom notification, if present.
+ * @property params The parameters specifying which resource URI to subscribe to.
*/
@Serializable
-public data class CustomNotification(override val method: Method, override val params: BaseNotificationParams? = null) :
- ClientNotification,
- ServerNotification {
-
- public val meta: JsonObject?
- get() = params?.meta
-}
+public data class SubscribeRequest(override val params: SubscribeRequestParams) : ClientRequest {
+ @EncodeDefault
+ override val method: Method = Method.Defined.ResourcesSubscribe
-// ============================================================================
+ /**
+ * The URI of the resource to subscribe to.
+ */
+ public val uri: String
+ get() = params.uri
```
This class is important because it defines how MCP Kotlin SDK Tutorial: Building Multiplatform MCP Clients and Servers implements the patterns covered in this chapter.
-### `kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/notification.kt`
+### `kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/resources.kt`
-The `captures` class in [`kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/notification.kt`](https://github.com/modelcontextprotocol/kotlin-sdk/blob/HEAD/kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/notification.kt) handles a key part of this chapter's functionality:
+The `SubscribeRequest` class in [`kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/resources.kt`](https://github.com/modelcontextprotocol/kotlin-sdk/blob/HEAD/kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/resources.kt) handles a key part of this chapter's functionality:
```kt
- *
- * The MCP protocol allows implementations to define custom methods for extending functionality.
- * This class captures such custom notifications while preserving all their data.
- *
- * @property method The custom method name. By convention, custom methods often contain
- * organization-specific prefixes (e.g., "mycompany/custom_event").
- * @property params Raw JSON parameters for the custom notification, if present.
*/
@Serializable
-public data class CustomNotification(override val method: Method, override val params: BaseNotificationParams? = null) :
- ClientNotification,
- ServerNotification {
+public data class SubscribeRequest(override val params: SubscribeRequestParams) : ClientRequest {
+ @EncodeDefault
+ override val method: Method = Method.Defined.ResourcesSubscribe
- public val meta: JsonObject?
- get() = params?.meta
-}
+ /**
+ * The URI of the resource to subscribe to.
+ */
+ public val uri: String
+ get() = params.uri
-// ============================================================================
-// Cancelled Notification
-// ============================================================================
+ /**
+ * Metadata for this request. May include a progressToken for out-of-band progress notifications.
+ */
+ public val meta: RequestMeta?
+ get() = params.meta
+}
/**
- * This notification can be sent by either side to indicate that it is cancelling a previously-issued request.
- *
- * The request SHOULD still be in-flight, but due to communication latency,
- * it is always possible that this notification MAY arrive after the request has already finished.
- *
- * This notification indicates that the result will be unused, so any associated processing SHOULD cease.
- *
- * A client MUST NOT attempt to cancel its `initialize` request.
+ * Parameters for a resources/subscribe request.
*
- * @property params Details of the cancellation request.
+ * @property uri The URI of the resource to subscribe to. The URI can use any protocol;
+ * it is up to the server how to interpret it.
+ * @property meta Optional metadata for this request. May include a progressToken for
+ * out-of-band progress notifications.
+ */
+@Serializable
+public data class SubscribeRequestParams(
+ val uri: String,
+ @SerialName("_meta")
+ override val meta: RequestMeta? = null,
```
This class is important because it defines how MCP Kotlin SDK Tutorial: Building Multiplatform MCP Clients and Servers implements the patterns covered in this chapter.
-### `kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/notification.kt`
+### `kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/resources.kt`
-The `CustomNotification` class in [`kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/notification.kt`](https://github.com/modelcontextprotocol/kotlin-sdk/blob/HEAD/kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/notification.kt) handles a key part of this chapter's functionality:
+The `SubscribeRequestParams` class in [`kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/resources.kt`](https://github.com/modelcontextprotocol/kotlin-sdk/blob/HEAD/kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/resources.kt) handles a key part of this chapter's functionality:
```kt
*/
@Serializable
-public data class CustomNotification(override val method: Method, override val params: BaseNotificationParams? = null) :
- ClientNotification,
- ServerNotification {
+public data class SubscribeRequest(override val params: SubscribeRequestParams) : ClientRequest {
+ @EncodeDefault
+ override val method: Method = Method.Defined.ResourcesSubscribe
- public val meta: JsonObject?
- get() = params?.meta
-}
+ /**
+ * The URI of the resource to subscribe to.
+ */
+ public val uri: String
+ get() = params.uri
-// ============================================================================
-// Cancelled Notification
-// ============================================================================
+ /**
+ * Metadata for this request. May include a progressToken for out-of-band progress notifications.
+ */
+ public val meta: RequestMeta?
+ get() = params.meta
+}
/**
- * This notification can be sent by either side to indicate that it is cancelling a previously-issued request.
- *
- * The request SHOULD still be in-flight, but due to communication latency,
- * it is always possible that this notification MAY arrive after the request has already finished.
- *
- * This notification indicates that the result will be unused, so any associated processing SHOULD cease.
+ * Parameters for a resources/subscribe request.
*
- * A client MUST NOT attempt to cancel its `initialize` request.
- *
- * @property params Details of the cancellation request.
+ * @property uri The URI of the resource to subscribe to. The URI can use any protocol;
+ * it is up to the server how to interpret it.
+ * @property meta Optional metadata for this request. May include a progressToken for
+ * out-of-band progress notifications.
*/
@Serializable
-public data class CancelledNotification(override val params: CancelledNotificationParams) :
- ClientNotification,
- ServerNotification {
- @EncodeDefault
- override val method: Method = Method.Defined.NotificationsCancelled
+public data class SubscribeRequestParams(
+ val uri: String,
+ @SerialName("_meta")
+ override val meta: RequestMeta? = null,
```
This class is important because it defines how MCP Kotlin SDK Tutorial: Building Multiplatform MCP Clients and Servers implements the patterns covered in this chapter.
-### `kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/notification.kt`
+### `kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/resources.kt`
-The `CancelledNotification` class in [`kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/notification.kt`](https://github.com/modelcontextprotocol/kotlin-sdk/blob/HEAD/kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/notification.kt) handles a key part of this chapter's functionality:
+The `UnsubscribeRequest` class in [`kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/resources.kt`](https://github.com/modelcontextprotocol/kotlin-sdk/blob/HEAD/kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/resources.kt) handles a key part of this chapter's functionality:
```kt
*/
@Serializable
-public data class CancelledNotification(override val params: CancelledNotificationParams) :
- ClientNotification,
- ServerNotification {
+public data class UnsubscribeRequest(override val params: UnsubscribeRequestParams) : ClientRequest {
@EncodeDefault
- override val method: Method = Method.Defined.NotificationsCancelled
+ override val method: Method = Method.Defined.ResourcesUnsubscribe
/**
- * The ID of the request to cancel.
+ * The URI of the resource to unsubscribe from.
*/
- public val requestId: RequestId
- get() = params.requestId
+ public val uri: String
+ get() = params.uri
/**
- * A string describing the reason for the cancellation.
+ * Metadata for this request. May include a progressToken for out-of-band progress notifications.
*/
- public val reason: String?
- get() = params.reason
-
- /**
- * Metadata for this notification.
- */
- public val meta: JsonObject?
+ public val meta: RequestMeta?
get() = params.meta
+
+ public constructor(
+ uri: String,
+ meta: RequestMeta? = null,
+ ) : this(UnsubscribeRequestParams(uri, meta))
}
/**
- * Parameters for a notifications/cancelled notification.
+ * Parameters for a resources/unsubscribe request.
*
- * @property requestId The ID of the request to cancel.
- * This MUST correspond to the ID of a request previously issued in the same direction.
+ * @property uri The URI of the resource to unsubscribe from. This should match
+ * a URI from a previous [SubscribeRequest].
+ * @property meta Optional metadata for this request. May include a progressToken for
+ * out-of-band progress notifications.
+ */
```
This class is important because it defines how MCP Kotlin SDK Tutorial: Building Multiplatform MCP Clients and Servers implements the patterns covered in this chapter.
@@ -212,11 +210,11 @@ This class is important because it defines how MCP Kotlin SDK Tutorial: Building
```mermaid
flowchart TD
- A[Progress]
- B[captures]
- C[CustomNotification]
- D[CancelledNotification]
- E[CancelledNotificationParams]
+ A[ReadResourceResult]
+ B[SubscribeRequest]
+ C[SubscribeRequestParams]
+ D[UnsubscribeRequest]
+ E[UnsubscribeRequestParams]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-kotlin-sdk-tutorial/07-testing-conformance-and-operational-diagnostics.md b/tutorials/mcp-kotlin-sdk-tutorial/07-testing-conformance-and-operational-diagnostics.md
index 6ee79f47..cc5ad55c 100644
--- a/tutorials/mcp-kotlin-sdk-tutorial/07-testing-conformance-and-operational-diagnostics.md
+++ b/tutorials/mcp-kotlin-sdk-tutorial/07-testing-conformance-and-operational-diagnostics.md
@@ -40,170 +40,168 @@ You now have a repeatable validation workflow for Kotlin MCP implementations.
Next: [Chapter 8: Release Strategy and Production Rollout](08-release-strategy-and-production-rollout.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/notification.kt`
+### `kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/resources.kt`
-The `PromptListChangedNotification` class in [`kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/notification.kt`](https://github.com/modelcontextprotocol/kotlin-sdk/blob/HEAD/kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/notification.kt) handles a key part of this chapter's functionality:
+The `URIs` interface in [`kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/resources.kt`](https://github.com/modelcontextprotocol/kotlin-sdk/blob/HEAD/kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/resources.kt) handles a key part of this chapter's functionality:
```kt
- */
-@Serializable
-public data class PromptListChangedNotification(override val params: BaseNotificationParams? = null) :
- ServerNotification {
- @EncodeDefault
- override val method: Method = Method.Defined.NotificationsPromptsListChanged
-}
-
-// ============================================================================
-// Resources List Changed Notification
-// ============================================================================
-
-/**
- * An optional notification from the server to the client,
- * informing it that the list of resources it can read from has changed.
+ * where parameters are indicated with curly braces (e.g., `file:///{directory}/{filename}`).
*
- * Servers may issue this without any previous subscription from the client.
- * Sent only if the server's [ServerCapabilities.resources] has `listChanged = true`.
- *
- * @property params Optional notification parameters containing metadata.
+ * @property uriTemplate A URI template (according to RFC 6570) that can be used to construct resource URIs.
+ * Parameters are indicated with curly braces, e.g., `file:///{path}` or `db://users/{userId}`.
+ * @property name The programmatic identifier for this template.
+ * Intended for logical use and API identification. If [title] is not provided,
+ * this should be used as a fallback display name.
+ * @property description A description of what this template is for.
+ * Clients can use this to improve the LLM's understanding of available resources.
+ * It can be thought of like a "hint" to the model.
+ * @property mimeType The MIME type for all resources that match this template.
+ * This should only be included if all resources matching this template have the same type.
+ * For example, a file template might not have a MIME type since files can be of any type,
+ * but a database record template might always return JSON.
+ * @property title Optional human-readable display name for this template.
+ * Intended for UI and end-user contexts, optimized to be easily understood
+ * even by those unfamiliar with domain-specific terminology.
+ * If not provided, [name] should be used for display purposes.
+ * @property annotations Optional annotations for the client. Provides additional metadata and hints
+ * about how to use or display resources created from this template.
+ * @property icons Optional set of sized icons that clients can display in their user interface.
+ * Clients MUST support at least PNG and JPEG formats.
+ * Clients SHOULD also support SVG and WebP formats.
+ * @property meta Optional metadata for this template.
*/
@Serializable
-public data class ResourceListChangedNotification(override val params: BaseNotificationParams? = null) :
- ServerNotification {
- @EncodeDefault
- override val method: Method = Method.Defined.NotificationsResourcesListChanged
-}
-
-// ============================================================================
-// Resource Updated Notification
-// ============================================================================
-
+public data class ResourceTemplate(
+ val uriTemplate: String,
+ val name: String,
+ val description: String? = null,
+ val mimeType: String? = null,
+ val title: String? = null,
```
-This class is important because it defines how MCP Kotlin SDK Tutorial: Building Multiplatform MCP Clients and Servers implements the patterns covered in this chapter.
+This interface is important because it defines how MCP Kotlin SDK Tutorial: Building Multiplatform MCP Clients and Servers implements the patterns covered in this chapter.
-### `kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/notification.kt`
+### `kotlin-sdk-server/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/FeatureNotificationService.kt`
-The `ResourceListChangedNotification` class in [`kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/notification.kt`](https://github.com/modelcontextprotocol/kotlin-sdk/blob/HEAD/kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/notification.kt) handles a key part of this chapter's functionality:
+The `NotificationEvent` class in [`kotlin-sdk-server/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/FeatureNotificationService.kt`](https://github.com/modelcontextprotocol/kotlin-sdk/blob/HEAD/kotlin-sdk-server/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/FeatureNotificationService.kt) handles a key part of this chapter's functionality:
```kt
+ * @property timestamp A timestamp for the event.
*/
-@Serializable
-public data class ResourceListChangedNotification(override val params: BaseNotificationParams? = null) :
- ServerNotification {
- @EncodeDefault
- override val method: Method = Method.Defined.NotificationsResourcesListChanged
-}
-
-// ============================================================================
-// Resource Updated Notification
-// ============================================================================
+private sealed class NotificationEvent(open val timestamp: Long)
/**
- * A notification from the server to the client, informing it that a resource has changed and may need to be read again.
+ * Represents an event for a notification.
*
- * This should only be sent if the client previously sent a resources/subscribe request
- * and the server's [ServerCapabilities.resources] has `subscribe = true`.
- *
- * @property params Parameters identifying which resource was updated.
+ * @property notification The notification associated with the event.
*/
-@Serializable
-public data class ResourceUpdatedNotification(override val params: ResourceUpdatedNotificationParams) :
- ServerNotification {
- @EncodeDefault
- override val method: Method = Method.Defined.NotificationsResourcesUpdated
-}
+private class SendEvent(override val timestamp: Long, val notification: Notification) : NotificationEvent(timestamp)
+
+/** Represents an event marking the end of notification processing. */
+private class EndEvent(override val timestamp: Long) : NotificationEvent(timestamp)
/**
- * Parameters for a notifications/resources/updated notification.
+ * Represents a job that handles session-specific notifications, processing events
+ * and delivering relevant notifications to the associated session.
*
- * @property uri The URI of the resource that has been updated.
- * This might be a sub-resource of the one that the client actually subscribed to.
+ * This class listens to a stream of notification events and processes them
+ * based on the event type and the resource subscriptions associated with the session.
+ * It allows subscribing to or unsubscribing from specific resource keys for granular
+ * notification handling. The job can also be canceled to stop processing further events.
+ * Notification with timestamps older than the starting timestamp are skipped.
+ */
+private class SessionNotificationJob {
+ private val job: Job
+ private val resourceSubscriptions = atomic(persistentMapOf<FeatureKey, Long>())
+ private val logger = KotlinLogging.logger {}
+
+ /**
+ * Constructor for the SessionNotificationJob, responsible for processing notification events
+ * and dispatching appropriate notifications to the provided server session. The job operates
```
This class is important because it defines how MCP Kotlin SDK Tutorial: Building Multiplatform MCP Clients and Servers implements the patterns covered in this chapter.
-### `kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/notification.kt`
+### `kotlin-sdk-server/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/FeatureNotificationService.kt`
-The `ResourceUpdatedNotification` class in [`kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/notification.kt`](https://github.com/modelcontextprotocol/kotlin-sdk/blob/HEAD/kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/notification.kt) handles a key part of this chapter's functionality:
+The `SendEvent` class in [`kotlin-sdk-server/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/FeatureNotificationService.kt`](https://github.com/modelcontextprotocol/kotlin-sdk/blob/HEAD/kotlin-sdk-server/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/FeatureNotificationService.kt) handles a key part of this chapter's functionality:
```kt
+ * @property notification The notification associated with the event.
*/
-@Serializable
-public data class ResourceUpdatedNotification(override val params: ResourceUpdatedNotificationParams) :
- ServerNotification {
- @EncodeDefault
- override val method: Method = Method.Defined.NotificationsResourcesUpdated
-}
-
-/**
- * Parameters for a notifications/resources/updated notification.
- *
- * @property uri The URI of the resource that has been updated.
- * This might be a sub-resource of the one that the client actually subscribed to.
- * @property meta Optional metadata for this notification.
- */
-@Serializable
-public data class ResourceUpdatedNotificationParams(
- val uri: String,
- @SerialName("_meta")
- override val meta: JsonObject? = null,
-) : NotificationParams
+private class SendEvent(override val timestamp: Long, val notification: Notification) : NotificationEvent(timestamp)
-// ============================================================================
-// Roots List Changed Notification
-// ============================================================================
+/** Represents an event marking the end of notification processing. */
+private class EndEvent(override val timestamp: Long) : NotificationEvent(timestamp)
/**
- * A notification from the client to the server, informing it that the list of roots has changed.
+ * Represents a job that handles session-specific notifications, processing events
+ * and delivering relevant notifications to the associated session.
*
- * This notification should be sent whenever the client adds, removes, or modifies any root.
- * The server should then request an updated list of roots using the ListRootsRequest.
- * Sent only if the client's [ClientCapabilities.roots] has `listChanged = true`.
+ * This class listens to a stream of notification events and processes them
+ * based on the event type and the resource subscriptions associated with the session.
+ * It allows subscribing to or unsubscribing from specific resource keys for granular
+ * notification handling. The job can also be canceled to stop processing further events.
+ * Notification with timestamps older than the starting timestamp are skipped.
+ */
+private class SessionNotificationJob {
+ private val job: Job
+ private val resourceSubscriptions = atomic(persistentMapOf<FeatureKey, Long>())
+ private val logger = KotlinLogging.logger {}
+
+ /**
+ * Constructor for the SessionNotificationJob, responsible for processing notification events
+ * and dispatching appropriate notifications to the provided server session. The job operates
+ * within the given coroutine scope and begins handling events starting from the specified
+ * timestamp.
+ *
+ * @param session The server session where notifications will be dispatched.
+ * @param scope The coroutine scope in which this job operates.
+ * @param events A shared flow of notification events that the job listens to.
+ * @param fromTimestamp The timestamp from which the job starts processing events.
```
This class is important because it defines how MCP Kotlin SDK Tutorial: Building Multiplatform MCP Clients and Servers implements the patterns covered in this chapter.
-### `kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/notification.kt`
+### `kotlin-sdk-server/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/FeatureNotificationService.kt`
-The `ResourceUpdatedNotificationParams` class in [`kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/notification.kt`](https://github.com/modelcontextprotocol/kotlin-sdk/blob/HEAD/kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/notification.kt) handles a key part of this chapter's functionality:
+The `EndEvent` class in [`kotlin-sdk-server/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/FeatureNotificationService.kt`](https://github.com/modelcontextprotocol/kotlin-sdk/blob/HEAD/kotlin-sdk-server/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/FeatureNotificationService.kt) handles a key part of this chapter's functionality:
```kt
- */
-@Serializable
-public data class ResourceUpdatedNotification(override val params: ResourceUpdatedNotificationParams) :
- ServerNotification {
- @EncodeDefault
- override val method: Method = Method.Defined.NotificationsResourcesUpdated
-}
-/**
- * Parameters for a notifications/resources/updated notification.
- *
- * @property uri The URI of the resource that has been updated.
- * This might be a sub-resource of the one that the client actually subscribed to.
- * @property meta Optional metadata for this notification.
- */
-@Serializable
-public data class ResourceUpdatedNotificationParams(
- val uri: String,
- @SerialName("_meta")
- override val meta: JsonObject? = null,
-) : NotificationParams
-
-// ============================================================================
-// Roots List Changed Notification
-// ============================================================================
+/** Represents an event marking the end of notification processing. */
+private class EndEvent(override val timestamp: Long) : NotificationEvent(timestamp)
/**
- * A notification from the client to the server, informing it that the list of roots has changed.
+ * Represents a job that handles session-specific notifications, processing events
+ * and delivering relevant notifications to the associated session.
*
- * This notification should be sent whenever the client adds, removes, or modifies any root.
- * The server should then request an updated list of roots using the ListRootsRequest.
- * Sent only if the client's [ClientCapabilities.roots] has `listChanged = true`.
+ * This class listens to a stream of notification events and processes them
+ * based on the event type and the resource subscriptions associated with the session.
+ * It allows subscribing to or unsubscribing from specific resource keys for granular
+ * notification handling. The job can also be canceled to stop processing further events.
+ * Notification with timestamps older than the starting timestamp are skipped.
+ */
+private class SessionNotificationJob {
+ private val job: Job
+ private val resourceSubscriptions = atomic(persistentMapOf<FeatureKey, Long>())
+ private val logger = KotlinLogging.logger {}
+
+ /**
+ * Constructor for the SessionNotificationJob, responsible for processing notification events
+ * and dispatching appropriate notifications to the provided server session. The job operates
+ * within the given coroutine scope and begins handling events starting from the specified
+ * timestamp.
+ *
+ * @param session The server session where notifications will be dispatched.
+ * @param scope The coroutine scope in which this job operates.
+ * @param events A shared flow of notification events that the job listens to.
+ * @param fromTimestamp The timestamp from which the job starts processing events.
+ */
+ constructor(
+ session: ServerSession,
```
This class is important because it defines how MCP Kotlin SDK Tutorial: Building Multiplatform MCP Clients and Servers implements the patterns covered in this chapter.
@@ -213,11 +211,11 @@ This class is important because it defines how MCP Kotlin SDK Tutorial: Building
```mermaid
flowchart TD
- A[PromptListChangedNotification]
- B[ResourceListChangedNotification]
- C[ResourceUpdatedNotification]
- D[ResourceUpdatedNotificationParams]
- E[RootsListChangedNotification]
+ A[URIs]
+ B[NotificationEvent]
+ C[SendEvent]
+ D[EndEvent]
+ E[listens]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-kotlin-sdk-tutorial/08-release-strategy-and-production-rollout.md b/tutorials/mcp-kotlin-sdk-tutorial/08-release-strategy-and-production-rollout.md
index aaa27411..38f5d872 100644
--- a/tutorials/mcp-kotlin-sdk-tutorial/08-release-strategy-and-production-rollout.md
+++ b/tutorials/mcp-kotlin-sdk-tutorial/08-release-strategy-and-production-rollout.md
@@ -42,170 +42,168 @@ You now have a production rollout framework for operating Kotlin MCP systems wit
Return to the [MCP Kotlin SDK Tutorial index](README.md).
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/notification.kt`
+### `kotlin-sdk-client/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/client/StdioClientTransport.kt`
-The `ServerNotification` interface in [`kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/notification.kt`](https://github.com/modelcontextprotocol/kotlin-sdk/blob/HEAD/kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/notification.kt) handles a key part of this chapter's functionality:
+The `JsonRpc` class in [`kotlin-sdk-client/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/client/StdioClientTransport.kt`](https://github.com/modelcontextprotocol/kotlin-sdk/blob/HEAD/kotlin-sdk-client/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/client/StdioClientTransport.kt) handles a key part of this chapter's functionality:
```kt
- * Represents a notification sent by the server.
- */
-@Serializable(with = ServerNotificationPolymorphicSerializer::class)
-public sealed interface ServerNotification : Notification
-
-/**
- * Interface for notification parameter types.
- *
- * @property meta Optional metadata for the notification.
- */
-@Serializable
-public sealed interface NotificationParams : WithMeta
-
-/**
- * Base parameters for notifications that only contain metadata.
- */
-@Serializable
-public data class BaseNotificationParams(@SerialName("_meta") override val meta: JsonObject? = null) :
- NotificationParams
-
-/**
- * Represents a progress notification.
- *
- * @property progress The progress thus far. This should increase every time progress is made,
- * even if the total is unknown.
- * @property total Total number of items to a process (or total progress required), if known.
- * @property message An optional message describing the current progress.
- */
-@Serializable
-public class Progress(
- public val progress: Double,
- public val total: Double? = null,
+ do {
+ val msg = readBuffer.readMessage()
+ msg?.let { send(Event.JsonRpc(msg)) }
+ } while (msg != null)
+ }
+ }.invokeOnCompletion {
+ logger.debug(it) { "Read stdin coroutine finished." }
+ }
+
+ error?.let { source ->
+ launch(ioCoroutineContext) {
+ logger.debug { "Read stderr coroutine started." }
+ readSource(
+ stream = ProcessStream.Stderr,
+ source = source,
+ channel = this@channelFlow,
+ ) { bytes ->
+ val str = bytes.decodeToString()
+ send(Event.StderrEvent(str))
+ }
+ }
+ }
+ }
+
+ // Collect events on handlerCoroutineContext (Dispatchers.Default from parent scope)
+ // No flowOn necessary - collection runs in parent launch context
+ eventsFlow
+ .collect { event ->
+ when (event) {
+ is Event.JsonRpc -> {
+ handleJSONRPCMessage(event.message)
+ }
```
-This interface is important because it defines how MCP Kotlin SDK Tutorial: Building Multiplatform MCP Clients and Servers implements the patterns covered in this chapter.
+This class is important because it defines how MCP Kotlin SDK Tutorial: Building Multiplatform MCP Clients and Servers implements the patterns covered in this chapter.
-### `kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/notification.kt`
+### `kotlin-sdk-client/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/client/StdioClientTransport.kt`
-The `NotificationParams` interface in [`kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/notification.kt`](https://github.com/modelcontextprotocol/kotlin-sdk/blob/HEAD/kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/notification.kt) handles a key part of this chapter's functionality:
+The `StderrEvent` class in [`kotlin-sdk-client/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/client/StdioClientTransport.kt`](https://github.com/modelcontextprotocol/kotlin-sdk/blob/HEAD/kotlin-sdk-client/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/client/StdioClientTransport.kt) handles a key part of this chapter's functionality:
```kt
-public sealed interface Notification {
- public val method: Method
- public val params: NotificationParams?
-}
-
-/**
- * Represents a notification sent by the client.
- */
-@Serializable(with = ClientNotificationPolymorphicSerializer::class)
-public sealed interface ClientNotification : Notification
-
-/**
- * Represents a notification sent by the server.
- */
-@Serializable(with = ServerNotificationPolymorphicSerializer::class)
-public sealed interface ServerNotification : Notification
-
-/**
- * Interface for notification parameter types.
- *
- * @property meta Optional metadata for the notification.
- */
-@Serializable
-public sealed interface NotificationParams : WithMeta
-
-/**
- * Base parameters for notifications that only contain metadata.
- */
-@Serializable
-public data class BaseNotificationParams(@SerialName("_meta") override val meta: JsonObject? = null) :
- NotificationParams
-
+ ) { bytes ->
+ val str = bytes.decodeToString()
+ send(Event.StderrEvent(str))
+ }
+ }
+ }
+ }
+
+ // Collect events on handlerCoroutineContext (Dispatchers.Default from parent scope)
+ // No flowOn necessary - collection runs in parent launch context
+ eventsFlow
+ .collect { event ->
+ when (event) {
+ is Event.JsonRpc -> {
+ handleJSONRPCMessage(event.message)
+ }
+
+ is Event.StderrEvent -> {
+ val errorSeverity = classifyStderr(event.message)
+ when (errorSeverity) {
+ FATAL -> {
+ runCatching {
+ _onError(
+ McpException(INTERNAL_ERROR, "Message in StdErr: ${event.message}"),
+ )
+ }
+ stopProcessing("Fatal STDERR message received")
+ }
+
+ WARNING -> {
+ logger.warn { "STDERR message received: ${event.message}" }
+ }
```
-This interface is important because it defines how MCP Kotlin SDK Tutorial: Building Multiplatform MCP Clients and Servers implements the patterns covered in this chapter.
+This class is important because it defines how MCP Kotlin SDK Tutorial: Building Multiplatform MCP Clients and Servers implements the patterns covered in this chapter.
### `kotlin-sdk-client/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/client/StdioClientTransport.kt`
-The `StdioClientTransport` class in [`kotlin-sdk-client/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/client/StdioClientTransport.kt`](https://github.com/modelcontextprotocol/kotlin-sdk/blob/HEAD/kotlin-sdk-client/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/client/StdioClientTransport.kt) handles a key part of this chapter's functionality:
+The `EOFEvent` class in [`kotlin-sdk-client/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/client/StdioClientTransport.kt`](https://github.com/modelcontextprotocol/kotlin-sdk/blob/HEAD/kotlin-sdk-client/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/client/StdioClientTransport.kt) handles a key part of this chapter's functionality:
```kt
-import io.github.oshai.kotlinlogging.KLogger
-import io.github.oshai.kotlinlogging.KotlinLogging
-import io.modelcontextprotocol.kotlin.sdk.client.StdioClientTransport.StderrSeverity.DEBUG
-import io.modelcontextprotocol.kotlin.sdk.client.StdioClientTransport.StderrSeverity.FATAL
-import io.modelcontextprotocol.kotlin.sdk.client.StdioClientTransport.StderrSeverity.IGNORE
-import io.modelcontextprotocol.kotlin.sdk.client.StdioClientTransport.StderrSeverity.INFO
-import io.modelcontextprotocol.kotlin.sdk.client.StdioClientTransport.StderrSeverity.WARNING
-import io.modelcontextprotocol.kotlin.sdk.internal.IODispatcher
-import io.modelcontextprotocol.kotlin.sdk.shared.AbstractClientTransport
-import io.modelcontextprotocol.kotlin.sdk.shared.ReadBuffer
-import io.modelcontextprotocol.kotlin.sdk.shared.TransportSendOptions
-import io.modelcontextprotocol.kotlin.sdk.shared.serializeMessage
-import io.modelcontextprotocol.kotlin.sdk.types.JSONRPCMessage
-import io.modelcontextprotocol.kotlin.sdk.types.McpException
-import io.modelcontextprotocol.kotlin.sdk.types.RPCError.ErrorCode.CONNECTION_CLOSED
-import io.modelcontextprotocol.kotlin.sdk.types.RPCError.ErrorCode.INTERNAL_ERROR
-import kotlinx.coroutines.CancellationException
-import kotlinx.coroutines.CoroutineName
-import kotlinx.coroutines.CoroutineScope
-import kotlinx.coroutines.Dispatchers
-import kotlinx.coroutines.Job
-import kotlinx.coroutines.SupervisorJob
-import kotlinx.coroutines.cancel
-import kotlinx.coroutines.cancelAndJoin
-import kotlinx.coroutines.channels.Channel
-import kotlinx.coroutines.channels.ClosedSendChannelException
-import kotlinx.coroutines.channels.ProducerScope
-import kotlinx.coroutines.channels.consumeEach
-import kotlinx.coroutines.flow.channelFlow
-import kotlinx.coroutines.isActive
-import kotlinx.coroutines.launch
-import kotlinx.coroutines.yield
+ }
+
+ is Event.EOFEvent -> {
+ if (event.stream == ProcessStream.Stdin) {
+ stopProcessing("EOF in ${event.stream}")
+ }
+ }
+
+ is Event.IOErrorEvent -> {
+ runCatching { _onError(event.cause) }
+ stopProcessing("IO Error", event.cause)
+ }
+ }
+ }
+ } finally {
+ // Wait for write job to complete before closing, matching old implementation
+ writeJob?.cancelAndJoin()
+ logger.debug { "Transport coroutine completed, calling onClose" }
+ invokeOnCloseCallback()
+ }
+ }
+ }
+
+ override suspend fun performSend(message: JSONRPCMessage, options: TransportSendOptions?) {
+ @Suppress("SwallowedException")
+ try {
+ sendChannel.send(message)
+ } catch (e: CancellationException) {
+ throw e // MUST rethrow immediately - don't log, don't wrap
+ } catch (e: ClosedSendChannelException) {
+ logger.debug(e) { "Cannot send message: transport is closed" }
+ throw McpException(
```
This class is important because it defines how MCP Kotlin SDK Tutorial: Building Multiplatform MCP Clients and Servers implements the patterns covered in this chapter.
### `kotlin-sdk-client/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/client/StdioClientTransport.kt`
-The `StderrSeverity` class in [`kotlin-sdk-client/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/client/StdioClientTransport.kt`](https://github.com/modelcontextprotocol/kotlin-sdk/blob/HEAD/kotlin-sdk-client/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/client/StdioClientTransport.kt) handles a key part of this chapter's functionality:
+The `IOErrorEvent` class in [`kotlin-sdk-client/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/client/StdioClientTransport.kt`](https://github.com/modelcontextprotocol/kotlin-sdk/blob/HEAD/kotlin-sdk-client/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/client/StdioClientTransport.kt) handles a key part of this chapter's functionality:
```kt
-import io.github.oshai.kotlinlogging.KLogger
-import io.github.oshai.kotlinlogging.KotlinLogging
-import io.modelcontextprotocol.kotlin.sdk.client.StdioClientTransport.StderrSeverity.DEBUG
-import io.modelcontextprotocol.kotlin.sdk.client.StdioClientTransport.StderrSeverity.FATAL
-import io.modelcontextprotocol.kotlin.sdk.client.StdioClientTransport.StderrSeverity.IGNORE
-import io.modelcontextprotocol.kotlin.sdk.client.StdioClientTransport.StderrSeverity.INFO
-import io.modelcontextprotocol.kotlin.sdk.client.StdioClientTransport.StderrSeverity.WARNING
-import io.modelcontextprotocol.kotlin.sdk.internal.IODispatcher
-import io.modelcontextprotocol.kotlin.sdk.shared.AbstractClientTransport
-import io.modelcontextprotocol.kotlin.sdk.shared.ReadBuffer
-import io.modelcontextprotocol.kotlin.sdk.shared.TransportSendOptions
-import io.modelcontextprotocol.kotlin.sdk.shared.serializeMessage
-import io.modelcontextprotocol.kotlin.sdk.types.JSONRPCMessage
-import io.modelcontextprotocol.kotlin.sdk.types.McpException
-import io.modelcontextprotocol.kotlin.sdk.types.RPCError.ErrorCode.CONNECTION_CLOSED
-import io.modelcontextprotocol.kotlin.sdk.types.RPCError.ErrorCode.INTERNAL_ERROR
-import kotlinx.coroutines.CancellationException
-import kotlinx.coroutines.CoroutineName
-import kotlinx.coroutines.CoroutineScope
-import kotlinx.coroutines.Dispatchers
-import kotlinx.coroutines.Job
-import kotlinx.coroutines.SupervisorJob
-import kotlinx.coroutines.cancel
-import kotlinx.coroutines.cancelAndJoin
-import kotlinx.coroutines.channels.Channel
-import kotlinx.coroutines.channels.ClosedSendChannelException
-import kotlinx.coroutines.channels.ProducerScope
-import kotlinx.coroutines.channels.consumeEach
-import kotlinx.coroutines.flow.channelFlow
-import kotlinx.coroutines.isActive
-import kotlinx.coroutines.launch
-import kotlinx.coroutines.yield
+ }
+
+ is Event.IOErrorEvent -> {
+ runCatching { _onError(event.cause) }
+ stopProcessing("IO Error", event.cause)
+ }
+ }
+ }
+ } finally {
+ // Wait for write job to complete before closing, matching old implementation
+ writeJob?.cancelAndJoin()
+ logger.debug { "Transport coroutine completed, calling onClose" }
+ invokeOnCloseCallback()
+ }
+ }
+ }
+
+ override suspend fun performSend(message: JSONRPCMessage, options: TransportSendOptions?) {
+ @Suppress("SwallowedException")
+ try {
+ sendChannel.send(message)
+ } catch (e: CancellationException) {
+ throw e // MUST rethrow immediately - don't log, don't wrap
+ } catch (e: ClosedSendChannelException) {
+ logger.debug(e) { "Cannot send message: transport is closed" }
+ throw McpException(
+ code = CONNECTION_CLOSED,
+ message = "Transport is closed",
+ cause = e,
+ )
+ }
+ }
```
This class is important because it defines how MCP Kotlin SDK Tutorial: Building Multiplatform MCP Clients and Servers implements the patterns covered in this chapter.
@@ -215,11 +213,11 @@ This class is important because it defines how MCP Kotlin SDK Tutorial: Building
```mermaid
flowchart TD
- A[ServerNotification]
- B[NotificationParams]
- C[StdioClientTransport]
- D[StderrSeverity]
- E[ProcessStream]
+ A[JsonRpc]
+ B[StderrEvent]
+ C[EOFEvent]
+ D[IOErrorEvent]
+ E[Event]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-php-sdk-tutorial/01-getting-started-and-experimental-baseline.md b/tutorials/mcp-php-sdk-tutorial/01-getting-started-and-experimental-baseline.md
index f58d6b30..01c0ac05 100644
--- a/tutorials/mcp-php-sdk-tutorial/01-getting-started-and-experimental-baseline.md
+++ b/tutorials/mcp-php-sdk-tutorial/01-getting-started-and-experimental-baseline.md
@@ -47,54 +47,8 @@ You now have a practical baseline for adopting the PHP SDK with controlled risk.
Next: [Chapter 2: Server Builder and Capability Registration](02-server-builder-and-capability-registration.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `composer.json`
-
-The `composer` module in [`composer.json`](https://github.com/modelcontextprotocol/php-sdk/blob/HEAD/composer.json) handles a key part of this chapter's functionality:
-
-```json
-{
- "name": "mcp/sdk",
- "description": "Model Context Protocol SDK for Client and Server applications in PHP",
- "license": "Apache-2.0",
- "type": "library",
- "authors": [
- {
- "name": "Christopher Hertel",
- "email": "mail@christopher-hertel.de"
- },
- {
- "name": "Kyrian Obikwelu",
- "email": "koshnawaza@gmail.com"
- },
- {
- "name": "Tobias Nyholm",
- "email": "tobias.nyholm@gmail.com"
- }
- ],
- "require": {
- "php": "^8.1",
- "ext-fileinfo": "*",
- "opis/json-schema": "^2.4",
- "php-http/discovery": "^1.20",
- "phpdocumentor/reflection-docblock": "^5.6 || ^6.0",
- "psr/clock": "^1.0",
- "psr/container": "^1.0 || ^2.0",
- "psr/event-dispatcher": "^1.0",
- "psr/http-client": "^1.0",
- "psr/http-factory": "^1.1",
- "psr/http-message": "^1.1 || ^2.0",
- "psr/http-server-handler": "^1.0",
- "psr/http-server-middleware": "^1.0",
- "psr/log": "^1.0 || ^2.0 || ^3.0",
- "symfony/finder": "^5.4 || ^6.4 || ^7.3 || ^8.0",
-```
-
-This module is important because it defines how MCP PHP SDK Tutorial: Building MCP Servers in PHP with Discovery and Transport Flexibility implements the patterns covered in this chapter.
-
### `examples/server/oauth-keycloak/keycloak/mcp-realm.json`
The `mcp-realm` module in [`examples/server/oauth-keycloak/keycloak/mcp-realm.json`](https://github.com/modelcontextprotocol/php-sdk/blob/HEAD/examples/server/oauth-keycloak/keycloak/mcp-realm.json) handles a key part of this chapter's functionality:
@@ -183,14 +137,58 @@ services:
This module is important because it defines how MCP PHP SDK Tutorial: Building MCP Servers in PHP with Discovery and Transport Flexibility implements the patterns covered in this chapter.
+### `composer.json`
+
+The `composer` module in [`composer.json`](https://github.com/modelcontextprotocol/php-sdk/blob/HEAD/composer.json) handles a key part of this chapter's functionality:
+
+```json
+{
+ "name": "mcp/sdk",
+ "description": "Model Context Protocol SDK for Client and Server applications in PHP",
+ "license": "Apache-2.0",
+ "type": "library",
+ "authors": [
+ {
+ "name": "Christopher Hertel",
+ "email": "mail@christopher-hertel.de"
+ },
+ {
+ "name": "Kyrian Obikwelu",
+ "email": "koshnawaza@gmail.com"
+ },
+ {
+ "name": "Tobias Nyholm",
+ "email": "tobias.nyholm@gmail.com"
+ }
+ ],
+ "require": {
+ "php": "^8.1",
+ "ext-fileinfo": "*",
+ "opis/json-schema": "^2.4",
+ "php-http/discovery": "^1.20",
+ "phpdocumentor/reflection-docblock": "^5.6 || ^6.0",
+ "psr/clock": "^1.0",
+ "psr/container": "^1.0 || ^2.0",
+ "psr/event-dispatcher": "^1.0",
+ "psr/http-client": "^1.0",
+ "psr/http-factory": "^1.1",
+ "psr/http-message": "^1.1 || ^2.0",
+ "psr/http-server-handler": "^1.0",
+ "psr/http-server-middleware": "^1.0",
+ "psr/log": "^1.0 || ^2.0 || ^3.0",
+ "symfony/finder": "^5.4 || ^6.4 || ^7.3 || ^8.0",
+```
+
+This module is important because it defines how MCP PHP SDK Tutorial: Building MCP Servers in PHP with Discovery and Transport Flexibility implements the patterns covered in this chapter.
+
## How These Components Connect
```mermaid
flowchart TD
- A[composer]
- B[mcp-realm]
- C[docker-compose]
+ A[mcp-realm]
+ B[docker-compose]
+ C[composer]
A --> B
B --> C
```
diff --git a/tutorials/mcp-php-sdk-tutorial/02-server-builder-and-capability-registration.md b/tutorials/mcp-php-sdk-tutorial/02-server-builder-and-capability-registration.md
index b59fd80e..729b487c 100644
--- a/tutorials/mcp-php-sdk-tutorial/02-server-builder-and-capability-registration.md
+++ b/tutorials/mcp-php-sdk-tutorial/02-server-builder-and-capability-registration.md
@@ -46,54 +46,8 @@ You now have a builder-centric model for composing PHP MCP servers.
Next: [Chapter 3: MCP Elements: Tools, Resources, Prompts, and Schemas](03-mcp-elements-tools-resources-prompts-and-schemas.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `composer.json`
-
-The `composer` module in [`composer.json`](https://github.com/modelcontextprotocol/php-sdk/blob/HEAD/composer.json) handles a key part of this chapter's functionality:
-
-```json
-{
- "name": "mcp/sdk",
- "description": "Model Context Protocol SDK for Client and Server applications in PHP",
- "license": "Apache-2.0",
- "type": "library",
- "authors": [
- {
- "name": "Christopher Hertel",
- "email": "mail@christopher-hertel.de"
- },
- {
- "name": "Kyrian Obikwelu",
- "email": "koshnawaza@gmail.com"
- },
- {
- "name": "Tobias Nyholm",
- "email": "tobias.nyholm@gmail.com"
- }
- ],
- "require": {
- "php": "^8.1",
- "ext-fileinfo": "*",
- "opis/json-schema": "^2.4",
- "php-http/discovery": "^1.20",
- "phpdocumentor/reflection-docblock": "^5.6 || ^6.0",
- "psr/clock": "^1.0",
- "psr/container": "^1.0 || ^2.0",
- "psr/event-dispatcher": "^1.0",
- "psr/http-client": "^1.0",
- "psr/http-factory": "^1.1",
- "psr/http-message": "^1.1 || ^2.0",
- "psr/http-server-handler": "^1.0",
- "psr/http-server-middleware": "^1.0",
- "psr/log": "^1.0 || ^2.0 || ^3.0",
- "symfony/finder": "^5.4 || ^6.4 || ^7.3 || ^8.0",
-```
-
-This module is important because it defines how MCP PHP SDK Tutorial: Building MCP Servers in PHP with Discovery and Transport Flexibility implements the patterns covered in this chapter.
-
### `examples/server/oauth-keycloak/keycloak/mcp-realm.json`
The `mcp-realm` module in [`examples/server/oauth-keycloak/keycloak/mcp-realm.json`](https://github.com/modelcontextprotocol/php-sdk/blob/HEAD/examples/server/oauth-keycloak/keycloak/mcp-realm.json) handles a key part of this chapter's functionality:
@@ -182,14 +136,58 @@ services:
This module is important because it defines how MCP PHP SDK Tutorial: Building MCP Servers in PHP with Discovery and Transport Flexibility implements the patterns covered in this chapter.
+### `composer.json`
+
+The `composer` module in [`composer.json`](https://github.com/modelcontextprotocol/php-sdk/blob/HEAD/composer.json) handles a key part of this chapter's functionality:
+
+```json
+{
+ "name": "mcp/sdk",
+ "description": "Model Context Protocol SDK for Client and Server applications in PHP",
+ "license": "Apache-2.0",
+ "type": "library",
+ "authors": [
+ {
+ "name": "Christopher Hertel",
+ "email": "mail@christopher-hertel.de"
+ },
+ {
+ "name": "Kyrian Obikwelu",
+ "email": "koshnawaza@gmail.com"
+ },
+ {
+ "name": "Tobias Nyholm",
+ "email": "tobias.nyholm@gmail.com"
+ }
+ ],
+ "require": {
+ "php": "^8.1",
+ "ext-fileinfo": "*",
+ "opis/json-schema": "^2.4",
+ "php-http/discovery": "^1.20",
+ "phpdocumentor/reflection-docblock": "^5.6 || ^6.0",
+ "psr/clock": "^1.0",
+ "psr/container": "^1.0 || ^2.0",
+ "psr/event-dispatcher": "^1.0",
+ "psr/http-client": "^1.0",
+ "psr/http-factory": "^1.1",
+ "psr/http-message": "^1.1 || ^2.0",
+ "psr/http-server-handler": "^1.0",
+ "psr/http-server-middleware": "^1.0",
+ "psr/log": "^1.0 || ^2.0 || ^3.0",
+ "symfony/finder": "^5.4 || ^6.4 || ^7.3 || ^8.0",
+```
+
+This module is important because it defines how MCP PHP SDK Tutorial: Building MCP Servers in PHP with Discovery and Transport Flexibility implements the patterns covered in this chapter.
+
## How These Components Connect
```mermaid
flowchart TD
- A[composer]
- B[mcp-realm]
- C[docker-compose]
+ A[mcp-realm]
+ B[docker-compose]
+ C[composer]
A --> B
B --> C
```
diff --git a/tutorials/mcp-php-sdk-tutorial/03-mcp-elements-tools-resources-prompts-and-schemas.md b/tutorials/mcp-php-sdk-tutorial/03-mcp-elements-tools-resources-prompts-and-schemas.md
index 0d54b04f..2c770cfa 100644
--- a/tutorials/mcp-php-sdk-tutorial/03-mcp-elements-tools-resources-prompts-and-schemas.md
+++ b/tutorials/mcp-php-sdk-tutorial/03-mcp-elements-tools-resources-prompts-and-schemas.md
@@ -47,54 +47,8 @@ You now have a schema-first primitive strategy for PHP MCP servers.
Next: [Chapter 4: Discovery, Manual Registration, and Caching](04-discovery-manual-registration-and-caching.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `composer.json`
-
-The `composer` module in [`composer.json`](https://github.com/modelcontextprotocol/php-sdk/blob/HEAD/composer.json) handles a key part of this chapter's functionality:
-
-```json
-{
- "name": "mcp/sdk",
- "description": "Model Context Protocol SDK for Client and Server applications in PHP",
- "license": "Apache-2.0",
- "type": "library",
- "authors": [
- {
- "name": "Christopher Hertel",
- "email": "mail@christopher-hertel.de"
- },
- {
- "name": "Kyrian Obikwelu",
- "email": "koshnawaza@gmail.com"
- },
- {
- "name": "Tobias Nyholm",
- "email": "tobias.nyholm@gmail.com"
- }
- ],
- "require": {
- "php": "^8.1",
- "ext-fileinfo": "*",
- "opis/json-schema": "^2.4",
- "php-http/discovery": "^1.20",
- "phpdocumentor/reflection-docblock": "^5.6 || ^6.0",
- "psr/clock": "^1.0",
- "psr/container": "^1.0 || ^2.0",
- "psr/event-dispatcher": "^1.0",
- "psr/http-client": "^1.0",
- "psr/http-factory": "^1.1",
- "psr/http-message": "^1.1 || ^2.0",
- "psr/http-server-handler": "^1.0",
- "psr/http-server-middleware": "^1.0",
- "psr/log": "^1.0 || ^2.0 || ^3.0",
- "symfony/finder": "^5.4 || ^6.4 || ^7.3 || ^8.0",
-```
-
-This module is important because it defines how MCP PHP SDK Tutorial: Building MCP Servers in PHP with Discovery and Transport Flexibility implements the patterns covered in this chapter.
-
### `examples/server/oauth-keycloak/keycloak/mcp-realm.json`
The `mcp-realm` module in [`examples/server/oauth-keycloak/keycloak/mcp-realm.json`](https://github.com/modelcontextprotocol/php-sdk/blob/HEAD/examples/server/oauth-keycloak/keycloak/mcp-realm.json) handles a key part of this chapter's functionality:
@@ -183,14 +137,58 @@ services:
This module is important because it defines how MCP PHP SDK Tutorial: Building MCP Servers in PHP with Discovery and Transport Flexibility implements the patterns covered in this chapter.
+### `composer.json`
+
+The `composer` module in [`composer.json`](https://github.com/modelcontextprotocol/php-sdk/blob/HEAD/composer.json) handles a key part of this chapter's functionality:
+
+```json
+{
+ "name": "mcp/sdk",
+ "description": "Model Context Protocol SDK for Client and Server applications in PHP",
+ "license": "Apache-2.0",
+ "type": "library",
+ "authors": [
+ {
+ "name": "Christopher Hertel",
+ "email": "mail@christopher-hertel.de"
+ },
+ {
+ "name": "Kyrian Obikwelu",
+ "email": "koshnawaza@gmail.com"
+ },
+ {
+ "name": "Tobias Nyholm",
+ "email": "tobias.nyholm@gmail.com"
+ }
+ ],
+ "require": {
+ "php": "^8.1",
+ "ext-fileinfo": "*",
+ "opis/json-schema": "^2.4",
+ "php-http/discovery": "^1.20",
+ "phpdocumentor/reflection-docblock": "^5.6 || ^6.0",
+ "psr/clock": "^1.0",
+ "psr/container": "^1.0 || ^2.0",
+ "psr/event-dispatcher": "^1.0",
+ "psr/http-client": "^1.0",
+ "psr/http-factory": "^1.1",
+ "psr/http-message": "^1.1 || ^2.0",
+ "psr/http-server-handler": "^1.0",
+ "psr/http-server-middleware": "^1.0",
+ "psr/log": "^1.0 || ^2.0 || ^3.0",
+ "symfony/finder": "^5.4 || ^6.4 || ^7.3 || ^8.0",
+```
+
+This module is important because it defines how MCP PHP SDK Tutorial: Building MCP Servers in PHP with Discovery and Transport Flexibility implements the patterns covered in this chapter.
+
## How These Components Connect
```mermaid
flowchart TD
- A[composer]
- B[mcp-realm]
- C[docker-compose]
+ A[mcp-realm]
+ B[docker-compose]
+ C[composer]
A --> B
B --> C
```
diff --git a/tutorials/mcp-php-sdk-tutorial/04-discovery-manual-registration-and-caching.md b/tutorials/mcp-php-sdk-tutorial/04-discovery-manual-registration-and-caching.md
index 2745787f..91dbede7 100644
--- a/tutorials/mcp-php-sdk-tutorial/04-discovery-manual-registration-and-caching.md
+++ b/tutorials/mcp-php-sdk-tutorial/04-discovery-manual-registration-and-caching.md
@@ -46,54 +46,8 @@ You now have a registration strategy framework that balances speed and control.
Next: [Chapter 5: Transports: STDIO and Streamable HTTP](05-transports-stdio-and-streamable-http.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `composer.json`
-
-The `composer` module in [`composer.json`](https://github.com/modelcontextprotocol/php-sdk/blob/HEAD/composer.json) handles a key part of this chapter's functionality:
-
-```json
-{
- "name": "mcp/sdk",
- "description": "Model Context Protocol SDK for Client and Server applications in PHP",
- "license": "Apache-2.0",
- "type": "library",
- "authors": [
- {
- "name": "Christopher Hertel",
- "email": "mail@christopher-hertel.de"
- },
- {
- "name": "Kyrian Obikwelu",
- "email": "koshnawaza@gmail.com"
- },
- {
- "name": "Tobias Nyholm",
- "email": "tobias.nyholm@gmail.com"
- }
- ],
- "require": {
- "php": "^8.1",
- "ext-fileinfo": "*",
- "opis/json-schema": "^2.4",
- "php-http/discovery": "^1.20",
- "phpdocumentor/reflection-docblock": "^5.6 || ^6.0",
- "psr/clock": "^1.0",
- "psr/container": "^1.0 || ^2.0",
- "psr/event-dispatcher": "^1.0",
- "psr/http-client": "^1.0",
- "psr/http-factory": "^1.1",
- "psr/http-message": "^1.1 || ^2.0",
- "psr/http-server-handler": "^1.0",
- "psr/http-server-middleware": "^1.0",
- "psr/log": "^1.0 || ^2.0 || ^3.0",
- "symfony/finder": "^5.4 || ^6.4 || ^7.3 || ^8.0",
-```
-
-This module is important because it defines how MCP PHP SDK Tutorial: Building MCP Servers in PHP with Discovery and Transport Flexibility implements the patterns covered in this chapter.
-
### `examples/server/oauth-keycloak/keycloak/mcp-realm.json`
The `mcp-realm` module in [`examples/server/oauth-keycloak/keycloak/mcp-realm.json`](https://github.com/modelcontextprotocol/php-sdk/blob/HEAD/examples/server/oauth-keycloak/keycloak/mcp-realm.json) handles a key part of this chapter's functionality:
@@ -182,14 +136,58 @@ services:
This module is important because it defines how MCP PHP SDK Tutorial: Building MCP Servers in PHP with Discovery and Transport Flexibility implements the patterns covered in this chapter.
+### `composer.json`
+
+The `composer` module in [`composer.json`](https://github.com/modelcontextprotocol/php-sdk/blob/HEAD/composer.json) handles a key part of this chapter's functionality:
+
+```json
+{
+ "name": "mcp/sdk",
+ "description": "Model Context Protocol SDK for Client and Server applications in PHP",
+ "license": "Apache-2.0",
+ "type": "library",
+ "authors": [
+ {
+ "name": "Christopher Hertel",
+ "email": "mail@christopher-hertel.de"
+ },
+ {
+ "name": "Kyrian Obikwelu",
+ "email": "koshnawaza@gmail.com"
+ },
+ {
+ "name": "Tobias Nyholm",
+ "email": "tobias.nyholm@gmail.com"
+ }
+ ],
+ "require": {
+ "php": "^8.1",
+ "ext-fileinfo": "*",
+ "opis/json-schema": "^2.4",
+ "php-http/discovery": "^1.20",
+ "phpdocumentor/reflection-docblock": "^5.6 || ^6.0",
+ "psr/clock": "^1.0",
+ "psr/container": "^1.0 || ^2.0",
+ "psr/event-dispatcher": "^1.0",
+ "psr/http-client": "^1.0",
+ "psr/http-factory": "^1.1",
+ "psr/http-message": "^1.1 || ^2.0",
+ "psr/http-server-handler": "^1.0",
+ "psr/http-server-middleware": "^1.0",
+ "psr/log": "^1.0 || ^2.0 || ^3.0",
+ "symfony/finder": "^5.4 || ^6.4 || ^7.3 || ^8.0",
+```
+
+This module is important because it defines how MCP PHP SDK Tutorial: Building MCP Servers in PHP with Discovery and Transport Flexibility implements the patterns covered in this chapter.
+
## How These Components Connect
```mermaid
flowchart TD
- A[composer]
- B[mcp-realm]
- C[docker-compose]
+ A[mcp-realm]
+ B[docker-compose]
+ C[composer]
A --> B
B --> C
```
diff --git a/tutorials/mcp-php-sdk-tutorial/05-transports-stdio-and-streamable-http.md b/tutorials/mcp-php-sdk-tutorial/05-transports-stdio-and-streamable-http.md
index bb6f9cfe..78c14aaa 100644
--- a/tutorials/mcp-php-sdk-tutorial/05-transports-stdio-and-streamable-http.md
+++ b/tutorials/mcp-php-sdk-tutorial/05-transports-stdio-and-streamable-http.md
@@ -45,54 +45,8 @@ You now have a transport selection model for PHP MCP deployment contexts.
Next: [Chapter 6: Client Communication: Sampling, Logging, and Progress](06-client-communication-sampling-logging-and-progress.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `composer.json`
-
-The `composer` module in [`composer.json`](https://github.com/modelcontextprotocol/php-sdk/blob/HEAD/composer.json) handles a key part of this chapter's functionality:
-
-```json
-{
- "name": "mcp/sdk",
- "description": "Model Context Protocol SDK for Client and Server applications in PHP",
- "license": "Apache-2.0",
- "type": "library",
- "authors": [
- {
- "name": "Christopher Hertel",
- "email": "mail@christopher-hertel.de"
- },
- {
- "name": "Kyrian Obikwelu",
- "email": "koshnawaza@gmail.com"
- },
- {
- "name": "Tobias Nyholm",
- "email": "tobias.nyholm@gmail.com"
- }
- ],
- "require": {
- "php": "^8.1",
- "ext-fileinfo": "*",
- "opis/json-schema": "^2.4",
- "php-http/discovery": "^1.20",
- "phpdocumentor/reflection-docblock": "^5.6 || ^6.0",
- "psr/clock": "^1.0",
- "psr/container": "^1.0 || ^2.0",
- "psr/event-dispatcher": "^1.0",
- "psr/http-client": "^1.0",
- "psr/http-factory": "^1.1",
- "psr/http-message": "^1.1 || ^2.0",
- "psr/http-server-handler": "^1.0",
- "psr/http-server-middleware": "^1.0",
- "psr/log": "^1.0 || ^2.0 || ^3.0",
- "symfony/finder": "^5.4 || ^6.4 || ^7.3 || ^8.0",
-```
-
-This module is important because it defines how MCP PHP SDK Tutorial: Building MCP Servers in PHP with Discovery and Transport Flexibility implements the patterns covered in this chapter.
-
### `examples/server/oauth-keycloak/keycloak/mcp-realm.json`
The `mcp-realm` module in [`examples/server/oauth-keycloak/keycloak/mcp-realm.json`](https://github.com/modelcontextprotocol/php-sdk/blob/HEAD/examples/server/oauth-keycloak/keycloak/mcp-realm.json) handles a key part of this chapter's functionality:
@@ -181,14 +135,58 @@ services:
This module is important because it defines how MCP PHP SDK Tutorial: Building MCP Servers in PHP with Discovery and Transport Flexibility implements the patterns covered in this chapter.
+### `composer.json`
+
+The `composer` module in [`composer.json`](https://github.com/modelcontextprotocol/php-sdk/blob/HEAD/composer.json) handles a key part of this chapter's functionality:
+
+```json
+{
+ "name": "mcp/sdk",
+ "description": "Model Context Protocol SDK for Client and Server applications in PHP",
+ "license": "Apache-2.0",
+ "type": "library",
+ "authors": [
+ {
+ "name": "Christopher Hertel",
+ "email": "mail@christopher-hertel.de"
+ },
+ {
+ "name": "Kyrian Obikwelu",
+ "email": "koshnawaza@gmail.com"
+ },
+ {
+ "name": "Tobias Nyholm",
+ "email": "tobias.nyholm@gmail.com"
+ }
+ ],
+ "require": {
+ "php": "^8.1",
+ "ext-fileinfo": "*",
+ "opis/json-schema": "^2.4",
+ "php-http/discovery": "^1.20",
+ "phpdocumentor/reflection-docblock": "^5.6 || ^6.0",
+ "psr/clock": "^1.0",
+ "psr/container": "^1.0 || ^2.0",
+ "psr/event-dispatcher": "^1.0",
+ "psr/http-client": "^1.0",
+ "psr/http-factory": "^1.1",
+ "psr/http-message": "^1.1 || ^2.0",
+ "psr/http-server-handler": "^1.0",
+ "psr/http-server-middleware": "^1.0",
+ "psr/log": "^1.0 || ^2.0 || ^3.0",
+ "symfony/finder": "^5.4 || ^6.4 || ^7.3 || ^8.0",
+```
+
+This module is important because it defines how MCP PHP SDK Tutorial: Building MCP Servers in PHP with Discovery and Transport Flexibility implements the patterns covered in this chapter.
+
## How These Components Connect
```mermaid
flowchart TD
- A[composer]
- B[mcp-realm]
- C[docker-compose]
+ A[mcp-realm]
+ B[docker-compose]
+ C[composer]
A --> B
B --> C
```
diff --git a/tutorials/mcp-php-sdk-tutorial/06-client-communication-sampling-logging-and-progress.md b/tutorials/mcp-php-sdk-tutorial/06-client-communication-sampling-logging-and-progress.md
index 632bf617..24142d82 100644
--- a/tutorials/mcp-php-sdk-tutorial/06-client-communication-sampling-logging-and-progress.md
+++ b/tutorials/mcp-php-sdk-tutorial/06-client-communication-sampling-logging-and-progress.md
@@ -40,54 +40,8 @@ You now have an operational communication model for richer PHP MCP server UX.
Next: [Chapter 7: Framework Integration, Session Stores, and Dependencies](07-framework-integration-session-stores-and-dependencies.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `composer.json`
-
-The `composer` module in [`composer.json`](https://github.com/modelcontextprotocol/php-sdk/blob/HEAD/composer.json) handles a key part of this chapter's functionality:
-
-```json
-{
- "name": "mcp/sdk",
- "description": "Model Context Protocol SDK for Client and Server applications in PHP",
- "license": "Apache-2.0",
- "type": "library",
- "authors": [
- {
- "name": "Christopher Hertel",
- "email": "mail@christopher-hertel.de"
- },
- {
- "name": "Kyrian Obikwelu",
- "email": "koshnawaza@gmail.com"
- },
- {
- "name": "Tobias Nyholm",
- "email": "tobias.nyholm@gmail.com"
- }
- ],
- "require": {
- "php": "^8.1",
- "ext-fileinfo": "*",
- "opis/json-schema": "^2.4",
- "php-http/discovery": "^1.20",
- "phpdocumentor/reflection-docblock": "^5.6 || ^6.0",
- "psr/clock": "^1.0",
- "psr/container": "^1.0 || ^2.0",
- "psr/event-dispatcher": "^1.0",
- "psr/http-client": "^1.0",
- "psr/http-factory": "^1.1",
- "psr/http-message": "^1.1 || ^2.0",
- "psr/http-server-handler": "^1.0",
- "psr/http-server-middleware": "^1.0",
- "psr/log": "^1.0 || ^2.0 || ^3.0",
- "symfony/finder": "^5.4 || ^6.4 || ^7.3 || ^8.0",
-```
-
-This module is important because it defines how MCP PHP SDK Tutorial: Building MCP Servers in PHP with Discovery and Transport Flexibility implements the patterns covered in this chapter.
-
### `examples/server/oauth-keycloak/keycloak/mcp-realm.json`
The `mcp-realm` module in [`examples/server/oauth-keycloak/keycloak/mcp-realm.json`](https://github.com/modelcontextprotocol/php-sdk/blob/HEAD/examples/server/oauth-keycloak/keycloak/mcp-realm.json) handles a key part of this chapter's functionality:
@@ -176,14 +130,58 @@ services:
This module is important because it defines how MCP PHP SDK Tutorial: Building MCP Servers in PHP with Discovery and Transport Flexibility implements the patterns covered in this chapter.
+### `composer.json`
+
+The `composer` module in [`composer.json`](https://github.com/modelcontextprotocol/php-sdk/blob/HEAD/composer.json) handles a key part of this chapter's functionality:
+
+```json
+{
+ "name": "mcp/sdk",
+ "description": "Model Context Protocol SDK for Client and Server applications in PHP",
+ "license": "Apache-2.0",
+ "type": "library",
+ "authors": [
+ {
+ "name": "Christopher Hertel",
+ "email": "mail@christopher-hertel.de"
+ },
+ {
+ "name": "Kyrian Obikwelu",
+ "email": "koshnawaza@gmail.com"
+ },
+ {
+ "name": "Tobias Nyholm",
+ "email": "tobias.nyholm@gmail.com"
+ }
+ ],
+ "require": {
+ "php": "^8.1",
+ "ext-fileinfo": "*",
+ "opis/json-schema": "^2.4",
+ "php-http/discovery": "^1.20",
+ "phpdocumentor/reflection-docblock": "^5.6 || ^6.0",
+ "psr/clock": "^1.0",
+ "psr/container": "^1.0 || ^2.0",
+ "psr/event-dispatcher": "^1.0",
+ "psr/http-client": "^1.0",
+ "psr/http-factory": "^1.1",
+ "psr/http-message": "^1.1 || ^2.0",
+ "psr/http-server-handler": "^1.0",
+ "psr/http-server-middleware": "^1.0",
+ "psr/log": "^1.0 || ^2.0 || ^3.0",
+ "symfony/finder": "^5.4 || ^6.4 || ^7.3 || ^8.0",
+```
+
+This module is important because it defines how MCP PHP SDK Tutorial: Building MCP Servers in PHP with Discovery and Transport Flexibility implements the patterns covered in this chapter.
+
## How These Components Connect
```mermaid
flowchart TD
- A[composer]
- B[mcp-realm]
- C[docker-compose]
+ A[mcp-realm]
+ B[docker-compose]
+ C[composer]
A --> B
B --> C
```
diff --git a/tutorials/mcp-php-sdk-tutorial/07-framework-integration-session-stores-and-dependencies.md b/tutorials/mcp-php-sdk-tutorial/07-framework-integration-session-stores-and-dependencies.md
index 77531ecd..6b83e3e7 100644
--- a/tutorials/mcp-php-sdk-tutorial/07-framework-integration-session-stores-and-dependencies.md
+++ b/tutorials/mcp-php-sdk-tutorial/07-framework-integration-session-stores-and-dependencies.md
@@ -46,54 +46,8 @@ You now have a framework-aware infrastructure model for PHP MCP deployments.
Next: [Chapter 8: Roadmap, Release Strategy, and Production Readiness](08-roadmap-release-strategy-and-production-readiness.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `composer.json`
-
-The `composer` module in [`composer.json`](https://github.com/modelcontextprotocol/php-sdk/blob/HEAD/composer.json) handles a key part of this chapter's functionality:
-
-```json
-{
- "name": "mcp/sdk",
- "description": "Model Context Protocol SDK for Client and Server applications in PHP",
- "license": "Apache-2.0",
- "type": "library",
- "authors": [
- {
- "name": "Christopher Hertel",
- "email": "mail@christopher-hertel.de"
- },
- {
- "name": "Kyrian Obikwelu",
- "email": "koshnawaza@gmail.com"
- },
- {
- "name": "Tobias Nyholm",
- "email": "tobias.nyholm@gmail.com"
- }
- ],
- "require": {
- "php": "^8.1",
- "ext-fileinfo": "*",
- "opis/json-schema": "^2.4",
- "php-http/discovery": "^1.20",
- "phpdocumentor/reflection-docblock": "^5.6 || ^6.0",
- "psr/clock": "^1.0",
- "psr/container": "^1.0 || ^2.0",
- "psr/event-dispatcher": "^1.0",
- "psr/http-client": "^1.0",
- "psr/http-factory": "^1.1",
- "psr/http-message": "^1.1 || ^2.0",
- "psr/http-server-handler": "^1.0",
- "psr/http-server-middleware": "^1.0",
- "psr/log": "^1.0 || ^2.0 || ^3.0",
- "symfony/finder": "^5.4 || ^6.4 || ^7.3 || ^8.0",
-```
-
-This module is important because it defines how MCP PHP SDK Tutorial: Building MCP Servers in PHP with Discovery and Transport Flexibility implements the patterns covered in this chapter.
-
### `examples/server/oauth-keycloak/keycloak/mcp-realm.json`
The `mcp-realm` module in [`examples/server/oauth-keycloak/keycloak/mcp-realm.json`](https://github.com/modelcontextprotocol/php-sdk/blob/HEAD/examples/server/oauth-keycloak/keycloak/mcp-realm.json) handles a key part of this chapter's functionality:
@@ -182,14 +136,58 @@ services:
This module is important because it defines how MCP PHP SDK Tutorial: Building MCP Servers in PHP with Discovery and Transport Flexibility implements the patterns covered in this chapter.
+### `composer.json`
+
+The `composer` module in [`composer.json`](https://github.com/modelcontextprotocol/php-sdk/blob/HEAD/composer.json) handles a key part of this chapter's functionality:
+
+```json
+{
+ "name": "mcp/sdk",
+ "description": "Model Context Protocol SDK for Client and Server applications in PHP",
+ "license": "Apache-2.0",
+ "type": "library",
+ "authors": [
+ {
+ "name": "Christopher Hertel",
+ "email": "mail@christopher-hertel.de"
+ },
+ {
+ "name": "Kyrian Obikwelu",
+ "email": "koshnawaza@gmail.com"
+ },
+ {
+ "name": "Tobias Nyholm",
+ "email": "tobias.nyholm@gmail.com"
+ }
+ ],
+ "require": {
+ "php": "^8.1",
+ "ext-fileinfo": "*",
+ "opis/json-schema": "^2.4",
+ "php-http/discovery": "^1.20",
+ "phpdocumentor/reflection-docblock": "^5.6 || ^6.0",
+ "psr/clock": "^1.0",
+ "psr/container": "^1.0 || ^2.0",
+ "psr/event-dispatcher": "^1.0",
+ "psr/http-client": "^1.0",
+ "psr/http-factory": "^1.1",
+ "psr/http-message": "^1.1 || ^2.0",
+ "psr/http-server-handler": "^1.0",
+ "psr/http-server-middleware": "^1.0",
+ "psr/log": "^1.0 || ^2.0 || ^3.0",
+ "symfony/finder": "^5.4 || ^6.4 || ^7.3 || ^8.0",
+```
+
+This module is important because it defines how MCP PHP SDK Tutorial: Building MCP Servers in PHP with Discovery and Transport Flexibility implements the patterns covered in this chapter.
+
## How These Components Connect
```mermaid
flowchart TD
- A[composer]
- B[mcp-realm]
- C[docker-compose]
+ A[mcp-realm]
+ B[docker-compose]
+ C[composer]
A --> B
B --> C
```
diff --git a/tutorials/mcp-php-sdk-tutorial/08-roadmap-release-strategy-and-production-readiness.md b/tutorials/mcp-php-sdk-tutorial/08-roadmap-release-strategy-and-production-readiness.md
index 3200c863..c6ff152a 100644
--- a/tutorials/mcp-php-sdk-tutorial/08-roadmap-release-strategy-and-production-readiness.md
+++ b/tutorials/mcp-php-sdk-tutorial/08-roadmap-release-strategy-and-production-readiness.md
@@ -39,54 +39,8 @@ You now have a production rollout strategy for PHP MCP implementations under act
Return to the [MCP PHP SDK Tutorial index](README.md).
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `composer.json`
-
-The `composer` module in [`composer.json`](https://github.com/modelcontextprotocol/php-sdk/blob/HEAD/composer.json) handles a key part of this chapter's functionality:
-
-```json
-{
- "name": "mcp/sdk",
- "description": "Model Context Protocol SDK for Client and Server applications in PHP",
- "license": "Apache-2.0",
- "type": "library",
- "authors": [
- {
- "name": "Christopher Hertel",
- "email": "mail@christopher-hertel.de"
- },
- {
- "name": "Kyrian Obikwelu",
- "email": "koshnawaza@gmail.com"
- },
- {
- "name": "Tobias Nyholm",
- "email": "tobias.nyholm@gmail.com"
- }
- ],
- "require": {
- "php": "^8.1",
- "ext-fileinfo": "*",
- "opis/json-schema": "^2.4",
- "php-http/discovery": "^1.20",
- "phpdocumentor/reflection-docblock": "^5.6 || ^6.0",
- "psr/clock": "^1.0",
- "psr/container": "^1.0 || ^2.0",
- "psr/event-dispatcher": "^1.0",
- "psr/http-client": "^1.0",
- "psr/http-factory": "^1.1",
- "psr/http-message": "^1.1 || ^2.0",
- "psr/http-server-handler": "^1.0",
- "psr/http-server-middleware": "^1.0",
- "psr/log": "^1.0 || ^2.0 || ^3.0",
- "symfony/finder": "^5.4 || ^6.4 || ^7.3 || ^8.0",
-```
-
-This module is important because it defines how MCP PHP SDK Tutorial: Building MCP Servers in PHP with Discovery and Transport Flexibility implements the patterns covered in this chapter.
-
### `examples/server/oauth-keycloak/keycloak/mcp-realm.json`
The `mcp-realm` module in [`examples/server/oauth-keycloak/keycloak/mcp-realm.json`](https://github.com/modelcontextprotocol/php-sdk/blob/HEAD/examples/server/oauth-keycloak/keycloak/mcp-realm.json) handles a key part of this chapter's functionality:
@@ -175,14 +129,58 @@ services:
This module is important because it defines how MCP PHP SDK Tutorial: Building MCP Servers in PHP with Discovery and Transport Flexibility implements the patterns covered in this chapter.
+### `composer.json`
+
+The `composer` module in [`composer.json`](https://github.com/modelcontextprotocol/php-sdk/blob/HEAD/composer.json) handles a key part of this chapter's functionality:
+
+```json
+{
+ "name": "mcp/sdk",
+ "description": "Model Context Protocol SDK for Client and Server applications in PHP",
+ "license": "Apache-2.0",
+ "type": "library",
+ "authors": [
+ {
+ "name": "Christopher Hertel",
+ "email": "mail@christopher-hertel.de"
+ },
+ {
+ "name": "Kyrian Obikwelu",
+ "email": "koshnawaza@gmail.com"
+ },
+ {
+ "name": "Tobias Nyholm",
+ "email": "tobias.nyholm@gmail.com"
+ }
+ ],
+ "require": {
+ "php": "^8.1",
+ "ext-fileinfo": "*",
+ "opis/json-schema": "^2.4",
+ "php-http/discovery": "^1.20",
+ "phpdocumentor/reflection-docblock": "^5.6 || ^6.0",
+ "psr/clock": "^1.0",
+ "psr/container": "^1.0 || ^2.0",
+ "psr/event-dispatcher": "^1.0",
+ "psr/http-client": "^1.0",
+ "psr/http-factory": "^1.1",
+ "psr/http-message": "^1.1 || ^2.0",
+ "psr/http-server-handler": "^1.0",
+ "psr/http-server-middleware": "^1.0",
+ "psr/log": "^1.0 || ^2.0 || ^3.0",
+ "symfony/finder": "^5.4 || ^6.4 || ^7.3 || ^8.0",
+```
+
+This module is important because it defines how MCP PHP SDK Tutorial: Building MCP Servers in PHP with Discovery and Transport Flexibility implements the patterns covered in this chapter.
+
## How These Components Connect
```mermaid
flowchart TD
- A[composer]
- B[mcp-realm]
- C[docker-compose]
+ A[mcp-realm]
+ B[docker-compose]
+ C[composer]
A --> B
B --> C
```
diff --git a/tutorials/mcp-python-sdk-tutorial/02-core-concepts.md b/tutorials/mcp-python-sdk-tutorial/02-core-concepts.md
index ed10755e..ee6d0ab9 100644
--- a/tutorials/mcp-python-sdk-tutorial/02-core-concepts.md
+++ b/tutorials/mcp-python-sdk-tutorial/02-core-concepts.md
@@ -12,6 +12,20 @@ Welcome to **Chapter 2: Core Concepts - Resources, Tools, and Prompts**. In this
> Master the three fundamental primitives of MCP: Resources for data access, Tools for AI actions, and Prompts for reusable templates.
+## MCP Server Primitives
+
+```mermaid
+flowchart TD
+ SERVER[MCP Server] --> R[Resources\nURI-addressed read-only data]
+ SERVER --> T[Tools\nCallable functions with schema]
+ SERVER --> P[Prompts\nReusable prompt templates]
+
+ R --> R1[file:///path/to/file]
+ R --> R2[db://table/row]
+ T --> T1[search_documents\ncreate_issue\nrun_query]
+ P --> P1[code_review_template\nanalysis_prompt]
+```
+
## Overview
MCP servers expose three types of capabilities to AI clients:
diff --git a/tutorials/mcp-python-sdk-tutorial/04-advanced-patterns.md b/tutorials/mcp-python-sdk-tutorial/04-advanced-patterns.md
index 123011df..91148d20 100644
--- a/tutorials/mcp-python-sdk-tutorial/04-advanced-patterns.md
+++ b/tutorials/mcp-python-sdk-tutorial/04-advanced-patterns.md
@@ -12,6 +12,17 @@ Welcome to **Chapter 4: Advanced Patterns**. In this part of **MCP Python SDK Tu
> Master structured outputs, progress tracking, context management, and advanced server patterns.
+## Advanced Server Patterns Overview
+
+```mermaid
+flowchart TD
+ ADV[Advanced MCP Patterns] --> SO[Structured Outputs\nPydantic response models]
+ ADV --> PT[Progress Tracking\nnotifications/progress]
+ ADV --> CTX[Context Management\nlifespan + resource sharing]
+ ADV --> RS[Resource Subscriptions\nchange notifications]
+ ADV --> LS[Long-Running Tools\nasync with progress updates]
+```
+
## Structured Outputs
Use Pydantic models for type-safe responses:
diff --git a/tutorials/mcp-python-sdk-tutorial/05-authentication-security.md b/tutorials/mcp-python-sdk-tutorial/05-authentication-security.md
index b95b92f4..2cb04625 100644
--- a/tutorials/mcp-python-sdk-tutorial/05-authentication-security.md
+++ b/tutorials/mcp-python-sdk-tutorial/05-authentication-security.md
@@ -12,6 +12,23 @@ Welcome to **Chapter 5: Authentication & Security**. In this part of **MCP Pytho
> Implement secure authentication, authorization, and security best practices for production MCP servers.
+## Authentication and Authorization Flow
+
+```mermaid
+sequenceDiagram
+ participant C as MCP Client
+ participant S as MCP Server
+ participant A as Auth Provider
+
+ C->>S: Initialize with credentials
+ S->>A: Validate API key / OAuth token
+ A->>S: Token valid + scopes
+ S->>C: Capabilities (filtered by scope)
+ C->>S: Call tool X
+ S->>S: Check authorization: has scope for X?
+ S->>C: Result or 403 error
+```
+
## Authentication Patterns
### API Key Authentication
diff --git a/tutorials/mcp-python-sdk-tutorial/06-production-deployment.md b/tutorials/mcp-python-sdk-tutorial/06-production-deployment.md
index 47e11fad..85bc7b64 100644
--- a/tutorials/mcp-python-sdk-tutorial/06-production-deployment.md
+++ b/tutorials/mcp-python-sdk-tutorial/06-production-deployment.md
@@ -12,6 +12,20 @@ Welcome to **Chapter 6: Production Deployment**. In this part of **MCP Python SD
> Deploy MCP servers to production with Docker, monitoring, error handling, and scaling strategies.
+## Production Deployment Architecture
+
+```mermaid
+flowchart TD
+ SERVER[MCP Python Server] --> T{Transport Mode}
+ T -->|stdio| LOCAL[Local subprocess\nClaude Desktop / Code]
+ T -->|HTTP + SSE| DOCKER[Docker Container]
+ DOCKER --> K8S[Kubernetes / Cloud Run]
+ K8S --> LB[Load Balancer]
+ LB --> I1[Instance 1]
+ LB --> I2[Instance 2]
+ I1 --> MON[Monitoring: Prometheus + Grafana]
+```
+
## Docker Deployment
### Dockerfile
diff --git a/tutorials/mcp-python-sdk-tutorial/07-client-integration.md b/tutorials/mcp-python-sdk-tutorial/07-client-integration.md
index a660f597..aba69ed6 100644
--- a/tutorials/mcp-python-sdk-tutorial/07-client-integration.md
+++ b/tutorials/mcp-python-sdk-tutorial/07-client-integration.md
@@ -12,6 +12,19 @@ Welcome to **Chapter 7: Client Integration**. In this part of **MCP Python SDK T
> Integrate your MCP server with Claude Code, Claude.ai, and build custom MCP clients.
+## Client Integration Patterns
+
+```mermaid
+flowchart TD
+ SERVER[MCP Python Server] --> CC[Claude Code\n~/.claude.json config]
+ SERVER --> CW[Claude.ai Web\nMCP server settings]
+ SERVER --> CUSTOM[Custom Client\nmcp.ClientSession]
+
+ CC --> STDIO[stdio transport\nsubprocess spawn]
+ CW --> SSE[HTTP + SSE transport]
+ CUSTOM --> BOTH[stdio or HTTP]
+```
+
## Claude Code Integration
### Configuration
diff --git a/tutorials/mcp-python-sdk-tutorial/08-real-world-examples.md b/tutorials/mcp-python-sdk-tutorial/08-real-world-examples.md
index 234a9821..f5bb0130 100644
--- a/tutorials/mcp-python-sdk-tutorial/08-real-world-examples.md
+++ b/tutorials/mcp-python-sdk-tutorial/08-real-world-examples.md
@@ -12,6 +12,19 @@ Welcome to **Chapter 8: Real-World Examples**. In this part of **MCP Python SDK
> Complete production-ready MCP server implementations for common use cases.
+## Example Server Implementations Overview
+
+```mermaid
+flowchart TD
+ EXAMPLES[Real-World MCP Servers] --> FS[File System Server\nread/write files, search]
+ EXAMPLES --> DB[Database Server\nSQL queries, schema inspection]
+ EXAMPLES --> API[API Integration Server\nHTTP tools, webhooks]
+ EXAMPLES --> CODE[Code Execution Server\nsandboxed Python/JS runner]
+
+ FS --> TOOLS_FS[read_file, write_file\nlist_directory, search_files]
+ DB --> TOOLS_DB[query_db, list_tables\ndescribe_schema]
+```
+
## Example 1: File System Server
```python
diff --git a/tutorials/mcp-quickstart-resources-tutorial/01-getting-started-and-repository-topology.md b/tutorials/mcp-quickstart-resources-tutorial/01-getting-started-and-repository-topology.md
index 13ca076f..dada12fd 100644
--- a/tutorials/mcp-quickstart-resources-tutorial/01-getting-started-and-repository-topology.md
+++ b/tutorials/mcp-quickstart-resources-tutorial/01-getting-started-and-repository-topology.md
@@ -38,8 +38,6 @@ You now have a clear map of quickstart assets and intended usage.
Next: [Chapter 2: Weather Server Patterns Across Languages](02-weather-server-patterns-across-languages.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `mcp-client-python/client.py`
@@ -120,84 +118,84 @@ if __name__ == "__main__":
This function is important because it defines how MCP Quickstart Resources Tutorial: Cross-Language MCP Servers and Clients by Example implements the patterns covered in this chapter.
-### `weather-server-python/weather.py`
+### `mcp-client-go/main.go`
-The `make_nws_request` function in [`weather-server-python/weather.py`](https://github.com/modelcontextprotocol/quickstart-resources/blob/HEAD/weather-server-python/weather.py) handles a key part of this chapter's functionality:
+The `NewMCPClient` function in [`mcp-client-go/main.go`](https://github.com/modelcontextprotocol/quickstart-resources/blob/HEAD/mcp-client-go/main.go) handles a key part of this chapter's functionality:
-```py
+```go
+}
+
+func NewMCPClient() (*MCPClient, error) {
+ // Load .env file
+ if err := godotenv.Load(); err != nil {
+ return nil, fmt.Errorf("failed to load .env file: %w", err)
+ }
+
+ apiKey := os.Getenv("ANTHROPIC_API_KEY")
+ if apiKey == "" {
+ return nil, fmt.Errorf("ANTHROPIC_API_KEY environment variable not set")
+ }
+
+ client := anthropic.NewClient(option.WithAPIKey(apiKey))
+ return &MCPClient{
+ anthropic: &client,
+ }, nil
+}
-async def make_nws_request(url: str) -> dict[str, Any] | None:
- """Make a request to the NWS API with proper error handling."""
- headers = {"User-Agent": USER_AGENT, "Accept": "application/geo+json"}
- async with httpx.AsyncClient() as client:
- try:
- response = await client.get(url, headers=headers, timeout=30.0)
- response.raise_for_status()
- return response.json()
- except Exception:
- return None
-
-
-def format_alert(feature: dict) -> str:
- """Format an alert feature into a readable string."""
- props = feature["properties"]
- return f"""
-Event: {props.get("event", "Unknown")}
-Area: {props.get("areaDesc", "Unknown")}
-Severity: {props.get("severity", "Unknown")}
-Description: {props.get("description", "No description available")}
-Instructions: {props.get("instruction", "No specific instructions provided")}
-"""
-
-
-@mcp.tool()
-async def get_alerts(state: str) -> str:
- """Get weather alerts for a US state.
-
- Args:
- state: Two-letter US state code (e.g. CA, NY)
+func (c *MCPClient) ConnectToServer(ctx context.Context, serverArgs []string) error {
+ if len(serverArgs) == 0 {
+ return fmt.Errorf("no server command provided")
+ }
+
+ // Create command to spawn server process
+ cmd := exec.CommandContext(ctx, serverArgs[0], serverArgs[1:]...)
+
+ // Create MCP client
+ client := mcp.NewClient(
+ &mcp.Implementation{
+ Name: "mcp-client-go",
```
This function is important because it defines how MCP Quickstart Resources Tutorial: Cross-Language MCP Servers and Clients by Example implements the patterns covered in this chapter.
-### `weather-server-python/weather.py`
+### `mcp-client-go/main.go`
-The `format_alert` function in [`weather-server-python/weather.py`](https://github.com/modelcontextprotocol/quickstart-resources/blob/HEAD/weather-server-python/weather.py) handles a key part of this chapter's functionality:
-
-```py
+The `ConnectToServer` function in [`mcp-client-go/main.go`](https://github.com/modelcontextprotocol/quickstart-resources/blob/HEAD/mcp-client-go/main.go) handles a key part of this chapter's functionality:
+```go
+}
-def format_alert(feature: dict) -> str:
- """Format an alert feature into a readable string."""
- props = feature["properties"]
- return f"""
-Event: {props.get("event", "Unknown")}
-Area: {props.get("areaDesc", "Unknown")}
-Severity: {props.get("severity", "Unknown")}
-Description: {props.get("description", "No description available")}
-Instructions: {props.get("instruction", "No specific instructions provided")}
-"""
+func (c *MCPClient) ConnectToServer(ctx context.Context, serverArgs []string) error {
+ if len(serverArgs) == 0 {
+ return fmt.Errorf("no server command provided")
+ }
+ // Create command to spawn server process
+ cmd := exec.CommandContext(ctx, serverArgs[0], serverArgs[1:]...)
-@mcp.tool()
-async def get_alerts(state: str) -> str:
- """Get weather alerts for a US state.
+ // Create MCP client
+ client := mcp.NewClient(
+ &mcp.Implementation{
+ Name: "mcp-client-go",
+ Version: "0.1.0",
+ },
+ nil,
+ )
- Args:
- state: Two-letter US state code (e.g. CA, NY)
- """
- url = f"{NWS_API_BASE}/alerts/active/area/{state}"
- data = await make_nws_request(url)
+ // Connect using CommandTransport
+ transport := &mcp.CommandTransport{
+ Command: cmd,
+ }
- if not data or "features" not in data:
- return "Unable to fetch alerts or no alerts found."
+ session, err := client.Connect(ctx, transport, nil)
+ if err != nil {
+ return fmt.Errorf("failed to connect to server: %w", err)
+ }
- if not data["features"]:
- return "No active alerts for this state."
+ c.session = session
- alerts = [format_alert(feature) for feature in data["features"]]
- return "\n---\n".join(alerts)
+ // List available tools
```
This function is important because it defines how MCP Quickstart Resources Tutorial: Cross-Language MCP Servers and Clients by Example implements the patterns covered in this chapter.
@@ -209,9 +207,9 @@ This function is important because it defines how MCP Quickstart Resources Tutor
flowchart TD
A[MCPClient]
B[main]
- C[make_nws_request]
- D[format_alert]
- E[get_alerts]
+ C[NewMCPClient]
+ D[ConnectToServer]
+ E[mcpToolToAnthropicTool]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-quickstart-resources-tutorial/02-weather-server-patterns-across-languages.md b/tutorials/mcp-quickstart-resources-tutorial/02-weather-server-patterns-across-languages.md
index eec1d1e1..6598a026 100644
--- a/tutorials/mcp-quickstart-resources-tutorial/02-weather-server-patterns-across-languages.md
+++ b/tutorials/mcp-quickstart-resources-tutorial/02-weather-server-patterns-across-languages.md
@@ -40,148 +40,166 @@ You now have a cross-language pattern model for MCP weather-server implementatio
Next: [Chapter 3: MCP Client Patterns and LLM Chat Loops](03-mcp-client-patterns-and-llm-chat-loops.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `weather-server-python/weather.py`
-
-The `get_forecast` function in [`weather-server-python/weather.py`](https://github.com/modelcontextprotocol/quickstart-resources/blob/HEAD/weather-server-python/weather.py) handles a key part of this chapter's functionality:
-
-```py
+### `mcp-client-go/main.go`
-@mcp.tool()
-async def get_forecast(latitude: float, longitude: float) -> str:
- """Get weather forecast for a location.
+The `ProcessQuery` function in [`mcp-client-go/main.go`](https://github.com/modelcontextprotocol/quickstart-resources/blob/HEAD/mcp-client-go/main.go) handles a key part of this chapter's functionality:
- Args:
- latitude: Latitude of the location
- longitude: Longitude of the location
- """
- # First get the forecast grid endpoint
- points_url = f"{NWS_API_BASE}/points/{latitude},{longitude}"
- points_data = await make_nws_request(points_url)
+```go
+}
- if not points_data:
- return "Unable to fetch forecast data for this location."
+func (c *MCPClient) ProcessQuery(ctx context.Context, query string) (string, error) {
+ if c.session == nil {
+ return "", fmt.Errorf("client is not connected to any server")
+ }
- # Get the forecast URL from the points response
- forecast_url = points_data["properties"]["forecast"]
- forecast_data = await make_nws_request(forecast_url)
+ messages := []anthropic.MessageParam{
+ anthropic.NewUserMessage(anthropic.NewTextBlock(query)),
+ }
- if not forecast_data:
- return "Unable to fetch detailed forecast."
+ // Initial Claude API call with tools
+ response, err := c.anthropic.Messages.New(ctx, anthropic.MessageNewParams{
+ Model: model,
+ MaxTokens: 1024,
+ Messages: messages,
+ Tools: c.tools,
+ })
+ if err != nil {
+ return "", fmt.Errorf("anthropic API request failed: %w", err)
+ }
- # Format the periods into a readable forecast
- periods = forecast_data["properties"]["periods"]
- forecasts = []
- for period in periods[:5]: # Only show next 5 periods
- forecast = f"""
-{period["name"]}:
-Temperature: {period["temperature"]}°{period["temperatureUnit"]}
-Wind: {period["windSpeed"]} {period["windDirection"]}
-Forecast: {period["detailedForecast"]}
+ var toolUseBlocks []anthropic.ToolUseBlock
+ var finalText []string
+ for _, block := range response.Content {
+ switch b := block.AsAny().(type) {
+ case anthropic.TextBlock:
+ finalText = append(finalText, b.Text)
+ case anthropic.ToolUseBlock:
+ toolUseBlocks = append(toolUseBlocks, b)
+ }
+ }
```
This function is important because it defines how MCP Quickstart Resources Tutorial: Cross-Language MCP Servers and Clients by Example implements the patterns covered in this chapter.
-### `weather-server-python/weather.py`
-
-The `main` function in [`weather-server-python/weather.py`](https://github.com/modelcontextprotocol/quickstart-resources/blob/HEAD/weather-server-python/weather.py) handles a key part of this chapter's functionality:
-
-```py
-
+### `mcp-client-go/main.go`
-def main():
- # Initialize and run the server
- mcp.run(transport="stdio")
+The `ChatLoop` function in [`mcp-client-go/main.go`](https://github.com/modelcontextprotocol/quickstart-resources/blob/HEAD/mcp-client-go/main.go) handles a key part of this chapter's functionality:
+```go
+}
-if __name__ == "__main__":
- main()
+func (c *MCPClient) ChatLoop(ctx context.Context) error {
+ fmt.Println("\nMCP Client Started!")
+ fmt.Println("Type your queries or 'quit' to exit.")
+
+ scanner := bufio.NewScanner(os.Stdin)
+
+ for {
+ fmt.Print("\nQuery: ")
+ if !scanner.Scan() {
+ break // EOF
+ }
+
+ query := strings.TrimSpace(scanner.Text())
+ if strings.EqualFold(query, "quit") {
+ break
+ }
+ if query == "" {
+ continue
+ }
+
+ response, err := c.ProcessQuery(ctx, query)
+ if err != nil {
+ fmt.Printf("\nError: %v\n", err)
+ continue
+ }
+
+ fmt.Printf("\n%s\n", response)
+ }
+ return scanner.Err()
```
This function is important because it defines how MCP Quickstart Resources Tutorial: Cross-Language MCP Servers and Clients by Example implements the patterns covered in this chapter.
### `mcp-client-go/main.go`
-The `NewMCPClient` function in [`mcp-client-go/main.go`](https://github.com/modelcontextprotocol/quickstart-resources/blob/HEAD/mcp-client-go/main.go) handles a key part of this chapter's functionality:
+The `Cleanup` function in [`mcp-client-go/main.go`](https://github.com/modelcontextprotocol/quickstart-resources/blob/HEAD/mcp-client-go/main.go) handles a key part of this chapter's functionality:
```go
}
-func NewMCPClient() (*MCPClient, error) {
- // Load .env file
- if err := godotenv.Load(); err != nil {
- return nil, fmt.Errorf("failed to load .env file: %w", err)
+func (c *MCPClient) Cleanup() error {
+ if c.session != nil {
+ if err := c.session.Close(); err != nil {
+ return fmt.Errorf("failed to close session: %w", err)
+ }
+ c.session = nil
}
+ return nil
+}
- apiKey := os.Getenv("ANTHROPIC_API_KEY")
- if apiKey == "" {
- return nil, fmt.Errorf("ANTHROPIC_API_KEY environment variable not set")
+func main() {
+ if len(os.Args) < 2 {
+ fmt.Fprintln(os.Stderr, "Usage: go run main.go <server_script_or_binary> [args...]")
+ os.Exit(1)
}
- client := anthropic.NewClient(option.WithAPIKey(apiKey))
-
- return &MCPClient{
- anthropic: &client,
- }, nil
-}
+ serverArgs := os.Args[1:]
-func (c *MCPClient) ConnectToServer(ctx context.Context, serverArgs []string) error {
- if len(serverArgs) == 0 {
- return fmt.Errorf("no server command provided")
+ client, err := NewMCPClient()
+ if err != nil {
+ log.Fatalf("Failed to create MCP client: %v", err)
}
- // Create command to spawn server process
- cmd := exec.CommandContext(ctx, serverArgs[0], serverArgs[1:]...)
+ ctx := context.Background()
+
+ if err := client.ConnectToServer(ctx, serverArgs); err != nil {
+ log.Fatalf("Failed to connect to MCP server: %v", err)
+ }
- // Create MCP client
- client := mcp.NewClient(
- &mcp.Implementation{
- Name: "mcp-client-go",
+ if err := client.ChatLoop(ctx); err != nil {
```
This function is important because it defines how MCP Quickstart Resources Tutorial: Cross-Language MCP Servers and Clients by Example implements the patterns covered in this chapter.
### `mcp-client-go/main.go`
-The `ConnectToServer` function in [`mcp-client-go/main.go`](https://github.com/modelcontextprotocol/quickstart-resources/blob/HEAD/mcp-client-go/main.go) handles a key part of this chapter's functionality:
+The `main` function in [`mcp-client-go/main.go`](https://github.com/modelcontextprotocol/quickstart-resources/blob/HEAD/mcp-client-go/main.go) handles a key part of this chapter's functionality:
```go
+package main
+
+import (
+ "bufio"
+ "context"
+ "encoding/json"
+ "fmt"
+ "log"
+ "os"
+ "os/exec"
+ "strings"
+
+ "github.com/anthropics/anthropic-sdk-go"
+ "github.com/anthropics/anthropic-sdk-go/option"
+ "github.com/joho/godotenv"
+ "github.com/modelcontextprotocol/go-sdk/mcp"
+)
+
+var model anthropic.Model = anthropic.ModelClaudeSonnet4_5_20250929
+
+type MCPClient struct {
+ anthropic *anthropic.Client
+ session *mcp.ClientSession
+ tools []anthropic.ToolUnionParam
}
-func (c *MCPClient) ConnectToServer(ctx context.Context, serverArgs []string) error {
- if len(serverArgs) == 0 {
- return fmt.Errorf("no server command provided")
- }
-
- // Create command to spawn server process
- cmd := exec.CommandContext(ctx, serverArgs[0], serverArgs[1:]...)
-
- // Create MCP client
- client := mcp.NewClient(
- &mcp.Implementation{
- Name: "mcp-client-go",
- Version: "0.1.0",
- },
- nil,
- )
-
- // Connect using CommandTransport
- transport := &mcp.CommandTransport{
- Command: cmd,
- }
-
- session, err := client.Connect(ctx, transport, nil)
- if err != nil {
- return fmt.Errorf("failed to connect to server: %w", err)
- }
-
- c.session = session
-
- // List available tools
+func NewMCPClient() (*MCPClient, error) {
+ // Load .env file
+ if err := godotenv.Load(); err != nil {
+ return nil, fmt.Errorf("failed to load .env file: %w", err)
```
This function is important because it defines how MCP Quickstart Resources Tutorial: Cross-Language MCP Servers and Clients by Example implements the patterns covered in this chapter.
@@ -191,11 +209,11 @@ This function is important because it defines how MCP Quickstart Resources Tutor
```mermaid
flowchart TD
- A[get_forecast]
- B[main]
- C[NewMCPClient]
- D[ConnectToServer]
- E[mcpToolToAnthropicTool]
+ A[ProcessQuery]
+ B[ChatLoop]
+ C[Cleanup]
+ D[main]
+ E[MCPClient]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-quickstart-resources-tutorial/03-mcp-client-patterns-and-llm-chat-loops.md b/tutorials/mcp-quickstart-resources-tutorial/03-mcp-client-patterns-and-llm-chat-loops.md
index 94cc58c4..2fafca91 100644
--- a/tutorials/mcp-quickstart-resources-tutorial/03-mcp-client-patterns-and-llm-chat-loops.md
+++ b/tutorials/mcp-quickstart-resources-tutorial/03-mcp-client-patterns-and-llm-chat-loops.md
@@ -38,168 +38,168 @@ You now have a practical MCP client loop model for chatbot-oriented integrations
Next: [Chapter 4: Protocol Flow and stdio Transport Behavior](04-protocol-flow-and-stdio-transport-behavior.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `mcp-client-go/main.go`
+### `mcp-client-typescript/index.ts`
-The `ProcessQuery` function in [`mcp-client-go/main.go`](https://github.com/modelcontextprotocol/quickstart-resources/blob/HEAD/mcp-client-go/main.go) handles a key part of this chapter's functionality:
+The `main` function in [`mcp-client-typescript/index.ts`](https://github.com/modelcontextprotocol/quickstart-resources/blob/HEAD/mcp-client-typescript/index.ts) handles a key part of this chapter's functionality:
-```go
+```ts
}
-func (c *MCPClient) ProcessQuery(ctx context.Context, query string) (string, error) {
- if c.session == nil {
- return "", fmt.Errorf("client is not connected to any server")
- }
-
- messages := []anthropic.MessageParam{
- anthropic.NewUserMessage(anthropic.NewTextBlock(query)),
- }
-
- // Initial Claude API call with tools
- response, err := c.anthropic.Messages.New(ctx, anthropic.MessageNewParams{
- Model: model,
- MaxTokens: 1024,
- Messages: messages,
- Tools: c.tools,
- })
- if err != nil {
- return "", fmt.Errorf("anthropic API request failed: %w", err)
- }
+async function main() {
+ if (process.argv.length < 3) {
+ console.log("Usage: node build/index.js <path_to_server_script>");
+ return;
+ }
+ const mcpClient = new MCPClient();
+ try {
+ await mcpClient.connectToServer(process.argv[2]);
+
+ // Check if we have a valid API key to continue
+ const apiKey = process.env.ANTHROPIC_API_KEY;
+ if (!apiKey) {
+ console.log(
+ "\nNo ANTHROPIC_API_KEY found. To query these tools with Claude, set your API key:"
+ );
+ console.log(" export ANTHROPIC_API_KEY=your-api-key-here");
+ return;
+ }
+
+ await mcpClient.chatLoop();
+ } catch (e) {
+ console.error("Error:", e);
+ await mcpClient.cleanup();
+ process.exit(1);
+ } finally {
+ await mcpClient.cleanup();
+ process.exit(0);
+ }
+}
- var toolUseBlocks []anthropic.ToolUseBlock
- var finalText []string
- for _, block := range response.Content {
- switch b := block.AsAny().(type) {
- case anthropic.TextBlock:
- finalText = append(finalText, b.Text)
- case anthropic.ToolUseBlock:
- toolUseBlocks = append(toolUseBlocks, b)
- }
- }
```
This function is important because it defines how MCP Quickstart Resources Tutorial: Cross-Language MCP Servers and Clients by Example implements the patterns covered in this chapter.
-### `mcp-client-go/main.go`
+### `weather-server-go/main.go`
-The `ChatLoop` function in [`mcp-client-go/main.go`](https://github.com/modelcontextprotocol/quickstart-resources/blob/HEAD/mcp-client-go/main.go) handles a key part of this chapter's functionality:
+The `formatAlert` function in [`weather-server-go/main.go`](https://github.com/modelcontextprotocol/quickstart-resources/blob/HEAD/weather-server-go/main.go) handles a key part of this chapter's functionality:
```go
}
-func (c *MCPClient) ChatLoop(ctx context.Context) error {
- fmt.Println("\nMCP Client Started!")
- fmt.Println("Type your queries or 'quit' to exit.")
-
- scanner := bufio.NewScanner(os.Stdin)
-
- for {
- fmt.Print("\nQuery: ")
- if !scanner.Scan() {
- break // EOF
- }
-
- query := strings.TrimSpace(scanner.Text())
- if strings.EqualFold(query, "quit") {
- break
- }
- if query == "" {
- continue
- }
-
- response, err := c.ProcessQuery(ctx, query)
- if err != nil {
- fmt.Printf("\nError: %v\n", err)
- continue
- }
-
- fmt.Printf("\n%s\n", response)
- }
+func formatAlert(alert AlertFeature) string {
+ props := alert.Properties
+ event := cmp.Or(props.Event, "Unknown")
+ areaDesc := cmp.Or(props.AreaDesc, "Unknown")
+ severity := cmp.Or(props.Severity, "Unknown")
+ description := cmp.Or(props.Description, "No description available")
+ instruction := cmp.Or(props.Instruction, "No specific instructions provided")
+
+ return fmt.Sprintf(`
+Event: %s
+Area: %s
+Severity: %s
+Description: %s
+Instructions: %s
+`, event, areaDesc, severity, description, instruction)
+}
+
+func formatPeriod(period ForecastPeriod) string {
+ return fmt.Sprintf(`
+%s:
+Temperature: %d°%s
+Wind: %s %s
+Forecast: %s
+`, period.Name, period.Temperature, period.TemperatureUnit,
+ period.WindSpeed, period.WindDirection, period.DetailedForecast)
+}
- return scanner.Err()
+func getForecast(ctx context.Context, req *mcp.CallToolRequest, input ForecastInput) (
+ *mcp.CallToolResult, any, error,
+) {
```
This function is important because it defines how MCP Quickstart Resources Tutorial: Cross-Language MCP Servers and Clients by Example implements the patterns covered in this chapter.
-### `mcp-client-go/main.go`
+### `weather-server-go/main.go`
-The `Cleanup` function in [`mcp-client-go/main.go`](https://github.com/modelcontextprotocol/quickstart-resources/blob/HEAD/mcp-client-go/main.go) handles a key part of this chapter's functionality:
+The `formatPeriod` function in [`weather-server-go/main.go`](https://github.com/modelcontextprotocol/quickstart-resources/blob/HEAD/weather-server-go/main.go) handles a key part of this chapter's functionality:
```go
}
-func (c *MCPClient) Cleanup() error {
- if c.session != nil {
- if err := c.session.Close(); err != nil {
- return fmt.Errorf("failed to close session: %w", err)
- }
- c.session = nil
- }
- return nil
+func formatPeriod(period ForecastPeriod) string {
+ return fmt.Sprintf(`
+%s:
+Temperature: %d°%s
+Wind: %s %s
+Forecast: %s
+`, period.Name, period.Temperature, period.TemperatureUnit,
+ period.WindSpeed, period.WindDirection, period.DetailedForecast)
}
-func main() {
- if len(os.Args) < 2 {
- fmt.Fprintln(os.Stderr, "Usage: go run main.go <server_script_or_binary> [args...]")
- os.Exit(1)
- }
-
- serverArgs := os.Args[1:]
-
- client, err := NewMCPClient()
+func getForecast(ctx context.Context, req *mcp.CallToolRequest, input ForecastInput) (
+ *mcp.CallToolResult, any, error,
+) {
+ // Get points data
+ pointsURL := fmt.Sprintf("%s/points/%f,%f", NWSAPIBase, input.Latitude, input.Longitude)
+ pointsData, err := makeNWSRequest[PointsResponse](ctx, pointsURL)
if err != nil {
- log.Fatalf("Failed to create MCP client: %v", err)
- }
-
- ctx := context.Background()
-
- if err := client.ConnectToServer(ctx, serverArgs); err != nil {
- log.Fatalf("Failed to connect to MCP server: %v", err)
+ return &mcp.CallToolResult{
+ Content: []mcp.Content{
+ &mcp.TextContent{Text: "Unable to fetch forecast data for this location."},
+ },
+ }, nil, nil
}
- if err := client.ChatLoop(ctx); err != nil {
+ // Get forecast data
+ forecastURL := pointsData.Properties.Forecast
+ if forecastURL == "" {
+ return &mcp.CallToolResult{
+ Content: []mcp.Content{
+ &mcp.TextContent{Text: "Unable to fetch forecast URL."},
```
This function is important because it defines how MCP Quickstart Resources Tutorial: Cross-Language MCP Servers and Clients by Example implements the patterns covered in this chapter.
-### `mcp-client-go/main.go`
+### `weather-server-go/main.go`
-The `main` function in [`mcp-client-go/main.go`](https://github.com/modelcontextprotocol/quickstart-resources/blob/HEAD/mcp-client-go/main.go) handles a key part of this chapter's functionality:
+The `getForecast` function in [`weather-server-go/main.go`](https://github.com/modelcontextprotocol/quickstart-resources/blob/HEAD/weather-server-go/main.go) handles a key part of this chapter's functionality:
```go
-package main
-
-import (
- "bufio"
- "context"
- "encoding/json"
- "fmt"
- "log"
- "os"
- "os/exec"
- "strings"
-
- "github.com/anthropics/anthropic-sdk-go"
- "github.com/anthropics/anthropic-sdk-go/option"
- "github.com/joho/godotenv"
- "github.com/modelcontextprotocol/go-sdk/mcp"
-)
-
-var model anthropic.Model = anthropic.ModelClaudeSonnet4_5_20250929
-
-type MCPClient struct {
- anthropic *anthropic.Client
- session *mcp.ClientSession
- tools []anthropic.ToolUnionParam
}
-func NewMCPClient() (*MCPClient, error) {
- // Load .env file
- if err := godotenv.Load(); err != nil {
- return nil, fmt.Errorf("failed to load .env file: %w", err)
+func getForecast(ctx context.Context, req *mcp.CallToolRequest, input ForecastInput) (
+ *mcp.CallToolResult, any, error,
+) {
+ // Get points data
+ pointsURL := fmt.Sprintf("%s/points/%f,%f", NWSAPIBase, input.Latitude, input.Longitude)
+ pointsData, err := makeNWSRequest[PointsResponse](ctx, pointsURL)
+ if err != nil {
+ return &mcp.CallToolResult{
+ Content: []mcp.Content{
+ &mcp.TextContent{Text: "Unable to fetch forecast data for this location."},
+ },
+ }, nil, nil
+ }
+
+ // Get forecast data
+ forecastURL := pointsData.Properties.Forecast
+ if forecastURL == "" {
+ return &mcp.CallToolResult{
+ Content: []mcp.Content{
+ &mcp.TextContent{Text: "Unable to fetch forecast URL."},
+ },
+ }, nil, nil
+ }
+
+ forecastData, err := makeNWSRequest[ForecastResponse](ctx, forecastURL)
+ if err != nil {
+ return &mcp.CallToolResult{
+ Content: []mcp.Content{
+ &mcp.TextContent{Text: "Unable to fetch detailed forecast."},
+ },
```
This function is important because it defines how MCP Quickstart Resources Tutorial: Cross-Language MCP Servers and Clients by Example implements the patterns covered in this chapter.
@@ -209,11 +209,11 @@ This function is important because it defines how MCP Quickstart Resources Tutor
```mermaid
flowchart TD
- A[ProcessQuery]
- B[ChatLoop]
- C[Cleanup]
- D[main]
- E[formatAlert]
+ A[main]
+ B[formatAlert]
+ C[formatPeriod]
+ D[getForecast]
+ E[getAlerts]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-quickstart-resources-tutorial/04-protocol-flow-and-stdio-transport-behavior.md b/tutorials/mcp-quickstart-resources-tutorial/04-protocol-flow-and-stdio-transport-behavior.md
index dd014c3f..9a63c1f3 100644
--- a/tutorials/mcp-quickstart-resources-tutorial/04-protocol-flow-and-stdio-transport-behavior.md
+++ b/tutorials/mcp-quickstart-resources-tutorial/04-protocol-flow-and-stdio-transport-behavior.md
@@ -38,135 +38,10 @@ You now have a protocol baseline for debugging and extending quickstart implemen
Next: [Chapter 5: Smoke Tests and Mock Infrastructure](05-smoke-tests-and-mock-infrastructure.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `weather-server-go/main.go`
-The `formatPeriod` function in [`weather-server-go/main.go`](https://github.com/modelcontextprotocol/quickstart-resources/blob/HEAD/weather-server-go/main.go) handles a key part of this chapter's functionality:
-
-```go
-}
-
-func formatPeriod(period ForecastPeriod) string {
- return fmt.Sprintf(`
-%s:
-Temperature: %d°%s
-Wind: %s %s
-Forecast: %s
-`, period.Name, period.Temperature, period.TemperatureUnit,
- period.WindSpeed, period.WindDirection, period.DetailedForecast)
-}
-
-func getForecast(ctx context.Context, req *mcp.CallToolRequest, input ForecastInput) (
- *mcp.CallToolResult, any, error,
-) {
- // Get points data
- pointsURL := fmt.Sprintf("%s/points/%f,%f", NWSAPIBase, input.Latitude, input.Longitude)
- pointsData, err := makeNWSRequest[PointsResponse](ctx, pointsURL)
- if err != nil {
- return &mcp.CallToolResult{
- Content: []mcp.Content{
- &mcp.TextContent{Text: "Unable to fetch forecast data for this location."},
- },
- }, nil, nil
- }
-
- // Get forecast data
- forecastURL := pointsData.Properties.Forecast
- if forecastURL == "" {
- return &mcp.CallToolResult{
- Content: []mcp.Content{
- &mcp.TextContent{Text: "Unable to fetch forecast URL."},
-```
-
-This function is important because it defines how MCP Quickstart Resources Tutorial: Cross-Language MCP Servers and Clients by Example implements the patterns covered in this chapter.
-
-### `weather-server-go/main.go`
-
-The `getForecast` function in [`weather-server-go/main.go`](https://github.com/modelcontextprotocol/quickstart-resources/blob/HEAD/weather-server-go/main.go) handles a key part of this chapter's functionality:
-
-```go
-}
-
-func getForecast(ctx context.Context, req *mcp.CallToolRequest, input ForecastInput) (
- *mcp.CallToolResult, any, error,
-) {
- // Get points data
- pointsURL := fmt.Sprintf("%s/points/%f,%f", NWSAPIBase, input.Latitude, input.Longitude)
- pointsData, err := makeNWSRequest[PointsResponse](ctx, pointsURL)
- if err != nil {
- return &mcp.CallToolResult{
- Content: []mcp.Content{
- &mcp.TextContent{Text: "Unable to fetch forecast data for this location."},
- },
- }, nil, nil
- }
-
- // Get forecast data
- forecastURL := pointsData.Properties.Forecast
- if forecastURL == "" {
- return &mcp.CallToolResult{
- Content: []mcp.Content{
- &mcp.TextContent{Text: "Unable to fetch forecast URL."},
- },
- }, nil, nil
- }
-
- forecastData, err := makeNWSRequest[ForecastResponse](ctx, forecastURL)
- if err != nil {
- return &mcp.CallToolResult{
- Content: []mcp.Content{
- &mcp.TextContent{Text: "Unable to fetch detailed forecast."},
- },
-```
-
-This function is important because it defines how MCP Quickstart Resources Tutorial: Cross-Language MCP Servers and Clients by Example implements the patterns covered in this chapter.
-
-### `weather-server-go/main.go`
-
-The `getAlerts` function in [`weather-server-go/main.go`](https://github.com/modelcontextprotocol/quickstart-resources/blob/HEAD/weather-server-go/main.go) handles a key part of this chapter's functionality:
-
-```go
-}
-
-func getAlerts(ctx context.Context, req *mcp.CallToolRequest, input AlertsInput) (
- *mcp.CallToolResult, any, error,
-) {
- // Build alerts URL
- stateCode := strings.ToUpper(input.State)
- alertsURL := fmt.Sprintf("%s/alerts/active/area/%s", NWSAPIBase, stateCode)
-
- alertsData, err := makeNWSRequest[AlertsResponse](ctx, alertsURL)
- if err != nil {
- return &mcp.CallToolResult{
- Content: []mcp.Content{
- &mcp.TextContent{Text: "Unable to fetch alerts or no alerts found."},
- },
- }, nil, nil
- }
-
- // Check if there are any alerts
- if len(alertsData.Features) == 0 {
- return &mcp.CallToolResult{
- Content: []mcp.Content{
- &mcp.TextContent{Text: "No active alerts for this state."},
- },
- }, nil, nil
- }
-
- // Format alerts
- var alerts []string
- for _, feature := range alertsData.Features {
- alerts = append(alerts, formatAlert(feature))
- }
-```
-
-This function is important because it defines how MCP Quickstart Resources Tutorial: Cross-Language MCP Servers and Clients by Example implements the patterns covered in this chapter.
-
-### `weather-server-go/main.go`
-
The `main` function in [`weather-server-go/main.go`](https://github.com/modelcontextprotocol/quickstart-resources/blob/HEAD/weather-server-go/main.go) handles a key part of this chapter's functionality:
```go
@@ -204,16 +79,139 @@ type PointsResponse struct {
This function is important because it defines how MCP Quickstart Resources Tutorial: Cross-Language MCP Servers and Clients by Example implements the patterns covered in this chapter.
+### `weather-server-python/weather.py`
+
+The `make_nws_request` function in [`weather-server-python/weather.py`](https://github.com/modelcontextprotocol/quickstart-resources/blob/HEAD/weather-server-python/weather.py) handles a key part of this chapter's functionality:
+
+```py
+
+
+async def make_nws_request(url: str) -> dict[str, Any] | None:
+ """Make a request to the NWS API with proper error handling."""
+ headers = {"User-Agent": USER_AGENT, "Accept": "application/geo+json"}
+ async with httpx.AsyncClient() as client:
+ try:
+ response = await client.get(url, headers=headers, timeout=30.0)
+ response.raise_for_status()
+ return response.json()
+ except Exception:
+ return None
+
+
+def format_alert(feature: dict) -> str:
+ """Format an alert feature into a readable string."""
+ props = feature["properties"]
+ return f"""
+Event: {props.get("event", "Unknown")}
+Area: {props.get("areaDesc", "Unknown")}
+Severity: {props.get("severity", "Unknown")}
+Description: {props.get("description", "No description available")}
+Instructions: {props.get("instruction", "No specific instructions provided")}
+"""
+
+
+@mcp.tool()
+async def get_alerts(state: str) -> str:
+ """Get weather alerts for a US state.
+
+ Args:
+ state: Two-letter US state code (e.g. CA, NY)
+```
+
+This function is important because it defines how MCP Quickstart Resources Tutorial: Cross-Language MCP Servers and Clients by Example implements the patterns covered in this chapter.
+
+### `weather-server-python/weather.py`
+
+The `format_alert` function in [`weather-server-python/weather.py`](https://github.com/modelcontextprotocol/quickstart-resources/blob/HEAD/weather-server-python/weather.py) handles a key part of this chapter's functionality:
+
+```py
+
+
+def format_alert(feature: dict) -> str:
+ """Format an alert feature into a readable string."""
+ props = feature["properties"]
+ return f"""
+Event: {props.get("event", "Unknown")}
+Area: {props.get("areaDesc", "Unknown")}
+Severity: {props.get("severity", "Unknown")}
+Description: {props.get("description", "No description available")}
+Instructions: {props.get("instruction", "No specific instructions provided")}
+"""
+
+
+@mcp.tool()
+async def get_alerts(state: str) -> str:
+ """Get weather alerts for a US state.
+
+ Args:
+ state: Two-letter US state code (e.g. CA, NY)
+ """
+ url = f"{NWS_API_BASE}/alerts/active/area/{state}"
+ data = await make_nws_request(url)
+
+ if not data or "features" not in data:
+ return "Unable to fetch alerts or no alerts found."
+
+ if not data["features"]:
+ return "No active alerts for this state."
+
+ alerts = [format_alert(feature) for feature in data["features"]]
+ return "\n---\n".join(alerts)
+```
+
+This function is important because it defines how MCP Quickstart Resources Tutorial: Cross-Language MCP Servers and Clients by Example implements the patterns covered in this chapter.
+
+### `weather-server-python/weather.py`
+
+The `get_alerts` function in [`weather-server-python/weather.py`](https://github.com/modelcontextprotocol/quickstart-resources/blob/HEAD/weather-server-python/weather.py) handles a key part of this chapter's functionality:
+
+```py
+
+@mcp.tool()
+async def get_alerts(state: str) -> str:
+ """Get weather alerts for a US state.
+
+ Args:
+ state: Two-letter US state code (e.g. CA, NY)
+ """
+ url = f"{NWS_API_BASE}/alerts/active/area/{state}"
+ data = await make_nws_request(url)
+
+ if not data or "features" not in data:
+ return "Unable to fetch alerts or no alerts found."
+
+ if not data["features"]:
+ return "No active alerts for this state."
+
+ alerts = [format_alert(feature) for feature in data["features"]]
+ return "\n---\n".join(alerts)
+
+
+@mcp.tool()
+async def get_forecast(latitude: float, longitude: float) -> str:
+ """Get weather forecast for a location.
+
+ Args:
+ latitude: Latitude of the location
+ longitude: Longitude of the location
+ """
+ # First get the forecast grid endpoint
+ points_url = f"{NWS_API_BASE}/points/{latitude},{longitude}"
+ points_data = await make_nws_request(points_url)
+```
+
+This function is important because it defines how MCP Quickstart Resources Tutorial: Cross-Language MCP Servers and Clients by Example implements the patterns covered in this chapter.
+
## How These Components Connect
```mermaid
flowchart TD
- A[formatPeriod]
- B[getForecast]
- C[getAlerts]
- D[main]
- E[MCPClient]
+ A[main]
+ B[make_nws_request]
+ C[format_alert]
+ D[get_alerts]
+ E[get_forecast]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-quickstart-resources-tutorial/05-smoke-tests-and-mock-infrastructure.md b/tutorials/mcp-quickstart-resources-tutorial/05-smoke-tests-and-mock-infrastructure.md
index 5e406540..2b11a768 100644
--- a/tutorials/mcp-quickstart-resources-tutorial/05-smoke-tests-and-mock-infrastructure.md
+++ b/tutorials/mcp-quickstart-resources-tutorial/05-smoke-tests-and-mock-infrastructure.md
@@ -39,91 +39,26 @@ You now have a repeatable validation loop for quickstart server/client quality.
Next: [Chapter 6: Cross-Language Consistency and Extension Strategy](06-cross-language-consistency-and-extension-strategy.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `mcp-client-typescript/index.ts`
-
-The `main` function in [`mcp-client-typescript/index.ts`](https://github.com/modelcontextprotocol/quickstart-resources/blob/HEAD/mcp-client-typescript/index.ts) handles a key part of this chapter's functionality:
-
-```ts
-}
-
-async function main() {
- if (process.argv.length < 3) {
- console.log("Usage: node build/index.js <path_to_server_script>");
- return;
- }
- const mcpClient = new MCPClient();
- try {
- await mcpClient.connectToServer(process.argv[2]);
-
- // Check if we have a valid API key to continue
- const apiKey = process.env.ANTHROPIC_API_KEY;
- if (!apiKey) {
- console.log(
- "\nNo ANTHROPIC_API_KEY found. To query these tools with Claude, set your API key:"
- );
- console.log(" export ANTHROPIC_API_KEY=your-api-key-here");
- return;
- }
-
- await mcpClient.chatLoop();
- } catch (e) {
- console.error("Error:", e);
- await mcpClient.cleanup();
- process.exit(1);
- } finally {
- await mcpClient.cleanup();
- process.exit(0);
- }
-}
-
-```
-
-This function is important because it defines how MCP Quickstart Resources Tutorial: Cross-Language MCP Servers and Clients by Example implements the patterns covered in this chapter.
-
-### `mcp-client-rust/src/main.rs`
+### `weather-server-python/weather.py`
-The `MCPClient` interface in [`mcp-client-rust/src/main.rs`](https://github.com/modelcontextprotocol/quickstart-resources/blob/HEAD/mcp-client-rust/src/main.rs) handles a key part of this chapter's functionality:
+The `main` function in [`weather-server-python/weather.py`](https://github.com/modelcontextprotocol/quickstart-resources/blob/HEAD/weather-server-python/weather.py) handles a key part of this chapter's functionality:
-```rs
-const MODEL_ANTHROPIC: &str = "claude-sonnet-4-20250514";
+```py
-struct MCPClient {
- anthropic: Client,
- session: Option<RunningService<RoleClient, ()>>,
- tools: Vec<GenaiTool>,
-}
-
-impl MCPClient {
- fn new() -> Result<Self> {
- Ok(MCPClient {
- anthropic: Client::default(),
- session: None,
- tools: Vec::new(),
- })
- }
- async fn connect_to_server(&mut self, server_args: &[String]) -> Result<()> {
- if self.session.is_some() {
- bail!("Client is already connected to a server");
- }
+def main():
+ # Initialize and run the server
+ mcp.run(transport="stdio")
- let mut command = Command::new(&server_args[0]);
- command.args(&server_args[1..]);
- let process = TokioChildProcess::new(command)
- .with_context(|| format!("Failed to spawn server process for {:?}", server_args))?;
+if __name__ == "__main__":
+ main()
- let session = ().serve(process).await?;
-
- let rmcp_tools = session
- .list_all_tools()
```
-This interface is important because it defines how MCP Quickstart Resources Tutorial: Cross-Language MCP Servers and Clients by Example implements the patterns covered in this chapter.
+This function is important because it defines how MCP Quickstart Resources Tutorial: Cross-Language MCP Servers and Clients by Example implements the patterns covered in this chapter.
### `weather-server-typescript/src/index.ts`
@@ -188,16 +123,57 @@ main().catch((error) => {
This function is important because it defines how MCP Quickstart Resources Tutorial: Cross-Language MCP Servers and Clients by Example implements the patterns covered in this chapter.
+### `weather-server-typescript/src/index.ts`
+
+The `AlertFeature` interface in [`weather-server-typescript/src/index.ts`](https://github.com/modelcontextprotocol/quickstart-resources/blob/HEAD/weather-server-typescript/src/index.ts) handles a key part of this chapter's functionality:
+
+```ts
+}
+
+interface AlertFeature {
+ properties: {
+ event?: string;
+ areaDesc?: string;
+ severity?: string;
+ status?: string;
+ headline?: string;
+ };
+}
+
+// Format alert data
+function formatAlert(feature: AlertFeature): string {
+ const props = feature.properties;
+ return [
+ `Event: ${props.event || "Unknown"}`,
+ `Area: ${props.areaDesc || "Unknown"}`,
+ `Severity: ${props.severity || "Unknown"}`,
+ `Status: ${props.status || "Unknown"}`,
+ `Headline: ${props.headline || "No headline"}`,
+ "---",
+ ].join("\n");
+}
+
+interface ForecastPeriod {
+ name?: string;
+ temperature?: number;
+ temperatureUnit?: string;
+ windSpeed?: string;
+ windDirection?: string;
+ shortForecast?: string;
+```
+
+This interface is important because it defines how MCP Quickstart Resources Tutorial: Cross-Language MCP Servers and Clients by Example implements the patterns covered in this chapter.
+
## How These Components Connect
```mermaid
flowchart TD
A[main]
- B[MCPClient]
- C[formatAlert]
- D[main]
- E[AlertFeature]
+ B[formatAlert]
+ C[main]
+ D[AlertFeature]
+ E[ForecastPeriod]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-quickstart-resources-tutorial/06-cross-language-consistency-and-extension-strategy.md b/tutorials/mcp-quickstart-resources-tutorial/06-cross-language-consistency-and-extension-strategy.md
index 41393836..7d8eaf1f 100644
--- a/tutorials/mcp-quickstart-resources-tutorial/06-cross-language-consistency-and-extension-strategy.md
+++ b/tutorials/mcp-quickstart-resources-tutorial/06-cross-language-consistency-and-extension-strategy.md
@@ -38,53 +38,10 @@ You now have a strategy for controlled multi-language MCP feature evolution.
Next: [Chapter 7: CI, Toolchain Setup, and Troubleshooting](07-ci-toolchain-setup-and-troubleshooting.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `weather-server-typescript/src/index.ts`
-The `ForecastPeriod` interface in [`weather-server-typescript/src/index.ts`](https://github.com/modelcontextprotocol/quickstart-resources/blob/HEAD/weather-server-typescript/src/index.ts) handles a key part of this chapter's functionality:
-
-```ts
-}
-
-interface ForecastPeriod {
- name?: string;
- temperature?: number;
- temperatureUnit?: string;
- windSpeed?: string;
- windDirection?: string;
- shortForecast?: string;
-}
-
-interface AlertsResponse {
- features: AlertFeature[];
-}
-
-interface PointsResponse {
- properties: {
- forecast?: string;
- };
-}
-
-interface ForecastResponse {
- properties: {
- periods: ForecastPeriod[];
- };
-}
-
-// Create server instance
-const server = new McpServer({
- name: "weather",
- version: "1.0.0",
-});
-```
-
-This interface is important because it defines how MCP Quickstart Resources Tutorial: Cross-Language MCP Servers and Clients by Example implements the patterns covered in this chapter.
-
-### `weather-server-typescript/src/index.ts`
-
The `AlertsResponse` interface in [`weather-server-typescript/src/index.ts`](https://github.com/modelcontextprotocol/quickstart-resources/blob/HEAD/weather-server-typescript/src/index.ts) handles a key part of this chapter's functionality:
```ts
@@ -206,16 +163,57 @@ server.registerTool(
This interface is important because it defines how MCP Quickstart Resources Tutorial: Cross-Language MCP Servers and Clients by Example implements the patterns covered in this chapter.
+### `weather-server-rust/src/main.rs`
+
+The `AlertsResponse` interface in [`weather-server-rust/src/main.rs`](https://github.com/modelcontextprotocol/quickstart-resources/blob/HEAD/weather-server-rust/src/main.rs) handles a key part of this chapter's functionality:
+
+```rs
+
+#[derive(Debug, Deserialize)]
+struct AlertsResponse {
+ features: Vec<AlertFeature>,
+}
+
+#[derive(Debug, Deserialize)]
+struct AlertFeature {
+ properties: AlertProperties,
+}
+
+#[derive(Debug, Deserialize)]
+struct AlertProperties {
+ event: Option<String>,
+ #[serde(rename = "areaDesc")]
+ area_desc: Option<String>,
+ severity: Option<String>,
+ description: Option<String>,
+ instruction: Option<String>,
+}
+
+#[derive(Debug, Deserialize)]
+struct PointsResponse {
+ properties: PointsProperties,
+}
+
+#[derive(Debug, Deserialize)]
+struct PointsProperties {
+ forecast: String,
+}
+
+#[derive(Debug, Deserialize)]
+```
+
+This interface is important because it defines how MCP Quickstart Resources Tutorial: Cross-Language MCP Servers and Clients by Example implements the patterns covered in this chapter.
+
## How These Components Connect
```mermaid
flowchart TD
- A[ForecastPeriod]
- B[AlertsResponse]
- C[PointsResponse]
- D[ForecastResponse]
- E[AlertsResponse]
+ A[AlertsResponse]
+ B[PointsResponse]
+ C[ForecastResponse]
+ D[AlertsResponse]
+ E[AlertFeature]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-quickstart-resources-tutorial/07-ci-toolchain-setup-and-troubleshooting.md b/tutorials/mcp-quickstart-resources-tutorial/07-ci-toolchain-setup-and-troubleshooting.md
index d27cc011..6a47c53c 100644
--- a/tutorials/mcp-quickstart-resources-tutorial/07-ci-toolchain-setup-and-troubleshooting.md
+++ b/tutorials/mcp-quickstart-resources-tutorial/07-ci-toolchain-setup-and-troubleshooting.md
@@ -31,20 +31,13 @@ You now have an operations baseline for sustaining quickstart-based development
Next: [Chapter 8: From Tutorial Assets to Production Systems](08-from-tutorial-assets-to-production-systems.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `weather-server-rust/src/main.rs`
-The `AlertFeature` interface in [`weather-server-rust/src/main.rs`](https://github.com/modelcontextprotocol/quickstart-resources/blob/HEAD/weather-server-rust/src/main.rs) handles a key part of this chapter's functionality:
+The `AlertProperties` interface in [`weather-server-rust/src/main.rs`](https://github.com/modelcontextprotocol/quickstart-resources/blob/HEAD/weather-server-rust/src/main.rs) handles a key part of this chapter's functionality:
```rs
-#[derive(Debug, Deserialize)]
-struct AlertsResponse {
- features: Vec<AlertFeature>,
-}
-
#[derive(Debug, Deserialize)]
struct AlertFeature {
properties: AlertProperties,
@@ -72,29 +65,20 @@ struct PointsProperties {
#[derive(Debug, Deserialize)]
struct ForecastResponse {
+ properties: ForecastProperties,
+}
+
+#[derive(Debug, Deserialize)]
+struct ForecastProperties {
```
This interface is important because it defines how MCP Quickstart Resources Tutorial: Cross-Language MCP Servers and Clients by Example implements the patterns covered in this chapter.
### `weather-server-rust/src/main.rs`
-The `AlertProperties` interface in [`weather-server-rust/src/main.rs`](https://github.com/modelcontextprotocol/quickstart-resources/blob/HEAD/weather-server-rust/src/main.rs) handles a key part of this chapter's functionality:
+The `PointsResponse` interface in [`weather-server-rust/src/main.rs`](https://github.com/modelcontextprotocol/quickstart-resources/blob/HEAD/weather-server-rust/src/main.rs) handles a key part of this chapter's functionality:
```rs
-#[derive(Debug, Deserialize)]
-struct AlertFeature {
- properties: AlertProperties,
-}
-
-#[derive(Debug, Deserialize)]
-struct AlertProperties {
- event: Option<String>,
- #[serde(rename = "areaDesc")]
- area_desc: Option<String>,
- severity: Option<String>,
- description: Option<String>,
- instruction: Option<String>,
-}
#[derive(Debug, Deserialize)]
struct PointsResponse {
@@ -113,16 +97,29 @@ struct ForecastResponse {
#[derive(Debug, Deserialize)]
struct ForecastProperties {
+ periods: Vec<ForecastPeriod>,
+}
+
+#[derive(Debug, Deserialize)]
+struct ForecastPeriod {
+ name: String,
+ temperature: i32,
+ #[serde(rename = "temperatureUnit")]
+ temperature_unit: String,
+ #[serde(rename = "windSpeed")]
+ wind_speed: String,
+ #[serde(rename = "windDirection")]
+ wind_direction: String,
+ #[serde(rename = "detailedForecast")]
```
This interface is important because it defines how MCP Quickstart Resources Tutorial: Cross-Language MCP Servers and Clients by Example implements the patterns covered in this chapter.
### `weather-server-rust/src/main.rs`
-The `PointsResponse` interface in [`weather-server-rust/src/main.rs`](https://github.com/modelcontextprotocol/quickstart-resources/blob/HEAD/weather-server-rust/src/main.rs) handles a key part of this chapter's functionality:
+The `PointsProperties` interface in [`weather-server-rust/src/main.rs`](https://github.com/modelcontextprotocol/quickstart-resources/blob/HEAD/weather-server-rust/src/main.rs) handles a key part of this chapter's functionality:
```rs
-
#[derive(Debug, Deserialize)]
struct PointsResponse {
properties: PointsProperties,
@@ -154,24 +151,16 @@ struct ForecastPeriod {
#[serde(rename = "windDirection")]
wind_direction: String,
#[serde(rename = "detailedForecast")]
+ detailed_forecast: String,
```
This interface is important because it defines how MCP Quickstart Resources Tutorial: Cross-Language MCP Servers and Clients by Example implements the patterns covered in this chapter.
### `weather-server-rust/src/main.rs`
-The `PointsProperties` interface in [`weather-server-rust/src/main.rs`](https://github.com/modelcontextprotocol/quickstart-resources/blob/HEAD/weather-server-rust/src/main.rs) handles a key part of this chapter's functionality:
+The `ForecastResponse` interface in [`weather-server-rust/src/main.rs`](https://github.com/modelcontextprotocol/quickstart-resources/blob/HEAD/weather-server-rust/src/main.rs) handles a key part of this chapter's functionality:
```rs
-#[derive(Debug, Deserialize)]
-struct PointsResponse {
- properties: PointsProperties,
-}
-
-#[derive(Debug, Deserialize)]
-struct PointsProperties {
- forecast: String,
-}
#[derive(Debug, Deserialize)]
struct ForecastResponse {
@@ -195,6 +184,15 @@ struct ForecastPeriod {
wind_direction: String,
#[serde(rename = "detailedForecast")]
detailed_forecast: String,
+}
+
+async fn make_nws_request<T: DeserializeOwned>(url: &str) -> Result<T> {
+ let client = reqwest::Client::new();
+ let rsp = client
+ .get(url)
+ .header(reqwest::header::USER_AGENT, USER_AGENT)
+ .header(reqwest::header::ACCEPT, "application/geo+json")
+ .send()
```
This interface is important because it defines how MCP Quickstart Resources Tutorial: Cross-Language MCP Servers and Clients by Example implements the patterns covered in this chapter.
@@ -204,11 +202,11 @@ This interface is important because it defines how MCP Quickstart Resources Tuto
```mermaid
flowchart TD
- A[AlertFeature]
- B[AlertProperties]
- C[PointsResponse]
- D[PointsProperties]
- E[ForecastResponse]
+ A[AlertProperties]
+ B[PointsResponse]
+ C[PointsProperties]
+ D[ForecastResponse]
+ E[ForecastProperties]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-quickstart-resources-tutorial/08-from-tutorial-assets-to-production-systems.md b/tutorials/mcp-quickstart-resources-tutorial/08-from-tutorial-assets-to-production-systems.md
index 7bfe9f9d..f849ab8c 100644
--- a/tutorials/mcp-quickstart-resources-tutorial/08-from-tutorial-assets-to-production-systems.md
+++ b/tutorials/mcp-quickstart-resources-tutorial/08-from-tutorial-assets-to-production-systems.md
@@ -41,53 +41,10 @@ You now have a roadmap for evolving quickstart MCP assets into durable productio
Return to the [MCP Quickstart Resources Tutorial index](README.md).
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `weather-server-rust/src/main.rs`
-The `ForecastProperties` interface in [`weather-server-rust/src/main.rs`](https://github.com/modelcontextprotocol/quickstart-resources/blob/HEAD/weather-server-rust/src/main.rs) handles a key part of this chapter's functionality:
-
-```rs
-#[derive(Debug, Deserialize)]
-struct ForecastResponse {
- properties: ForecastProperties,
-}
-
-#[derive(Debug, Deserialize)]
-struct ForecastProperties {
- periods: Vec<ForecastPeriod>,
-}
-
-#[derive(Debug, Deserialize)]
-struct ForecastPeriod {
- name: String,
- temperature: i32,
- #[serde(rename = "temperatureUnit")]
- temperature_unit: String,
- #[serde(rename = "windSpeed")]
- wind_speed: String,
- #[serde(rename = "windDirection")]
- wind_direction: String,
- #[serde(rename = "detailedForecast")]
- detailed_forecast: String,
-}
-
-async fn make_nws_request<T: DeserializeOwned>(url: &str) -> Result<T> {
- let client = reqwest::Client::new();
- let rsp = client
- .get(url)
- .header(reqwest::header::USER_AGENT, USER_AGENT)
- .header(reqwest::header::ACCEPT, "application/geo+json")
- .send()
- .await?
-```
-
-This interface is important because it defines how MCP Quickstart Resources Tutorial: Cross-Language MCP Servers and Clients by Example implements the patterns covered in this chapter.
-
-### `weather-server-rust/src/main.rs`
-
The `ForecastPeriod` interface in [`weather-server-rust/src/main.rs`](https://github.com/modelcontextprotocol/quickstart-resources/blob/HEAD/weather-server-rust/src/main.rs) handles a key part of this chapter's functionality:
```rs
@@ -209,16 +166,57 @@ impl Weather {
This interface is important because it defines how MCP Quickstart Resources Tutorial: Cross-Language MCP Servers and Clients by Example implements the patterns covered in this chapter.
+### `weather-server-rust/src/main.rs`
+
+The `Weather` interface in [`weather-server-rust/src/main.rs`](https://github.com/modelcontextprotocol/quickstart-resources/blob/HEAD/weather-server-rust/src/main.rs) handles a key part of this chapter's functionality:
+
+```rs
+}
+
+pub struct Weather {
+ tool_router: ToolRouter<Weather>,
+}
+
+#[tool_router]
+impl Weather {
+ fn new() -> Self {
+ Self {
+ tool_router: Self::tool_router(),
+ }
+ }
+
+ #[tool(description = "Get weather alerts for a US state.")]
+ async fn get_alerts(
+ &self,
+ Parameters(MCPAlertRequest { state }): Parameters<MCPAlertRequest>,
+ ) -> String {
+ let url = format!(
+ "{}/alerts/active/area/{}",
+ NWS_API_BASE,
+ state.to_uppercase()
+ );
+
+ match make_nws_request::<AlertsResponse>(&url).await {
+ Ok(data) => {
+ if data.features.is_empty() {
+ "No active alerts for this state.".to_string()
+ } else {
+ data.features
+ .iter()
+```
+
+This interface is important because it defines how MCP Quickstart Resources Tutorial: Cross-Language MCP Servers and Clients by Example implements the patterns covered in this chapter.
+
## How These Components Connect
```mermaid
flowchart TD
- A[ForecastProperties]
- B[ForecastPeriod]
- C[MCPForecastRequest]
- D[MCPAlertRequest]
- E[Weather]
+ A[ForecastPeriod]
+ B[MCPForecastRequest]
+ C[MCPAlertRequest]
+ D[Weather]
+ E[MCPClient]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-registry-tutorial/01-getting-started-and-first-publish.md b/tutorials/mcp-registry-tutorial/01-getting-started-and-first-publish.md
index bec1a29f..24a8433d 100644
--- a/tutorials/mcp-registry-tutorial/01-getting-started-and-first-publish.md
+++ b/tutorials/mcp-registry-tutorial/01-getting-started-and-first-publish.md
@@ -55,8 +55,6 @@ You now have a working baseline for first publication.
Next: [Chapter 2: Registry Architecture and Data Flow](02-registry-architecture-and-data-flow.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `deploy/main.go`
@@ -139,82 +137,84 @@ func createProvider(ctx *pulumi.Context) (providers.ClusterProvider, error) {
This function is important because it defines how MCP Registry Tutorial: Publishing, Discovery, and Governance for MCP Servers implements the patterns covered in this chapter.
-### `cmd/publisher/main.go`
+### `internal/validators/schema.go`
-The `main` function in [`cmd/publisher/main.go`](https://github.com/modelcontextprotocol/registry/blob/HEAD/cmd/publisher/main.go) handles a key part of this chapter's functionality:
+The `extractVersionFromSchemaURL` function in [`internal/validators/schema.go`](https://github.com/modelcontextprotocol/registry/blob/HEAD/internal/validators/schema.go) handles a key part of this chapter's functionality:
```go
-package main
-
-import (
- "fmt"
- "log"
- "os"
-
- "github.com/modelcontextprotocol/registry/cmd/publisher/commands"
-)
-
-// Version info for the MCP Publisher tool
-// These variables are injected at build time via ldflags by goreleaser
-var (
- // Version is the current version of the MCP Publisher tool
- Version = "dev"
-
- // BuildTime is the time at which the binary was built
- BuildTime = "unknown"
-
- // GitCommit is the git commit that was compiled
- GitCommit = "unknown"
-)
+var schemaFS embed.FS
+
+// extractVersionFromSchemaURL extracts the version identifier from a schema URL
+// e.g., "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json" -> "2025-10-17"
+// e.g., "https://static.modelcontextprotocol.io/schemas/draft/server.schema.json" -> "draft"
+// Version identifier can contain: A-Z, a-z, 0-9, hyphen (-), underscore (_), tilde (~), and period (.)
+func extractVersionFromSchemaURL(schemaURL string) (string, error) {
+ // Pattern: /schemas/{identifier}/server.schema.json
+ // Identifier allowed characters: A-Z, a-z, 0-9, -, _, ~, .
+ re := regexp.MustCompile(`/schemas/([A-Za-z0-9_~.-]+)/server\.schema\.json`)
+ matches := re.FindStringSubmatch(schemaURL)
+ if len(matches) < 2 {
+ return "", fmt.Errorf("invalid schema URL format: %s", schemaURL)
+ }
+ return matches[1], nil
+}
-func main() {
- if len(os.Args) < 2 {
- printUsage()
- os.Exit(1)
+// loadSchemaByVersion loads a schema file from the embedded filesystem by version
+func loadSchemaByVersion(version string) ([]byte, error) {
+ filename := fmt.Sprintf("schemas/%s.json", version)
+ data, err := schemaFS.ReadFile(filename)
+ if err != nil {
+ return nil, fmt.Errorf("schema version %s not found in embedded schemas: %w", version, err)
}
+ return data, nil
+}
+
+// GetCurrentSchemaVersion returns the current schema URL from constants
+func GetCurrentSchemaVersion() (string, error) {
+ return model.CurrentSchemaURL, nil
+}
- // Check for help flag for subcommands
```
This function is important because it defines how MCP Registry Tutorial: Publishing, Discovery, and Governance for MCP Servers implements the patterns covered in this chapter.
-### `cmd/publisher/main.go`
+### `internal/validators/schema.go`
-The `printUsage` function in [`cmd/publisher/main.go`](https://github.com/modelcontextprotocol/registry/blob/HEAD/cmd/publisher/main.go) handles a key part of this chapter's functionality:
+The `loadSchemaByVersion` function in [`internal/validators/schema.go`](https://github.com/modelcontextprotocol/registry/blob/HEAD/internal/validators/schema.go) handles a key part of this chapter's functionality:
```go
-func main() {
- if len(os.Args) < 2 {
- printUsage()
- os.Exit(1)
- }
+}
- // Check for help flag for subcommands
- if len(os.Args) >= 3 && (os.Args[2] == "--help" || os.Args[2] == "-h") {
- printCommandHelp(os.Args[1])
- return
+// loadSchemaByVersion loads a schema file from the embedded filesystem by version
+func loadSchemaByVersion(version string) ([]byte, error) {
+ filename := fmt.Sprintf("schemas/%s.json", version)
+ data, err := schemaFS.ReadFile(filename)
+ if err != nil {
+ return nil, fmt.Errorf("schema version %s not found in embedded schemas: %w", version, err)
}
+ return data, nil
+}
- var err error
- switch os.Args[1] {
- case "init":
- err = commands.InitCommand()
- case "login":
- err = commands.LoginCommand(os.Args[2:])
- case "logout":
- err = commands.LogoutCommand()
- case "publish":
- err = commands.PublishCommand(os.Args[2:])
- case "status":
- err = commands.StatusCommand(os.Args[2:])
- case "validate":
- err = commands.ValidateCommand(os.Args[2:])
- case "--version", "-v", "version":
- log.Printf("mcp-publisher %s (commit: %s, built: %s)", Version, GitCommit, BuildTime)
- return
- case "--help", "-h", "help":
- printUsage()
- default:
+// GetCurrentSchemaVersion returns the current schema URL from constants
+func GetCurrentSchemaVersion() (string, error) {
+ return model.CurrentSchemaURL, nil
+}
+
+// validateServerJSONSchema validates the server JSON against the schema version specified in $schema using jsonschema
+// Empty/missing schema always produces an error.
+// If performValidation is true, performs full JSON Schema validation.
+// If performValidation is false, only checks for empty schema (always an error) and handles non-current schemas per policy.
+// nonCurrentPolicy determines how non-current (but valid) schema versions are handled when performValidation is true.
+func validateServerJSONSchema(serverJSON *apiv0.ServerJSON, performValidation bool, nonCurrentPolicy SchemaVersionPolicy) *ValidationResult {
+ result := &ValidationResult{Valid: true, Issues: []ValidationIssue{}}
+ ctx := &ValidationContext{}
+
+ // Empty/missing schema is always an error
+ if serverJSON.Schema == "" {
+ issue := NewValidationIssue(
+ ValidationIssueTypeSemantic,
+ ctx.Field("schema").String(),
+ "$schema field is required",
```
This function is important because it defines how MCP Registry Tutorial: Publishing, Discovery, and Governance for MCP Servers implements the patterns covered in this chapter.
@@ -226,9 +226,9 @@ This function is important because it defines how MCP Registry Tutorial: Publish
flowchart TD
A[createProvider]
B[main]
- C[main]
- D[printUsage]
- E[printCommandHelp]
+ C[extractVersionFromSchemaURL]
+ D[loadSchemaByVersion]
+ E[GetCurrentSchemaVersion]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-registry-tutorial/02-registry-architecture-and-data-flow.md b/tutorials/mcp-registry-tutorial/02-registry-architecture-and-data-flow.md
index 3790fdcb..8dc90cac 100644
--- a/tutorials/mcp-registry-tutorial/02-registry-architecture-and-data-flow.md
+++ b/tutorials/mcp-registry-tutorial/02-registry-architecture-and-data-flow.md
@@ -45,170 +45,168 @@ You now have a system-level model for registry behavior.
Next: [Chapter 3: server.json Schema and Package Verification](03-server-json-schema-and-package-verification.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `internal/validators/validators.go`
+### `internal/service/registry_service.go`
-The `validateNamedArgumentName` function in [`internal/validators/validators.go`](https://github.com/modelcontextprotocol/registry/blob/HEAD/internal/validators/validators.go) handles a key part of this chapter's functionality:
+The `ListServers` function in [`internal/service/registry_service.go`](https://github.com/modelcontextprotocol/registry/blob/HEAD/internal/service/registry_service.go) handles a key part of this chapter's functionality:
```go
- if obj.Type == model.ArgumentTypeNamed {
- // Validate named argument name format
- nameResult := validateNamedArgumentName(ctx.Field("name"), obj.Name)
- result.Merge(nameResult)
-
- // Validate value and default don't start with the name
- valueResult := validateArgumentValueFields(ctx, obj.Name, obj.Value, obj.Default)
- result.Merge(valueResult)
+}
+
+// ListServers returns registry entries with cursor-based pagination and optional filtering
+func (s *registryServiceImpl) ListServers(ctx context.Context, filter *database.ServerFilter, cursor string, limit int) ([]*apiv0.ServerResponse, string, error) {
+ // If limit is not set or negative, use a default limit
+ if limit <= 0 {
+ limit = 30
}
- return result
+
+ // Use the database's ListServers method with pagination and filtering
+ serverRecords, nextCursor, err := s.db.ListServers(ctx, nil, filter, cursor, limit)
+ if err != nil {
+ return nil, "", err
+ }
+
+ return serverRecords, nextCursor, nil
}
-func validateNamedArgumentName(ctx *ValidationContext, name string) *ValidationResult {
- result := &ValidationResult{Valid: true, Issues: []ValidationIssue{}}
-
- // Check if name is required for named arguments
- if name == "" {
- issue := NewValidationIssueFromError(
- ValidationIssueTypeSemantic,
- ctx.String(),
- ErrNamedArgumentNameRequired,
- "named-argument-name-required",
- )
- result.AddIssue(issue)
- return result
+// GetServerByName retrieves the latest version of a server by its server name
+func (s *registryServiceImpl) GetServerByName(ctx context.Context, serverName string, includeDeleted bool) (*apiv0.ServerResponse, error) {
+ serverRecord, err := s.db.GetServerByName(ctx, nil, serverName, includeDeleted)
+ if err != nil {
+ return nil, err
}
- // Check for invalid characters that suggest embedded values or descriptions
- // Valid: "--directory", "--port", "-v", "config", "verbose"
- // Invalid: "--directory <absolute_path_to_adfin_mcp_folder>", "--port 8080"
- if strings.Contains(name, "<") || strings.Contains(name, ">") ||
- strings.Contains(name, " ") || strings.Contains(name, "$") {
+ return serverRecord, nil
+}
+
+// GetServerByNameAndVersion retrieves a specific version of a server by server name and version
+func (s *registryServiceImpl) GetServerByNameAndVersion(ctx context.Context, serverName string, version string, includeDeleted bool) (*apiv0.ServerResponse, error) {
+ serverRecord, err := s.db.GetServerByNameAndVersion(ctx, nil, serverName, version, includeDeleted)
+ if err != nil {
```
This function is important because it defines how MCP Registry Tutorial: Publishing, Discovery, and Governance for MCP Servers implements the patterns covered in this chapter.
-### `internal/validators/validators.go`
+### `internal/service/registry_service.go`
-The `validateArgumentValueFields` function in [`internal/validators/validators.go`](https://github.com/modelcontextprotocol/registry/blob/HEAD/internal/validators/validators.go) handles a key part of this chapter's functionality:
+The `GetServerByName` function in [`internal/service/registry_service.go`](https://github.com/modelcontextprotocol/registry/blob/HEAD/internal/service/registry_service.go) handles a key part of this chapter's functionality:
```go
+}
- // Validate value and default don't start with the name
- valueResult := validateArgumentValueFields(ctx, obj.Name, obj.Value, obj.Default)
- result.Merge(valueResult)
+// GetServerByName retrieves the latest version of a server by its server name
+func (s *registryServiceImpl) GetServerByName(ctx context.Context, serverName string, includeDeleted bool) (*apiv0.ServerResponse, error) {
+ serverRecord, err := s.db.GetServerByName(ctx, nil, serverName, includeDeleted)
+ if err != nil {
+ return nil, err
}
- return result
+
+ return serverRecord, nil
+}
+
+// GetServerByNameAndVersion retrieves a specific version of a server by server name and version
+func (s *registryServiceImpl) GetServerByNameAndVersion(ctx context.Context, serverName string, version string, includeDeleted bool) (*apiv0.ServerResponse, error) {
+ serverRecord, err := s.db.GetServerByNameAndVersion(ctx, nil, serverName, version, includeDeleted)
+ if err != nil {
+ return nil, err
+ }
+
+ return serverRecord, nil
}
-func validateNamedArgumentName(ctx *ValidationContext, name string) *ValidationResult {
- result := &ValidationResult{Valid: true, Issues: []ValidationIssue{}}
-
- // Check if name is required for named arguments
- if name == "" {
- issue := NewValidationIssueFromError(
- ValidationIssueTypeSemantic,
- ctx.String(),
- ErrNamedArgumentNameRequired,
- "named-argument-name-required",
- )
- result.AddIssue(issue)
- return result
+// GetAllVersionsByServerName retrieves all versions of a server by server name
+func (s *registryServiceImpl) GetAllVersionsByServerName(ctx context.Context, serverName string, includeDeleted bool) ([]*apiv0.ServerResponse, error) {
+ serverRecords, err := s.db.GetAllVersionsByServerName(ctx, nil, serverName, includeDeleted)
+ if err != nil {
+ return nil, err
}
- // Check for invalid characters that suggest embedded values or descriptions
- // Valid: "--directory", "--port", "-v", "config", "verbose"
- // Invalid: "--directory <absolute_path_to_adfin_mcp_folder>", "--port 8080"
- if strings.Contains(name, "<") || strings.Contains(name, ">") ||
- strings.Contains(name, " ") || strings.Contains(name, "$") {
- issue := NewValidationIssueFromError(
- ValidationIssueTypeSemantic,
- ctx.String(),
- fmt.Errorf("%w: %s", ErrInvalidNamedArgumentName, name),
+ return serverRecords, nil
+}
+
```
This function is important because it defines how MCP Registry Tutorial: Publishing, Discovery, and Governance for MCP Servers implements the patterns covered in this chapter.
-### `internal/validators/validators.go`
+### `internal/service/registry_service.go`
-The `collectAvailableVariables` function in [`internal/validators/validators.go`](https://github.com/modelcontextprotocol/registry/blob/HEAD/internal/validators/validators.go) handles a key part of this chapter's functionality:
+The `GetServerByNameAndVersion` function in [`internal/service/registry_service.go`](https://github.com/modelcontextprotocol/registry/blob/HEAD/internal/service/registry_service.go) handles a key part of this chapter's functionality:
```go
+}
- // Validate transport with template variable support
- availableVariables := collectAvailableVariables(obj)
- transportResult := validatePackageTransport(ctx.Field("transport"), &obj.Transport, availableVariables)
- result.Merge(transportResult)
+// GetServerByNameAndVersion retrieves a specific version of a server by server name and version
+func (s *registryServiceImpl) GetServerByNameAndVersion(ctx context.Context, serverName string, version string, includeDeleted bool) (*apiv0.ServerResponse, error) {
+ serverRecord, err := s.db.GetServerByNameAndVersion(ctx, nil, serverName, version, includeDeleted)
+ if err != nil {
+ return nil, err
+ }
- return result
+ return serverRecord, nil
}
-// validateVersion validates the version string.
-// NB: we decided that we would not enforce strict semver for version strings
-func validateVersion(ctx *ValidationContext, version string) *ValidationResult {
- result := &ValidationResult{Valid: true, Issues: []ValidationIssue{}}
-
- if version == "latest" {
- issue := NewValidationIssueFromError(
- ValidationIssueTypeSemantic,
- ctx.String(),
- ErrReservedVersionString,
- "reserved-version-string",
- )
- result.AddIssue(issue)
- return result
+// GetAllVersionsByServerName retrieves all versions of a server by server name
+func (s *registryServiceImpl) GetAllVersionsByServerName(ctx context.Context, serverName string, includeDeleted bool) ([]*apiv0.ServerResponse, error) {
+ serverRecords, err := s.db.GetAllVersionsByServerName(ctx, nil, serverName, includeDeleted)
+ if err != nil {
+ return nil, err
}
- // Reject semver range-like inputs
- if looksLikeVersionRange(version) {
- issue := NewValidationIssueFromError(
- ValidationIssueTypeSemantic,
- ctx.String(),
- fmt.Errorf("%w: %q", ErrVersionLooksLikeRange, version),
- "version-looks-like-range",
+ return serverRecords, nil
+}
+
+// CreateServer creates a new server version
+func (s *registryServiceImpl) CreateServer(ctx context.Context, req *apiv0.ServerJSON) (*apiv0.ServerResponse, error) {
+ // Wrap the entire operation in a transaction
+ return database.InTransactionT(ctx, s.db, func(ctx context.Context, tx pgx.Tx) (*apiv0.ServerResponse, error) {
+ return s.createServerInTransaction(ctx, tx, req)
+ })
+}
+
+// createServerInTransaction contains the actual CreateServer logic within a transaction
+func (s *registryServiceImpl) createServerInTransaction(ctx context.Context, tx pgx.Tx, req *apiv0.ServerJSON) (*apiv0.ServerResponse, error) {
```
This function is important because it defines how MCP Registry Tutorial: Publishing, Discovery, and Governance for MCP Servers implements the patterns covered in this chapter.
-### `internal/validators/validators.go`
+### `internal/service/registry_service.go`
-The `collectRemoteTransportVariables` function in [`internal/validators/validators.go`](https://github.com/modelcontextprotocol/registry/blob/HEAD/internal/validators/validators.go) handles a key part of this chapter's functionality:
+The `GetAllVersionsByServerName` function in [`internal/service/registry_service.go`](https://github.com/modelcontextprotocol/registry/blob/HEAD/internal/service/registry_service.go) handles a key part of this chapter's functionality:
```go
}
-// collectRemoteTransportVariables extracts available variable names from a remote transport
-func collectRemoteTransportVariables(transport *model.Transport) []string {
- var variables []string
-
- // Add variable names from the Variables map
- for variableName := range transport.Variables {
- if variableName != "" {
- variables = append(variables, variableName)
- }
+// GetAllVersionsByServerName retrieves all versions of a server by server name
+func (s *registryServiceImpl) GetAllVersionsByServerName(ctx context.Context, serverName string, includeDeleted bool) ([]*apiv0.ServerResponse, error) {
+ serverRecords, err := s.db.GetAllVersionsByServerName(ctx, nil, serverName, includeDeleted)
+ if err != nil {
+ return nil, err
}
- return variables
+ return serverRecords, nil
+}
+
+// CreateServer creates a new server version
+func (s *registryServiceImpl) CreateServer(ctx context.Context, req *apiv0.ServerJSON) (*apiv0.ServerResponse, error) {
+ // Wrap the entire operation in a transaction
+ return database.InTransactionT(ctx, s.db, func(ctx context.Context, tx pgx.Tx) (*apiv0.ServerResponse, error) {
+ return s.createServerInTransaction(ctx, tx, req)
+ })
}
-// validatePackageTransport validates a package's transport with templating support
-func validatePackageTransport(ctx *ValidationContext, transport *model.Transport, availableVariables []string) *ValidationResult {
- result := &ValidationResult{Valid: true, Issues: []ValidationIssue{}}
-
- // Validate transport type is supported
- switch transport.Type {
- case model.TransportTypeStdio:
- // Validate that URL is empty for stdio transport
- if transport.URL != "" {
- issue := NewValidationIssue(
- ValidationIssueTypeSemantic,
- ctx.Field("url").String(),
- fmt.Sprintf("url must be empty for %s transport type, got: %s", transport.Type, transport.URL),
- ValidationIssueSeverityError,
- "stdio-transport-url-not-empty",
- )
+// createServerInTransaction contains the actual CreateServer logic within a transaction
+func (s *registryServiceImpl) createServerInTransaction(ctx context.Context, tx pgx.Tx, req *apiv0.ServerJSON) (*apiv0.ServerResponse, error) {
+ // Validate the request
+ if err := validators.ValidatePublishRequest(ctx, *req, s.cfg); err != nil {
+ return nil, err
+ }
+
+ publishTime := time.Now()
+ serverJSON := *req
+
+ // Acquire advisory lock to prevent concurrent publishes of the same server
+ if err := s.db.AcquirePublishLock(ctx, tx, serverJSON.Name); err != nil {
```
This function is important because it defines how MCP Registry Tutorial: Publishing, Discovery, and Governance for MCP Servers implements the patterns covered in this chapter.
@@ -218,11 +216,11 @@ This function is important because it defines how MCP Registry Tutorial: Publish
```mermaid
flowchart TD
- A[validateNamedArgumentName]
- B[validateArgumentValueFields]
- C[collectAvailableVariables]
- D[collectRemoteTransportVariables]
- E[validatePackageTransport]
+ A[ListServers]
+ B[GetServerByName]
+ C[GetServerByNameAndVersion]
+ D[GetAllVersionsByServerName]
+ E[CreateServer]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-registry-tutorial/03-server-json-schema-and-package-verification.md b/tutorials/mcp-registry-tutorial/03-server-json-schema-and-package-verification.md
index 4f8170be..26981991 100644
--- a/tutorials/mcp-registry-tutorial/03-server-json-schema-and-package-verification.md
+++ b/tutorials/mcp-registry-tutorial/03-server-json-schema-and-package-verification.md
@@ -46,170 +46,168 @@ You can now design metadata that is far less likely to fail publication checks.
Next: [Chapter 4: Authentication Models and Namespace Ownership](04-authentication-models-and-namespace-ownership.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `internal/service/registry_service.go`
+### `internal/validators/validators.go`
-The `GetAllVersionsByServerName` function in [`internal/service/registry_service.go`](https://github.com/modelcontextprotocol/registry/blob/HEAD/internal/service/registry_service.go) handles a key part of this chapter's functionality:
+The `validateRepository` function in [`internal/validators/validators.go`](https://github.com/modelcontextprotocol/registry/blob/HEAD/internal/validators/validators.go) handles a key part of this chapter's functionality:
```go
-}
-// GetAllVersionsByServerName retrieves all versions of a server by server name
-func (s *registryServiceImpl) GetAllVersionsByServerName(ctx context.Context, serverName string, includeDeleted bool) ([]*apiv0.ServerResponse, error) {
- serverRecords, err := s.db.GetAllVersionsByServerName(ctx, nil, serverName, includeDeleted)
- if err != nil {
- return nil, err
- }
+ // Validate repository
+ repoResult := validateRepository(ctx.Field("repository"), serverJSON.Repository)
+ result.Merge(repoResult)
- return serverRecords, nil
-}
+ // Validate website URL if provided
+ websiteResult := validateWebsiteURL(ctx.Field("websiteUrl"), serverJSON.WebsiteURL)
+ result.Merge(websiteResult)
-// CreateServer creates a new server version
-func (s *registryServiceImpl) CreateServer(ctx context.Context, req *apiv0.ServerJSON) (*apiv0.ServerResponse, error) {
- // Wrap the entire operation in a transaction
- return database.InTransactionT(ctx, s.db, func(ctx context.Context, tx pgx.Tx) (*apiv0.ServerResponse, error) {
- return s.createServerInTransaction(ctx, tx, req)
- })
-}
+ // Validate title if provided
+ titleResult := validateTitle(ctx.Field("title"), serverJSON.Title)
+ result.Merge(titleResult)
+
+ // Validate icons if provided
+ iconsResult := validateIcons(ctx.Field("icons"), serverJSON.Icons)
+ result.Merge(iconsResult)
-// createServerInTransaction contains the actual CreateServer logic within a transaction
-func (s *registryServiceImpl) createServerInTransaction(ctx context.Context, tx pgx.Tx, req *apiv0.ServerJSON) (*apiv0.ServerResponse, error) {
- // Validate the request
- if err := validators.ValidatePublishRequest(ctx, *req, s.cfg); err != nil {
- return nil, err
+ // Validate all packages (basic field validation)
+ // Detailed package validation (including registry checks) is done during publish
+ for i, pkg := range serverJSON.Packages {
+ pkgResult := validatePackageField(ctx.Field("packages").Index(i), &pkg)
+ result.Merge(pkgResult)
}
- publishTime := time.Now()
- serverJSON := *req
+ // Validate all remotes
+ for i, remote := range serverJSON.Remotes {
+ remoteResult := validateRemoteTransport(ctx.Field("remotes").Index(i), &remote)
+ result.Merge(remoteResult)
+ }
- // Acquire advisory lock to prevent concurrent publishes of the same server
- if err := s.db.AcquirePublishLock(ctx, tx, serverJSON.Name); err != nil {
+ return result
+}
```
This function is important because it defines how MCP Registry Tutorial: Publishing, Discovery, and Governance for MCP Servers implements the patterns covered in this chapter.
-### `internal/service/registry_service.go`
+### `internal/validators/validators.go`
-The `CreateServer` function in [`internal/service/registry_service.go`](https://github.com/modelcontextprotocol/registry/blob/HEAD/internal/service/registry_service.go) handles a key part of this chapter's functionality:
+The `validateWebsiteURL` function in [`internal/validators/validators.go`](https://github.com/modelcontextprotocol/registry/blob/HEAD/internal/validators/validators.go) handles a key part of this chapter's functionality:
```go
-}
-// CreateServer creates a new server version
-func (s *registryServiceImpl) CreateServer(ctx context.Context, req *apiv0.ServerJSON) (*apiv0.ServerResponse, error) {
- // Wrap the entire operation in a transaction
- return database.InTransactionT(ctx, s.db, func(ctx context.Context, tx pgx.Tx) (*apiv0.ServerResponse, error) {
- return s.createServerInTransaction(ctx, tx, req)
- })
-}
+ // Validate website URL if provided
+ websiteResult := validateWebsiteURL(ctx.Field("websiteUrl"), serverJSON.WebsiteURL)
+ result.Merge(websiteResult)
-// createServerInTransaction contains the actual CreateServer logic within a transaction
-func (s *registryServiceImpl) createServerInTransaction(ctx context.Context, tx pgx.Tx, req *apiv0.ServerJSON) (*apiv0.ServerResponse, error) {
- // Validate the request
- if err := validators.ValidatePublishRequest(ctx, *req, s.cfg); err != nil {
- return nil, err
- }
+ // Validate title if provided
+ titleResult := validateTitle(ctx.Field("title"), serverJSON.Title)
+ result.Merge(titleResult)
- publishTime := time.Now()
- serverJSON := *req
+ // Validate icons if provided
+ iconsResult := validateIcons(ctx.Field("icons"), serverJSON.Icons)
+ result.Merge(iconsResult)
- // Acquire advisory lock to prevent concurrent publishes of the same server
- if err := s.db.AcquirePublishLock(ctx, tx, serverJSON.Name); err != nil {
- return nil, err
+ // Validate all packages (basic field validation)
+ // Detailed package validation (including registry checks) is done during publish
+ for i, pkg := range serverJSON.Packages {
+ pkgResult := validatePackageField(ctx.Field("packages").Index(i), &pkg)
+ result.Merge(pkgResult)
}
- // Check for duplicate remote URLs
- if err := s.validateNoDuplicateRemoteURLs(ctx, tx, serverJSON); err != nil {
- return nil, err
+ // Validate all remotes
+ for i, remote := range serverJSON.Remotes {
+ remoteResult := validateRemoteTransport(ctx.Field("remotes").Index(i), &remote)
+ result.Merge(remoteResult)
}
- // Check we haven't exceeded the maximum versions allowed for a server
- versionCount, err := s.db.CountServerVersions(ctx, tx, serverJSON.Name)
+ return result
+}
+
+func validateRepository(ctx *ValidationContext, obj *model.Repository) *ValidationResult {
+ result := &ValidationResult{Valid: true, Issues: []ValidationIssue{}}
+
```
This function is important because it defines how MCP Registry Tutorial: Publishing, Discovery, and Governance for MCP Servers implements the patterns covered in this chapter.
-### `internal/service/registry_service.go`
+### `internal/validators/validators.go`
-The `createServerInTransaction` function in [`internal/service/registry_service.go`](https://github.com/modelcontextprotocol/registry/blob/HEAD/internal/service/registry_service.go) handles a key part of this chapter's functionality:
+The `validateTitle` function in [`internal/validators/validators.go`](https://github.com/modelcontextprotocol/registry/blob/HEAD/internal/validators/validators.go) handles a key part of this chapter's functionality:
```go
- // Wrap the entire operation in a transaction
- return database.InTransactionT(ctx, s.db, func(ctx context.Context, tx pgx.Tx) (*apiv0.ServerResponse, error) {
- return s.createServerInTransaction(ctx, tx, req)
- })
-}
-// createServerInTransaction contains the actual CreateServer logic within a transaction
-func (s *registryServiceImpl) createServerInTransaction(ctx context.Context, tx pgx.Tx, req *apiv0.ServerJSON) (*apiv0.ServerResponse, error) {
- // Validate the request
- if err := validators.ValidatePublishRequest(ctx, *req, s.cfg); err != nil {
- return nil, err
- }
+ // Validate title if provided
+ titleResult := validateTitle(ctx.Field("title"), serverJSON.Title)
+ result.Merge(titleResult)
- publishTime := time.Now()
- serverJSON := *req
+ // Validate icons if provided
+ iconsResult := validateIcons(ctx.Field("icons"), serverJSON.Icons)
+ result.Merge(iconsResult)
- // Acquire advisory lock to prevent concurrent publishes of the same server
- if err := s.db.AcquirePublishLock(ctx, tx, serverJSON.Name); err != nil {
- return nil, err
+ // Validate all packages (basic field validation)
+ // Detailed package validation (including registry checks) is done during publish
+ for i, pkg := range serverJSON.Packages {
+ pkgResult := validatePackageField(ctx.Field("packages").Index(i), &pkg)
+ result.Merge(pkgResult)
}
- // Check for duplicate remote URLs
- if err := s.validateNoDuplicateRemoteURLs(ctx, tx, serverJSON); err != nil {
- return nil, err
+ // Validate all remotes
+ for i, remote := range serverJSON.Remotes {
+ remoteResult := validateRemoteTransport(ctx.Field("remotes").Index(i), &remote)
+ result.Merge(remoteResult)
}
- // Check we haven't exceeded the maximum versions allowed for a server
- versionCount, err := s.db.CountServerVersions(ctx, tx, serverJSON.Name)
- if err != nil && !errors.Is(err, database.ErrNotFound) {
- return nil, err
+ return result
+}
+
+func validateRepository(ctx *ValidationContext, obj *model.Repository) *ValidationResult {
+ result := &ValidationResult{Valid: true, Issues: []ValidationIssue{}}
+
+ // Skip validation if repository is nil or empty (optional field)
+ if obj == nil || (obj.URL == "" && obj.Source == "") {
+ return result
}
- if versionCount >= maxServerVersionsPerServer {
```
This function is important because it defines how MCP Registry Tutorial: Publishing, Discovery, and Governance for MCP Servers implements the patterns covered in this chapter.
-### `internal/service/registry_service.go`
+### `internal/validators/validators.go`
-The `validateNoDuplicateRemoteURLs` function in [`internal/service/registry_service.go`](https://github.com/modelcontextprotocol/registry/blob/HEAD/internal/service/registry_service.go) handles a key part of this chapter's functionality:
+The `validateIcons` function in [`internal/validators/validators.go`](https://github.com/modelcontextprotocol/registry/blob/HEAD/internal/validators/validators.go) handles a key part of this chapter's functionality:
```go
- // Check for duplicate remote URLs
- if err := s.validateNoDuplicateRemoteURLs(ctx, tx, serverJSON); err != nil {
- return nil, err
- }
+ // Validate icons if provided
+ iconsResult := validateIcons(ctx.Field("icons"), serverJSON.Icons)
+ result.Merge(iconsResult)
- // Check we haven't exceeded the maximum versions allowed for a server
- versionCount, err := s.db.CountServerVersions(ctx, tx, serverJSON.Name)
- if err != nil && !errors.Is(err, database.ErrNotFound) {
- return nil, err
- }
- if versionCount >= maxServerVersionsPerServer {
- return nil, database.ErrMaxServersReached
+ // Validate all packages (basic field validation)
+ // Detailed package validation (including registry checks) is done during publish
+ for i, pkg := range serverJSON.Packages {
+ pkgResult := validatePackageField(ctx.Field("packages").Index(i), &pkg)
+ result.Merge(pkgResult)
}
- // Check this isn't a duplicate version
- versionExists, err := s.db.CheckVersionExists(ctx, tx, serverJSON.Name, serverJSON.Version)
- if err != nil {
- return nil, err
- }
- if versionExists {
- return nil, database.ErrInvalidVersion
+ // Validate all remotes
+ for i, remote := range serverJSON.Remotes {
+ remoteResult := validateRemoteTransport(ctx.Field("remotes").Index(i), &remote)
+ result.Merge(remoteResult)
}
- // Get current latest version to determine if new version should be latest
- currentLatest, err := s.db.GetCurrentLatestVersion(ctx, tx, serverJSON.Name)
- if err != nil && !errors.Is(err, database.ErrNotFound) {
- return nil, err
+ return result
+}
+
+func validateRepository(ctx *ValidationContext, obj *model.Repository) *ValidationResult {
+ result := &ValidationResult{Valid: true, Issues: []ValidationIssue{}}
+
+ // Skip validation if repository is nil or empty (optional field)
+ if obj == nil || (obj.URL == "" && obj.Source == "") {
+ return result
}
- // Determine if this version should be marked as latest
- isNewLatest := true
+ // validate the repository source
+ repoSource := RepositorySource(obj.Source)
+ if !IsValidRepositoryURL(repoSource, obj.URL) {
```
This function is important because it defines how MCP Registry Tutorial: Publishing, Discovery, and Governance for MCP Servers implements the patterns covered in this chapter.
@@ -219,11 +217,11 @@ This function is important because it defines how MCP Registry Tutorial: Publish
```mermaid
flowchart TD
- A[GetAllVersionsByServerName]
- B[CreateServer]
- C[createServerInTransaction]
- D[validateNoDuplicateRemoteURLs]
- E[UpdateServer]
+ A[validateRepository]
+ B[validateWebsiteURL]
+ C[validateTitle]
+ D[validateIcons]
+ E[validateIcon]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-registry-tutorial/04-authentication-models-and-namespace-ownership.md b/tutorials/mcp-registry-tutorial/04-authentication-models-and-namespace-ownership.md
index ad41b18d..d2a6c247 100644
--- a/tutorials/mcp-registry-tutorial/04-authentication-models-and-namespace-ownership.md
+++ b/tutorials/mcp-registry-tutorial/04-authentication-models-and-namespace-ownership.md
@@ -45,170 +45,168 @@ You now have a reliable mapping from namespace policy to authentication workflow
Next: [Chapter 5: API Consumption, Subregistries, and Sync Strategies](05-api-consumption-subregistries-and-sync-strategies.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `internal/database/postgres.go`
+### `internal/validators/validators.go`
-The `ListServers` function in [`internal/database/postgres.go`](https://github.com/modelcontextprotocol/registry/blob/HEAD/internal/database/postgres.go) handles a key part of this chapter's functionality:
+The `ValidatePublishRequest` function in [`internal/validators/validators.go`](https://github.com/modelcontextprotocol/registry/blob/HEAD/internal/validators/validators.go) handles a key part of this chapter's functionality:
```go
}
-func (db *PostgreSQL) ListServers(
- ctx context.Context,
- tx pgx.Tx,
- filter *ServerFilter,
- cursor string,
- limit int,
-) ([]*apiv0.ServerResponse, string, error) {
- if limit <= 0 {
- limit = 10
+// ValidatePublishRequest validates a complete publish request including extensions
+// Note: ValidateServerJSON should be called separately before this function
+func ValidatePublishRequest(ctx context.Context, req apiv0.ServerJSON, cfg *config.Config) error {
+ // Validate publisher extensions in _meta
+ if err := validatePublisherExtensions(req); err != nil {
+ return err
}
- if ctx.Err() != nil {
- return nil, "", ctx.Err()
+ // Validate registry ownership for all packages if validation is enabled
+ if cfg.EnableRegistryValidation {
+ if err := validateRegistryOwnership(ctx, req); err != nil {
+ return err
+ }
}
- // Build WHERE clause conditions
- argIndex := 1
- whereConditions, args, argIndex := buildFilterConditions(filter, argIndex)
+ return nil
+}
- // Add cursor pagination
- cursorCondition, cursorArgs, argIndex := addCursorCondition(cursor, argIndex)
- if cursorCondition != "" {
- whereConditions = append(whereConditions, cursorCondition)
- args = append(args, cursorArgs...)
+// ValidateUpdateRequest validates an update request including registry ownership
+// Note: ValidateServerJSON should be called separately before this function
+func ValidateUpdateRequest(ctx context.Context, req apiv0.ServerJSON, cfg *config.Config, skipRegistryValidation bool) error {
+ if cfg.EnableRegistryValidation && !skipRegistryValidation {
+ if err := validateRegistryOwnership(ctx, req); err != nil {
+ return err
+ }
}
- _ = argIndex // Silence unused variable warning
- // Build the WHERE clause
- whereClause := ""
- if len(whereConditions) > 0 {
+ return nil
+}
+
```
This function is important because it defines how MCP Registry Tutorial: Publishing, Discovery, and Governance for MCP Servers implements the patterns covered in this chapter.
-### `internal/database/postgres.go`
+### `internal/validators/validators.go`
-The `GetServerByName` function in [`internal/database/postgres.go`](https://github.com/modelcontextprotocol/registry/blob/HEAD/internal/database/postgres.go) handles a key part of this chapter's functionality:
+The `ValidateUpdateRequest` function in [`internal/validators/validators.go`](https://github.com/modelcontextprotocol/registry/blob/HEAD/internal/validators/validators.go) handles a key part of this chapter's functionality:
```go
}
-// GetServerByName retrieves the latest version of a server by server name
-func (db *PostgreSQL) GetServerByName(ctx context.Context, tx pgx.Tx, serverName string, includeDeleted bool) (*apiv0.ServerResponse, error) {
- if ctx.Err() != nil {
- return nil, ctx.Err()
- }
-
- // Build filter conditions
- isLatest := true
- filter := &ServerFilter{
- Name: &serverName,
- IsLatest: &isLatest,
- IncludeDeleted: &includeDeleted,
+// ValidateUpdateRequest validates an update request including registry ownership
+// Note: ValidateServerJSON should be called separately before this function
+func ValidateUpdateRequest(ctx context.Context, req apiv0.ServerJSON, cfg *config.Config, skipRegistryValidation bool) error {
+ if cfg.EnableRegistryValidation && !skipRegistryValidation {
+ if err := validateRegistryOwnership(ctx, req); err != nil {
+ return err
+ }
}
- argIndex := 1
- whereConditions, args, _ := buildFilterConditions(filter, argIndex)
+ return nil
+}
- whereClause := ""
- if len(whereConditions) > 0 {
- whereClause = "WHERE " + strings.Join(whereConditions, " AND ")
+func validateRegistryOwnership(ctx context.Context, req apiv0.ServerJSON) error {
+ for i, pkg := range req.Packages {
+ if err := ValidatePackage(ctx, pkg, req.Name); err != nil {
+ return fmt.Errorf("registry validation failed for package %d (%s): %w", i, pkg.Identifier, err)
+ }
}
+ return nil
+}
- query := fmt.Sprintf(`
- SELECT server_name, version, status, status_changed_at, status_message, published_at, updated_at, is_latest, value
- FROM servers
- %s
- ORDER BY published_at DESC
- LIMIT 1
- `, whereClause)
+func validatePublisherExtensions(req apiv0.ServerJSON) error {
+ const maxExtensionSize = 4 * 1024 // 4KB limit
+ // Check size limit for _meta publisher-provided extension
+ if req.Meta != nil && req.Meta.PublisherProvided != nil {
+ extensionsJSON, err := json.Marshal(req.Meta.PublisherProvided)
+ if err != nil {
+ return fmt.Errorf("failed to marshal _meta.io.modelcontextprotocol.registry/publisher-provided extension: %w", err)
+ }
```
This function is important because it defines how MCP Registry Tutorial: Publishing, Discovery, and Governance for MCP Servers implements the patterns covered in this chapter.
-### `internal/database/postgres.go`
+### `internal/validators/validators.go`
-The `GetServerByNameAndVersion` function in [`internal/database/postgres.go`](https://github.com/modelcontextprotocol/registry/blob/HEAD/internal/database/postgres.go) handles a key part of this chapter's functionality:
+The `validateRegistryOwnership` function in [`internal/validators/validators.go`](https://github.com/modelcontextprotocol/registry/blob/HEAD/internal/validators/validators.go) handles a key part of this chapter's functionality:
```go
-}
-
-// GetServerByNameAndVersion retrieves a specific version of a server by server name and version
-func (db *PostgreSQL) GetServerByNameAndVersion(ctx context.Context, tx pgx.Tx, serverName string, version string, includeDeleted bool) (*apiv0.ServerResponse, error) {
- if ctx.Err() != nil {
- return nil, ctx.Err()
+ // Validate registry ownership for all packages if validation is enabled
+ if cfg.EnableRegistryValidation {
+ if err := validateRegistryOwnership(ctx, req); err != nil {
+ return err
+ }
}
- // Build filter conditions
- filter := &ServerFilter{
- Name: &serverName,
- Version: &version,
- IncludeDeleted: &includeDeleted,
+ return nil
+}
+
+// ValidateUpdateRequest validates an update request including registry ownership
+// Note: ValidateServerJSON should be called separately before this function
+func ValidateUpdateRequest(ctx context.Context, req apiv0.ServerJSON, cfg *config.Config, skipRegistryValidation bool) error {
+ if cfg.EnableRegistryValidation && !skipRegistryValidation {
+ if err := validateRegistryOwnership(ctx, req); err != nil {
+ return err
+ }
}
- argIndex := 1
- whereConditions, args, _ := buildFilterConditions(filter, argIndex)
+ return nil
+}
- whereClause := ""
- if len(whereConditions) > 0 {
- whereClause = "WHERE " + strings.Join(whereConditions, " AND ")
+func validateRegistryOwnership(ctx context.Context, req apiv0.ServerJSON) error {
+ for i, pkg := range req.Packages {
+ if err := ValidatePackage(ctx, pkg, req.Name); err != nil {
+ return fmt.Errorf("registry validation failed for package %d (%s): %w", i, pkg.Identifier, err)
+ }
}
+ return nil
+}
- query := fmt.Sprintf(`
- SELECT server_name, version, status, status_changed_at, status_message, published_at, updated_at, is_latest, value
- FROM servers
- %s
- LIMIT 1
- `, whereClause)
-
- var name, vers, status string
- var statusChangedAt, publishedAt, updatedAt time.Time
+func validatePublisherExtensions(req apiv0.ServerJSON) error {
```
This function is important because it defines how MCP Registry Tutorial: Publishing, Discovery, and Governance for MCP Servers implements the patterns covered in this chapter.
-### `internal/database/postgres.go`
+### `internal/validators/validators.go`
-The `GetAllVersionsByServerName` function in [`internal/database/postgres.go`](https://github.com/modelcontextprotocol/registry/blob/HEAD/internal/database/postgres.go) handles a key part of this chapter's functionality:
+The `validatePublisherExtensions` function in [`internal/validators/validators.go`](https://github.com/modelcontextprotocol/registry/blob/HEAD/internal/validators/validators.go) handles a key part of this chapter's functionality:
```go
-}
-
-// GetAllVersionsByServerName retrieves all versions of a server by server name
-func (db *PostgreSQL) GetAllVersionsByServerName(ctx context.Context, tx pgx.Tx, serverName string, includeDeleted bool) ([]*apiv0.ServerResponse, error) {
- if ctx.Err() != nil {
- return nil, ctx.Err()
+func ValidatePublishRequest(ctx context.Context, req apiv0.ServerJSON, cfg *config.Config) error {
+ // Validate publisher extensions in _meta
+ if err := validatePublisherExtensions(req); err != nil {
+ return err
}
- // Build filter conditions
- filter := &ServerFilter{
- Name: &serverName,
- IncludeDeleted: &includeDeleted,
+ // Validate registry ownership for all packages if validation is enabled
+ if cfg.EnableRegistryValidation {
+ if err := validateRegistryOwnership(ctx, req); err != nil {
+ return err
+ }
}
- argIndex := 1
- whereConditions, args, _ := buildFilterConditions(filter, argIndex)
+ return nil
+}
- whereClause := ""
- if len(whereConditions) > 0 {
- whereClause = "WHERE " + strings.Join(whereConditions, " AND ")
+// ValidateUpdateRequest validates an update request including registry ownership
+// Note: ValidateServerJSON should be called separately before this function
+func ValidateUpdateRequest(ctx context.Context, req apiv0.ServerJSON, cfg *config.Config, skipRegistryValidation bool) error {
+ if cfg.EnableRegistryValidation && !skipRegistryValidation {
+ if err := validateRegistryOwnership(ctx, req); err != nil {
+ return err
+ }
}
- query := fmt.Sprintf(`
- SELECT server_name, version, status, status_changed_at, status_message, published_at, updated_at, is_latest, value
- FROM servers
- %s
- ORDER BY published_at DESC
- `, whereClause)
+ return nil
+}
- rows, err := db.getExecutor(tx).Query(ctx, query, args...)
- if err != nil {
- return nil, fmt.Errorf("failed to query server versions: %w", err)
+func validateRegistryOwnership(ctx context.Context, req apiv0.ServerJSON) error {
+ for i, pkg := range req.Packages {
+ if err := ValidatePackage(ctx, pkg, req.Name); err != nil {
+ return fmt.Errorf("registry validation failed for package %d (%s): %w", i, pkg.Identifier, err)
```
This function is important because it defines how MCP Registry Tutorial: Publishing, Discovery, and Governance for MCP Servers implements the patterns covered in this chapter.
@@ -218,11 +216,11 @@ This function is important because it defines how MCP Registry Tutorial: Publish
```mermaid
flowchart TD
- A[ListServers]
- B[GetServerByName]
- C[GetServerByNameAndVersion]
- D[GetAllVersionsByServerName]
- E[CreateServer]
+ A[ValidatePublishRequest]
+ B[ValidateUpdateRequest]
+ C[validateRegistryOwnership]
+ D[validatePublisherExtensions]
+ E[parseServerName]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-registry-tutorial/05-api-consumption-subregistries-and-sync-strategies.md b/tutorials/mcp-registry-tutorial/05-api-consumption-subregistries-and-sync-strategies.md
index ffa939c8..81f2d9bf 100644
--- a/tutorials/mcp-registry-tutorial/05-api-consumption-subregistries-and-sync-strategies.md
+++ b/tutorials/mcp-registry-tutorial/05-api-consumption-subregistries-and-sync-strategies.md
@@ -47,170 +47,168 @@ You now have a stable ingestion model for registry-backed discovery systems.
Next: [Chapter 6: Versioning, Governance, and Moderation Lifecycle](06-versioning-governance-and-moderation-lifecycle.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `internal/database/postgres.go`
-The `Close` function in [`internal/database/postgres.go`](https://github.com/modelcontextprotocol/registry/blob/HEAD/internal/database/postgres.go) handles a key part of this chapter's functionality:
+The `SetServerStatus` function in [`internal/database/postgres.go`](https://github.com/modelcontextprotocol/registry/blob/HEAD/internal/database/postgres.go) handles a key part of this chapter's functionality:
```go
- return nil, "", fmt.Errorf("failed to query servers: %w", err)
- }
- defer rows.Close()
+}
- var results []*apiv0.ServerResponse
- for rows.Next() {
- var serverName, version, status string
- var statusChangedAt, publishedAt, updatedAt time.Time
- var statusMessage *string
- var isLatest bool
- var valueJSON []byte
-
- err := rows.Scan(&serverName, &version, &status, &statusChangedAt, &statusMessage, &publishedAt, &updatedAt, &isLatest, &valueJSON)
- if err != nil {
- return nil, "", fmt.Errorf("failed to scan server row: %w", err)
- }
+// SetServerStatus updates the status of a specific server version
+func (db *PostgreSQL) SetServerStatus(ctx context.Context, tx pgx.Tx, serverName, version string, status model.Status, statusMessage *string) (*apiv0.ServerResponse, error) {
+ if ctx.Err() != nil {
+ return nil, ctx.Err()
+ }
- // Parse the ServerJSON from JSONB
- var serverJSON apiv0.ServerJSON
- if err := json.Unmarshal(valueJSON, &serverJSON); err != nil {
- return nil, "", fmt.Errorf("failed to unmarshal server JSON: %w", err)
+ // Update the status and related fields
+ // Only update status_changed_at when status actually changes
+ query := `
+ UPDATE servers
+ SET
+ status = $1,
+ status_changed_at = CASE WHEN status != $1::varchar THEN NOW() ELSE status_changed_at END,
+ updated_at = NOW(),
+ status_message = $4
+ WHERE server_name = $2 AND version = $3
+ RETURNING server_name, version, status, value, published_at, updated_at, is_latest, status_changed_at, status_message
+ `
+
+ var name, vers, currentStatus string
+ var publishedAt, updatedAt, statusChangedAt time.Time
+ var isLatest bool
+ var valueJSON []byte
+ var resultStatusMessage *string
+
+ err := db.getExecutor(tx).QueryRow(ctx, query, string(status), serverName, version, statusMessage).Scan(&name, &vers, ¤tStatus, &valueJSON, &publishedAt, &updatedAt, &isLatest, &statusChangedAt, &resultStatusMessage)
+ if err != nil {
+ if errors.Is(err, pgx.ErrNoRows) {
+ return nil, ErrNotFound
}
-
- // Build ServerResponse with separated metadata
- serverResponse := &apiv0.ServerResponse{
- Server: serverJSON,
- Meta: apiv0.ResponseMeta{
- Official: &apiv0.RegistryExtensions{
- Status: model.Status(status),
- StatusChangedAt: statusChangedAt,
- StatusMessage: statusMessage,
- PublishedAt: publishedAt,
```
This function is important because it defines how MCP Registry Tutorial: Publishing, Discovery, and Governance for MCP Servers implements the patterns covered in this chapter.
### `internal/database/postgres.go`
-The `using` interface in [`internal/database/postgres.go`](https://github.com/modelcontextprotocol/registry/blob/HEAD/internal/database/postgres.go) handles a key part of this chapter's functionality:
+The `SetAllVersionsStatus` function in [`internal/database/postgres.go`](https://github.com/modelcontextprotocol/registry/blob/HEAD/internal/database/postgres.go) handles a key part of this chapter's functionality:
```go
-)
-
-// PostgreSQL is an implementation of the Database interface using PostgreSQL
-type PostgreSQL struct {
- pool *pgxpool.Pool
}
-// Executor is an interface for executing queries (satisfied by both pgx.Tx and pgxpool.Pool)
-type Executor interface {
- Exec(ctx context.Context, sql string, arguments ...any) (pgconn.CommandTag, error)
- Query(ctx context.Context, sql string, args ...any) (pgx.Rows, error)
- QueryRow(ctx context.Context, sql string, args ...any) pgx.Row
-}
-
-// getExecutor returns the appropriate executor (transaction or pool)
-func (db *PostgreSQL) getExecutor(tx pgx.Tx) Executor {
- if tx != nil {
- return tx
+// SetAllVersionsStatus updates the status of all versions of a server in a single query
+func (db *PostgreSQL) SetAllVersionsStatus(ctx context.Context, tx pgx.Tx, serverName string, status model.Status, statusMessage *string) ([]*apiv0.ServerResponse, error) {
+ if ctx.Err() != nil {
+ return nil, ctx.Err()
}
- return db.pool
-}
-// NewPostgreSQL creates a new instance of the PostgreSQL database
-func NewPostgreSQL(ctx context.Context, connectionURI string) (*PostgreSQL, error) {
- // Parse connection config for pool settings
- config, err := pgxpool.ParseConfig(connectionURI)
+ // Update the status and related fields for all versions
+ // Only update rows where status or status_message actually changes
+ // Only update status_changed_at when status actually changes
+ query := `
+ UPDATE servers
+ SET
+ status = $1,
+ status_changed_at = CASE WHEN status != $1::varchar THEN NOW() ELSE status_changed_at END,
+ updated_at = NOW(),
+ status_message = $2
+ WHERE server_name = $3
+ AND (status != $1::varchar OR status_message IS DISTINCT FROM $2)
+ RETURNING server_name, version, status, value, published_at, updated_at, is_latest, status_changed_at, status_message
+ `
+
+ rows, err := db.getExecutor(tx).Query(ctx, query, string(status), statusMessage, serverName)
if err != nil {
- return nil, fmt.Errorf("failed to parse PostgreSQL config: %w", err)
+ return nil, fmt.Errorf("failed to update all server versions status: %w", err)
}
+ defer rows.Close()
- // Configure pool for stability-focused defaults
- config.MaxConns = 30 // Handle good concurrent load
+ var results []*apiv0.ServerResponse
+ for rows.Next() {
+ var name, vers, currentStatus string
```
-This interface is important because it defines how MCP Registry Tutorial: Publishing, Discovery, and Governance for MCP Servers implements the patterns covered in this chapter.
+This function is important because it defines how MCP Registry Tutorial: Publishing, Discovery, and Governance for MCP Servers implements the patterns covered in this chapter.
### `internal/database/postgres.go`
-The `for` interface in [`internal/database/postgres.go`](https://github.com/modelcontextprotocol/registry/blob/HEAD/internal/database/postgres.go) handles a key part of this chapter's functionality:
+The `InTransaction` function in [`internal/database/postgres.go`](https://github.com/modelcontextprotocol/registry/blob/HEAD/internal/database/postgres.go) handles a key part of this chapter's functionality:
```go
}
-// Executor is an interface for executing queries (satisfied by both pgx.Tx and pgxpool.Pool)
-type Executor interface {
- Exec(ctx context.Context, sql string, arguments ...any) (pgconn.CommandTag, error)
- Query(ctx context.Context, sql string, args ...any) (pgx.Rows, error)
- QueryRow(ctx context.Context, sql string, args ...any) pgx.Row
-}
-
-// getExecutor returns the appropriate executor (transaction or pool)
-func (db *PostgreSQL) getExecutor(tx pgx.Tx) Executor {
- if tx != nil {
- return tx
+// InTransaction executes a function within a database transaction
+func (db *PostgreSQL) InTransaction(ctx context.Context, fn func(ctx context.Context, tx pgx.Tx) error) error {
+ if ctx.Err() != nil {
+ return ctx.Err()
}
- return db.pool
-}
-// NewPostgreSQL creates a new instance of the PostgreSQL database
-func NewPostgreSQL(ctx context.Context, connectionURI string) (*PostgreSQL, error) {
- // Parse connection config for pool settings
- config, err := pgxpool.ParseConfig(connectionURI)
+ tx, err := db.pool.Begin(ctx)
if err != nil {
- return nil, fmt.Errorf("failed to parse PostgreSQL config: %w", err)
+ return fmt.Errorf("failed to begin transaction: %w", err)
}
+ //nolint:contextcheck // Intentionally using separate context for rollback to ensure cleanup even if request is cancelled
+ defer func() {
+ rollbackCtx, cancel := context.WithTimeout(context.Background(), 1*time.Second)
+ defer cancel()
+ if rbErr := tx.Rollback(rollbackCtx); rbErr != nil && !errors.Is(rbErr, pgx.ErrTxClosed) {
+ log.Printf("failed to rollback transaction: %v", rbErr)
+ }
+ }()
- // Configure pool for stability-focused defaults
- config.MaxConns = 30 // Handle good concurrent load
- config.MinConns = 5 // Keep connections warm for fast response
- config.MaxConnIdleTime = 30 * time.Minute // Keep connections available for bursts
- config.MaxConnLifetime = 2 * time.Hour // Refresh connections regularly for stability
+ if err := fn(ctx, tx); err != nil {
+ return err
+ }
+
+ if err := tx.Commit(ctx); err != nil {
+ return fmt.Errorf("failed to commit transaction: %w", err)
+ }
+
+ return nil
+}
- // Create connection pool with configured settings
```
-This interface is important because it defines how MCP Registry Tutorial: Publishing, Discovery, and Governance for MCP Servers implements the patterns covered in this chapter.
+This function is important because it defines how MCP Registry Tutorial: Publishing, Discovery, and Governance for MCP Servers implements the patterns covered in this chapter.
-### `internal/validators/schema.go`
+### `internal/database/postgres.go`
-The `extractVersionFromSchemaURL` function in [`internal/validators/schema.go`](https://github.com/modelcontextprotocol/registry/blob/HEAD/internal/validators/schema.go) handles a key part of this chapter's functionality:
+The `AcquirePublishLock` function in [`internal/database/postgres.go`](https://github.com/modelcontextprotocol/registry/blob/HEAD/internal/database/postgres.go) handles a key part of this chapter's functionality:
```go
-var schemaFS embed.FS
-
-// extractVersionFromSchemaURL extracts the version identifier from a schema URL
-// e.g., "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json" -> "2025-10-17"
-// e.g., "https://static.modelcontextprotocol.io/schemas/draft/server.schema.json" -> "draft"
-// Version identifier can contain: A-Z, a-z, 0-9, hyphen (-), underscore (_), tilde (~), and period (.)
-func extractVersionFromSchemaURL(schemaURL string) (string, error) {
- // Pattern: /schemas/{identifier}/server.schema.json
- // Identifier allowed characters: A-Z, a-z, 0-9, -, _, ~, .
- re := regexp.MustCompile(`/schemas/([A-Za-z0-9_~.-]+)/server\.schema\.json`)
- matches := re.FindStringSubmatch(schemaURL)
- if len(matches) < 2 {
- return "", fmt.Errorf("invalid schema URL format: %s", schemaURL)
- }
- return matches[1], nil
}
-// loadSchemaByVersion loads a schema file from the embedded filesystem by version
-func loadSchemaByVersion(version string) ([]byte, error) {
- filename := fmt.Sprintf("schemas/%s.json", version)
- data, err := schemaFS.ReadFile(filename)
- if err != nil {
- return nil, fmt.Errorf("schema version %s not found in embedded schemas: %w", version, err)
+// AcquirePublishLock acquires an exclusive advisory lock for publishing a server
+// This prevents race conditions when multiple versions are published concurrently
+// Using pg_advisory_xact_lock which auto-releases on transaction end
+func (db *PostgreSQL) AcquirePublishLock(ctx context.Context, tx pgx.Tx, serverName string) error {
+ if ctx.Err() != nil {
+ return ctx.Err()
}
- return data, nil
-}
-// GetCurrentSchemaVersion returns the current schema URL from constants
-func GetCurrentSchemaVersion() (string, error) {
- return model.CurrentSchemaURL, nil
+ lockID := hashServerName(serverName)
+
+ if _, err := db.getExecutor(tx).Exec(ctx, "SELECT pg_advisory_xact_lock($1)", lockID); err != nil {
+ return fmt.Errorf("failed to acquire publish lock: %w", err)
+ }
+
+ return nil
}
+// hashServerName creates a consistent hash of the server name for advisory locking
+// We use FNV-1a hash and mask to 63 bits to fit in PostgreSQL's bigint range
+func hashServerName(name string) int64 {
+ const (
+ offset64 = 14695981039346656037
+ prime64 = 1099511628211
+ )
+ hash := uint64(offset64)
+ for i := 0; i < len(name); i++ {
+ hash ^= uint64(name[i])
+ hash *= prime64
+ }
+ //nolint:gosec // Intentional conversion with masking to 63 bits
```
This function is important because it defines how MCP Registry Tutorial: Publishing, Discovery, and Governance for MCP Servers implements the patterns covered in this chapter.
@@ -220,11 +218,11 @@ This function is important because it defines how MCP Registry Tutorial: Publish
```mermaid
flowchart TD
- A[Close]
- B[using]
- C[for]
- D[extractVersionFromSchemaURL]
- E[loadSchemaByVersion]
+ A[SetServerStatus]
+ B[SetAllVersionsStatus]
+ C[InTransaction]
+ D[AcquirePublishLock]
+ E[hashServerName]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-registry-tutorial/06-versioning-governance-and-moderation-lifecycle.md b/tutorials/mcp-registry-tutorial/06-versioning-governance-and-moderation-lifecycle.md
index 792f0956..89dac062 100644
--- a/tutorials/mcp-registry-tutorial/06-versioning-governance-and-moderation-lifecycle.md
+++ b/tutorials/mcp-registry-tutorial/06-versioning-governance-and-moderation-lifecycle.md
@@ -45,170 +45,168 @@ You now have lifecycle rules for safer metadata governance.
Next: [Chapter 7: Admin Operations, Deployment, and Observability](07-admin-operations-deployment-and-observability.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `tools/validate-examples/main.go`
+### `internal/validators/utils.go`
-The `main` function in [`tools/validate-examples/main.go`](https://github.com/modelcontextprotocol/registry/blob/HEAD/tools/validate-examples/main.go) handles a key part of this chapter's functionality:
+The `replaceTemplateVariables` function in [`internal/validators/utils.go`](https://github.com/modelcontextprotocol/registry/blob/HEAD/internal/validators/utils.go) handles a key part of this chapter's functionality:
```go
-// validate-examples validates JSON examples in documentation files
-// against both schema.json and Go validators.
-package main
-
-import (
- "bytes"
- "encoding/json"
- "fmt"
- "log"
- "os"
- "path/filepath"
- "regexp"
- "strings"
-
- "github.com/modelcontextprotocol/registry/internal/validators"
- apiv0 "github.com/modelcontextprotocol/registry/pkg/api/v0"
- jsonschema "github.com/santhosh-tekuri/jsonschema/v5"
-)
-
-type validationTarget struct {
- path string
- requireSchema bool
- expectedCount *int
}
-func main() {
- log.SetFlags(0) // Remove timestamp from logs
+// replaceTemplateVariables replaces template variables with placeholder values for URL validation
+func replaceTemplateVariables(rawURL string) string {
+ // Replace common template variables with valid placeholder values for parsing
+ templateReplacements := map[string]string{
+ "{host}": "example.com",
+ "{port}": "8080",
+ "{path}": "api",
+ "{protocol}": "http",
+ "{scheme}": "http",
+ }
- if err := runValidation(); err != nil {
- log.Fatalf("Error: %v", err)
+ result := rawURL
+ for placeholder, replacement := range templateReplacements {
+ result = strings.ReplaceAll(result, placeholder, replacement)
}
+
+ // Handle any remaining {variable} patterns with context-appropriate placeholders
+ // If the variable is in a port position (after a colon in the host), use a numeric placeholder
+ // Pattern: :/{variable} or :{variable}/ or :{variable} at end
+ portRe := regexp.MustCompile(`:(\{[^}]+\})(/|$)`)
+ result = portRe.ReplaceAllString(result, ":8080$2")
+
+ // Replace any other remaining {variable} patterns with generic placeholder
+ re := regexp.MustCompile(`\{[^}]+\}`)
+ result = re.ReplaceAllString(result, "placeholder")
+
+ return result
}
+
+// IsValidURL checks if a URL is in valid format (basic structure validation)
```
This function is important because it defines how MCP Registry Tutorial: Publishing, Discovery, and Governance for MCP Servers implements the patterns covered in this chapter.
-### `tools/validate-examples/main.go`
+### `internal/validators/utils.go`
-The `runValidation` function in [`tools/validate-examples/main.go`](https://github.com/modelcontextprotocol/registry/blob/HEAD/tools/validate-examples/main.go) handles a key part of this chapter's functionality:
+The `IsValidURL` function in [`internal/validators/utils.go`](https://github.com/modelcontextprotocol/registry/blob/HEAD/internal/validators/utils.go) handles a key part of this chapter's functionality:
```go
- log.SetFlags(0) // Remove timestamp from logs
+}
+
+// IsValidURL checks if a URL is in valid format (basic structure validation)
+func IsValidURL(rawURL string) bool {
+ // Replace template variables with placeholders for parsing
+ testURL := replaceTemplateVariables(rawURL)
+
+ // Parse the URL
+ u, err := url.Parse(testURL)
+ if err != nil {
+ return false
+ }
+
+ // Check if scheme is present (http or https)
+ if u.Scheme != "http" && u.Scheme != "https" {
+ return false
+ }
- if err := runValidation(); err != nil {
- log.Fatalf("Error: %v", err)
+ if u.Host == "" {
+ return false
}
+ return true
}
-func runValidation() error {
- // Define what we validate and how
- expectedServerJSONCount := 15
- targets := []validationTarget{
- {
- path: filepath.Join("docs", "reference", "server-json", "generic-server-json.md"),
- requireSchema: false,
- expectedCount: &expectedServerJSONCount,
- },
- {
- path: filepath.Join("docs", "modelcontextprotocol-io", "package-types.mdx"),
- requireSchema: true,
- expectedCount: nil, // No count validation for guide
- },
- {
- path: filepath.Join("docs", "modelcontextprotocol-io", "quickstart.mdx"),
- requireSchema: true,
- expectedCount: nil, // No count validation for guide
- },
- {
- path: filepath.Join("docs", "modelcontextprotocol-io", "remote-servers.mdx"),
- requireSchema: true,
- expectedCount: nil, // No count validation for guide
- },
+// IsValidSubfolderPath checks if a subfolder path is valid
+func IsValidSubfolderPath(path string) bool {
+ // Empty path is valid (subfolder is optional)
+ if path == "" {
+ return true
}
+
+ // Must not start with / (must be relative)
```
This function is important because it defines how MCP Registry Tutorial: Publishing, Discovery, and Governance for MCP Servers implements the patterns covered in this chapter.
-### `tools/validate-examples/main.go`
+### `internal/validators/utils.go`
-The `validateFile` function in [`tools/validate-examples/main.go`](https://github.com/modelcontextprotocol/registry/blob/HEAD/tools/validate-examples/main.go) handles a key part of this chapter's functionality:
+The `IsValidSubfolderPath` function in [`internal/validators/utils.go`](https://github.com/modelcontextprotocol/registry/blob/HEAD/internal/validators/utils.go) handles a key part of this chapter's functionality:
```go
-
- for _, target := range targets {
- if err := validateFile(target, baseSchema); err != nil {
- return err
- }
- log.Println()
- }
-
- log.Println("All validations passed!")
- return nil
}
-func validateFile(target validationTarget, baseSchema *jsonschema.Schema) error {
- examples, err := extractExamples(target.path, target.requireSchema)
- if err != nil {
- return fmt.Errorf("failed to extract examples from %s: %w", target.path, err)
+// IsValidSubfolderPath checks if a subfolder path is valid
+func IsValidSubfolderPath(path string) bool {
+ // Empty path is valid (subfolder is optional)
+ if path == "" {
+ return true
}
- log.Printf("Validating %s: found %d examples\n", target.path, len(examples))
-
- if target.expectedCount != nil && len(examples) != *target.expectedCount {
- return fmt.Errorf("expected %d examples in %s but found %d - if this is intentional, update expectedCount in tools/validate-examples/main.go",
- *target.expectedCount, target.path, len(examples))
+ // Must not start with / (must be relative)
+ if strings.HasPrefix(path, "/") {
+ return false
}
- if len(examples) == 0 {
- log.Println(" No examples to validate")
- return nil
+ // Must not end with / (clean path format)
+ if strings.HasSuffix(path, "/") {
+ return false
}
- log.Println()
+ // Check for valid path characters (alphanumeric, dash, underscore, dot, forward slash)
+ validPathRegex := regexp.MustCompile(`^[a-zA-Z0-9\-_./]+$`)
+ if !validPathRegex.MatchString(path) {
+ return false
+ }
+ // Check that path segments are valid
+ segments := strings.Split(path, "/")
+ for _, segment := range segments {
+ // Disallow empty segments ("//"), current dir ("."), and parent dir ("..")
+ if segment == "" || segment == "." || segment == ".." {
+ return false
+ }
```
This function is important because it defines how MCP Registry Tutorial: Publishing, Discovery, and Governance for MCP Servers implements the patterns covered in this chapter.
-### `tools/validate-examples/main.go`
+### `internal/validators/utils.go`
-The `validateExample` function in [`tools/validate-examples/main.go`](https://github.com/modelcontextprotocol/registry/blob/HEAD/tools/validate-examples/main.go) handles a key part of this chapter's functionality:
+The `IsValidRemoteURL` function in [`internal/validators/utils.go`](https://github.com/modelcontextprotocol/registry/blob/HEAD/internal/validators/utils.go) handles a key part of this chapter's functionality:
```go
- log.Printf(" Example %d (line %d):", i+1, example.line)
-
- if validateExample(example, baseSchema) {
- validatedCount++
- }
+}
- log.Println()
+// IsValidRemoteURL checks if a URL is valid for remotes (stricter than packages - no localhost allowed)
+func IsValidRemoteURL(rawURL string) bool {
+ // First check basic URL structure
+ if !IsValidURL(rawURL) {
+ return false
}
- if validatedCount != len(examples) {
- return fmt.Errorf("validation failed for %s: expected %d examples to pass but only %d did",
- target.path, len(examples), validatedCount)
+ // Replace template variables with placeholders before parsing for localhost check
+ testURL := replaceTemplateVariables(rawURL)
+
+ // Parse the URL to check for localhost restriction
+ u, err := url.Parse(testURL)
+ if err != nil {
+ return false
}
- return nil
-}
+ // Reject localhost URLs for remotes (security/production concerns)
+ hostname := u.Hostname()
+ if hostname == "localhost" || hostname == "127.0.0.1" || strings.HasSuffix(hostname, ".localhost") {
+ return false
+ }
-func validateExample(ex example, baseSchema *jsonschema.Schema) bool {
- var data any
- if err := json.Unmarshal([]byte(ex.content), &data); err != nil {
- log.Printf(" ❌ Invalid JSON: %v", err)
+ if u.Scheme != "https" {
return false
}
- // Extract server portion if this is a PublishRequest format
- serverData := data
- publishRequestValid := true
- if dataMap, ok := data.(map[string]any); ok {
- if server, exists := dataMap["server"]; exists {
- // This is a PublishRequest format - validate only expected properties exist
- for key := range dataMap {
- if key != "server" && key != "x-publisher" {
+ return true
+}
+
+// IsValidTemplatedURL validates a URL with template variables against available variables
```
This function is important because it defines how MCP Registry Tutorial: Publishing, Discovery, and Governance for MCP Servers implements the patterns covered in this chapter.
@@ -218,11 +216,11 @@ This function is important because it defines how MCP Registry Tutorial: Publish
```mermaid
flowchart TD
- A[main]
- B[runValidation]
- C[validateFile]
- D[validateExample]
- E[validateAgainstSchema]
+ A[replaceTemplateVariables]
+ B[IsValidURL]
+ C[IsValidSubfolderPath]
+ D[IsValidRemoteURL]
+ E[IsValidTemplatedURL]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-registry-tutorial/07-admin-operations-deployment-and-observability.md b/tutorials/mcp-registry-tutorial/07-admin-operations-deployment-and-observability.md
index 9506f597..4bc5cb9e 100644
--- a/tutorials/mcp-registry-tutorial/07-admin-operations-deployment-and-observability.md
+++ b/tutorials/mcp-registry-tutorial/07-admin-operations-deployment-and-observability.md
@@ -45,158 +45,143 @@ You now have a practical operational playbook for registry administration.
Next: [Chapter 8: Production Rollout, Automation, and Contribution](08-production-rollout-automation-and-contribution.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `internal/validators/validation_types.go`
-The `AddIssue` function in [`internal/validators/validation_types.go`](https://github.com/modelcontextprotocol/registry/blob/HEAD/internal/validators/validation_types.go) handles a key part of this chapter's functionality:
+The `String` function in [`internal/validators/validation_types.go`](https://github.com/modelcontextprotocol/registry/blob/HEAD/internal/validators/validation_types.go) handles a key part of this chapter's functionality:
```go
}
-// AddIssue adds a validation issue to the result
-func (vr *ValidationResult) AddIssue(issue ValidationIssue) {
- vr.Issues = append(vr.Issues, issue)
- if issue.Severity == ValidationIssueSeverityError {
- vr.Valid = false
- }
-}
-
-// Merge combines another validation result into this one
-func (vr *ValidationResult) Merge(other *ValidationResult) {
- vr.Issues = append(vr.Issues, other.Issues...)
- if !other.Valid {
- vr.Valid = false
- }
-}
-
-// FirstError returns the first error-level issue as an error, or nil if valid
-// This provides backward compatibility for code that expects an error return type
-func (vr *ValidationResult) FirstError() error {
- if vr.Valid {
- return nil
- }
- for _, issue := range vr.Issues {
- if issue.Severity == ValidationIssueSeverityError {
- return fmt.Errorf("%s", issue.Message)
- }
- }
- return nil
+// String returns the current path as a string
+func (ctx *ValidationContext) String() string {
+ return ctx.path
}
```
This function is important because it defines how MCP Registry Tutorial: Publishing, Discovery, and Governance for MCP Servers implements the patterns covered in this chapter.
-### `internal/validators/validation_types.go`
+### `internal/database/database.go`
-The `Merge` function in [`internal/validators/validation_types.go`](https://github.com/modelcontextprotocol/registry/blob/HEAD/internal/validators/validation_types.go) handles a key part of this chapter's functionality:
+The `for` interface in [`internal/database/database.go`](https://github.com/modelcontextprotocol/registry/blob/HEAD/internal/database/database.go) handles a key part of this chapter's functionality:
```go
-}
-
-// Merge combines another validation result into this one
-func (vr *ValidationResult) Merge(other *ValidationResult) {
- vr.Issues = append(vr.Issues, other.Issues...)
- if !other.Valid {
- vr.Valid = false
- }
-}
-
-// FirstError returns the first error-level issue as an error, or nil if valid
-// This provides backward compatibility for code that expects an error return type
-func (vr *ValidationResult) FirstError() error {
- if vr.Valid {
- return nil
- }
- for _, issue := range vr.Issues {
- if issue.Severity == ValidationIssueSeverityError {
- return fmt.Errorf("%s", issue.Message)
- }
- }
- return nil
-}
-
-// Field adds a field name to the context path
-func (ctx *ValidationContext) Field(name string) *ValidationContext {
- if ctx.path == "" {
- return &ValidationContext{path: name}
- }
- return &ValidationContext{path: ctx.path + "." + name}
-}
-
+ ErrDatabase = errors.New("database error")
+ ErrInvalidVersion = errors.New("invalid version: cannot publish duplicate version")
+ ErrMaxServersReached = errors.New("maximum number of versions for this server reached (10000): please reach out at https://github.com/modelcontextprotocol/registry to explain your use case")
+)
+
+// ServerFilter defines filtering options for server queries
+type ServerFilter struct {
+ Name *string // for finding versions of same server
+ RemoteURL *string // for duplicate URL detection
+ UpdatedSince *time.Time // for incremental sync filtering
+ SubstringName *string // for substring search on name
+ Version *string // for exact version matching
+ IsLatest *bool // for filtering latest versions only
+ IncludeDeleted *bool // for including deleted packages in results (default: exclude)
+}
+
+// Database defines the interface for database operations
+type Database interface {
+ // CreateServer inserts a new server version with official metadata
+ CreateServer(ctx context.Context, tx pgx.Tx, serverJSON *apiv0.ServerJSON, officialMeta *apiv0.RegistryExtensions) (*apiv0.ServerResponse, error)
+ // UpdateServer updates an existing server record
+ UpdateServer(ctx context.Context, tx pgx.Tx, serverName, version string, serverJSON *apiv0.ServerJSON) (*apiv0.ServerResponse, error)
+ // SetServerStatus updates the status of a specific server version
+ SetServerStatus(ctx context.Context, tx pgx.Tx, serverName, version string, status model.Status, statusMessage *string) (*apiv0.ServerResponse, error)
+ // SetAllVersionsStatus updates the status of all versions of a server in a single query
+ SetAllVersionsStatus(ctx context.Context, tx pgx.Tx, serverName string, status model.Status, statusMessage *string) ([]*apiv0.ServerResponse, error)
+ // ListServers retrieve server entries with optional filtering
+ ListServers(ctx context.Context, tx pgx.Tx, filter *ServerFilter, cursor string, limit int) ([]*apiv0.ServerResponse, string, error)
+ // GetServerByName retrieve a single server by its name
+ GetServerByName(ctx context.Context, tx pgx.Tx, serverName string, includeDeleted bool) (*apiv0.ServerResponse, error)
+ // GetServerByNameAndVersion retrieve specific version of a server by server name and version
+ GetServerByNameAndVersion(ctx context.Context, tx pgx.Tx, serverName string, version string, includeDeleted bool) (*apiv0.ServerResponse, error)
```
-This function is important because it defines how MCP Registry Tutorial: Publishing, Discovery, and Governance for MCP Servers implements the patterns covered in this chapter.
+This interface is important because it defines how MCP Registry Tutorial: Publishing, Discovery, and Governance for MCP Servers implements the patterns covered in this chapter.
-### `internal/validators/validation_types.go`
+### `internal/importer/importer.go`
-The `FirstError` function in [`internal/validators/validation_types.go`](https://github.com/modelcontextprotocol/registry/blob/HEAD/internal/validators/validation_types.go) handles a key part of this chapter's functionality:
+The `NewService` function in [`internal/importer/importer.go`](https://github.com/modelcontextprotocol/registry/blob/HEAD/internal/importer/importer.go) handles a key part of this chapter's functionality:
```go
}
-// FirstError returns the first error-level issue as an error, or nil if valid
-// This provides backward compatibility for code that expects an error return type
-func (vr *ValidationResult) FirstError() error {
- if vr.Valid {
- return nil
- }
- for _, issue := range vr.Issues {
- if issue.Severity == ValidationIssueSeverityError {
- return fmt.Errorf("%s", issue.Message)
- }
- }
- return nil
+// NewService creates a new importer service
+func NewService(registry service.RegistryService) *Service {
+ return &Service{registry: registry}
}
-// Field adds a field name to the context path
-func (ctx *ValidationContext) Field(name string) *ValidationContext {
- if ctx.path == "" {
- return &ValidationContext{path: name}
+// ImportFromPath imports seed data from various sources:
+// 1. Local file paths (*.json files) - expects ServerJSON array format
+// 2. Direct HTTP URLs to seed.json files - expects ServerJSON array format
+// 3. Registry root URLs (automatically appends /v0/servers and paginates)
+func (s *Service) ImportFromPath(ctx context.Context, path string) error {
+ servers, err := readSeedFile(ctx, path)
+ if err != nil {
+ return fmt.Errorf("failed to read seed data: %w", err)
}
- return &ValidationContext{path: ctx.path + "." + name}
-}
-// Index adds an array index to the context path
-func (ctx *ValidationContext) Index(i int) *ValidationContext {
- return &ValidationContext{path: ctx.path + fmt.Sprintf("[%d]", i)}
-}
+ // Import each server using registry service CreateServer
+ var successfullyCreated []string
+ var failedCreations []string
+
+ for _, server := range servers {
+ _, err := s.registry.CreateServer(ctx, server)
+ if err != nil {
+ failedCreations = append(failedCreations, fmt.Sprintf("%s: %v", server.Name, err))
+ log.Printf("Failed to create server %s: %v", server.Name, err)
+ } else {
+ successfullyCreated = append(successfullyCreated, server.Name)
+ }
+ }
-// String returns the current path as a string
-func (ctx *ValidationContext) String() string {
- return ctx.path
+ // Report import results after actual creation attempts
```
This function is important because it defines how MCP Registry Tutorial: Publishing, Discovery, and Governance for MCP Servers implements the patterns covered in this chapter.
-### `internal/validators/validation_types.go`
+### `internal/importer/importer.go`
-The `Field` function in [`internal/validators/validation_types.go`](https://github.com/modelcontextprotocol/registry/blob/HEAD/internal/validators/validation_types.go) handles a key part of this chapter's functionality:
+The `ImportFromPath` function in [`internal/importer/importer.go`](https://github.com/modelcontextprotocol/registry/blob/HEAD/internal/importer/importer.go) handles a key part of this chapter's functionality:
```go
}
-// Field adds a field name to the context path
-func (ctx *ValidationContext) Field(name string) *ValidationContext {
- if ctx.path == "" {
- return &ValidationContext{path: name}
+// ImportFromPath imports seed data from various sources:
+// 1. Local file paths (*.json files) - expects ServerJSON array format
+// 2. Direct HTTP URLs to seed.json files - expects ServerJSON array format
+// 3. Registry root URLs (automatically appends /v0/servers and paginates)
+func (s *Service) ImportFromPath(ctx context.Context, path string) error {
+ servers, err := readSeedFile(ctx, path)
+ if err != nil {
+ return fmt.Errorf("failed to read seed data: %w", err)
}
- return &ValidationContext{path: ctx.path + "." + name}
-}
-
-// Index adds an array index to the context path
-func (ctx *ValidationContext) Index(i int) *ValidationContext {
- return &ValidationContext{path: ctx.path + fmt.Sprintf("[%d]", i)}
-}
-// String returns the current path as a string
-func (ctx *ValidationContext) String() string {
- return ctx.path
-}
+ // Import each server using registry service CreateServer
+ var successfullyCreated []string
+ var failedCreations []string
+
+ for _, server := range servers {
+ _, err := s.registry.CreateServer(ctx, server)
+ if err != nil {
+ failedCreations = append(failedCreations, fmt.Sprintf("%s: %v", server.Name, err))
+ log.Printf("Failed to create server %s: %v", server.Name, err)
+ } else {
+ successfullyCreated = append(successfullyCreated, server.Name)
+ }
+ }
+ // Report import results after actual creation attempts
+ if len(failedCreations) > 0 {
+ log.Printf("Import completed with errors: %d servers created successfully, %d servers failed",
+ len(successfullyCreated), len(failedCreations))
+ log.Printf("Failed servers: %v", failedCreations)
+ return fmt.Errorf("failed to import %d servers", len(failedCreations))
```
This function is important because it defines how MCP Registry Tutorial: Publishing, Discovery, and Governance for MCP Servers implements the patterns covered in this chapter.
@@ -206,11 +191,11 @@ This function is important because it defines how MCP Registry Tutorial: Publish
```mermaid
flowchart TD
- A[AddIssue]
- B[Merge]
- C[FirstError]
- D[Field]
- E[Index]
+ A[String]
+ B[for]
+ C[NewService]
+ D[ImportFromPath]
+ E[readSeedFile]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-registry-tutorial/08-production-rollout-automation-and-contribution.md b/tutorials/mcp-registry-tutorial/08-production-rollout-automation-and-contribution.md
index 94e32344..051f81d5 100644
--- a/tutorials/mcp-registry-tutorial/08-production-rollout-automation-and-contribution.md
+++ b/tutorials/mcp-registry-tutorial/08-production-rollout-automation-and-contribution.md
@@ -47,170 +47,155 @@ You now have an end-to-end plan to publish, operate, and evolve registry workflo
Next: Continue with [MCP Inspector Tutorial](../mcp-inspector-tutorial/)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `internal/validators/utils.go`
+### `internal/auth/jwt.go`
-The `replaceTemplateVariables` function in [`internal/validators/utils.go`](https://github.com/modelcontextprotocol/registry/blob/HEAD/internal/validators/utils.go) handles a key part of this chapter's functionality:
+The `ValidateToken` function in [`internal/auth/jwt.go`](https://github.com/modelcontextprotocol/registry/blob/HEAD/internal/auth/jwt.go) handles a key part of this chapter's functionality:
```go
}
-// replaceTemplateVariables replaces template variables with placeholder values for URL validation
-func replaceTemplateVariables(rawURL string) string {
- // Replace common template variables with valid placeholder values for parsing
- templateReplacements := map[string]string{
- "{host}": "example.com",
- "{port}": "8080",
- "{path}": "api",
- "{protocol}": "http",
- "{scheme}": "http",
+// ValidateToken validates a Registry JWT token and returns the claims
+func (j *JWTManager) ValidateToken(_ context.Context, tokenString string) (*JWTClaims, error) {
+ // Parse token
+ // This also validates expiry
+ token, err := jwt.ParseWithClaims(
+ tokenString,
+ &JWTClaims{},
+ func(_ *jwt.Token) (interface{}, error) { return j.publicKey, nil },
+ jwt.WithValidMethods([]string{"EdDSA"}),
+ jwt.WithExpirationRequired(),
+ )
+ // Validate token
+ if err != nil {
+ return nil, fmt.Errorf("failed to parse token: %w", err)
}
-
- result := rawURL
- for placeholder, replacement := range templateReplacements {
- result = strings.ReplaceAll(result, placeholder, replacement)
+ if !token.Valid {
+ return nil, fmt.Errorf("invalid token")
}
- // Handle any remaining {variable} patterns with context-appropriate placeholders
- // If the variable is in a port position (after a colon in the host), use a numeric placeholder
- // Pattern: :/{variable} or :{variable}/ or :{variable} at end
- portRe := regexp.MustCompile(`:(\{[^}]+\})(/|$)`)
- result = portRe.ReplaceAllString(result, ":8080$2")
-
- // Replace any other remaining {variable} patterns with generic placeholder
- re := regexp.MustCompile(`\{[^}]+\}`)
- result = re.ReplaceAllString(result, "placeholder")
+ // Extract claims
+ claims, ok := token.Claims.(*JWTClaims)
+ if !ok {
+ return nil, fmt.Errorf("invalid token claims")
+ }
- return result
+ return claims, nil
}
-// IsValidURL checks if a URL is in valid format (basic structure validation)
+func (j *JWTManager) HasPermission(resource string, action PermissionAction, permissions []Permission) bool {
+ for _, perm := range permissions {
```
This function is important because it defines how MCP Registry Tutorial: Publishing, Discovery, and Governance for MCP Servers implements the patterns covered in this chapter.
-### `internal/validators/utils.go`
+### `internal/auth/jwt.go`
-The `IsValidURL` function in [`internal/validators/utils.go`](https://github.com/modelcontextprotocol/registry/blob/HEAD/internal/validators/utils.go) handles a key part of this chapter's functionality:
+The `HasPermission` function in [`internal/auth/jwt.go`](https://github.com/modelcontextprotocol/registry/blob/HEAD/internal/auth/jwt.go) handles a key part of this chapter's functionality:
```go
-}
-
-// IsValidURL checks if a URL is in valid format (basic structure validation)
-func IsValidURL(rawURL string) bool {
- // Replace template variables with placeholders for parsing
- testURL := replaceTemplateVariables(rawURL)
-
- // Parse the URL
- u, err := url.Parse(testURL)
- if err != nil {
- return false
+ if !hasGlobalPermissions {
+ for _, blockedNamespace := range BlockedNamespaces {
+ if j.HasPermission(blockedNamespace+"/test", PermissionActionPublish, claims.Permissions) {
+ return nil, fmt.Errorf("your namespace is blocked. raise an issue at https://github.com/modelcontextprotocol/registry/ if you think this is a mistake")
+ }
+ }
}
- // Check if scheme is present (http or https)
- if u.Scheme != "http" && u.Scheme != "https" {
- return false
+ if claims.IssuedAt == nil {
+ claims.IssuedAt = jwt.NewNumericDate(time.Now())
}
-
- if u.Host == "" {
- return false
+ if claims.ExpiresAt == nil {
+ claims.ExpiresAt = jwt.NewNumericDate(time.Now().Add(j.tokenDuration))
+ }
+ if claims.NotBefore == nil {
+ claims.NotBefore = jwt.NewNumericDate(time.Now())
+ }
+ if claims.Issuer == "" {
+ claims.Issuer = "mcp-registry"
}
- return true
-}
-// IsValidSubfolderPath checks if a subfolder path is valid
-func IsValidSubfolderPath(path string) bool {
- // Empty path is valid (subfolder is optional)
- if path == "" {
- return true
+ // Create token with claims
+ token := jwt.NewWithClaims(&jwt.SigningMethodEd25519{}, claims)
+
+ // Sign token with Ed25519 private key
+ tokenString, err := token.SignedString(j.privateKey)
+ if err != nil {
+ return nil, fmt.Errorf("failed to sign token: %w", err)
}
- // Must not start with / (must be relative)
+ return &TokenResponse{
+ RegistryToken: tokenString,
```
This function is important because it defines how MCP Registry Tutorial: Publishing, Discovery, and Governance for MCP Servers implements the patterns covered in this chapter.
-### `internal/validators/utils.go`
+### `internal/auth/jwt.go`
-The `IsValidSubfolderPath` function in [`internal/validators/utils.go`](https://github.com/modelcontextprotocol/registry/blob/HEAD/internal/validators/utils.go) handles a key part of this chapter's functionality:
+The `isResourceMatch` function in [`internal/auth/jwt.go`](https://github.com/modelcontextprotocol/registry/blob/HEAD/internal/auth/jwt.go) handles a key part of this chapter's functionality:
```go
+func (j *JWTManager) HasPermission(resource string, action PermissionAction, permissions []Permission) bool {
+ for _, perm := range permissions {
+ if perm.Action == action && isResourceMatch(resource, perm.ResourcePattern) {
+ return true
+ }
+ }
+ return false
}
-// IsValidSubfolderPath checks if a subfolder path is valid
-func IsValidSubfolderPath(path string) bool {
- // Empty path is valid (subfolder is optional)
- if path == "" {
+func isResourceMatch(resource, pattern string) bool {
+ if pattern == "*" {
return true
}
-
- // Must not start with / (must be relative)
- if strings.HasPrefix(path, "/") {
- return false
- }
-
- // Must not end with / (clean path format)
- if strings.HasSuffix(path, "/") {
- return false
- }
-
- // Check for valid path characters (alphanumeric, dash, underscore, dot, forward slash)
- validPathRegex := regexp.MustCompile(`^[a-zA-Z0-9\-_./]+$`)
- if !validPathRegex.MatchString(path) {
- return false
+ if strings.HasSuffix(pattern, "*") {
+ return strings.HasPrefix(resource, strings.TrimSuffix(pattern, "*"))
}
+ return resource == pattern
+}
- // Check that path segments are valid
- segments := strings.Split(path, "/")
- for _, segment := range segments {
- // Disallow empty segments ("//"), current dir ("."), and parent dir ("..")
- if segment == "" || segment == "." || segment == ".." {
- return false
- }
```
This function is important because it defines how MCP Registry Tutorial: Publishing, Discovery, and Governance for MCP Servers implements the patterns covered in this chapter.
-### `internal/validators/utils.go`
+### `internal/api/server.go`
-The `IsValidRemoteURL` function in [`internal/validators/utils.go`](https://github.com/modelcontextprotocol/registry/blob/HEAD/internal/validators/utils.go) handles a key part of this chapter's functionality:
+The `NulByteValidationMiddleware` function in [`internal/api/server.go`](https://github.com/modelcontextprotocol/registry/blob/HEAD/internal/api/server.go) handles a key part of this chapter's functionality:
```go
-}
-
-// IsValidRemoteURL checks if a URL is valid for remotes (stricter than packages - no localhost allowed)
-func IsValidRemoteURL(rawURL string) bool {
- // First check basic URL structure
- if !IsValidURL(rawURL) {
- return false
- }
-
- // Replace template variables with placeholders before parsing for localhost check
- testURL := replaceTemplateVariables(rawURL)
-
- // Parse the URL to check for localhost restriction
- u, err := url.Parse(testURL)
- if err != nil {
- return false
- }
-
- // Reject localhost URLs for remotes (security/production concerns)
- hostname := u.Hostname()
- if hostname == "localhost" || hostname == "127.0.0.1" || strings.HasSuffix(hostname, ".localhost") {
- return false
- }
+)
+
+// NulByteValidationMiddleware rejects requests containing NUL bytes in URL path or query parameters.
+// This prevents PostgreSQL encoding errors (SQLSTATE 22021) and returns a proper 400 Bad Request.
+// Checks for both literal NUL bytes (\x00) and URL-encoded form (%00).
+func NulByteValidationMiddleware(next http.Handler) http.Handler {
+ return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ // Check URL path for literal NUL bytes or URL-encoded %00
+ // Path needs %00 check because handlers call url.PathUnescape() which would decode it
+ if containsNulByte(r.URL.Path) {
+ writeErrorResponse(w, http.StatusBadRequest, "Invalid request: URL path contains null bytes")
+ return
+ }
- if u.Scheme != "https" {
- return false
- }
+ // Check raw query string for literal NUL bytes or URL-encoded %00
+ if containsNulByte(r.URL.RawQuery) {
+ writeErrorResponse(w, http.StatusBadRequest, "Invalid request: query parameters contain null bytes")
+ return
+ }
- return true
+ next.ServeHTTP(w, r)
+ })
}
-// IsValidTemplatedURL validates a URL with template variables against available variables
+// writeErrorResponse writes a JSON error response using huma's ErrorModel format
+// for consistency with the rest of the API.
+func writeErrorResponse(w http.ResponseWriter, status int, detail string) {
+ w.Header().Set("Content-Type", "application/json")
+ w.WriteHeader(status)
+
+ errModel := &huma.ErrorModel{
+ Title: http.StatusText(status),
```
This function is important because it defines how MCP Registry Tutorial: Publishing, Discovery, and Governance for MCP Servers implements the patterns covered in this chapter.
@@ -220,11 +205,11 @@ This function is important because it defines how MCP Registry Tutorial: Publish
```mermaid
flowchart TD
- A[replaceTemplateVariables]
- B[IsValidURL]
- C[IsValidSubfolderPath]
- D[IsValidRemoteURL]
- E[IsValidTemplatedURL]
+ A[ValidateToken]
+ B[HasPermission]
+ C[isResourceMatch]
+ D[NulByteValidationMiddleware]
+ E[writeErrorResponse]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-ruby-sdk-tutorial/01-getting-started-and-gem-baseline.md b/tutorials/mcp-ruby-sdk-tutorial/01-getting-started-and-gem-baseline.md
index bed878b5..e2bb20de 100644
--- a/tutorials/mcp-ruby-sdk-tutorial/01-getting-started-and-gem-baseline.md
+++ b/tutorials/mcp-ruby-sdk-tutorial/01-getting-started-and-gem-baseline.md
@@ -47,8 +47,6 @@ You now have a stable Ruby MCP baseline for deeper server/client implementation.
Next: [Chapter 2: Server Architecture and Capability Negotiation](02-server-architecture-and-capability-negotiation.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `conformance/server.rb`
diff --git a/tutorials/mcp-ruby-sdk-tutorial/02-server-architecture-and-capability-negotiation.md b/tutorials/mcp-ruby-sdk-tutorial/02-server-architecture-and-capability-negotiation.md
index 21d8de1c..28261bc1 100644
--- a/tutorials/mcp-ruby-sdk-tutorial/02-server-architecture-and-capability-negotiation.md
+++ b/tutorials/mcp-ruby-sdk-tutorial/02-server-architecture-and-capability-negotiation.md
@@ -46,94 +46,8 @@ You now have a server architecture baseline aligned to MCP method and capability
Next: [Chapter 3: Tools, Prompts, Resources, and Schema Discipline](03-tools-prompts-resources-and-schema-discipline.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `dev.yml`
-
-The `dev` module in [`dev.yml`](https://github.com/modelcontextprotocol/ruby-sdk/blob/HEAD/dev.yml) handles a key part of this chapter's functionality:
-
-```yml
-name: mcp-ruby
-
-type: ruby
-
-up:
- - ruby
- - bundler
-
-commands:
- console:
- desc: Open console with the gem loaded
- run: bin/console
- build:
- desc: Build the gem using rake build
- run: bin/rake build
- test:
- desc: Run tests
- syntax:
- argument: file
- optional: args...
- run: |
- if [[ $# -eq 0 ]]; then
- bin/rake test
- else
- bin/rake -I test "$@"
- fi
- style:
- desc: Run rubocop
- aliases: [rubocop, lint]
- run: bin/rake rubocop
-
-```
-
-This module is important because it defines how MCP Ruby SDK Tutorial: Building MCP Servers and Clients in Ruby implements the patterns covered in this chapter.
-
-### `examples/streamable_http_server.rb`
-
-The `streamable_http_server` module in [`examples/streamable_http_server.rb`](https://github.com/modelcontextprotocol/ruby-sdk/blob/HEAD/examples/streamable_http_server.rb) handles a key part of this chapter's functionality:
-
-```rb
-# frozen_string_literal: true
-
-$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
-require "mcp"
-require "rack/cors"
-require "rackup"
-require "json"
-require "logger"
-
-# Create a logger for SSE-specific logging
-sse_logger = Logger.new($stdout)
-sse_logger.formatter = proc do |severity, datetime, _progname, msg|
- "[SSE] #{severity} #{datetime.strftime("%H:%M:%S.%L")} - #{msg}\n"
-end
-
-# Tool that returns a response that will be sent via SSE if a stream is active
-class NotificationTool < MCP::Tool
- tool_name "notification_tool"
- description "Returns a notification message that will be sent via SSE if stream is active"
- input_schema(
- properties: {
- message: { type: "string", description: "Message to send via SSE" },
- delay: { type: "number", description: "Delay in seconds before returning (optional)" },
- },
- required: ["message"],
- )
-
- class << self
- attr_accessor :logger
-
- def call(message:, delay: 0)
- sleep(delay) if delay > 0
-
- logger&.info("Returning notification message: #{message}")
-
-```
-
-This module is important because it defines how MCP Ruby SDK Tutorial: Building MCP Servers and Clients in Ruby implements the patterns covered in this chapter.
-
### `.rubocop.yml`
The `.rubocop` module in [`.rubocop.yml`](https://github.com/modelcontextprotocol/ruby-sdk/blob/HEAD/.rubocop.yml) handles a key part of this chapter's functionality:
@@ -162,14 +76,102 @@ Minitest/LiteralAsActualArgument:
This module is important because it defines how MCP Ruby SDK Tutorial: Building MCP Servers and Clients in Ruby implements the patterns covered in this chapter.
+### `conformance/server.rb`
+
+The `server` module in [`conformance/server.rb`](https://github.com/modelcontextprotocol/ruby-sdk/blob/HEAD/conformance/server.rb) handles a key part of this chapter's functionality:
+
+```rb
+# frozen_string_literal: true
+
+require "rackup"
+require "json"
+require "uri"
+require_relative "../lib/mcp"
+
+module Conformance
+ # 1x1 red PNG pixel (matches TypeScript SDK and Python SDK)
+ BASE64_1X1_PNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8DwHwAFBQIAX8jx0gAAAABJRU5ErkJggg=="
+
+ # Minimal WAV file (matches TypeScript SDK and Python SDK)
+ BASE64_MINIMAL_WAV = "UklGRiYAAABXQVZFZm10IBAAAAABAAEAQB8AAAB9AAACABAAZGF0YQIAAAA="
+
+ module Tools
+ class TestSimpleText < MCP::Tool
+ tool_name "test_simple_text"
+ description "A tool that returns simple text content"
+
+ class << self
+ def call(**_args)
+ MCP::Tool::Response.new([MCP::Content::Text.new("This is a simple text response for testing.").to_h])
+ end
+ end
+ end
+
+ class TestImageContent < MCP::Tool
+ tool_name "test_image_content"
+ description "A tool that returns image content"
+
+ class << self
+ def call(**_args)
+ MCP::Tool::Response.new([MCP::Content::Image.new(BASE64_1X1_PNG, "image/png").to_h])
+ end
+ end
+```
+
+This module is important because it defines how MCP Ruby SDK Tutorial: Building MCP Servers and Clients in Ruby implements the patterns covered in this chapter.
+
+### `lib/json_rpc_handler.rb`
+
+The `json_rpc_handler` module in [`lib/json_rpc_handler.rb`](https://github.com/modelcontextprotocol/ruby-sdk/blob/HEAD/lib/json_rpc_handler.rb) handles a key part of this chapter's functionality:
+
+```rb
+# frozen_string_literal: true
+
+require "json"
+
+module JsonRpcHandler
+ class Version
+ V1_0 = "1.0"
+ V2_0 = "2.0"
+ end
+
+ class ErrorCode
+ INVALID_REQUEST = -32600
+ METHOD_NOT_FOUND = -32601
+ INVALID_PARAMS = -32602
+ INTERNAL_ERROR = -32603
+ PARSE_ERROR = -32700
+ end
+
+ DEFAULT_ALLOWED_ID_CHARACTERS = /\A[a-zA-Z0-9_-]+\z/
+
+ extend self
+
+ def handle(request, id_validation_pattern: DEFAULT_ALLOWED_ID_CHARACTERS, &method_finder)
+ if request.is_a?(Array)
+ return error_response(id: :unknown_id, id_validation_pattern: id_validation_pattern, error: {
+ code: ErrorCode::INVALID_REQUEST,
+ message: "Invalid Request",
+ data: "Request is an empty array",
+ }) if request.empty?
+
+ # Handle batch requests
+ responses = request.map { |req| process_request(req, id_validation_pattern: id_validation_pattern, &method_finder) }.compact
+
+ # A single item is hoisted out of the array
+ return responses.first if responses.one?
+```
+
+This module is important because it defines how MCP Ruby SDK Tutorial: Building MCP Servers and Clients in Ruby implements the patterns covered in this chapter.
+
## How These Components Connect
```mermaid
flowchart TD
- A[dev]
- B[streamable_http_server]
- C[.rubocop]
+ A[.rubocop]
+ B[server]
+ C[json_rpc_handler]
A --> B
B --> C
```
diff --git a/tutorials/mcp-ruby-sdk-tutorial/03-tools-prompts-resources-and-schema-discipline.md b/tutorials/mcp-ruby-sdk-tutorial/03-tools-prompts-resources-and-schema-discipline.md
index 69677806..118c4e64 100644
--- a/tutorials/mcp-ruby-sdk-tutorial/03-tools-prompts-resources-and-schema-discipline.md
+++ b/tutorials/mcp-ruby-sdk-tutorial/03-tools-prompts-resources-and-schema-discipline.md
@@ -40,94 +40,8 @@ You now have a schema-first primitive strategy for Ruby MCP servers.
Next: [Chapter 4: Notifications, Logging, and Observability](04-notifications-logging-and-observability.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `dev.yml`
-
-The `dev` module in [`dev.yml`](https://github.com/modelcontextprotocol/ruby-sdk/blob/HEAD/dev.yml) handles a key part of this chapter's functionality:
-
-```yml
-name: mcp-ruby
-
-type: ruby
-
-up:
- - ruby
- - bundler
-
-commands:
- console:
- desc: Open console with the gem loaded
- run: bin/console
- build:
- desc: Build the gem using rake build
- run: bin/rake build
- test:
- desc: Run tests
- syntax:
- argument: file
- optional: args...
- run: |
- if [[ $# -eq 0 ]]; then
- bin/rake test
- else
- bin/rake -I test "$@"
- fi
- style:
- desc: Run rubocop
- aliases: [rubocop, lint]
- run: bin/rake rubocop
-
-```
-
-This module is important because it defines how MCP Ruby SDK Tutorial: Building MCP Servers and Clients in Ruby implements the patterns covered in this chapter.
-
-### `examples/streamable_http_server.rb`
-
-The `streamable_http_server` module in [`examples/streamable_http_server.rb`](https://github.com/modelcontextprotocol/ruby-sdk/blob/HEAD/examples/streamable_http_server.rb) handles a key part of this chapter's functionality:
-
-```rb
-# frozen_string_literal: true
-
-$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
-require "mcp"
-require "rack/cors"
-require "rackup"
-require "json"
-require "logger"
-
-# Create a logger for SSE-specific logging
-sse_logger = Logger.new($stdout)
-sse_logger.formatter = proc do |severity, datetime, _progname, msg|
- "[SSE] #{severity} #{datetime.strftime("%H:%M:%S.%L")} - #{msg}\n"
-end
-
-# Tool that returns a response that will be sent via SSE if a stream is active
-class NotificationTool < MCP::Tool
- tool_name "notification_tool"
- description "Returns a notification message that will be sent via SSE if stream is active"
- input_schema(
- properties: {
- message: { type: "string", description: "Message to send via SSE" },
- delay: { type: "number", description: "Delay in seconds before returning (optional)" },
- },
- required: ["message"],
- )
-
- class << self
- attr_accessor :logger
-
- def call(message:, delay: 0)
- sleep(delay) if delay > 0
-
- logger&.info("Returning notification message: #{message}")
-
-```
-
-This module is important because it defines how MCP Ruby SDK Tutorial: Building MCP Servers and Clients in Ruby implements the patterns covered in this chapter.
-
### `.rubocop.yml`
The `.rubocop` module in [`.rubocop.yml`](https://github.com/modelcontextprotocol/ruby-sdk/blob/HEAD/.rubocop.yml) handles a key part of this chapter's functionality:
@@ -156,14 +70,102 @@ Minitest/LiteralAsActualArgument:
This module is important because it defines how MCP Ruby SDK Tutorial: Building MCP Servers and Clients in Ruby implements the patterns covered in this chapter.
+### `conformance/server.rb`
+
+The `server` module in [`conformance/server.rb`](https://github.com/modelcontextprotocol/ruby-sdk/blob/HEAD/conformance/server.rb) handles a key part of this chapter's functionality:
+
+```rb
+# frozen_string_literal: true
+
+require "rackup"
+require "json"
+require "uri"
+require_relative "../lib/mcp"
+
+module Conformance
+ # 1x1 red PNG pixel (matches TypeScript SDK and Python SDK)
+ BASE64_1X1_PNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8DwHwAFBQIAX8jx0gAAAABJRU5ErkJggg=="
+
+ # Minimal WAV file (matches TypeScript SDK and Python SDK)
+ BASE64_MINIMAL_WAV = "UklGRiYAAABXQVZFZm10IBAAAAABAAEAQB8AAAB9AAACABAAZGF0YQIAAAA="
+
+ module Tools
+ class TestSimpleText < MCP::Tool
+ tool_name "test_simple_text"
+ description "A tool that returns simple text content"
+
+ class << self
+ def call(**_args)
+ MCP::Tool::Response.new([MCP::Content::Text.new("This is a simple text response for testing.").to_h])
+ end
+ end
+ end
+
+ class TestImageContent < MCP::Tool
+ tool_name "test_image_content"
+ description "A tool that returns image content"
+
+ class << self
+ def call(**_args)
+ MCP::Tool::Response.new([MCP::Content::Image.new(BASE64_1X1_PNG, "image/png").to_h])
+ end
+ end
+```
+
+This module is important because it defines how MCP Ruby SDK Tutorial: Building MCP Servers and Clients in Ruby implements the patterns covered in this chapter.
+
+### `lib/json_rpc_handler.rb`
+
+The `json_rpc_handler` module in [`lib/json_rpc_handler.rb`](https://github.com/modelcontextprotocol/ruby-sdk/blob/HEAD/lib/json_rpc_handler.rb) handles a key part of this chapter's functionality:
+
+```rb
+# frozen_string_literal: true
+
+require "json"
+
+module JsonRpcHandler
+ class Version
+ V1_0 = "1.0"
+ V2_0 = "2.0"
+ end
+
+ class ErrorCode
+ INVALID_REQUEST = -32600
+ METHOD_NOT_FOUND = -32601
+ INVALID_PARAMS = -32602
+ INTERNAL_ERROR = -32603
+ PARSE_ERROR = -32700
+ end
+
+ DEFAULT_ALLOWED_ID_CHARACTERS = /\A[a-zA-Z0-9_-]+\z/
+
+ extend self
+
+ def handle(request, id_validation_pattern: DEFAULT_ALLOWED_ID_CHARACTERS, &method_finder)
+ if request.is_a?(Array)
+ return error_response(id: :unknown_id, id_validation_pattern: id_validation_pattern, error: {
+ code: ErrorCode::INVALID_REQUEST,
+ message: "Invalid Request",
+ data: "Request is an empty array",
+ }) if request.empty?
+
+ # Handle batch requests
+ responses = request.map { |req| process_request(req, id_validation_pattern: id_validation_pattern, &method_finder) }.compact
+
+ # A single item is hoisted out of the array
+ return responses.first if responses.one?
+```
+
+This module is important because it defines how MCP Ruby SDK Tutorial: Building MCP Servers and Clients in Ruby implements the patterns covered in this chapter.
+
## How These Components Connect
```mermaid
flowchart TD
- A[dev]
- B[streamable_http_server]
- C[.rubocop]
+ A[.rubocop]
+ B[server]
+ C[json_rpc_handler]
A --> B
B --> C
```
diff --git a/tutorials/mcp-ruby-sdk-tutorial/04-notifications-logging-and-observability.md b/tutorials/mcp-ruby-sdk-tutorial/04-notifications-logging-and-observability.md
index 2edfbe64..ed9a99ee 100644
--- a/tutorials/mcp-ruby-sdk-tutorial/04-notifications-logging-and-observability.md
+++ b/tutorials/mcp-ruby-sdk-tutorial/04-notifications-logging-and-observability.md
@@ -47,94 +47,8 @@ You now have a practical observability model for Ruby MCP services.
Next: [Chapter 5: Transports: stdio, Streamable HTTP, and Session Modes](05-transports-stdio-streamable-http-and-session-modes.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `dev.yml`
-
-The `dev` module in [`dev.yml`](https://github.com/modelcontextprotocol/ruby-sdk/blob/HEAD/dev.yml) handles a key part of this chapter's functionality:
-
-```yml
-name: mcp-ruby
-
-type: ruby
-
-up:
- - ruby
- - bundler
-
-commands:
- console:
- desc: Open console with the gem loaded
- run: bin/console
- build:
- desc: Build the gem using rake build
- run: bin/rake build
- test:
- desc: Run tests
- syntax:
- argument: file
- optional: args...
- run: |
- if [[ $# -eq 0 ]]; then
- bin/rake test
- else
- bin/rake -I test "$@"
- fi
- style:
- desc: Run rubocop
- aliases: [rubocop, lint]
- run: bin/rake rubocop
-
-```
-
-This module is important because it defines how MCP Ruby SDK Tutorial: Building MCP Servers and Clients in Ruby implements the patterns covered in this chapter.
-
-### `examples/streamable_http_server.rb`
-
-The `streamable_http_server` module in [`examples/streamable_http_server.rb`](https://github.com/modelcontextprotocol/ruby-sdk/blob/HEAD/examples/streamable_http_server.rb) handles a key part of this chapter's functionality:
-
-```rb
-# frozen_string_literal: true
-
-$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
-require "mcp"
-require "rack/cors"
-require "rackup"
-require "json"
-require "logger"
-
-# Create a logger for SSE-specific logging
-sse_logger = Logger.new($stdout)
-sse_logger.formatter = proc do |severity, datetime, _progname, msg|
- "[SSE] #{severity} #{datetime.strftime("%H:%M:%S.%L")} - #{msg}\n"
-end
-
-# Tool that returns a response that will be sent via SSE if a stream is active
-class NotificationTool < MCP::Tool
- tool_name "notification_tool"
- description "Returns a notification message that will be sent via SSE if stream is active"
- input_schema(
- properties: {
- message: { type: "string", description: "Message to send via SSE" },
- delay: { type: "number", description: "Delay in seconds before returning (optional)" },
- },
- required: ["message"],
- )
-
- class << self
- attr_accessor :logger
-
- def call(message:, delay: 0)
- sleep(delay) if delay > 0
-
- logger&.info("Returning notification message: #{message}")
-
-```
-
-This module is important because it defines how MCP Ruby SDK Tutorial: Building MCP Servers and Clients in Ruby implements the patterns covered in this chapter.
-
### `.rubocop.yml`
The `.rubocop` module in [`.rubocop.yml`](https://github.com/modelcontextprotocol/ruby-sdk/blob/HEAD/.rubocop.yml) handles a key part of this chapter's functionality:
@@ -163,14 +77,102 @@ Minitest/LiteralAsActualArgument:
This module is important because it defines how MCP Ruby SDK Tutorial: Building MCP Servers and Clients in Ruby implements the patterns covered in this chapter.
+### `conformance/server.rb`
+
+The `server` module in [`conformance/server.rb`](https://github.com/modelcontextprotocol/ruby-sdk/blob/HEAD/conformance/server.rb) handles a key part of this chapter's functionality:
+
+```rb
+# frozen_string_literal: true
+
+require "rackup"
+require "json"
+require "uri"
+require_relative "../lib/mcp"
+
+module Conformance
+ # 1x1 red PNG pixel (matches TypeScript SDK and Python SDK)
+ BASE64_1X1_PNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8DwHwAFBQIAX8jx0gAAAABJRU5ErkJggg=="
+
+ # Minimal WAV file (matches TypeScript SDK and Python SDK)
+ BASE64_MINIMAL_WAV = "UklGRiYAAABXQVZFZm10IBAAAAABAAEAQB8AAAB9AAACABAAZGF0YQIAAAA="
+
+ module Tools
+ class TestSimpleText < MCP::Tool
+ tool_name "test_simple_text"
+ description "A tool that returns simple text content"
+
+ class << self
+ def call(**_args)
+ MCP::Tool::Response.new([MCP::Content::Text.new("This is a simple text response for testing.").to_h])
+ end
+ end
+ end
+
+ class TestImageContent < MCP::Tool
+ tool_name "test_image_content"
+ description "A tool that returns image content"
+
+ class << self
+ def call(**_args)
+ MCP::Tool::Response.new([MCP::Content::Image.new(BASE64_1X1_PNG, "image/png").to_h])
+ end
+ end
+```
+
+This module is important because it defines how MCP Ruby SDK Tutorial: Building MCP Servers and Clients in Ruby implements the patterns covered in this chapter.
+
+### `lib/json_rpc_handler.rb`
+
+The `json_rpc_handler` module in [`lib/json_rpc_handler.rb`](https://github.com/modelcontextprotocol/ruby-sdk/blob/HEAD/lib/json_rpc_handler.rb) handles a key part of this chapter's functionality:
+
+```rb
+# frozen_string_literal: true
+
+require "json"
+
+module JsonRpcHandler
+ class Version
+ V1_0 = "1.0"
+ V2_0 = "2.0"
+ end
+
+ class ErrorCode
+ INVALID_REQUEST = -32600
+ METHOD_NOT_FOUND = -32601
+ INVALID_PARAMS = -32602
+ INTERNAL_ERROR = -32603
+ PARSE_ERROR = -32700
+ end
+
+ DEFAULT_ALLOWED_ID_CHARACTERS = /\A[a-zA-Z0-9_-]+\z/
+
+ extend self
+
+ def handle(request, id_validation_pattern: DEFAULT_ALLOWED_ID_CHARACTERS, &method_finder)
+ if request.is_a?(Array)
+ return error_response(id: :unknown_id, id_validation_pattern: id_validation_pattern, error: {
+ code: ErrorCode::INVALID_REQUEST,
+ message: "Invalid Request",
+ data: "Request is an empty array",
+ }) if request.empty?
+
+ # Handle batch requests
+ responses = request.map { |req| process_request(req, id_validation_pattern: id_validation_pattern, &method_finder) }.compact
+
+ # A single item is hoisted out of the array
+ return responses.first if responses.one?
+```
+
+This module is important because it defines how MCP Ruby SDK Tutorial: Building MCP Servers and Clients in Ruby implements the patterns covered in this chapter.
+
## How These Components Connect
```mermaid
flowchart TD
- A[dev]
- B[streamable_http_server]
- C[.rubocop]
+ A[.rubocop]
+ B[server]
+ C[json_rpc_handler]
A --> B
B --> C
```
diff --git a/tutorials/mcp-ruby-sdk-tutorial/05-transports-stdio-streamable-http-and-session-modes.md b/tutorials/mcp-ruby-sdk-tutorial/05-transports-stdio-streamable-http-and-session-modes.md
index 2e252827..5d0d8596 100644
--- a/tutorials/mcp-ruby-sdk-tutorial/05-transports-stdio-streamable-http-and-session-modes.md
+++ b/tutorials/mcp-ruby-sdk-tutorial/05-transports-stdio-streamable-http-and-session-modes.md
@@ -47,94 +47,8 @@ You now have a transport/session framework for Ruby MCP runtime planning.
Next: [Chapter 6: Client Workflows, HTTP Integration, and Auth Considerations](06-client-workflows-http-integration-and-auth-considerations.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `dev.yml`
-
-The `dev` module in [`dev.yml`](https://github.com/modelcontextprotocol/ruby-sdk/blob/HEAD/dev.yml) handles a key part of this chapter's functionality:
-
-```yml
-name: mcp-ruby
-
-type: ruby
-
-up:
- - ruby
- - bundler
-
-commands:
- console:
- desc: Open console with the gem loaded
- run: bin/console
- build:
- desc: Build the gem using rake build
- run: bin/rake build
- test:
- desc: Run tests
- syntax:
- argument: file
- optional: args...
- run: |
- if [[ $# -eq 0 ]]; then
- bin/rake test
- else
- bin/rake -I test "$@"
- fi
- style:
- desc: Run rubocop
- aliases: [rubocop, lint]
- run: bin/rake rubocop
-
-```
-
-This module is important because it defines how MCP Ruby SDK Tutorial: Building MCP Servers and Clients in Ruby implements the patterns covered in this chapter.
-
-### `examples/streamable_http_server.rb`
-
-The `streamable_http_server` module in [`examples/streamable_http_server.rb`](https://github.com/modelcontextprotocol/ruby-sdk/blob/HEAD/examples/streamable_http_server.rb) handles a key part of this chapter's functionality:
-
-```rb
-# frozen_string_literal: true
-
-$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
-require "mcp"
-require "rack/cors"
-require "rackup"
-require "json"
-require "logger"
-
-# Create a logger for SSE-specific logging
-sse_logger = Logger.new($stdout)
-sse_logger.formatter = proc do |severity, datetime, _progname, msg|
- "[SSE] #{severity} #{datetime.strftime("%H:%M:%S.%L")} - #{msg}\n"
-end
-
-# Tool that returns a response that will be sent via SSE if a stream is active
-class NotificationTool < MCP::Tool
- tool_name "notification_tool"
- description "Returns a notification message that will be sent via SSE if stream is active"
- input_schema(
- properties: {
- message: { type: "string", description: "Message to send via SSE" },
- delay: { type: "number", description: "Delay in seconds before returning (optional)" },
- },
- required: ["message"],
- )
-
- class << self
- attr_accessor :logger
-
- def call(message:, delay: 0)
- sleep(delay) if delay > 0
-
- logger&.info("Returning notification message: #{message}")
-
-```
-
-This module is important because it defines how MCP Ruby SDK Tutorial: Building MCP Servers and Clients in Ruby implements the patterns covered in this chapter.
-
### `.rubocop.yml`
The `.rubocop` module in [`.rubocop.yml`](https://github.com/modelcontextprotocol/ruby-sdk/blob/HEAD/.rubocop.yml) handles a key part of this chapter's functionality:
@@ -163,14 +77,102 @@ Minitest/LiteralAsActualArgument:
This module is important because it defines how MCP Ruby SDK Tutorial: Building MCP Servers and Clients in Ruby implements the patterns covered in this chapter.
+### `conformance/server.rb`
+
+The `server` module in [`conformance/server.rb`](https://github.com/modelcontextprotocol/ruby-sdk/blob/HEAD/conformance/server.rb) handles a key part of this chapter's functionality:
+
+```rb
+# frozen_string_literal: true
+
+require "rackup"
+require "json"
+require "uri"
+require_relative "../lib/mcp"
+
+module Conformance
+ # 1x1 red PNG pixel (matches TypeScript SDK and Python SDK)
+ BASE64_1X1_PNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8DwHwAFBQIAX8jx0gAAAABJRU5ErkJggg=="
+
+ # Minimal WAV file (matches TypeScript SDK and Python SDK)
+ BASE64_MINIMAL_WAV = "UklGRiYAAABXQVZFZm10IBAAAAABAAEAQB8AAAB9AAACABAAZGF0YQIAAAA="
+
+ module Tools
+ class TestSimpleText < MCP::Tool
+ tool_name "test_simple_text"
+ description "A tool that returns simple text content"
+
+ class << self
+ def call(**_args)
+ MCP::Tool::Response.new([MCP::Content::Text.new("This is a simple text response for testing.").to_h])
+ end
+ end
+ end
+
+ class TestImageContent < MCP::Tool
+ tool_name "test_image_content"
+ description "A tool that returns image content"
+
+ class << self
+ def call(**_args)
+ MCP::Tool::Response.new([MCP::Content::Image.new(BASE64_1X1_PNG, "image/png").to_h])
+ end
+ end
+```
+
+This module is important because it defines how MCP Ruby SDK Tutorial: Building MCP Servers and Clients in Ruby implements the patterns covered in this chapter.
+
+### `lib/json_rpc_handler.rb`
+
+The `json_rpc_handler` module in [`lib/json_rpc_handler.rb`](https://github.com/modelcontextprotocol/ruby-sdk/blob/HEAD/lib/json_rpc_handler.rb) handles a key part of this chapter's functionality:
+
+```rb
+# frozen_string_literal: true
+
+require "json"
+
+module JsonRpcHandler
+ class Version
+ V1_0 = "1.0"
+ V2_0 = "2.0"
+ end
+
+ class ErrorCode
+ INVALID_REQUEST = -32600
+ METHOD_NOT_FOUND = -32601
+ INVALID_PARAMS = -32602
+ INTERNAL_ERROR = -32603
+ PARSE_ERROR = -32700
+ end
+
+ DEFAULT_ALLOWED_ID_CHARACTERS = /\A[a-zA-Z0-9_-]+\z/
+
+ extend self
+
+ def handle(request, id_validation_pattern: DEFAULT_ALLOWED_ID_CHARACTERS, &method_finder)
+ if request.is_a?(Array)
+ return error_response(id: :unknown_id, id_validation_pattern: id_validation_pattern, error: {
+ code: ErrorCode::INVALID_REQUEST,
+ message: "Invalid Request",
+ data: "Request is an empty array",
+ }) if request.empty?
+
+ # Handle batch requests
+ responses = request.map { |req| process_request(req, id_validation_pattern: id_validation_pattern, &method_finder) }.compact
+
+ # A single item is hoisted out of the array
+ return responses.first if responses.one?
+```
+
+This module is important because it defines how MCP Ruby SDK Tutorial: Building MCP Servers and Clients in Ruby implements the patterns covered in this chapter.
+
## How These Components Connect
```mermaid
flowchart TD
- A[dev]
- B[streamable_http_server]
- C[.rubocop]
+ A[.rubocop]
+ B[server]
+ C[json_rpc_handler]
A --> B
B --> C
```
diff --git a/tutorials/mcp-ruby-sdk-tutorial/06-client-workflows-http-integration-and-auth-considerations.md b/tutorials/mcp-ruby-sdk-tutorial/06-client-workflows-http-integration-and-auth-considerations.md
index 6ace7502..02e731fd 100644
--- a/tutorials/mcp-ruby-sdk-tutorial/06-client-workflows-http-integration-and-auth-considerations.md
+++ b/tutorials/mcp-ruby-sdk-tutorial/06-client-workflows-http-integration-and-auth-considerations.md
@@ -40,94 +40,8 @@ You now have a reliable client integration pattern for Ruby MCP over HTTP.
Next: [Chapter 7: Quality, Security, and Release Workflows](07-quality-security-and-release-workflows.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `dev.yml`
-
-The `dev` module in [`dev.yml`](https://github.com/modelcontextprotocol/ruby-sdk/blob/HEAD/dev.yml) handles a key part of this chapter's functionality:
-
-```yml
-name: mcp-ruby
-
-type: ruby
-
-up:
- - ruby
- - bundler
-
-commands:
- console:
- desc: Open console with the gem loaded
- run: bin/console
- build:
- desc: Build the gem using rake build
- run: bin/rake build
- test:
- desc: Run tests
- syntax:
- argument: file
- optional: args...
- run: |
- if [[ $# -eq 0 ]]; then
- bin/rake test
- else
- bin/rake -I test "$@"
- fi
- style:
- desc: Run rubocop
- aliases: [rubocop, lint]
- run: bin/rake rubocop
-
-```
-
-This module is important because it defines how MCP Ruby SDK Tutorial: Building MCP Servers and Clients in Ruby implements the patterns covered in this chapter.
-
-### `examples/streamable_http_server.rb`
-
-The `streamable_http_server` module in [`examples/streamable_http_server.rb`](https://github.com/modelcontextprotocol/ruby-sdk/blob/HEAD/examples/streamable_http_server.rb) handles a key part of this chapter's functionality:
-
-```rb
-# frozen_string_literal: true
-
-$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
-require "mcp"
-require "rack/cors"
-require "rackup"
-require "json"
-require "logger"
-
-# Create a logger for SSE-specific logging
-sse_logger = Logger.new($stdout)
-sse_logger.formatter = proc do |severity, datetime, _progname, msg|
- "[SSE] #{severity} #{datetime.strftime("%H:%M:%S.%L")} - #{msg}\n"
-end
-
-# Tool that returns a response that will be sent via SSE if a stream is active
-class NotificationTool < MCP::Tool
- tool_name "notification_tool"
- description "Returns a notification message that will be sent via SSE if stream is active"
- input_schema(
- properties: {
- message: { type: "string", description: "Message to send via SSE" },
- delay: { type: "number", description: "Delay in seconds before returning (optional)" },
- },
- required: ["message"],
- )
-
- class << self
- attr_accessor :logger
-
- def call(message:, delay: 0)
- sleep(delay) if delay > 0
-
- logger&.info("Returning notification message: #{message}")
-
-```
-
-This module is important because it defines how MCP Ruby SDK Tutorial: Building MCP Servers and Clients in Ruby implements the patterns covered in this chapter.
-
### `.rubocop.yml`
The `.rubocop` module in [`.rubocop.yml`](https://github.com/modelcontextprotocol/ruby-sdk/blob/HEAD/.rubocop.yml) handles a key part of this chapter's functionality:
@@ -156,14 +70,102 @@ Minitest/LiteralAsActualArgument:
This module is important because it defines how MCP Ruby SDK Tutorial: Building MCP Servers and Clients in Ruby implements the patterns covered in this chapter.
+### `conformance/server.rb`
+
+The `server` module in [`conformance/server.rb`](https://github.com/modelcontextprotocol/ruby-sdk/blob/HEAD/conformance/server.rb) handles a key part of this chapter's functionality:
+
+```rb
+# frozen_string_literal: true
+
+require "rackup"
+require "json"
+require "uri"
+require_relative "../lib/mcp"
+
+module Conformance
+ # 1x1 red PNG pixel (matches TypeScript SDK and Python SDK)
+ BASE64_1X1_PNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8DwHwAFBQIAX8jx0gAAAABJRU5ErkJggg=="
+
+ # Minimal WAV file (matches TypeScript SDK and Python SDK)
+ BASE64_MINIMAL_WAV = "UklGRiYAAABXQVZFZm10IBAAAAABAAEAQB8AAAB9AAACABAAZGF0YQIAAAA="
+
+ module Tools
+ class TestSimpleText < MCP::Tool
+ tool_name "test_simple_text"
+ description "A tool that returns simple text content"
+
+ class << self
+ def call(**_args)
+ MCP::Tool::Response.new([MCP::Content::Text.new("This is a simple text response for testing.").to_h])
+ end
+ end
+ end
+
+ class TestImageContent < MCP::Tool
+ tool_name "test_image_content"
+ description "A tool that returns image content"
+
+ class << self
+ def call(**_args)
+ MCP::Tool::Response.new([MCP::Content::Image.new(BASE64_1X1_PNG, "image/png").to_h])
+ end
+ end
+```
+
+This module is important because it defines how MCP Ruby SDK Tutorial: Building MCP Servers and Clients in Ruby implements the patterns covered in this chapter.
+
+### `lib/json_rpc_handler.rb`
+
+The `json_rpc_handler` module in [`lib/json_rpc_handler.rb`](https://github.com/modelcontextprotocol/ruby-sdk/blob/HEAD/lib/json_rpc_handler.rb) handles a key part of this chapter's functionality:
+
+```rb
+# frozen_string_literal: true
+
+require "json"
+
+module JsonRpcHandler
+ class Version
+ V1_0 = "1.0"
+ V2_0 = "2.0"
+ end
+
+ class ErrorCode
+ INVALID_REQUEST = -32600
+ METHOD_NOT_FOUND = -32601
+ INVALID_PARAMS = -32602
+ INTERNAL_ERROR = -32603
+ PARSE_ERROR = -32700
+ end
+
+ DEFAULT_ALLOWED_ID_CHARACTERS = /\A[a-zA-Z0-9_-]+\z/
+
+ extend self
+
+ def handle(request, id_validation_pattern: DEFAULT_ALLOWED_ID_CHARACTERS, &method_finder)
+ if request.is_a?(Array)
+ return error_response(id: :unknown_id, id_validation_pattern: id_validation_pattern, error: {
+ code: ErrorCode::INVALID_REQUEST,
+ message: "Invalid Request",
+ data: "Request is an empty array",
+ }) if request.empty?
+
+ # Handle batch requests
+ responses = request.map { |req| process_request(req, id_validation_pattern: id_validation_pattern, &method_finder) }.compact
+
+ # A single item is hoisted out of the array
+ return responses.first if responses.one?
+```
+
+This module is important because it defines how MCP Ruby SDK Tutorial: Building MCP Servers and Clients in Ruby implements the patterns covered in this chapter.
+
## How These Components Connect
```mermaid
flowchart TD
- A[dev]
- B[streamable_http_server]
- C[.rubocop]
+ A[.rubocop]
+ B[server]
+ C[json_rpc_handler]
A --> B
B --> C
```
diff --git a/tutorials/mcp-ruby-sdk-tutorial/07-quality-security-and-release-workflows.md b/tutorials/mcp-ruby-sdk-tutorial/07-quality-security-and-release-workflows.md
index 10a094e3..90231091 100644
--- a/tutorials/mcp-ruby-sdk-tutorial/07-quality-security-and-release-workflows.md
+++ b/tutorials/mcp-ruby-sdk-tutorial/07-quality-security-and-release-workflows.md
@@ -41,94 +41,8 @@ You now have a quality and release discipline model for Ruby MCP systems.
Next: [Chapter 8: Production Deployment and Upgrade Strategy](08-production-deployment-and-upgrade-strategy.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `dev.yml`
-
-The `dev` module in [`dev.yml`](https://github.com/modelcontextprotocol/ruby-sdk/blob/HEAD/dev.yml) handles a key part of this chapter's functionality:
-
-```yml
-name: mcp-ruby
-
-type: ruby
-
-up:
- - ruby
- - bundler
-
-commands:
- console:
- desc: Open console with the gem loaded
- run: bin/console
- build:
- desc: Build the gem using rake build
- run: bin/rake build
- test:
- desc: Run tests
- syntax:
- argument: file
- optional: args...
- run: |
- if [[ $# -eq 0 ]]; then
- bin/rake test
- else
- bin/rake -I test "$@"
- fi
- style:
- desc: Run rubocop
- aliases: [rubocop, lint]
- run: bin/rake rubocop
-
-```
-
-This module is important because it defines how MCP Ruby SDK Tutorial: Building MCP Servers and Clients in Ruby implements the patterns covered in this chapter.
-
-### `examples/streamable_http_server.rb`
-
-The `streamable_http_server` module in [`examples/streamable_http_server.rb`](https://github.com/modelcontextprotocol/ruby-sdk/blob/HEAD/examples/streamable_http_server.rb) handles a key part of this chapter's functionality:
-
-```rb
-# frozen_string_literal: true
-
-$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
-require "mcp"
-require "rack/cors"
-require "rackup"
-require "json"
-require "logger"
-
-# Create a logger for SSE-specific logging
-sse_logger = Logger.new($stdout)
-sse_logger.formatter = proc do |severity, datetime, _progname, msg|
- "[SSE] #{severity} #{datetime.strftime("%H:%M:%S.%L")} - #{msg}\n"
-end
-
-# Tool that returns a response that will be sent via SSE if a stream is active
-class NotificationTool < MCP::Tool
- tool_name "notification_tool"
- description "Returns a notification message that will be sent via SSE if stream is active"
- input_schema(
- properties: {
- message: { type: "string", description: "Message to send via SSE" },
- delay: { type: "number", description: "Delay in seconds before returning (optional)" },
- },
- required: ["message"],
- )
-
- class << self
- attr_accessor :logger
-
- def call(message:, delay: 0)
- sleep(delay) if delay > 0
-
- logger&.info("Returning notification message: #{message}")
-
-```
-
-This module is important because it defines how MCP Ruby SDK Tutorial: Building MCP Servers and Clients in Ruby implements the patterns covered in this chapter.
-
### `.rubocop.yml`
The `.rubocop` module in [`.rubocop.yml`](https://github.com/modelcontextprotocol/ruby-sdk/blob/HEAD/.rubocop.yml) handles a key part of this chapter's functionality:
@@ -157,14 +71,102 @@ Minitest/LiteralAsActualArgument:
This module is important because it defines how MCP Ruby SDK Tutorial: Building MCP Servers and Clients in Ruby implements the patterns covered in this chapter.
+### `conformance/server.rb`
+
+The `server` module in [`conformance/server.rb`](https://github.com/modelcontextprotocol/ruby-sdk/blob/HEAD/conformance/server.rb) handles a key part of this chapter's functionality:
+
+```rb
+# frozen_string_literal: true
+
+require "rackup"
+require "json"
+require "uri"
+require_relative "../lib/mcp"
+
+module Conformance
+ # 1x1 red PNG pixel (matches TypeScript SDK and Python SDK)
+ BASE64_1X1_PNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8DwHwAFBQIAX8jx0gAAAABJRU5ErkJggg=="
+
+ # Minimal WAV file (matches TypeScript SDK and Python SDK)
+ BASE64_MINIMAL_WAV = "UklGRiYAAABXQVZFZm10IBAAAAABAAEAQB8AAAB9AAACABAAZGF0YQIAAAA="
+
+ module Tools
+ class TestSimpleText < MCP::Tool
+ tool_name "test_simple_text"
+ description "A tool that returns simple text content"
+
+ class << self
+ def call(**_args)
+ MCP::Tool::Response.new([MCP::Content::Text.new("This is a simple text response for testing.").to_h])
+ end
+ end
+ end
+
+ class TestImageContent < MCP::Tool
+ tool_name "test_image_content"
+ description "A tool that returns image content"
+
+ class << self
+ def call(**_args)
+ MCP::Tool::Response.new([MCP::Content::Image.new(BASE64_1X1_PNG, "image/png").to_h])
+ end
+ end
+```
+
+This module is important because it defines how MCP Ruby SDK Tutorial: Building MCP Servers and Clients in Ruby implements the patterns covered in this chapter.
+
+### `lib/json_rpc_handler.rb`
+
+The `json_rpc_handler` module in [`lib/json_rpc_handler.rb`](https://github.com/modelcontextprotocol/ruby-sdk/blob/HEAD/lib/json_rpc_handler.rb) handles a key part of this chapter's functionality:
+
+```rb
+# frozen_string_literal: true
+
+require "json"
+
+module JsonRpcHandler
+ class Version
+ V1_0 = "1.0"
+ V2_0 = "2.0"
+ end
+
+ class ErrorCode
+ INVALID_REQUEST = -32600
+ METHOD_NOT_FOUND = -32601
+ INVALID_PARAMS = -32602
+ INTERNAL_ERROR = -32603
+ PARSE_ERROR = -32700
+ end
+
+ DEFAULT_ALLOWED_ID_CHARACTERS = /\A[a-zA-Z0-9_-]+\z/
+
+ extend self
+
+ def handle(request, id_validation_pattern: DEFAULT_ALLOWED_ID_CHARACTERS, &method_finder)
+ if request.is_a?(Array)
+ return error_response(id: :unknown_id, id_validation_pattern: id_validation_pattern, error: {
+ code: ErrorCode::INVALID_REQUEST,
+ message: "Invalid Request",
+ data: "Request is an empty array",
+ }) if request.empty?
+
+ # Handle batch requests
+ responses = request.map { |req| process_request(req, id_validation_pattern: id_validation_pattern, &method_finder) }.compact
+
+ # A single item is hoisted out of the array
+ return responses.first if responses.one?
+```
+
+This module is important because it defines how MCP Ruby SDK Tutorial: Building MCP Servers and Clients in Ruby implements the patterns covered in this chapter.
+
## How These Components Connect
```mermaid
flowchart TD
- A[dev]
- B[streamable_http_server]
- C[.rubocop]
+ A[.rubocop]
+ B[server]
+ C[json_rpc_handler]
A --> B
B --> C
```
diff --git a/tutorials/mcp-ruby-sdk-tutorial/08-production-deployment-and-upgrade-strategy.md b/tutorials/mcp-ruby-sdk-tutorial/08-production-deployment-and-upgrade-strategy.md
index ec4f0313..89c7007e 100644
--- a/tutorials/mcp-ruby-sdk-tutorial/08-production-deployment-and-upgrade-strategy.md
+++ b/tutorials/mcp-ruby-sdk-tutorial/08-production-deployment-and-upgrade-strategy.md
@@ -41,94 +41,8 @@ You now have a production rollout and upgrade strategy for Ruby MCP implementati
Return to the [MCP Ruby SDK Tutorial index](README.md).
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `dev.yml`
-
-The `dev` module in [`dev.yml`](https://github.com/modelcontextprotocol/ruby-sdk/blob/HEAD/dev.yml) handles a key part of this chapter's functionality:
-
-```yml
-name: mcp-ruby
-
-type: ruby
-
-up:
- - ruby
- - bundler
-
-commands:
- console:
- desc: Open console with the gem loaded
- run: bin/console
- build:
- desc: Build the gem using rake build
- run: bin/rake build
- test:
- desc: Run tests
- syntax:
- argument: file
- optional: args...
- run: |
- if [[ $# -eq 0 ]]; then
- bin/rake test
- else
- bin/rake -I test "$@"
- fi
- style:
- desc: Run rubocop
- aliases: [rubocop, lint]
- run: bin/rake rubocop
-
-```
-
-This module is important because it defines how MCP Ruby SDK Tutorial: Building MCP Servers and Clients in Ruby implements the patterns covered in this chapter.
-
-### `examples/streamable_http_server.rb`
-
-The `streamable_http_server` module in [`examples/streamable_http_server.rb`](https://github.com/modelcontextprotocol/ruby-sdk/blob/HEAD/examples/streamable_http_server.rb) handles a key part of this chapter's functionality:
-
-```rb
-# frozen_string_literal: true
-
-$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
-require "mcp"
-require "rack/cors"
-require "rackup"
-require "json"
-require "logger"
-
-# Create a logger for SSE-specific logging
-sse_logger = Logger.new($stdout)
-sse_logger.formatter = proc do |severity, datetime, _progname, msg|
- "[SSE] #{severity} #{datetime.strftime("%H:%M:%S.%L")} - #{msg}\n"
-end
-
-# Tool that returns a response that will be sent via SSE if a stream is active
-class NotificationTool < MCP::Tool
- tool_name "notification_tool"
- description "Returns a notification message that will be sent via SSE if stream is active"
- input_schema(
- properties: {
- message: { type: "string", description: "Message to send via SSE" },
- delay: { type: "number", description: "Delay in seconds before returning (optional)" },
- },
- required: ["message"],
- )
-
- class << self
- attr_accessor :logger
-
- def call(message:, delay: 0)
- sleep(delay) if delay > 0
-
- logger&.info("Returning notification message: #{message}")
-
-```
-
-This module is important because it defines how MCP Ruby SDK Tutorial: Building MCP Servers and Clients in Ruby implements the patterns covered in this chapter.
-
### `.rubocop.yml`
The `.rubocop` module in [`.rubocop.yml`](https://github.com/modelcontextprotocol/ruby-sdk/blob/HEAD/.rubocop.yml) handles a key part of this chapter's functionality:
@@ -157,14 +71,102 @@ Minitest/LiteralAsActualArgument:
This module is important because it defines how MCP Ruby SDK Tutorial: Building MCP Servers and Clients in Ruby implements the patterns covered in this chapter.
+### `conformance/server.rb`
+
+The `server` module in [`conformance/server.rb`](https://github.com/modelcontextprotocol/ruby-sdk/blob/HEAD/conformance/server.rb) handles a key part of this chapter's functionality:
+
+```rb
+# frozen_string_literal: true
+
+require "rackup"
+require "json"
+require "uri"
+require_relative "../lib/mcp"
+
+module Conformance
+ # 1x1 red PNG pixel (matches TypeScript SDK and Python SDK)
+ BASE64_1X1_PNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8DwHwAFBQIAX8jx0gAAAABJRU5ErkJggg=="
+
+ # Minimal WAV file (matches TypeScript SDK and Python SDK)
+ BASE64_MINIMAL_WAV = "UklGRiYAAABXQVZFZm10IBAAAAABAAEAQB8AAAB9AAACABAAZGF0YQIAAAA="
+
+ module Tools
+ class TestSimpleText < MCP::Tool
+ tool_name "test_simple_text"
+ description "A tool that returns simple text content"
+
+ class << self
+ def call(**_args)
+ MCP::Tool::Response.new([MCP::Content::Text.new("This is a simple text response for testing.").to_h])
+ end
+ end
+ end
+
+ class TestImageContent < MCP::Tool
+ tool_name "test_image_content"
+ description "A tool that returns image content"
+
+ class << self
+ def call(**_args)
+ MCP::Tool::Response.new([MCP::Content::Image.new(BASE64_1X1_PNG, "image/png").to_h])
+ end
+ end
+```
+
+This module is important because it defines how MCP Ruby SDK Tutorial: Building MCP Servers and Clients in Ruby implements the patterns covered in this chapter.
+
+### `lib/json_rpc_handler.rb`
+
+The `json_rpc_handler` module in [`lib/json_rpc_handler.rb`](https://github.com/modelcontextprotocol/ruby-sdk/blob/HEAD/lib/json_rpc_handler.rb) handles a key part of this chapter's functionality:
+
+```rb
+# frozen_string_literal: true
+
+require "json"
+
+module JsonRpcHandler
+ class Version
+ V1_0 = "1.0"
+ V2_0 = "2.0"
+ end
+
+ class ErrorCode
+ INVALID_REQUEST = -32600
+ METHOD_NOT_FOUND = -32601
+ INVALID_PARAMS = -32602
+ INTERNAL_ERROR = -32603
+ PARSE_ERROR = -32700
+ end
+
+ DEFAULT_ALLOWED_ID_CHARACTERS = /\A[a-zA-Z0-9_-]+\z/
+
+ extend self
+
+ def handle(request, id_validation_pattern: DEFAULT_ALLOWED_ID_CHARACTERS, &method_finder)
+ if request.is_a?(Array)
+ return error_response(id: :unknown_id, id_validation_pattern: id_validation_pattern, error: {
+ code: ErrorCode::INVALID_REQUEST,
+ message: "Invalid Request",
+ data: "Request is an empty array",
+ }) if request.empty?
+
+ # Handle batch requests
+ responses = request.map { |req| process_request(req, id_validation_pattern: id_validation_pattern, &method_finder) }.compact
+
+ # A single item is hoisted out of the array
+ return responses.first if responses.one?
+```
+
+This module is important because it defines how MCP Ruby SDK Tutorial: Building MCP Servers and Clients in Ruby implements the patterns covered in this chapter.
+
## How These Components Connect
```mermaid
flowchart TD
- A[dev]
- B[streamable_http_server]
- C[.rubocop]
+ A[.rubocop]
+ B[server]
+ C[json_rpc_handler]
A --> B
B --> C
```
diff --git a/tutorials/mcp-rust-sdk-tutorial/01-getting-started-and-crate-setup.md b/tutorials/mcp-rust-sdk-tutorial/01-getting-started-and-crate-setup.md
index fd9ec70b..663b3e87 100644
--- a/tutorials/mcp-rust-sdk-tutorial/01-getting-started-and-crate-setup.md
+++ b/tutorials/mcp-rust-sdk-tutorial/01-getting-started-and-crate-setup.md
@@ -39,170 +39,168 @@ You now have a dependency baseline that keeps early integrations predictable.
Next: [Chapter 2: Service Model and Macro-Based Tooling](02-service-model-and-macro-based-tooling.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `examples/servers/src/completion_stdio.rs`
+### `crates/rmcp/src/service.rs`
-The `SqlQueryArgs` interface in [`examples/servers/src/completion_stdio.rs`](https://github.com/modelcontextprotocol/rust-sdk/blob/HEAD/examples/servers/src/completion_stdio.rs) handles a key part of this chapter's functionality:
+The `serve_directly` function in [`crates/rmcp/src/service.rs`](https://github.com/modelcontextprotocol/rust-sdk/blob/HEAD/crates/rmcp/src/service.rs) handles a key part of this chapter's functionality:
```rs
-#[derive(Debug, Serialize, Deserialize, JsonSchema)]
-#[schemars(description = "SQL query builder with progressive completion")]
-pub struct SqlQueryArgs {
- #[schemars(description = "SQL operation type (SELECT, INSERT, UPDATE, DELETE)")]
- pub operation: String,
- #[schemars(description = "Database table name")]
- pub table: String,
- #[schemars(description = "Columns to select/update (only for SELECT/UPDATE)")]
- pub columns: Option<String>,
- #[schemars(description = "WHERE clause condition (optional for all operations)")]
- pub where_clause: Option<String>,
- #[schemars(description = "Values to insert (only for INSERT)")]
- pub values: Option<String>,
-}
-/// SQL query builder server with progressive completion
-#[derive(Clone)]
-pub struct SqlQueryServer {
- prompt_router: PromptRouter<SqlQueryServer>,
+/// Use this function to skip initialization process
+pub fn serve_directly<R, S, T, E, A>(
+ service: S,
+ transport: T,
+ peer_info: Option<R::PeerInfo>,
+) -> RunningService<R, S>
+where
+ R: ServiceRole,
+ S: Service<R>,
+ T: IntoTransport<R, E, A>,
+ E: std::error::Error + Send + Sync + 'static,
+{
+ serve_directly_with_ct(service, transport, peer_info, Default::default())
}
-impl SqlQueryServer {
- pub fn new() -> Self {
- Self {
- prompt_router: Self::prompt_router(),
- }
- }
+/// Use this function to skip initialization process
+pub fn serve_directly_with_ct<R, S, T, E, A>(
+ service: S,
+ transport: T,
+ peer_info: Option<R::PeerInfo>,
+ ct: CancellationToken,
+) -> RunningService<R, S>
+where
+ R: ServiceRole,
+ S: Service<R>,
+ T: IntoTransport<R, E, A>,
+ E: std::error::Error + Send + Sync + 'static,
+{
+ let (peer, peer_rx) = Peer::new(Arc::new(AtomicU32RequestIdProvider::default()), peer_info);
+ serve_inner(service, transport.into_transport(), peer, peer_rx, ct)
}
-
-impl Default for SqlQueryServer {
- fn default() -> Self {
- Self::new()
```
-This interface is important because it defines how MCP Rust SDK Tutorial: Building High-Performance MCP Services with RMCP implements the patterns covered in this chapter.
+This function is important because it defines how MCP Rust SDK Tutorial: Building High-Performance MCP Services with RMCP implements the patterns covered in this chapter.
-### `examples/servers/src/completion_stdio.rs`
+### `crates/rmcp/src/service.rs`
-The `SqlQueryServer` interface in [`examples/servers/src/completion_stdio.rs`](https://github.com/modelcontextprotocol/rust-sdk/blob/HEAD/examples/servers/src/completion_stdio.rs) handles a key part of this chapter's functionality:
+The `serve_directly_with_ct` function in [`crates/rmcp/src/service.rs`](https://github.com/modelcontextprotocol/rust-sdk/blob/HEAD/crates/rmcp/src/service.rs) handles a key part of this chapter's functionality:
```rs
-/// SQL query builder server with progressive completion
-#[derive(Clone)]
-pub struct SqlQueryServer {
- prompt_router: PromptRouter<SqlQueryServer>,
+ E: std::error::Error + Send + Sync + 'static,
+{
+ serve_directly_with_ct(service, transport, peer_info, Default::default())
}
-impl SqlQueryServer {
- pub fn new() -> Self {
- Self {
- prompt_router: Self::prompt_router(),
- }
- }
+/// Use this function to skip initialization process
+pub fn serve_directly_with_ct<R, S, T, E, A>(
+ service: S,
+ transport: T,
+ peer_info: Option<R::PeerInfo>,
+ ct: CancellationToken,
+) -> RunningService<R, S>
+where
+ R: ServiceRole,
+ S: Service<R>,
+ T: IntoTransport<R, E, A>,
+ E: std::error::Error + Send + Sync + 'static,
+{
+ let (peer, peer_rx) = Peer::new(Arc::new(AtomicU32RequestIdProvider::default()), peer_info);
+ serve_inner(service, transport.into_transport(), peer, peer_rx, ct)
}
-impl Default for SqlQueryServer {
- fn default() -> Self {
- Self::new()
- }
-}
-
-impl SqlQueryServer {
- /// Fuzzy matching with scoring for completion suggestions
- fn fuzzy_match(&self, query: &str, candidates: &[&str]) -> Vec<String> {
- if query.is_empty() {
- return candidates.iter().take(10).map(|s| s.to_string()).collect();
- }
-
- let query_lower = query.to_lowercase();
- let mut scored_matches = Vec::new();
-
- for candidate in candidates {
- let candidate_lower = candidate.to_lowercase();
+/// Spawn a task that may hold `!Send` state when the `local` feature is active.
+///
+/// Without the `local` feature this is `tokio::spawn` (requires `Future: Send + 'static`).
+/// With `local` it uses `tokio::task::spawn_local` (requires only `Future: 'static`).
+#[cfg(not(feature = "local"))]
+fn spawn_service_task<F>(future: F) -> tokio::task::JoinHandle<F::Output>
+where
+ F: Future + Send + 'static,
+ F::Output: Send + 'static,
+{
```
-This interface is important because it defines how MCP Rust SDK Tutorial: Building High-Performance MCP Services with RMCP implements the patterns covered in this chapter.
+This function is important because it defines how MCP Rust SDK Tutorial: Building High-Performance MCP Services with RMCP implements the patterns covered in this chapter.
-### `conformance/src/bin/client.rs`
+### `crates/rmcp/src/service.rs`
-The `ConformanceContext` interface in [`conformance/src/bin/client.rs`](https://github.com/modelcontextprotocol/rust-sdk/blob/HEAD/conformance/src/bin/client.rs) handles a key part of this chapter's functionality:
+The `to` interface in [`crates/rmcp/src/service.rs`](https://github.com/modelcontextprotocol/rust-sdk/blob/HEAD/crates/rmcp/src/service.rs) handles a key part of this chapter's functionality:
```rs
-
-#[derive(Debug, Default, serde::Deserialize)]
-struct ConformanceContext {
- #[serde(default)]
- client_id: Option<String>,
- #[serde(default)]
- client_secret: Option<String>,
- // client-credentials-jwt
- #[serde(default)]
- private_key_pem: Option<String>,
- #[serde(default)]
- signing_algorithm: Option<String>,
-}
-
-fn load_context() -> ConformanceContext {
- std::env::var("MCP_CONFORMANCE_CONTEXT")
- .ok()
- .and_then(|s| serde_json::from_str(&s).ok())
- .unwrap_or_default()
-}
-
-// ─── Client handlers ────────────────────────────────────────────────────────
-
-/// A basic client handler that does nothing special
-struct BasicClientHandler;
-impl ClientHandler for BasicClientHandler {}
-
-/// A client handler that handles elicitation requests by applying schema defaults.
-struct ElicitationDefaultsClientHandler;
-
-impl ClientHandler for ElicitationDefaultsClientHandler {
- fn get_info(&self) -> ClientInfo {
+ NumberOrString, ProgressToken, RequestId,
+ },
+ transport::{DynamicTransportError, IntoTransport, Transport},
+};
+#[cfg(feature = "client")]
+mod client;
+#[cfg(feature = "client")]
+pub use client::*;
+#[cfg(feature = "server")]
+mod server;
+#[cfg(feature = "server")]
+pub use server::*;
+#[cfg(feature = "tower")]
+mod tower;
+use tokio_util::sync::{CancellationToken, DropGuard};
+#[cfg(feature = "tower")]
+pub use tower::*;
+use tracing::{Instrument as _, instrument};
+#[derive(Error, Debug)]
+#[non_exhaustive]
+pub enum ServiceError {
+ #[error("Mcp error: {0}")]
+ McpError(McpError),
+ #[error("Transport send error: {0}")]
+ TransportSend(DynamicTransportError),
+ #[error("Transport closed")]
+ TransportClosed,
+ #[error("Unexpected response type")]
+ UnexpectedResponse,
+ #[error("task cancelled for reason {}", reason.as_deref().unwrap_or("<unknown>"))]
+ Cancelled { reason: Option<String> },
+ #[error("request timeout after {}", chrono::Duration::from_std(*timeout).unwrap_or_default())]
```
This interface is important because it defines how MCP Rust SDK Tutorial: Building High-Performance MCP Services with RMCP implements the patterns covered in this chapter.
-### `conformance/src/bin/client.rs`
+### `crates/rmcp/src/service.rs`
-The `BasicClientHandler` interface in [`conformance/src/bin/client.rs`](https://github.com/modelcontextprotocol/rust-sdk/blob/HEAD/conformance/src/bin/client.rs) handles a key part of this chapter's functionality:
+The `to` interface in [`crates/rmcp/src/service.rs`](https://github.com/modelcontextprotocol/rust-sdk/blob/HEAD/crates/rmcp/src/service.rs) handles a key part of this chapter's functionality:
```rs
-
-/// A basic client handler that does nothing special
-struct BasicClientHandler;
-impl ClientHandler for BasicClientHandler {}
-
-/// A client handler that handles elicitation requests by applying schema defaults.
-struct ElicitationDefaultsClientHandler;
-
-impl ClientHandler for ElicitationDefaultsClientHandler {
- fn get_info(&self) -> ClientInfo {
- let mut info = ClientInfo::default();
- info.capabilities.elicitation = Some(ElicitationCapability {
- form: Some(FormElicitationCapability {
- schema_validation: Some(true),
- }),
- url: None,
- });
- info
- }
-
- async fn create_elicitation(
- &self,
- request: CreateElicitationRequestParams,
- _cx: RequestContext<RoleClient>,
- ) -> Result<CreateElicitationResult, ErrorData> {
- let content = match &request {
- CreateElicitationRequestParams::FormElicitationParams {
- requested_schema, ..
- } => {
- let mut defaults = serde_json::Map::new();
- for (name, prop) in &requested_schema.properties {
- match prop {
+ NumberOrString, ProgressToken, RequestId,
+ },
+ transport::{DynamicTransportError, IntoTransport, Transport},
+};
+#[cfg(feature = "client")]
+mod client;
+#[cfg(feature = "client")]
+pub use client::*;
+#[cfg(feature = "server")]
+mod server;
+#[cfg(feature = "server")]
+pub use server::*;
+#[cfg(feature = "tower")]
+mod tower;
+use tokio_util::sync::{CancellationToken, DropGuard};
+#[cfg(feature = "tower")]
+pub use tower::*;
+use tracing::{Instrument as _, instrument};
+#[derive(Error, Debug)]
+#[non_exhaustive]
+pub enum ServiceError {
+ #[error("Mcp error: {0}")]
+ McpError(McpError),
+ #[error("Transport send error: {0}")]
+ TransportSend(DynamicTransportError),
+ #[error("Transport closed")]
+ TransportClosed,
+ #[error("Unexpected response type")]
+ UnexpectedResponse,
+ #[error("task cancelled for reason {}", reason.as_deref().unwrap_or("<unknown>"))]
+ Cancelled { reason: Option<String> },
+ #[error("request timeout after {}", chrono::Duration::from_std(*timeout).unwrap_or_default())]
```
This interface is important because it defines how MCP Rust SDK Tutorial: Building High-Performance MCP Services with RMCP implements the patterns covered in this chapter.
@@ -212,11 +210,11 @@ This interface is important because it defines how MCP Rust SDK Tutorial: Buildi
```mermaid
flowchart TD
- A[SqlQueryArgs]
- B[SqlQueryServer]
- C[ConformanceContext]
- D[BasicClientHandler]
- E[ElicitationDefaultsClientHandler]
+ A[serve_directly]
+ B[serve_directly_with_ct]
+ C[to]
+ D[to]
+ E[to]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-rust-sdk-tutorial/02-service-model-and-macro-based-tooling.md b/tutorials/mcp-rust-sdk-tutorial/02-service-model-and-macro-based-tooling.md
index 0e233a08..224624b8 100644
--- a/tutorials/mcp-rust-sdk-tutorial/02-service-model-and-macro-based-tooling.md
+++ b/tutorials/mcp-rust-sdk-tutorial/02-service-model-and-macro-based-tooling.md
@@ -38,170 +38,168 @@ You now have a practical model for macro-driven capability design in Rust.
Next: [Chapter 3: Transports: stdio, Streamable HTTP, and Custom Channels](03-transports-stdio-streamable-http-and-custom-channels.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `examples/servers/src/complex_auth_streamhttp.rs`
+### `crates/rmcp/src/service.rs`
-The `AuthSession` interface in [`examples/servers/src/complex_auth_streamhttp.rs`](https://github.com/modelcontextprotocol/rust-sdk/blob/HEAD/examples/servers/src/complex_auth_streamhttp.rs) handles a key part of this chapter's functionality:
+The `PeerRequestOptions` interface in [`crates/rmcp/src/service.rs`](https://github.com/modelcontextprotocol/rust-sdk/blob/HEAD/crates/rmcp/src/service.rs) handles a key part of this chapter's functionality:
```rs
-struct McpOAuthStore {
- clients: Arc<RwLock<HashMap<String, OAuthClientConfig>>>,
- auth_sessions: Arc<RwLock<HashMap<String, AuthSession>>>,
- access_tokens: Arc<RwLock<HashMap<String, McpAccessToken>>>,
+pub struct RequestHandle<R: ServiceRole> {
+ pub rx: tokio::sync::oneshot::Receiver<Result<R::PeerResp, ServiceError>>,
+ pub options: PeerRequestOptions,
+ pub peer: Peer<R>,
+ pub id: RequestId,
+ pub progress_token: ProgressToken,
}
-impl McpOAuthStore {
- fn new() -> Self {
- let mut clients = HashMap::new();
- clients.insert(
- "mcp-client".to_string(),
- OAuthClientConfig {
- client_id: "mcp-client".to_string(),
- client_secret: Some("mcp-client-secret".to_string()),
- scopes: vec!["profile".to_string(), "email".to_string()],
- redirect_uri: "http://localhost:8080/callback".to_string(),
- },
- );
-
- Self {
- clients: Arc::new(RwLock::new(clients)),
- auth_sessions: Arc::new(RwLock::new(HashMap::new())),
- access_tokens: Arc::new(RwLock::new(HashMap::new())),
- }
- }
-
- async fn validate_client(
- &self,
- client_id: &str,
- redirect_uri: &str,
- ) -> Option<OAuthClientConfig> {
- let clients = self.clients.read().await;
+impl<R: ServiceRole> RequestHandle<R> {
+ pub const REQUEST_TIMEOUT_REASON: &str = "request timeout";
+ pub async fn await_response(self) -> Result<R::PeerResp, ServiceError> {
+ if let Some(timeout) = self.options.timeout {
+ let timeout_result = tokio::time::timeout(timeout, async move {
+ self.rx.await.map_err(|_e| ServiceError::TransportClosed)?
+ })
+ .await;
+ match timeout_result {
+ Ok(response) => response,
+ Err(_) => {
+ let error = Err(ServiceError::Timeout { timeout });
+ // cancel this request
+ let notification = CancelledNotification {
+ params: CancelledNotificationParam {
+ request_id: self.id,
+ reason: Some(Self::REQUEST_TIMEOUT_REASON.to_owned()),
+ },
+ method: crate::model::CancelledNotificationMethod,
+ extensions: Default::default(),
+ };
+ let _ = self.peer.send_notification(notification.into()).await;
+ error
+ }
```
This interface is important because it defines how MCP Rust SDK Tutorial: Building High-Performance MCP Services with RMCP implements the patterns covered in this chapter.
-### `examples/servers/src/complex_auth_streamhttp.rs`
+### `crates/rmcp/src/service.rs`
-The `AuthToken` interface in [`examples/servers/src/complex_auth_streamhttp.rs`](https://github.com/modelcontextprotocol/rust-sdk/blob/HEAD/examples/servers/src/complex_auth_streamhttp.rs) handles a key part of this chapter's functionality:
+The `RunningService` interface in [`crates/rmcp/src/service.rs`](https://github.com/modelcontextprotocol/rust-sdk/blob/HEAD/crates/rmcp/src/service.rs) handles a key part of this chapter's functionality:
```rs
+ self,
+ transport: T,
+ ) -> impl Future<Output = Result<RunningService<R, Self>, R::InitializeError>> + MaybeSendFuture
+ where
+ T: IntoTransport<R, E, A>,
+ E: std::error::Error + Send + Sync + 'static,
+ Self: Sized,
+ {
+ Self::serve_with_ct(self, transport, Default::default())
+ }
+ fn serve_with_ct<T, E, A>(
+ self,
+ transport: T,
+ ct: CancellationToken,
+ ) -> impl Future<Output = Result<RunningService<R, Self>, R::InitializeError>> + MaybeSendFuture
+ where
+ T: IntoTransport<R, E, A>,
+ E: std::error::Error + Send + Sync + 'static,
+ Self: Sized;
+}
+
+impl<R: ServiceRole> Service<R> for Box<dyn DynService<R>> {
+ fn handle_request(
&self,
- session_id: &str,
- token: AuthToken,
- ) -> Result<(), String> {
- let mut sessions = self.auth_sessions.write().await;
- if let Some(session) = sessions.get_mut(session_id) {
- session.auth_token = Some(token);
- Ok(())
- } else {
- Err("Session not found".to_string())
- }
+ request: R::PeerReq,
+ context: RequestContext<R>,
+ ) -> impl Future<Output = Result<R::Resp, McpError>> + MaybeSendFuture + '_ {
+ DynService::handle_request(self.as_ref(), request, context)
}
- async fn create_mcp_token(&self, session_id: &str) -> Result<McpAccessToken, String> {
- let sessions = self.auth_sessions.read().await;
- if let Some(session) = sessions.get(session_id) {
- if let Some(auth_token) = &session.auth_token {
- let access_token = format!("mcp-token-{}", Uuid::new_v4());
- let token = McpAccessToken {
- access_token: access_token.clone(),
- token_type: "Bearer".to_string(),
- expires_in: 3600,
- refresh_token: format!("mcp-refresh-{}", Uuid::new_v4()),
- scope: session.scope.clone(),
- auth_token: auth_token.clone(),
- client_id: session.client_id.clone(),
- };
-
- self.access_tokens
- .write()
- .await
- .insert(access_token.clone(), token.clone());
+ fn handle_notification(
+ &self,
```
This interface is important because it defines how MCP Rust SDK Tutorial: Building High-Performance MCP Services with RMCP implements the patterns covered in this chapter.
-### `examples/servers/src/complex_auth_streamhttp.rs`
+### `crates/rmcp/src/service.rs`
-The `McpAccessToken` interface in [`examples/servers/src/complex_auth_streamhttp.rs`](https://github.com/modelcontextprotocol/rust-sdk/blob/HEAD/examples/servers/src/complex_auth_streamhttp.rs) handles a key part of this chapter's functionality:
+The `RunningServiceCancellationToken` interface in [`crates/rmcp/src/service.rs`](https://github.com/modelcontextprotocol/rust-sdk/blob/HEAD/crates/rmcp/src/service.rs) handles a key part of this chapter's functionality:
```rs
- clients: Arc<RwLock<HashMap<String, OAuthClientConfig>>>,
- auth_sessions: Arc<RwLock<HashMap<String, AuthSession>>>,
- access_tokens: Arc<RwLock<HashMap<String, McpAccessToken>>>,
-}
+ }
+ #[inline]
+ pub fn cancellation_token(&self) -> RunningServiceCancellationToken {
+ RunningServiceCancellationToken(self.cancellation_token.clone())
+ }
-impl McpOAuthStore {
- fn new() -> Self {
- let mut clients = HashMap::new();
- clients.insert(
- "mcp-client".to_string(),
- OAuthClientConfig {
- client_id: "mcp-client".to_string(),
- client_secret: Some("mcp-client-secret".to_string()),
- scopes: vec!["profile".to_string(), "email".to_string()],
- redirect_uri: "http://localhost:8080/callback".to_string(),
- },
- );
-
- Self {
- clients: Arc::new(RwLock::new(clients)),
- auth_sessions: Arc::new(RwLock::new(HashMap::new())),
- access_tokens: Arc::new(RwLock::new(HashMap::new())),
+ /// Returns true if the service has been closed or cancelled.
+ #[inline]
+ pub fn is_closed(&self) -> bool {
+ self.handle.is_none() || self.cancellation_token.is_cancelled()
+ }
+
+ /// Wait for the service to complete.
+ ///
+ /// This will block until the service loop terminates (either due to
+ /// cancellation, transport closure, or an error).
+ #[inline]
+ pub async fn waiting(mut self) -> Result<QuitReason, tokio::task::JoinError> {
+ match self.handle.take() {
+ Some(handle) => handle.await,
+ None => Ok(QuitReason::Closed),
}
}
- async fn validate_client(
- &self,
- client_id: &str,
- redirect_uri: &str,
- ) -> Option<OAuthClientConfig> {
- let clients = self.clients.read().await;
- if let Some(client) = clients.get(client_id) {
+ /// Gracefully close the connection and wait for cleanup to complete.
+ ///
+ /// This method cancels the service, waits for the background task to finish
+ /// (which includes calling `transport.close()`), and ensures all cleanup
+ /// operations complete before returning.
+ ///
+ /// Unlike [`cancel`](Self::cancel), this method takes `&mut self` and can be
+ /// called without consuming the `RunningService`. After calling this method,
```
This interface is important because it defines how MCP Rust SDK Tutorial: Building High-Performance MCP Services with RMCP implements the patterns covered in this chapter.
-### `examples/servers/src/complex_auth_streamhttp.rs`
+### `crates/rmcp/src/service.rs`
-The `AuthorizeQuery` interface in [`examples/servers/src/complex_auth_streamhttp.rs`](https://github.com/modelcontextprotocol/rust-sdk/blob/HEAD/examples/servers/src/complex_auth_streamhttp.rs) handles a key part of this chapter's functionality:
+The `RequestContext` interface in [`crates/rmcp/src/service.rs`](https://github.com/modelcontextprotocol/rust-sdk/blob/HEAD/crates/rmcp/src/service.rs) handles a key part of this chapter's functionality:
```rs
-
-#[derive(Debug, Deserialize)]
-struct AuthorizeQuery {
- #[allow(dead_code)]
- response_type: String,
- client_id: String,
- redirect_uri: String,
- scope: Option<String>,
- state: Option<String>,
+ &self,
+ request: R::PeerReq,
+ context: RequestContext<R>,
+ ) -> impl Future<Output = Result<R::Resp, McpError>> + MaybeSendFuture + '_;
+ fn handle_notification(
+ &self,
+ notification: R::PeerNot,
+ context: NotificationContext<R>,
+ ) -> impl Future<Output = Result<(), McpError>> + MaybeSendFuture + '_;
+ fn get_info(&self) -> R::Info;
}
-#[derive(Debug, Deserialize, Serialize)]
-struct TokenRequest {
- grant_type: String,
- #[serde(default)]
- code: String,
- #[serde(default)]
- client_id: String,
- #[serde(default)]
- client_secret: String,
- #[serde(default)]
- redirect_uri: String,
- #[serde(default)]
- code_verifier: Option<String>,
- #[serde(default)]
- refresh_token: String,
+#[cfg(feature = "local")]
+pub trait Service<R: ServiceRole>: 'static {
+ fn handle_request(
+ &self,
+ request: R::PeerReq,
+ context: RequestContext<R>,
+ ) -> impl Future<Output = Result<R::Resp, McpError>> + MaybeSendFuture + '_;
+ fn handle_notification(
+ &self,
+ notification: R::PeerNot,
+ context: NotificationContext<R>,
+ ) -> impl Future<Output = Result<(), McpError>> + MaybeSendFuture + '_;
+ fn get_info(&self) -> R::Info;
}
-fn generate_random_string(length: usize) -> String {
- rand::rng()
- .sample_iter(&Alphanumeric)
- .take(length)
+pub trait ServiceExt<R: ServiceRole>: Service<R> + Sized {
+ /// Convert this service to a dynamic boxed service
+ ///
+ /// This could be very helpful when you want to store the services in a collection
+ fn into_dyn(self) -> Box<dyn DynService<R>> {
```
This interface is important because it defines how MCP Rust SDK Tutorial: Building High-Performance MCP Services with RMCP implements the patterns covered in this chapter.
@@ -211,11 +209,11 @@ This interface is important because it defines how MCP Rust SDK Tutorial: Buildi
```mermaid
flowchart TD
- A[AuthSession]
- B[AuthToken]
- C[McpAccessToken]
- D[AuthorizeQuery]
- E[TokenRequest]
+ A[PeerRequestOptions]
+ B[RunningService]
+ C[RunningServiceCancellationToken]
+ D[RequestContext]
+ E[NotificationContext]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-rust-sdk-tutorial/03-transports-stdio-streamable-http-and-custom-channels.md b/tutorials/mcp-rust-sdk-tutorial/03-transports-stdio-streamable-http-and-custom-channels.md
index 2d1434a7..8b9e9292 100644
--- a/tutorials/mcp-rust-sdk-tutorial/03-transports-stdio-streamable-http-and-custom-channels.md
+++ b/tutorials/mcp-rust-sdk-tutorial/03-transports-stdio-streamable-http-and-custom-channels.md
@@ -39,170 +39,168 @@ You now have a transport planning framework for matching capability requirements
Next: [Chapter 4: Client Patterns, Sampling, and Batching Flows](04-client-patterns-sampling-and-batching-flows.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `crates/rmcp/src/service.rs`
-The `serve_directly_with_ct` function in [`crates/rmcp/src/service.rs`](https://github.com/modelcontextprotocol/rust-sdk/blob/HEAD/crates/rmcp/src/service.rs) handles a key part of this chapter's functionality:
+The `MaybeSendFuture` interface in [`crates/rmcp/src/service.rs`](https://github.com/modelcontextprotocol/rust-sdk/blob/HEAD/crates/rmcp/src/service.rs) handles a key part of this chapter's functionality:
```rs
- E: std::error::Error + Send + Sync + 'static,
-{
- serve_directly_with_ct(service, transport, peer_info, Default::default())
-}
+//
+// `MaybeSend` – supertrait alias: `Send + Sync` without `local`, empty with `local`
+// `MaybeSendFuture` – future bound alias: `Send` without `local`, empty with `local`
+// `MaybeBoxFuture` – boxed future type: `BoxFuture` without `local`, `LocalBoxFuture` with `local`
+// ---------------------------------------------------------------------------
-/// Use this function to skip initialization process
-pub fn serve_directly_with_ct<R, S, T, E, A>(
- service: S,
- transport: T,
- peer_info: Option<R::PeerInfo>,
- ct: CancellationToken,
-) -> RunningService<R, S>
-where
- R: ServiceRole,
- S: Service<R>,
- T: IntoTransport<R, E, A>,
- E: std::error::Error + Send + Sync + 'static,
-{
- let (peer, peer_rx) = Peer::new(Arc::new(AtomicU32RequestIdProvider::default()), peer_info);
- serve_inner(service, transport.into_transport(), peer, peer_rx, ct)
-}
+#[cfg(not(feature = "local"))]
+#[doc(hidden)]
+pub trait MaybeSend: Send + Sync {}
+#[cfg(not(feature = "local"))]
+impl<T: Send + Sync> MaybeSend for T {}
+
+#[cfg(feature = "local")]
+#[doc(hidden)]
+pub trait MaybeSend {}
+#[cfg(feature = "local")]
+impl<T> MaybeSend for T {}
-/// Spawn a task that may hold `!Send` state when the `local` feature is active.
-///
-/// Without the `local` feature this is `tokio::spawn` (requires `Future: Send + 'static`).
-/// With `local` it uses `tokio::task::spawn_local` (requires only `Future: 'static`).
#[cfg(not(feature = "local"))]
-fn spawn_service_task<F>(future: F) -> tokio::task::JoinHandle<F::Output>
-where
- F: Future + Send + 'static,
- F::Output: Send + 'static,
-{
+#[doc(hidden)]
+pub trait MaybeSendFuture: Send {}
+#[cfg(not(feature = "local"))]
+impl<T: Send> MaybeSendFuture for T {}
+
+#[cfg(feature = "local")]
+#[doc(hidden)]
+pub trait MaybeSendFuture {}
+#[cfg(feature = "local")]
+impl<T> MaybeSendFuture for T {}
+
+#[cfg(not(feature = "local"))]
+pub(crate) type MaybeBoxFuture<'a, T> = BoxFuture<'a, T>;
```
-This function is important because it defines how MCP Rust SDK Tutorial: Building High-Performance MCP Services with RMCP implements the patterns covered in this chapter.
+This interface is important because it defines how MCP Rust SDK Tutorial: Building High-Performance MCP Services with RMCP implements the patterns covered in this chapter.
### `crates/rmcp/src/service.rs`
-The `to` interface in [`crates/rmcp/src/service.rs`](https://github.com/modelcontextprotocol/rust-sdk/blob/HEAD/crates/rmcp/src/service.rs) handles a key part of this chapter's functionality:
+The `MaybeSendFuture` interface in [`crates/rmcp/src/service.rs`](https://github.com/modelcontextprotocol/rust-sdk/blob/HEAD/crates/rmcp/src/service.rs) handles a key part of this chapter's functionality:
```rs
- NumberOrString, ProgressToken, RequestId,
- },
- transport::{DynamicTransportError, IntoTransport, Transport},
-};
-#[cfg(feature = "client")]
-mod client;
-#[cfg(feature = "client")]
-pub use client::*;
-#[cfg(feature = "server")]
-mod server;
-#[cfg(feature = "server")]
-pub use server::*;
-#[cfg(feature = "tower")]
-mod tower;
-use tokio_util::sync::{CancellationToken, DropGuard};
-#[cfg(feature = "tower")]
-pub use tower::*;
-use tracing::{Instrument as _, instrument};
-#[derive(Error, Debug)]
-#[non_exhaustive]
-pub enum ServiceError {
- #[error("Mcp error: {0}")]
- McpError(McpError),
- #[error("Transport send error: {0}")]
- TransportSend(DynamicTransportError),
- #[error("Transport closed")]
- TransportClosed,
- #[error("Unexpected response type")]
- UnexpectedResponse,
- #[error("task cancelled for reason {}", reason.as_deref().unwrap_or("<unknown>"))]
- Cancelled { reason: Option<String> },
- #[error("request timeout after {}", chrono::Duration::from_std(*timeout).unwrap_or_default())]
+//
+// `MaybeSend` – supertrait alias: `Send + Sync` without `local`, empty with `local`
+// `MaybeSendFuture` – future bound alias: `Send` without `local`, empty with `local`
+// `MaybeBoxFuture` – boxed future type: `BoxFuture` without `local`, `LocalBoxFuture` with `local`
+// ---------------------------------------------------------------------------
+
+#[cfg(not(feature = "local"))]
+#[doc(hidden)]
+pub trait MaybeSend: Send + Sync {}
+#[cfg(not(feature = "local"))]
+impl<T: Send + Sync> MaybeSend for T {}
+
+#[cfg(feature = "local")]
+#[doc(hidden)]
+pub trait MaybeSend {}
+#[cfg(feature = "local")]
+impl<T> MaybeSend for T {}
+
+#[cfg(not(feature = "local"))]
+#[doc(hidden)]
+pub trait MaybeSendFuture: Send {}
+#[cfg(not(feature = "local"))]
+impl<T: Send> MaybeSendFuture for T {}
+
+#[cfg(feature = "local")]
+#[doc(hidden)]
+pub trait MaybeSendFuture {}
+#[cfg(feature = "local")]
+impl<T> MaybeSendFuture for T {}
+
+#[cfg(not(feature = "local"))]
+pub(crate) type MaybeBoxFuture<'a, T> = BoxFuture<'a, T>;
```
This interface is important because it defines how MCP Rust SDK Tutorial: Building High-Performance MCP Services with RMCP implements the patterns covered in this chapter.
### `crates/rmcp/src/service.rs`
-The `to` interface in [`crates/rmcp/src/service.rs`](https://github.com/modelcontextprotocol/rust-sdk/blob/HEAD/crates/rmcp/src/service.rs) handles a key part of this chapter's functionality:
+The `TransferObject` interface in [`crates/rmcp/src/service.rs`](https://github.com/modelcontextprotocol/rust-sdk/blob/HEAD/crates/rmcp/src/service.rs) handles a key part of this chapter's functionality:
```rs
- NumberOrString, ProgressToken, RequestId,
- },
- transport::{DynamicTransportError, IntoTransport, Transport},
-};
-#[cfg(feature = "client")]
-mod client;
-#[cfg(feature = "client")]
-pub use client::*;
-#[cfg(feature = "server")]
-mod server;
-#[cfg(feature = "server")]
-pub use server::*;
-#[cfg(feature = "tower")]
-mod tower;
-use tokio_util::sync::{CancellationToken, DropGuard};
-#[cfg(feature = "tower")]
-pub use tower::*;
-use tracing::{Instrument as _, instrument};
-#[derive(Error, Debug)]
-#[non_exhaustive]
-pub enum ServiceError {
- #[error("Mcp error: {0}")]
- McpError(McpError),
- #[error("Transport send error: {0}")]
- TransportSend(DynamicTransportError),
- #[error("Transport closed")]
- TransportClosed,
- #[error("Unexpected response type")]
- UnexpectedResponse,
- #[error("task cancelled for reason {}", reason.as_deref().unwrap_or("<unknown>"))]
- Cancelled { reason: Option<String> },
- #[error("request timeout after {}", chrono::Duration::from_std(*timeout).unwrap_or_default())]
+}
+
+trait TransferObject:
+ std::fmt::Debug + Clone + serde::Serialize + serde::de::DeserializeOwned + Send + Sync + 'static
+{
+}
+
+impl<T> TransferObject for T where
+ T: std::fmt::Debug
+ + serde::Serialize
+ + serde::de::DeserializeOwned
+ + Send
+ + Sync
+ + 'static
+ + Clone
+{
+}
+
+#[allow(private_bounds, reason = "there's no the third implementation")]
+pub trait ServiceRole: std::fmt::Debug + Send + Sync + 'static + Copy + Clone {
+ type Req: TransferObject + GetMeta + GetExtensions;
+ type Resp: TransferObject;
+ type Not: TryInto<CancelledNotification, Error = Self::Not>
+ + From<CancelledNotification>
+ + TransferObject;
+ type PeerReq: TransferObject + GetMeta + GetExtensions;
+ type PeerResp: TransferObject;
+ type PeerNot: TryInto<CancelledNotification, Error = Self::PeerNot>
+ + From<CancelledNotification>
+ + TransferObject
+ + GetMeta
+ + GetExtensions;
```
This interface is important because it defines how MCP Rust SDK Tutorial: Building High-Performance MCP Services with RMCP implements the patterns covered in this chapter.
### `crates/rmcp/src/service.rs`
-The `to` interface in [`crates/rmcp/src/service.rs`](https://github.com/modelcontextprotocol/rust-sdk/blob/HEAD/crates/rmcp/src/service.rs) handles a key part of this chapter's functionality:
+The `ServiceRole` interface in [`crates/rmcp/src/service.rs`](https://github.com/modelcontextprotocol/rust-sdk/blob/HEAD/crates/rmcp/src/service.rs) handles a key part of this chapter's functionality:
```rs
- NumberOrString, ProgressToken, RequestId,
- },
- transport::{DynamicTransportError, IntoTransport, Transport},
-};
-#[cfg(feature = "client")]
-mod client;
-#[cfg(feature = "client")]
-pub use client::*;
-#[cfg(feature = "server")]
-mod server;
-#[cfg(feature = "server")]
-pub use server::*;
-#[cfg(feature = "tower")]
-mod tower;
-use tokio_util::sync::{CancellationToken, DropGuard};
-#[cfg(feature = "tower")]
-pub use tower::*;
-use tracing::{Instrument as _, instrument};
-#[derive(Error, Debug)]
-#[non_exhaustive]
-pub enum ServiceError {
- #[error("Mcp error: {0}")]
- McpError(McpError),
- #[error("Transport send error: {0}")]
- TransportSend(DynamicTransportError),
- #[error("Transport closed")]
- TransportClosed,
- #[error("Unexpected response type")]
- UnexpectedResponse,
- #[error("task cancelled for reason {}", reason.as_deref().unwrap_or("<unknown>"))]
- Cancelled { reason: Option<String> },
- #[error("request timeout after {}", chrono::Duration::from_std(*timeout).unwrap_or_default())]
+
+#[allow(private_bounds, reason = "there's no the third implementation")]
+pub trait ServiceRole: std::fmt::Debug + Send + Sync + 'static + Copy + Clone {
+ type Req: TransferObject + GetMeta + GetExtensions;
+ type Resp: TransferObject;
+ type Not: TryInto<CancelledNotification, Error = Self::Not>
+ + From<CancelledNotification>
+ + TransferObject;
+ type PeerReq: TransferObject + GetMeta + GetExtensions;
+ type PeerResp: TransferObject;
+ type PeerNot: TryInto<CancelledNotification, Error = Self::PeerNot>
+ + From<CancelledNotification>
+ + TransferObject
+ + GetMeta
+ + GetExtensions;
+ type InitializeError;
+ const IS_CLIENT: bool;
+ type Info: TransferObject;
+ type PeerInfo: TransferObject;
+}
+
+pub type TxJsonRpcMessage<R> =
+ JsonRpcMessage<<R as ServiceRole>::Req, <R as ServiceRole>::Resp, <R as ServiceRole>::Not>;
+pub type RxJsonRpcMessage<R> = JsonRpcMessage<
+ <R as ServiceRole>::PeerReq,
+ <R as ServiceRole>::PeerResp,
+ <R as ServiceRole>::PeerNot,
+>;
+
+#[cfg(not(feature = "local"))]
+pub trait Service<R: ServiceRole>: Send + Sync + 'static {
+ fn handle_request(
```
This interface is important because it defines how MCP Rust SDK Tutorial: Building High-Performance MCP Services with RMCP implements the patterns covered in this chapter.
@@ -212,11 +210,11 @@ This interface is important because it defines how MCP Rust SDK Tutorial: Buildi
```mermaid
flowchart TD
- A[serve_directly_with_ct]
- B[to]
- C[to]
- D[to]
- E[AtomicU32Provider]
+ A[MaybeSendFuture]
+ B[MaybeSendFuture]
+ C[TransferObject]
+ D[ServiceRole]
+ E[Service]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-rust-sdk-tutorial/04-client-patterns-sampling-and-batching-flows.md b/tutorials/mcp-rust-sdk-tutorial/04-client-patterns-sampling-and-batching-flows.md
index d2c2f9b0..c28b8085 100644
--- a/tutorials/mcp-rust-sdk-tutorial/04-client-patterns-sampling-and-batching-flows.md
+++ b/tutorials/mcp-rust-sdk-tutorial/04-client-patterns-sampling-and-batching-flows.md
@@ -39,15 +39,19 @@ You now have a client execution model for handling advanced capability flows und
Next: [Chapter 5: Server Patterns: Tools, Resources, Prompts, and Tasks](05-server-patterns-tools-resources-prompts-and-tasks.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `crates/rmcp/src/service.rs`
-The `RunningService` interface in [`crates/rmcp/src/service.rs`](https://github.com/modelcontextprotocol/rust-sdk/blob/HEAD/crates/rmcp/src/service.rs) handles a key part of this chapter's functionality:
+The `DynService` interface in [`crates/rmcp/src/service.rs`](https://github.com/modelcontextprotocol/rust-sdk/blob/HEAD/crates/rmcp/src/service.rs) handles a key part of this chapter's functionality:
```rs
+ ///
+ /// This could be very helpful when you want to store the services in a collection
+ fn into_dyn(self) -> Box<dyn DynService<R>> {
+ Box::new(self)
+ }
+ fn serve<T, E, A>(
self,
transport: T,
) -> impl Future<Output = Result<RunningService<R, Self>, R::InitializeError>> + MaybeSendFuture
@@ -74,135 +78,129 @@ impl<R: ServiceRole> Service<R> for Box<dyn DynService<R>> {
&self,
request: R::PeerReq,
context: RequestContext<R>,
- ) -> impl Future<Output = Result<R::Resp, McpError>> + MaybeSendFuture + '_ {
- DynService::handle_request(self.as_ref(), request, context)
- }
-
- fn handle_notification(
- &self,
```
This interface is important because it defines how MCP Rust SDK Tutorial: Building High-Performance MCP Services with RMCP implements the patterns covered in this chapter.
### `crates/rmcp/src/service.rs`
-The `RunningServiceCancellationToken` interface in [`crates/rmcp/src/service.rs`](https://github.com/modelcontextprotocol/rust-sdk/blob/HEAD/crates/rmcp/src/service.rs) handles a key part of this chapter's functionality:
+The `RequestIdProvider` interface in [`crates/rmcp/src/service.rs`](https://github.com/modelcontextprotocol/rust-sdk/blob/HEAD/crates/rmcp/src/service.rs) handles a key part of this chapter's functionality:
```rs
- }
- #[inline]
- pub fn cancellation_token(&self) -> RunningServiceCancellationToken {
- RunningServiceCancellationToken(self.cancellation_token.clone())
- }
+use tokio::sync::mpsc;
- /// Returns true if the service has been closed or cancelled.
- #[inline]
- pub fn is_closed(&self) -> bool {
- self.handle.is_none() || self.cancellation_token.is_cancelled()
- }
+pub trait RequestIdProvider: Send + Sync + 'static {
+ fn next_request_id(&self) -> RequestId;
+}
- /// Wait for the service to complete.
- ///
- /// This will block until the service loop terminates (either due to
- /// cancellation, transport closure, or an error).
- #[inline]
- pub async fn waiting(mut self) -> Result<QuitReason, tokio::task::JoinError> {
- match self.handle.take() {
- Some(handle) => handle.await,
- None => Ok(QuitReason::Closed),
- }
+pub trait ProgressTokenProvider: Send + Sync + 'static {
+ fn next_progress_token(&self) -> ProgressToken;
+}
+
+pub type AtomicU32RequestIdProvider = AtomicU32Provider;
+pub type AtomicU32ProgressTokenProvider = AtomicU32Provider;
+
+#[derive(Debug, Default)]
+pub struct AtomicU32Provider {
+ id: AtomicU64,
+}
+
+impl RequestIdProvider for AtomicU32Provider {
+ fn next_request_id(&self) -> RequestId {
+ let id = self.id.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
+ // Safe conversion: we start at 0 and increment by 1, so we won't overflow i64::MAX in practice
+ RequestId::Number(id as i64)
}
+}
- /// Gracefully close the connection and wait for cleanup to complete.
- ///
- /// This method cancels the service, waits for the background task to finish
- /// (which includes calling `transport.close()`), and ensures all cleanup
- /// operations complete before returning.
- ///
- /// Unlike [`cancel`](Self::cancel), this method takes `&mut self` and can be
- /// called without consuming the `RunningService`. After calling this method,
+impl ProgressTokenProvider for AtomicU32Provider {
+ fn next_progress_token(&self) -> ProgressToken {
+ let id = self.id.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
+ ProgressToken(NumberOrString::Number(id as i64))
+ }
+}
```
This interface is important because it defines how MCP Rust SDK Tutorial: Building High-Performance MCP Services with RMCP implements the patterns covered in this chapter.
### `crates/rmcp/src/service.rs`
-The `RequestContext` interface in [`crates/rmcp/src/service.rs`](https://github.com/modelcontextprotocol/rust-sdk/blob/HEAD/crates/rmcp/src/service.rs) handles a key part of this chapter's functionality:
+The `ProgressTokenProvider` interface in [`crates/rmcp/src/service.rs`](https://github.com/modelcontextprotocol/rust-sdk/blob/HEAD/crates/rmcp/src/service.rs) handles a key part of this chapter's functionality:
```rs
- &self,
- request: R::PeerReq,
- context: RequestContext<R>,
- ) -> impl Future<Output = Result<R::Resp, McpError>> + MaybeSendFuture + '_;
- fn handle_notification(
- &self,
- notification: R::PeerNot,
- context: NotificationContext<R>,
- ) -> impl Future<Output = Result<(), McpError>> + MaybeSendFuture + '_;
- fn get_info(&self) -> R::Info;
}
-#[cfg(feature = "local")]
-pub trait Service<R: ServiceRole>: 'static {
- fn handle_request(
- &self,
- request: R::PeerReq,
- context: RequestContext<R>,
- ) -> impl Future<Output = Result<R::Resp, McpError>> + MaybeSendFuture + '_;
- fn handle_notification(
- &self,
- notification: R::PeerNot,
- context: NotificationContext<R>,
- ) -> impl Future<Output = Result<(), McpError>> + MaybeSendFuture + '_;
- fn get_info(&self) -> R::Info;
+pub trait ProgressTokenProvider: Send + Sync + 'static {
+ fn next_progress_token(&self) -> ProgressToken;
}
-pub trait ServiceExt<R: ServiceRole>: Service<R> + Sized {
- /// Convert this service to a dynamic boxed service
- ///
- /// This could be very helpful when you want to store the services in a collection
- fn into_dyn(self) -> Box<dyn DynService<R>> {
+pub type AtomicU32RequestIdProvider = AtomicU32Provider;
+pub type AtomicU32ProgressTokenProvider = AtomicU32Provider;
+
+#[derive(Debug, Default)]
+pub struct AtomicU32Provider {
+ id: AtomicU64,
+}
+
+impl RequestIdProvider for AtomicU32Provider {
+ fn next_request_id(&self) -> RequestId {
+ let id = self.id.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
+ // Safe conversion: we start at 0 and increment by 1, so we won't overflow i64::MAX in practice
+ RequestId::Number(id as i64)
+ }
+}
+
+impl ProgressTokenProvider for AtomicU32Provider {
+ fn next_progress_token(&self) -> ProgressToken {
+ let id = self.id.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
+ ProgressToken(NumberOrString::Number(id as i64))
+ }
+}
+
+type Responder<T> = tokio::sync::oneshot::Sender<T>;
+
+/// A handle to a remote request
```
This interface is important because it defines how MCP Rust SDK Tutorial: Building High-Performance MCP Services with RMCP implements the patterns covered in this chapter.
### `crates/rmcp/src/service.rs`
-The `NotificationContext` interface in [`crates/rmcp/src/service.rs`](https://github.com/modelcontextprotocol/rust-sdk/blob/HEAD/crates/rmcp/src/service.rs) handles a key part of this chapter's functionality:
+The `ServiceError` interface in [`crates/rmcp/src/service.rs`](https://github.com/modelcontextprotocol/rust-sdk/blob/HEAD/crates/rmcp/src/service.rs) handles a key part of this chapter's functionality:
```rs
- &self,
- notification: R::PeerNot,
- context: NotificationContext<R>,
- ) -> impl Future<Output = Result<(), McpError>> + MaybeSendFuture + '_;
- fn get_info(&self) -> R::Info;
+#[derive(Error, Debug)]
+#[non_exhaustive]
+pub enum ServiceError {
+ #[error("Mcp error: {0}")]
+ McpError(McpError),
+ #[error("Transport send error: {0}")]
+ TransportSend(DynamicTransportError),
+ #[error("Transport closed")]
+ TransportClosed,
+ #[error("Unexpected response type")]
+ UnexpectedResponse,
+ #[error("task cancelled for reason {}", reason.as_deref().unwrap_or("<unknown>"))]
+ Cancelled { reason: Option<String> },
+ #[error("request timeout after {}", chrono::Duration::from_std(*timeout).unwrap_or_default())]
+ Timeout { timeout: Duration },
}
-#[cfg(feature = "local")]
-pub trait Service<R: ServiceRole>: 'static {
- fn handle_request(
- &self,
- request: R::PeerReq,
- context: RequestContext<R>,
- ) -> impl Future<Output = Result<R::Resp, McpError>> + MaybeSendFuture + '_;
- fn handle_notification(
- &self,
- notification: R::PeerNot,
- context: NotificationContext<R>,
- ) -> impl Future<Output = Result<(), McpError>> + MaybeSendFuture + '_;
- fn get_info(&self) -> R::Info;
+trait TransferObject:
+ std::fmt::Debug + Clone + serde::Serialize + serde::de::DeserializeOwned + Send + Sync + 'static
+{
}
-pub trait ServiceExt<R: ServiceRole>: Service<R> + Sized {
- /// Convert this service to a dynamic boxed service
- ///
- /// This could be very helpful when you want to store the services in a collection
- fn into_dyn(self) -> Box<dyn DynService<R>> {
- Box::new(self)
- }
- fn serve<T, E, A>(
- self,
- transport: T,
+impl<T> TransferObject for T where
+ T: std::fmt::Debug
+ + serde::Serialize
+ + serde::de::DeserializeOwned
+ + Send
+ + Sync
+ + 'static
+ + Clone
+{
+}
```
This interface is important because it defines how MCP Rust SDK Tutorial: Building High-Performance MCP Services with RMCP implements the patterns covered in this chapter.
@@ -212,11 +210,11 @@ This interface is important because it defines how MCP Rust SDK Tutorial: Buildi
```mermaid
flowchart TD
- A[RunningService]
- B[RunningServiceCancellationToken]
- C[RequestContext]
- D[NotificationContext]
- E[alias]
+ A[DynService]
+ B[RequestIdProvider]
+ C[ProgressTokenProvider]
+ D[ServiceError]
+ E[PeerSinkMessage]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-rust-sdk-tutorial/05-server-patterns-tools-resources-prompts-and-tasks.md b/tutorials/mcp-rust-sdk-tutorial/05-server-patterns-tools-resources-prompts-and-tasks.md
index 7f82cb01..732d445f 100644
--- a/tutorials/mcp-rust-sdk-tutorial/05-server-patterns-tools-resources-prompts-and-tasks.md
+++ b/tutorials/mcp-rust-sdk-tutorial/05-server-patterns-tools-resources-prompts-and-tasks.md
@@ -39,170 +39,168 @@ You now have a staged capability approach for building robust Rust MCP servers.
Next: [Chapter 6: OAuth, Security, and Auth Workflows](06-oauth-security-and-auth-workflows.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `crates/rmcp/src/service.rs`
-
-The `MaybeSendFuture` interface in [`crates/rmcp/src/service.rs`](https://github.com/modelcontextprotocol/rust-sdk/blob/HEAD/crates/rmcp/src/service.rs) handles a key part of this chapter's functionality:
-
-```rs
-//
-// `MaybeSend` – supertrait alias: `Send + Sync` without `local`, empty with `local`
-// `MaybeSendFuture` – future bound alias: `Send` without `local`, empty with `local`
-// `MaybeBoxFuture` – boxed future type: `BoxFuture` without `local`, `LocalBoxFuture` with `local`
-// ---------------------------------------------------------------------------
-
-#[cfg(not(feature = "local"))]
-#[doc(hidden)]
-pub trait MaybeSend: Send + Sync {}
-#[cfg(not(feature = "local"))]
-impl<T: Send + Sync> MaybeSend for T {}
-
-#[cfg(feature = "local")]
-#[doc(hidden)]
-pub trait MaybeSend {}
-#[cfg(feature = "local")]
-impl<T> MaybeSend for T {}
-
-#[cfg(not(feature = "local"))]
-#[doc(hidden)]
-pub trait MaybeSendFuture: Send {}
-#[cfg(not(feature = "local"))]
-impl<T: Send> MaybeSendFuture for T {}
-
-#[cfg(feature = "local")]
-#[doc(hidden)]
-pub trait MaybeSendFuture {}
-#[cfg(feature = "local")]
-impl<T> MaybeSendFuture for T {}
-
-#[cfg(not(feature = "local"))]
-pub(crate) type MaybeBoxFuture<'a, T> = BoxFuture<'a, T>;
-```
-
-This interface is important because it defines how MCP Rust SDK Tutorial: Building High-Performance MCP Services with RMCP implements the patterns covered in this chapter.
-
-### `crates/rmcp/src/service.rs`
+### `conformance/src/bin/server.rs`
-The `TransferObject` interface in [`crates/rmcp/src/service.rs`](https://github.com/modelcontextprotocol/rust-sdk/blob/HEAD/crates/rmcp/src/service.rs) handles a key part of this chapter's functionality:
+The `ConformanceServer` interface in [`conformance/src/bin/server.rs`](https://github.com/modelcontextprotocol/rust-sdk/blob/HEAD/conformance/src/bin/server.rs) handles a key part of this chapter's functionality:
```rs
-}
-trait TransferObject:
- std::fmt::Debug + Clone + serde::Serialize + serde::de::DeserializeOwned + Send + Sync + 'static
-{
+#[derive(Clone)]
+struct ConformanceServer {
+ subscriptions: Arc<Mutex<HashSet<String>>>,
+ log_level: Arc<Mutex<LoggingLevel>>,
}
-impl<T> TransferObject for T where
- T: std::fmt::Debug
- + serde::Serialize
- + serde::de::DeserializeOwned
- + Send
- + Sync
- + 'static
- + Clone
-{
+impl ConformanceServer {
+ fn new() -> Self {
+ Self {
+ subscriptions: Arc::new(Mutex::new(HashSet::new())),
+ log_level: Arc::new(Mutex::new(LoggingLevel::Debug)),
+ }
+ }
}
-#[allow(private_bounds, reason = "there's no the third implementation")]
-pub trait ServiceRole: std::fmt::Debug + Send + Sync + 'static + Copy + Clone {
- type Req: TransferObject + GetMeta + GetExtensions;
- type Resp: TransferObject;
- type Not: TryInto<CancelledNotification, Error = Self::Not>
- + From<CancelledNotification>
- + TransferObject;
- type PeerReq: TransferObject + GetMeta + GetExtensions;
- type PeerResp: TransferObject;
- type PeerNot: TryInto<CancelledNotification, Error = Self::PeerNot>
- + From<CancelledNotification>
- + TransferObject
- + GetMeta
- + GetExtensions;
+impl ServerHandler for ConformanceServer {
+ async fn initialize(
+ &self,
+ _request: InitializeRequestParams,
+ _cx: RequestContext<RoleServer>,
+ ) -> Result<InitializeResult, ErrorData> {
+ Ok(InitializeResult::new(
+ ServerCapabilities::builder()
+ .enable_prompts()
+ .enable_resources()
+ .enable_tools()
+ .enable_logging()
+ .build(),
+ )
+ .with_server_info(Implementation::new("rust-conformance-server", "0.1.0"))
+ .with_instructions("Rust MCP conformance test server"))
```
This interface is important because it defines how MCP Rust SDK Tutorial: Building High-Performance MCP Services with RMCP implements the patterns covered in this chapter.
-### `crates/rmcp/src/service.rs`
+### `conformance/src/bin/server.rs`
-The `ServiceRole` interface in [`crates/rmcp/src/service.rs`](https://github.com/modelcontextprotocol/rust-sdk/blob/HEAD/crates/rmcp/src/service.rs) handles a key part of this chapter's functionality:
+The `schema` interface in [`conformance/src/bin/server.rs`](https://github.com/modelcontextprotocol/rust-sdk/blob/HEAD/conformance/src/bin/server.rs) handles a key part of this chapter's functionality:
```rs
+ Tool::new(
+ "test_elicitation_sep1330_enums",
+ "Tests enum schema improvements (SEP-1330)",
+ json_object(json!({
+ "type": "object",
+ "properties": {}
+ })),
+ ),
+ Tool::new(
+ "json_schema_2020_12_tool",
+ "Tool with JSON Schema 2020-12 features",
+ json_object(json!({
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "type": "object",
+ "$defs": {
+ "address": {
+ "type": "object",
+ "properties": {
+ "street": { "type": "string" },
+ "city": { "type": "string" }
+ }
+ }
+ },
+ "properties": {
+ "name": { "type": "string" },
+ "address": { "$ref": "#/$defs/address" }
+ },
+ "additionalProperties": false
+ })),
+ ),
+ Tool::new(
+ "test_reconnection",
+```
-#[allow(private_bounds, reason = "there's no the third implementation")]
-pub trait ServiceRole: std::fmt::Debug + Send + Sync + 'static + Copy + Clone {
- type Req: TransferObject + GetMeta + GetExtensions;
- type Resp: TransferObject;
- type Not: TryInto<CancelledNotification, Error = Self::Not>
- + From<CancelledNotification>
- + TransferObject;
- type PeerReq: TransferObject + GetMeta + GetExtensions;
- type PeerResp: TransferObject;
- type PeerNot: TryInto<CancelledNotification, Error = Self::PeerNot>
- + From<CancelledNotification>
- + TransferObject
- + GetMeta
- + GetExtensions;
- type InitializeError;
- const IS_CLIENT: bool;
- type Info: TransferObject;
- type PeerInfo: TransferObject;
-}
+This interface is important because it defines how MCP Rust SDK Tutorial: Building High-Performance MCP Services with RMCP implements the patterns covered in this chapter.
+
+### `conformance/src/bin/server.rs`
-pub type TxJsonRpcMessage<R> =
- JsonRpcMessage<<R as ServiceRole>::Req, <R as ServiceRole>::Resp, <R as ServiceRole>::Not>;
-pub type RxJsonRpcMessage<R> = JsonRpcMessage<
- <R as ServiceRole>::PeerReq,
- <R as ServiceRole>::PeerResp,
- <R as ServiceRole>::PeerNot,
->;
-
-#[cfg(not(feature = "local"))]
-pub trait Service<R: ServiceRole>: Send + Sync + 'static {
- fn handle_request(
+The `schema` interface in [`conformance/src/bin/server.rs`](https://github.com/modelcontextprotocol/rust-sdk/blob/HEAD/conformance/src/bin/server.rs) handles a key part of this chapter's functionality:
+
+```rs
+ Tool::new(
+ "test_elicitation_sep1330_enums",
+ "Tests enum schema improvements (SEP-1330)",
+ json_object(json!({
+ "type": "object",
+ "properties": {}
+ })),
+ ),
+ Tool::new(
+ "json_schema_2020_12_tool",
+ "Tool with JSON Schema 2020-12 features",
+ json_object(json!({
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "type": "object",
+ "$defs": {
+ "address": {
+ "type": "object",
+ "properties": {
+ "street": { "type": "string" },
+ "city": { "type": "string" }
+ }
+ }
+ },
+ "properties": {
+ "name": { "type": "string" },
+ "address": { "$ref": "#/$defs/address" }
+ },
+ "additionalProperties": false
+ })),
+ ),
+ Tool::new(
+ "test_reconnection",
```
This interface is important because it defines how MCP Rust SDK Tutorial: Building High-Performance MCP Services with RMCP implements the patterns covered in this chapter.
-### `crates/rmcp/src/service.rs`
+### `conformance/src/bin/client.rs`
-The `Service` interface in [`crates/rmcp/src/service.rs`](https://github.com/modelcontextprotocol/rust-sdk/blob/HEAD/crates/rmcp/src/service.rs) handles a key part of this chapter's functionality:
+The `ConformanceContext` interface in [`conformance/src/bin/client.rs`](https://github.com/modelcontextprotocol/rust-sdk/blob/HEAD/conformance/src/bin/client.rs) handles a key part of this chapter's functionality:
```rs
-#[derive(Error, Debug)]
-#[non_exhaustive]
-pub enum ServiceError {
- #[error("Mcp error: {0}")]
- McpError(McpError),
- #[error("Transport send error: {0}")]
- TransportSend(DynamicTransportError),
- #[error("Transport closed")]
- TransportClosed,
- #[error("Unexpected response type")]
- UnexpectedResponse,
- #[error("task cancelled for reason {}", reason.as_deref().unwrap_or("<unknown>"))]
- Cancelled { reason: Option<String> },
- #[error("request timeout after {}", chrono::Duration::from_std(*timeout).unwrap_or_default())]
- Timeout { timeout: Duration },
-}
-trait TransferObject:
- std::fmt::Debug + Clone + serde::Serialize + serde::de::DeserializeOwned + Send + Sync + 'static
-{
+#[derive(Debug, Default, serde::Deserialize)]
+struct ConformanceContext {
+ #[serde(default)]
+ client_id: Option<String>,
+ #[serde(default)]
+ client_secret: Option<String>,
+ // client-credentials-jwt
+ #[serde(default)]
+ private_key_pem: Option<String>,
+ #[serde(default)]
+ signing_algorithm: Option<String>,
}
-impl<T> TransferObject for T where
- T: std::fmt::Debug
- + serde::Serialize
- + serde::de::DeserializeOwned
- + Send
- + Sync
- + 'static
- + Clone
-{
+fn load_context() -> ConformanceContext {
+ std::env::var("MCP_CONFORMANCE_CONTEXT")
+ .ok()
+ .and_then(|s| serde_json::from_str(&s).ok())
+ .unwrap_or_default()
}
+
+// ─── Client handlers ────────────────────────────────────────────────────────
+
+/// A basic client handler that does nothing special
+struct BasicClientHandler;
+impl ClientHandler for BasicClientHandler {}
+
+/// A client handler that handles elicitation requests by applying schema defaults.
+struct ElicitationDefaultsClientHandler;
+
+impl ClientHandler for ElicitationDefaultsClientHandler {
+ fn get_info(&self) -> ClientInfo {
```
This interface is important because it defines how MCP Rust SDK Tutorial: Building High-Performance MCP Services with RMCP implements the patterns covered in this chapter.
@@ -212,11 +210,11 @@ This interface is important because it defines how MCP Rust SDK Tutorial: Buildi
```mermaid
flowchart TD
- A[MaybeSendFuture]
- B[TransferObject]
- C[ServiceRole]
- D[Service]
- E[Service]
+ A[ConformanceServer]
+ B[schema]
+ C[schema]
+ D[ConformanceContext]
+ E[BasicClientHandler]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-rust-sdk-tutorial/06-oauth-security-and-auth-workflows.md b/tutorials/mcp-rust-sdk-tutorial/06-oauth-security-and-auth-workflows.md
index 841bd6f0..476119a4 100644
--- a/tutorials/mcp-rust-sdk-tutorial/06-oauth-security-and-auth-workflows.md
+++ b/tutorials/mcp-rust-sdk-tutorial/06-oauth-security-and-auth-workflows.md
@@ -39,170 +39,168 @@ You now have an OAuth implementation baseline for Rust MCP services and clients.
Next: [Chapter 7: Conformance, Changelog, and Release Discipline](07-conformance-changelog-and-release-discipline.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `crates/rmcp/src/service.rs`
+### `examples/servers/src/complex_auth_streamhttp.rs`
-The `RequestIdProvider` interface in [`crates/rmcp/src/service.rs`](https://github.com/modelcontextprotocol/rust-sdk/blob/HEAD/crates/rmcp/src/service.rs) handles a key part of this chapter's functionality:
+The `McpOAuthStore` interface in [`examples/servers/src/complex_auth_streamhttp.rs`](https://github.com/modelcontextprotocol/rust-sdk/blob/HEAD/examples/servers/src/complex_auth_streamhttp.rs) handles a key part of this chapter's functionality:
```rs
-use tokio::sync::mpsc;
-
-pub trait RequestIdProvider: Send + Sync + 'static {
- fn next_request_id(&self) -> RequestId;
-}
-
-pub trait ProgressTokenProvider: Send + Sync + 'static {
- fn next_progress_token(&self) -> ProgressToken;
-}
-
-pub type AtomicU32RequestIdProvider = AtomicU32Provider;
-pub type AtomicU32ProgressTokenProvider = AtomicU32Provider;
-
-#[derive(Debug, Default)]
-pub struct AtomicU32Provider {
- id: AtomicU64,
+// A easy way to manage MCP OAuth Store for managing tokens and sessions
+#[derive(Clone, Debug)]
+struct McpOAuthStore {
+ clients: Arc<RwLock<HashMap<String, OAuthClientConfig>>>,
+ auth_sessions: Arc<RwLock<HashMap<String, AuthSession>>>,
+ access_tokens: Arc<RwLock<HashMap<String, McpAccessToken>>>,
}
-impl RequestIdProvider for AtomicU32Provider {
- fn next_request_id(&self) -> RequestId {
- let id = self.id.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
- // Safe conversion: we start at 0 and increment by 1, so we won't overflow i64::MAX in practice
- RequestId::Number(id as i64)
+impl McpOAuthStore {
+ fn new() -> Self {
+ let mut clients = HashMap::new();
+ clients.insert(
+ "mcp-client".to_string(),
+ OAuthClientConfig::new("mcp-client", "http://localhost:8080/callback")
+ .with_client_secret("mcp-client-secret")
+ .with_scopes(vec!["profile".to_string(), "email".to_string()]),
+ );
+
+ Self {
+ clients: Arc::new(RwLock::new(clients)),
+ auth_sessions: Arc::new(RwLock::new(HashMap::new())),
+ access_tokens: Arc::new(RwLock::new(HashMap::new())),
+ }
}
-}
-impl ProgressTokenProvider for AtomicU32Provider {
- fn next_progress_token(&self) -> ProgressToken {
- let id = self.id.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
- ProgressToken(NumberOrString::Number(id as i64))
- }
-}
+ async fn validate_client(
+ &self,
+ client_id: &str,
+ redirect_uri: &str,
+ ) -> Option<OAuthClientConfig> {
+ let clients = self.clients.read().await;
+ if let Some(client) = clients.get(client_id) {
```
This interface is important because it defines how MCP Rust SDK Tutorial: Building High-Performance MCP Services with RMCP implements the patterns covered in this chapter.
-### `crates/rmcp/src/service.rs`
+### `examples/servers/src/complex_auth_streamhttp.rs`
-The `ProgressTokenProvider` interface in [`crates/rmcp/src/service.rs`](https://github.com/modelcontextprotocol/rust-sdk/blob/HEAD/crates/rmcp/src/service.rs) handles a key part of this chapter's functionality:
+The `AuthSession` interface in [`examples/servers/src/complex_auth_streamhttp.rs`](https://github.com/modelcontextprotocol/rust-sdk/blob/HEAD/examples/servers/src/complex_auth_streamhttp.rs) handles a key part of this chapter's functionality:
```rs
+struct McpOAuthStore {
+ clients: Arc<RwLock<HashMap<String, OAuthClientConfig>>>,
+ auth_sessions: Arc<RwLock<HashMap<String, AuthSession>>>,
+ access_tokens: Arc<RwLock<HashMap<String, McpAccessToken>>>,
}
-pub trait ProgressTokenProvider: Send + Sync + 'static {
- fn next_progress_token(&self) -> ProgressToken;
-}
-
-pub type AtomicU32RequestIdProvider = AtomicU32Provider;
-pub type AtomicU32ProgressTokenProvider = AtomicU32Provider;
-
-#[derive(Debug, Default)]
-pub struct AtomicU32Provider {
- id: AtomicU64,
-}
-
-impl RequestIdProvider for AtomicU32Provider {
- fn next_request_id(&self) -> RequestId {
- let id = self.id.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
- // Safe conversion: we start at 0 and increment by 1, so we won't overflow i64::MAX in practice
- RequestId::Number(id as i64)
+impl McpOAuthStore {
+ fn new() -> Self {
+ let mut clients = HashMap::new();
+ clients.insert(
+ "mcp-client".to_string(),
+ OAuthClientConfig::new("mcp-client", "http://localhost:8080/callback")
+ .with_client_secret("mcp-client-secret")
+ .with_scopes(vec!["profile".to_string(), "email".to_string()]),
+ );
+
+ Self {
+ clients: Arc::new(RwLock::new(clients)),
+ auth_sessions: Arc::new(RwLock::new(HashMap::new())),
+ access_tokens: Arc::new(RwLock::new(HashMap::new())),
+ }
}
-}
-impl ProgressTokenProvider for AtomicU32Provider {
- fn next_progress_token(&self) -> ProgressToken {
- let id = self.id.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
- ProgressToken(NumberOrString::Number(id as i64))
- }
-}
-
-type Responder<T> = tokio::sync::oneshot::Sender<T>;
-
-/// A handle to a remote request
+ async fn validate_client(
+ &self,
+ client_id: &str,
+ redirect_uri: &str,
+ ) -> Option<OAuthClientConfig> {
+ let clients = self.clients.read().await;
+ if let Some(client) = clients.get(client_id) {
+ if client.redirect_uri.contains(&redirect_uri.to_string()) {
+ return Some(client.clone());
```
This interface is important because it defines how MCP Rust SDK Tutorial: Building High-Performance MCP Services with RMCP implements the patterns covered in this chapter.
-### `crates/rmcp/src/service.rs`
+### `examples/servers/src/complex_auth_streamhttp.rs`
-The `ServiceError` interface in [`crates/rmcp/src/service.rs`](https://github.com/modelcontextprotocol/rust-sdk/blob/HEAD/crates/rmcp/src/service.rs) handles a key part of this chapter's functionality:
+The `AuthToken` interface in [`examples/servers/src/complex_auth_streamhttp.rs`](https://github.com/modelcontextprotocol/rust-sdk/blob/HEAD/examples/servers/src/complex_auth_streamhttp.rs) handles a key part of this chapter's functionality:
```rs
-#[derive(Error, Debug)]
-#[non_exhaustive]
-pub enum ServiceError {
- #[error("Mcp error: {0}")]
- McpError(McpError),
- #[error("Transport send error: {0}")]
- TransportSend(DynamicTransportError),
- #[error("Transport closed")]
- TransportClosed,
- #[error("Unexpected response type")]
- UnexpectedResponse,
- #[error("task cancelled for reason {}", reason.as_deref().unwrap_or("<unknown>"))]
- Cancelled { reason: Option<String> },
- #[error("request timeout after {}", chrono::Duration::from_std(*timeout).unwrap_or_default())]
- Timeout { timeout: Duration },
-}
-
-trait TransferObject:
- std::fmt::Debug + Clone + serde::Serialize + serde::de::DeserializeOwned + Send + Sync + 'static
-{
-}
+ &self,
+ session_id: &str,
+ token: AuthToken,
+ ) -> Result<(), String> {
+ let mut sessions = self.auth_sessions.write().await;
+ if let Some(session) = sessions.get_mut(session_id) {
+ session.auth_token = Some(token);
+ Ok(())
+ } else {
+ Err("Session not found".to_string())
+ }
+ }
-impl<T> TransferObject for T where
- T: std::fmt::Debug
- + serde::Serialize
- + serde::de::DeserializeOwned
- + Send
- + Sync
- + 'static
- + Clone
-{
-}
+ async fn create_mcp_token(&self, session_id: &str) -> Result<McpAccessToken, String> {
+ let sessions = self.auth_sessions.read().await;
+ if let Some(session) = sessions.get(session_id) {
+ if let Some(auth_token) = &session.auth_token {
+ let access_token = format!("mcp-token-{}", Uuid::new_v4());
+ let token = McpAccessToken {
+ access_token: access_token.clone(),
+ token_type: "Bearer".to_string(),
+ expires_in: 3600,
+ refresh_token: format!("mcp-refresh-{}", Uuid::new_v4()),
+ scope: session.scope.clone(),
+ auth_token: auth_token.clone(),
+ client_id: session.client_id.clone(),
+ };
+
+ self.access_tokens
+ .write()
+ .await
+ .insert(access_token.clone(), token.clone());
```
This interface is important because it defines how MCP Rust SDK Tutorial: Building High-Performance MCP Services with RMCP implements the patterns covered in this chapter.
-### `crates/rmcp/src/service.rs`
+### `examples/servers/src/complex_auth_streamhttp.rs`
-The `PeerSinkMessage` interface in [`crates/rmcp/src/service.rs`](https://github.com/modelcontextprotocol/rust-sdk/blob/HEAD/crates/rmcp/src/service.rs) handles a key part of this chapter's functionality:
+The `McpAccessToken` interface in [`examples/servers/src/complex_auth_streamhttp.rs`](https://github.com/modelcontextprotocol/rust-sdk/blob/HEAD/examples/servers/src/complex_auth_streamhttp.rs) handles a key part of this chapter's functionality:
```rs
-
-#[derive(Debug)]
-pub(crate) enum PeerSinkMessage<R: ServiceRole> {
- Request {
- request: R::Req,
- id: RequestId,
- responder: Responder<Result<R::PeerResp, ServiceError>>,
- },
- Notification {
- notification: R::Not,
- responder: Responder<Result<(), ServiceError>>,
- },
+ clients: Arc<RwLock<HashMap<String, OAuthClientConfig>>>,
+ auth_sessions: Arc<RwLock<HashMap<String, AuthSession>>>,
+ access_tokens: Arc<RwLock<HashMap<String, McpAccessToken>>>,
}
-/// An interface to fetch the remote client or server
-///
-/// For general purpose, call [`Peer::send_request`] or [`Peer::send_notification`] to send message to remote peer.
-///
-/// To create a cancellable request, call [`Peer::send_request_with_option`].
-#[derive(Clone)]
-pub struct Peer<R: ServiceRole> {
- tx: mpsc::Sender<PeerSinkMessage<R>>,
- request_id_provider: Arc<dyn RequestIdProvider>,
- progress_token_provider: Arc<dyn ProgressTokenProvider>,
- info: Arc<tokio::sync::OnceCell<R::PeerInfo>>,
-}
+impl McpOAuthStore {
+ fn new() -> Self {
+ let mut clients = HashMap::new();
+ clients.insert(
+ "mcp-client".to_string(),
+ OAuthClientConfig::new("mcp-client", "http://localhost:8080/callback")
+ .with_client_secret("mcp-client-secret")
+ .with_scopes(vec!["profile".to_string(), "email".to_string()]),
+ );
+
+ Self {
+ clients: Arc::new(RwLock::new(clients)),
+ auth_sessions: Arc::new(RwLock::new(HashMap::new())),
+ access_tokens: Arc::new(RwLock::new(HashMap::new())),
+ }
+ }
-impl<R: ServiceRole> std::fmt::Debug for Peer<R> {
- fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
- f.debug_struct("PeerSink")
- .field("tx", &self.tx)
- .field("is_client", &R::IS_CLIENT)
+ async fn validate_client(
+ &self,
+ client_id: &str,
+ redirect_uri: &str,
+ ) -> Option<OAuthClientConfig> {
+ let clients = self.clients.read().await;
+ if let Some(client) = clients.get(client_id) {
+ if client.redirect_uri.contains(&redirect_uri.to_string()) {
+ return Some(client.clone());
+ }
```
This interface is important because it defines how MCP Rust SDK Tutorial: Building High-Performance MCP Services with RMCP implements the patterns covered in this chapter.
@@ -212,11 +210,11 @@ This interface is important because it defines how MCP Rust SDK Tutorial: Buildi
```mermaid
flowchart TD
- A[RequestIdProvider]
- B[ProgressTokenProvider]
- C[ServiceError]
- D[PeerSinkMessage]
- E[QuitReason]
+ A[McpOAuthStore]
+ B[AuthSession]
+ C[AuthToken]
+ D[McpAccessToken]
+ E[AuthorizeQuery]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-rust-sdk-tutorial/07-conformance-changelog-and-release-discipline.md b/tutorials/mcp-rust-sdk-tutorial/07-conformance-changelog-and-release-discipline.md
index 4b516ff7..f3becdbf 100644
--- a/tutorials/mcp-rust-sdk-tutorial/07-conformance-changelog-and-release-discipline.md
+++ b/tutorials/mcp-rust-sdk-tutorial/07-conformance-changelog-and-release-discipline.md
@@ -39,170 +39,168 @@ You now have a release process aligned with the pace and risk profile of rmcp de
Next: [Chapter 8: Ecosystem Integration and Production Operations](08-ecosystem-integration-and-production-operations.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `conformance/src/bin/server.rs`
+### `examples/servers/src/completion_stdio.rs`
-The `schema` interface in [`conformance/src/bin/server.rs`](https://github.com/modelcontextprotocol/rust-sdk/blob/HEAD/conformance/src/bin/server.rs) handles a key part of this chapter's functionality:
+The `SqlQueryArgs` interface in [`examples/servers/src/completion_stdio.rs`](https://github.com/modelcontextprotocol/rust-sdk/blob/HEAD/examples/servers/src/completion_stdio.rs) handles a key part of this chapter's functionality:
```rs
- Tool::new(
- "test_elicitation_sep1330_enums",
- "Tests enum schema improvements (SEP-1330)",
- json_object(json!({
- "type": "object",
- "properties": {}
- })),
- ),
- Tool::new(
- "json_schema_2020_12_tool",
- "Tool with JSON Schema 2020-12 features",
- json_object(json!({
- "$schema": "https://json-schema.org/draft/2020-12/schema",
- "type": "object",
- "$defs": {
- "address": {
- "type": "object",
- "properties": {
- "street": { "type": "string" },
- "city": { "type": "string" }
- }
- }
- },
- "properties": {
- "name": { "type": "string" },
- "address": { "$ref": "#/$defs/address" }
- },
- "additionalProperties": false
- })),
- ),
- Tool::new(
- "test_reconnection",
-```
-
-This interface is important because it defines how MCP Rust SDK Tutorial: Building High-Performance MCP Services with RMCP implements the patterns covered in this chapter.
+#[derive(Debug, Serialize, Deserialize, JsonSchema)]
+#[schemars(description = "SQL query builder with progressive completion")]
+pub struct SqlQueryArgs {
+ #[schemars(description = "SQL operation type (SELECT, INSERT, UPDATE, DELETE)")]
+ pub operation: String,
+ #[schemars(description = "Database table name")]
+ pub table: String,
+ #[schemars(description = "Columns to select/update (only for SELECT/UPDATE)")]
+ pub columns: Option<String>,
+ #[schemars(description = "WHERE clause condition (optional for all operations)")]
+ pub where_clause: Option<String>,
+ #[schemars(description = "Values to insert (only for INSERT)")]
+ pub values: Option<String>,
+}
-### `conformance/src/bin/server.rs`
+/// SQL query builder server with progressive completion
+#[derive(Clone)]
+pub struct SqlQueryServer {
+ prompt_router: PromptRouter<SqlQueryServer>,
+}
-The `schema` interface in [`conformance/src/bin/server.rs`](https://github.com/modelcontextprotocol/rust-sdk/blob/HEAD/conformance/src/bin/server.rs) handles a key part of this chapter's functionality:
+impl SqlQueryServer {
+ pub fn new() -> Self {
+ Self {
+ prompt_router: Self::prompt_router(),
+ }
+ }
+}
-```rs
- Tool::new(
- "test_elicitation_sep1330_enums",
- "Tests enum schema improvements (SEP-1330)",
- json_object(json!({
- "type": "object",
- "properties": {}
- })),
- ),
- Tool::new(
- "json_schema_2020_12_tool",
- "Tool with JSON Schema 2020-12 features",
- json_object(json!({
- "$schema": "https://json-schema.org/draft/2020-12/schema",
- "type": "object",
- "$defs": {
- "address": {
- "type": "object",
- "properties": {
- "street": { "type": "string" },
- "city": { "type": "string" }
- }
- }
- },
- "properties": {
- "name": { "type": "string" },
- "address": { "$ref": "#/$defs/address" }
- },
- "additionalProperties": false
- })),
- ),
- Tool::new(
- "test_reconnection",
+impl Default for SqlQueryServer {
+ fn default() -> Self {
+ Self::new()
```
This interface is important because it defines how MCP Rust SDK Tutorial: Building High-Performance MCP Services with RMCP implements the patterns covered in this chapter.
-### `examples/servers/src/cimd_auth_streamhttp.rs`
+### `examples/servers/src/completion_stdio.rs`
-The `AuthCodeRecord` interface in [`examples/servers/src/cimd_auth_streamhttp.rs`](https://github.com/modelcontextprotocol/rust-sdk/blob/HEAD/examples/servers/src/cimd_auth_streamhttp.rs) handles a key part of this chapter's functionality:
+The `SqlQueryServer` interface in [`examples/servers/src/completion_stdio.rs`](https://github.com/modelcontextprotocol/rust-sdk/blob/HEAD/examples/servers/src/completion_stdio.rs) handles a key part of this chapter's functionality:
```rs
-/// In-memory authorization code record
-#[derive(Clone, Debug)]
-struct AuthCodeRecord {
- _client_id: String,
- _redirect_uri: String,
- expires_at: SystemTime,
-}
-
+/// SQL query builder server with progressive completion
#[derive(Clone)]
-struct AppState {
- auth_codes: Arc<RwLock<HashMap<String, AuthCodeRecord>>>,
+pub struct SqlQueryServer {
+ prompt_router: PromptRouter<SqlQueryServer>,
}
-impl AppState {
- fn new() -> Self {
+impl SqlQueryServer {
+ pub fn new() -> Self {
Self {
- auth_codes: Arc::new(RwLock::new(HashMap::new())),
+ prompt_router: Self::prompt_router(),
}
}
}
-fn generate_authorization_code() -> String {
- rand::rng()
- .sample_iter(&Alphanumeric)
- .take(32)
- .map(char::from)
- .collect()
+impl Default for SqlQueryServer {
+ fn default() -> Self {
+ Self::new()
+ }
}
-fn generate_access_token() -> String {
- rand::rng()
- .sample_iter(&Alphanumeric)
+impl SqlQueryServer {
+ /// Fuzzy matching with scoring for completion suggestions
+ fn fuzzy_match(&self, query: &str, candidates: &[&str]) -> Vec<String> {
+ if query.is_empty() {
+ return candidates.iter().take(10).map(|s| s.to_string()).collect();
+ }
+
+ let query_lower = query.to_lowercase();
+ let mut scored_matches = Vec::new();
+
+ for candidate in candidates {
+ let candidate_lower = candidate.to_lowercase();
```
This interface is important because it defines how MCP Rust SDK Tutorial: Building High-Performance MCP Services with RMCP implements the patterns covered in this chapter.
-### `examples/servers/src/cimd_auth_streamhttp.rs`
+### `crates/rmcp-macros/src/tool.rs`
-The `AppState` interface in [`examples/servers/src/cimd_auth_streamhttp.rs`](https://github.com/modelcontextprotocol/rust-sdk/blob/HEAD/examples/servers/src/cimd_auth_streamhttp.rs) handles a key part of this chapter's functionality:
+The `tool` function in [`crates/rmcp-macros/src/tool.rs`](https://github.com/modelcontextprotocol/rust-sdk/blob/HEAD/crates/rmcp-macros/src/tool.rs) handles a key part of this chapter's functionality:
```rs
+ if let Some(inner_type) = extract_json_inner_type(ret_type) {
+ return syn::parse2::<Expr>(quote! {
+ rmcp::handler::server::tool::schema_for_output::<#inner_type>()
+ .unwrap_or_else(|e| {
+ panic!(
+ "Invalid output schema for Json<{}>: {}",
+ std::any::type_name::<#inner_type>(),
+ e
+ )
+ })
+ })
+ .ok();
+ }
-#[derive(Clone)]
-struct AppState {
- auth_codes: Arc<RwLock<HashMap<String, AuthCodeRecord>>>,
-}
+ // Then, try Result<Json<T>, E>
+ let type_path = match ret_type {
+ syn::Type::Path(path) => path,
+ _ => return None,
+ };
-impl AppState {
- fn new() -> Self {
- Self {
- auth_codes: Arc::new(RwLock::new(HashMap::new())),
- }
+ let last_segment = type_path.path.segments.last()?;
+
+ if last_segment.ident != "Result" {
+ return None;
}
-}
-fn generate_authorization_code() -> String {
- rand::rng()
- .sample_iter(&Alphanumeric)
- .take(32)
- .map(char::from)
- .collect()
+ let args = match &last_segment.arguments {
+ syn::PathArguments::AngleBracketed(args) => args,
+ _ => return None,
+ };
+
+ let ok_type = match args.args.first()? {
+```
+
+This function is important because it defines how MCP Rust SDK Tutorial: Building High-Performance MCP Services with RMCP implements the patterns covered in this chapter.
+
+### `crates/rmcp-macros/src/tool.rs`
+
+The `ToolAttribute` interface in [`crates/rmcp-macros/src/tool.rs`](https://github.com/modelcontextprotocol/rust-sdk/blob/HEAD/crates/rmcp-macros/src/tool.rs) handles a key part of this chapter's functionality:
+
+```rs
+#[derive(FromMeta, Default, Debug)]
+#[darling(default)]
+pub struct ToolAttribute {
+ /// The name of the tool
+ pub name: Option<String>,
+ /// Human readable title of tool
+ pub title: Option<String>,
+ pub description: Option<String>,
+ /// A JSON Schema object defining the expected parameters for the tool
+ pub input_schema: Option<Expr>,
+ /// An optional JSON Schema object defining the structure of the tool's output
+ pub output_schema: Option<Expr>,
+ /// Optional additional tool information.
+ pub annotations: Option<ToolAnnotationsAttribute>,
+ /// Execution-related configuration including task support.
+ pub execution: Option<ToolExecutionAttribute>,
+ /// Optional icons for the tool
+ pub icons: Option<Expr>,
+ /// Optional metadata for the tool
+ pub meta: Option<Expr>,
+ /// When true, the generated future will not require `Send`. Useful for `!Send` handlers
+ /// (e.g. single-threaded database connections). Also enabled globally by the `local` crate feature.
+ pub local: bool,
}
-fn generate_access_token() -> String {
- rand::rng()
- .sample_iter(&Alphanumeric)
- .take(32)
- .map(char::from)
- .collect()
+#[derive(FromMeta, Debug, Default)]
+#[darling(default)]
+pub struct ToolExecutionAttribute {
+ /// Task support mode: "forbidden", "optional", or "required"
+ pub task_support: Option<String>,
}
-/// Validate that the client_id is a URL that meets CIMD mandatory requirements.
-/// Mirrors the JS validateClientIdUrl helper.
```
This interface is important because it defines how MCP Rust SDK Tutorial: Building High-Performance MCP Services with RMCP implements the patterns covered in this chapter.
@@ -212,11 +210,11 @@ This interface is important because it defines how MCP Rust SDK Tutorial: Buildi
```mermaid
flowchart TD
- A[schema]
- B[schema]
- C[AuthCodeRecord]
- D[AppState]
- E[AuthorizeQuery]
+ A[SqlQueryArgs]
+ B[SqlQueryServer]
+ C[tool]
+ D[ToolAttribute]
+ E[ToolExecutionAttribute]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-rust-sdk-tutorial/08-ecosystem-integration-and-production-operations.md b/tutorials/mcp-rust-sdk-tutorial/08-ecosystem-integration-and-production-operations.md
index a3d93678..571dc743 100644
--- a/tutorials/mcp-rust-sdk-tutorial/08-ecosystem-integration-and-production-operations.md
+++ b/tutorials/mcp-rust-sdk-tutorial/08-ecosystem-integration-and-production-operations.md
@@ -39,170 +39,168 @@ You now have a full operations and integration model for Rust MCP deployments.
Next: Continue with [MCP Swift SDK Tutorial](../mcp-swift-sdk-tutorial/)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `crates/rmcp-macros/src/tool.rs`
+### `examples/servers/src/cimd_auth_streamhttp.rs`
-The `ToolAttribute` interface in [`crates/rmcp-macros/src/tool.rs`](https://github.com/modelcontextprotocol/rust-sdk/blob/HEAD/crates/rmcp-macros/src/tool.rs) handles a key part of this chapter's functionality:
+The `AppState` interface in [`examples/servers/src/cimd_auth_streamhttp.rs`](https://github.com/modelcontextprotocol/rust-sdk/blob/HEAD/examples/servers/src/cimd_auth_streamhttp.rs) handles a key part of this chapter's functionality:
```rs
-#[derive(FromMeta, Default, Debug)]
-#[darling(default)]
-pub struct ToolAttribute {
- /// The name of the tool
- pub name: Option<String>,
- /// Human readable title of tool
- pub title: Option<String>,
- pub description: Option<String>,
- /// A JSON Schema object defining the expected parameters for the tool
- pub input_schema: Option<Expr>,
- /// An optional JSON Schema object defining the structure of the tool's output
- pub output_schema: Option<Expr>,
- /// Optional additional tool information.
- pub annotations: Option<ToolAnnotationsAttribute>,
- /// Execution-related configuration including task support.
- pub execution: Option<ToolExecutionAttribute>,
- /// Optional icons for the tool
- pub icons: Option<Expr>,
- /// Optional metadata for the tool
- pub meta: Option<Expr>,
- /// When true, the generated future will not require `Send`. Useful for `!Send` handlers
- /// (e.g. single-threaded database connections). Also enabled globally by the `local` crate feature.
- pub local: bool,
+
+#[derive(Clone)]
+struct AppState {
+ auth_codes: Arc<RwLock<HashMap<String, AuthCodeRecord>>>,
+}
+
+impl AppState {
+ fn new() -> Self {
+ Self {
+ auth_codes: Arc::new(RwLock::new(HashMap::new())),
+ }
+ }
+}
+
+fn generate_authorization_code() -> String {
+ rand::rng()
+ .sample_iter(&Alphanumeric)
+ .take(32)
+ .map(char::from)
+ .collect()
}
-#[derive(FromMeta, Debug, Default)]
-#[darling(default)]
-pub struct ToolExecutionAttribute {
- /// Task support mode: "forbidden", "optional", or "required"
- pub task_support: Option<String>,
+fn generate_access_token() -> String {
+ rand::rng()
+ .sample_iter(&Alphanumeric)
+ .take(32)
+ .map(char::from)
+ .collect()
}
+/// Validate that the client_id is a URL that meets CIMD mandatory requirements.
+/// Mirrors the JS validateClientIdUrl helper.
```
This interface is important because it defines how MCP Rust SDK Tutorial: Building High-Performance MCP Services with RMCP implements the patterns covered in this chapter.
-### `crates/rmcp-macros/src/tool.rs`
+### `examples/servers/src/cimd_auth_streamhttp.rs`
-The `ToolExecutionAttribute` interface in [`crates/rmcp-macros/src/tool.rs`](https://github.com/modelcontextprotocol/rust-sdk/blob/HEAD/crates/rmcp-macros/src/tool.rs) handles a key part of this chapter's functionality:
+The `AuthorizeQuery` interface in [`examples/servers/src/cimd_auth_streamhttp.rs`](https://github.com/modelcontextprotocol/rust-sdk/blob/HEAD/examples/servers/src/cimd_auth_streamhttp.rs) handles a key part of this chapter's functionality:
```rs
- pub annotations: Option<ToolAnnotationsAttribute>,
- /// Execution-related configuration including task support.
- pub execution: Option<ToolExecutionAttribute>,
- /// Optional icons for the tool
- pub icons: Option<Expr>,
- /// Optional metadata for the tool
- pub meta: Option<Expr>,
- /// When true, the generated future will not require `Send`. Useful for `!Send` handlers
- /// (e.g. single-threaded database connections). Also enabled globally by the `local` crate feature.
- pub local: bool,
-}
-#[derive(FromMeta, Debug, Default)]
-#[darling(default)]
-pub struct ToolExecutionAttribute {
- /// Task support mode: "forbidden", "optional", or "required"
- pub task_support: Option<String>,
+#[derive(Debug, Deserialize)]
+struct AuthorizeQuery {
+ client_id: Option<String>,
+ redirect_uri: Option<String>,
+ response_type: Option<String>,
+ state: Option<String>,
+ scope: Option<String>,
}
-pub struct ResolvedToolAttribute {
- pub name: String,
- pub title: Option<String>,
- pub description: Option<Expr>,
- pub input_schema: Expr,
- pub output_schema: Option<Expr>,
- pub annotations: Option<Expr>,
- pub execution: Option<Expr>,
- pub icons: Option<Expr>,
- pub meta: Option<Expr>,
+#[derive(Debug, Deserialize)]
+struct LoginForm {
+ username: Option<String>,
+ password: Option<String>,
+ // OAuth params come from hidden form fields
+ client_id: Option<String>,
+ redirect_uri: Option<String>,
+ response_type: Option<String>,
+ state: Option<String>,
+ scope: Option<String>,
}
-impl ResolvedToolAttribute {
+fn render_login_form(params: &AuthorizeQuery, error: Option<&str>) -> Html<String> {
+ let hidden_fields = [
+ ("client_id", params.client_id.as_deref().unwrap_or_default()),
+ (
+ "redirect_uri",
+ params.redirect_uri.as_deref().unwrap_or_default(),
+ ),
+ (
+ "response_type",
+ params.response_type.as_deref().unwrap_or_default(),
```
This interface is important because it defines how MCP Rust SDK Tutorial: Building High-Performance MCP Services with RMCP implements the patterns covered in this chapter.
-### `crates/rmcp-macros/src/tool.rs`
+### `examples/servers/src/cimd_auth_streamhttp.rs`
-The `ResolvedToolAttribute` interface in [`crates/rmcp-macros/src/tool.rs`](https://github.com/modelcontextprotocol/rust-sdk/blob/HEAD/crates/rmcp-macros/src/tool.rs) handles a key part of this chapter's functionality:
+The `LoginForm` interface in [`examples/servers/src/cimd_auth_streamhttp.rs`](https://github.com/modelcontextprotocol/rust-sdk/blob/HEAD/examples/servers/src/cimd_auth_streamhttp.rs) handles a key part of this chapter's functionality:
```rs
-}
-pub struct ResolvedToolAttribute {
- pub name: String,
- pub title: Option<String>,
- pub description: Option<Expr>,
- pub input_schema: Expr,
- pub output_schema: Option<Expr>,
- pub annotations: Option<Expr>,
- pub execution: Option<Expr>,
- pub icons: Option<Expr>,
- pub meta: Option<Expr>,
+#[derive(Debug, Deserialize)]
+struct LoginForm {
+ username: Option<String>,
+ password: Option<String>,
+ // OAuth params come from hidden form fields
+ client_id: Option<String>,
+ redirect_uri: Option<String>,
+ response_type: Option<String>,
+ state: Option<String>,
+ scope: Option<String>,
}
-impl ResolvedToolAttribute {
- pub fn into_fn(self, fn_ident: Ident) -> syn::Result<ImplItemFn> {
- let Self {
- name,
- description,
- title,
- input_schema,
- output_schema,
- annotations,
- execution,
- icons,
- meta,
- } = self;
- let description = if let Some(description) = description {
- quote! { Some(#description.into()) }
- } else {
- quote! { None }
- };
+fn render_login_form(params: &AuthorizeQuery, error: Option<&str>) -> Html<String> {
+ let hidden_fields = [
+ ("client_id", params.client_id.as_deref().unwrap_or_default()),
+ (
+ "redirect_uri",
+ params.redirect_uri.as_deref().unwrap_or_default(),
+ ),
+ (
+ "response_type",
+ params.response_type.as_deref().unwrap_or_default(),
+ ),
+ ("state", params.state.as_deref().unwrap_or_default()),
+ ("scope", params.scope.as_deref().unwrap_or_default()),
+ ]
+ .iter()
+ .map(|(k, v)| format!(r#"<input type="hidden" name="{k}" value="{v}">"#))
+ .collect::<Vec<_>>()
+ .join("\n ");
+
```
This interface is important because it defines how MCP Rust SDK Tutorial: Building High-Performance MCP Services with RMCP implements the patterns covered in this chapter.
-### `crates/rmcp-macros/src/tool.rs`
+### `examples/servers/src/cimd_auth_streamhttp.rs`
-The `ToolAnnotationsAttribute` interface in [`crates/rmcp-macros/src/tool.rs`](https://github.com/modelcontextprotocol/rust-sdk/blob/HEAD/crates/rmcp-macros/src/tool.rs) handles a key part of this chapter's functionality:
+The `TokenRequest` interface in [`examples/servers/src/cimd_auth_streamhttp.rs`](https://github.com/modelcontextprotocol/rust-sdk/blob/HEAD/examples/servers/src/cimd_auth_streamhttp.rs) handles a key part of this chapter's functionality:
```rs
- pub output_schema: Option<Expr>,
- /// Optional additional tool information.
- pub annotations: Option<ToolAnnotationsAttribute>,
- /// Execution-related configuration including task support.
- pub execution: Option<ToolExecutionAttribute>,
- /// Optional icons for the tool
- pub icons: Option<Expr>,
- /// Optional metadata for the tool
- pub meta: Option<Expr>,
- /// When true, the generated future will not require `Send`. Useful for `!Send` handlers
- /// (e.g. single-threaded database connections). Also enabled globally by the `local` crate feature.
- pub local: bool,
-}
-#[derive(FromMeta, Debug, Default)]
-#[darling(default)]
-pub struct ToolExecutionAttribute {
- /// Task support mode: "forbidden", "optional", or "required"
- pub task_support: Option<String>,
+#[derive(Debug, Deserialize)]
+struct TokenRequest {
+ grant_type: Option<String>,
+ code: Option<String>,
}
-pub struct ResolvedToolAttribute {
- pub name: String,
- pub title: Option<String>,
- pub description: Option<Expr>,
- pub input_schema: Expr,
- pub output_schema: Option<Expr>,
- pub annotations: Option<Expr>,
- pub execution: Option<Expr>,
- pub icons: Option<Expr>,
- pub meta: Option<Expr>,
-}
+async fn token(State(state): State<AppState>, Form(form): Form<TokenRequest>) -> impl IntoResponse {
+ if form.grant_type.as_deref() != Some("authorization_code") {
+ let body = serde_json::json!({
+ "error": "unsupported_grant_type",
+ "error_description": "Only authorization_code is supported in this demo",
+ });
+ return (StatusCode::BAD_REQUEST, Json(body)).into_response();
+ }
+
+ let code = match &form.code {
+ Some(c) => c.clone(),
+ None => {
+ let body = serde_json::json!({
+ "error": "invalid_request",
+ "error_description": "Authorization code is required",
+ });
+ return (StatusCode::BAD_REQUEST, Json(body)).into_response();
+ }
+ };
+
+ let record_opt = {
+ let mut codes = state.auth_codes.write().await;
+ codes.remove(&code)
+ };
+
```
This interface is important because it defines how MCP Rust SDK Tutorial: Building High-Performance MCP Services with RMCP implements the patterns covered in this chapter.
@@ -212,10 +210,10 @@ This interface is important because it defines how MCP Rust SDK Tutorial: Buildi
```mermaid
flowchart TD
- A[ToolAttribute]
- B[ToolExecutionAttribute]
- C[ResolvedToolAttribute]
- D[ToolAnnotationsAttribute]
+ A[AppState]
+ B[AuthorizeQuery]
+ C[LoginForm]
+ D[TokenRequest]
E[CodeReviewArgs]
A --> B
B --> C
diff --git a/tutorials/mcp-servers-tutorial/01-getting-started.md b/tutorials/mcp-servers-tutorial/01-getting-started.md
index c0c83add..c00f4c09 100644
--- a/tutorials/mcp-servers-tutorial/01-getting-started.md
+++ b/tutorials/mcp-servers-tutorial/01-getting-started.md
@@ -114,184 +114,182 @@ Suggested trace strategy:
- [Main Catalog](../../README.md#-tutorial-catalog)
- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `scripts/release.py`
-
-The `from` class in [`scripts/release.py`](https://github.com/modelcontextprotocol/servers/blob/HEAD/scripts/release.py) handles a key part of this chapter's functionality:
-
-```py
-import re
-import click
-from pathlib import Path
-import json
-import tomlkit
-import datetime
-import subprocess
-from dataclasses import dataclass
-from typing import Any, Iterator, NewType, Protocol
+### `src/filesystem/lib.ts`
+The `setAllowedDirectories` function in [`src/filesystem/lib.ts`](https://github.com/modelcontextprotocol/servers/blob/HEAD/src/filesystem/lib.ts) handles a key part of this chapter's functionality:
-Version = NewType("Version", str)
-GitHash = NewType("GitHash", str)
+```ts
+// Function to set allowed directories from the main module
+export function setAllowedDirectories(directories: string[]): void {
+ allowedDirectories = [...directories];
+}
-class GitHashParamType(click.ParamType):
- name = "git_hash"
+// Function to get current allowed directories
+export function getAllowedDirectories(): string[] {
+ return [...allowedDirectories];
+}
- def convert(
- self, value: Any, param: click.Parameter | None, ctx: click.Context | None
- ) -> GitHash | None:
- if value is None:
- return None
+// Type definitions
+interface FileInfo {
+ size: number;
+ created: Date;
+ modified: Date;
+ accessed: Date;
+ isDirectory: boolean;
+ isFile: boolean;
+ permissions: string;
+}
- if not (8 <= len(value) <= 40):
- self.fail(f"Git hash must be between 8 and 40 characters, got {len(value)}")
+export interface SearchOptions {
+ excludePatterns?: string[];
+}
- if not re.match(r"^[0-9a-fA-F]+$", value):
- self.fail("Git hash must contain only hex digits (0-9, a-f)")
+export interface SearchResult {
+ path: string;
+ isDirectory: boolean;
+}
- try:
- # Verify hash exists in repo
+// Pure Utility Functions
```
-This class is important because it defines how MCP Servers Tutorial: Reference Implementations and Patterns implements the patterns covered in this chapter.
-
-### `scripts/release.py`
-
-The `GitHashParamType` class in [`scripts/release.py`](https://github.com/modelcontextprotocol/servers/blob/HEAD/scripts/release.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-class GitHashParamType(click.ParamType):
- name = "git_hash"
-
- def convert(
- self, value: Any, param: click.Parameter | None, ctx: click.Context | None
- ) -> GitHash | None:
- if value is None:
- return None
-
- if not (8 <= len(value) <= 40):
- self.fail(f"Git hash must be between 8 and 40 characters, got {len(value)}")
-
- if not re.match(r"^[0-9a-fA-F]+$", value):
- self.fail("Git hash must contain only hex digits (0-9, a-f)")
-
- try:
- # Verify hash exists in repo
- subprocess.run(
- ["git", "rev-parse", "--verify", value], check=True, capture_output=True
- )
- except subprocess.CalledProcessError:
- self.fail(f"Git hash {value} not found in repository")
-
- return GitHash(value.lower())
-
-
-GIT_HASH = GitHashParamType()
-
-
-class Package(Protocol):
+This function is important because it defines how MCP Servers Tutorial: Reference Implementations and Patterns implements the patterns covered in this chapter.
+
+### `src/filesystem/lib.ts`
+
+The `getAllowedDirectories` function in [`src/filesystem/lib.ts`](https://github.com/modelcontextprotocol/servers/blob/HEAD/src/filesystem/lib.ts) handles a key part of this chapter's functionality:
+
+```ts
+
+// Function to get current allowed directories
+export function getAllowedDirectories(): string[] {
+ return [...allowedDirectories];
+}
+
+// Type definitions
+interface FileInfo {
+ size: number;
+ created: Date;
+ modified: Date;
+ accessed: Date;
+ isDirectory: boolean;
+ isFile: boolean;
+ permissions: string;
+}
+
+export interface SearchOptions {
+ excludePatterns?: string[];
+}
+
+export interface SearchResult {
+ path: string;
+ isDirectory: boolean;
+}
+
+// Pure Utility Functions
+export function formatSize(bytes: number): string {
+ const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+ if (bytes === 0) return '0 B';
+
+ const i = Math.floor(Math.log(bytes) / Math.log(1024));
```
-This class is important because it defines how MCP Servers Tutorial: Reference Implementations and Patterns implements the patterns covered in this chapter.
-
-### `scripts/release.py`
-
-The `Package` class in [`scripts/release.py`](https://github.com/modelcontextprotocol/servers/blob/HEAD/scripts/release.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-class Package(Protocol):
- path: Path
-
- def package_name(self) -> str: ...
-
- def update_version(self, version: Version) -> None: ...
-
-
-@dataclass
-class NpmPackage:
- path: Path
-
- def package_name(self) -> str:
- with open(self.path / "package.json", "r") as f:
- return json.load(f)["name"]
-
- def update_version(self, version: Version):
- with open(self.path / "package.json", "r+") as f:
- data = json.load(f)
- data["version"] = version
- f.seek(0)
- json.dump(data, f, indent=2)
- f.truncate()
-
-
-@dataclass
-class PyPiPackage:
- path: Path
-
- def package_name(self) -> str:
+This function is important because it defines how MCP Servers Tutorial: Reference Implementations and Patterns implements the patterns covered in this chapter.
+
+### `src/filesystem/lib.ts`
+
+The `formatSize` function in [`src/filesystem/lib.ts`](https://github.com/modelcontextprotocol/servers/blob/HEAD/src/filesystem/lib.ts) handles a key part of this chapter's functionality:
+
+```ts
+
+// Pure Utility Functions
+export function formatSize(bytes: number): string {
+ const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+ if (bytes === 0) return '0 B';
+
+ const i = Math.floor(Math.log(bytes) / Math.log(1024));
+
+ if (i < 0 || i === 0) return `${bytes} ${units[0]}`;
+
+ const unitIndex = Math.min(i, units.length - 1);
+ return `${(bytes / Math.pow(1024, unitIndex)).toFixed(2)} ${units[unitIndex]}`;
+}
+
+export function normalizeLineEndings(text: string): string {
+ return text.replace(/\r\n/g, '\n');
+}
+
+export function createUnifiedDiff(originalContent: string, newContent: string, filepath: string = 'file'): string {
+ // Ensure consistent line endings for diff
+ const normalizedOriginal = normalizeLineEndings(originalContent);
+ const normalizedNew = normalizeLineEndings(newContent);
+
+ return createTwoFilesPatch(
+ filepath,
+ filepath,
+ normalizedOriginal,
+ normalizedNew,
+ 'original',
+ 'modified'
+ );
+}
```
-This class is important because it defines how MCP Servers Tutorial: Reference Implementations and Patterns implements the patterns covered in this chapter.
-
-### `scripts/release.py`
-
-The `class` class in [`scripts/release.py`](https://github.com/modelcontextprotocol/servers/blob/HEAD/scripts/release.py) handles a key part of this chapter's functionality:
-
-```py
-import datetime
-import subprocess
-from dataclasses import dataclass
-from typing import Any, Iterator, NewType, Protocol
-
-
-Version = NewType("Version", str)
-GitHash = NewType("GitHash", str)
-
-
-class GitHashParamType(click.ParamType):
- name = "git_hash"
-
- def convert(
- self, value: Any, param: click.Parameter | None, ctx: click.Context | None
- ) -> GitHash | None:
- if value is None:
- return None
-
- if not (8 <= len(value) <= 40):
- self.fail(f"Git hash must be between 8 and 40 characters, got {len(value)}")
-
- if not re.match(r"^[0-9a-fA-F]+$", value):
- self.fail("Git hash must contain only hex digits (0-9, a-f)")
-
- try:
- # Verify hash exists in repo
- subprocess.run(
- ["git", "rev-parse", "--verify", value], check=True, capture_output=True
- )
- except subprocess.CalledProcessError:
- self.fail(f"Git hash {value} not found in repository")
+This function is important because it defines how MCP Servers Tutorial: Reference Implementations and Patterns implements the patterns covered in this chapter.
+
+### `src/filesystem/lib.ts`
+
+The `normalizeLineEndings` function in [`src/filesystem/lib.ts`](https://github.com/modelcontextprotocol/servers/blob/HEAD/src/filesystem/lib.ts) handles a key part of this chapter's functionality:
+
+```ts
+}
+
+export function normalizeLineEndings(text: string): string {
+ return text.replace(/\r\n/g, '\n');
+}
+
+export function createUnifiedDiff(originalContent: string, newContent: string, filepath: string = 'file'): string {
+ // Ensure consistent line endings for diff
+ const normalizedOriginal = normalizeLineEndings(originalContent);
+ const normalizedNew = normalizeLineEndings(newContent);
+
+ return createTwoFilesPatch(
+ filepath,
+ filepath,
+ normalizedOriginal,
+ normalizedNew,
+ 'original',
+ 'modified'
+ );
+}
+
+// Helper function to resolve relative paths against allowed directories
+function resolveRelativePathAgainstAllowedDirectories(relativePath: string): string {
+ if (allowedDirectories.length === 0) {
+ // Fallback to process.cwd() if no allowed directories are set
+ return path.resolve(process.cwd(), relativePath);
+ }
+
+ // Try to resolve relative path against each allowed directory
+ for (const allowedDir of allowedDirectories) {
+ const candidate = path.resolve(allowedDir, relativePath);
+ const normalizedCandidate = normalizePath(candidate);
```
-This class is important because it defines how MCP Servers Tutorial: Reference Implementations and Patterns implements the patterns covered in this chapter.
+This function is important because it defines how MCP Servers Tutorial: Reference Implementations and Patterns implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[from]
- B[GitHashParamType]
- C[Package]
- D[class]
- E[class]
+ A[setAllowedDirectories]
+ B[getAllowedDirectories]
+ C[formatSize]
+ D[normalizeLineEndings]
+ E[createUnifiedDiff]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-servers-tutorial/02-filesystem-server.md b/tutorials/mcp-servers-tutorial/02-filesystem-server.md
index 2c64342c..8bcde5c8 100644
--- a/tutorials/mcp-servers-tutorial/02-filesystem-server.md
+++ b/tutorials/mcp-servers-tutorial/02-filesystem-server.md
@@ -123,170 +123,168 @@ Suggested trace strategy:
- [Main Catalog](../../README.md#-tutorial-catalog)
- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `scripts/release.py`
-
-The `find_changed_packages` function in [`scripts/release.py`](https://github.com/modelcontextprotocol/servers/blob/HEAD/scripts/release.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def find_changed_packages(directory: Path, git_hash: GitHash) -> Iterator[Package]:
- for path in directory.glob("*/package.json"):
- if has_changes(path.parent, git_hash):
- yield NpmPackage(path.parent)
- for path in directory.glob("*/pyproject.toml"):
- if has_changes(path.parent, git_hash):
- yield PyPiPackage(path.parent)
-
-
-@click.group()
-def cli():
- pass
-
-
-@cli.command("update-packages")
-@click.option(
- "--directory", type=click.Path(exists=True, path_type=Path), default=Path.cwd()
-)
-@click.argument("git_hash", type=GIT_HASH)
-def update_packages(directory: Path, git_hash: GitHash) -> int:
- # Detect package type
- path = directory.resolve(strict=True)
- version = gen_version()
-
- for package in find_changed_packages(path, git_hash):
- name = package.package_name()
- package.update_version(version)
-
- click.echo(f"{name}@{version}")
-
+### `src/filesystem/lib.ts`
+
+The `getFileStats` function in [`src/filesystem/lib.ts`](https://github.com/modelcontextprotocol/servers/blob/HEAD/src/filesystem/lib.ts) handles a key part of this chapter's functionality:
+
+```ts
+
+// File Operations
+export async function getFileStats(filePath: string): Promise<FileInfo> {
+ const stats = await fs.stat(filePath);
+ return {
+ size: stats.size,
+ created: stats.birthtime,
+ modified: stats.mtime,
+ accessed: stats.atime,
+ isDirectory: stats.isDirectory(),
+ isFile: stats.isFile(),
+ permissions: stats.mode.toString(8).slice(-3),
+ };
+}
+
+export async function readFileContent(filePath: string, encoding: string = 'utf-8'): Promise<string> {
+ return await fs.readFile(filePath, encoding as BufferEncoding);
+}
+
+export async function writeFileContent(filePath: string, content: string): Promise<void> {
+ try {
+ // Security: 'wx' flag ensures exclusive creation - fails if file/symlink exists,
+ // preventing writes through pre-existing symlinks
+ await fs.writeFile(filePath, content, { encoding: "utf-8", flag: 'wx' });
+ } catch (error) {
+ if ((error as NodeJS.ErrnoException).code === 'EEXIST') {
+ // Security: Use atomic rename to prevent race conditions where symlinks
+ // could be created between validation and write. Rename operations
+ // replace the target file atomically and don't follow symlinks.
+ const tempPath = `${filePath}.${randomBytes(16).toString('hex')}.tmp`;
+ try {
+ await fs.writeFile(tempPath, content, 'utf-8');
```
This function is important because it defines how MCP Servers Tutorial: Reference Implementations and Patterns implements the patterns covered in this chapter.
-### `scripts/release.py`
-
-The `cli` function in [`scripts/release.py`](https://github.com/modelcontextprotocol/servers/blob/HEAD/scripts/release.py) handles a key part of this chapter's functionality:
-
-```py
-# requires-python = ">=3.12"
-# dependencies = [
-# "click>=8.1.8",
-# "tomlkit>=0.13.2"
-# ]
-# ///
-import sys
-import re
-import click
-from pathlib import Path
-import json
-import tomlkit
-import datetime
-import subprocess
-from dataclasses import dataclass
-from typing import Any, Iterator, NewType, Protocol
+### `src/filesystem/lib.ts`
+
+The `readFileContent` function in [`src/filesystem/lib.ts`](https://github.com/modelcontextprotocol/servers/blob/HEAD/src/filesystem/lib.ts) handles a key part of this chapter's functionality:
+
+```ts
+}
+
+export async function readFileContent(filePath: string, encoding: string = 'utf-8'): Promise<string> {
+ return await fs.readFile(filePath, encoding as BufferEncoding);
+}
+
+export async function writeFileContent(filePath: string, content: string): Promise<void> {
+ try {
+ // Security: 'wx' flag ensures exclusive creation - fails if file/symlink exists,
+ // preventing writes through pre-existing symlinks
+ await fs.writeFile(filePath, content, { encoding: "utf-8", flag: 'wx' });
+ } catch (error) {
+ if ((error as NodeJS.ErrnoException).code === 'EEXIST') {
+ // Security: Use atomic rename to prevent race conditions where symlinks
+ // could be created between validation and write. Rename operations
+ // replace the target file atomically and don't follow symlinks.
+ const tempPath = `${filePath}.${randomBytes(16).toString('hex')}.tmp`;
+ try {
+ await fs.writeFile(tempPath, content, 'utf-8');
+ await fs.rename(tempPath, filePath);
+ } catch (renameError) {
+ try {
+ await fs.unlink(tempPath);
+ } catch {}
+ throw renameError;
+ }
+ } else {
+ throw error;
+ }
+ }
+}
-
-Version = NewType("Version", str)
-GitHash = NewType("GitHash", str)
-
-
-class GitHashParamType(click.ParamType):
- name = "git_hash"
-
- def convert(
- self, value: Any, param: click.Parameter | None, ctx: click.Context | None
- ) -> GitHash | None:
- if value is None:
- return None
-
- if not (8 <= len(value) <= 40):
```
This function is important because it defines how MCP Servers Tutorial: Reference Implementations and Patterns implements the patterns covered in this chapter.
-### `scripts/release.py`
-
-The `update_packages` function in [`scripts/release.py`](https://github.com/modelcontextprotocol/servers/blob/HEAD/scripts/release.py) handles a key part of this chapter's functionality:
-
-```py
-)
-@click.argument("git_hash", type=GIT_HASH)
-def update_packages(directory: Path, git_hash: GitHash) -> int:
- # Detect package type
- path = directory.resolve(strict=True)
- version = gen_version()
-
- for package in find_changed_packages(path, git_hash):
- name = package.package_name()
- package.update_version(version)
-
- click.echo(f"{name}@{version}")
-
- return 0
-
-
-@cli.command("generate-notes")
-@click.option(
- "--directory", type=click.Path(exists=True, path_type=Path), default=Path.cwd()
-)
-@click.argument("git_hash", type=GIT_HASH)
-def generate_notes(directory: Path, git_hash: GitHash) -> int:
- # Detect package type
- path = directory.resolve(strict=True)
- version = gen_version()
-
- click.echo(f"# Release : v{version}")
- click.echo("")
- click.echo("## Updated packages")
- for package in find_changed_packages(path, git_hash):
- name = package.package_name()
- click.echo(f"- {name}@{version}")
+### `src/filesystem/lib.ts`
+
+The `writeFileContent` function in [`src/filesystem/lib.ts`](https://github.com/modelcontextprotocol/servers/blob/HEAD/src/filesystem/lib.ts) handles a key part of this chapter's functionality:
+
+```ts
+}
+
+export async function writeFileContent(filePath: string, content: string): Promise<void> {
+ try {
+ // Security: 'wx' flag ensures exclusive creation - fails if file/symlink exists,
+ // preventing writes through pre-existing symlinks
+ await fs.writeFile(filePath, content, { encoding: "utf-8", flag: 'wx' });
+ } catch (error) {
+ if ((error as NodeJS.ErrnoException).code === 'EEXIST') {
+ // Security: Use atomic rename to prevent race conditions where symlinks
+ // could be created between validation and write. Rename operations
+ // replace the target file atomically and don't follow symlinks.
+ const tempPath = `${filePath}.${randomBytes(16).toString('hex')}.tmp`;
+ try {
+ await fs.writeFile(tempPath, content, 'utf-8');
+ await fs.rename(tempPath, filePath);
+ } catch (renameError) {
+ try {
+ await fs.unlink(tempPath);
+ } catch {}
+ throw renameError;
+ }
+ } else {
+ throw error;
+ }
+ }
+}
+
+
+// File Editing Functions
+interface FileEdit {
+ oldText: string;
```
This function is important because it defines how MCP Servers Tutorial: Reference Implementations and Patterns implements the patterns covered in this chapter.
-### `scripts/release.py`
+### `src/filesystem/lib.ts`
-The `generate_notes` function in [`scripts/release.py`](https://github.com/modelcontextprotocol/servers/blob/HEAD/scripts/release.py) handles a key part of this chapter's functionality:
+The `applyFileEdits` function in [`src/filesystem/lib.ts`](https://github.com/modelcontextprotocol/servers/blob/HEAD/src/filesystem/lib.ts) handles a key part of this chapter's functionality:
-```py
-)
-@click.argument("git_hash", type=GIT_HASH)
-def generate_notes(directory: Path, git_hash: GitHash) -> int:
- # Detect package type
- path = directory.resolve(strict=True)
- version = gen_version()
+```ts
+}
- click.echo(f"# Release : v{version}")
- click.echo("")
- click.echo("## Updated packages")
- for package in find_changed_packages(path, git_hash):
- name = package.package_name()
- click.echo(f"- {name}@{version}")
+export async function applyFileEdits(
+ filePath: string,
+ edits: FileEdit[],
+ dryRun: boolean = false
+): Promise<string> {
+ // Read file content and normalize line endings
+ const content = normalizeLineEndings(await fs.readFile(filePath, 'utf-8'));
- return 0
+ // Apply edits sequentially
+ let modifiedContent = content;
+ for (const edit of edits) {
+ const normalizedOld = normalizeLineEndings(edit.oldText);
+ const normalizedNew = normalizeLineEndings(edit.newText);
+ // If exact match exists, use it
+ if (modifiedContent.includes(normalizedOld)) {
+ modifiedContent = modifiedContent.replace(normalizedOld, normalizedNew);
+ continue;
+ }
-@cli.command("generate-version")
-def generate_version() -> int:
- # Detect package type
- click.echo(gen_version())
- return 0
+ // Otherwise, try line-by-line matching with flexibility for whitespace
+ const oldLines = normalizedOld.split('\n');
+ const contentLines = modifiedContent.split('\n');
+ let matchFound = false;
+ for (let i = 0; i <= contentLines.length - oldLines.length; i++) {
+ const potentialMatch = contentLines.slice(i, i + oldLines.length);
-@cli.command("generate-matrix")
-@click.option(
- "--directory", type=click.Path(exists=True, path_type=Path), default=Path.cwd()
-)
-@click.option("--npm", is_flag=True, default=False)
-@click.option("--pypi", is_flag=True, default=False)
-@click.argument("git_hash", type=GIT_HASH)
-def generate_matrix(directory: Path, git_hash: GitHash, pypi: bool, npm: bool) -> int:
+ // Compare lines with normalized whitespace
+ const isMatch = oldLines.every((oldLine, j) => {
```
This function is important because it defines how MCP Servers Tutorial: Reference Implementations and Patterns implements the patterns covered in this chapter.
@@ -296,11 +294,11 @@ This function is important because it defines how MCP Servers Tutorial: Referenc
```mermaid
flowchart TD
- A[find_changed_packages]
- B[cli]
- C[update_packages]
- D[generate_notes]
- E[generate_version]
+ A[getFileStats]
+ B[readFileContent]
+ C[writeFileContent]
+ D[applyFileEdits]
+ E[tailFile]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-servers-tutorial/03-git-server.md b/tutorials/mcp-servers-tutorial/03-git-server.md
index 457f3ba7..d9eea8c9 100644
--- a/tutorials/mcp-servers-tutorial/03-git-server.md
+++ b/tutorials/mcp-servers-tutorial/03-git-server.md
@@ -114,171 +114,182 @@ Suggested trace strategy:
- [Main Catalog](../../README.md#-tutorial-catalog)
- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/memory/index.ts`
+### `src/filesystem/lib.ts`
-The `contains` class in [`src/memory/index.ts`](https://github.com/modelcontextprotocol/servers/blob/HEAD/src/memory/index.ts) handles a key part of this chapter's functionality:
+The `search` function in [`src/filesystem/lib.ts`](https://github.com/modelcontextprotocol/servers/blob/HEAD/src/filesystem/lib.ts) handles a key part of this chapter's functionality:
```ts
}
-// The KnowledgeGraphManager class contains all operations to interact with the knowledge graph
-export class KnowledgeGraphManager {
- constructor(private memoryFilePath: string) {}
-
- private async loadGraph(): Promise<KnowledgeGraph> {
- try {
- const data = await fs.readFile(this.memoryFilePath, "utf-8");
- const lines = data.split("\n").filter(line => line.trim() !== "");
- return lines.reduce((graph: KnowledgeGraph, line) => {
- const item = JSON.parse(line);
- if (item.type === "entity") {
- graph.entities.push({
- name: item.name,
- entityType: item.entityType,
- observations: item.observations
- });
- }
- if (item.type === "relation") {
- graph.relations.push({
- from: item.from,
- to: item.to,
- relationType: item.relationType
- });
+export async function searchFilesWithValidation(
+ rootPath: string,
+ pattern: string,
+ allowedDirectories: string[],
+ options: SearchOptions = {}
+): Promise<string[]> {
+ const { excludePatterns = [] } = options;
+ const results: string[] = [];
+
+ async function search(currentPath: string) {
+ const entries = await fs.readdir(currentPath, { withFileTypes: true });
+
+ for (const entry of entries) {
+ const fullPath = path.join(currentPath, entry.name);
+
+ try {
+ await validatePath(fullPath);
+
+ const relativePath = path.relative(rootPath, fullPath);
+ const shouldExclude = excludePatterns.some(excludePattern =>
+ minimatch(relativePath, excludePattern, { dot: true })
+ );
+
+ if (shouldExclude) continue;
+
+ // Use glob matching for the search pattern
+ if (minimatch(relativePath, pattern, { dot: true })) {
+ results.push(fullPath);
}
- return graph;
- }, { entities: [], relations: [] });
- } catch (error) {
- if (error instanceof Error && 'code' in error && (error as any).code === "ENOENT") {
- return { entities: [], relations: [] };
- }
+
```
-This class is important because it defines how MCP Servers Tutorial: Reference Implementations and Patterns implements the patterns covered in this chapter.
+This function is important because it defines how MCP Servers Tutorial: Reference Implementations and Patterns implements the patterns covered in this chapter.
-### `src/memory/index.ts`
+### `src/filesystem/lib.ts`
-The `KnowledgeGraphManager` class in [`src/memory/index.ts`](https://github.com/modelcontextprotocol/servers/blob/HEAD/src/memory/index.ts) handles a key part of this chapter's functionality:
+The `FileInfo` interface in [`src/filesystem/lib.ts`](https://github.com/modelcontextprotocol/servers/blob/HEAD/src/filesystem/lib.ts) handles a key part of this chapter's functionality:
```ts
+
+// Type definitions
+interface FileInfo {
+ size: number;
+ created: Date;
+ modified: Date;
+ accessed: Date;
+ isDirectory: boolean;
+ isFile: boolean;
+ permissions: string;
}
-// The KnowledgeGraphManager class contains all operations to interact with the knowledge graph
-export class KnowledgeGraphManager {
- constructor(private memoryFilePath: string) {}
-
- private async loadGraph(): Promise<KnowledgeGraph> {
- try {
- const data = await fs.readFile(this.memoryFilePath, "utf-8");
- const lines = data.split("\n").filter(line => line.trim() !== "");
- return lines.reduce((graph: KnowledgeGraph, line) => {
- const item = JSON.parse(line);
- if (item.type === "entity") {
- graph.entities.push({
- name: item.name,
- entityType: item.entityType,
- observations: item.observations
- });
- }
- if (item.type === "relation") {
- graph.relations.push({
- from: item.from,
- to: item.to,
- relationType: item.relationType
- });
- }
- return graph;
- }, { entities: [], relations: [] });
- } catch (error) {
- if (error instanceof Error && 'code' in error && (error as any).code === "ENOENT") {
- return { entities: [], relations: [] };
- }
+export interface SearchOptions {
+ excludePatterns?: string[];
+}
+
+export interface SearchResult {
+ path: string;
+ isDirectory: boolean;
+}
+
+// Pure Utility Functions
+export function formatSize(bytes: number): string {
+ const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+ if (bytes === 0) return '0 B';
+
+ const i = Math.floor(Math.log(bytes) / Math.log(1024));
+
+ if (i < 0 || i === 0) return `${bytes} ${units[0]}`;
+
+ const unitIndex = Math.min(i, units.length - 1);
+ return `${(bytes / Math.pow(1024, unitIndex)).toFixed(2)} ${units[unitIndex]}`;
```
-This class is important because it defines how MCP Servers Tutorial: Reference Implementations and Patterns implements the patterns covered in this chapter.
+This interface is important because it defines how MCP Servers Tutorial: Reference Implementations and Patterns implements the patterns covered in this chapter.
-### `src/memory/index.ts`
+### `src/filesystem/lib.ts`
-The `ensureMemoryFilePath` function in [`src/memory/index.ts`](https://github.com/modelcontextprotocol/servers/blob/HEAD/src/memory/index.ts) handles a key part of this chapter's functionality:
+The `SearchOptions` interface in [`src/filesystem/lib.ts`](https://github.com/modelcontextprotocol/servers/blob/HEAD/src/filesystem/lib.ts) handles a key part of this chapter's functionality:
```ts
+}
+
+export interface SearchOptions {
+ excludePatterns?: string[];
+}
+
+export interface SearchResult {
+ path: string;
+ isDirectory: boolean;
+}
-// Handle backward compatibility: migrate memory.json to memory.jsonl if needed
-export async function ensureMemoryFilePath(): Promise<string> {
- if (process.env.MEMORY_FILE_PATH) {
- // Custom path provided, use it as-is (with absolute path resolution)
- return path.isAbsolute(process.env.MEMORY_FILE_PATH)
- ? process.env.MEMORY_FILE_PATH
- : path.join(path.dirname(fileURLToPath(import.meta.url)), process.env.MEMORY_FILE_PATH);
- }
+// Pure Utility Functions
+export function formatSize(bytes: number): string {
+ const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+ if (bytes === 0) return '0 B';
+
+ const i = Math.floor(Math.log(bytes) / Math.log(1024));
- // No custom path set, check for backward compatibility migration
- const oldMemoryPath = path.join(path.dirname(fileURLToPath(import.meta.url)), 'memory.json');
- const newMemoryPath = defaultMemoryPath;
+ if (i < 0 || i === 0) return `${bytes} ${units[0]}`;
- try {
- // Check if old file exists and new file doesn't
- await fs.access(oldMemoryPath);
- try {
- await fs.access(newMemoryPath);
- // Both files exist, use new one (no migration needed)
- return newMemoryPath;
- } catch {
- // Old file exists, new file doesn't - migrate
- console.error('DETECTED: Found legacy memory.json file, migrating to memory.jsonl for JSONL format compatibility');
- await fs.rename(oldMemoryPath, newMemoryPath);
- console.error('COMPLETED: Successfully migrated memory.json to memory.jsonl');
- return newMemoryPath;
- }
- } catch {
- // Old file doesn't exist, use new path
- return newMemoryPath;
- }
+ const unitIndex = Math.min(i, units.length - 1);
+ return `${(bytes / Math.pow(1024, unitIndex)).toFixed(2)} ${units[unitIndex]}`;
+}
+
+export function normalizeLineEndings(text: string): string {
+ return text.replace(/\r\n/g, '\n');
+}
+
+export function createUnifiedDiff(originalContent: string, newContent: string, filepath: string = 'file'): string {
+ // Ensure consistent line endings for diff
+ const normalizedOriginal = normalizeLineEndings(originalContent);
+ const normalizedNew = normalizeLineEndings(newContent);
```
-This function is important because it defines how MCP Servers Tutorial: Reference Implementations and Patterns implements the patterns covered in this chapter.
+This interface is important because it defines how MCP Servers Tutorial: Reference Implementations and Patterns implements the patterns covered in this chapter.
-### `src/memory/index.ts`
+### `src/filesystem/lib.ts`
-The `main` function in [`src/memory/index.ts`](https://github.com/modelcontextprotocol/servers/blob/HEAD/src/memory/index.ts) handles a key part of this chapter's functionality:
+The `SearchResult` interface in [`src/filesystem/lib.ts`](https://github.com/modelcontextprotocol/servers/blob/HEAD/src/filesystem/lib.ts) handles a key part of this chapter's functionality:
```ts
-);
+}
-async function main() {
- // Initialize memory file path with backward compatibility
- MEMORY_FILE_PATH = await ensureMemoryFilePath();
+export interface SearchResult {
+ path: string;
+ isDirectory: boolean;
+}
- // Initialize knowledge graph manager with the memory file path
- knowledgeGraphManager = new KnowledgeGraphManager(MEMORY_FILE_PATH);
+// Pure Utility Functions
+export function formatSize(bytes: number): string {
+ const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+ if (bytes === 0) return '0 B';
+
+ const i = Math.floor(Math.log(bytes) / Math.log(1024));
+
+ if (i < 0 || i === 0) return `${bytes} ${units[0]}`;
+
+ const unitIndex = Math.min(i, units.length - 1);
+ return `${(bytes / Math.pow(1024, unitIndex)).toFixed(2)} ${units[unitIndex]}`;
+}
- const transport = new StdioServerTransport();
- await server.connect(transport);
- console.error("Knowledge Graph MCP Server running on stdio");
+export function normalizeLineEndings(text: string): string {
+ return text.replace(/\r\n/g, '\n');
}
-main().catch((error) => {
- console.error("Fatal error in main():", error);
- process.exit(1);
-});
+export function createUnifiedDiff(originalContent: string, newContent: string, filepath: string = 'file'): string {
+ // Ensure consistent line endings for diff
+ const normalizedOriginal = normalizeLineEndings(originalContent);
+ const normalizedNew = normalizeLineEndings(newContent);
+ return createTwoFilesPatch(
+ filepath,
+ filepath,
```
-This function is important because it defines how MCP Servers Tutorial: Reference Implementations and Patterns implements the patterns covered in this chapter.
+This interface is important because it defines how MCP Servers Tutorial: Reference Implementations and Patterns implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[contains]
- B[KnowledgeGraphManager]
- C[ensureMemoryFilePath]
- D[main]
- E[Entity]
+ A[search]
+ B[FileInfo]
+ C[SearchOptions]
+ D[SearchResult]
+ E[FileEdit]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-servers-tutorial/04-memory-server.md b/tutorials/mcp-servers-tutorial/04-memory-server.md
index 970ea5ec..9bd7a06f 100644
--- a/tutorials/mcp-servers-tutorial/04-memory-server.md
+++ b/tutorials/mcp-servers-tutorial/04-memory-server.md
@@ -114,184 +114,169 @@ Suggested trace strategy:
- [Main Catalog](../../README.md#-tutorial-catalog)
- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/filesystem/lib.ts`
+### `src/memory/index.ts`
-The `setAllowedDirectories` function in [`src/filesystem/lib.ts`](https://github.com/modelcontextprotocol/servers/blob/HEAD/src/filesystem/lib.ts) handles a key part of this chapter's functionality:
+The `ensureMemoryFilePath` function in [`src/memory/index.ts`](https://github.com/modelcontextprotocol/servers/blob/HEAD/src/memory/index.ts) handles a key part of this chapter's functionality:
```ts
-// Function to set allowed directories from the main module
-export function setAllowedDirectories(directories: string[]): void {
- allowedDirectories = [...directories];
-}
-
-// Function to get current allowed directories
-export function getAllowedDirectories(): string[] {
- return [...allowedDirectories];
-}
-
-// Type definitions
-interface FileInfo {
- size: number;
- created: Date;
- modified: Date;
- accessed: Date;
- isDirectory: boolean;
- isFile: boolean;
- permissions: string;
-}
-
-export interface SearchOptions {
- excludePatterns?: string[];
-}
-
-export interface SearchResult {
- path: string;
- isDirectory: boolean;
-}
-
-// Pure Utility Functions
+// Handle backward compatibility: migrate memory.json to memory.jsonl if needed
+export async function ensureMemoryFilePath(): Promise<string> {
+ if (process.env.MEMORY_FILE_PATH) {
+ // Custom path provided, use it as-is (with absolute path resolution)
+ return path.isAbsolute(process.env.MEMORY_FILE_PATH)
+ ? process.env.MEMORY_FILE_PATH
+ : path.join(path.dirname(fileURLToPath(import.meta.url)), process.env.MEMORY_FILE_PATH);
+ }
+
+ // No custom path set, check for backward compatibility migration
+ const oldMemoryPath = path.join(path.dirname(fileURLToPath(import.meta.url)), 'memory.json');
+ const newMemoryPath = defaultMemoryPath;
+
+ try {
+ // Check if old file exists and new file doesn't
+ await fs.access(oldMemoryPath);
+ try {
+ await fs.access(newMemoryPath);
+ // Both files exist, use new one (no migration needed)
+ return newMemoryPath;
+ } catch {
+ // Old file exists, new file doesn't - migrate
+ console.error('DETECTED: Found legacy memory.json file, migrating to memory.jsonl for JSONL format compatibility');
+ await fs.rename(oldMemoryPath, newMemoryPath);
+ console.error('COMPLETED: Successfully migrated memory.json to memory.jsonl');
+ return newMemoryPath;
+ }
+ } catch {
+ // Old file doesn't exist, use new path
+ return newMemoryPath;
+ }
```
This function is important because it defines how MCP Servers Tutorial: Reference Implementations and Patterns implements the patterns covered in this chapter.
-### `src/filesystem/lib.ts`
+### `src/memory/index.ts`
-The `getAllowedDirectories` function in [`src/filesystem/lib.ts`](https://github.com/modelcontextprotocol/servers/blob/HEAD/src/filesystem/lib.ts) handles a key part of this chapter's functionality:
+The `main` function in [`src/memory/index.ts`](https://github.com/modelcontextprotocol/servers/blob/HEAD/src/memory/index.ts) handles a key part of this chapter's functionality:
```ts
+);
-// Function to get current allowed directories
-export function getAllowedDirectories(): string[] {
- return [...allowedDirectories];
-}
+async function main() {
+ // Initialize memory file path with backward compatibility
+ MEMORY_FILE_PATH = await ensureMemoryFilePath();
-// Type definitions
-interface FileInfo {
- size: number;
- created: Date;
- modified: Date;
- accessed: Date;
- isDirectory: boolean;
- isFile: boolean;
- permissions: string;
-}
+ // Initialize knowledge graph manager with the memory file path
+ knowledgeGraphManager = new KnowledgeGraphManager(MEMORY_FILE_PATH);
-export interface SearchOptions {
- excludePatterns?: string[];
+ const transport = new StdioServerTransport();
+ await server.connect(transport);
+ console.error("Knowledge Graph MCP Server running on stdio");
}
-export interface SearchResult {
- path: string;
- isDirectory: boolean;
-}
+main().catch((error) => {
+ console.error("Fatal error in main():", error);
+ process.exit(1);
+});
-// Pure Utility Functions
-export function formatSize(bytes: number): string {
- const units = ['B', 'KB', 'MB', 'GB', 'TB'];
- if (bytes === 0) return '0 B';
-
- const i = Math.floor(Math.log(bytes) / Math.log(1024));
```
This function is important because it defines how MCP Servers Tutorial: Reference Implementations and Patterns implements the patterns covered in this chapter.
-### `src/filesystem/lib.ts`
+### `src/memory/index.ts`
-The `formatSize` function in [`src/filesystem/lib.ts`](https://github.com/modelcontextprotocol/servers/blob/HEAD/src/filesystem/lib.ts) handles a key part of this chapter's functionality:
+The `Entity` interface in [`src/memory/index.ts`](https://github.com/modelcontextprotocol/servers/blob/HEAD/src/memory/index.ts) handles a key part of this chapter's functionality:
```ts
-// Pure Utility Functions
-export function formatSize(bytes: number): string {
- const units = ['B', 'KB', 'MB', 'GB', 'TB'];
- if (bytes === 0) return '0 B';
-
- const i = Math.floor(Math.log(bytes) / Math.log(1024));
-
- if (i < 0 || i === 0) return `${bytes} ${units[0]}`;
-
- const unitIndex = Math.min(i, units.length - 1);
- return `${(bytes / Math.pow(1024, unitIndex)).toFixed(2)} ${units[unitIndex]}`;
+// We are storing our memory using entities, relations, and observations in a graph structure
+export interface Entity {
+ name: string;
+ entityType: string;
+ observations: string[];
}
-export function normalizeLineEndings(text: string): string {
- return text.replace(/\r\n/g, '\n');
+export interface Relation {
+ from: string;
+ to: string;
+ relationType: string;
}
-export function createUnifiedDiff(originalContent: string, newContent: string, filepath: string = 'file'): string {
- // Ensure consistent line endings for diff
- const normalizedOriginal = normalizeLineEndings(originalContent);
- const normalizedNew = normalizeLineEndings(newContent);
-
- return createTwoFilesPatch(
- filepath,
- filepath,
- normalizedOriginal,
- normalizedNew,
- 'original',
- 'modified'
- );
+export interface KnowledgeGraph {
+ entities: Entity[];
+ relations: Relation[];
}
+
+// The KnowledgeGraphManager class contains all operations to interact with the knowledge graph
+export class KnowledgeGraphManager {
+ constructor(private memoryFilePath: string) {}
+
+ private async loadGraph(): Promise<KnowledgeGraph> {
+ try {
+ const data = await fs.readFile(this.memoryFilePath, "utf-8");
+ const lines = data.split("\n").filter(line => line.trim() !== "");
+ return lines.reduce((graph: KnowledgeGraph, line) => {
+ const item = JSON.parse(line);
+ if (item.type === "entity") {
+ graph.entities.push({
+ name: item.name,
```
-This function is important because it defines how MCP Servers Tutorial: Reference Implementations and Patterns implements the patterns covered in this chapter.
+This interface is important because it defines how MCP Servers Tutorial: Reference Implementations and Patterns implements the patterns covered in this chapter.
-### `src/filesystem/lib.ts`
+### `src/memory/index.ts`
-The `normalizeLineEndings` function in [`src/filesystem/lib.ts`](https://github.com/modelcontextprotocol/servers/blob/HEAD/src/filesystem/lib.ts) handles a key part of this chapter's functionality:
+The `Relation` interface in [`src/memory/index.ts`](https://github.com/modelcontextprotocol/servers/blob/HEAD/src/memory/index.ts) handles a key part of this chapter's functionality:
```ts
}
-export function normalizeLineEndings(text: string): string {
- return text.replace(/\r\n/g, '\n');
+export interface Relation {
+ from: string;
+ to: string;
+ relationType: string;
}
-export function createUnifiedDiff(originalContent: string, newContent: string, filepath: string = 'file'): string {
- // Ensure consistent line endings for diff
- const normalizedOriginal = normalizeLineEndings(originalContent);
- const normalizedNew = normalizeLineEndings(newContent);
-
- return createTwoFilesPatch(
- filepath,
- filepath,
- normalizedOriginal,
- normalizedNew,
- 'original',
- 'modified'
- );
+export interface KnowledgeGraph {
+ entities: Entity[];
+ relations: Relation[];
}
-// Helper function to resolve relative paths against allowed directories
-function resolveRelativePathAgainstAllowedDirectories(relativePath: string): string {
- if (allowedDirectories.length === 0) {
- // Fallback to process.cwd() if no allowed directories are set
- return path.resolve(process.cwd(), relativePath);
- }
-
- // Try to resolve relative path against each allowed directory
- for (const allowedDir of allowedDirectories) {
- const candidate = path.resolve(allowedDir, relativePath);
- const normalizedCandidate = normalizePath(candidate);
+// The KnowledgeGraphManager class contains all operations to interact with the knowledge graph
+export class KnowledgeGraphManager {
+ constructor(private memoryFilePath: string) {}
+
+ private async loadGraph(): Promise<KnowledgeGraph> {
+ try {
+ const data = await fs.readFile(this.memoryFilePath, "utf-8");
+ const lines = data.split("\n").filter(line => line.trim() !== "");
+ return lines.reduce((graph: KnowledgeGraph, line) => {
+ const item = JSON.parse(line);
+ if (item.type === "entity") {
+ graph.entities.push({
+ name: item.name,
+ entityType: item.entityType,
+ observations: item.observations
+ });
+ }
+ if (item.type === "relation") {
+ graph.relations.push({
```
-This function is important because it defines how MCP Servers Tutorial: Reference Implementations and Patterns implements the patterns covered in this chapter.
+This interface is important because it defines how MCP Servers Tutorial: Reference Implementations and Patterns implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[setAllowedDirectories]
- B[getAllowedDirectories]
- C[formatSize]
- D[normalizeLineEndings]
- E[createUnifiedDiff]
+ A[ensureMemoryFilePath]
+ B[main]
+ C[Entity]
+ D[Relation]
+ E[KnowledgeGraph]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-servers-tutorial/05-multi-language-servers.md b/tutorials/mcp-servers-tutorial/05-multi-language-servers.md
index 10a0ee00..a5cd810c 100644
--- a/tutorials/mcp-servers-tutorial/05-multi-language-servers.md
+++ b/tutorials/mcp-servers-tutorial/05-multi-language-servers.md
@@ -103,184 +103,182 @@ Suggested trace strategy:
- [Main Catalog](../../README.md#-tutorial-catalog)
- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/filesystem/lib.ts`
-
-The `getFileStats` function in [`src/filesystem/lib.ts`](https://github.com/modelcontextprotocol/servers/blob/HEAD/src/filesystem/lib.ts) handles a key part of this chapter's functionality:
-
-```ts
-
-// File Operations
-export async function getFileStats(filePath: string): Promise<FileInfo> {
- const stats = await fs.stat(filePath);
- return {
- size: stats.size,
- created: stats.birthtime,
- modified: stats.mtime,
- accessed: stats.atime,
- isDirectory: stats.isDirectory(),
- isFile: stats.isFile(),
- permissions: stats.mode.toString(8).slice(-3),
- };
-}
-
-export async function readFileContent(filePath: string, encoding: string = 'utf-8'): Promise<string> {
- return await fs.readFile(filePath, encoding as BufferEncoding);
-}
-
-export async function writeFileContent(filePath: string, content: string): Promise<void> {
- try {
- // Security: 'wx' flag ensures exclusive creation - fails if file/symlink exists,
- // preventing writes through pre-existing symlinks
- await fs.writeFile(filePath, content, { encoding: "utf-8", flag: 'wx' });
- } catch (error) {
- if ((error as NodeJS.ErrnoException).code === 'EEXIST') {
- // Security: Use atomic rename to prevent race conditions where symlinks
- // could be created between validation and write. Rename operations
- // replace the target file atomically and don't follow symlinks.
- const tempPath = `${filePath}.${randomBytes(16).toString('hex')}.tmp`;
- try {
- await fs.writeFile(tempPath, content, 'utf-8');
+### `scripts/release.py`
+
+The `GitHashParamType` class in [`scripts/release.py`](https://github.com/modelcontextprotocol/servers/blob/HEAD/scripts/release.py) handles a key part of this chapter's functionality:
+
+```py
+
+
+class GitHashParamType(click.ParamType):
+ name = "git_hash"
+
+ def convert(
+ self, value: Any, param: click.Parameter | None, ctx: click.Context | None
+ ) -> GitHash | None:
+ if value is None:
+ return None
+
+ if not (8 <= len(value) <= 40):
+ self.fail(f"Git hash must be between 8 and 40 characters, got {len(value)}")
+
+ if not re.match(r"^[0-9a-fA-F]+$", value):
+ self.fail("Git hash must contain only hex digits (0-9, a-f)")
+
+ try:
+ # Verify hash exists in repo
+ subprocess.run(
+ ["git", "rev-parse", "--verify", value], check=True, capture_output=True
+ )
+ except subprocess.CalledProcessError:
+ self.fail(f"Git hash {value} not found in repository")
+
+ return GitHash(value.lower())
+
+
+GIT_HASH = GitHashParamType()
+
+
+class Package(Protocol):
```
-This function is important because it defines how MCP Servers Tutorial: Reference Implementations and Patterns implements the patterns covered in this chapter.
-
-### `src/filesystem/lib.ts`
-
-The `readFileContent` function in [`src/filesystem/lib.ts`](https://github.com/modelcontextprotocol/servers/blob/HEAD/src/filesystem/lib.ts) handles a key part of this chapter's functionality:
-
-```ts
-}
-
-export async function readFileContent(filePath: string, encoding: string = 'utf-8'): Promise<string> {
- return await fs.readFile(filePath, encoding as BufferEncoding);
-}
-
-export async function writeFileContent(filePath: string, content: string): Promise<void> {
- try {
- // Security: 'wx' flag ensures exclusive creation - fails if file/symlink exists,
- // preventing writes through pre-existing symlinks
- await fs.writeFile(filePath, content, { encoding: "utf-8", flag: 'wx' });
- } catch (error) {
- if ((error as NodeJS.ErrnoException).code === 'EEXIST') {
- // Security: Use atomic rename to prevent race conditions where symlinks
- // could be created between validation and write. Rename operations
- // replace the target file atomically and don't follow symlinks.
- const tempPath = `${filePath}.${randomBytes(16).toString('hex')}.tmp`;
- try {
- await fs.writeFile(tempPath, content, 'utf-8');
- await fs.rename(tempPath, filePath);
- } catch (renameError) {
- try {
- await fs.unlink(tempPath);
- } catch {}
- throw renameError;
- }
- } else {
- throw error;
- }
- }
-}
+This class is important because it defines how MCP Servers Tutorial: Reference Implementations and Patterns implements the patterns covered in this chapter.
+
+### `scripts/release.py`
+
+The `Package` class in [`scripts/release.py`](https://github.com/modelcontextprotocol/servers/blob/HEAD/scripts/release.py) handles a key part of this chapter's functionality:
+
+```py
+
+
+class Package(Protocol):
+ path: Path
+
+ def package_name(self) -> str: ...
+ def update_version(self, version: Version) -> None: ...
+
+
+@dataclass
+class NpmPackage:
+ path: Path
+
+ def package_name(self) -> str:
+ with open(self.path / "package.json", "r") as f:
+ return json.load(f)["name"]
+
+ def update_version(self, version: Version):
+ with open(self.path / "package.json", "r+") as f:
+ data = json.load(f)
+ data["version"] = version
+ f.seek(0)
+ json.dump(data, f, indent=2)
+ f.truncate()
+
+
+@dataclass
+class PyPiPackage:
+ path: Path
+
+ def package_name(self) -> str:
```
-This function is important because it defines how MCP Servers Tutorial: Reference Implementations and Patterns implements the patterns covered in this chapter.
-
-### `src/filesystem/lib.ts`
-
-The `writeFileContent` function in [`src/filesystem/lib.ts`](https://github.com/modelcontextprotocol/servers/blob/HEAD/src/filesystem/lib.ts) handles a key part of this chapter's functionality:
-
-```ts
-}
-
-export async function writeFileContent(filePath: string, content: string): Promise<void> {
- try {
- // Security: 'wx' flag ensures exclusive creation - fails if file/symlink exists,
- // preventing writes through pre-existing symlinks
- await fs.writeFile(filePath, content, { encoding: "utf-8", flag: 'wx' });
- } catch (error) {
- if ((error as NodeJS.ErrnoException).code === 'EEXIST') {
- // Security: Use atomic rename to prevent race conditions where symlinks
- // could be created between validation and write. Rename operations
- // replace the target file atomically and don't follow symlinks.
- const tempPath = `${filePath}.${randomBytes(16).toString('hex')}.tmp`;
- try {
- await fs.writeFile(tempPath, content, 'utf-8');
- await fs.rename(tempPath, filePath);
- } catch (renameError) {
- try {
- await fs.unlink(tempPath);
- } catch {}
- throw renameError;
- }
- } else {
- throw error;
- }
- }
-}
-
-
-// File Editing Functions
-interface FileEdit {
- oldText: string;
+This class is important because it defines how MCP Servers Tutorial: Reference Implementations and Patterns implements the patterns covered in this chapter.
+
+### `scripts/release.py`
+
+The `class` class in [`scripts/release.py`](https://github.com/modelcontextprotocol/servers/blob/HEAD/scripts/release.py) handles a key part of this chapter's functionality:
+
+```py
+import datetime
+import subprocess
+from dataclasses import dataclass
+from typing import Any, Iterator, NewType, Protocol
+
+
+Version = NewType("Version", str)
+GitHash = NewType("GitHash", str)
+
+
+class GitHashParamType(click.ParamType):
+ name = "git_hash"
+
+ def convert(
+ self, value: Any, param: click.Parameter | None, ctx: click.Context | None
+ ) -> GitHash | None:
+ if value is None:
+ return None
+
+ if not (8 <= len(value) <= 40):
+ self.fail(f"Git hash must be between 8 and 40 characters, got {len(value)}")
+
+ if not re.match(r"^[0-9a-fA-F]+$", value):
+ self.fail("Git hash must contain only hex digits (0-9, a-f)")
+
+ try:
+ # Verify hash exists in repo
+ subprocess.run(
+ ["git", "rev-parse", "--verify", value], check=True, capture_output=True
+ )
+ except subprocess.CalledProcessError:
+ self.fail(f"Git hash {value} not found in repository")
```
-This function is important because it defines how MCP Servers Tutorial: Reference Implementations and Patterns implements the patterns covered in this chapter.
+This class is important because it defines how MCP Servers Tutorial: Reference Implementations and Patterns implements the patterns covered in this chapter.
+
+### `scripts/release.py`
+
+The `class` class in [`scripts/release.py`](https://github.com/modelcontextprotocol/servers/blob/HEAD/scripts/release.py) handles a key part of this chapter's functionality:
-### `src/filesystem/lib.ts`
+```py
+import datetime
+import subprocess
+from dataclasses import dataclass
+from typing import Any, Iterator, NewType, Protocol
-The `applyFileEdits` function in [`src/filesystem/lib.ts`](https://github.com/modelcontextprotocol/servers/blob/HEAD/src/filesystem/lib.ts) handles a key part of this chapter's functionality:
-```ts
-}
+Version = NewType("Version", str)
+GitHash = NewType("GitHash", str)
-export async function applyFileEdits(
- filePath: string,
- edits: FileEdit[],
- dryRun: boolean = false
-): Promise<string> {
- // Read file content and normalize line endings
- const content = normalizeLineEndings(await fs.readFile(filePath, 'utf-8'));
- // Apply edits sequentially
- let modifiedContent = content;
- for (const edit of edits) {
- const normalizedOld = normalizeLineEndings(edit.oldText);
- const normalizedNew = normalizeLineEndings(edit.newText);
+class GitHashParamType(click.ParamType):
+ name = "git_hash"
- // If exact match exists, use it
- if (modifiedContent.includes(normalizedOld)) {
- modifiedContent = modifiedContent.replace(normalizedOld, normalizedNew);
- continue;
- }
+ def convert(
+ self, value: Any, param: click.Parameter | None, ctx: click.Context | None
+ ) -> GitHash | None:
+ if value is None:
+ return None
- // Otherwise, try line-by-line matching with flexibility for whitespace
- const oldLines = normalizedOld.split('\n');
- const contentLines = modifiedContent.split('\n');
- let matchFound = false;
+ if not (8 <= len(value) <= 40):
+ self.fail(f"Git hash must be between 8 and 40 characters, got {len(value)}")
- for (let i = 0; i <= contentLines.length - oldLines.length; i++) {
- const potentialMatch = contentLines.slice(i, i + oldLines.length);
+ if not re.match(r"^[0-9a-fA-F]+$", value):
+ self.fail("Git hash must contain only hex digits (0-9, a-f)")
- // Compare lines with normalized whitespace
- const isMatch = oldLines.every((oldLine, j) => {
+ try:
+ # Verify hash exists in repo
+ subprocess.run(
+ ["git", "rev-parse", "--verify", value], check=True, capture_output=True
+ )
+ except subprocess.CalledProcessError:
+ self.fail(f"Git hash {value} not found in repository")
```
-This function is important because it defines how MCP Servers Tutorial: Reference Implementations and Patterns implements the patterns covered in this chapter.
+This class is important because it defines how MCP Servers Tutorial: Reference Implementations and Patterns implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[getFileStats]
- B[readFileContent]
- C[writeFileContent]
- D[applyFileEdits]
- E[tailFile]
+ A[GitHashParamType]
+ B[Package]
+ C[class]
+ D[class]
+ E[has_changes]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-servers-tutorial/06-custom-server-development.md b/tutorials/mcp-servers-tutorial/06-custom-server-development.md
index 076bacb3..718073cf 100644
--- a/tutorials/mcp-servers-tutorial/06-custom-server-development.md
+++ b/tutorials/mcp-servers-tutorial/06-custom-server-development.md
@@ -117,184 +117,182 @@ Suggested trace strategy:
- [Main Catalog](../../README.md#-tutorial-catalog)
- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/filesystem/lib.ts`
+### `scripts/release.py`
+
+The `cli` function in [`scripts/release.py`](https://github.com/modelcontextprotocol/servers/blob/HEAD/scripts/release.py) handles a key part of this chapter's functionality:
+
+```py
+# requires-python = ">=3.12"
+# dependencies = [
+# "click>=8.1.8",
+# "tomlkit>=0.13.2"
+# ]
+# ///
+import sys
+import re
+import click
+from pathlib import Path
+import json
+import tomlkit
+import datetime
+import subprocess
+from dataclasses import dataclass
+from typing import Any, Iterator, NewType, Protocol
+
+
+Version = NewType("Version", str)
+GitHash = NewType("GitHash", str)
+
+
+class GitHashParamType(click.ParamType):
+ name = "git_hash"
+
+ def convert(
+ self, value: Any, param: click.Parameter | None, ctx: click.Context | None
+ ) -> GitHash | None:
+ if value is None:
+ return None
-The `search` function in [`src/filesystem/lib.ts`](https://github.com/modelcontextprotocol/servers/blob/HEAD/src/filesystem/lib.ts) handles a key part of this chapter's functionality:
+ if not (8 <= len(value) <= 40):
+```
+
+This function is important because it defines how MCP Servers Tutorial: Reference Implementations and Patterns implements the patterns covered in this chapter.
-```ts
-}
+### `scripts/release.py`
-export async function searchFilesWithValidation(
- rootPath: string,
- pattern: string,
- allowedDirectories: string[],
- options: SearchOptions = {}
-): Promise<string[]> {
- const { excludePatterns = [] } = options;
- const results: string[] = [];
+The `update_packages` function in [`scripts/release.py`](https://github.com/modelcontextprotocol/servers/blob/HEAD/scripts/release.py) handles a key part of this chapter's functionality:
- async function search(currentPath: string) {
- const entries = await fs.readdir(currentPath, { withFileTypes: true });
+```py
+)
+@click.argument("git_hash", type=GIT_HASH)
+def update_packages(directory: Path, git_hash: GitHash) -> int:
+ # Detect package type
+ path = directory.resolve(strict=True)
+ version = gen_version()
- for (const entry of entries) {
- const fullPath = path.join(currentPath, entry.name);
+ for package in find_changed_packages(path, git_hash):
+ name = package.package_name()
+ package.update_version(version)
- try {
- await validatePath(fullPath);
+ click.echo(f"{name}@{version}")
- const relativePath = path.relative(rootPath, fullPath);
- const shouldExclude = excludePatterns.some(excludePattern =>
- minimatch(relativePath, excludePattern, { dot: true })
- );
+ return 0
- if (shouldExclude) continue;
- // Use glob matching for the search pattern
- if (minimatch(relativePath, pattern, { dot: true })) {
- results.push(fullPath);
- }
+@cli.command("generate-notes")
+@click.option(
+ "--directory", type=click.Path(exists=True, path_type=Path), default=Path.cwd()
+)
+@click.argument("git_hash", type=GIT_HASH)
+def generate_notes(directory: Path, git_hash: GitHash) -> int:
+ # Detect package type
+ path = directory.resolve(strict=True)
+ version = gen_version()
+ click.echo(f"# Release : v{version}")
+ click.echo("")
+ click.echo("## Updated packages")
+ for package in find_changed_packages(path, git_hash):
+ name = package.package_name()
+ click.echo(f"- {name}@{version}")
```
This function is important because it defines how MCP Servers Tutorial: Reference Implementations and Patterns implements the patterns covered in this chapter.
-### `src/filesystem/lib.ts`
-
-The `FileInfo` interface in [`src/filesystem/lib.ts`](https://github.com/modelcontextprotocol/servers/blob/HEAD/src/filesystem/lib.ts) handles a key part of this chapter's functionality:
-
-```ts
-
-// Type definitions
-interface FileInfo {
- size: number;
- created: Date;
- modified: Date;
- accessed: Date;
- isDirectory: boolean;
- isFile: boolean;
- permissions: string;
-}
-
-export interface SearchOptions {
- excludePatterns?: string[];
-}
-
-export interface SearchResult {
- path: string;
- isDirectory: boolean;
-}
-
-// Pure Utility Functions
-export function formatSize(bytes: number): string {
- const units = ['B', 'KB', 'MB', 'GB', 'TB'];
- if (bytes === 0) return '0 B';
-
- const i = Math.floor(Math.log(bytes) / Math.log(1024));
-
- if (i < 0 || i === 0) return `${bytes} ${units[0]}`;
-
- const unitIndex = Math.min(i, units.length - 1);
- return `${(bytes / Math.pow(1024, unitIndex)).toFixed(2)} ${units[unitIndex]}`;
-```
+### `scripts/release.py`
+
+The `generate_notes` function in [`scripts/release.py`](https://github.com/modelcontextprotocol/servers/blob/HEAD/scripts/release.py) handles a key part of this chapter's functionality:
+
+```py
+)
+@click.argument("git_hash", type=GIT_HASH)
+def generate_notes(directory: Path, git_hash: GitHash) -> int:
+ # Detect package type
+ path = directory.resolve(strict=True)
+ version = gen_version()
+
+ click.echo(f"# Release : v{version}")
+ click.echo("")
+ click.echo("## Updated packages")
+ for package in find_changed_packages(path, git_hash):
+ name = package.package_name()
+ click.echo(f"- {name}@{version}")
+
+ return 0
-This interface is important because it defines how MCP Servers Tutorial: Reference Implementations and Patterns implements the patterns covered in this chapter.
-
-### `src/filesystem/lib.ts`
-
-The `SearchOptions` interface in [`src/filesystem/lib.ts`](https://github.com/modelcontextprotocol/servers/blob/HEAD/src/filesystem/lib.ts) handles a key part of this chapter's functionality:
-
-```ts
-}
-
-export interface SearchOptions {
- excludePatterns?: string[];
-}
-
-export interface SearchResult {
- path: string;
- isDirectory: boolean;
-}
-
-// Pure Utility Functions
-export function formatSize(bytes: number): string {
- const units = ['B', 'KB', 'MB', 'GB', 'TB'];
- if (bytes === 0) return '0 B';
-
- const i = Math.floor(Math.log(bytes) / Math.log(1024));
-
- if (i < 0 || i === 0) return `${bytes} ${units[0]}`;
-
- const unitIndex = Math.min(i, units.length - 1);
- return `${(bytes / Math.pow(1024, unitIndex)).toFixed(2)} ${units[unitIndex]}`;
-}
-
-export function normalizeLineEndings(text: string): string {
- return text.replace(/\r\n/g, '\n');
-}
-
-export function createUnifiedDiff(originalContent: string, newContent: string, filepath: string = 'file'): string {
- // Ensure consistent line endings for diff
- const normalizedOriginal = normalizeLineEndings(originalContent);
- const normalizedNew = normalizeLineEndings(newContent);
+
+@cli.command("generate-version")
+def generate_version() -> int:
+ # Detect package type
+ click.echo(gen_version())
+ return 0
+
+
+@cli.command("generate-matrix")
+@click.option(
+ "--directory", type=click.Path(exists=True, path_type=Path), default=Path.cwd()
+)
+@click.option("--npm", is_flag=True, default=False)
+@click.option("--pypi", is_flag=True, default=False)
+@click.argument("git_hash", type=GIT_HASH)
+def generate_matrix(directory: Path, git_hash: GitHash, pypi: bool, npm: bool) -> int:
```
-This interface is important because it defines how MCP Servers Tutorial: Reference Implementations and Patterns implements the patterns covered in this chapter.
-
-### `src/filesystem/lib.ts`
-
-The `SearchResult` interface in [`src/filesystem/lib.ts`](https://github.com/modelcontextprotocol/servers/blob/HEAD/src/filesystem/lib.ts) handles a key part of this chapter's functionality:
-
-```ts
-}
-
-export interface SearchResult {
- path: string;
- isDirectory: boolean;
-}
-
-// Pure Utility Functions
-export function formatSize(bytes: number): string {
- const units = ['B', 'KB', 'MB', 'GB', 'TB'];
- if (bytes === 0) return '0 B';
-
- const i = Math.floor(Math.log(bytes) / Math.log(1024));
-
- if (i < 0 || i === 0) return `${bytes} ${units[0]}`;
-
- const unitIndex = Math.min(i, units.length - 1);
- return `${(bytes / Math.pow(1024, unitIndex)).toFixed(2)} ${units[unitIndex]}`;
-}
-
-export function normalizeLineEndings(text: string): string {
- return text.replace(/\r\n/g, '\n');
-}
-
-export function createUnifiedDiff(originalContent: string, newContent: string, filepath: string = 'file'): string {
- // Ensure consistent line endings for diff
- const normalizedOriginal = normalizeLineEndings(originalContent);
- const normalizedNew = normalizeLineEndings(newContent);
-
- return createTwoFilesPatch(
- filepath,
- filepath,
+This function is important because it defines how MCP Servers Tutorial: Reference Implementations and Patterns implements the patterns covered in this chapter.
+
+### `scripts/release.py`
+
+The `generate_version` function in [`scripts/release.py`](https://github.com/modelcontextprotocol/servers/blob/HEAD/scripts/release.py) handles a key part of this chapter's functionality:
+
+```py
+
+@cli.command("generate-version")
+def generate_version() -> int:
+ # Detect package type
+ click.echo(gen_version())
+ return 0
+
+
+@cli.command("generate-matrix")
+@click.option(
+ "--directory", type=click.Path(exists=True, path_type=Path), default=Path.cwd()
+)
+@click.option("--npm", is_flag=True, default=False)
+@click.option("--pypi", is_flag=True, default=False)
+@click.argument("git_hash", type=GIT_HASH)
+def generate_matrix(directory: Path, git_hash: GitHash, pypi: bool, npm: bool) -> int:
+ # Detect package type
+ path = directory.resolve(strict=True)
+ version = gen_version()
+
+ changes = []
+ for package in find_changed_packages(path, git_hash):
+ pkg = package.path.relative_to(path)
+ if npm and isinstance(package, NpmPackage):
+ changes.append(str(pkg))
+ if pypi and isinstance(package, PyPiPackage):
+ changes.append(str(pkg))
+
+ click.echo(json.dumps(changes))
+ return 0
+
+
```
-This interface is important because it defines how MCP Servers Tutorial: Reference Implementations and Patterns implements the patterns covered in this chapter.
+This function is important because it defines how MCP Servers Tutorial: Reference Implementations and Patterns implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[search]
- B[FileInfo]
- C[SearchOptions]
- D[SearchResult]
- E[FileEdit]
+ A[cli]
+ B[update_packages]
+ C[generate_notes]
+ D[generate_version]
+ E[generate_matrix]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-servers-tutorial/07-security-considerations.md b/tutorials/mcp-servers-tutorial/07-security-considerations.md
index b075c01e..b59d57f6 100644
--- a/tutorials/mcp-servers-tutorial/07-security-considerations.md
+++ b/tutorials/mcp-servers-tutorial/07-security-considerations.md
@@ -107,168 +107,156 @@ Suggested trace strategy:
- [Main Catalog](../../README.md#-tutorial-catalog)
- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/filesystem/index.ts`
+### `src/filesystem/path-utils.ts`
-The `updateAllowedDirectoriesFromRoots` function in [`src/filesystem/index.ts`](https://github.com/modelcontextprotocol/servers/blob/HEAD/src/filesystem/index.ts) handles a key part of this chapter's functionality:
+The `expandHome` function in [`src/filesystem/path-utils.ts`](https://github.com/modelcontextprotocol/servers/blob/HEAD/src/filesystem/path-utils.ts) handles a key part of this chapter's functionality:
```ts
-
-// Updates allowed directories based on MCP client roots
-async function updateAllowedDirectoriesFromRoots(requestedRoots: Root[]) {
- const validatedRootDirs = await getValidRootDirectories(requestedRoots);
- if (validatedRootDirs.length > 0) {
- allowedDirectories = [...validatedRootDirs];
- setAllowedDirectories(allowedDirectories); // Update the global state in lib.ts
- console.error(`Updated allowed directories from MCP roots: ${validatedRootDirs.length} valid directories`);
- } else {
- console.error("No valid root directories provided by client");
+ * @returns Expanded path
+ */
+export function expandHome(filepath: string): string {
+ if (filepath.startsWith('~/') || filepath === '~') {
+ return path.join(os.homedir(), filepath.slice(1));
}
+ return filepath;
}
-// Handles dynamic roots updates during runtime, when client sends "roots/list_changed" notification, server fetches the updated roots and replaces all allowed directories with the new roots.
-server.server.setNotificationHandler(RootsListChangedNotificationSchema, async () => {
- try {
- // Request the updated roots list from the client
- const response = await server.server.listRoots();
- if (response && 'roots' in response) {
- await updateAllowedDirectoriesFromRoots(response.roots);
- }
- } catch (error) {
- console.error("Failed to request roots from client:", error instanceof Error ? error.message : String(error));
- }
-});
-
-// Handles post-initialization setup, specifically checking for and fetching MCP roots.
-server.server.oninitialized = async () => {
- const clientCapabilities = server.server.getClientCapabilities();
- if (clientCapabilities?.roots) {
- try {
```
This function is important because it defines how MCP Servers Tutorial: Reference Implementations and Patterns implements the patterns covered in this chapter.
-### `src/filesystem/index.ts`
+### `src/filesystem/roots-utils.ts`
-The `runServer` function in [`src/filesystem/index.ts`](https://github.com/modelcontextprotocol/servers/blob/HEAD/src/filesystem/index.ts) handles a key part of this chapter's functionality:
+The `parseRootUri` function in [`src/filesystem/roots-utils.ts`](https://github.com/modelcontextprotocol/servers/blob/HEAD/src/filesystem/roots-utils.ts) handles a key part of this chapter's functionality:
```ts
-
-// Start server
-async function runServer() {
- const transport = new StdioServerTransport();
- await server.connect(transport);
- console.error("Secure MCP Filesystem Server running on stdio");
- if (allowedDirectories.length === 0) {
- console.error("Started without allowed directories - waiting for client to provide roots via MCP protocol");
+ * @returns Promise resolving to validated path or null if invalid
+ */
+async function parseRootUri(rootUri: string): Promise<string | null> {
+ try {
+ const rawPath = rootUri.startsWith('file://') ? fileURLToPath(rootUri) : rootUri;
+ const expandedPath = rawPath.startsWith('~/') || rawPath === '~'
+ ? path.join(os.homedir(), rawPath.slice(1))
+ : rawPath;
+ const absolutePath = path.resolve(expandedPath);
+ const resolvedPath = await fs.realpath(absolutePath);
+ return normalizePath(resolvedPath);
+ } catch {
+ return null; // Path doesn't exist or other error
}
}
-runServer().catch((error) => {
- console.error("Fatal error running server:", error);
- process.exit(1);
-});
+/**
+ * Formats error message for directory validation failures.
+ * @param dir - Directory path that failed validation
+ * @param error - Error that occurred during validation
+ * @param reason - Specific reason for failure
+ * @returns Formatted error message
+ */
+function formatDirectoryError(dir: string, error?: unknown, reason?: string): string {
+ if (reason) {
+ return `Skipping ${reason}: ${dir}`;
+ }
+ const message = error instanceof Error ? error.message : String(error);
+ return `Skipping invalid directory: ${dir} due to error: ${message}`;
+}
+/**
```
This function is important because it defines how MCP Servers Tutorial: Reference Implementations and Patterns implements the patterns covered in this chapter.
-### `src/filesystem/index.ts`
+### `src/filesystem/roots-utils.ts`
-The `TreeEntry` interface in [`src/filesystem/index.ts`](https://github.com/modelcontextprotocol/servers/blob/HEAD/src/filesystem/index.ts) handles a key part of this chapter's functionality:
+The `formatDirectoryError` function in [`src/filesystem/roots-utils.ts`](https://github.com/modelcontextprotocol/servers/blob/HEAD/src/filesystem/roots-utils.ts) handles a key part of this chapter's functionality:
```ts
- },
- async (args: z.infer<typeof DirectoryTreeArgsSchema>) => {
- interface TreeEntry {
- name: string;
- type: 'file' | 'directory';
- children?: TreeEntry[];
+ * @returns Formatted error message
+ */
+function formatDirectoryError(dir: string, error?: unknown, reason?: string): string {
+ if (reason) {
+ return `Skipping ${reason}: ${dir}`;
+ }
+ const message = error instanceof Error ? error.message : String(error);
+ return `Skipping invalid directory: ${dir} due to error: ${message}`;
+}
+
+/**
+ * Resolves requested root directories from MCP root specifications.
+ *
+ * Converts root URI specifications (file:// URIs or plain paths) into normalized
+ * directory paths, validating that each path exists and is a directory.
+ * Includes symlink resolution for security.
+ *
+ * @param requestedRoots - Array of root specifications with URI and optional name
+ * @returns Promise resolving to array of validated directory paths
+ */
+export async function getValidRootDirectories(
+ requestedRoots: readonly Root[]
+): Promise<string[]> {
+ const validatedDirectories: string[] = [];
+
+ for (const requestedRoot of requestedRoots) {
+ const resolvedPath = await parseRootUri(requestedRoot.uri);
+ if (!resolvedPath) {
+ console.error(formatDirectoryError(requestedRoot.uri, undefined, 'invalid path or inaccessible'));
+ continue;
}
- const rootPath = args.path;
-
- async function buildTree(currentPath: string, excludePatterns: string[] = []): Promise<TreeEntry[]> {
- const validPath = await validatePath(currentPath);
- const entries = await fs.readdir(validPath, { withFileTypes: true });
- const result: TreeEntry[] = [];
-
- for (const entry of entries) {
- const relativePath = path.relative(rootPath, path.join(currentPath, entry.name));
- const shouldExclude = excludePatterns.some(pattern => {
- if (pattern.includes('*')) {
- return minimatch(relativePath, pattern, { dot: true });
- }
- // For files: match exact name or as part of path
- // For directories: match as directory path
- return minimatch(relativePath, pattern, { dot: true }) ||
- minimatch(relativePath, `**/${pattern}`, { dot: true }) ||
- minimatch(relativePath, `**/${pattern}/**`, { dot: true });
- });
- if (shouldExclude)
- continue;
-
- const entryData: TreeEntry = {
- name: entry.name,
- type: entry.isDirectory() ? 'directory' : 'file'
+
```
-This interface is important because it defines how MCP Servers Tutorial: Reference Implementations and Patterns implements the patterns covered in this chapter.
+This function is important because it defines how MCP Servers Tutorial: Reference Implementations and Patterns implements the patterns covered in this chapter.
-### `src/sequentialthinking/lib.ts`
+### `src/filesystem/roots-utils.ts`
-The `SequentialThinkingServer` class in [`src/sequentialthinking/lib.ts`](https://github.com/modelcontextprotocol/servers/blob/HEAD/src/sequentialthinking/lib.ts) handles a key part of this chapter's functionality:
+The `getValidRootDirectories` function in [`src/filesystem/roots-utils.ts`](https://github.com/modelcontextprotocol/servers/blob/HEAD/src/filesystem/roots-utils.ts) handles a key part of this chapter's functionality:
```ts
-}
-
-export class SequentialThinkingServer {
- private thoughtHistory: ThoughtData[] = [];
- private branches: Record<string, ThoughtData[]> = {};
- private disableThoughtLogging: boolean;
-
- constructor() {
- this.disableThoughtLogging = (process.env.DISABLE_THOUGHT_LOGGING || "").toLowerCase() === "true";
- }
-
- private formatThought(thoughtData: ThoughtData): string {
- const { thoughtNumber, totalThoughts, thought, isRevision, revisesThought, branchFromThought, branchId } = thoughtData;
-
- let prefix = '';
- let context = '';
-
- if (isRevision) {
- prefix = chalk.yellow('🔄 Revision');
- context = ` (revising thought ${revisesThought})`;
- } else if (branchFromThought) {
- prefix = chalk.green('🌿 Branch');
- context = ` (from thought ${branchFromThought}, ID: ${branchId})`;
- } else {
- prefix = chalk.blue('💭 Thought');
- context = '';
+ * @returns Promise resolving to array of validated directory paths
+ */
+export async function getValidRootDirectories(
+ requestedRoots: readonly Root[]
+): Promise<string[]> {
+ const validatedDirectories: string[] = [];
+
+ for (const requestedRoot of requestedRoots) {
+ const resolvedPath = await parseRootUri(requestedRoot.uri);
+ if (!resolvedPath) {
+ console.error(formatDirectoryError(requestedRoot.uri, undefined, 'invalid path or inaccessible'));
+ continue;
}
-
- const header = `${prefix} ${thoughtNumber}/${totalThoughts}${context}`;
- const border = '─'.repeat(Math.max(header.length, thought.length) + 4);
-
- return `
+
+ try {
+ const stats: Stats = await fs.stat(resolvedPath);
+ if (stats.isDirectory()) {
+ validatedDirectories.push(resolvedPath);
+ } else {
+ console.error(formatDirectoryError(resolvedPath, undefined, 'non-directory root'));
+ }
+ } catch (error) {
+ console.error(formatDirectoryError(resolvedPath, error));
+ }
+ }
+
+ return validatedDirectories;
+}
```
-This class is important because it defines how MCP Servers Tutorial: Reference Implementations and Patterns implements the patterns covered in this chapter.
+This function is important because it defines how MCP Servers Tutorial: Reference Implementations and Patterns implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[updateAllowedDirectoriesFromRoots]
- B[runServer]
- C[TreeEntry]
- D[SequentialThinkingServer]
- E[ThoughtData]
+ A[expandHome]
+ B[parseRootUri]
+ C[formatDirectoryError]
+ D[getValidRootDirectories]
+ E[SequentialThinkingServer]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-servers-tutorial/08-production-adaptation.md b/tutorials/mcp-servers-tutorial/08-production-adaptation.md
index 1d8c0a41..c5a88072 100644
--- a/tutorials/mcp-servers-tutorial/08-production-adaptation.md
+++ b/tutorials/mcp-servers-tutorial/08-production-adaptation.md
@@ -113,29 +113,8 @@ Suggested trace strategy:
- [Main Catalog](../../README.md#-tutorial-catalog)
- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/filesystem/path-utils.ts`
-
-The `expandHome` function in [`src/filesystem/path-utils.ts`](https://github.com/modelcontextprotocol/servers/blob/HEAD/src/filesystem/path-utils.ts) handles a key part of this chapter's functionality:
-
-```ts
- * @returns Expanded path
- */
-export function expandHome(filepath: string): string {
- if (filepath.startsWith('~/') || filepath === '~') {
- return path.join(os.homedir(), filepath.slice(1));
- }
- return filepath;
-}
-
-
-```
-
-This function is important because it defines how MCP Servers Tutorial: Reference Implementations and Patterns implements the patterns covered in this chapter.
-
### `src/everything/index.ts`
The `run` function in [`src/everything/index.ts`](https://github.com/modelcontextprotocol/servers/blob/HEAD/src/everything/index.ts) handles a key part of this chapter's functionality:
@@ -177,84 +156,125 @@ async function run() {
This function is important because it defines how MCP Servers Tutorial: Reference Implementations and Patterns implements the patterns covered in this chapter.
-### `src/filesystem/roots-utils.ts`
+### `src/filesystem/index.ts`
-The `parseRootUri` function in [`src/filesystem/roots-utils.ts`](https://github.com/modelcontextprotocol/servers/blob/HEAD/src/filesystem/roots-utils.ts) handles a key part of this chapter's functionality:
+The `readFileAsBase64Stream` function in [`src/filesystem/index.ts`](https://github.com/modelcontextprotocol/servers/blob/HEAD/src/filesystem/index.ts) handles a key part of this chapter's functionality:
```ts
- * @returns Promise resolving to validated path or null if invalid
- */
-async function parseRootUri(rootUri: string): Promise<string | null> {
- try {
- const rawPath = rootUri.startsWith('file://') ? fileURLToPath(rootUri) : rootUri;
- const expandedPath = rawPath.startsWith('~/') || rawPath === '~'
- ? path.join(os.homedir(), rawPath.slice(1))
- : rawPath;
- const absolutePath = path.resolve(expandedPath);
- const resolvedPath = await fs.realpath(absolutePath);
- return normalizePath(resolvedPath);
- } catch {
- return null; // Path doesn't exist or other error
- }
+// the result to a Base64 string. This is a memory-efficient way to handle
+// binary data from a stream before the final encoding.
+async function readFileAsBase64Stream(filePath: string): Promise<string> {
+ return new Promise((resolve, reject) => {
+ const stream = createReadStream(filePath);
+ const chunks: Buffer[] = [];
+ stream.on('data', (chunk) => {
+ chunks.push(chunk as Buffer);
+ });
+ stream.on('end', () => {
+ const finalBuffer = Buffer.concat(chunks);
+ resolve(finalBuffer.toString('base64'));
+ });
+ stream.on('error', (err) => reject(err));
+ });
}
-/**
- * Formats error message for directory validation failures.
- * @param dir - Directory path that failed validation
- * @param error - Error that occurred during validation
- * @param reason - Specific reason for failure
- * @returns Formatted error message
- */
-function formatDirectoryError(dir: string, error?: unknown, reason?: string): string {
- if (reason) {
- return `Skipping ${reason}: ${dir}`;
+// Tool registrations
+
+// read_file (deprecated) and read_text_file
+const readTextFileHandler = async (args: z.infer<typeof ReadTextFileArgsSchema>) => {
+ const validPath = await validatePath(args.path);
+
+ if (args.head && args.tail) {
+ throw new Error("Cannot specify both head and tail parameters simultaneously");
}
- const message = error instanceof Error ? error.message : String(error);
- return `Skipping invalid directory: ${dir} due to error: ${message}`;
-}
-/**
+ let content: string;
+ if (args.tail) {
+ content = await tailFile(validPath, args.tail);
+ } else if (args.head) {
+ content = await headFile(validPath, args.head);
```
This function is important because it defines how MCP Servers Tutorial: Reference Implementations and Patterns implements the patterns covered in this chapter.
-### `src/filesystem/roots-utils.ts`
+### `src/filesystem/index.ts`
-The `formatDirectoryError` function in [`src/filesystem/roots-utils.ts`](https://github.com/modelcontextprotocol/servers/blob/HEAD/src/filesystem/roots-utils.ts) handles a key part of this chapter's functionality:
+The `buildTree` function in [`src/filesystem/index.ts`](https://github.com/modelcontextprotocol/servers/blob/HEAD/src/filesystem/index.ts) handles a key part of this chapter's functionality:
```ts
- * @returns Formatted error message
- */
-function formatDirectoryError(dir: string, error?: unknown, reason?: string): string {
- if (reason) {
- return `Skipping ${reason}: ${dir}`;
+ const rootPath = args.path;
+
+ async function buildTree(currentPath: string, excludePatterns: string[] = []): Promise<TreeEntry[]> {
+ const validPath = await validatePath(currentPath);
+ const entries = await fs.readdir(validPath, { withFileTypes: true });
+ const result: TreeEntry[] = [];
+
+ for (const entry of entries) {
+ const relativePath = path.relative(rootPath, path.join(currentPath, entry.name));
+ const shouldExclude = excludePatterns.some(pattern => {
+ if (pattern.includes('*')) {
+ return minimatch(relativePath, pattern, { dot: true });
+ }
+ // For files: match exact name or as part of path
+ // For directories: match as directory path
+ return minimatch(relativePath, pattern, { dot: true }) ||
+ minimatch(relativePath, `**/${pattern}`, { dot: true }) ||
+ minimatch(relativePath, `**/${pattern}/**`, { dot: true });
+ });
+ if (shouldExclude)
+ continue;
+
+ const entryData: TreeEntry = {
+ name: entry.name,
+ type: entry.isDirectory() ? 'directory' : 'file'
+ };
+
+ if (entry.isDirectory()) {
+ const subPath = path.join(currentPath, entry.name);
+ entryData.children = await buildTree(subPath, excludePatterns);
+ }
+
+```
+
+This function is important because it defines how MCP Servers Tutorial: Reference Implementations and Patterns implements the patterns covered in this chapter.
+
+### `src/filesystem/index.ts`
+
+The `updateAllowedDirectoriesFromRoots` function in [`src/filesystem/index.ts`](https://github.com/modelcontextprotocol/servers/blob/HEAD/src/filesystem/index.ts) handles a key part of this chapter's functionality:
+
+```ts
+
+// Updates allowed directories based on MCP client roots
+async function updateAllowedDirectoriesFromRoots(requestedRoots: Root[]) {
+ const validatedRootDirs = await getValidRootDirectories(requestedRoots);
+ if (validatedRootDirs.length > 0) {
+ allowedDirectories = [...validatedRootDirs];
+ setAllowedDirectories(allowedDirectories); // Update the global state in lib.ts
+ console.error(`Updated allowed directories from MCP roots: ${validatedRootDirs.length} valid directories`);
+ } else {
+ console.error("No valid root directories provided by client");
}
- const message = error instanceof Error ? error.message : String(error);
- return `Skipping invalid directory: ${dir} due to error: ${message}`;
}
-/**
- * Resolves requested root directories from MCP root specifications.
- *
- * Converts root URI specifications (file:// URIs or plain paths) into normalized
- * directory paths, validating that each path exists and is a directory.
- * Includes symlink resolution for security.
- *
- * @param requestedRoots - Array of root specifications with URI and optional name
- * @returns Promise resolving to array of validated directory paths
- */
-export async function getValidRootDirectories(
- requestedRoots: readonly Root[]
-): Promise<string[]> {
- const validatedDirectories: string[] = [];
-
- for (const requestedRoot of requestedRoots) {
- const resolvedPath = await parseRootUri(requestedRoot.uri);
- if (!resolvedPath) {
- console.error(formatDirectoryError(requestedRoot.uri, undefined, 'invalid path or inaccessible'));
- continue;
+// Handles dynamic roots updates during runtime, when client sends "roots/list_changed" notification, server fetches the updated roots and replaces all allowed directories with the new roots.
+server.server.setNotificationHandler(RootsListChangedNotificationSchema, async () => {
+ try {
+ // Request the updated roots list from the client
+ const response = await server.server.listRoots();
+ if (response && 'roots' in response) {
+ await updateAllowedDirectoriesFromRoots(response.roots);
}
-
+ } catch (error) {
+ console.error("Failed to request roots from client:", error instanceof Error ? error.message : String(error));
+ }
+});
+
+// Handles post-initialization setup, specifically checking for and fetching MCP roots.
+server.server.oninitialized = async () => {
+ const clientCapabilities = server.server.getClientCapabilities();
+
+ if (clientCapabilities?.roots) {
+ try {
```
This function is important because it defines how MCP Servers Tutorial: Reference Implementations and Patterns implements the patterns covered in this chapter.
@@ -264,11 +284,11 @@ This function is important because it defines how MCP Servers Tutorial: Referenc
```mermaid
flowchart TD
- A[expandHome]
- B[run]
- C[parseRootUri]
- D[formatDirectoryError]
- E[getValidRootDirectories]
+ A[run]
+ B[readFileAsBase64Stream]
+ C[buildTree]
+ D[updateAllowedDirectoriesFromRoots]
+ E[runServer]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-specification-tutorial/01-getting-started-and-version-navigation.md b/tutorials/mcp-specification-tutorial/01-getting-started-and-version-navigation.md
index 0a2e0b70..589a9ae1 100644
--- a/tutorials/mcp-specification-tutorial/01-getting-started-and-version-navigation.md
+++ b/tutorials/mcp-specification-tutorial/01-getting-started-and-version-navigation.md
@@ -47,170 +47,168 @@ You now have a revision-first process that keeps implementation decisions aligne
Next: [Chapter 2: Architecture and Capability Negotiation](02-architecture-and-capability-negotiation.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `scripts/generate-schemas.ts`
+### `migrate_seps.js`
-The `applyJsonSchema202012Transformations` function in [`scripts/generate-schemas.ts`](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/HEAD/scripts/generate-schemas.ts) handles a key part of this chapter's functionality:
+The `fetchSEPIssues` function in [`migrate_seps.js`](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/HEAD/migrate_seps.js) handles a key part of this chapter's functionality:
-```ts
- * Apply JSON Schema 2020-12 transformations to a schema file
- */
-function applyJsonSchema202012Transformations(schemaPath: string): void {
- let content = readFileSync(schemaPath, 'utf-8');
+```js
- // Replace $schema URL
- content = content.replace(
- /http:\/\/json-schema\.org\/draft-07\/schema#/g,
- 'https://json-schema.org/draft/2020-12/schema'
- );
+// Fetch all SEP issues from GitHub
+function fetchSEPIssues() {
+ console.log('Fetching SEP issues from GitHub...');
- // Replace "definitions": with "$defs":
- content = content.replace(
- /"definitions":/g,
- '"$defs":'
+ const result = execSync(
+ 'gh issue list --label SEP --state all --limit 500 --json number,title,state,labels,body,createdAt,closedAt,author',
+ { encoding: 'utf-8' }
);
- // Replace #/definitions/ with #/$defs/
- content = content.replace(
- /#\/definitions\//g,
- '#/$defs/'
- );
+ return JSON.parse(result);
+}
- writeFileSync(schemaPath, content, 'utf-8');
+// Determine SEP status from labels
+function getStatusFromLabels(labels) {
+ const labelNames = labels.map(l => l.name.toLowerCase());
+
+ // Check for status labels in priority order
+ if (labelNames.includes('final')) return 'Final';
+ if (labelNames.includes('accepted-with-changes')) return 'Accepted';
+ if (labelNames.includes('accepted')) return 'Accepted';
+ if (labelNames.includes('in-review')) return 'In-Review';
+ if (labelNames.includes('draft')) return 'Draft';
+ if (labelNames.includes('proposal')) return 'Draft';
+
+ return null;
}
-/**
- * Generate JSON schema for a specific version
- */
-async function generateSchema(version: string, check: boolean = false): Promise<boolean> {
- const schemaDir = join('schema', version);
- const schemaTs = join(schemaDir, 'schema.ts');
+// Check if issue should be migrated (has accepted, accepted-with-changes, or final status)
+function shouldMigrate(issue) {
+ const status = getStatusFromLabels(issue.labels);
+ return status && ['Accepted', 'Final'].includes(status);
```
This function is important because it defines how MCP Specification Tutorial: Designing Production-Grade MCP Clients and Servers From the Source of Truth implements the patterns covered in this chapter.
-### `scripts/generate-schemas.ts`
-
-The `generateSchema` function in [`scripts/generate-schemas.ts`](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/HEAD/scripts/generate-schemas.ts) handles a key part of this chapter's functionality:
-
-```ts
- * Generate JSON schema for a specific version
- */
-async function generateSchema(version: string, check: boolean = false): Promise<boolean> {
- const schemaDir = join('schema', version);
- const schemaTs = join(schemaDir, 'schema.ts');
- const schemaJson = join(schemaDir, 'schema.json');
-
- if (check) {
- // Read existing schema
- const existingSchema = readFileSync(schemaJson, 'utf-8');
-
- // Generate schema to stdout and capture it
- try {
- const { stdout: generated } = await execAsync(
- `npx typescript-json-schema --defaultNumberType integer --required --skipLibCheck "${schemaTs}" "*"`
- );
-
- let expectedSchema = generated;
-
- // Apply transformations for non-legacy schemas
- if (!LEGACY_SCHEMAS.includes(version)) {
- expectedSchema = expectedSchema.replace(
- /http:\/\/json-schema\.org\/draft-07\/schema#/g,
- 'https://json-schema.org/draft/2020-12/schema'
- );
- expectedSchema = expectedSchema.replace(/"definitions":/g, '"$defs":');
- expectedSchema = expectedSchema.replace(/#\/definitions\//g, '#/$defs/');
- }
-
- // Compare
- if (existingSchema.trim() !== expectedSchema.trim()) {
- console.error(` ✗ Schema ${version} is out of date!`);
-```
+### `migrate_seps.js`
-This function is important because it defines how MCP Specification Tutorial: Designing Production-Grade MCP Clients and Servers From the Source of Truth implements the patterns covered in this chapter.
+The `getStatusFromLabels` function in [`migrate_seps.js`](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/HEAD/migrate_seps.js) handles a key part of this chapter's functionality:
-### `scripts/generate-schemas.ts`
+```js
-The `main` function in [`scripts/generate-schemas.ts`](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/HEAD/scripts/generate-schemas.ts) handles a key part of this chapter's functionality:
+// Determine SEP status from labels
+function getStatusFromLabels(labels) {
+ const labelNames = labels.map(l => l.name.toLowerCase());
-```ts
-const execAsync = promisify(exec);
+ // Check for status labels in priority order
+ if (labelNames.includes('final')) return 'Final';
+ if (labelNames.includes('accepted-with-changes')) return 'Accepted';
+ if (labelNames.includes('accepted')) return 'Accepted';
+ if (labelNames.includes('in-review')) return 'In-Review';
+ if (labelNames.includes('draft')) return 'Draft';
+ if (labelNames.includes('proposal')) return 'Draft';
-// Legacy schema versions that should remain as JSON Schema draft-07
-const LEGACY_SCHEMAS = ['2024-11-05', '2025-03-26', '2025-06-18'];
+ return null;
+}
-// Modern schema versions that use JSON Schema 2020-12
-const MODERN_SCHEMAS = ['2025-11-25', 'draft'];
+// Check if issue should be migrated (has accepted, accepted-with-changes, or final status)
+function shouldMigrate(issue) {
+ const status = getStatusFromLabels(issue.labels);
+ return status && ['Accepted', 'Final'].includes(status);
+}
-// All schema versions to generate
-const ALL_SCHEMAS = [...LEGACY_SCHEMAS, ...MODERN_SCHEMAS];
+// Extract metadata from issue body
+function parseIssueBody(body, issue) {
+ if (!body) return null;
-// Check if we're in check mode (validate existing schemas match generated ones)
-const CHECK_MODE = process.argv.includes('--check');
+ const metadata = {
+ title: issue.title.replace(/^\[?SEP-\d+\]?:?\s*/i, ''),
+ status: getStatusFromLabels(issue.labels),
+ type: 'Standards Track',
+ created: issue.createdAt ? issue.createdAt.split('T')[0] : new Date().toISOString().split('T')[0],
+ author: issue.author ? issue.author.login : 'Unknown',
+```
-/**
- * Apply JSON Schema 2020-12 transformations to a schema file
- */
-function applyJsonSchema202012Transformations(schemaPath: string): void {
- let content = readFileSync(schemaPath, 'utf-8');
+This function is important because it defines how MCP Specification Tutorial: Designing Production-Grade MCP Clients and Servers From the Source of Truth implements the patterns covered in this chapter.
- // Replace $schema URL
- content = content.replace(
- /http:\/\/json-schema\.org\/draft-07\/schema#/g,
- 'https://json-schema.org/draft/2020-12/schema'
- );
+### `migrate_seps.js`
- // Replace "definitions": with "$defs":
- content = content.replace(
- /"definitions":/g,
- '"$defs":'
- );
+The `shouldMigrate` function in [`migrate_seps.js`](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/HEAD/migrate_seps.js) handles a key part of this chapter's functionality:
+```js
+
+// Check if issue should be migrated (has accepted, accepted-with-changes, or final status)
+function shouldMigrate(issue) {
+ const status = getStatusFromLabels(issue.labels);
+ return status && ['Accepted', 'Final'].includes(status);
+}
+
+// Extract metadata from issue body
+function parseIssueBody(body, issue) {
+ if (!body) return null;
+
+ const metadata = {
+ title: issue.title.replace(/^\[?SEP-\d+\]?:?\s*/i, ''),
+ status: getStatusFromLabels(issue.labels),
+ type: 'Standards Track',
+ created: issue.createdAt ? issue.createdAt.split('T')[0] : new Date().toISOString().split('T')[0],
+ author: issue.author ? issue.author.login : 'Unknown',
+ sponsor: null,
+ pr: null
+ };
+
+ // Try to extract metadata from the body
+ const lines = body.split('\n');
+
+ for (const line of lines) {
+ const trimmed = line.trim();
+
+ // Extract type
+ if (trimmed.match(/\*?\*?Type\*?\*?:/i)) {
+ const match = trimmed.match(/Type\*?\*?:\s*(.+)/i);
+ if (match) metadata.type = match[1].trim();
+ }
```
This function is important because it defines how MCP Specification Tutorial: Designing Production-Grade MCP Clients and Servers From the Source of Truth implements the patterns covered in this chapter.
-### `scripts/render-seps.ts`
-
-The `parseSEPMetadata` function in [`scripts/render-seps.ts`](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/HEAD/scripts/render-seps.ts) handles a key part of this chapter's functionality:
-
-```ts
- * Parse SEP metadata from markdown content
- */
-function parseSEPMetadata(content: string, filename: string): SEPMetadata | null {
- // Skip template and README files
- if (filename === "TEMPLATE.md" || filename === "README.md") {
- return null;
- }
-
- // Extract SEP number and slug from filename (e.g., "1850-pr-based-sep-workflow.md")
- const filenameMatch = filename.match(/^(\d+)-(.+)\.md$/);
- if (!filenameMatch) {
- // Skip files that don't match SEP naming convention (like 0000-*.md drafts)
- if (filename.match(/^0000-/)) {
- return null;
+### `migrate_seps.js`
+
+The `parseIssueBody` function in [`migrate_seps.js`](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/HEAD/migrate_seps.js) handles a key part of this chapter's functionality:
+
+```js
+
+// Extract metadata from issue body
+function parseIssueBody(body, issue) {
+ if (!body) return null;
+
+ const metadata = {
+ title: issue.title.replace(/^\[?SEP-\d+\]?:?\s*/i, ''),
+ status: getStatusFromLabels(issue.labels),
+ type: 'Standards Track',
+ created: issue.createdAt ? issue.createdAt.split('T')[0] : new Date().toISOString().split('T')[0],
+ author: issue.author ? issue.author.login : 'Unknown',
+ sponsor: null,
+ pr: null
+ };
+
+ // Try to extract metadata from the body
+ const lines = body.split('\n');
+
+ for (const line of lines) {
+ const trimmed = line.trim();
+
+ // Extract type
+ if (trimmed.match(/\*?\*?Type\*?\*?:/i)) {
+ const match = trimmed.match(/Type\*?\*?:\s*(.+)/i);
+ if (match) metadata.type = match[1].trim();
+ }
+
+ // Extract author(s)
+ if (trimmed.match(/\*?\*?Authors?\*?\*?:/i)) {
+ const match = trimmed.match(/Authors?\*?\*?:\s*(.+)/i);
+ if (match) metadata.author = match[1].trim();
}
- console.warn(`Warning: Skipping ${filename} - doesn't match SEP naming convention`);
- return null;
- }
-
- const [, number, slug] = filenameMatch;
-
- // Parse title from first heading
- const titleMatch = content.match(/^#\s+SEP-\d+:\s+(.+)$/m);
- const title = titleMatch ? titleMatch[1].trim() : "Untitled";
-
- // Parse metadata fields using regex
- const statusMatch = content.match(/^\s*-\s*\*\*Status\*\*:\s*(.+)$/m);
- const typeMatch = content.match(/^\s*-\s*\*\*Type\*\*:\s*(.+)$/m);
- const createdMatch = content.match(/^\s*-\s*\*\*Created\*\*:\s*(.+)$/m);
- const acceptedMatch = content.match(/^\s*-\s*\*\*Accepted\*\*:\s*(.+)$/m);
- const authorsMatch = content.match(/^\s*-\s*\*\*Author\(s\)\*\*:\s*(.+)$/m);
- const sponsorMatch = content.match(/^\s*-\s*\*\*Sponsor\*\*:\s*(.+)$/m);
```
This function is important because it defines how MCP Specification Tutorial: Designing Production-Grade MCP Clients and Servers From the Source of Truth implements the patterns covered in this chapter.
@@ -220,11 +218,11 @@ This function is important because it defines how MCP Specification Tutorial: De
```mermaid
flowchart TD
- A[applyJsonSchema202012Transformations]
- B[generateSchema]
- C[main]
- D[parseSEPMetadata]
- E[formatAuthors]
+ A[fetchSEPIssues]
+ B[getStatusFromLabels]
+ C[shouldMigrate]
+ D[parseIssueBody]
+ E[cleanBodyContent]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-specification-tutorial/02-architecture-and-capability-negotiation.md b/tutorials/mcp-specification-tutorial/02-architecture-and-capability-negotiation.md
index 6a711320..85d898eb 100644
--- a/tutorials/mcp-specification-tutorial/02-architecture-and-capability-negotiation.md
+++ b/tutorials/mcp-specification-tutorial/02-architecture-and-capability-negotiation.md
@@ -57,104 +57,95 @@ You now have an architectural model that prevents capability confusion and keeps
Next: [Chapter 3: Base Protocol Messages and Schema Contracts](03-base-protocol-messages-and-schema-contracts.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `schema/2025-06-18/schema.ts`
-The `JSONRPCError` interface in [`schema/2025-06-18/schema.ts`](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/HEAD/schema/2025-06-18/schema.ts) handles a key part of this chapter's functionality:
+The `InitializeResult` interface in [`schema/2025-06-18/schema.ts`](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/HEAD/schema/2025-06-18/schema.ts) handles a key part of this chapter's functionality:
```ts
- | JSONRPCNotification
- | JSONRPCResponse
- | JSONRPCError;
+ * @category `initialize`
+ */
+export interface InitializeResult extends Result {
+ /**
+ * The version of the Model Context Protocol that the server wants to use. This may not match the version that the client requested. If the client cannot support this version, it MUST disconnect.
+ */
+ protocolVersion: string;
+ capabilities: ServerCapabilities;
+ serverInfo: Implementation;
-/** @internal */
-export const LATEST_PROTOCOL_VERSION = "2025-06-18";
-/** @internal */
-export const JSONRPC_VERSION = "2.0";
+ /**
+ * Instructions describing how to use the server and its features.
+ *
+ * This can be used by clients to improve the LLM's understanding of available tools, resources, etc. It can be thought of like a "hint" to the model. For example, this information MAY be added to the system prompt.
+ */
+ instructions?: string;
+}
/**
- * A progress token, used to associate progress notifications with the original request.
+ * This notification is sent from the client to the server after initialization has finished.
*
- * @category Common Types
+ * @category `notifications/initialized`
*/
-export type ProgressToken = string | number;
+export interface InitializedNotification extends Notification {
+ method: "notifications/initialized";
+}
/**
- * An opaque token used to represent a cursor for pagination.
+ * Capabilities a client may support. Known capabilities are defined here, in this schema, but this is not a closed set: any client can define its own, additional capabilities.
*
- * @category Common Types
+ * @category `initialize`
*/
-export type Cursor = string;
-
-/** @internal */
-export interface Request {
- method: string;
- params?: {
- /**
- * See [General fields: `_meta`](/specification/2025-06-18/basic/index#meta) for notes on `_meta` usage.
- */
- _meta?: {
- /**
```
This interface is important because it defines how MCP Specification Tutorial: Designing Production-Grade MCP Clients and Servers From the Source of Truth implements the patterns covered in this chapter.
### `schema/2025-06-18/schema.ts`
-The `CancelledNotification` interface in [`schema/2025-06-18/schema.ts`](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/HEAD/schema/2025-06-18/schema.ts) handles a key part of this chapter's functionality:
+The `InitializedNotification` interface in [`schema/2025-06-18/schema.ts`](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/HEAD/schema/2025-06-18/schema.ts) handles a key part of this chapter's functionality:
```ts
- * @category `notifications/cancelled`
+ * @category `notifications/initialized`
*/
-export interface CancelledNotification extends Notification {
- method: "notifications/cancelled";
- params: {
- /**
- * The ID of the request to cancel.
- *
- * This MUST correspond to the ID of a request previously issued in the same direction.
- */
- requestId: RequestId;
-
- /**
- * An optional string describing the reason for the cancellation. This MAY be logged or presented to the user.
- */
- reason?: string;
- };
+export interface InitializedNotification extends Notification {
+ method: "notifications/initialized";
}
-/* Initialization */
/**
- * This request is sent from the client to the server when it first connects, asking it to begin initialization.
+ * Capabilities a client may support. Known capabilities are defined here, in this schema, but this is not a closed set: any client can define its own, additional capabilities.
*
* @category `initialize`
*/
-export interface InitializeRequest extends Request {
- method: "initialize";
- params: {
+export interface ClientCapabilities {
+ /**
+ * Experimental, non-standard capabilities that the client supports.
+ */
+ experimental?: { [key: string]: object };
+ /**
+ * Present if the client supports listing roots.
+ */
+ roots?: {
/**
- * The latest version of the Model Context Protocol that the client supports. The client MAY decide to support older versions as well.
+ * Whether the client supports notifications for changes to the roots list.
*/
- protocolVersion: string;
+ listChanged?: boolean;
+ };
+ /**
+ * Present if the client supports sampling from an LLM.
+ */
+ sampling?: object;
+ /**
+ * Present if the client supports elicitation from the server.
+ */
```
This interface is important because it defines how MCP Specification Tutorial: Designing Production-Grade MCP Clients and Servers From the Source of Truth implements the patterns covered in this chapter.
### `schema/2025-06-18/schema.ts`
-The `InitializeRequest` interface in [`schema/2025-06-18/schema.ts`](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/HEAD/schema/2025-06-18/schema.ts) handles a key part of this chapter's functionality:
+The `ClientCapabilities` interface in [`schema/2025-06-18/schema.ts`](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/HEAD/schema/2025-06-18/schema.ts) handles a key part of this chapter's functionality:
```ts
- * @category `initialize`
- */
-export interface InitializeRequest extends Request {
- method: "initialize";
- params: {
- /**
- * The latest version of the Model Context Protocol that the client supports. The client MAY decide to support older versions as well.
*/
protocolVersion: string;
capabilities: ClientCapabilities;
@@ -180,20 +171,22 @@ export interface InitializeResult extends Result {
*
* This can be used by clients to improve the LLM's understanding of available tools, resources, etc. It can be thought of like a "hint" to the model. For example, this information MAY be added to the system prompt.
*/
+ instructions?: string;
+}
+
+/**
+ * This notification is sent from the client to the server after initialization has finished.
+ *
+ * @category `notifications/initialized`
```
This interface is important because it defines how MCP Specification Tutorial: Designing Production-Grade MCP Clients and Servers From the Source of Truth implements the patterns covered in this chapter.
### `schema/2025-06-18/schema.ts`
-The `InitializeResult` interface in [`schema/2025-06-18/schema.ts`](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/HEAD/schema/2025-06-18/schema.ts) handles a key part of this chapter's functionality:
+The `ServerCapabilities` interface in [`schema/2025-06-18/schema.ts`](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/HEAD/schema/2025-06-18/schema.ts) handles a key part of this chapter's functionality:
```ts
- * @category `initialize`
- */
-export interface InitializeResult extends Result {
- /**
- * The version of the Model Context Protocol that the server wants to use. This may not match the version that the client requested. If the client cannot support this version, it MUST disconnect.
*/
protocolVersion: string;
capabilities: ServerCapabilities;
@@ -221,6 +214,11 @@ export interface InitializedNotification extends Notification {
*
* @category `initialize`
*/
+export interface ClientCapabilities {
+ /**
+ * Experimental, non-standard capabilities that the client supports.
+ */
+ experimental?: { [key: string]: object };
```
This interface is important because it defines how MCP Specification Tutorial: Designing Production-Grade MCP Clients and Servers From the Source of Truth implements the patterns covered in this chapter.
@@ -230,11 +228,11 @@ This interface is important because it defines how MCP Specification Tutorial: D
```mermaid
flowchart TD
- A[JSONRPCError]
- B[CancelledNotification]
- C[InitializeRequest]
- D[InitializeResult]
- E[InitializedNotification]
+ A[InitializeResult]
+ B[InitializedNotification]
+ C[ClientCapabilities]
+ D[ServerCapabilities]
+ E[for]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-specification-tutorial/03-base-protocol-messages-and-schema-contracts.md b/tutorials/mcp-specification-tutorial/03-base-protocol-messages-and-schema-contracts.md
index 8101ca1a..386bdebe 100644
--- a/tutorials/mcp-specification-tutorial/03-base-protocol-messages-and-schema-contracts.md
+++ b/tutorials/mcp-specification-tutorial/03-base-protocol-messages-and-schema-contracts.md
@@ -50,170 +50,168 @@ You now have a protocol-contract baseline that reduces cross-client/server seria
Next: [Chapter 4: Transport Model: stdio, Streamable HTTP, and Sessions](04-transport-model-stdio-streamable-http-and-sessions.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `schema/2025-06-18/schema.ts`
-The `Prompt` interface in [`schema/2025-06-18/schema.ts`](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/HEAD/schema/2025-06-18/schema.ts) handles a key part of this chapter's functionality:
+The `ResourceLink` interface in [`schema/2025-06-18/schema.ts`](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/HEAD/schema/2025-06-18/schema.ts) handles a key part of this chapter's functionality:
```ts
-}
-
-/* Prompts */
-/**
- * Sent from the client to request a list of prompts and prompt templates the server has.
- *
- * @category `prompts/list`
+ * @category Content
*/
-export interface ListPromptsRequest extends PaginatedRequest {
- method: "prompts/list";
+export interface ResourceLink extends Resource {
+ type: "resource_link";
}
/**
- * The server's response to a prompts/list request from the client.
+ * The contents of a resource, embedded into a prompt or tool call result.
*
- * @category `prompts/list`
+ * It is up to the client how best to render embedded resources for the benefit
+ * of the LLM and/or the user.
+ *
+ * @category Content
*/
-export interface ListPromptsResult extends PaginatedResult {
- prompts: Prompt[];
-}
+export interface EmbeddedResource {
+ type: "resource";
+ resource: TextResourceContents | BlobResourceContents;
+
+ /**
+ * Optional annotations for the client.
+ */
+ annotations?: Annotations;
+ /**
+ * See [General fields: `_meta`](/specification/2025-06-18/basic/index#meta) for notes on `_meta` usage.
+ */
+ _meta?: { [key: string]: unknown };
+}
/**
- * Used by the client to get a prompt provided by the server.
+ * An optional notification from the server to the client, informing it that the list of prompts it offers has changed. This may be issued by servers without any previous subscription from the client.
*
- * @category `prompts/get`
- */
-export interface GetPromptRequest extends Request {
- method: "prompts/get";
- params: {
- /**
- * The name of the prompt or prompt template.
- */
+ * @category `notifications/prompts/list_changed`
```
This interface is important because it defines how MCP Specification Tutorial: Designing Production-Grade MCP Clients and Servers From the Source of Truth implements the patterns covered in this chapter.
### `schema/2025-06-18/schema.ts`
-The `PromptArgument` interface in [`schema/2025-06-18/schema.ts`](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/HEAD/schema/2025-06-18/schema.ts) handles a key part of this chapter's functionality:
+The `EmbeddedResource` interface in [`schema/2025-06-18/schema.ts`](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/HEAD/schema/2025-06-18/schema.ts) handles a key part of this chapter's functionality:
```ts
- * A list of arguments to use for templating the prompt.
+ * @category Content
+ */
+export interface EmbeddedResource {
+ type: "resource";
+ resource: TextResourceContents | BlobResourceContents;
+
+ /**
+ * Optional annotations for the client.
*/
- arguments?: PromptArgument[];
+ annotations?: Annotations;
/**
* See [General fields: `_meta`](/specification/2025-06-18/basic/index#meta) for notes on `_meta` usage.
*/
_meta?: { [key: string]: unknown };
}
-
/**
- * Describes an argument that a prompt can accept.
+ * An optional notification from the server to the client, informing it that the list of prompts it offers has changed. This may be issued by servers without any previous subscription from the client.
*
- * @category `prompts/list`
+ * @category `notifications/prompts/list_changed`
*/
-export interface PromptArgument extends BaseMetadata {
- /**
- * A human-readable description of the argument.
- */
- description?: string;
- /**
- * Whether this argument must be provided.
- */
- required?: boolean;
+export interface PromptListChangedNotification extends Notification {
+ method: "notifications/prompts/list_changed";
}
+/* Tools */
/**
- * The sender or recipient of messages and data in a conversation.
+ * Sent from the client to request a list of tools the server has.
*
- * @category Common Types
+ * @category `tools/list`
*/
-export type Role = "user" | "assistant";
+export interface ListToolsRequest extends PaginatedRequest {
```
This interface is important because it defines how MCP Specification Tutorial: Designing Production-Grade MCP Clients and Servers From the Source of Truth implements the patterns covered in this chapter.
### `schema/2025-06-18/schema.ts`
-The `PromptMessage` interface in [`schema/2025-06-18/schema.ts`](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/HEAD/schema/2025-06-18/schema.ts) handles a key part of this chapter's functionality:
+The `PromptListChangedNotification` interface in [`schema/2025-06-18/schema.ts`](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/HEAD/schema/2025-06-18/schema.ts) handles a key part of this chapter's functionality:
```ts
- */
- description?: string;
- messages: PromptMessage[];
+ * @category `notifications/prompts/list_changed`
+ */
+export interface PromptListChangedNotification extends Notification {
+ method: "notifications/prompts/list_changed";
}
+/* Tools */
/**
- * A prompt or prompt template that the server offers.
+ * Sent from the client to request a list of tools the server has.
*
- * @category `prompts/list`
+ * @category `tools/list`
*/
-export interface Prompt extends BaseMetadata {
- /**
- * An optional description of what this prompt provides
- */
- description?: string;
- /**
- * A list of arguments to use for templating the prompt.
- */
- arguments?: PromptArgument[];
+export interface ListToolsRequest extends PaginatedRequest {
+ method: "tools/list";
+}
- /**
- * See [General fields: `_meta`](/specification/2025-06-18/basic/index#meta) for notes on `_meta` usage.
- */
- _meta?: { [key: string]: unknown };
+/**
+ * The server's response to a tools/list request from the client.
+ *
+ * @category `tools/list`
+ */
+export interface ListToolsResult extends PaginatedResult {
+ tools: Tool[];
}
/**
- * Describes an argument that a prompt can accept.
+ * The server's response to a tool call.
*
- * @category `prompts/list`
+ * @category `tools/call`
*/
-export interface PromptArgument extends BaseMetadata {
+export interface CallToolResult extends Result {
+ /**
```
This interface is important because it defines how MCP Specification Tutorial: Designing Production-Grade MCP Clients and Servers From the Source of Truth implements the patterns covered in this chapter.
### `schema/2025-06-18/schema.ts`
-The `ResourceLink` interface in [`schema/2025-06-18/schema.ts`](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/HEAD/schema/2025-06-18/schema.ts) handles a key part of this chapter's functionality:
+The `ListToolsRequest` interface in [`schema/2025-06-18/schema.ts`](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/HEAD/schema/2025-06-18/schema.ts) handles a key part of this chapter's functionality:
```ts
- * @category Content
+ * @category `tools/list`
*/
-export interface ResourceLink extends Resource {
- type: "resource_link";
+export interface ListToolsRequest extends PaginatedRequest {
+ method: "tools/list";
}
/**
- * The contents of a resource, embedded into a prompt or tool call result.
+ * The server's response to a tools/list request from the client.
*
- * It is up to the client how best to render embedded resources for the benefit
- * of the LLM and/or the user.
- *
- * @category Content
+ * @category `tools/list`
*/
-export interface EmbeddedResource {
- type: "resource";
- resource: TextResourceContents | BlobResourceContents;
+export interface ListToolsResult extends PaginatedResult {
+ tools: Tool[];
+}
+/**
+ * The server's response to a tool call.
+ *
+ * @category `tools/call`
+ */
+export interface CallToolResult extends Result {
/**
- * Optional annotations for the client.
+ * A list of content objects that represent the unstructured result of the tool call.
*/
- annotations?: Annotations;
+ content: ContentBlock[];
/**
- * See [General fields: `_meta`](/specification/2025-06-18/basic/index#meta) for notes on `_meta` usage.
+ * An optional JSON object that represents the structured result of the tool call.
*/
- _meta?: { [key: string]: unknown };
-}
-/**
- * An optional notification from the server to the client, informing it that the list of prompts it offers has changed. This may be issued by servers without any previous subscription from the client.
- *
- * @category `notifications/prompts/list_changed`
+ structuredContent?: { [key: string]: unknown };
+
+ /**
```
This interface is important because it defines how MCP Specification Tutorial: Designing Production-Grade MCP Clients and Servers From the Source of Truth implements the patterns covered in this chapter.
@@ -223,11 +221,11 @@ This interface is important because it defines how MCP Specification Tutorial: D
```mermaid
flowchart TD
- A[Prompt]
- B[PromptArgument]
- C[PromptMessage]
- D[ResourceLink]
- E[EmbeddedResource]
+ A[ResourceLink]
+ B[EmbeddedResource]
+ C[PromptListChangedNotification]
+ D[ListToolsRequest]
+ E[ListToolsResult]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-specification-tutorial/04-transport-model-stdio-streamable-http-and-sessions.md b/tutorials/mcp-specification-tutorial/04-transport-model-stdio-streamable-http-and-sessions.md
index 773344cc..681d5850 100644
--- a/tutorials/mcp-specification-tutorial/04-transport-model-stdio-streamable-http-and-sessions.md
+++ b/tutorials/mcp-specification-tutorial/04-transport-model-stdio-streamable-http-and-sessions.md
@@ -47,58 +47,13 @@ You now have a transport operations model that is compatible with current sessio
Next: [Chapter 5: Server Primitives: Tools, Resources, and Prompts](05-server-primitives-tools-resources-and-prompts.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `schema/2025-06-18/schema.ts`
-The `ElicitRequest` interface in [`schema/2025-06-18/schema.ts`](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/HEAD/schema/2025-06-18/schema.ts) handles a key part of this chapter's functionality:
-
-```ts
- * @category `elicitation/create`
- */
-export interface ElicitRequest extends Request {
- method: "elicitation/create";
- params: {
- /**
- * The message to present to the user.
- */
- message: string;
- /**
- * A restricted subset of JSON Schema.
- * Only top-level properties are allowed, without nesting.
- */
- requestedSchema: {
- type: "object";
- properties: {
- [key: string]: PrimitiveSchemaDefinition;
- };
- required?: string[];
- };
- };
-}
-
-/**
- * Restricted schema definitions that only allow primitive types
- * without nested objects or arrays.
- *
- * @category `elicitation/create`
- */
-export type PrimitiveSchemaDefinition =
- | StringSchema
- | NumberSchema
-```
-
-This interface is important because it defines how MCP Specification Tutorial: Designing Production-Grade MCP Clients and Servers From the Source of Truth implements the patterns covered in this chapter.
-
-### `schema/2025-06-18/schema.ts`
-
-The `StringSchema` interface in [`schema/2025-06-18/schema.ts`](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/HEAD/schema/2025-06-18/schema.ts) handles a key part of this chapter's functionality:
+The `BooleanSchema` interface in [`schema/2025-06-18/schema.ts`](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/HEAD/schema/2025-06-18/schema.ts) handles a key part of this chapter's functionality:
```ts
- */
-export type PrimitiveSchemaDefinition =
| StringSchema
| NumberSchema
| BooleanSchema
@@ -129,17 +84,17 @@ export interface NumberSchema {
/**
* @category `elicitation/create`
+ */
+export interface BooleanSchema {
```
This interface is important because it defines how MCP Specification Tutorial: Designing Production-Grade MCP Clients and Servers From the Source of Truth implements the patterns covered in this chapter.
### `schema/2025-06-18/schema.ts`
-The `NumberSchema` interface in [`schema/2025-06-18/schema.ts`](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/HEAD/schema/2025-06-18/schema.ts) handles a key part of this chapter's functionality:
+The `EnumSchema` interface in [`schema/2025-06-18/schema.ts`](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/HEAD/schema/2025-06-18/schema.ts) handles a key part of this chapter's functionality:
```ts
-export type PrimitiveSchemaDefinition =
- | StringSchema
| NumberSchema
| BooleanSchema
| EnumSchema;
@@ -170,47 +125,90 @@ export interface NumberSchema {
/**
* @category `elicitation/create`
*/
+export interface BooleanSchema {
+ type: "boolean";
```
This interface is important because it defines how MCP Specification Tutorial: Designing Production-Grade MCP Clients and Servers From the Source of Truth implements the patterns covered in this chapter.
### `schema/2025-06-18/schema.ts`
-The `BooleanSchema` interface in [`schema/2025-06-18/schema.ts`](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/HEAD/schema/2025-06-18/schema.ts) handles a key part of this chapter's functionality:
+The `ElicitResult` interface in [`schema/2025-06-18/schema.ts`](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/HEAD/schema/2025-06-18/schema.ts) handles a key part of this chapter's functionality:
```ts
- | StringSchema
- | NumberSchema
- | BooleanSchema
- | EnumSchema;
-
-/**
* @category `elicitation/create`
*/
-export interface StringSchema {
- type: "string";
- title?: string;
- description?: string;
- minLength?: number;
- maxLength?: number;
- format?: "email" | "uri" | "date" | "date-time";
+export interface ElicitResult extends Result {
+ /**
+ * The user action in response to the elicitation.
+ * - "accept": User submitted the form/confirmed the action
+ * - "decline": User explicitly declined the action
+ * - "cancel": User dismissed without making an explicit choice
+ */
+ action: "accept" | "decline" | "cancel";
+
+ /**
+ * The submitted form data, only present when action is "accept".
+ * Contains values matching the requested schema.
+ */
+ content?: { [key: string]: string | number | boolean };
+}
+
+/* Client messages */
+/** @internal */
+export type ClientRequest =
+ | PingRequest
+ | InitializeRequest
+ | CompleteRequest
+ | SetLevelRequest
+ | GetPromptRequest
+ | ListPromptsRequest
+ | ListResourcesRequest
+ | ListResourceTemplatesRequest
+ | ReadResourceRequest
+ | SubscribeRequest
+ | UnsubscribeRequest
+```
+
+This interface is important because it defines how MCP Specification Tutorial: Designing Production-Grade MCP Clients and Servers From the Source of Truth implements the patterns covered in this chapter.
+
+### `schema/2025-06-18/schema.ts`
+
+The `resource` interface in [`schema/2025-06-18/schema.ts`](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/HEAD/schema/2025-06-18/schema.ts) handles a key part of this chapter's functionality:
+
+```ts
+ * Instructions describing how to use the server and its features.
+ *
+ * This can be used by clients to improve the LLM's understanding of available tools, resources, etc. It can be thought of like a "hint" to the model. For example, this information MAY be added to the system prompt.
+ */
+ instructions?: string;
}
/**
- * @category `elicitation/create`
+ * This notification is sent from the client to the server after initialization has finished.
+ *
+ * @category `notifications/initialized`
*/
-export interface NumberSchema {
- type: "number" | "integer";
- title?: string;
- description?: string;
- minimum?: number;
- maximum?: number;
+export interface InitializedNotification extends Notification {
+ method: "notifications/initialized";
}
/**
- * @category `elicitation/create`
+ * Capabilities a client may support. Known capabilities are defined here, in this schema, but this is not a closed set: any client can define its own, additional capabilities.
+ *
+ * @category `initialize`
*/
-export interface BooleanSchema {
+export interface ClientCapabilities {
+ /**
+ * Experimental, non-standard capabilities that the client supports.
+ */
+ experimental?: { [key: string]: object };
+ /**
+ * Present if the client supports listing roots.
+ */
+ roots?: {
+ /**
+ * Whether the client supports notifications for changes to the roots list.
```
This interface is important because it defines how MCP Specification Tutorial: Designing Production-Grade MCP Clients and Servers From the Source of Truth implements the patterns covered in this chapter.
@@ -220,11 +218,11 @@ This interface is important because it defines how MCP Specification Tutorial: D
```mermaid
flowchart TD
- A[ElicitRequest]
- B[StringSchema]
- C[NumberSchema]
- D[BooleanSchema]
- E[EnumSchema]
+ A[BooleanSchema]
+ B[EnumSchema]
+ C[ElicitResult]
+ D[resource]
+ E[values]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-specification-tutorial/05-server-primitives-tools-resources-and-prompts.md b/tutorials/mcp-specification-tutorial/05-server-primitives-tools-resources-and-prompts.md
index 4ea234bc..208d39ef 100644
--- a/tutorials/mcp-specification-tutorial/05-server-primitives-tools-resources-and-prompts.md
+++ b/tutorials/mcp-specification-tutorial/05-server-primitives-tools-resources-and-prompts.md
@@ -49,8 +49,6 @@ You now have a practical design framework for server primitives that is easier f
Next: [Chapter 6: Client Primitives: Roots, Sampling, Elicitation, and Tasks](06-client-primitives-roots-sampling-elicitation-and-tasks.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `schema/2025-03-26/schema.ts`
diff --git a/tutorials/mcp-specification-tutorial/06-client-primitives-roots-sampling-elicitation-and-tasks.md b/tutorials/mcp-specification-tutorial/06-client-primitives-roots-sampling-elicitation-and-tasks.md
index 06984eae..3a6b2df1 100644
--- a/tutorials/mcp-specification-tutorial/06-client-primitives-roots-sampling-elicitation-and-tasks.md
+++ b/tutorials/mcp-specification-tutorial/06-client-primitives-roots-sampling-elicitation-and-tasks.md
@@ -48,8 +48,6 @@ You now have a client capability strategy that keeps power features usable witho
Next: [Chapter 7: Authorization and Security Best Practices](07-authorization-and-security-best-practices.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `schema/2025-03-26/schema.ts`
diff --git a/tutorials/mcp-specification-tutorial/07-authorization-and-security-best-practices.md b/tutorials/mcp-specification-tutorial/07-authorization-and-security-best-practices.md
index 870f8d73..a37c1d6d 100644
--- a/tutorials/mcp-specification-tutorial/07-authorization-and-security-best-practices.md
+++ b/tutorials/mcp-specification-tutorial/07-authorization-and-security-best-practices.md
@@ -49,8 +49,6 @@ You now have a concrete security baseline for authorization, session handling, a
Next: [Chapter 8: Governance, SEPs, and Contribution Workflow](08-governance-seps-and-contribution-workflow.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `schema/2024-11-05/schema.ts`
diff --git a/tutorials/mcp-specification-tutorial/08-governance-seps-and-contribution-workflow.md b/tutorials/mcp-specification-tutorial/08-governance-seps-and-contribution-workflow.md
index dd1c0b81..5f8121dc 100644
--- a/tutorials/mcp-specification-tutorial/08-governance-seps-and-contribution-workflow.md
+++ b/tutorials/mcp-specification-tutorial/08-governance-seps-and-contribution-workflow.md
@@ -49,8 +49,6 @@ You now have a governance-aware operating model for shipping MCP changes and tra
Next: Continue with [MCP Go SDK Tutorial](../mcp-go-sdk-tutorial/)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `schema/2024-11-05/schema.ts`
diff --git a/tutorials/mcp-swift-sdk-tutorial/01-getting-started-and-package-baseline.md b/tutorials/mcp-swift-sdk-tutorial/01-getting-started-and-package-baseline.md
index 5d108f43..a6dbe116 100644
--- a/tutorials/mcp-swift-sdk-tutorial/01-getting-started-and-package-baseline.md
+++ b/tutorials/mcp-swift-sdk-tutorial/01-getting-started-and-package-baseline.md
@@ -38,170 +38,168 @@ You now have a stable Swift MCP baseline for subsequent client/server implementa
Next: [Chapter 2: Client Transport and Capability Negotiation](02-client-transport-and-capability-negotiation.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `Sources/MCP/Client/Client.swift`
+### `Sources/MCPConformance/Server/main.swift`
-The `public` interface in [`Sources/MCP/Client/Client.swift`](https://github.com/modelcontextprotocol/swift-sdk/blob/HEAD/Sources/MCP/Client/Client.swift) handles a key part of this chapter's functionality:
+The `MCPHTTPServer` interface in [`Sources/MCPConformance/Server/main.swift`](https://github.com/modelcontextprotocol/swift-sdk/blob/HEAD/Sources/MCPConformance/Server/main.swift) handles a key part of this chapter's functionality:
```swift
-
-/// Model Context Protocol client
-public actor Client {
- /// The client configuration
- public struct Configuration: Hashable, Codable, Sendable {
- /// The default configuration.
- public static let `default` = Configuration(strict: false)
-
- /// The strict configuration.
- public static let strict = Configuration(strict: true)
-
- /// When strict mode is enabled, the client:
- /// - Requires server capabilities to be initialized before making requests
- /// - Rejects all requests that require capabilities before initialization
- ///
- /// While the MCP specification requires servers to respond to initialize requests
- /// with their capabilities, some implementations may not follow this.
- /// Disabling strict mode allows the client to be more lenient with non-compliant
- /// servers, though this may lead to undefined behavior.
- public var strict: Bool
-
- public init(strict: Bool = false) {
- self.strict = strict
+// MARK: - Main
+
+struct MCPHTTPServer {
+ static func run() async throws {
+ let args = CommandLine.arguments
+ var port = 3001
+
+ for (index, arg) in args.enumerated() {
+ if arg == "--port" && index + 1 < args.count {
+ if let p = Int(args[index + 1]) {
+ port = p
+ }
+ }
}
- }
- /// Implementation information
- public struct Info: Hashable, Codable, Sendable {
- /// The client name
- public var name: String
- /// A human-readable title for display purposes
- public var title: String?
+ var loggerConfig = Logger(label: "mcp.http.server", factory: { StreamLogHandler.standardError(label: $0) })
+ loggerConfig.logLevel = .trace
+ let logger = loggerConfig
+
+ let state = ServerState()
+
+ logger.info("Starting MCP HTTP Server...", metadata: ["port": "\(port)"])
+
+ // Create HTTPApp with server factory
+ let app = HTTPApp(
+ configuration: .init(
+ host: "127.0.0.1",
+ port: port,
+ endpoint: "/mcp",
+ retryInterval: 1000
+ ),
+ validationPipeline: StandardValidationPipeline(validators: [
```
This interface is important because it defines how MCP Swift SDK Tutorial: Building MCP Clients and Servers in Swift implements the patterns covered in this chapter.
-### `Sources/MCP/Client/Client.swift`
+### `Sources/MCPConformance/Server/main.swift`
-The `Foundation` interface in [`Sources/MCP/Client/Client.swift`](https://github.com/modelcontextprotocol/swift-sdk/blob/HEAD/Sources/MCP/Client/Client.swift) handles a key part of this chapter's functionality:
+The `variants` interface in [`Sources/MCPConformance/Server/main.swift`](https://github.com/modelcontextprotocol/swift-sdk/blob/HEAD/Sources/MCPConformance/Server/main.swift) handles a key part of this chapter's functionality:
```swift
-import Logging
-
-import struct Foundation.Data
-import struct Foundation.Date
-import class Foundation.JSONDecoder
-import class Foundation.JSONEncoder
-
-/// Model Context Protocol client
-public actor Client {
- /// The client configuration
- public struct Configuration: Hashable, Codable, Sendable {
- /// The default configuration.
- public static let `default` = Configuration(strict: false)
-
- /// The strict configuration.
- public static let strict = Configuration(strict: true)
-
- /// When strict mode is enabled, the client:
- /// - Requires server capabilities to be initialized before making requests
- /// - Rejects all requests that require capabilities before initialization
- ///
- /// While the MCP specification requires servers to respond to initialize requests
- /// with their capabilities, some implementations may not follow this.
- /// Disabling strict mode allows the client to be more lenient with non-compliant
- /// servers, though this may lead to undefined behavior.
- public var strict: Bool
-
- public init(strict: Bool = false) {
- self.strict = strict
- }
+ Tool(name: "test_elicitation", description: "Tests user input elicitation", inputSchema: .object(["type": "object", "properties": ["message": ["type": "string", "description": "Text displayed to user"]], "required": ["message"]])),
+ Tool(name: "test_elicitation_sep1034_defaults", description: "Tests elicitation with default values (SEP-1034)", inputSchema: .object(["type": "object", "properties": [:]])),
+ Tool(name: "test_elicitation_sep1330_enums", description: "Tests elicitation with enum variants (SEP-1330)", inputSchema: .object(["type": "object", "properties": [:]])),
+ Tool(name: "test_client_elicitation_defaults", description: "Tests that client applies defaults for omitted elicitation fields", inputSchema: .object(["type": "object", "properties": [:]])),
+ Tool(name: "json_schema_2020_12_tool", description: "Tool with JSON Schema 2020-12 features", inputSchema: .object([
+ "$schema": .string("https://json-schema.org/draft/2020-12/schema"),
+ "type": .string("object"),
+ "$defs": .object([
+ "address": .object([
+ "type": .string("object"),
+ "properties": .object([
+ "street": .object(["type": .string("string")]),
+ "city": .object(["type": .string("string")])
+ ])
+ ])
+ ]),
+ "properties": .object([
+ "name": .object(["type": .string("string")]),
+ "address": .object(["$ref": .string("#/$defs/address")])
+ ]),
+ "additionalProperties": .bool(false)
+ ]))
+ ])
}
+ await server.withMethodHandler(CallTool.self) { [weak server, transport] params in
+ switch params.name {
+ case "test_simple_text":
+ return .init(content: [.text(text: "This is a simple text response for testing.", annotations: nil, _meta: nil)], isError: false)
+ case "test_image_content":
+ return .init(content: [.image(data: testImageBase64, mimeType: "image/png", annotations: nil, _meta: nil)], isError: false)
+ case "test_audio_content":
```
This interface is important because it defines how MCP Swift SDK Tutorial: Building MCP Clients and Servers in Swift implements the patterns covered in this chapter.
-### `Sources/MCP/Client/Client.swift`
+### `Sources/MCPConformance/Server/main.swift`
-The `Foundation` interface in [`Sources/MCP/Client/Client.swift`](https://github.com/modelcontextprotocol/swift-sdk/blob/HEAD/Sources/MCP/Client/Client.swift) handles a key part of this chapter's functionality:
+The `variants` interface in [`Sources/MCPConformance/Server/main.swift`](https://github.com/modelcontextprotocol/swift-sdk/blob/HEAD/Sources/MCPConformance/Server/main.swift) handles a key part of this chapter's functionality:
```swift
-import Logging
-
-import struct Foundation.Data
-import struct Foundation.Date
-import class Foundation.JSONDecoder
-import class Foundation.JSONEncoder
-
-/// Model Context Protocol client
-public actor Client {
- /// The client configuration
- public struct Configuration: Hashable, Codable, Sendable {
- /// The default configuration.
- public static let `default` = Configuration(strict: false)
-
- /// The strict configuration.
- public static let strict = Configuration(strict: true)
-
- /// When strict mode is enabled, the client:
- /// - Requires server capabilities to be initialized before making requests
- /// - Rejects all requests that require capabilities before initialization
- ///
- /// While the MCP specification requires servers to respond to initialize requests
- /// with their capabilities, some implementations may not follow this.
- /// Disabling strict mode allows the client to be more lenient with non-compliant
- /// servers, though this may lead to undefined behavior.
- public var strict: Bool
-
- public init(strict: Bool = false) {
- self.strict = strict
- }
+ Tool(name: "test_elicitation", description: "Tests user input elicitation", inputSchema: .object(["type": "object", "properties": ["message": ["type": "string", "description": "Text displayed to user"]], "required": ["message"]])),
+ Tool(name: "test_elicitation_sep1034_defaults", description: "Tests elicitation with default values (SEP-1034)", inputSchema: .object(["type": "object", "properties": [:]])),
+ Tool(name: "test_elicitation_sep1330_enums", description: "Tests elicitation with enum variants (SEP-1330)", inputSchema: .object(["type": "object", "properties": [:]])),
+ Tool(name: "test_client_elicitation_defaults", description: "Tests that client applies defaults for omitted elicitation fields", inputSchema: .object(["type": "object", "properties": [:]])),
+ Tool(name: "json_schema_2020_12_tool", description: "Tool with JSON Schema 2020-12 features", inputSchema: .object([
+ "$schema": .string("https://json-schema.org/draft/2020-12/schema"),
+ "type": .string("object"),
+ "$defs": .object([
+ "address": .object([
+ "type": .string("object"),
+ "properties": .object([
+ "street": .object(["type": .string("string")]),
+ "city": .object(["type": .string("string")])
+ ])
+ ])
+ ]),
+ "properties": .object([
+ "name": .object(["type": .string("string")]),
+ "address": .object(["$ref": .string("#/$defs/address")])
+ ]),
+ "additionalProperties": .bool(false)
+ ]))
+ ])
}
+ await server.withMethodHandler(CallTool.self) { [weak server, transport] params in
+ switch params.name {
+ case "test_simple_text":
+ return .init(content: [.text(text: "This is a simple text response for testing.", annotations: nil, _meta: nil)], isError: false)
+ case "test_image_content":
+ return .init(content: [.image(data: testImageBase64, mimeType: "image/png", annotations: nil, _meta: nil)], isError: false)
+ case "test_audio_content":
```
This interface is important because it defines how MCP Swift SDK Tutorial: Building MCP Clients and Servers in Swift implements the patterns covered in this chapter.
-### `Sources/MCP/Client/Client.swift`
+### `Sources/MCPConformance/Server/main.swift`
-The `Configuration` interface in [`Sources/MCP/Client/Client.swift`](https://github.com/modelcontextprotocol/swift-sdk/blob/HEAD/Sources/MCP/Client/Client.swift) handles a key part of this chapter's functionality:
+The `testing` interface in [`Sources/MCPConformance/Server/main.swift`](https://github.com/modelcontextprotocol/swift-sdk/blob/HEAD/Sources/MCPConformance/Server/main.swift) handles a key part of this chapter's functionality:
```swift
-public actor Client {
- /// The client configuration
- public struct Configuration: Hashable, Codable, Sendable {
- /// The default configuration.
- public static let `default` = Configuration(strict: false)
-
- /// The strict configuration.
- public static let strict = Configuration(strict: true)
-
- /// When strict mode is enabled, the client:
- /// - Requires server capabilities to be initialized before making requests
- /// - Rejects all requests that require capabilities before initialization
- ///
- /// While the MCP specification requires servers to respond to initialize requests
- /// with their capabilities, some implementations may not follow this.
- /// Disabling strict mode allows the client to be more lenient with non-compliant
- /// servers, though this may lead to undefined behavior.
- public var strict: Bool
-
- public init(strict: Bool = false) {
- self.strict = strict
- }
+ * MCP HTTP Server Wrapper
+ *
+ * HTTP server that wraps the MCP conformance server for testing with the
+ * official conformance framework.
+ *
+ * Usage: mcp-http-server [--port PORT]
+ */
+
+import Foundation
+import Logging
+import MCP
+
+#if canImport(FoundationNetworking)
+ import FoundationNetworking
+#endif
+
+// MARK: - Test Data
+
+private let testImageBase64 = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8DwHwAFBQIAX8jx0gAAAABJRU5ErkJggg=="
+private let testAudioBase64 = "UklGRiYAAABXQVZFZm10IBAAAAABAAEAQB8AAAB9AAACABAAZGF0YQIAAAA="
+
+// MARK: - Server State
+
+actor ServerState {
+ var resourceSubscriptions: Set<String> = []
+ var watchedResourceContent = "Watched resource content"
+
+ func subscribe(to uri: String) {
+ resourceSubscriptions.insert(uri)
}
- /// Implementation information
- public struct Info: Hashable, Codable, Sendable {
- /// The client name
- public var name: String
- /// A human-readable title for display purposes
- public var title: String?
- /// The client version
- public var version: String
+ func unsubscribe(from uri: String) {
```
This interface is important because it defines how MCP Swift SDK Tutorial: Building MCP Clients and Servers in Swift implements the patterns covered in this chapter.
@@ -211,11 +209,11 @@ This interface is important because it defines how MCP Swift SDK Tutorial: Build
```mermaid
flowchart TD
- A[public]
- B[Foundation]
- C[Foundation]
- D[Configuration]
- E[Info]
+ A[MCPHTTPServer]
+ B[variants]
+ C[variants]
+ D[testing]
+ E[public]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-swift-sdk-tutorial/02-client-transport-and-capability-negotiation.md b/tutorials/mcp-swift-sdk-tutorial/02-client-transport-and-capability-negotiation.md
index 972b2c2f..d700e111 100644
--- a/tutorials/mcp-swift-sdk-tutorial/02-client-transport-and-capability-negotiation.md
+++ b/tutorials/mcp-swift-sdk-tutorial/02-client-transport-and-capability-negotiation.md
@@ -38,170 +38,168 @@ You now have a client setup model that keeps capability assumptions and transpor
Next: [Chapter 3: Tools, Resources, Prompts, and Request Patterns](03-tools-resources-prompts-and-request-patterns.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `Sources/MCP/Client/Sampling.swift`
+### `Sources/MCP/Client/Client.swift`
-The `Result` interface in [`Sources/MCP/Client/Sampling.swift`](https://github.com/modelcontextprotocol/swift-sdk/blob/HEAD/Sources/MCP/Client/Sampling.swift) handles a key part of this chapter's functionality:
+The `Capabilities` interface in [`Sources/MCP/Client/Client.swift`](https://github.com/modelcontextprotocol/swift-sdk/blob/HEAD/Sources/MCP/Client/Client.swift) handles a key part of this chapter's functionality:
```swift
- case toolUse(Sampling.ToolUseContent)
- /// Tool result content
- case toolResult(Sampling.ToolResultContent)
- }
- /// Returns true if this is a single content block
- public var isSingle: Bool {
- if case .single = self { return true }
- return false
- }
+ /// The client capabilities
+ public struct Capabilities: Hashable, Codable, Sendable {
+ /// The roots capabilities
+ public struct Roots: Hashable, Codable, Sendable {
+ /// Whether the list of roots has changed
+ public var listChanged: Bool?
- /// Returns content as an array of blocks
- public var asArray: [ContentBlock] {
- switch self {
- case .single(let block):
- return [block]
- case .multiple(let blocks):
- return blocks
- }
+ public init(listChanged: Bool? = nil) {
+ self.listChanged = listChanged
}
+ }
- /// Creates content from a text string (convenience)
- public static func text(_ text: String) -> Content {
- .single(.text(text))
+ /// The sampling capabilities
+ public struct Sampling: Hashable, Sendable {
+ /// Tools sub-capability for sampling
+ public struct Tools: Hashable, Codable, Sendable {
+ public init() {}
}
- /// Creates content from an image (convenience)
- public static func image(data: String, mimeType: String) -> Content {
- .single(.image(data: data, mimeType: mimeType))
+ /// Context sub-capability for sampling
+ public struct Context: Hashable, Codable, Sendable {
+ public init() {}
}
- /// Creates content from audio (convenience)
+ /// Whether tools are supported in sampling
+ public var tools: Tools?
+ /// Whether context is supported in sampling
+ public var context: Context?
+
+ public init(tools: Tools? = nil, context: Context? = nil) {
+ self.tools = tools
```
This interface is important because it defines how MCP Swift SDK Tutorial: Building MCP Clients and Servers in Swift implements the patterns covered in this chapter.
-### `Sources/MCP/Client/Sampling.swift`
+### `Sources/MCP/Client/Client.swift`
-The `Sampling` interface in [`Sources/MCP/Client/Sampling.swift`](https://github.com/modelcontextprotocol/swift-sdk/blob/HEAD/Sources/MCP/Client/Sampling.swift) handles a key part of this chapter's functionality:
+The `Roots` interface in [`Sources/MCP/Client/Client.swift`](https://github.com/modelcontextprotocol/swift-sdk/blob/HEAD/Sources/MCP/Client/Client.swift) handles a key part of this chapter's functionality:
```swift
-///
-/// - SeeAlso: https://modelcontextprotocol.io/docs/concepts/sampling#how-sampling-works
-public enum Sampling {
- /// A message in the conversation history.
- public struct Message: Hashable, Sendable {
- /// The message role
- public enum Role: String, Hashable, Codable, Sendable {
- /// A user message
- case user
- /// An assistant message
- case assistant
+ public struct Capabilities: Hashable, Codable, Sendable {
+ /// The roots capabilities
+ public struct Roots: Hashable, Codable, Sendable {
+ /// Whether the list of roots has changed
+ public var listChanged: Bool?
+
+ public init(listChanged: Bool? = nil) {
+ self.listChanged = listChanged
+ }
}
- /// The message role
- public let role: Role
- /// The message content
- public let content: Content
- /// Optional metadata
- public var _meta: Metadata?
-
- /// Creates a message with the specified role and content
- @available(
- *, deprecated, message: "Use static factory methods .user(_:) or .assistant(_:) instead"
- )
- public init(role: Role, content: Content, _meta: Metadata? = nil) {
- self.role = role
- self.content = content
- self._meta = _meta
- }
+ /// The sampling capabilities
+ public struct Sampling: Hashable, Sendable {
+ /// Tools sub-capability for sampling
+ public struct Tools: Hashable, Codable, Sendable {
+ public init() {}
+ }
- /// Private initializer for convenience methods to avoid deprecation warnings
- private init(_role role: Role, _content content: Content, _meta: Metadata? = nil) {
+ /// Context sub-capability for sampling
+ public struct Context: Hashable, Codable, Sendable {
+ public init() {}
+ }
+
+ /// Whether tools are supported in sampling
+ public var tools: Tools?
+ /// Whether context is supported in sampling
+ public var context: Context?
+
+ public init(tools: Tools? = nil, context: Context? = nil) {
+ self.tools = tools
+ self.context = context
+ }
```
This interface is important because it defines how MCP Swift SDK Tutorial: Building MCP Clients and Servers in Swift implements the patterns covered in this chapter.
-### `Sources/MCP/Client/Sampling.swift`
+### `Sources/MCP/Client/Client.swift`
-The `Role` interface in [`Sources/MCP/Client/Sampling.swift`](https://github.com/modelcontextprotocol/swift-sdk/blob/HEAD/Sources/MCP/Client/Sampling.swift) handles a key part of this chapter's functionality:
+The `Sampling` interface in [`Sources/MCP/Client/Client.swift`](https://github.com/modelcontextprotocol/swift-sdk/blob/HEAD/Sources/MCP/Client/Client.swift) handles a key part of this chapter's functionality:
```swift
- public struct Message: Hashable, Sendable {
- /// The message role
- public enum Role: String, Hashable, Codable, Sendable {
- /// A user message
- case user
- /// An assistant message
- case assistant
- }
- /// The message role
- public let role: Role
- /// The message content
- public let content: Content
- /// Optional metadata
- public var _meta: Metadata?
-
- /// Creates a message with the specified role and content
- @available(
- *, deprecated, message: "Use static factory methods .user(_:) or .assistant(_:) instead"
- )
- public init(role: Role, content: Content, _meta: Metadata? = nil) {
- self.role = role
- self.content = content
- self._meta = _meta
- }
+ /// The sampling capabilities
+ public struct Sampling: Hashable, Sendable {
+ /// Tools sub-capability for sampling
+ public struct Tools: Hashable, Codable, Sendable {
+ public init() {}
+ }
- /// Private initializer for convenience methods to avoid deprecation warnings
- private init(_role role: Role, _content content: Content, _meta: Metadata? = nil) {
- self.role = role
- self.content = content
- self._meta = _meta
+ /// Context sub-capability for sampling
+ public struct Context: Hashable, Codable, Sendable {
+ public init() {}
+ }
+
+ /// Whether tools are supported in sampling
+ public var tools: Tools?
+ /// Whether context is supported in sampling
+ public var context: Context?
+
+ public init(tools: Tools? = nil, context: Context? = nil) {
+ self.tools = tools
+ self.context = context
+ }
}
+
+ /// The elicitation capabilities
+ public struct Elicitation: Hashable, Sendable {
+ /// Form-based elicitation sub-capability
+ public struct Form: Hashable, Codable, Sendable {
+ public init() {}
+ }
+
+ /// URL-based elicitation sub-capability
```
This interface is important because it defines how MCP Swift SDK Tutorial: Building MCP Clients and Servers in Swift implements the patterns covered in this chapter.
-### `Sources/MCP/Client/Sampling.swift`
+### `Sources/MCP/Client/Client.swift`
-The `Content` interface in [`Sources/MCP/Client/Sampling.swift`](https://github.com/modelcontextprotocol/swift-sdk/blob/HEAD/Sources/MCP/Client/Sampling.swift) handles a key part of this chapter's functionality:
+The `Tools` interface in [`Sources/MCP/Client/Client.swift`](https://github.com/modelcontextprotocol/swift-sdk/blob/HEAD/Sources/MCP/Client/Client.swift) handles a key part of this chapter's functionality:
```swift
- public let role: Role
- /// The message content
- public let content: Content
- /// Optional metadata
- public var _meta: Metadata?
-
- /// Creates a message with the specified role and content
- @available(
- *, deprecated, message: "Use static factory methods .user(_:) or .assistant(_:) instead"
- )
- public init(role: Role, content: Content, _meta: Metadata? = nil) {
- self.role = role
- self.content = content
- self._meta = _meta
- }
+ /// The sampling capabilities
+ public struct Sampling: Hashable, Sendable {
+ /// Tools sub-capability for sampling
+ public struct Tools: Hashable, Codable, Sendable {
+ public init() {}
+ }
- /// Private initializer for convenience methods to avoid deprecation warnings
- private init(_role role: Role, _content content: Content, _meta: Metadata? = nil) {
- self.role = role
- self.content = content
- self._meta = _meta
- }
+ /// Context sub-capability for sampling
+ public struct Context: Hashable, Codable, Sendable {
+ public init() {}
+ }
- /// Creates a user message with the specified content
- public static func user(_ content: Content, _meta: Metadata? = nil) -> Message {
- return Message(_role: .user, _content: content, _meta: _meta)
- }
+ /// Whether tools are supported in sampling
+ public var tools: Tools?
+ /// Whether context is supported in sampling
+ public var context: Context?
- /// Creates an assistant message with the specified content
- public static func assistant(_ content: Content, _meta: Metadata? = nil) -> Message {
- return Message(_role: .assistant, _content: content, _meta: _meta)
+ public init(tools: Tools? = nil, context: Context? = nil) {
+ self.tools = tools
+ self.context = context
+ }
}
+
+ /// The elicitation capabilities
+ public struct Elicitation: Hashable, Sendable {
+ /// Form-based elicitation sub-capability
+ public struct Form: Hashable, Codable, Sendable {
+ public init() {}
+ }
+
+ /// URL-based elicitation sub-capability
+ public struct URL: Hashable, Codable, Sendable {
```
This interface is important because it defines how MCP Swift SDK Tutorial: Building MCP Clients and Servers in Swift implements the patterns covered in this chapter.
@@ -211,11 +209,11 @@ This interface is important because it defines how MCP Swift SDK Tutorial: Build
```mermaid
flowchart TD
- A[Result]
- B[Sampling]
- C[Role]
- D[Content]
- E[ContentBlock]
+ A[Capabilities]
+ B[Roots]
+ C[Sampling]
+ D[Tools]
+ E[Context]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-swift-sdk-tutorial/03-tools-resources-prompts-and-request-patterns.md b/tutorials/mcp-swift-sdk-tutorial/03-tools-resources-prompts-and-request-patterns.md
index a27b862d..7665ebd9 100644
--- a/tutorials/mcp-swift-sdk-tutorial/03-tools-resources-prompts-and-request-patterns.md
+++ b/tutorials/mcp-swift-sdk-tutorial/03-tools-resources-prompts-and-request-patterns.md
@@ -39,168 +39,168 @@ You now have a predictable pattern for primitive interactions in Swift MCP clien
Next: [Chapter 4: Sampling, Human-in-the-Loop, and Error Handling](04-sampling-human-in-the-loop-and-error-handling.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `Sources/MCP/Server/Server.swift`
+### `Sources/MCP/Server/Tools.swift`
-The `Logging` interface in [`Sources/MCP/Server/Server.swift`](https://github.com/modelcontextprotocol/swift-sdk/blob/HEAD/Sources/MCP/Server/Server.swift) handles a key part of this chapter's functionality:
+The `Content` interface in [`Sources/MCP/Server/Tools.swift`](https://github.com/modelcontextprotocol/swift-sdk/blob/HEAD/Sources/MCP/Server/Tools.swift) handles a key part of this chapter's functionality:
```swift
-import Logging
-
-import struct Foundation.Data
-import struct Foundation.Date
-import class Foundation.JSONDecoder
-import class Foundation.JSONEncoder
-
-/// Model Context Protocol server
-public actor Server {
- /// The server configuration
- public struct Configuration: Hashable, Codable, Sendable {
- /// The default configuration.
- public static let `default` = Configuration(strict: false)
-
- /// The strict configuration.
- public static let strict = Configuration(strict: true)
-
- /// When strict mode is enabled, the server:
- /// - Requires clients to send an initialize request before any other requests
- /// - Rejects all requests from uninitialized clients with a protocol error
- ///
- /// While the MCP specification requires clients to initialize the connection
- /// before sending other requests, some implementations may not follow this.
- /// Disabling strict mode allows the server to be more lenient with non-compliant
- /// clients, though this may lead to undefined behavior.
- public var strict: Bool
}
- /// Implementation information
- public struct Info: Hashable, Codable, Sendable {
+ /// Content types that can be returned by a tool
+ public enum Content: Hashable, Codable, Sendable {
+ /// Text content
+ case text(text: String, annotations: Resource.Annotations?, _meta: Metadata?)
+ /// Image content
+ case image(data: String, mimeType: String, annotations: Resource.Annotations?, _meta: Metadata?)
+ /// Audio content
+ case audio(data: String, mimeType: String, annotations: Resource.Annotations?, _meta: Metadata?)
+ /// Embedded resource content (EmbeddedResource from spec)
+ case resource(resource: Resource.Content, annotations: Resource.Annotations? = nil, _meta: Metadata? = nil)
+ /// Resource link
+ case resourceLink(
+ uri: String, name: String, title: String? = nil, description: String? = nil,
+ mimeType: String? = nil,
+ annotations: Resource.Annotations? = nil
+ )
+
+ /// Deprecated compatibility factory for older call sites that used `.text("...")` and `.text("...", metadata: ...)`.
+ @available(*, deprecated, message: "Use .text(text:annotations:_meta:) instead.")
+ public static func text(_ text: String, metadata: Metadata? = nil) -> Self {
+ .text(text: text, annotations: nil, _meta: metadata)
+ }
+
+ /// Deprecated compatibility factory for older call sites that used `.text(text: ..., metadata: ...)`.
+ @available(*, deprecated, message: "Use .text(text:annotations:_meta:) instead.")
+ public static func text(text: String, metadata: Metadata? = nil) -> Self {
+ .text(text: text, annotations: nil, _meta: metadata)
+ }
+
+ /// Deprecated compatibility factory for older call sites that used `.image(..., metadata: ...)`.
```
This interface is important because it defines how MCP Swift SDK Tutorial: Building MCP Clients and Servers in Swift implements the patterns covered in this chapter.
-### `Sources/MCP/Server/Server.swift`
+### `Sources/MCP/Server/Tools.swift`
-The `Completions` interface in [`Sources/MCP/Server/Server.swift`](https://github.com/modelcontextprotocol/swift-sdk/blob/HEAD/Sources/MCP/Server/Server.swift) handles a key part of this chapter's functionality:
+The `CodingKeys` interface in [`Sources/MCP/Server/Tools.swift`](https://github.com/modelcontextprotocol/swift-sdk/blob/HEAD/Sources/MCP/Server/Tools.swift) handles a key part of this chapter's functionality:
```swift
}
- /// Completions capabilities
- public struct Completions: Hashable, Codable, Sendable {
- public init() {}
+ private enum CodingKeys: String, CodingKey {
+ case type
+ case text
+ case image
+ case resource
+ case resource_link
+ case audio
+ case uri
+ case name
+ case title
+ case description
+ case annotations
+ case mimeType
+ case data
+ case _meta
}
- /// Completions capabilities
- public var completions: Completions?
- /// Logging capabilities
- public var logging: Logging?
- /// Prompts capabilities
- public var prompts: Prompts?
- /// Resources capabilities
- public var resources: Resources?
- /// Tools capabilities
- public var tools: Tools?
-
- public init(
- completions: Completions? = nil,
- logging: Logging? = nil,
- prompts: Prompts? = nil,
- resources: Resources? = nil,
- tools: Tools? = nil
- ) {
- self.completions = completions
- self.logging = logging
- self.prompts = prompts
- self.resources = resources
- self.tools = tools
- }
- }
+ public init(from decoder: Decoder) throws {
+ let container = try decoder.container(keyedBy: CodingKeys.self)
+ let type = try container.decode(String.self, forKey: .type)
+
+ switch type {
+ case "text":
+ let text = try container.decode(String.self, forKey: .text)
+ let annotations = try container.decodeIfPresent(Resource.Annotations.self, forKey: .annotations)
+ let _meta = try container.decodeIfPresent(Metadata.self, forKey: ._meta)
+ self = .text(text: text, annotations: annotations, _meta: _meta)
+ case "image":
+ let data = try container.decode(String.self, forKey: .data)
+ let mimeType = try container.decode(String.self, forKey: .mimeType)
```
This interface is important because it defines how MCP Swift SDK Tutorial: Building MCP Clients and Servers in Swift implements the patterns covered in this chapter.
-### `Sources/MCP/Server/Server.swift`
+### `Sources/MCP/Server/Tools.swift`
-The `Batch` interface in [`Sources/MCP/Server/Server.swift`](https://github.com/modelcontextprotocol/swift-sdk/blob/HEAD/Sources/MCP/Server/Server.swift) handles a key part of this chapter's functionality:
+The `CodingKeys` interface in [`Sources/MCP/Server/Tools.swift`](https://github.com/modelcontextprotocol/swift-sdk/blob/HEAD/Sources/MCP/Server/Tools.swift) handles a key part of this chapter's functionality:
```swift
- // Attempt to decode as batch first, then as individual response, request, or notification
- let decoder = JSONDecoder()
- if let batch = try? decoder.decode(Server.Batch.self, from: data) {
- try await handleBatch(batch)
- } else if let response = try? decoder.decode(AnyResponse.self, from: data) {
- await handleResponse(response)
- } else if let request = try? decoder.decode(AnyRequest.self, from: data) {
- // Handle request in a separate task to avoid blocking the receive loop
- Task {
- _ = try? await self.handleRequest(request, sendResponse: true)
- }
- } else if let message = try? decoder.decode(AnyMessage.self, from: data) {
- try await handleMessage(message)
- } else {
- // Try to extract request ID from raw JSON if possible
- if let json = try? JSONDecoder().decode(
- [String: Value].self, from: data),
- let idValue = json["id"]
- {
- if let strValue = idValue.stringValue {
- requestID = .string(strValue)
- } else if let intValue = idValue.intValue {
- requestID = .number(intValue)
- }
- }
- throw MCPError.parseError("Invalid message format")
- }
- } catch let error where MCPError.isResourceTemporarilyUnavailable(error) {
- // Resource temporarily unavailable, retry after a short delay
- try? await Task.sleep(for: .milliseconds(10))
- continue
- } catch {
+ }
+
+ private enum CodingKeys: String, CodingKey {
+ case type
+ case text
+ case image
+ case resource
+ case resource_link
+ case audio
+ case uri
+ case name
+ case title
+ case description
+ case annotations
+ case mimeType
+ case data
+ case _meta
+ }
+
+ public init(from decoder: Decoder) throws {
+ let container = try decoder.container(keyedBy: CodingKeys.self)
+ let type = try container.decode(String.self, forKey: .type)
+
+ switch type {
+ case "text":
+ let text = try container.decode(String.self, forKey: .text)
+ let annotations = try container.decodeIfPresent(Resource.Annotations.self, forKey: .annotations)
+ let _meta = try container.decodeIfPresent(Metadata.self, forKey: ._meta)
+ self = .text(text: text, annotations: annotations, _meta: _meta)
+ case "image":
+ let data = try container.decode(String.self, forKey: .data)
+ let mimeType = try container.decode(String.self, forKey: .mimeType)
```
This interface is important because it defines how MCP Swift SDK Tutorial: Building MCP Clients and Servers in Swift implements the patterns covered in this chapter.
-### `Sources/MCP/Server/Server.swift`
+### `Sources/MCP/Server/Tools.swift`
-The `Item` interface in [`Sources/MCP/Server/Server.swift`](https://github.com/modelcontextprotocol/swift-sdk/blob/HEAD/Sources/MCP/Server/Server.swift) handles a key part of this chapter's functionality:
+The `ListTools` interface in [`Sources/MCP/Server/Tools.swift`](https://github.com/modelcontextprotocol/swift-sdk/blob/HEAD/Sources/MCP/Server/Tools.swift) handles a key part of this chapter's functionality:
```swift
- struct Batch: Sendable {
- /// An item in a JSON-RPC batch
- enum Item: Sendable {
- case request(Request<AnyMethod>)
- case notification(Message<AnyNotification>)
+/// To discover available tools, clients send a `tools/list` request.
+/// - SeeAlso: https://modelcontextprotocol.io/specification/2025-11-25/server/tools/#listing-tools
+public enum ListTools: Method {
+ public static let name = "tools/list"
- }
+ public struct Parameters: NotRequired, Hashable, Codable, Sendable {
+ public let cursor: String?
- var items: [Item]
+ public init() {
+ self.cursor = nil
+ }
- init(items: [Item]) {
- self.items = items
+ public init(cursor: String) {
+ self.cursor = cursor
}
}
- /// Process a batch of requests and/or notifications
- private func handleBatch(_ batch: Batch) async throws {
- await logger?.trace("Processing batch request", metadata: ["size": "\(batch.items.count)"])
+ public struct Result: Hashable, Codable, Sendable {
+ public let tools: [Tool]
+ public let nextCursor: String?
+ public var _meta: Metadata?
- if batch.items.isEmpty {
- // Empty batch is invalid according to JSON-RPC spec
- let error = MCPError.invalidRequest("Batch array must not be empty")
- let response = AnyMethod.response(id: .random, error: error)
- try await send(response)
- return
+ public init(
+ tools: [Tool],
+ nextCursor: String? = nil,
+ _meta: Metadata? = nil
+ ) {
+ self.tools = tools
+ self.nextCursor = nextCursor
+ self._meta = _meta
}
- // Process each item in the batch and collect responses
- var responses: [Response<AnyMethod>] = []
-
- for item in batch.items {
- do {
```
This interface is important because it defines how MCP Swift SDK Tutorial: Building MCP Clients and Servers in Swift implements the patterns covered in this chapter.
@@ -210,10 +210,10 @@ This interface is important because it defines how MCP Swift SDK Tutorial: Build
```mermaid
flowchart TD
- A[Logging]
- B[Completions]
- C[Batch]
- D[Item]
+ A[Content]
+ B[CodingKeys]
+ C[CodingKeys]
+ D[ListTools]
E[CodingKeys]
A --> B
B --> C
diff --git a/tutorials/mcp-swift-sdk-tutorial/04-sampling-human-in-the-loop-and-error-handling.md b/tutorials/mcp-swift-sdk-tutorial/04-sampling-human-in-the-loop-and-error-handling.md
index 0b2c10e9..311e63f6 100644
--- a/tutorials/mcp-swift-sdk-tutorial/04-sampling-human-in-the-loop-and-error-handling.md
+++ b/tutorials/mcp-swift-sdk-tutorial/04-sampling-human-in-the-loop-and-error-handling.md
@@ -38,170 +38,150 @@ You now have a human-in-the-loop sampling pattern for safer Swift client operati
Next: [Chapter 5: Server Setup, Hooks, and Primitive Authoring](05-server-setup-hooks-and-primitive-authoring.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `Sources/MCP/Server/Tools.swift`
+### `Sources/MCP/Server/Resources.swift`
-The `CodingKeys` interface in [`Sources/MCP/Server/Tools.swift`](https://github.com/modelcontextprotocol/swift-sdk/blob/HEAD/Sources/MCP/Server/Tools.swift) handles a key part of this chapter's functionality:
+The `ResourceUpdatedNotification` interface in [`Sources/MCP/Server/Resources.swift`](https://github.com/modelcontextprotocol/swift-sdk/blob/HEAD/Sources/MCP/Server/Resources.swift) handles a key part of this chapter's functionality:
```swift
- }
+/// When a resource changes, servers that declared the updated capability SHOULD send a notification to subscribed clients.
+/// - SeeAlso: https://modelcontextprotocol.io/specification/2025-11-25/server/resources/#subscriptions
+public struct ResourceUpdatedNotification: Notification {
+ public static let name: String = "notifications/resources/updated"
+
+ public struct Parameters: Hashable, Codable, Sendable {
+ public let uri: String
- private enum CodingKeys: String, CodingKey {
- case type
- case text
- case image
- case resource
- case resource_link
- case audio
- case uri
- case name
- case title
- case description
- case annotations
- case mimeType
- case data
- case _meta
+ public init(uri: String) {
+ self.uri = uri
}
+ }
+}
- public init(from decoder: Decoder) throws {
- let container = try decoder.container(keyedBy: CodingKeys.self)
- let type = try container.decode(String.self, forKey: .type)
-
- switch type {
- case "text":
- let text = try container.decode(String.self, forKey: .text)
- let annotations = try container.decodeIfPresent(Resource.Annotations.self, forKey: .annotations)
- let _meta = try container.decodeIfPresent(Metadata.self, forKey: ._meta)
- self = .text(text: text, annotations: annotations, _meta: _meta)
- case "image":
- let data = try container.decode(String.self, forKey: .data)
- let mimeType = try container.decode(String.self, forKey: .mimeType)
```
This interface is important because it defines how MCP Swift SDK Tutorial: Building MCP Clients and Servers in Swift implements the patterns covered in this chapter.
-### `Sources/MCP/Server/Tools.swift`
+### `Sources/MCP/Server/Resources.swift`
-The `CodingKeys` interface in [`Sources/MCP/Server/Tools.swift`](https://github.com/modelcontextprotocol/swift-sdk/blob/HEAD/Sources/MCP/Server/Tools.swift) handles a key part of this chapter's functionality:
+The `Parameters` interface in [`Sources/MCP/Server/Resources.swift`](https://github.com/modelcontextprotocol/swift-sdk/blob/HEAD/Sources/MCP/Server/Resources.swift) handles a key part of this chapter's functionality:
```swift
+ public static let name: String = "resources/list"
+
+ public struct Parameters: NotRequired, Hashable, Codable, Sendable {
+ public let cursor: String?
+
+ public init() {
+ self.cursor = nil
}
- private enum CodingKeys: String, CodingKey {
- case type
- case text
- case image
- case resource
- case resource_link
- case audio
- case uri
- case name
- case title
- case description
- case annotations
- case mimeType
- case data
- case _meta
+ public init(cursor: String) {
+ self.cursor = cursor
+ }
+ }
+
+ public struct Result: Hashable, Codable, Sendable {
+ public let resources: [Resource]
+ public let nextCursor: String?
+ public var _meta: Metadata?
+
+ public init(
+ resources: [Resource],
+ nextCursor: String? = nil,
+ _meta: Metadata? = nil
+ ) {
+ self.resources = resources
+ self.nextCursor = nextCursor
+ self._meta = _meta
}
- public init(from decoder: Decoder) throws {
- let container = try decoder.container(keyedBy: CodingKeys.self)
- let type = try container.decode(String.self, forKey: .type)
-
- switch type {
- case "text":
- let text = try container.decode(String.self, forKey: .text)
- let annotations = try container.decodeIfPresent(Resource.Annotations.self, forKey: .annotations)
- let _meta = try container.decodeIfPresent(Metadata.self, forKey: ._meta)
- self = .text(text: text, annotations: annotations, _meta: _meta)
- case "image":
- let data = try container.decode(String.self, forKey: .data)
- let mimeType = try container.decode(String.self, forKey: .mimeType)
+ private enum CodingKeys: String, CodingKey, CaseIterable {
+ case resources, nextCursor, _meta
+ }
```
This interface is important because it defines how MCP Swift SDK Tutorial: Building MCP Clients and Servers in Swift implements the patterns covered in this chapter.
-### `Sources/MCPConformance/Server/HTTPApp.swift`
+### `Sources/MCP/Server/Resources.swift`
-The `Configuration` interface in [`Sources/MCPConformance/Server/HTTPApp.swift`](https://github.com/modelcontextprotocol/swift-sdk/blob/HEAD/Sources/MCPConformance/Server/HTTPApp.swift) handles a key part of this chapter's functionality:
+The `CodingKeys` interface in [`Sources/MCP/Server/Resources.swift`](https://github.com/modelcontextprotocol/swift-sdk/blob/HEAD/Sources/MCP/Server/Resources.swift) handles a key part of this chapter's functionality:
```swift
+ }
-actor HTTPApp {
- /// Configuration for the HTTP application.
- struct Configuration: Sendable {
- /// The host address to bind to.
- var host: String
-
- /// The port to bind to.
- var port: Int
-
- /// The MCP endpoint path.
- var endpoint: String
-
- /// Session timeout in seconds.
- var sessionTimeout: TimeInterval
+ private enum CodingKeys: String, CodingKey {
+ case name
+ case uri
+ case title
+ case description
+ case mimeType
+ case size
+ case annotations
+ case icons
+ case _meta
+ }
- /// SSE retry interval in milliseconds for priming events.
- var retryInterval: Int?
+ public init(from decoder: Decoder) throws {
+ let container = try decoder.container(keyedBy: CodingKeys.self)
+ name = try container.decode(String.self, forKey: .name)
+ uri = try container.decode(String.self, forKey: .uri)
+ title = try container.decodeIfPresent(String.self, forKey: .title)
+ description = try container.decodeIfPresent(String.self, forKey: .description)
+ mimeType = try container.decodeIfPresent(String.self, forKey: .mimeType)
+ size = try container.decodeIfPresent(Int.self, forKey: .size)
+ annotations = try container.decodeIfPresent(Resource.Annotations.self, forKey: .annotations)
+ icons = try container.decodeIfPresent([Icon].self, forKey: .icons)
+ _meta = try container.decodeIfPresent(Metadata.self, forKey: ._meta)
+ }
- init(
- host: String = "127.0.0.1",
- port: Int = 3000,
- endpoint: String = "/mcp",
- sessionTimeout: TimeInterval = 3600,
- retryInterval: Int? = nil
- ) {
- self.host = host
- self.port = port
- self.endpoint = endpoint
- self.sessionTimeout = sessionTimeout
- self.retryInterval = retryInterval
- }
+ public func encode(to encoder: Encoder) throws {
+ var container = encoder.container(keyedBy: CodingKeys.self)
+ try container.encode(name, forKey: .name)
+ try container.encode(uri, forKey: .uri)
+ try container.encodeIfPresent(title, forKey: .title)
```
This interface is important because it defines how MCP Swift SDK Tutorial: Building MCP Clients and Servers in Swift implements the patterns covered in this chapter.
-### `Sources/MCPConformance/Server/HTTPApp.swift`
+### `Sources/MCP/Server/Resources.swift`
-The `SessionContext` interface in [`Sources/MCPConformance/Server/HTTPApp.swift`](https://github.com/modelcontextprotocol/swift-sdk/blob/HEAD/Sources/MCPConformance/Server/HTTPApp.swift) handles a key part of this chapter's functionality:
+The `CodingKeys` interface in [`Sources/MCP/Server/Resources.swift`](https://github.com/modelcontextprotocol/swift-sdk/blob/HEAD/Sources/MCP/Server/Resources.swift) handles a key part of this chapter's functionality:
```swift
- private let validationPipeline: (any HTTPRequestValidationPipeline)?
- private var channel: Channel?
- private var sessions: [String: SessionContext] = [:]
+ }
- nonisolated let logger: Logger
+ private enum CodingKeys: String, CodingKey {
+ case name
+ case uri
+ case title
+ case description
+ case mimeType
+ case size
+ case annotations
+ case icons
+ case _meta
+ }
- struct SessionContext {
- let server: Server
- let transport: StatefulHTTPServerTransport
- let createdAt: Date
- var lastAccessedAt: Date
+ public init(from decoder: Decoder) throws {
+ let container = try decoder.container(keyedBy: CodingKeys.self)
+ name = try container.decode(String.self, forKey: .name)
+ uri = try container.decode(String.self, forKey: .uri)
+ title = try container.decodeIfPresent(String.self, forKey: .title)
+ description = try container.decodeIfPresent(String.self, forKey: .description)
+ mimeType = try container.decodeIfPresent(String.self, forKey: .mimeType)
+ size = try container.decodeIfPresent(Int.self, forKey: .size)
+ annotations = try container.decodeIfPresent(Resource.Annotations.self, forKey: .annotations)
+ icons = try container.decodeIfPresent([Icon].self, forKey: .icons)
+ _meta = try container.decodeIfPresent(Metadata.self, forKey: ._meta)
}
- // MARK: - Init
-
- /// Creates a new HTTP application.
- ///
- /// - Parameters:
- /// - configuration: Application configuration.
- /// - validationPipeline: Custom validation pipeline passed to each transport.
- /// If `nil`, transports use their sensible defaults.
- /// - serverFactory: Factory function to create Server instances for each session.
- /// - logger: Optional logger instance.
- init(
- configuration: Configuration = Configuration(),
- validationPipeline: (any HTTPRequestValidationPipeline)? = nil,
- serverFactory: @escaping ServerFactory,
- logger: Logger? = nil
- ) {
- self.configuration = configuration
- self.serverFactory = serverFactory
- self.validationPipeline = validationPipeline
+ public func encode(to encoder: Encoder) throws {
+ var container = encoder.container(keyedBy: CodingKeys.self)
+ try container.encode(name, forKey: .name)
+ try container.encode(uri, forKey: .uri)
+ try container.encodeIfPresent(title, forKey: .title)
```
This interface is important because it defines how MCP Swift SDK Tutorial: Building MCP Clients and Servers in Swift implements the patterns covered in this chapter.
@@ -211,11 +191,11 @@ This interface is important because it defines how MCP Swift SDK Tutorial: Build
```mermaid
flowchart TD
- A[CodingKeys]
- B[CodingKeys]
- C[Configuration]
- D[SessionContext]
- E[FixedSessionIDGenerator]
+ A[ResourceUpdatedNotification]
+ B[Parameters]
+ C[CodingKeys]
+ D[CodingKeys]
+ E[Audience]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-swift-sdk-tutorial/05-server-setup-hooks-and-primitive-authoring.md b/tutorials/mcp-swift-sdk-tutorial/05-server-setup-hooks-and-primitive-authoring.md
index 0a2ca17a..5487d6a0 100644
--- a/tutorials/mcp-swift-sdk-tutorial/05-server-setup-hooks-and-primitive-authoring.md
+++ b/tutorials/mcp-swift-sdk-tutorial/05-server-setup-hooks-and-primitive-authoring.md
@@ -38,168 +38,168 @@ You now have a structured foundation for implementing Swift MCP servers.
Next: [Chapter 6: Transports, Custom Implementations, and Shutdown](06-transports-custom-implementations-and-shutdown.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `Sources/MCP/Server/Prompts.swift`
+### `Sources/MCP/Client/Sampling.swift`
-The `GetPrompt` interface in [`Sources/MCP/Server/Prompts.swift`](https://github.com/modelcontextprotocol/swift-sdk/blob/HEAD/Sources/MCP/Server/Prompts.swift) handles a key part of this chapter's functionality:
+The `ModelPreferences` interface in [`Sources/MCP/Client/Sampling.swift`](https://github.com/modelcontextprotocol/swift-sdk/blob/HEAD/Sources/MCP/Client/Sampling.swift) handles a key part of this chapter's functionality:
```swift
-/// Arguments may be auto-completed through the completion API.
-/// - SeeAlso: https://modelcontextprotocol.io/specification/2025-11-25/server/prompts/#getting-a-prompt
-public enum GetPrompt: Method {
- public static let name: String = "prompts/get"
- public struct Parameters: Hashable, Codable, Sendable {
- public let name: String
- public let arguments: [String: String]?
+ /// Model preferences for sampling requests
+ public struct ModelPreferences: Hashable, Codable, Sendable {
+ /// Model hints for selection
+ public struct Hint: Hashable, Codable, Sendable {
+ /// Suggested model name/family
+ public let name: String?
- public init(name: String, arguments: [String: String]? = nil) {
- self.name = name
- self.arguments = arguments
+ public init(name: String? = nil) {
+ self.name = name
+ }
}
- }
- public struct Result: Hashable, Codable, Sendable {
- public let description: String?
- public let messages: [Prompt.Message]
- /// Optional metadata about this result
- public var _meta: Metadata?
+ /// Array of model name suggestions that clients can use to select an appropriate model
+ public let hints: [Hint]?
+ /// Importance of minimizing costs (0-1 normalized)
+ public let costPriority: UnitInterval?
+ /// Importance of low latency response (0-1 normalized)
+ public let speedPriority: UnitInterval?
+ /// Importance of advanced model capabilities (0-1 normalized)
+ public let intelligencePriority: UnitInterval?
public init(
- description: String? = nil,
- messages: [Prompt.Message],
- _meta: Metadata? = nil
+ hints: [Hint]? = nil,
+ costPriority: UnitInterval? = nil,
+ speedPriority: UnitInterval? = nil,
+ intelligencePriority: UnitInterval? = nil
) {
- self.description = description
- self.messages = messages
- self._meta = _meta
- }
-
- private enum CodingKeys: String, CodingKey, CaseIterable {
+ self.hints = hints
+ self.costPriority = costPriority
+ self.speedPriority = speedPriority
+ self.intelligencePriority = intelligencePriority
```
This interface is important because it defines how MCP Swift SDK Tutorial: Building MCP Clients and Servers in Swift implements the patterns covered in this chapter.
-### `Sources/MCP/Server/Prompts.swift`
+### `Sources/MCP/Client/Sampling.swift`
-The `CodingKeys` interface in [`Sources/MCP/Server/Prompts.swift`](https://github.com/modelcontextprotocol/swift-sdk/blob/HEAD/Sources/MCP/Server/Prompts.swift) handles a key part of this chapter's functionality:
+The `Hint` interface in [`Sources/MCP/Client/Sampling.swift`](https://github.com/modelcontextprotocol/swift-sdk/blob/HEAD/Sources/MCP/Client/Sampling.swift) handles a key part of this chapter's functionality:
```swift
- }
-
- private enum CodingKeys: String, CodingKey {
- case name, title, description, arguments, icons, _meta
- }
+ public struct ModelPreferences: Hashable, Codable, Sendable {
+ /// Model hints for selection
+ public struct Hint: Hashable, Codable, Sendable {
+ /// Suggested model name/family
+ public let name: String?
+
+ public init(name: String? = nil) {
+ self.name = name
+ }
+ }
- public func encode(to encoder: Encoder) throws {
- var container = encoder.container(keyedBy: CodingKeys.self)
- try container.encode(name, forKey: .name)
- try container.encodeIfPresent(title, forKey: .title)
- try container.encodeIfPresent(description, forKey: .description)
- try container.encodeIfPresent(arguments, forKey: .arguments)
- try container.encodeIfPresent(icons, forKey: .icons)
- try container.encodeIfPresent(_meta, forKey: ._meta)
- }
+ /// Array of model name suggestions that clients can use to select an appropriate model
+ public let hints: [Hint]?
+ /// Importance of minimizing costs (0-1 normalized)
+ public let costPriority: UnitInterval?
+ /// Importance of low latency response (0-1 normalized)
+ public let speedPriority: UnitInterval?
+ /// Importance of advanced model capabilities (0-1 normalized)
+ public let intelligencePriority: UnitInterval?
- public init(from decoder: Decoder) throws {
- let container = try decoder.container(keyedBy: CodingKeys.self)
- name = try container.decode(String.self, forKey: .name)
- title = try container.decodeIfPresent(String.self, forKey: .title)
- description = try container.decodeIfPresent(String.self, forKey: .description)
- arguments = try container.decodeIfPresent([Argument].self, forKey: .arguments)
- icons = try container.decodeIfPresent([Icon].self, forKey: .icons)
- _meta = try container.decodeIfPresent(Metadata.self, forKey: ._meta)
+ public init(
+ hints: [Hint]? = nil,
+ costPriority: UnitInterval? = nil,
+ speedPriority: UnitInterval? = nil,
+ intelligencePriority: UnitInterval? = nil
+ ) {
+ self.hints = hints
+ self.costPriority = costPriority
+ self.speedPriority = speedPriority
+ self.intelligencePriority = intelligencePriority
+ }
}
-
- /// An argument for a prompt
- public struct Argument: Hashable, Codable, Sendable {
- /// The argument name
- public let name: String
- /// A human-readable argument title
- public let title: String?
```
This interface is important because it defines how MCP Swift SDK Tutorial: Building MCP Clients and Servers in Swift implements the patterns covered in this chapter.
-### `Sources/MCP/Base/Value.swift`
+### `Sources/MCP/Client/Sampling.swift`
-The `Foundation` interface in [`Sources/MCP/Base/Value.swift`](https://github.com/modelcontextprotocol/swift-sdk/blob/HEAD/Sources/MCP/Base/Value.swift) handles a key part of this chapter's functionality:
+The `StopReason` interface in [`Sources/MCP/Client/Sampling.swift`](https://github.com/modelcontextprotocol/swift-sdk/blob/HEAD/Sources/MCP/Client/Sampling.swift) handles a key part of this chapter's functionality:
```swift
-import struct Foundation.Data
-import class Foundation.JSONDecoder
-import class Foundation.JSONEncoder
-
-/// A codable value.
-public enum Value: Hashable, Sendable {
- case null
- case bool(Bool)
- case int(Int)
- case double(Double)
- case string(String)
- case data(mimeType: String? = nil, Data)
- case array([Value])
- case object([String: Value])
-
- /// Create a `Value` from a `Codable` value.
- /// - Parameter value: The codable value
- /// - Returns: A value
- public init<T: Codable>(_ value: T) throws {
- if let valueAsValue = value as? Value {
- self = valueAsValue
- } else {
- let data = try JSONEncoder().encode(value)
- self = try JSONDecoder().decode(Value.self, from: data)
- }
+ /// The spec defines this as an open string — any provider-specific value is valid.
+ /// The well-known values are exposed as static constants.
+ public struct StopReason: RawRepresentable, Hashable, Codable, Sendable,
+ ExpressibleByStringLiteral
+ {
+ public let rawValue: String
+ public init(rawValue: String) { self.rawValue = rawValue }
+ public init(stringLiteral value: String) { self.rawValue = value }
+
+ /// Natural end of turn
+ public static let endTurn = StopReason(rawValue: "endTurn")
+ /// Hit a stop sequence
+ public static let stopSequence = StopReason(rawValue: "stopSequence")
+ /// Reached maximum tokens
+ public static let maxTokens = StopReason(rawValue: "maxTokens")
+ /// Model wants to use a tool
+ public static let toolUse = StopReason(rawValue: "toolUse")
}
- /// Returns whether the value is `null`.
- public var isNull: Bool {
- return self == .null
+ /// Content representing a tool use request from the model
+ public struct ToolUseContent: Hashable, Codable, Sendable {
+ /// Unique identifier for this tool use
+ public let id: String
+ /// Name of the tool being invoked
+ public let name: String
+ /// Input parameters for the tool
+ public let input: [String: Value]
+ /// Optional metadata
+ public var _meta: Metadata?
+
+ public init(id: String, name: String, input: [String: Value], _meta: Metadata? = nil) {
+ self.id = id
```
This interface is important because it defines how MCP Swift SDK Tutorial: Building MCP Clients and Servers in Swift implements the patterns covered in this chapter.
-### `Sources/MCP/Base/Value.swift`
+### `Sources/MCP/Client/Sampling.swift`
-The `StringInterpolation` interface in [`Sources/MCP/Base/Value.swift`](https://github.com/modelcontextprotocol/swift-sdk/blob/HEAD/Sources/MCP/Base/Value.swift) handles a key part of this chapter's functionality:
+The `ToolUseContent` interface in [`Sources/MCP/Client/Sampling.swift`](https://github.com/modelcontextprotocol/swift-sdk/blob/HEAD/Sources/MCP/Client/Sampling.swift) handles a key part of this chapter's functionality:
```swift
-}
-
-// MARK: - ExpressibleByStringInterpolation
-
-extension Value: ExpressibleByStringInterpolation {
- public struct StringInterpolation: StringInterpolationProtocol {
- var stringValue: String
-
- public init(literalCapacity: Int, interpolationCount: Int) {
- self.stringValue = ""
- self.stringValue.reserveCapacity(literalCapacity + interpolationCount)
- }
-
- public mutating func appendLiteral(_ literal: String) {
- self.stringValue.append(literal)
- }
-
- public mutating func appendInterpolation<T: CustomStringConvertible>(_ value: T) {
- self.stringValue.append(value.description)
- }
- }
-
- public init(stringInterpolation: StringInterpolation) {
- self = .string(stringInterpolation.stringValue)
- }
-}
-
-// MARK: - Standard Library Type Extensions
-
-extension Bool {
- /// Creates a boolean value from a `Value` instance.
- ///
+ case audio(data: String, mimeType: String)
+ /// Tool use content
+ case toolUse(Sampling.ToolUseContent)
+ /// Tool result content
+ case toolResult(Sampling.ToolResultContent)
+ }
+
+ /// Returns true if this is a single content block
+ public var isSingle: Bool {
+ if case .single = self { return true }
+ return false
+ }
+
+ /// Returns content as an array of blocks
+ public var asArray: [ContentBlock] {
+ switch self {
+ case .single(let block):
+ return [block]
+ case .multiple(let blocks):
+ return blocks
+ }
+ }
+
+ /// Creates content from a text string (convenience)
+ public static func text(_ text: String) -> Content {
+ .single(.text(text))
+ }
+
+ /// Creates content from an image (convenience)
+ public static func image(data: String, mimeType: String) -> Content {
+ .single(.image(data: data, mimeType: mimeType))
+ }
```
This interface is important because it defines how MCP Swift SDK Tutorial: Building MCP Clients and Servers in Swift implements the patterns covered in this chapter.
@@ -209,11 +209,11 @@ This interface is important because it defines how MCP Swift SDK Tutorial: Build
```mermaid
flowchart TD
- A[GetPrompt]
- B[CodingKeys]
- C[Foundation]
- D[StringInterpolation]
- E[Value]
+ A[ModelPreferences]
+ B[Hint]
+ C[StopReason]
+ D[ToolUseContent]
+ E[ToolResultContent]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-swift-sdk-tutorial/06-transports-custom-implementations-and-shutdown.md b/tutorials/mcp-swift-sdk-tutorial/06-transports-custom-implementations-and-shutdown.md
index cb3c2748..52499c1e 100644
--- a/tutorials/mcp-swift-sdk-tutorial/06-transports-custom-implementations-and-shutdown.md
+++ b/tutorials/mcp-swift-sdk-tutorial/06-transports-custom-implementations-and-shutdown.md
@@ -39,170 +39,168 @@ You now have runtime lifecycle controls for operating Swift MCP services more sa
Next: [Chapter 7: Strict Mode, Batching, Logging, and Debugging](07-strict-mode-batching-logging-and-debugging.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `Sources/MCP/Server/Resources.swift`
+### `Sources/MCPConformance/Server/HTTPApp.swift`
-The `CodingKeys` interface in [`Sources/MCP/Server/Resources.swift`](https://github.com/modelcontextprotocol/swift-sdk/blob/HEAD/Sources/MCP/Server/Resources.swift) handles a key part of this chapter's functionality:
+The `FixedSessionIDGenerator` interface in [`Sources/MCPConformance/Server/HTTPApp.swift`](https://github.com/modelcontextprotocol/swift-sdk/blob/HEAD/Sources/MCPConformance/Server/HTTPApp.swift) handles a key part of this chapter's functionality:
```swift
- }
+ // MARK: - Session Management
- private enum CodingKeys: String, CodingKey {
- case name
- case uri
- case title
- case description
- case mimeType
- case size
- case annotations
- case icons
- case _meta
+ private struct FixedSessionIDGenerator: SessionIDGenerator {
+ let sessionID: String
+ func generateSessionID() -> String { sessionID }
}
- public init(from decoder: Decoder) throws {
- let container = try decoder.container(keyedBy: CodingKeys.self)
- name = try container.decode(String.self, forKey: .name)
- uri = try container.decode(String.self, forKey: .uri)
- title = try container.decodeIfPresent(String.self, forKey: .title)
- description = try container.decodeIfPresent(String.self, forKey: .description)
- mimeType = try container.decodeIfPresent(String.self, forKey: .mimeType)
- size = try container.decodeIfPresent(Int.self, forKey: .size)
- annotations = try container.decodeIfPresent(Resource.Annotations.self, forKey: .annotations)
- icons = try container.decodeIfPresent([Icon].self, forKey: .icons)
- _meta = try container.decodeIfPresent(Metadata.self, forKey: ._meta)
- }
+ private func createSessionAndHandle(_ request: HTTPRequest) async -> HTTPResponse {
+ let sessionID = UUID().uuidString
+
+ let transport = StatefulHTTPServerTransport(
+ sessionIDGenerator: FixedSessionIDGenerator(sessionID: sessionID),
+ validationPipeline: validationPipeline,
+ retryInterval: configuration.retryInterval,
+ logger: logger
+ )
+
+ do {
+ let server = try await serverFactory(sessionID, transport)
+ try await server.start(transport: transport)
- public func encode(to encoder: Encoder) throws {
- var container = encoder.container(keyedBy: CodingKeys.self)
- try container.encode(name, forKey: .name)
- try container.encode(uri, forKey: .uri)
- try container.encodeIfPresent(title, forKey: .title)
+ sessions[sessionID] = SessionContext(
+ server: server,
+ transport: transport,
+ createdAt: Date(),
+ lastAccessedAt: Date()
+ )
+
+ let response = await transport.handleRequest(request)
+
+ // If transport returned an error, clean up
+ if case .error = response {
```
This interface is important because it defines how MCP Swift SDK Tutorial: Building MCP Clients and Servers in Swift implements the patterns covered in this chapter.
-### `Sources/MCP/Server/Resources.swift`
+### `Sources/MCPConformance/Server/HTTPApp.swift`
-The `Audience` interface in [`Sources/MCP/Server/Resources.swift`](https://github.com/modelcontextprotocol/swift-sdk/blob/HEAD/Sources/MCP/Server/Resources.swift) handles a key part of this chapter's functionality:
+The `RequestState` interface in [`Sources/MCPConformance/Server/HTTPApp.swift`](https://github.com/modelcontextprotocol/swift-sdk/blob/HEAD/Sources/MCPConformance/Server/HTTPApp.swift) handles a key part of this chapter's functionality:
```swift
- public struct Annotations: Hashable, Codable, Sendable {
- /// The intended audience for this resource.
- public enum Audience: String, Hashable, Codable, Sendable {
- /// Content intended for end users.
- case user = "user"
- /// Content intended for AI assistants.
- case assistant = "assistant"
- }
-
- /// An array indicating the intended audience(s) for this resource. For example, `[.user, .assistant]` indicates content useful for both.
- public let audience: [Audience]?
- /// A number from 0.0 to 1.0 indicating the importance of this resource. A value of 1 means "most important" (effectively required), while 0 means "least important".
- public let priority: Double?
- /// An ISO 8601 formatted timestamp indicating when the resource was last modified (e.g., "2025-01-12T15:00:58Z").
- public let lastModified: String?
-
- public init(
- audience: [Audience]? = nil,
- priority: Double? = nil,
- lastModified: String? = nil
- ) {
- self.audience = audience
- self.priority = priority
- self.lastModified = lastModified
- }
+ private let app: HTTPApp
+
+ private struct RequestState {
+ var head: HTTPRequestHead
+ var bodyBuffer: ByteBuffer
}
-}
-// MARK: -
+ private var requestState: RequestState?
+
+ init(app: HTTPApp) {
+ self.app = app
+ }
-/// To discover available resources, clients send a `resources/list` request.
-/// - SeeAlso: https://modelcontextprotocol.io/specification/2025-11-25/server/resources/#listing-resources
+ func channelRead(context: ChannelHandlerContext, data: NIOAny) {
+ let part = unwrapInboundIn(data)
+
+ switch part {
+ case .head(let head):
+ requestState = RequestState(
+ head: head,
+ bodyBuffer: context.channel.allocator.buffer(capacity: 0)
+ )
+ case .body(var buffer):
+ requestState?.bodyBuffer.writeBuffer(&buffer)
+ case .end:
+ guard let state = requestState else { return }
+ requestState = nil
+
+ nonisolated(unsafe) let ctx = context
+ Task { @MainActor in
+ await self.handleRequest(state: state, context: ctx)
+ }
```
This interface is important because it defines how MCP Swift SDK Tutorial: Building MCP Clients and Servers in Swift implements the patterns covered in this chapter.
-### `Sources/MCP/Server/Resources.swift`
+### `Sources/MCP/Base/Error.swift`
-The `ListResources` interface in [`Sources/MCP/Server/Resources.swift`](https://github.com/modelcontextprotocol/swift-sdk/blob/HEAD/Sources/MCP/Server/Resources.swift) handles a key part of this chapter's functionality:
+The `URLElicitationInfo` interface in [`Sources/MCP/Base/Error.swift`](https://github.com/modelcontextprotocol/swift-sdk/blob/HEAD/Sources/MCP/Base/Error.swift) handles a key part of this chapter's functionality:
```swift
-/// To discover available resources, clients send a `resources/list` request.
-/// - SeeAlso: https://modelcontextprotocol.io/specification/2025-11-25/server/resources/#listing-resources
-public enum ListResources: Method {
- public static let name: String = "resources/list"
-
- public struct Parameters: NotRequired, Hashable, Codable, Sendable {
- public let cursor: String?
-
- public init() {
- self.cursor = nil
- }
- public init(cursor: String) {
- self.cursor = cursor
- }
+/// Information about a required URL elicitation
+public struct URLElicitationInfo: Codable, Hashable, Sendable {
+ /// Elicitation mode (must be "url")
+ public var mode: String
+ /// Unique identifier for this elicitation
+ public var elicitationId: String
+ /// URL for the user to visit
+ public var url: String
+ /// Message describing the elicitation
+ public var message: String
+
+ public init(mode: String = "url", elicitationId: String, url: String, message: String) {
+ self.mode = mode
+ self.elicitationId = elicitationId
+ self.url = url
+ self.message = message
}
+}
+
+/// A model context protocol error.
+public enum MCPError: Swift.Error, Sendable {
+ // Standard JSON-RPC 2.0 errors (-32700 to -32603)
+ case parseError(String?) // -32700
+ case invalidRequest(String?) // -32600
+ case methodNotFound(String?) // -32601
+ case invalidParams(String?) // -32602
+ case internalError(String?) // -32603
- public struct Result: Hashable, Codable, Sendable {
- public let resources: [Resource]
- public let nextCursor: String?
- public var _meta: Metadata?
-
- public init(
- resources: [Resource],
- nextCursor: String? = nil,
- _meta: Metadata? = nil
- ) {
- self.resources = resources
- self.nextCursor = nextCursor
- self._meta = _meta
- }
+ // Server errors (-32000 to -32099)
+ case serverError(code: Int, message: String)
```
This interface is important because it defines how MCP Swift SDK Tutorial: Building MCP Clients and Servers in Swift implements the patterns covered in this chapter.
-### `Sources/MCP/Server/Resources.swift`
+### `Sources/MCP/Base/Error.swift`
-The `CodingKeys` interface in [`Sources/MCP/Server/Resources.swift`](https://github.com/modelcontextprotocol/swift-sdk/blob/HEAD/Sources/MCP/Server/Resources.swift) handles a key part of this chapter's functionality:
+The `MCPError` interface in [`Sources/MCP/Base/Error.swift`](https://github.com/modelcontextprotocol/swift-sdk/blob/HEAD/Sources/MCP/Base/Error.swift) handles a key part of this chapter's functionality:
```swift
- }
-
- private enum CodingKeys: String, CodingKey {
- case name
- case uri
- case title
- case description
- case mimeType
- case size
- case annotations
- case icons
- case _meta
- }
-
- public init(from decoder: Decoder) throws {
- let container = try decoder.container(keyedBy: CodingKeys.self)
- name = try container.decode(String.self, forKey: .name)
- uri = try container.decode(String.self, forKey: .uri)
- title = try container.decodeIfPresent(String.self, forKey: .title)
- description = try container.decodeIfPresent(String.self, forKey: .description)
- mimeType = try container.decodeIfPresent(String.self, forKey: .mimeType)
- size = try container.decodeIfPresent(Int.self, forKey: .size)
- annotations = try container.decodeIfPresent(Resource.Annotations.self, forKey: .annotations)
- icons = try container.decodeIfPresent([Icon].self, forKey: .icons)
- _meta = try container.decodeIfPresent(Metadata.self, forKey: ._meta)
- }
- public func encode(to encoder: Encoder) throws {
- var container = encoder.container(keyedBy: CodingKeys.self)
- try container.encode(name, forKey: .name)
- try container.encode(uri, forKey: .uri)
- try container.encodeIfPresent(title, forKey: .title)
+/// A model context protocol error.
+public enum MCPError: Swift.Error, Sendable {
+ // Standard JSON-RPC 2.0 errors (-32700 to -32603)
+ case parseError(String?) // -32700
+ case invalidRequest(String?) // -32600
+ case methodNotFound(String?) // -32601
+ case invalidParams(String?) // -32602
+ case internalError(String?) // -32603
+
+ // Server errors (-32000 to -32099)
+ case serverError(code: Int, message: String)
+
+ // MCP specific errors
+ case urlElicitationRequired(message: String, elicitations: [URLElicitationInfo]) // -32042
+
+ // Transport specific errors
+ case connectionClosed
+ case transportError(Swift.Error)
+
+ /// The JSON-RPC 2.0 error code
+ public var code: Int {
+ switch self {
+ case .parseError: return -32700
+ case .invalidRequest: return -32600
+ case .methodNotFound: return -32601
+ case .invalidParams: return -32602
+ case .internalError: return -32603
+ case .serverError(let code, _): return code
+ case .urlElicitationRequired: return -32042
+ case .connectionClosed: return -32000
+ case .transportError: return -32001
```
This interface is important because it defines how MCP Swift SDK Tutorial: Building MCP Clients and Servers in Swift implements the patterns covered in this chapter.
@@ -212,11 +210,11 @@ This interface is important because it defines how MCP Swift SDK Tutorial: Build
```mermaid
flowchart TD
- A[CodingKeys]
- B[Audience]
- C[ListResources]
- D[CodingKeys]
- E[ReadResource]
+ A[FixedSessionIDGenerator]
+ B[RequestState]
+ C[URLElicitationInfo]
+ D[MCPError]
+ E[CodingKeys]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-swift-sdk-tutorial/07-strict-mode-batching-logging-and-debugging.md b/tutorials/mcp-swift-sdk-tutorial/07-strict-mode-batching-logging-and-debugging.md
index 1371f72f..2116f5fa 100644
--- a/tutorials/mcp-swift-sdk-tutorial/07-strict-mode-batching-logging-and-debugging.md
+++ b/tutorials/mcp-swift-sdk-tutorial/07-strict-mode-batching-logging-and-debugging.md
@@ -39,153 +39,166 @@ You now have a control model for balancing safety and performance in Swift MCP c
Next: [Chapter 8: Release, Versioning, and Production Guidelines](08-release-versioning-and-production-guidelines.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `Sources/MCP/Client/Elicitation.swift`
+### `Sources/MCP/Server/Prompts.swift`
-The `ElicitationCompleteNotification` interface in [`Sources/MCP/Client/Elicitation.swift`](https://github.com/modelcontextprotocol/swift-sdk/blob/HEAD/Sources/MCP/Client/Elicitation.swift) handles a key part of this chapter's functionality:
+The `CodingKeys` interface in [`Sources/MCP/Server/Prompts.swift`](https://github.com/modelcontextprotocol/swift-sdk/blob/HEAD/Sources/MCP/Server/Prompts.swift) handles a key part of this chapter's functionality:
```swift
+ }
-/// Notification sent when a URL-based elicitation is complete
-public struct ElicitationCompleteNotification: Notification {
- public static let name = "notifications/elicitation/complete"
+ private enum CodingKeys: String, CodingKey {
+ case name, title, description, arguments, icons, _meta
+ }
- public struct Parameters: Hashable, Codable, Sendable {
- /// The elicitation ID that was completed
- public var elicitationId: String
+ public func encode(to encoder: Encoder) throws {
+ var container = encoder.container(keyedBy: CodingKeys.self)
+ try container.encode(name, forKey: .name)
+ try container.encodeIfPresent(title, forKey: .title)
+ try container.encodeIfPresent(description, forKey: .description)
+ try container.encodeIfPresent(arguments, forKey: .arguments)
+ try container.encodeIfPresent(icons, forKey: .icons)
+ try container.encodeIfPresent(_meta, forKey: ._meta)
+ }
- public init(elicitationId: String) {
- self.elicitationId = elicitationId
- }
+ public init(from decoder: Decoder) throws {
+ let container = try decoder.container(keyedBy: CodingKeys.self)
+ name = try container.decode(String.self, forKey: .name)
+ title = try container.decodeIfPresent(String.self, forKey: .title)
+ description = try container.decodeIfPresent(String.self, forKey: .description)
+ arguments = try container.decodeIfPresent([Argument].self, forKey: .arguments)
+ icons = try container.decodeIfPresent([Icon].self, forKey: .icons)
+ _meta = try container.decodeIfPresent(Metadata.self, forKey: ._meta)
}
-}
+ /// An argument for a prompt
+ public struct Argument: Hashable, Codable, Sendable {
+ /// The argument name
+ public let name: String
+ /// A human-readable argument title
+ public let title: String?
```
This interface is important because it defines how MCP Swift SDK Tutorial: Building MCP Clients and Servers in Swift implements the patterns covered in this chapter.
-### `Sources/MCP/Client/Elicitation.swift`
+### `Sources/MCP/Base/Value.swift`
-The `Parameters` interface in [`Sources/MCP/Client/Elicitation.swift`](https://github.com/modelcontextprotocol/swift-sdk/blob/HEAD/Sources/MCP/Client/Elicitation.swift) handles a key part of this chapter's functionality:
+The `Foundation` interface in [`Sources/MCP/Base/Value.swift`](https://github.com/modelcontextprotocol/swift-sdk/blob/HEAD/Sources/MCP/Base/Value.swift) handles a key part of this chapter's functionality:
```swift
- public static let name = "elicitation/create"
-
- public enum Parameters: Hashable, Sendable {
- /// Form-based elicitation parameters
- case form(FormParameters)
- /// URL-based elicitation parameters
- case url(URLParameters)
-
- /// Parameters for form-based elicitation
- public struct FormParameters: Hashable, Codable, Sendable {
- /// Message displayed to the user describing the request
- public var message: String
- /// Elicitation mode (optional for backward compatibility, defaults to form)
- public var mode: Elicitation.Mode?
- /// Schema describing the expected response content (required per spec)
- public var requestedSchema: Elicitation.RequestSchema
- /// Optional metadata
- public var _meta: Metadata?
-
- public init(
- message: String,
- mode: Elicitation.Mode? = nil,
- requestedSchema: Elicitation.RequestSchema = .init(),
- _meta: Metadata? = nil
- ) {
- self.message = message
- self.mode = mode
- self.requestedSchema = requestedSchema
- self._meta = _meta
- }
+import struct Foundation.Data
+import class Foundation.JSONDecoder
+import class Foundation.JSONEncoder
+
+/// A codable value.
+public enum Value: Hashable, Sendable {
+ case null
+ case bool(Bool)
+ case int(Int)
+ case double(Double)
+ case string(String)
+ case data(mimeType: String? = nil, Data)
+ case array([Value])
+ case object([String: Value])
+
+ /// Create a `Value` from a `Codable` value.
+ /// - Parameter value: The codable value
+ /// - Returns: A value
+ public init<T: Codable>(_ value: T) throws {
+ if let valueAsValue = value as? Value {
+ self = valueAsValue
+ } else {
+ let data = try JSONEncoder().encode(value)
+ self = try JSONDecoder().decode(Value.self, from: data)
}
+ }
+ /// Returns whether the value is `null`.
+ public var isNull: Bool {
+ return self == .null
```
This interface is important because it defines how MCP Swift SDK Tutorial: Building MCP Clients and Servers in Swift implements the patterns covered in this chapter.
-### `Sources/MCP/Client/Elicitation.swift`
+### `Sources/MCP/Base/Value.swift`
-The `Elicitation` interface in [`Sources/MCP/Client/Elicitation.swift`](https://github.com/modelcontextprotocol/swift-sdk/blob/HEAD/Sources/MCP/Client/Elicitation.swift) handles a key part of this chapter's functionality:
+The `StringInterpolation` interface in [`Sources/MCP/Base/Value.swift`](https://github.com/modelcontextprotocol/swift-sdk/blob/HEAD/Sources/MCP/Base/Value.swift) handles a key part of this chapter's functionality:
```swift
-/// Servers use elicitation to collect structured input from users via the client.
-/// The schema subset mirrors the 2025-11-25 revision of the specification.
-public enum Elicitation {
- /// Schema describing the expected response content.
- public struct RequestSchema: Hashable, Codable, Sendable {
- /// Supported top-level types. Currently limited to objects.
- public enum SchemaType: String, Hashable, Codable, Sendable {
- case object
+}
+
+// MARK: - ExpressibleByStringInterpolation
+
+extension Value: ExpressibleByStringInterpolation {
+ public struct StringInterpolation: StringInterpolationProtocol {
+ var stringValue: String
+
+ public init(literalCapacity: Int, interpolationCount: Int) {
+ self.stringValue = ""
+ self.stringValue.reserveCapacity(literalCapacity + interpolationCount)
+ }
+
+ public mutating func appendLiteral(_ literal: String) {
+ self.stringValue.append(literal)
+ }
+
+ public mutating func appendInterpolation<T: CustomStringConvertible>(_ value: T) {
+ self.stringValue.append(value.description)
}
+ }
+
+ public init(stringInterpolation: StringInterpolation) {
+ self = .string(stringInterpolation.stringValue)
+ }
+}
+
+// MARK: - Standard Library Type Extensions
- /// Schema title presented to users.
- public var title: String?
- /// Schema description providing additional guidance.
- public var description: String?
- /// Raw JSON Schema fragments describing the requested fields.
- public var properties: [String: Value]
- /// List of required field keys.
- public var required: [String]?
- /// Top-level schema type. Defaults to `object`.
- public var type: SchemaType
-
- public init(
- title: String? = nil,
- description: String? = nil,
- properties: [String: Value] = [:],
- required: [String]? = nil,
- type: SchemaType = .object
- ) {
- self.title = title
- self.description = description
- self.properties = properties
- self.required = required
+extension Bool {
+ /// Creates a boolean value from a `Value` instance.
+ ///
```
This interface is important because it defines how MCP Swift SDK Tutorial: Building MCP Clients and Servers in Swift implements the patterns covered in this chapter.
-### `Sources/MCP/Client/Elicitation.swift`
+### `Sources/MCP/Base/Value.swift`
-The `SchemaType` interface in [`Sources/MCP/Client/Elicitation.swift`](https://github.com/modelcontextprotocol/swift-sdk/blob/HEAD/Sources/MCP/Client/Elicitation.swift) handles a key part of this chapter's functionality:
+The `Value` interface in [`Sources/MCP/Base/Value.swift`](https://github.com/modelcontextprotocol/swift-sdk/blob/HEAD/Sources/MCP/Base/Value.swift) handles a key part of this chapter's functionality:
```swift
- public struct RequestSchema: Hashable, Codable, Sendable {
- /// Supported top-level types. Currently limited to objects.
- public enum SchemaType: String, Hashable, Codable, Sendable {
- case object
- }
- /// Schema title presented to users.
- public var title: String?
- /// Schema description providing additional guidance.
- public var description: String?
- /// Raw JSON Schema fragments describing the requested fields.
- public var properties: [String: Value]
- /// List of required field keys.
- public var required: [String]?
- /// Top-level schema type. Defaults to `object`.
- public var type: SchemaType
-
- public init(
- title: String? = nil,
- description: String? = nil,
- properties: [String: Value] = [:],
- required: [String]? = nil,
- type: SchemaType = .object
- ) {
- self.title = title
- self.description = description
- self.properties = properties
- self.required = required
- self.type = type
+/// A codable value.
+public enum Value: Hashable, Sendable {
+ case null
+ case bool(Bool)
+ case int(Int)
+ case double(Double)
+ case string(String)
+ case data(mimeType: String? = nil, Data)
+ case array([Value])
+ case object([String: Value])
+
+ /// Create a `Value` from a `Codable` value.
+ /// - Parameter value: The codable value
+ /// - Returns: A value
+ public init<T: Codable>(_ value: T) throws {
+ if let valueAsValue = value as? Value {
+ self = valueAsValue
+ } else {
+ let data = try JSONEncoder().encode(value)
+ self = try JSONDecoder().decode(Value.self, from: data)
}
+ }
+
+ /// Returns whether the value is `null`.
+ public var isNull: Bool {
+ return self == .null
+ }
- private enum CodingKeys: String, CodingKey {
+ /// Returns the `Bool` value if the value is a `bool`,
+ /// otherwise returns `nil`.
+ public var boolValue: Bool? {
```
This interface is important because it defines how MCP Swift SDK Tutorial: Building MCP Clients and Servers in Swift implements the patterns covered in this chapter.
@@ -195,11 +208,11 @@ This interface is important because it defines how MCP Swift SDK Tutorial: Build
```mermaid
flowchart TD
- A[ElicitationCompleteNotification]
- B[Parameters]
- C[Elicitation]
- D[SchemaType]
- E[CodingKeys]
+ A[CodingKeys]
+ B[Foundation]
+ C[StringInterpolation]
+ D[Value]
+ E[UnitInterval]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-swift-sdk-tutorial/08-release-versioning-and-production-guidelines.md b/tutorials/mcp-swift-sdk-tutorial/08-release-versioning-and-production-guidelines.md
index c784a2f0..95c2a1ae 100644
--- a/tutorials/mcp-swift-sdk-tutorial/08-release-versioning-and-production-guidelines.md
+++ b/tutorials/mcp-swift-sdk-tutorial/08-release-versioning-and-production-guidelines.md
@@ -39,170 +39,168 @@ You now have a release-aware operating model for shipping Swift MCP systems with
Next: Continue with [MCP Use Tutorial](../mcp-use-tutorial/)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `Sources/MCP/Server/Completion.swift`
+### `Sources/MCP/Base/Lifecycle.swift`
-The `CodingKeys` interface in [`Sources/MCP/Server/Completion.swift`](https://github.com/modelcontextprotocol/swift-sdk/blob/HEAD/Sources/MCP/Server/Completion.swift) handles a key part of this chapter's functionality:
+The `Initialize` interface in [`Sources/MCP/Base/Lifecycle.swift`](https://github.com/modelcontextprotocol/swift-sdk/blob/HEAD/Sources/MCP/Base/Lifecycle.swift) handles a key part of this chapter's functionality:
```swift
- }
+///
+/// - SeeAlso: https://spec.modelcontextprotocol.io/specification/2024-11-05/basic/lifecycle/#initialization
+public enum Initialize: Method {
+ public static let name: String = "initialize"
- private enum CodingKeys: String, CodingKey {
- case type, uri
- }
+ public struct Parameters: Hashable, Codable, Sendable {
+ public let protocolVersion: String
+ public let capabilities: Client.Capabilities
+ public let clientInfo: Client.Info
- public func encode(to encoder: Encoder) throws {
- var container = encoder.container(keyedBy: CodingKeys.self)
- try container.encode("ref/resource", forKey: .type)
- try container.encode(uri, forKey: .uri)
- }
+ public init(
+ protocolVersion: String = Version.latest,
+ capabilities: Client.Capabilities,
+ clientInfo: Client.Info
+ ) {
+ self.protocolVersion = protocolVersion
+ self.capabilities = capabilities
+ self.clientInfo = clientInfo
+ }
- public init(from decoder: Decoder) throws {
- let container = try decoder.container(keyedBy: CodingKeys.self)
- let type = try container.decode(String.self, forKey: .type)
- guard type == "ref/resource" else {
- throw DecodingError.dataCorruptedError(
- forKey: .type,
- in: container,
- debugDescription: "Expected ref/resource type"
- )
+ private enum CodingKeys: String, CodingKey {
+ case protocolVersion, capabilities, clientInfo
}
- uri = try container.decode(String.self, forKey: .uri)
- }
-}
-
-/// A reference type for completion requests (either prompt or resource)
-public enum CompletionReference: Hashable, Codable, Sendable {
- /// References a prompt by name
- case prompt(PromptReference)
- /// References a resource URI
- case resource(ResourceReference)
+
+ public init(from decoder: Decoder) throws {
+ let container = try decoder.container(keyedBy: CodingKeys.self)
+ protocolVersion =
+ try container.decodeIfPresent(String.self, forKey: .protocolVersion)
+ ?? Version.latest
+ capabilities =
+ try container.decodeIfPresent(Client.Capabilities.self, forKey: .capabilities)
+ ?? .init()
```
This interface is important because it defines how MCP Swift SDK Tutorial: Building MCP Clients and Servers in Swift implements the patterns covered in this chapter.
-### `Sources/MCP/Server/Completion.swift`
+### `Sources/MCP/Base/Lifecycle.swift`
-The `CompletionReference` interface in [`Sources/MCP/Server/Completion.swift`](https://github.com/modelcontextprotocol/swift-sdk/blob/HEAD/Sources/MCP/Server/Completion.swift) handles a key part of this chapter's functionality:
+The `CodingKeys` interface in [`Sources/MCP/Base/Lifecycle.swift`](https://github.com/modelcontextprotocol/swift-sdk/blob/HEAD/Sources/MCP/Base/Lifecycle.swift) handles a key part of this chapter's functionality:
```swift
+ }
-/// A reference type for completion requests (either prompt or resource)
-public enum CompletionReference: Hashable, Codable, Sendable {
- /// References a prompt by name
- case prompt(PromptReference)
- /// References a resource URI
- case resource(ResourceReference)
-
- private enum CodingKeys: String, CodingKey {
- case type
- }
+ private enum CodingKeys: String, CodingKey {
+ case protocolVersion, capabilities, clientInfo
+ }
- public init(from decoder: Decoder) throws {
- let container = try decoder.container(keyedBy: CodingKeys.self)
- let type = try container.decode(String.self, forKey: .type)
-
- switch type {
- case "ref/prompt":
- self = .prompt(try PromptReference(from: decoder))
- case "ref/resource":
- self = .resource(try ResourceReference(from: decoder))
- default:
- throw DecodingError.dataCorruptedError(
- forKey: .type,
- in: container,
- debugDescription: "Unknown reference type: \(type)"
- )
+ public init(from decoder: Decoder) throws {
+ let container = try decoder.container(keyedBy: CodingKeys.self)
+ protocolVersion =
+ try container.decodeIfPresent(String.self, forKey: .protocolVersion)
+ ?? Version.latest
+ capabilities =
+ try container.decodeIfPresent(Client.Capabilities.self, forKey: .capabilities)
+ ?? .init()
+ clientInfo =
+ try container.decodeIfPresent(Client.Info.self, forKey: .clientInfo)
+ ?? .init(name: "unknown", version: "0.0.0")
}
}
- public func encode(to encoder: Encoder) throws {
- switch self {
+ public struct Result: Hashable, Codable, Sendable {
+ public let protocolVersion: String
+ public let capabilities: Server.Capabilities
+ public let serverInfo: Server.Info
+ public let instructions: String?
+ public var _meta: Metadata?
+
+ public init(
+ protocolVersion: String,
+ capabilities: Server.Capabilities,
+ serverInfo: Server.Info,
+ instructions: String? = nil,
```
This interface is important because it defines how MCP Swift SDK Tutorial: Building MCP Clients and Servers in Swift implements the patterns covered in this chapter.
-### `Sources/MCP/Server/Completion.swift`
+### `Sources/MCP/Base/Lifecycle.swift`
-The `CodingKeys` interface in [`Sources/MCP/Server/Completion.swift`](https://github.com/modelcontextprotocol/swift-sdk/blob/HEAD/Sources/MCP/Server/Completion.swift) handles a key part of this chapter's functionality:
+The `CodingKeys` interface in [`Sources/MCP/Base/Lifecycle.swift`](https://github.com/modelcontextprotocol/swift-sdk/blob/HEAD/Sources/MCP/Base/Lifecycle.swift) handles a key part of this chapter's functionality:
```swift
- }
-
- private enum CodingKeys: String, CodingKey {
- case type, uri
- }
+ }
- public func encode(to encoder: Encoder) throws {
- var container = encoder.container(keyedBy: CodingKeys.self)
- try container.encode("ref/resource", forKey: .type)
- try container.encode(uri, forKey: .uri)
- }
+ private enum CodingKeys: String, CodingKey {
+ case protocolVersion, capabilities, clientInfo
+ }
- public init(from decoder: Decoder) throws {
- let container = try decoder.container(keyedBy: CodingKeys.self)
- let type = try container.decode(String.self, forKey: .type)
- guard type == "ref/resource" else {
- throw DecodingError.dataCorruptedError(
- forKey: .type,
- in: container,
- debugDescription: "Expected ref/resource type"
- )
+ public init(from decoder: Decoder) throws {
+ let container = try decoder.container(keyedBy: CodingKeys.self)
+ protocolVersion =
+ try container.decodeIfPresent(String.self, forKey: .protocolVersion)
+ ?? Version.latest
+ capabilities =
+ try container.decodeIfPresent(Client.Capabilities.self, forKey: .capabilities)
+ ?? .init()
+ clientInfo =
+ try container.decodeIfPresent(Client.Info.self, forKey: .clientInfo)
+ ?? .init(name: "unknown", version: "0.0.0")
}
- uri = try container.decode(String.self, forKey: .uri)
}
-}
-
-/// A reference type for completion requests (either prompt or resource)
-public enum CompletionReference: Hashable, Codable, Sendable {
- /// References a prompt by name
- case prompt(PromptReference)
- /// References a resource URI
- case resource(ResourceReference)
+
+ public struct Result: Hashable, Codable, Sendable {
+ public let protocolVersion: String
+ public let capabilities: Server.Capabilities
+ public let serverInfo: Server.Info
+ public let instructions: String?
+ public var _meta: Metadata?
+
+ public init(
+ protocolVersion: String,
+ capabilities: Server.Capabilities,
+ serverInfo: Server.Info,
+ instructions: String? = nil,
```
This interface is important because it defines how MCP Swift SDK Tutorial: Building MCP Clients and Servers in Swift implements the patterns covered in this chapter.
-### `Sources/MCP/Server/Completion.swift`
+### `Sources/MCP/Client/Roots.swift`
-The `Complete` interface in [`Sources/MCP/Server/Completion.swift`](https://github.com/modelcontextprotocol/swift-sdk/blob/HEAD/Sources/MCP/Server/Completion.swift) handles a key part of this chapter's functionality:
+The `Root` interface in [`Sources/MCP/Client/Roots.swift`](https://github.com/modelcontextprotocol/swift-sdk/blob/HEAD/Sources/MCP/Client/Roots.swift) handles a key part of this chapter's functionality:
```swift
-/// To get completion suggestions, clients send a `completion/complete` request.
-/// - SeeAlso: https://modelcontextprotocol.io/specification/2025-11-25/server/utilities/completion/
-public enum Complete: Method {
- public static let name = "completion/complete"
-
- public struct Parameters: Hashable, Codable, Sendable {
- /// The reference to what is being completed
- public let ref: CompletionReference
- /// The argument being completed
- public let argument: Argument
- /// Optional context with already-resolved arguments
- public let context: Context?
- public init(
- ref: CompletionReference,
- argument: Argument,
- context: Context? = nil
- ) {
- self.ref = ref
- self.argument = argument
- self.context = context
- }
-
- /// The argument being completed
- public struct Argument: Hashable, Codable, Sendable {
- /// The argument name
- public let name: String
- /// The current value (partial or complete)
- public let value: String
+/// The Model Context Protocol (MCP) provides a mechanism for clients to expose
+/// filesystem boundaries to servers through roots. Roots allow servers to understand
+/// the scope of filesystem access they can request, enabling safe and controlled
+/// file operations.
+///
+/// Unlike Resources/Tools/Prompts, Roots use bidirectional communication:
+/// - Servers send `roots/list` requests TO clients
+/// - Clients respond with available roots
+/// - Clients send `notifications/roots/list_changed` when roots change
+///
+/// - SeeAlso: https://modelcontextprotocol.io/specification/2025-11-25/client/roots
+public struct Root: Hashable, Codable, Sendable {
+ /// The root URI (must use file:// scheme)
+ public let uri: String
+ /// Optional human-readable name for the root
+ public let name: String?
+ /// Optional metadata
+ public var _meta: Metadata?
+
+ public init(
+ uri: String,
+ name: String? = nil,
+ _meta: Metadata? = nil
+ ) {
+ self.uri = uri
+ self.name = name
+ self._meta = _meta
+ }
- public init(name: String, value: String) {
- self.name = name
+ private enum CodingKeys: String, CodingKey {
+ case uri
```
This interface is important because it defines how MCP Swift SDK Tutorial: Building MCP Clients and Servers in Swift implements the patterns covered in this chapter.
@@ -212,11 +210,11 @@ This interface is important because it defines how MCP Swift SDK Tutorial: Build
```mermaid
flowchart TD
- A[CodingKeys]
- B[CompletionReference]
+ A[Initialize]
+ B[CodingKeys]
C[CodingKeys]
- D[Complete]
- E[CodingKeys]
+ D[Root]
+ E[Result]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcp-typescript-sdk-tutorial/01-getting-started-and-package-model.md b/tutorials/mcp-typescript-sdk-tutorial/01-getting-started-and-package-model.md
index fef8b546..fc2ce9de 100644
--- a/tutorials/mcp-typescript-sdk-tutorial/01-getting-started-and-package-model.md
+++ b/tutorials/mcp-typescript-sdk-tutorial/01-getting-started-and-package-model.md
@@ -5,100 +5,160 @@ nav_order: 1
parent: MCP TypeScript SDK Tutorial
---
-
# Chapter 1: Getting Started and Package Model
-Welcome to **Chapter 1: Getting Started and Package Model**. In this part of **MCP TypeScript SDK Tutorial: Building and Migrating MCP Clients and Servers in TypeScript**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
-
-
-This chapter establishes a clean package baseline for MCP TypeScript development.
+The MCP TypeScript SDK v2 is a monorepo of split packages that replaces the single `@modelcontextprotocol/sdk` from v1. This chapter establishes the correct package baseline, explains which packages serve which roles, and gets your first client and server running.
## Learning Goals
-- distinguish v1 and v2 branch expectations before coding
-- choose the right split packages for your use case
-- run first client/server examples from the monorepo
-- avoid dependency drift around `zod` and runtime versions
+- Distinguish v1 and v2 package structures before writing any code
+- Choose the right packages for your use case (client-only, server-only, both)
+- Run first server and client examples from the repository
+- Avoid dependency drift around `zod` and Node.js versions
-## First-Run Sequence
+## The v2 Package Split
+
+```mermaid
+graph TD
+ OLD[v1: @modelcontextprotocol/sdk\nMonolithic — everything in one package]
+
+ NEW[v2: Split packages]
+ NEW --> CORE[@modelcontextprotocol/core\nTypes, protocol, transport interfaces\nDo not import directly]
+ NEW --> CLIENT[@modelcontextprotocol/client\nClient + StdioClientTransport\n+ StreamableHTTPClientTransport + SSE]
+ NEW --> SERVER[@modelcontextprotocol/server\nMcpServer + StdioServerTransport\n+ WebStandardStreamableHTTPServerTransport]
+ NEW --> NODE[@modelcontextprotocol/node\nNodeStreamableHTTPServerTransport\nfor Node.js native http module]
+ NEW --> EXPRESS[@modelcontextprotocol/express\nExpress middleware + host validation]
+ NEW --> HONO[@modelcontextprotocol/hono\nHono web-standard adapter]
+```
-1. confirm Node.js 20+ for v2-oriented work
-2. install only needed packages (`client`, `server`, optional adapters)
-3. run example server and example client from repo docs
-4. lock package versions in your project before scaling usage
+`@modelcontextprotocol/core` is an internal package — import types from whichever of `client` or `server` you already depend on. They both re-export everything you need.
-## Package Baseline
+## Installation
```bash
-# client-only usage
-npm install @modelcontextprotocol/client zod
+# Client-only project
+npm install @modelcontextprotocol/client
+
+# Server-only project (stdio or web-standard HTTP)
+npm install @modelcontextprotocol/server
+
+# Server project using Node.js native http module
+npm install @modelcontextprotocol/server @modelcontextprotocol/node
-# server-only usage
-npm install @modelcontextprotocol/server zod
+# Server with Express integration
+npm install @modelcontextprotocol/server @modelcontextprotocol/express
-# node HTTP transport adapter
-npm install @modelcontextprotocol/node
+# Full-stack (client + server in same project)
+npm install @modelcontextprotocol/client @modelcontextprotocol/server
```
-## Source References
+**No zod needed in most cases** — v2 dropped the `zod` peer dependency. You can still use zod in your own server code for input validation, but it is no longer required by the SDK itself.
-- [TypeScript SDK README](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/README.md)
-- [Documents Index](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/docs/documents.md)
-- [FAQ - Zod recursion issue](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/docs/faq.md)
+## Runtime Requirements
-## Summary
+| Requirement | v1 | v2 |
+|:------------|:---|:---|
+| Node.js | 18+ | **20+** |
+| Module format | CJS + ESM | **ESM only** |
+| TypeScript | 4.x+ | 5.x recommended |
-You now have a stable package and runtime baseline for SDK work.
+If your project uses CommonJS (`require()`), you must either migrate to ESM or use dynamic `import()` calls.
-Next: [Chapter 2: Server Transports and Deployment Patterns](02-server-transports-and-deployment-patterns.md)
+## First Server (Minimal)
+
+```typescript
+// server.ts
+import { McpServer } from '@modelcontextprotocol/server';
+import { StdioServerTransport } from '@modelcontextprotocol/server';
+
+const server = new McpServer({
+ name: "my-server",
+ version: "1.0.0",
+});
+
+server.registerTool("hello", {
+ description: "Say hello",
+ inputSchema: { type: "object", properties: { name: { type: "string" } }, required: ["name"] },
+}, async ({ name }) => ({
+ content: [{ type: "text", text: `Hello, ${name}!` }]
+}));
-## Source Code Walkthrough
-
-### `scripts/cli.ts`
-
-The `runClient` function in [`scripts/cli.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/HEAD/scripts/cli.ts) handles a key part of this chapter's functionality:
-
-```ts
-import { ListResourcesResultSchema } from '../src/types.js';
-
-async function runClient(url_or_command: string, args: string[]) {
- const client = new Client(
- {
- name: 'mcp-typescript test client',
- version: '0.1.0'
- },
- {
- capabilities: {
- sampling: {}
- }
- }
- );
-
- let clientTransport;
-
- let url: URL | undefined = undefined;
- try {
- url = new URL(url_or_command);
- } catch {
- // Ignore
- }
-
- if (url?.protocol === 'http:' || url?.protocol === 'https:') {
- clientTransport = new SSEClientTransport(new URL(url_or_command));
- } else if (url?.protocol === 'ws:' || url?.protocol === 'wss:') {
- clientTransport = new WebSocketClientTransport(new URL(url_or_command));
- } else {
- clientTransport = new StdioClientTransport({
- command: url_or_command,
- args
+const transport = new StdioServerTransport();
+await server.connect(transport);
```
-This function is important because it defines how MCP TypeScript SDK Tutorial: Building and Migrating MCP Clients and Servers in TypeScript implements the patterns covered in this chapter.
+```bash
+npx ts-node server.ts
+# or after build:
+node dist/server.js
+```
+
+## First Client (Minimal)
+
+```typescript
+// client.ts
+import { Client } from '@modelcontextprotocol/client';
+import { StdioClientTransport } from '@modelcontextprotocol/client';
+const client = new Client({ name: "my-client", version: "1.0.0" });
+const transport = new StdioClientTransport({
+ command: "node",
+ args: ["dist/server.js"]
+});
-## How These Components Connect
+await client.connect(transport);
+
+const tools = await client.listTools();
+console.log("Tools:", tools.tools.map(t => t.name));
+
+const result = await client.callTool({ name: "hello", arguments: { name: "World" } });
+console.log("Result:", result.content[0].text);
+
+await client.close();
+```
+
+## Package Dependency Diagram
```mermaid
-flowchart TD
- A[runClient]
+graph LR
+ YOUR_PROJECT[Your Project]
+ YOUR_PROJECT --> CLIENT[@modelcontextprotocol/client]
+ YOUR_PROJECT --> SERVER[@modelcontextprotocol/server]
+ YOUR_PROJECT --> NODE[@modelcontextprotocol/node\noptional]
+ YOUR_PROJECT --> EXPRESS[@modelcontextprotocol/express\noptional]
+
+ CLIENT --> CORE[@modelcontextprotocol/core\nauto-installed]
+ SERVER --> CORE
+ NODE --> CORE
+ EXPRESS --> NODE
```
+
+All middleware packages depend on `core` transitively. You never need to add `core` to your own `package.json`.
+
+## v1 Import Map
+
+If you are migrating from v1, here is the import mapping:
+
+| v1 import path | v2 import |
+|:--------------|:----------|
+| `@modelcontextprotocol/sdk/client/index.js` | `@modelcontextprotocol/client` |
+| `@modelcontextprotocol/sdk/server/mcp.js` | `@modelcontextprotocol/server` |
+| `@modelcontextprotocol/sdk/types.js` | `@modelcontextprotocol/client` or `server` |
+| `@modelcontextprotocol/sdk/client/streamableHttp.js` | `@modelcontextprotocol/client` |
+| `@modelcontextprotocol/sdk/server/streamableHttp.js` | `@modelcontextprotocol/node` (renamed to `NodeStreamableHTTPServerTransport`) |
+| `@modelcontextprotocol/sdk/client/stdio.js` | `@modelcontextprotocol/client` |
+| `@modelcontextprotocol/sdk/server/stdio.js` | `@modelcontextprotocol/server` |
+
+## Source References
+
+- [TypeScript SDK README](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/README.md)
+- [Migration Guide (v1 → v2)](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/docs/migration.md)
+- [Client package README](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/README.md)
+- [Server package README](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/server/README.md)
+- [FAQ](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/docs/faq.md)
+
+## Summary
+
+The v2 SDK splits the monolithic `@modelcontextprotocol/sdk` into focused packages: `client`, `server`, `node`, `express`, `hono`. Node.js 20+ and ESM are required. Zod is no longer a peer dependency. The `core` package is internal — import from `client` or `server` instead. For new projects, install only the packages your role requires.
+
+Next: [Chapter 2: Server Transports and Deployment Patterns](02-server-transports-and-deployment-patterns.md)
diff --git a/tutorials/mcp-typescript-sdk-tutorial/02-server-transports-and-deployment-patterns.md b/tutorials/mcp-typescript-sdk-tutorial/02-server-transports-and-deployment-patterns.md
index fcbd05e4..babc63b0 100644
--- a/tutorials/mcp-typescript-sdk-tutorial/02-server-transports-and-deployment-patterns.md
+++ b/tutorials/mcp-typescript-sdk-tutorial/02-server-transports-and-deployment-patterns.md
@@ -5,94 +5,175 @@ nav_order: 2
parent: MCP TypeScript SDK Tutorial
---
-
# Chapter 2: Server Transports and Deployment Patterns
-Welcome to **Chapter 2: Server Transports and Deployment Patterns**. In this part of **MCP TypeScript SDK Tutorial: Building and Migrating MCP Clients and Servers in TypeScript**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
+Server architecture in the v2 TypeScript SDK begins with transport selection. The transport determines the deployment model, session management strategy, and which framework adapter (if any) you need. This chapter maps available transports to deployment scenarios.
+## Learning Goals
-Server design starts with transport choice and state model, not with tool code.
+- Choose between stateless and stateful StreamableHTTP modes
+- Understand where the legacy SSE transport still matters
+- Map deployment pattern to session and event storage strategy
+- Pick the right framework adapter for your runtime
-## Learning Goals
+## Transport Options Overview
-- choose between stateless and stateful Streamable HTTP modes
-- understand where deprecated SSE still matters
-- map deployment pattern to session/event storage strategy
-- pick framework adapter based on runtime constraints
+```mermaid
+graph TD
+ TRANSPORTS[Server Transports in v2]
+ TRANSPORTS --> STDIO[StdioServerTransport\n@modelcontextprotocol/server\nLocal subprocess - desktop clients]
+ TRANSPORTS --> WEB_STD[WebStandardStreamableHTTPServerTransport\n@modelcontextprotocol/server\nWeb-standard Request/Response APIs]
+ TRANSPORTS --> NODE_HTTP[NodeStreamableHTTPServerTransport\n@modelcontextprotocol/node\nNode.js native http module]
+ TRANSPORTS --> SSE_LEGACY[SSEServerTransport\n@modelcontextprotocol/server\nLegacy compatibility only]
+```
-## Deployment Pattern Matrix
+## Stdio Transport
-| Pattern | Best For | Tradeoff |
-|:--------|:---------|:---------|
-| Stateless Streamable HTTP | simple API-style servers | no resumability/session continuity |
-| Stateful + event store | richer interactions and resumability | external storage complexity |
-| Local state + message routing | sticky-session architectures | highest operational complexity |
+The simplest and most universal transport. Used by Claude Desktop, Cursor, Windsurf, and any MCP host that spawns servers as child processes.
-## Adapter Guidance
+```typescript
+import { McpServer } from '@modelcontextprotocol/server';
+import { StdioServerTransport } from '@modelcontextprotocol/server';
-- `@modelcontextprotocol/node` for Node `http` integration
-- `@modelcontextprotocol/express` for Express defaults + host validation helpers
-- `@modelcontextprotocol/hono` for web-standard request handling
+const server = new McpServer({ name: "my-server", version: "1.0.0" });
+// ... register tools, resources, prompts ...
+await server.connect(new StdioServerTransport());
+```
-## Source References
+No HTTP server, no port management, no sessions. The MCP protocol runs over stdin/stdout. All logging must go to `process.stderr` to avoid corrupting the JSON-RPC stream.
-- [Server Docs](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/docs/server.md)
-- [Server Examples Index](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/README.md)
-- [Node Adapter README](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/middleware/node/README.md)
+## Web-Standard StreamableHTTP Transport
-## Summary
+`WebStandardStreamableHTTPServerTransport` uses Web API types (`Request`, `Response`, `ReadableStream`) — compatible with any runtime that implements the Web Platform APIs: Hono, Cloudflare Workers, Deno, Bun, and Node.js with `@modelcontextprotocol/hono`.
-You now have a transport-first architecture model for server implementation.
+```typescript
+import { McpServer } from '@modelcontextprotocol/server';
+import { WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/server';
+import { Hono } from 'hono';
+import { createHonoHandler } from '@modelcontextprotocol/hono';
-Next: [Chapter 3: Client Transports, OAuth, and Backwards Compatibility](03-client-transports-oauth-and-backwards-compatibility.md)
+const app = new Hono();
+const server = new McpServer({ name: "my-server", version: "1.0.0" });
+
+// Stateless mode — no session storage needed
+app.all('/mcp', createHonoHandler({
+ serverFactory: () => server,
+ options: { stateless: true }
+}));
+```
+
+### Stateless vs Stateful Mode
+
+```mermaid
+flowchart LR
+ HTTP[Incoming HTTP request]
+ HTTP --> STATELESS{stateless: true?}
+ STATELESS -- Yes --> PROC[Process request\nNo session storage\nNo event resumption]
+ STATELESS -- No --> SESSION[Look up or create session\nby Mcp-Session-Id header]
+ SESSION --> STORE[Persist events in event store\nfor SSE resumption support]
+ PROC --> RESP[HTTP response]
+ STORE --> RESP
+```
+
+**Stateless mode** (`stateless: true`):
+- Each request is independent — no session state
+- No external storage needed
+- Cannot resume interrupted SSE streams
+- Ideal for simple request-response tool servers
-## Source Code Walkthrough
+**Stateful mode** (default):
+- Each client gets a session ID in the `Mcp-Session-Id` header
+- Server maintains session state (connection, pending requests)
+- Requires an event store for SSE stream resumption
+- Supports long-running tool executions and streaming results
-### `scripts/cli.ts`
+## Node.js StreamableHTTP Transport
-The `runServer` function in [`scripts/cli.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/HEAD/scripts/cli.ts) handles a key part of this chapter's functionality:
+`NodeStreamableHTTPServerTransport` (from `@modelcontextprotocol/node`) wraps the Node.js `http.IncomingMessage`/`http.ServerResponse` types. Use this when you're running Node.js native `http` or Express.
-```ts
-}
+```typescript
+import { createServer } from 'node:http';
+import { McpServer } from '@modelcontextprotocol/server';
+import { NodeStreamableHTTPServerTransport } from '@modelcontextprotocol/node';
+import { createNodeHandler } from '@modelcontextprotocol/node';
-async function runServer(port: number | null) {
- if (port !== null) {
- const app = express();
+const server = new McpServer({ name: "my-server", version: "1.0.0" });
+// register tools...
- let servers: Server[] = [];
+const httpServer = createServer(createNodeHandler({
+ serverFactory: () => server,
+ options: { stateless: true }
+}));
- app.get('/sse', async (req, res) => {
- console.log('Got new SSE connection');
+httpServer.listen(3000);
+```
- const transport = new SSEServerTransport('/message', res);
- const server = new Server(
- {
- name: 'mcp-typescript test server',
- version: '0.1.0'
- },
- {
- capabilities: {}
- }
- );
+## Express Adapter
- servers.push(server);
+```typescript
+import express from 'express';
+import { McpServer } from '@modelcontextprotocol/server';
+import { createExpressHandler } from '@modelcontextprotocol/express';
- server.onclose = () => {
- console.log('SSE connection closed');
- servers = servers.filter(s => s !== server);
- };
+const app = express();
+const server = new McpServer({ name: "my-server", version: "1.0.0" });
- await server.connect(transport);
- });
+app.all('/mcp', createExpressHandler({
+ serverFactory: () => server
+}));
+app.listen(3000);
```
-This function is important because it defines how MCP TypeScript SDK Tutorial: Building and Migrating MCP Clients and Servers in TypeScript implements the patterns covered in this chapter.
+The Express adapter also provides host validation middleware (see Chapter 6).
+
+## Deployment Pattern Matrix
+
+| Pattern | Transport | State | Event Store | Use Case |
+|:--------|:----------|:------|:-----------|:---------|
+| Local desktop | Stdio | N/A | None | Claude Desktop, Cursor |
+| Simple API server | Web-standard / Node, stateless | None | None | Read-only tools, fast responses |
+| Streaming server | Node, stateful | Session map | InMemory or Redis | Long-running jobs, stream results |
+| Edge/Serverless | Web-standard, stateless | None | None | Cloudflare Workers, Vercel Edge |
+| Enterprise | Express/Hono, stateful | Session map | Persistent store | High availability, resumable sessions |
+
+## Legacy SSE Transport
+The `SSEServerTransport` is preserved for backward compatibility with clients that don't support StreamableHTTP. Do not use it for new deployments.
-## How These Components Connect
+```typescript
+// Legacy SSE — only for compatibility with old clients
+import { SSEServerTransport } from '@modelcontextprotocol/server';
+
+app.get('/sse', async (req, res) => {
+ const transport = new SSEServerTransport('/messages', res);
+ await server.connect(transport);
+});
+
+app.post('/messages', async (req, res) => {
+ await transport.handlePostMessage(req, res);
+});
+```
```mermaid
-flowchart TD
- A[runServer]
+graph LR
+ CLIENT_OLD[Old MCP Client\nSSE-only]
+ CLIENT_NEW[Modern MCP Client\nStreamableHTTP]
+
+ CLIENT_OLD --> SSE[Legacy SSEServerTransport\nTwo-endpoint model]
+ CLIENT_NEW --> STREAMABLE[StreamableHTTPServerTransport\nSingle-endpoint model]
```
+
+## Source References
+
+- [Server Docs](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/docs/server.md)
+- [Server package source: `streamableHttp.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/server/src/server/streamableHttp.ts)
+- [Server package source: `stdio.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/server/src/server/stdio.ts)
+- [Simple StreamableHTTP example](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/src/simpleStreamableHttp.ts)
+- [Stateless StreamableHTTP example](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/src/simpleStatelessStreamableHttp.ts)
+
+## Summary
+
+Start with `StdioServerTransport` for local desktop clients — no HTTP layer needed. For remote/hosted servers, use `WebStandardStreamableHTTPServerTransport` (Hono/Workers/Bun) or `NodeStreamableHTTPServerTransport` (Node.js/Express). Stateless mode suits simple tool servers; stateful mode is needed for streaming, resumable connections, and multi-turn interactions. Avoid the legacy SSE transport for new work.
+
+Next: [Chapter 3: Client Transports, OAuth, and Backwards Compatibility](03-client-transports-oauth-and-backwards-compatibility.md)
diff --git a/tutorials/mcp-typescript-sdk-tutorial/03-client-transports-oauth-and-backwards-compatibility.md b/tutorials/mcp-typescript-sdk-tutorial/03-client-transports-oauth-and-backwards-compatibility.md
index 7650f53e..eb6c9937 100644
--- a/tutorials/mcp-typescript-sdk-tutorial/03-client-transports-oauth-and-backwards-compatibility.md
+++ b/tutorials/mcp-typescript-sdk-tutorial/03-client-transports-oauth-and-backwards-compatibility.md
@@ -5,87 +5,195 @@ nav_order: 3
parent: MCP TypeScript SDK Tutorial
---
-
# Chapter 3: Client Transports, OAuth, and Backwards Compatibility
-Welcome to **Chapter 3: Client Transports, OAuth, and Backwards Compatibility**. In this part of **MCP TypeScript SDK Tutorial: Building and Migrating MCP Clients and Servers in TypeScript**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
-
-
-Client reliability depends on explicit transport behavior and robust auth handling.
+Client reliability depends on correct transport selection, robust auth handling, and a fallback strategy for connecting to older servers. This chapter covers the v2 client API, OAuth integration, and the StreamableHTTP-to-SSE fallback pattern.
## Learning Goals
-- connect clients over stdio, Streamable HTTP, and legacy SSE pathways
-- implement fallback flow from HTTP to SSE for older servers
-- apply OAuth helpers for secure remote server access
-- structure client operations for parallel and multi-server usage
+- Connect clients over stdio, StreamableHTTP, and legacy SSE transports
+- Implement the SSE fallback flow for servers that don't support StreamableHTTP
+- Apply OAuth helpers for secure remote server access
+- Structure client operations for parallel and multi-server usage
-## Practical Client Pattern
+## Client Transport Options
-1. prefer Streamable HTTP client transport
-2. detect known legacy cases and apply SSE fallback
-3. use high-level methods (`listTools`, `callTool`, `listResources`)
-4. persist auth/token context in tested provider implementations
+```mermaid
+graph TD
+ CLIENT[MCP Client\n@modelcontextprotocol/client]
+ CLIENT --> STDIO[StdioClientTransport\nSpawn subprocess, communicate via stdin/stdout]
+ CLIENT --> HTTP[StreamableHTTPClientTransport\nModern remote server connection]
+ CLIENT --> SSE[SSEClientTransport\nLegacy server compatibility]
+ CLIENT --> HTTP_FALLBACK[streamableHttpWithSseFallback\nTry HTTP first, fall back to SSE]
+```
-## Source References
+## Stdio Client Transport
-- [Client Docs](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/docs/client.md)
-- [Client Examples Index](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/client/README.md)
-- [Streamable HTTP Fallback Example](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/client/src/streamableHttpWithSseFallbackClient.ts)
+```typescript
+import { Client } from '@modelcontextprotocol/client';
+import { StdioClientTransport } from '@modelcontextprotocol/client';
-## Summary
+const client = new Client(
+ { name: "my-client", version: "1.0.0" },
+ { capabilities: { sampling: {} } }
+);
-You now have a stronger strategy for client transport and auth compatibility.
+const transport = new StdioClientTransport({
+ command: "node",
+ args: ["path/to/server.js"],
+ env: { MY_API_KEY: process.env.MY_API_KEY! }
+});
-Next: [Chapter 4: Tool, Resource, Prompt Design and Completions](04-tool-resource-prompt-design-and-completions.md)
+await client.connect(transport);
+```
-## Source Code Walkthrough
-
-### `scripts/sync-snippets.ts`
-
-The `findLabeledCodeFences` function in [`scripts/sync-snippets.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/HEAD/scripts/sync-snippets.ts) handles a key part of this chapter's functionality:
-
-```ts
- * @returns Array of labeled code fence references
- */
-function findLabeledCodeFences(
- content: string,
- filePath: string,
- mode: FileMode,
-): LabeledCodeFence[] {
- const results: LabeledCodeFence[] = [];
- const lines = content.split('\n');
- let charIndex = 0;
-
- // Select patterns based on mode
- const openPattern =
- mode === 'jsdoc'
- ? JSDOC_LABELED_FENCE_PATTERN
- : MARKDOWN_LABELED_FENCE_PATTERN;
- const closePattern =
- mode === 'jsdoc'
- ? JSDOC_CLOSING_FENCE_PATTERN
- : MARKDOWN_CLOSING_FENCE_PATTERN;
-
- for (let i = 0; i < lines.length; i++) {
- const line = lines[i];
- const openMatch = line.match(openPattern);
-
- if (openMatch) {
- let linePrefix: string;
- let language: string;
- let displayName: string | undefined;
- let examplePath: string;
- let regionName: string;
+The client spawns the server process and manages its lifecycle. When `client.close()` is called, the subprocess is terminated.
-```
+## StreamableHTTP Client Transport
-This function is important because it defines how MCP TypeScript SDK Tutorial: Building and Migrating MCP Clients and Servers in TypeScript implements the patterns covered in this chapter.
+```typescript
+import { Client } from '@modelcontextprotocol/client';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/client';
+const client = new Client({ name: "my-client", version: "1.0.0" });
+const transport = new StreamableHTTPClientTransport(
+ new URL("https://my-mcp-server.example.com/mcp")
+);
-## How These Components Connect
+await client.connect(transport);
+const { tools } = await client.listTools();
+```
+
+The transport handles the `Mcp-Session-Id` header automatically for stateful servers. For stateless servers, each request is independent.
+
+## SSE-to-StreamableHTTP Fallback
+
+When building a client that needs to connect to both modern (StreamableHTTP) and legacy (SSE) servers, use the fallback pattern:
+
+```typescript
+// From examples/client/src/streamableHttpWithSseFallbackClient.ts
+import { Client } from '@modelcontextprotocol/client';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/client';
+import { SSEClientTransport } from '@modelcontextprotocol/client';
+
+const url = new URL("https://mcp-server.example.com/mcp");
+
+async function connectWithFallback(client: Client, url: URL) {
+ try {
+ // Try StreamableHTTP first
+ const httpTransport = new StreamableHTTPClientTransport(url);
+ await client.connect(httpTransport);
+ console.log("Connected via StreamableHTTP");
+ } catch (error) {
+ if (error.code === "METHOD_NOT_ALLOWED" || error.status === 405) {
+ // Fall back to SSE (legacy server)
+ const sseUrl = new URL(url.toString().replace('/mcp', '/sse'));
+ const sseTransport = new SSEClientTransport(sseUrl);
+ await client.connect(sseTransport);
+ console.log("Connected via SSE (legacy fallback)");
+ } else {
+ throw error;
+ }
+ }
+}
+```
```mermaid
flowchart TD
- A[findLabeledCodeFences]
+ CONNECT[Connect to server at URL]
+ CONNECT --> TRY_HTTP[Try StreamableHTTPClientTransport]
+ TRY_HTTP --> HTTP_OK{Success?}
+ HTTP_OK -- Yes --> CONNECTED[Connected via StreamableHTTP]
+ HTTP_OK -- No 405 --> FALLBACK[Try SSEClientTransport\nat /sse endpoint]
+ FALLBACK --> SSE_OK{Success?}
+ SSE_OK -- Yes --> CONNECTED_SSE[Connected via SSE\nlegacy server]
+ SSE_OK -- No --> FAIL[Connection failed]
+```
+
+## OAuth Authentication
+
+The SDK includes a complete OAuth 2.0 client implementation for authenticating with servers that require it. The client supports the Authorization Code flow with PKCE.
+
+```typescript
+import { Client } from '@modelcontextprotocol/client';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/client';
+import { OAuthClientProvider } from '@modelcontextprotocol/client';
+
+// Implement OAuthClientProvider to handle token storage and refresh
+class MyOAuthProvider implements OAuthClientProvider {
+ get redirectUrl() { return "http://localhost:3000/callback"; }
+ get clientMetadata() { return { client_name: "My App", redirect_uris: [this.redirectUrl] }; }
+
+ async tokens() { return loadTokensFromStorage(); }
+ async saveTokens(tokens) { saveTokensToStorage(tokens); }
+ async redirectToAuthorization(url) { openBrowser(url); }
+ async saveCodeVerifier(verifier) { saveToStorage("verifier", verifier); }
+ async codeVerifier() { return loadFromStorage("verifier"); }
+}
+
+const transport = new StreamableHTTPClientTransport(
+ new URL("https://secure-server.example.com/mcp"),
+ { authProvider: new MyOAuthProvider() }
+);
+
+const client = new Client({ name: "my-client", version: "1.0.0" });
+await client.connect(transport); // triggers OAuth flow if not authenticated
+```
+
+## Token Provider (Simpler Auth)
+
+For servers that use simple API tokens instead of full OAuth flows, use `TokenProvider`:
+
+```typescript
+import { TokenProvider } from '@modelcontextprotocol/client';
+
+const transport = new StreamableHTTPClientTransport(
+ new URL("https://my-server.example.com/mcp"),
+ {
+ authProvider: new TokenProvider({
+ getToken: async () => process.env.MCP_API_TOKEN!
+ })
+ }
+);
+```
+
+## Parallel Multi-Server Client
+
+```typescript
+// Connect to multiple servers in parallel
+const servers = [
+ { name: "filesystem", command: "npx", args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"] },
+ { name: "firecrawl", command: "npx", args: ["-y", "firecrawl-mcp"] },
+];
+
+const clients = await Promise.all(
+ servers.map(async ({ name, command, args }) => {
+ const client = new Client({ name: `client-${name}`, version: "1.0.0" });
+ const transport = new StdioClientTransport({ command, args });
+ await client.connect(transport);
+ return { name, client };
+ })
+);
+
+// List all tools from all servers
+const allTools = (await Promise.all(
+ clients.map(async ({ name, client }) => {
+ const { tools } = await client.listTools();
+ return tools.map(t => ({ server: name, ...t }));
+ })
+)).flat();
```
+
+## Source References
+
+- [Client Docs](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/docs/client.md)
+- [Client package source: `auth.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/src/client/auth.ts)
+- [Client package source: `streamableHttp.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/src/client/streamableHttp.ts)
+- [StreamableHTTP fallback example](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/client/src/streamableHttpWithSseFallbackClient.ts)
+- [Simple OAuth client example](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/client/src/simpleOAuthClient.ts)
+
+## Summary
+
+The v2 client supports three transports: stdio (for subprocess servers), StreamableHTTP (for modern remote servers), and SSE (legacy compatibility). Implement the HTTP→SSE fallback pattern for universal server compatibility. OAuth and token-based auth are handled through the `authProvider` option on `StreamableHTTPClientTransport`. Connect multiple servers in parallel using `Promise.all` and merge their tool catalogs for multi-server agent architectures.
+
+Next: [Chapter 4: Tool, Resource, Prompt Design and Completions](04-tool-resource-prompt-design-and-completions.md)
diff --git a/tutorials/mcp-typescript-sdk-tutorial/04-tool-resource-prompt-design-and-completions.md b/tutorials/mcp-typescript-sdk-tutorial/04-tool-resource-prompt-design-and-completions.md
index 8da1223f..a51c51e2 100644
--- a/tutorials/mcp-typescript-sdk-tutorial/04-tool-resource-prompt-design-and-completions.md
+++ b/tutorials/mcp-typescript-sdk-tutorial/04-tool-resource-prompt-design-and-completions.md
@@ -5,88 +5,238 @@ nav_order: 4
parent: MCP TypeScript SDK Tutorial
---
-
# Chapter 4: Tool, Resource, Prompt Design and Completions
-Welcome to **Chapter 4: Tool, Resource, Prompt Design and Completions**. In this part of **MCP TypeScript SDK Tutorial: Building and Migrating MCP Clients and Servers in TypeScript**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
-
-
-Core server interface quality depends on well-structured tools, resources, and prompts.
+The quality of an MCP server depends on well-structured tools, resources, and prompts. The v2 SDK provides `McpServer.registerTool()`, `registerResource()`, and `registerPrompt()` with explicit schema and handler patterns. This chapter covers each primitive's design model and the completions feature for better UX.
## Learning Goals
-- build tool handlers with explicit input and output schemas
-- expose resources for stable read-oriented access patterns
-- design prompt templates for repeatable human/model workflows
-- use completions for better UX in prompt/resource argument entry
-
-## Design Rules
+- Build tool handlers with explicit input and output schemas
+- Expose resources with stable URI patterns and correct content types
+- Design prompt templates for repeatable human/model workflows
+- Use completions to assist selection in prompt and resource argument entry
-| Surface | Rule of Thumb |
-|:--------|:--------------|
-| Tools | side effects allowed, schemas should be strict |
-| Resources | read-focused, low side effects |
-| Prompts | reusable templates, minimal ambiguity |
-| Completions | assist selection without hiding underlying model |
+## `McpServer` Registration Model
-## Source References
-
-- [Server Docs - Tools, Resources, Prompts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/docs/server.md)
-- [Simple Streamable HTTP Example](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/src/simpleStreamableHttp.ts)
+```mermaid
+graph TD
+ MCP[McpServer instance]
+ MCP --> RT[registerTool\nname + schema + handler]
+ MCP --> RR[registerResource\nuri template + handler]
+ MCP --> RP[registerPrompt\nname + arguments + handler]
+ MCP --> RC[setCompletionHandler\nfor prompt/resource arg completion]
+
+ RT --> TOOL_RESP[Returns: {content: [...TextContent | ImageContent | EmbeddedResource]}]
+ RR --> RES_RESP[Returns: {contents: [{uri, text/blob, mimeType}]}]
+ RP --> PROMPT_RESP[Returns: {messages: [UserMessage | AssistantMessage]}]
+```
-## Summary
+## Tool Design
+
+Tools are callable functions. The LLM decides when to invoke them based on names and descriptions. Side effects are acceptable.
+
+```typescript
+import { McpServer } from '@modelcontextprotocol/server';
+
+const server = new McpServer({ name: "my-server", version: "1.0.0" });
+
+server.registerTool("search_documents", {
+ description: "Search the document store for relevant results. Returns up to 10 matches.",
+ inputSchema: {
+ type: "object",
+ properties: {
+ query: {
+ type: "string",
+ description: "Search query string"
+ },
+ limit: {
+ type: "integer",
+ minimum: 1,
+ maximum: 50,
+ default: 10,
+ description: "Maximum number of results"
+ }
+ },
+ required: ["query"]
+ },
+ // Output schema (v2 feature — describes structured output)
+ outputSchema: {
+ type: "object",
+ properties: {
+ results: {
+ type: "array",
+ items: { type: "object", properties: { title: { type: "string" }, score: { type: "number" } } }
+ }
+ }
+ }
+}, async ({ query, limit = 10 }) => {
+ const results = await db.search(query, limit);
+ return {
+ content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
+ // Structured output (when outputSchema is provided)
+ structuredContent: { results }
+ };
+});
+```
-You now have clearer interface design standards for MCP server surfaces.
+### Tool Design Rules
+
+| Rule | Rationale |
+|:-----|:---------|
+| Description is an instruction, not a label | LLM reads description to decide when to call |
+| `required` fields should be minimal | Optional fields reduce required LLM precision |
+| Validate inputs, return error text for bad inputs | Never throw — return error in `content` |
+| Side-effectful tools need clear descriptions | Users need to understand what will happen |
+| Output schemas improve structured result parsing | Client can validate and parse reliably |
+
+## Resource Design
+
+Resources are URI-addressed data blobs for read-oriented access. They do not execute side effects.
+
+```typescript
+// Static resource (fixed URI)
+server.registerResource(
+ "config",
+ "config://app/settings",
+ {
+ name: "Application Settings",
+ description: "Current application configuration",
+ mimeType: "application/json"
+ },
+ async (uri) => ({
+ contents: [{
+ uri: uri.href,
+ text: JSON.stringify(await loadConfig(), null, 2),
+ mimeType: "application/json"
+ }]
+ })
+);
+
+// Dynamic resource with URI template
+server.registerResource(
+ "note",
+ new ResourceTemplate("note://internal/{noteId}", { list: undefined }),
+ {
+ name: "Note",
+ description: "A stored note by ID",
+ mimeType: "text/plain"
+ },
+ async (uri, { noteId }) => {
+ const note = await db.getNote(noteId);
+ if (!note) throw new Error(`Note ${noteId} not found`);
+ return {
+ contents: [{ uri: uri.href, text: note.content, mimeType: "text/plain" }]
+ };
+ }
+);
+```
-Next: [Chapter 5: Sampling, Elicitation, and Experimental Tasks](05-sampling-elicitation-and-experimental-tasks.md)
+### Resource URI Conventions
+
+| Scheme | Use Case | Example |
+|:-------|:---------|:--------|
+| `file://` | File system resources | `file:///home/user/docs/report.pdf` |
+| Custom scheme | Application data | `note://internal/42`, `db://users/alice` |
+| `https://` | Remote resources (proxied) | `https://api.example.com/data/1` |
+
+## Prompt Design
+
+Prompts are server-defined message templates. They return message arrays for the client to inject into conversation context.
+
+```typescript
+server.registerPrompt(
+ "code_review",
+ {
+ description: "Generate a code review for a pull request",
+ arguments: [
+ {
+ name: "diff",
+ description: "The git diff to review",
+ required: true
+ },
+ {
+ name: "focus",
+ description: "Review focus: 'security', 'performance', 'style'",
+ required: false
+ }
+ ]
+ },
+ async ({ diff, focus = "general" }) => ({
+ messages: [
+ {
+ role: "user",
+ content: {
+ type: "text",
+ text: `Please review the following code diff with focus on ${focus}:\n\n${diff}`
+ }
+ }
+ ]
+ })
+);
+```
-## Source Code Walkthrough
-
-### `scripts/sync-snippets.ts`
-
-The `dedent` function in [`scripts/sync-snippets.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/HEAD/scripts/sync-snippets.ts) handles a key part of this chapter's functionality:
-
-```ts
-/**
- * Dedent content by removing a base indentation prefix from each line.
- * @param content The content to dedent
- * @param baseIndent The indentation to remove
- * @returns The dedented content
- */
-function dedent(content: string, baseIndent: string): string {
- const lines = content.split('\n');
- const dedentedLines = lines.map((line) => {
- // Preserve empty lines as-is
- if (line.trim() === '') return '';
- // Remove the base indentation if present
- if (line.startsWith(baseIndent)) {
- return line.slice(baseIndent.length);
+## Completions
+
+Completions allow servers to provide autocomplete suggestions for prompt argument values and resource URI template parameters. This enables UIs to build contextual dropdown menus.
+
+```typescript
+import { Completable } from '@modelcontextprotocol/server';
+
+server.registerPrompt(
+ "summarize_document",
+ {
+ arguments: [
+ {
+ name: "document_id",
+ description: "Document to summarize",
+ required: true,
+ // Mark as completable
+ complete: true
+ }
+ ]
+ },
+ async ({ document_id }) => { /* ... */ }
+);
+
+// Register completion handler for the argument
+server.setCompletionHandler(async ({ ref, argument }) => {
+ if (ref.type === "ref/prompt" && ref.name === "summarize_document") {
+ if (argument.name === "document_id") {
+ const docs = await db.listDocuments(argument.value);
+ return {
+ completion: {
+ values: docs.map(d => d.id),
+ hasMore: docs.length === 10,
+ total: docs.total
+ }
+ };
}
- // Line has less indentation than base - keep as-is
- return line;
- });
-
- // Trim trailing empty lines
- while (
- dedentedLines.length > 0 &&
- dedentedLines[dedentedLines.length - 1] === ''
- ) {
- dedentedLines.pop();
}
+ return { completion: { values: [] } };
+});
+```
- return dedentedLines.join('\n');
-}
-
-/**
- * Extract a region from an example file.
+```mermaid
+sequenceDiagram
+ participant UI
+ participant Client
+ participant Server
+
+ UI->>Client: User types "doc" in document_id field
+ Client->>Server: completion/complete {ref: {name: "summarize_document"}, argument: {name: "document_id", value: "doc"}}
+ Server-->>Client: {values: ["doc-1", "doc-23", "document-final"]}
+ Client-->>UI: Show dropdown with suggestions
```
-This function is important because it defines how MCP TypeScript SDK Tutorial: Building and Migrating MCP Clients and Servers in TypeScript implements the patterns covered in this chapter.
+## Source References
+- [Server Docs — Tools, Resources, Prompts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/docs/server.md)
+- [McpServer source: `mcp.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/server/src/server/mcp.ts)
+- [Completable source: `completable.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/server/src/server/completable.ts)
+- [Simple StreamableHTTP example](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/src/simpleStreamableHttp.ts)
-## How These Components Connect
+## Summary
-```mermaid
-flowchart TD
- A[dedent]
-```
+Use `registerTool` for callable side-effectful operations, `registerResource` for URI-addressed reads, and `registerPrompt` for reusable message templates. Write tool descriptions as instructions for the LLM. Return error text in `content` rather than throwing. Use `outputSchema` for structured results. Completions (via `setCompletionHandler`) improve UX for argument entry in prompt and resource forms.
+
+Next: [Chapter 5: Sampling, Elicitation, and Experimental Tasks](05-sampling-elicitation-and-experimental-tasks.md)
diff --git a/tutorials/mcp-typescript-sdk-tutorial/05-sampling-elicitation-and-experimental-tasks.md b/tutorials/mcp-typescript-sdk-tutorial/05-sampling-elicitation-and-experimental-tasks.md
index 5931112a..08b63f8e 100644
--- a/tutorials/mcp-typescript-sdk-tutorial/05-sampling-elicitation-and-experimental-tasks.md
+++ b/tutorials/mcp-typescript-sdk-tutorial/05-sampling-elicitation-and-experimental-tasks.md
@@ -5,87 +5,204 @@ nav_order: 5
parent: MCP TypeScript SDK Tutorial
---
-
# Chapter 5: Sampling, Elicitation, and Experimental Tasks
-Welcome to **Chapter 5: Sampling, Elicitation, and Experimental Tasks**. In this part of **MCP TypeScript SDK Tutorial: Building and Migrating MCP Clients and Servers in TypeScript**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
-
-
-Advanced capabilities should be introduced intentionally, with clear user and security boundaries.
+Advanced capabilities in the v2 SDK allow servers to request LLM inference (sampling), ask clients for structured user input (elicitation), and manage long-running agentic workflows (experimental tasks). This chapter covers when and how to use each, with security boundaries clearly marked.
## Learning Goals
-- add sampling for server-initiated model calls when appropriate
-- choose form vs URL elicitation based on data sensitivity
-- understand task-based execution lifecycle and experimental status
-- avoid coupling experimental task APIs to critical production paths
+- Add sampling for server-initiated LLM inference when appropriate
+- Choose form elicitation versus URL elicitation based on data sensitivity
+- Understand the experimental task API lifecycle and its current status
+- Avoid coupling experimental APIs to critical production paths
-## Capability Safety Guidance
+## Sampling: Server-Initiated LLM Calls
-- use form elicitation only for non-sensitive input
-- use URL elicitation for sensitive/credential workflows
-- treat experimental tasks API as opt-in with rollback plan
+Sampling allows a server to request that the host perform LLM inference on its behalf. This is how servers implement agentic loop behavior without holding API keys.
-## Source References
+```mermaid
+sequenceDiagram
+ participant Server
+ participant Client
+ participant Host
+ participant LLM
+
+ Server->>Client: sampling/createMessage {messages, modelPrefs, maxTokens}
+ Client->>Host: forward request
+ Host->>Host: Optional: show to user for approval
+ Host->>LLM: call with messages
+ LLM-->>Host: completion
+ Host-->>Client: result
+ Client-->>Server: CreateMessageResult
+```
-- [Capabilities Docs](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/docs/capabilities.md)
-- [Elicitation Form Example](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/src/elicitationFormExample.ts)
-- [Elicitation URL Example](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/src/elicitationUrlExample.ts)
-- [Task + Sampling Example](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/src/toolWithSampleServer.ts)
+### Capability Negotiation
-## Summary
+Servers must check that the client supports sampling before calling it:
-You now understand when and how to use advanced capability flows without overexposing risk.
+```typescript
+import { Server } from '@modelcontextprotocol/server';
-Next: [Chapter 6: Middleware, Security, and Host Validation](06-middleware-security-and-host-validation.md)
+const server = new Server({ name: "sampling-server", version: "1.0.0" });
-## Source Code Walkthrough
-
-### `scripts/sync-snippets.ts`
-
-The `extractRegion` function in [`scripts/sync-snippets.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/HEAD/scripts/sync-snippets.ts) handles a key part of this chapter's functionality:
-
-```ts
- * @returns The dedented region content
- */
-function extractRegion(
- exampleContent: string,
- regionName: string,
- examplePath: string,
-): string {
- // Region extraction only supported for .ts files (uses //#region syntax)
- if (!examplePath.endsWith('.ts')) {
- throw new Error(
- `Region extraction (#${regionName}) is only supported for .ts files. ` +
- `Use full-file inclusion (without #regionName) for: ${examplePath}`,
- );
+server.setRequestHandler(/* tool call */, async (request, context) => {
+ // Check capability before using
+ if (!context.clientCapabilities?.sampling) {
+ return {
+ content: [{ type: "text", text: "Error: client does not support sampling" }]
+ };
}
- const lineEnding = exampleContent.includes('\r\n') ? '\r\n' : '\n';
- const regionStart = `//#region ${regionName}${lineEnding}`;
- const regionEnd = `//#endregion ${regionName}${lineEnding}`;
+ const result = await server.createMessage({
+ messages: [
+ { role: "user", content: { type: "text", text: `Summarize: ${document}` } }
+ ],
+ maxTokens: 500,
+ modelPreferences: {
+ hints: [{ name: "claude-3-haiku" }], // prefer fast/cheap model
+ costPriority: 0.8,
+ speedPriority: 0.5,
+ intelligencePriority: 0.2
+ }
+ });
+
+ return {
+ content: [{ type: "text", text: result.content.text }]
+ };
+});
+```
+
+**Human-in-the-loop**: The host is responsible for applying safety policies and may show the sampling request to the user. The server cannot control whether the request is shown or modified.
+
+## Elicitation: Requesting User Input
+
+Elicitation allows a server to pause execution and ask the user for additional input through the host UI. The v2 SDK supports two elicitation modes.
- const startIndex = exampleContent.indexOf(regionStart);
- if (startIndex === -1) {
- throw new Error(`Region "${regionName}" not found in ${examplePath}`);
+```mermaid
+graph LR
+ ELICIT[Server needs user input]
+ ELICIT --> FORM[Form elicitation\nelicitation/create with schema\nHost renders a form]
+ ELICIT --> URL[URL elicitation\nelicitation/create with url\nHost opens a browser URL]
+
+ FORM --> SENSITIVE{Data sensitive?}
+ SENSITIVE -- No --> USE_FORM[Use form elicitation\ne.g., preferences, settings]
+ SENSITIVE -- Yes --> USE_URL[Use URL elicitation\ne.g., OAuth credentials\nexternal auth flow]
+```
+
+### Form Elicitation
+
+Use for non-sensitive structured input — preferences, filter criteria, configuration parameters:
+
+```typescript
+// From examples/server/src/elicitationFormExample.ts
+const elicitResult = await server.elicitInput({
+ message: "Please provide search parameters",
+ requestedSchema: {
+ type: "object",
+ properties: {
+ query: { type: "string", description: "Search query" },
+ maxResults: { type: "integer", minimum: 1, maximum: 100, default: 10 },
+ includeArchived: { type: "boolean", default: false }
+ },
+ required: ["query"]
}
+});
+
+if (elicitResult.action === "accept") {
+ const { query, maxResults, includeArchived } = elicitResult.content;
+ // proceed with validated input
+} else {
+ // user declined
+}
+```
+
+### URL Elicitation
+
+Use for flows where sensitive credentials or external authorization are needed:
- const endIndex = exampleContent.indexOf(regionEnd, startIndex);
- if (endIndex === -1) {
- throw new Error(
- `Region end marker for "${regionName}" not found in ${examplePath}`,
- );
+```typescript
+// From examples/server/src/elicitationUrlExample.ts
+const elicitResult = await server.elicitInput({
+ message: "Please authorize access to your calendar",
+ url: {
+ href: "https://auth.example.com/oauth/authorize?client_id=my-app&scope=calendar",
+ title: "Authorize Calendar Access"
}
+});
- // Get content after the region start line
+// After user completes the OAuth flow at the URL, the result contains
+// the authorization code or callback data
```
-This function is important because it defines how MCP TypeScript SDK Tutorial: Building and Migrating MCP Clients and Servers in TypeScript implements the patterns covered in this chapter.
+## Experimental Tasks API
+The tasks API provides a structured way to manage long-running agentic operations. It is marked **experimental** — available in `@modelcontextprotocol/server/experimental` — and should not be used on critical production paths.
-## How These Components Connect
+```typescript
+import { McpServer } from '@modelcontextprotocol/server';
+import { withExperimentalTasks } from '@modelcontextprotocol/server/experimental';
+
+const server = withExperimentalTasks(
+ new McpServer({ name: "task-server", version: "1.0.0" }),
+ {
+ maxConcurrentTasks: 10,
+ taskTimeoutMs: 60_000
+ }
+);
+
+server.registerTool("long_running_analysis", {
+ description: "Analyze a large dataset asynchronously",
+ inputSchema: { type: "object", properties: { datasetId: { type: "string" } }, required: ["datasetId"] }
+}, async ({ datasetId }, { task }) => {
+ // Create a task for the long-running operation
+ const taskId = await task.create({ title: `Analyzing dataset ${datasetId}` });
+
+ // Report progress
+ await task.update(taskId, { progress: 0.1, status: "Starting analysis..." });
+
+ const results = await runAnalysis(datasetId, (progress) => {
+ task.update(taskId, { progress, status: "Processing..." });
+ });
+
+ await task.complete(taskId, { results });
+ return { content: [{ type: "text", text: `Task ${taskId} completed` }] };
+});
+```
```mermaid
-flowchart TD
- A[extractRegion]
+sequenceDiagram
+ participant Client
+ participant Server
+ participant TaskManager
+
+ Client->>Server: tools/call long_running_analysis
+ Server->>TaskManager: task.create
+ TaskManager-->>Client: notifications/tasks/created {taskId}
+ Server->>TaskManager: task.update {progress: 0.1}
+ TaskManager-->>Client: notifications/tasks/updated
+ Server->>TaskManager: task.complete
+ TaskManager-->>Client: notifications/tasks/completed
+ Server-->>Client: tools/call result
```
+
+### Task API Stability Warning
+
+The tasks API is in `experimental/` for a reason:
+- Interfaces may change in future minor versions without a major bump
+- Not all clients support task notifications
+- Use feature detection before relying on task notifications in client-facing workflows
+
+For production use, implement task status as a regular resource (poll-based) rather than via task notifications until the API is stable.
+
+## Source References
+
+- [Elicitation form example](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/src/elicitationFormExample.ts)
+- [Elicitation URL example](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/src/elicitationUrlExample.ts)
+- [Tool with sampling example](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/src/toolWithSampleServer.ts)
+- [Experimental tasks: `mcpServer.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/server/src/experimental/tasks/mcpServer.ts)
+
+## Summary
+
+Use sampling for server-initiated LLM calls, checking client capability first. Form elicitation handles non-sensitive structured user input; URL elicitation handles credential and external auth flows. The experimental tasks API provides structured async job management but is not stable — don't couple production-critical paths to it. For each advanced capability, implement a graceful degradation path when the capability is unavailable.
+
+Next: [Chapter 6: Middleware, Security, and Host Validation](06-middleware-security-and-host-validation.md)
diff --git a/tutorials/mcp-typescript-sdk-tutorial/06-middleware-security-and-host-validation.md b/tutorials/mcp-typescript-sdk-tutorial/06-middleware-security-and-host-validation.md
index 10f751e9..7396aad2 100644
--- a/tutorials/mcp-typescript-sdk-tutorial/06-middleware-security-and-host-validation.md
+++ b/tutorials/mcp-typescript-sdk-tutorial/06-middleware-security-and-host-validation.md
@@ -5,89 +5,185 @@ nav_order: 6
parent: MCP TypeScript SDK Tutorial
---
-
# Chapter 6: Middleware, Security, and Host Validation
-Welcome to **Chapter 6: Middleware, Security, and Host Validation**. In this part of **MCP TypeScript SDK Tutorial: Building and Migrating MCP Clients and Servers in TypeScript**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
+Most MCP server security risk in local and deployed environments comes from weak host binding controls and missing DNS rebinding protection. The v2 SDK addresses this through built-in host header validation middleware available in the Express and Hono adapters.
+## Learning Goals
-Most server risk in local and internal environments comes from weak host/binding controls, not tool code.
+- Apply framework adapter defaults that reduce attack surface
+- Configure host header validation and allowed hostname lists
+- Understand DNS rebinding attacks and why host validation prevents them
+- Align localhost development and network-access behavior safely
-## Learning Goals
+## The DNS Rebinding Attack Vector
-- apply framework adapter defaults that reduce exposure
-- configure host header validation and allowed hostnames
-- align localhost development and network-access behavior safely
-- separate runtime adapter concerns from protocol concerns
+A DNS rebinding attack can allow a malicious website to reach a locally-running MCP server by manipulating DNS resolution to point the attacker's domain to `127.0.0.1`. The attacker's JavaScript code then makes requests with the `Host: attacker.com` header — but they're actually hitting `localhost`.
+
+```mermaid
+flowchart TD
+ ATTACKER[Malicious website\nattacker.com]
+ ATTACKER --> DNS[DNS resolves attacker.com\nto 127.0.0.1 briefly]
+ DNS --> REQUEST[Browser makes request:\nGET http://attacker.com/mcp\nHost: attacker.com]
+ REQUEST --> SERVER[Local MCP server\non localhost:3000]
+ SERVER --> NOCHECK{No host validation?}
+ NOCHECK -- No check --> VULNERABLE[Server responds to\nattacker's request]
+ NOCHECK -- Has validation --> BLOCKED[Request rejected:\nHost not in allowlist]
+```
-## Security Checklist
+## Host Validation Middleware
-| Control | Recommendation |
-|:--------|:---------------|
-| Local host binding | default to localhost/loopback |
-| Host validation | explicit allowlist when externally bound |
-| Adapter choice | match runtime, keep adapters thin |
-| Legacy SSE | keep only for compatibility windows |
+The SDK provides `hostHeaderValidationMiddleware` for Express and an equivalent for Hono.
-## Source References
+### Express Host Validation
-- [Server Docs - DNS rebinding protection](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/docs/server.md)
-- [Express Adapter README](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/middleware/express/README.md)
-- [Hono Adapter README](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/middleware/hono/README.md)
+```typescript
+import express from 'express';
+import { McpServer } from '@modelcontextprotocol/server';
+import { createExpressHandler, hostHeaderValidationMiddleware } from '@modelcontextprotocol/express';
-## Summary
+const app = express();
-You now have concrete controls for hardening local and remote server exposure.
+// Apply host validation before MCP routes
+app.use(hostHeaderValidationMiddleware({
+ allowedHosts: [
+ "localhost",
+ "127.0.0.1",
+ "::1",
+ // Add your production domain if externally accessible
+ "mcp.yourcompany.com"
+ ]
+}));
-Next: [Chapter 7: v1 to v2 Migration Strategy](07-v1-to-v2-migration-strategy.md)
+const server = new McpServer({ name: "secure-server", version: "1.0.0" });
+// register tools...
+
+app.all('/mcp', createExpressHandler({ serverFactory: () => server }));
+```
+
+### Hono Host Validation
+
+```typescript
+import { Hono } from 'hono';
+import { McpServer } from '@modelcontextprotocol/server';
+import { createHonoHandler, hostHeaderValidationMiddleware } from '@modelcontextprotocol/hono';
+
+const app = new Hono();
+const server = new McpServer({ name: "secure-server", version: "1.0.0" });
+
+app.use('/*', hostHeaderValidationMiddleware({
+ allowedHosts: ["localhost", "mcp.yourcompany.com"]
+}));
+
+app.all('/mcp', createHonoHandler({ serverFactory: () => server }));
+```
+
+## Client-Side Auth Middleware
-## Source Code Walkthrough
-
-### `scripts/sync-snippets.ts`
-
-The `getOrLoadRegion` function in [`scripts/sync-snippets.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/HEAD/scripts/sync-snippets.ts) handles a key part of this chapter's functionality:
-
-```ts
- * @returns The extracted code string
- */
-function getOrLoadRegion(
- sourceFilePath: string,
- examplePath: string,
- regionName: string | undefined,
- cache: RegionCache,
-): string {
- // Resolve the example path relative to the source file
- const sourceDir = dirname(sourceFilePath);
- const absoluteExamplePath = resolve(sourceDir, examplePath);
-
- // File content is always cached with key ending in "#" (empty region)
- const fileKey = `${absoluteExamplePath}#`;
- let fileContent = cache.get(fileKey);
-
- if (fileContent === undefined) {
- try {
- fileContent = readFileSync(absoluteExamplePath, 'utf-8');
- } catch {
- throw new Error(`Example file not found: ${absoluteExamplePath}`);
- }
- cache.set(fileKey, fileContent);
+The SDK's `@modelcontextprotocol/client` also includes a middleware system for adding cross-cutting concerns to outgoing requests:
+
+```typescript
+import { Client } from '@modelcontextprotocol/client';
+import { withMiddleware } from '@modelcontextprotocol/client';
+
+// Add logging middleware to all client requests
+const loggingMiddleware = {
+ async before(request) {
+ console.log(`→ ${request.method}`);
+ return request;
+ },
+ async after(response) {
+ console.log(`← ${response.id} done`);
+ return response;
}
+};
+
+const client = withMiddleware(
+ new Client({ name: "my-client", version: "1.0.0" }),
+ [loggingMiddleware]
+);
+```
+
+## Deployment Security Checklist
- // If no region name, return whole file
- if (!regionName) {
- return fileContent.trim();
+```mermaid
+graph TD
+ CHECKLIST[Security Checklist]
+ CHECKLIST --> LOCAL[Local Development]
+ CHECKLIST --> REMOTE[Remote Deployment]
+
+ LOCAL --> L1[Bind to 127.0.0.1\nnot 0.0.0.0]
+ LOCAL --> L2[Apply host validation\nallow localhost only]
+ LOCAL --> L3[No TLS needed for localhost\nbut validate Host header]
+
+ REMOTE --> R1[TLS required\nhttps:// only]
+ REMOTE --> R2[Host validation with\nyour exact domain]
+ REMOTE --> R3[OAuth or API key auth\nfor all connections]
+ REMOTE --> R4[Rate limiting at\nnginx/load balancer level]
+```
+
+| Scenario | Binding | Host Allowlist | Auth |
+|:---------|:--------|:--------------|:-----|
+| Local dev (stdio) | N/A | N/A | None |
+| Local dev (HTTP) | 127.0.0.1 | `localhost`, `127.0.0.1` | None |
+| Team/internal | Private network | Internal hostnames | Optional token |
+| Public hosted | 0.0.0.0 with TLS | Your exact domain | OAuth or API key |
+
+## Sensitive Tool Guards
+
+For tools that perform destructive or sensitive operations, add explicit guards in the tool handler:
+
+```typescript
+server.registerTool("delete_all_records", {
+ description: "Permanently delete all records from the database. IRREVERSIBLE.",
+ inputSchema: {
+ type: "object",
+ properties: {
+ confirm: {
+ type: "string",
+ description: "Type 'DELETE ALL' to confirm",
+ enum: ["DELETE ALL"]
+ }
+ },
+ required: ["confirm"]
+ }
+}, async ({ confirm }, context) => {
+ // Double-check auth context if available
+ if (!context.authInfo?.scopes?.includes("admin")) {
+ return { content: [{ type: "text", text: "Error: admin scope required" }] };
}
- // Extract region from cached file content, cache the result
- const regionKey = `${absoluteExamplePath}#${regionName}`;
+ await db.deleteAll();
+ return { content: [{ type: "text", text: "All records deleted" }] };
+});
```
-This function is important because it defines how MCP TypeScript SDK Tutorial: Building and Migrating MCP Clients and Servers in TypeScript implements the patterns covered in this chapter.
+## Rate Limiting for HTTP Transports
+The SDK does not include built-in rate limiting. Apply it at the infrastructure layer:
-## How These Components Connect
+```typescript
+// Express rate limiting example using express-rate-limit
+import rateLimit from 'express-rate-limit';
-```mermaid
-flowchart TD
- A[getOrLoadRegion]
+app.use('/mcp', rateLimit({
+ windowMs: 60 * 1000, // 1 minute
+ max: 100, // 100 requests per minute
+ standardHeaders: true,
+ legacyHeaders: false
+}));
```
+
+## Source References
+
+- [Server Docs — DNS rebinding protection](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/docs/server.md)
+- [Host header validation source](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/server/src/server/middleware/hostHeaderValidation.ts)
+- [Express adapter README](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/middleware/express/README.md)
+- [Hono adapter README](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/middleware/hono/README.md)
+- [Client middleware source](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/src/client/middleware.ts)
+
+## Summary
+
+DNS rebinding attacks are the primary security threat for locally-run HTTP MCP servers. The `hostHeaderValidationMiddleware` in `@modelcontextprotocol/express` and `@modelcontextprotocol/hono` blocks requests with unrecognized Host headers. Always bind local servers to `127.0.0.1`. For remote deployments, require TLS and use OAuth or API key authentication. Add sensitive-operation guards in tool handlers for destructive operations.
+
+Next: [Chapter 7: v1 to v2 Migration Strategy](07-v1-to-v2-migration-strategy.md)
diff --git a/tutorials/mcp-typescript-sdk-tutorial/07-v1-to-v2-migration-strategy.md b/tutorials/mcp-typescript-sdk-tutorial/07-v1-to-v2-migration-strategy.md
index beeb2ed9..149990c0 100644
--- a/tutorials/mcp-typescript-sdk-tutorial/07-v1-to-v2-migration-strategy.md
+++ b/tutorials/mcp-typescript-sdk-tutorial/07-v1-to-v2-migration-strategy.md
@@ -5,88 +5,217 @@ nav_order: 7
parent: MCP TypeScript SDK Tutorial
---
-
# Chapter 7: v1 to v2 Migration Strategy
-Welcome to **Chapter 7: v1 to v2 Migration Strategy**. In this part of **MCP TypeScript SDK Tutorial: Building and Migrating MCP Clients and Servers in TypeScript**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
+Migrating from the monolithic `@modelcontextprotocol/sdk` v1 to the split-package v2 requires sequenced steps: runtime upgrade, package split, import updates, API changes, and regression testing. This chapter provides the complete migration map with before/after examples.
+## Learning Goals
-Migration success depends on sequencing: package split, imports, API updates, then behavior tests.
+- Map old monolithic package usage to the v2 split packages
+- Plan Node.js 20+ and ESM prerequisites before refactoring
+- Update import paths, server API, and transport names
+- Manage mixed v1/v2 environments during migration windows
-## Learning Goals
+## Migration Sequence
-- map old monolithic package usage to v2 split packages
-- plan Node/ESM/runtime prerequisites before refactoring
-- update API usage (`registerTool`, method-string handlers, header model)
-- manage mixed v1/v2 environments during migration windows
+```mermaid
+flowchart TD
+ STEP1[1. Upgrade runtime\nNode.js 20+, ESM config]
+ STEP2[2. Replace packages\nnpm uninstall sdk\nnpm install client/server/node]
+ STEP3[3. Update import paths\nold paths → new package paths]
+ STEP4[4. Update API calls\nregisterTool, renamed transports]
+ STEP5[5. Run tests\nconformance + integration]
+ STEP6[6. Roll out by service]
+
+ STEP1 --> STEP2 --> STEP3 --> STEP4 --> STEP5 --> STEP6
+```
-## Migration Order
+## Step 1: Runtime and Module Format
-1. align runtime and module format (Node 20+, ESM)
-2. migrate dependencies/imports
-3. update server/client API calls and schema shapes
-4. run regression and conformance checks
-5. roll out by service boundary, not by giant all-at-once PR
+v2 requires Node.js 20+ and ESM. If your project currently uses CommonJS:
-## Source References
+```json
+// package.json — add this to enable ESM
+{
+ "type": "module"
+}
+```
-- [Migration Guide](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/docs/migration.md)
-- [Migration Skill Guide](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/docs/migration-SKILL.md)
-- [FAQ - v1 branch guidance](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/docs/faq.md)
+```json
+// tsconfig.json — update for ESM
+{
+ "compilerOptions": {
+ "module": "NodeNext",
+ "moduleResolution": "NodeNext",
+ "target": "ES2022"
+ }
+}
+```
-## Summary
+If you cannot migrate to ESM, use dynamic imports as a bridge:
+```typescript
+// CommonJS wrapper for ESM SDK
+const { Client } = await import('@modelcontextprotocol/client');
+```
-You now have a phased migration plan that reduces production breakage risk.
+## Step 2: Package Replacement
-Next: [Chapter 8: Conformance Testing and Contribution Workflows](08-conformance-testing-and-contribution-workflows.md)
+```bash
+# Remove v1
+npm uninstall @modelcontextprotocol/sdk
-## Source Code Walkthrough
+# Install only what you need
+# For a server:
+npm install @modelcontextprotocol/server
-### `scripts/sync-snippets.ts`
+# For a server using Node.js native http:
+npm install @modelcontextprotocol/server @modelcontextprotocol/node
-The `formatCodeLines` function in [`scripts/sync-snippets.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/HEAD/scripts/sync-snippets.ts) handles a key part of this chapter's functionality:
+# For a client:
+npm install @modelcontextprotocol/client
-```ts
- * @returns The formatted code with JSDoc prefixes
- */
-function formatCodeLines(code: string, linePrefix: string): string {
- const lines = code.split('\n');
- return lines
- .map((line) =>
- line === '' ? linePrefix.trimEnd() : `${linePrefix}${line}`,
- )
- .join('\n');
-}
+# For an Express server:
+npm install @modelcontextprotocol/server @modelcontextprotocol/express
+```
-interface ProcessFileOptions {
- check?: boolean;
-}
+## Step 3: Import Path Updates
+
+This is the most mechanical step. Replace every import.
+
+### Server Imports
+
+```typescript
+// BEFORE (v1)
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+
+// AFTER (v2)
+import { McpServer } from '@modelcontextprotocol/server';
+import { StdioServerTransport } from '@modelcontextprotocol/server';
+// StreamableHTTPServerTransport is now NodeStreamableHTTPServerTransport in @modelcontextprotocol/node
+import { NodeStreamableHTTPServerTransport } from '@modelcontextprotocol/node';
+```
+
+### Client Imports
+
+```typescript
+// BEFORE (v1)
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
+
+// AFTER (v2)
+import { Client, StdioClientTransport, StreamableHTTPClientTransport, SSEClientTransport }
+ from '@modelcontextprotocol/client';
+```
+
+### Type Imports
-/**
- * Process a single source file to sync snippets.
- * @param filePath The source file path
- * @param cache The region cache
- * @param mode The processing mode (jsdoc or markdown)
- * @returns The processing result
- */
-function processFile(
- filePath: string,
- cache: RegionCache,
- mode: FileMode,
- options?: ProcessFileOptions,
-): FileProcessingResult {
- const result: FileProcessingResult = {
- filePath,
- modified: false,
- snippetsProcessed: 0,
+```typescript
+// BEFORE (v1)
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import { CallToolResultSchema } from '@modelcontextprotocol/sdk/types.js';
+
+// AFTER (v2) — import from whichever package you already use
+import type { CallToolResult } from '@modelcontextprotocol/server';
+import { CallToolResultSchema } from '@modelcontextprotocol/client';
+```
+
+## Step 4: API Changes
+
+### Server Registration API
+
+```typescript
+// BEFORE (v1) — method-string based registration
+server.tool("search", { query: z.string() }, async ({ query }) => {
+ return { content: [{ type: "text", text: await search(query) }] };
+});
+
+// AFTER (v2) — registerTool with JSON Schema
+server.registerTool("search", {
+ description: "Search documents",
+ inputSchema: {
+ type: "object",
+ properties: { query: { type: "string" } },
+ required: ["query"]
+ }
+}, async ({ query }) => {
+ return { content: [{ type: "text", text: await search(query) }] };
+});
```
-This function is important because it defines how MCP TypeScript SDK Tutorial: Building and Migrating MCP Clients and Servers in TypeScript implements the patterns covered in this chapter.
+### Transport Rename
+
+| v1 Name | v2 Name | Package |
+|:--------|:--------|:--------|
+| `StreamableHTTPServerTransport` | `NodeStreamableHTTPServerTransport` | `@modelcontextprotocol/node` |
+| `StreamableHTTPServerTransport` | `WebStandardStreamableHTTPServerTransport` | `@modelcontextprotocol/server` (web APIs) |
+```typescript
+// BEFORE (v1)
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: () => randomUUID() });
-## How These Components Connect
+// AFTER (v2) — Node.js HTTP
+import { NodeStreamableHTTPServerTransport } from '@modelcontextprotocol/node';
+const transport = new NodeStreamableHTTPServerTransport({ sessionIdGenerator: () => randomUUID() });
+```
+
+## Step 5: Zod Dependency
+
+v1 required zod as a peer dependency. v2 does not. If you used zod only for SDK-required validation:
+
+```bash
+# Remove if no longer needed for your own code
+npm uninstall zod
+```
+
+If you use zod in your own tool input validation, it remains valid — but is your project dependency, not the SDK's.
+
+## Migration Checklist
```mermaid
-flowchart TD
- A[formatCodeLines]
+graph LR
+ TASKS[Migration Checklist]
+ TASKS --> T1[Node.js >= 20 confirmed]
+ TASKS --> T2[package.json type: module set]
+ TASKS --> T3[tsconfig moduleResolution: NodeNext]
+ TASKS --> T4[sdk package removed]
+ TASKS --> T5[client/server packages installed]
+ TASKS --> T6[All import paths updated]
+ TASKS --> T7[registerTool API updated]
+ TASKS --> T8[Transport names updated]
+ TASKS --> T9[Zod peer dep removed if unused]
+ TASKS --> T10[Tests pass]
+ TASKS --> T11[Conformance suite passes]
```
+
+## Mixed v1/v2 Environments
+
+During migration windows, you may have some services on v1 and others on v2. v2 clients are backward-compatible with v1 servers (the protocol is the same). The packages differ; the wire format does not.
+
+```mermaid
+graph LR
+ V2CLIENT[v2 Client\n@modelcontextprotocol/client]
+ V1SERVER[v1 Server\n@modelcontextprotocol/sdk]
+ V2SERVER[v2 Server\n@modelcontextprotocol/server]
+
+ V2CLIENT -->|works| V1SERVER
+ V2CLIENT -->|works| V2SERVER
+```
+
+Migrate servers first, then clients — client behavior is more visible and easier to test incrementally.
+
+## Source References
+
+- [Migration Guide](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/docs/migration.md)
+- [Migration Skill Guide](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/docs/migration-SKILL.md)
+- [FAQ](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/docs/faq.md)
+
+## Summary
+
+The v1→v2 migration requires five ordered steps: Node 20+ with ESM, package replacement, import path rewrites, API updates (`registerTool`, transport renames), and regression testing. The most error-prone step is the transport rename (`StreamableHTTPServerTransport` → `NodeStreamableHTTPServerTransport` in `@modelcontextprotocol/node`). Migrate one service at a time; v2 clients connect to v1 servers without issues during the transition.
+
+Next: [Chapter 8: Conformance Testing and Contribution Workflows](08-conformance-testing-and-contribution-workflows.md)
diff --git a/tutorials/mcp-typescript-sdk-tutorial/08-conformance-testing-and-contribution-workflows.md b/tutorials/mcp-typescript-sdk-tutorial/08-conformance-testing-and-contribution-workflows.md
index fa450f14..9ddae351 100644
--- a/tutorials/mcp-typescript-sdk-tutorial/08-conformance-testing-and-contribution-workflows.md
+++ b/tutorials/mcp-typescript-sdk-tutorial/08-conformance-testing-and-contribution-workflows.md
@@ -5,87 +5,185 @@ nav_order: 8
parent: MCP TypeScript SDK Tutorial
---
-
# Chapter 8: Conformance Testing and Contribution Workflows
-Welcome to **Chapter 8: Conformance Testing and Contribution Workflows**. In this part of **MCP TypeScript SDK Tutorial: Building and Migrating MCP Clients and Servers in TypeScript**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
+Long-term SDK reliability comes from combining conformance testing with disciplined contribution practices. This chapter explains how to run the SDK's conformance suites, integrate them into your CI pipeline, and navigate the contribution workflow for the `modelcontextprotocol/typescript-sdk` repository.
+## Learning Goals
-Long-term reliability comes from conformance + integration testing, then disciplined contribution boundaries.
+- Run conformance suites for both client and server MCP behaviors
+- Combine conformance checks with package-level integration tests
+- Align PR scope and issue-first workflow with maintainer expectations
+- Understand branch targeting for v1.x maintenance vs. v2 development
-## Learning Goals
+## Conformance Testing Overview
-- run conformance suites for both client and server behaviors
-- combine conformance checks with repo-specific integration tests
-- align PR scope and issue-first workflow with maintainer expectations
-- support v1.x maintenance while adopting v2 paths deliberately
+The SDK monorepo includes a conformance test suite that validates protocol compliance across client and server implementations. Tests live in the `test/conformance/` directory.
-## Operational Testing Loop
+```mermaid
+graph TD
+ TESTING[Testing Layers]
+ TESTING --> UNIT[Unit tests\nper-package vitest suites\npackages/*/test/]
+ TESTING --> CONFORMANCE[Conformance tests\nprotocol-level compliance\ntest/conformance/]
+ TESTING --> INTEG[Integration tests\nin CI workflow\n.github/workflows/conformance.yml]
+
+ UNIT --> TRANSPORT_TEST[Transport behavior\nstreamableHttp.test.ts · stdio.test.ts]
+ UNIT --> SERVER_TEST[Server handler\nserver.test.ts]
+ CONFORMANCE --> CLIENT_CONF[Client conformance:\ninitialization, tool calls, resource reads]
+ CONFORMANCE --> SERVER_CONF[Server conformance:\ncapability negotiation, error handling]
+```
-- run `test:conformance:client` and `test:conformance:server`
-- run package-level integration tests for your specific transports
-- keep migration changes small and reviewable
-- document branch targeting (`main` vs `v1.x`) in team workflow docs
+## Running Tests Locally
-## Source References
+```bash
+# Clone the repository
+git clone https://github.com/modelcontextprotocol/typescript-sdk
+cd typescript-sdk
-- [Conformance README](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/test/conformance/README.md)
-- [Contributing Guide](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/CONTRIBUTING.md)
-- [TypeScript SDK Releases](https://github.com/modelcontextprotocol/typescript-sdk/releases)
+# Install all workspace dependencies
+npm install
-## Summary
+# Run all tests across the monorepo
+npm test
+
+# Run tests for a specific package
+cd packages/server
+npm test
+
+# Run conformance suite only
+npm run test:conformance
-You now have a production-aligned approach for maintaining and extending MCP TypeScript SDK usage over time.
-
-Next: Continue with [MCP Use Tutorial](../mcp-use-tutorial/)
-
-## Source Code Walkthrough
-
-### `scripts/sync-snippets.ts`
-
-The `processFile` function in [`scripts/sync-snippets.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/HEAD/scripts/sync-snippets.ts) handles a key part of this chapter's functionality:
-
-```ts
- * @returns The processing result
- */
-function processFile(
- filePath: string,
- cache: RegionCache,
- mode: FileMode,
- options?: ProcessFileOptions,
-): FileProcessingResult {
- const result: FileProcessingResult = {
- filePath,
- modified: false,
- snippetsProcessed: 0,
- errors: [],
- };
-
- let content: string;
- try {
- content = readFileSync(filePath, 'utf-8');
- } catch (err) {
- result.errors.push(`Failed to read file: ${err}`);
- return result;
- }
-
- let fences: LabeledCodeFence[];
- try {
- fences = findLabeledCodeFences(content, filePath, mode);
- } catch (err) {
- result.errors.push(err instanceof Error ? err.message : String(err));
- return result;
- }
-
- if (fences.length === 0) {
+# Run conformance in check mode (CI-style, no re-generation)
+npm run test:conformance:check
```
-This function is important because it defines how MCP TypeScript SDK Tutorial: Building and Migrating MCP Clients and Servers in TypeScript implements the patterns covered in this chapter.
+## Package-Level Test Structure
+Each package has its own test directory following the same structure:
-## How These Components Connect
+```
+packages/server/test/
+├── server/
+│ ├── server.test.ts # Core server behavior
+│ ├── stdio.test.ts # Stdio transport tests
+│ ├── streamableHttp.test.ts # StreamableHTTP transport tests
+│ └── completable.test.ts # Completions behavior
+
+packages/client/test/
+├── client/
+│ ├── auth.test.ts # OAuth and auth provider tests
+│ ├── middleware.test.ts # Client middleware tests
+│ ├── stdio.test.ts # Stdio client transport
+│ ├── streamableHttp.test.ts # StreamableHTTP client transport
+│ └── sse.test.ts # Legacy SSE client
+```
+
+Run tests with coverage:
+```bash
+npm run test -- --coverage
+```
+
+## CI Workflow
+
+The repository runs these CI checks on every PR:
+
+```mermaid
+flowchart LR
+ PR[Pull Request]
+ PR --> LINT[ESLint\nnpm run lint]
+ PR --> TYPECHECK[TypeScript type check\nnpm run typecheck]
+ PR --> UNIT[Unit tests\nvitest per package]
+ PR --> CONFORMANCE[Conformance tests\n.github/workflows/conformance.yml]
+ PR --> BUILD[Build check\nnpm run build]
+ PR --> SNIPPETS[Snippet sync check\nscripts/sync-snippets.ts --check]
+
+ SNIPPETS --> NOTE[Note: sync-snippets.ts\nis a doc tooling script\nthat syncs code examples\ninto markdown docs]
+```
+
+The `sync-snippets` check ensures that code examples in `docs/*.md` files stay synchronized with the actual TypeScript example files in `examples/`. This is a documentation quality tool — it has no relation to protocol behavior.
+
+## Contribution Workflow
```mermaid
flowchart TD
- A[processFile]
+ ISSUE[Open an issue first\nexplain the problem or proposal]
+ ISSUE --> DISCUSS[Wait for maintainer feedback\nbefore implementing]
+ DISCUSS --> FORK[Fork and create feature branch]
+ FORK --> CODE[Implement change]
+ CODE --> TEST[Add/update tests\nconformance + unit]
+ TEST --> DOCS[Update docs if needed\nconsider sync-snippets]
+ DOCS --> PR[Open PR against main branch\nfor v2 changes]
+ PR --> REVIEW[Maintainer review]
+ REVIEW --> MERGE[Merge]
+```
+
+### Branch Targeting
+
+| Change Type | Target Branch |
+|:------------|:-------------|
+| Bug fixes for v2 | `main` |
+| New features for v2 | `main` |
+| v1.x maintenance fixes | `v1.x` branch |
+| Breaking changes | `main` with migration guide update |
+
+Always check the `CONTRIBUTING.md` for the current active branch policy before opening a PR.
+
+### PR Scope Guidelines
+
+- One logical change per PR
+- Include tests that would have failed before the fix
+- Update `docs/` if behavior or API surface changes
+- Add a `.changeset/` entry for publishable changes (the repo uses changesets for versioning)
+
+```bash
+# Add a changeset entry for your change
+npx changeset
+
+# This creates a file in .changeset/ documenting your change
+# Maintainers use these to generate changelogs and bump versions
+```
+
+## Writing Tests for New Features
+
+When adding a new tool handler or transport behavior, follow the existing test patterns:
+
+```typescript
+// Example pattern from packages/server/test/server/server.test.ts
+import { describe, test, expect } from 'vitest';
+import { McpServer } from '../../src/index.js';
+import { InMemoryTransport } from '@modelcontextprotocol/core';
+import { Client } from '@modelcontextprotocol/client';
+
+describe('tool registration', () => {
+ test('registered tool appears in list', async () => {
+ const server = new McpServer({ name: "test", version: "1.0.0" });
+ server.registerTool("my-tool", {
+ description: "Test tool",
+ inputSchema: { type: "object", properties: { x: { type: "number" } }, required: ["x"] }
+ }, async ({ x }) => ({
+ content: [{ type: "text", text: `Result: ${x * 2}` }]
+ }));
+
+ const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+ const client = new Client({ name: "test-client", version: "1.0.0" });
+ await Promise.all([server.connect(serverTransport), client.connect(clientTransport)]);
+
+ const { tools } = await client.listTools();
+ expect(tools).toHaveLength(1);
+ expect(tools[0].name).toBe("my-tool");
+ });
+});
```
+
+## Source References
+
+- [Contributing Guide](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/CONTRIBUTING.md)
+- [Conformance test README](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/test/conformance/README.md)
+- [GitHub Actions conformance workflow](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/.github/workflows/conformance.yml)
+- [TypeScript SDK Releases](https://github.com/modelcontextprotocol/typescript-sdk/releases)
+
+## Summary
+
+Testing for MCP TypeScript SDK work runs at three levels: unit tests per package, conformance suite for protocol compliance, and CI integration tests. The `sync-snippets.ts` script is a documentation tooling utility, not a protocol concern. Contributions follow an issue-first workflow with PRs targeting `main` for v2 and `v1.x` for maintenance. Use `InMemoryTransport.createLinkedPair()` for fast unit testing of server and client handlers without a real network layer.
+
+Return to the [MCP TypeScript SDK Tutorial index](README.md).
diff --git a/tutorials/mcp-use-tutorial/01-getting-started-and-stack-selection.md b/tutorials/mcp-use-tutorial/01-getting-started-and-stack-selection.md
index dcee8079..07a6b9c5 100644
--- a/tutorials/mcp-use-tutorial/01-getting-started-and-stack-selection.md
+++ b/tutorials/mcp-use-tutorial/01-getting-started-and-stack-selection.md
@@ -40,8 +40,6 @@ You now have a clear stack-entry decision for mcp-use adoption.
Next: [Chapter 2: Client Configuration, Sessions, and Transport Choices](02-client-configuration-sessions-and-transport-choices.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `docs/docs.json`
@@ -65,43 +63,43 @@ The `showing` interface in [`docs/docs.json`](https://github.com/mcp-use/mcp-use
This interface is important because it defines how MCP Use Tutorial: Full-Stack MCP Development Across Agents, Clients, Servers, and Inspector implements the patterns covered in this chapter.
-### `libraries/python/examples/google_integration_example.py`
+### `libraries/python/examples/anthropic_integration_example.py`
-The `main` function in [`libraries/python/examples/google_integration_example.py`](https://github.com/mcp-use/mcp-use/blob/HEAD/libraries/python/examples/google_integration_example.py) handles a key part of this chapter's functionality:
+The `main` function in [`libraries/python/examples/anthropic_integration_example.py`](https://github.com/mcp-use/mcp-use/blob/HEAD/libraries/python/examples/anthropic_integration_example.py) handles a key part of this chapter's functionality:
```py
async def main():
config = {
- "mcpServers": {"playwright": {"command": "npx", "args": ["@playwright/mcp@latest"], "env": {"DISPLAY": ":1"}}}
+ "mcpServers": {
+ "airbnb": {"command": "npx", "args": ["-y", "@openbnb/mcp-server-airbnb", "--ignore-robots-txt"]},
+ }
}
try:
client = MCPClient(config=config)
- # Creates the adapter for Google's format
- adapter = GoogleMCPAdapter()
+ # Creates the adapter for Anthropic's format
+ adapter = AnthropicMCPAdapter()
- # Convert tools from active connectors to the Google's format
+ # Convert tools from active connectors to the Anthropic's format
await adapter.create_all(client)
# List concatenation (if you loaded all tools)
- all_tools = adapter.tools + adapter.resources + adapter.prompts
- google_tools = [types.Tool(function_declarations=all_tools)]
+ anthropic_tools = adapter.tools + adapter.resources + adapter.prompts
# If you don't want to create all tools, you can call single functions
# await adapter.create_tools(client)
# await adapter.create_resources(client)
# await adapter.create_prompts(client)
- # Use tools with Google's SDK (not agent in this case)
- gemini = genai.Client()
+ # Use tools with Anthropic's SDK (not agent in this case)
+ anthropic = Anthropic()
- messages = [
- types.Content(
- role="user",
- parts=[
+ # Initial request
+ messages = [{"role": "user", "content": "Please tell me the cheapest hotel for two people in Trapani."}]
+ response = anthropic.messages.create(
```
This function is important because it defines how MCP Use Tutorial: Full-Stack MCP Development Across Agents, Clients, Servers, and Inspector implements the patterns covered in this chapter.
diff --git a/tutorials/mcp-use-tutorial/02-client-configuration-sessions-and-transport-choices.md b/tutorials/mcp-use-tutorial/02-client-configuration-sessions-and-transport-choices.md
index 2772541f..1ac0f90f 100644
--- a/tutorials/mcp-use-tutorial/02-client-configuration-sessions-and-transport-choices.md
+++ b/tutorials/mcp-use-tutorial/02-client-configuration-sessions-and-transport-choices.md
@@ -40,88 +40,85 @@ You now have a repeatable client configuration baseline for local and remote MCP
Next: [Chapter 3: Agent Configuration, Tool Governance, and Memory](03-agent-configuration-tool-governance-and-memory.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `libraries/python/examples/example_middleware.py`
+### `libraries/python/examples/google_integration_example.py`
-The `TimingMiddleware` class in [`libraries/python/examples/example_middleware.py`](https://github.com/mcp-use/mcp-use/blob/HEAD/libraries/python/examples/example_middleware.py) handles a key part of this chapter's functionality:
+The `main` function in [`libraries/python/examples/google_integration_example.py`](https://github.com/mcp-use/mcp-use/blob/HEAD/libraries/python/examples/google_integration_example.py) handles a key part of this chapter's functionality:
```py
- # Create custom middleware
- class TimingMiddleware(Middleware):
- async def on_request(self, context: MiddlewareContext[Any], call_next: NextFunctionT) -> Any:
- start = time.time()
- try:
- print("--------------------------------")
- print(f"{context.method} started")
- print("--------------------------------")
- print(f"{context.params}, {context.metadata}, {context.timestamp}, {context.connection_id}")
- print("--------------------------------")
- result = await call_next(context)
- return result
- finally:
- duration = time.time() - start
- print("--------------------------------")
- print(f"{context.method} took {int(1000 * duration)}ms")
- print("--------------------------------")
-
- # Middleware that demonstrates mutating params and adding headers-like metadata
- class MutationMiddleware(Middleware):
- async def on_call_tool(self, context: MiddlewareContext[Any], call_next: NextFunctionT) -> Any:
- # Defensive mutation of params: ensure `arguments` exists before writing
- try:
- print("[MutationMiddleware] context.params=", context.params)
- args = getattr(context.params, "arguments", None)
- if args is None:
- args = {}
-
- # Inject a URL argument (example) and a trace id
- args["url"] = "https://github.com"
- meta = args.setdefault("meta", {})
+
+async def main():
+ config = {
+ "mcpServers": {"playwright": {"command": "npx", "args": ["@playwright/mcp@latest"], "env": {"DISPLAY": ":1"}}}
+ }
+
+ try:
+ client = MCPClient(config=config)
+
+ # Creates the adapter for Google's format
+ adapter = GoogleMCPAdapter()
+
+ # Convert tools from active connectors to the Google's format
+ await adapter.create_all(client)
+
+ # List concatenation (if you loaded all tools)
+ all_tools = adapter.tools + adapter.resources + adapter.prompts
+ google_tools = [types.Tool(function_declarations=all_tools)]
+
+ # If you don't want to create all tools, you can call single functions
+ # await adapter.create_tools(client)
+ # await adapter.create_resources(client)
+ # await adapter.create_prompts(client)
+
+ # Use tools with Google's SDK (not agent in this case)
+ gemini = genai.Client()
+
+ messages = [
+ types.Content(
+ role="user",
+ parts=[
```
-This class is important because it defines how MCP Use Tutorial: Full-Stack MCP Development Across Agents, Clients, Servers, and Inspector implements the patterns covered in this chapter.
+This function is important because it defines how MCP Use Tutorial: Full-Stack MCP Development Across Agents, Clients, Servers, and Inspector implements the patterns covered in this chapter.
-### `libraries/python/examples/example_middleware.py`
+### `libraries/python/mcp_use/logging.py`
-The `MutationMiddleware` class in [`libraries/python/examples/example_middleware.py`](https://github.com/mcp-use/mcp-use/blob/HEAD/libraries/python/examples/example_middleware.py) handles a key part of this chapter's functionality:
+The `Logger` class in [`libraries/python/mcp_use/logging.py`](https://github.com/mcp-use/mcp-use/blob/HEAD/libraries/python/mcp_use/logging.py) handles a key part of this chapter's functionality:
```py
+"""
+Logger module for mcp_use.
- # Middleware that demonstrates mutating params and adding headers-like metadata
- class MutationMiddleware(Middleware):
- async def on_call_tool(self, context: MiddlewareContext[Any], call_next: NextFunctionT) -> Any:
- # Defensive mutation of params: ensure `arguments` exists before writing
- try:
- print("[MutationMiddleware] context.params=", context.params)
- args = getattr(context.params, "arguments", None)
- if args is None:
- args = {}
+This module provides a centralized logging configuration for the mcp_use library,
+with customizable log levels and formatters.
+"""
- # Inject a URL argument (example) and a trace id
- args["url"] = "https://github.com"
- meta = args.setdefault("meta", {})
- meta["trace_id"] = "trace-123"
+import logging
+import os
+import sys
- # Write back the mutated arguments to the params object
- context.params.arguments = args
+from langchain_core.globals import set_debug as langchain_set_debug
- # Also demonstrate carrying header-like info via metadata
- context.metadata.setdefault("headers", {})["X-Trace-Id"] = "trace-123"
- # Debug: show the mutated params/metadata immediately
- print("[AddTraceMiddleware] after mutation:", context.params, context.metadata)
+# Global debug flag - can be set programmatically or from environment
+MCP_USE_DEBUG = 1
- except Exception as e:
- # Don't break the request flow in an example
- print(f"[AddTraceMiddleware] failed to mutate params: {e}")
- return await call_next(context)
+class Logger:
+ """Centralized logger for mcp_use.
- config = {
- "mcpServers": {"playwright": {"command": "npx", "args": ["@playwright/mcp@latest"], "env": {"DISPLAY": ":1"}}}
+ This class provides logging functionality with configurable levels,
+ formatters, and handlers.
+ """
+
+ # Default log format
+ DEFAULT_FORMAT = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+
+ # Module-specific loggers
+ _loggers = {}
+
+ @classmethod
```
This class is important because it defines how MCP Use Tutorial: Full-Stack MCP Development Across Agents, Clients, Servers, and Inspector implements the patterns covered in this chapter.
@@ -131,7 +128,7 @@ This class is important because it defines how MCP Use Tutorial: Full-Stack MCP
```mermaid
flowchart TD
- A[TimingMiddleware]
- B[MutationMiddleware]
+ A[main]
+ B[Logger]
A --> B
```
diff --git a/tutorials/mcp-use-tutorial/03-agent-configuration-tool-governance-and-memory.md b/tutorials/mcp-use-tutorial/03-agent-configuration-tool-governance-and-memory.md
index 8f3868f6..91a0d059 100644
--- a/tutorials/mcp-use-tutorial/03-agent-configuration-tool-governance-and-memory.md
+++ b/tutorials/mcp-use-tutorial/03-agent-configuration-tool-governance-and-memory.md
@@ -39,21 +39,54 @@ You now have agent-level guardrails for safer, more predictable tool execution.
Next: [Chapter 4: TypeScript Server Framework and UI Widgets](04-typescript-server-framework-and-ui-widgets.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `libraries/python/examples/example_middleware.py`
+### `libraries/python/mcp_use/logging.py`
-The `main` function in [`libraries/python/examples/example_middleware.py`](https://github.com/mcp-use/mcp-use/blob/HEAD/libraries/python/examples/example_middleware.py) handles a key part of this chapter's functionality:
+The `provides` class in [`libraries/python/mcp_use/logging.py`](https://github.com/mcp-use/mcp-use/blob/HEAD/libraries/python/mcp_use/logging.py) handles a key part of this chapter's functionality:
```py
+Logger module for mcp_use.
+
+This module provides a centralized logging configuration for the mcp_use library,
+with customizable log levels and formatters.
+"""
+
+import logging
+import os
+import sys
+
+from langchain_core.globals import set_debug as langchain_set_debug
+
+# Global debug flag - can be set programmatically or from environment
+MCP_USE_DEBUG = 1
+
+
+class Logger:
+ """Centralized logger for mcp_use.
+ This class provides logging functionality with configurable levels,
+ formatters, and handlers.
+ """
-async def main():
- """Run the example with default logging and optional custom middleware."""
- # Load environment variables
- load_dotenv()
+ # Default log format
+ DEFAULT_FORMAT = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+
+ # Module-specific loggers
+ _loggers = {}
+
+ @classmethod
+ def get_logger(cls, name: str = "mcp_use") -> logging.Logger:
+ """Get a logger instance for the specified name.
+```
+
+This class is important because it defines how MCP Use Tutorial: Full-Stack MCP Development Across Agents, Clients, Servers, and Inspector implements the patterns covered in this chapter.
+
+### `libraries/python/examples/example_middleware.py`
+
+The `TimingMiddleware` class in [`libraries/python/examples/example_middleware.py`](https://github.com/mcp-use/mcp-use/blob/HEAD/libraries/python/examples/example_middleware.py) handles a key part of this chapter's functionality:
+
+```py
# Create custom middleware
class TimingMiddleware(Middleware):
@@ -80,57 +113,22 @@ async def main():
try:
print("[MutationMiddleware] context.params=", context.params)
args = getattr(context.params, "arguments", None)
-```
-
-This function is important because it defines how MCP Use Tutorial: Full-Stack MCP Development Across Agents, Clients, Servers, and Inspector implements the patterns covered in this chapter.
-
-### `libraries/python/examples/openai_integration_example.py`
-
-The `main` function in [`libraries/python/examples/openai_integration_example.py`](https://github.com/mcp-use/mcp-use/blob/HEAD/libraries/python/examples/openai_integration_example.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-async def main():
- config = {
- "mcpServers": {
- "airbnb": {"command": "npx", "args": ["-y", "@openbnb/mcp-server-airbnb", "--ignore-robots-txt"]},
- }
- }
-
- try:
- client = MCPClient(config=config)
-
- # Creates the adapter for OpenAI's format
- adapter = OpenAIMCPAdapter()
-
- # Convert tools from active connectors to the OpenAI's format
- # this will populates the list of tools, resources and prompts
- await adapter.create_all(client)
-
- # If you don't want to create all tools, you can call single functions
- # await adapter.create_tools(client)
- # await adapter.create_resources(client)
- # await adapter.create_prompts(client)
-
- # If you decided to create all tools (list concatenation)
- openai_tools = adapter.tools + adapter.resources + adapter.prompts
-
- # Use tools with OpenAI's SDK (not agent in this case)
- openai = OpenAI()
- messages = [{"role": "user", "content": "Please tell me the cheapest hotel for two people in Trapani."}]
- response = openai.chat.completions.create(model="gpt-4o", messages=messages, tools=openai_tools)
+ if args is None:
+ args = {}
+ # Inject a URL argument (example) and a trace id
+ args["url"] = "https://github.com"
+ meta = args.setdefault("meta", {})
```
-This function is important because it defines how MCP Use Tutorial: Full-Stack MCP Development Across Agents, Clients, Servers, and Inspector implements the patterns covered in this chapter.
+This class is important because it defines how MCP Use Tutorial: Full-Stack MCP Development Across Agents, Clients, Servers, and Inspector implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[main]
- B[main]
+ A[provides]
+ B[TimingMiddleware]
A --> B
```
diff --git a/tutorials/mcp-use-tutorial/04-typescript-server-framework-and-ui-widgets.md b/tutorials/mcp-use-tutorial/04-typescript-server-framework-and-ui-widgets.md
index 9c4d22ce..616c753b 100644
--- a/tutorials/mcp-use-tutorial/04-typescript-server-framework-and-ui-widgets.md
+++ b/tutorials/mcp-use-tutorial/04-typescript-server-framework-and-ui-widgets.md
@@ -40,98 +40,96 @@ You now have a complete TypeScript server workflow, from scaffold to interactive
Next: [Chapter 5: Python Server Framework and Debug Endpoints](05-python-server-framework-and-debug-endpoints.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `libraries/python/examples/simple_server_manager_use.py`
+### `libraries/python/examples/example_middleware.py`
-The `DynamicTool` class in [`libraries/python/examples/simple_server_manager_use.py`](https://github.com/mcp-use/mcp-use/blob/HEAD/libraries/python/examples/simple_server_manager_use.py) handles a key part of this chapter's functionality:
+The `MutationMiddleware` class in [`libraries/python/examples/example_middleware.py`](https://github.com/mcp-use/mcp-use/blob/HEAD/libraries/python/examples/example_middleware.py) handles a key part of this chapter's functionality:
```py
-
-class DynamicTool(BaseTool):
- """A tool that is created dynamically."""
-
- name: str
- description: str
- args_schema: type[BaseModel] | None = None
-
- def _run(self) -> str:
- return f"Hello from {self.name}!"
-
- async def _arun(self) -> str:
- return f"Hello from {self.name}!"
-
-
-class HelloWorldTool(BaseTool):
- """A simple tool that returns a greeting and adds a new tool."""
-
- name: str = "hello_world"
- description: str = "Returns the string 'Hello, World!' and adds a new dynamic tool."
- args_schema: type[BaseModel] | None = None
- server_manager: "SimpleServerManager"
-
- def _run(self) -> str:
- new_tool = DynamicTool(
- name=f"dynamic_tool_{len(self.server_manager.tools)}", description="A dynamically created tool."
- )
- self.server_manager.add_tool(new_tool)
- return "Hello, World! I've added a new tool. You can use it now."
-
- async def _arun(self) -> str:
+ # Middleware that demonstrates mutating params and adding headers-like metadata
+ class MutationMiddleware(Middleware):
+ async def on_call_tool(self, context: MiddlewareContext[Any], call_next: NextFunctionT) -> Any:
+ # Defensive mutation of params: ensure `arguments` exists before writing
+ try:
+ print("[MutationMiddleware] context.params=", context.params)
+ args = getattr(context.params, "arguments", None)
+ if args is None:
+ args = {}
+
+ # Inject a URL argument (example) and a trace id
+ args["url"] = "https://github.com"
+ meta = args.setdefault("meta", {})
+ meta["trace_id"] = "trace-123"
+
+ # Write back the mutated arguments to the params object
+ context.params.arguments = args
+
+ # Also demonstrate carrying header-like info via metadata
+ context.metadata.setdefault("headers", {})["X-Trace-Id"] = "trace-123"
+ # Debug: show the mutated params/metadata immediately
+ print("[AddTraceMiddleware] after mutation:", context.params, context.metadata)
+
+ except Exception as e:
+ # Don't break the request flow in an example
+ print(f"[AddTraceMiddleware] failed to mutate params: {e}")
+
+ return await call_next(context)
+
+ config = {
+ "mcpServers": {"playwright": {"command": "npx", "args": ["@playwright/mcp@latest"], "env": {"DISPLAY": ":1"}}}
```
This class is important because it defines how MCP Use Tutorial: Full-Stack MCP Development Across Agents, Clients, Servers, and Inspector implements the patterns covered in this chapter.
-### `libraries/python/examples/simple_server_manager_use.py`
+### `libraries/python/examples/example_middleware.py`
-The `HelloWorldTool` class in [`libraries/python/examples/simple_server_manager_use.py`](https://github.com/mcp-use/mcp-use/blob/HEAD/libraries/python/examples/simple_server_manager_use.py) handles a key part of this chapter's functionality:
+The `main` function in [`libraries/python/examples/example_middleware.py`](https://github.com/mcp-use/mcp-use/blob/HEAD/libraries/python/examples/example_middleware.py) handles a key part of this chapter's functionality:
```py
-class HelloWorldTool(BaseTool):
- """A simple tool that returns a greeting and adds a new tool."""
-
- name: str = "hello_world"
- description: str = "Returns the string 'Hello, World!' and adds a new dynamic tool."
- args_schema: type[BaseModel] | None = None
- server_manager: "SimpleServerManager"
-
- def _run(self) -> str:
- new_tool = DynamicTool(
- name=f"dynamic_tool_{len(self.server_manager.tools)}", description="A dynamically created tool."
- )
- self.server_manager.add_tool(new_tool)
- return "Hello, World! I've added a new tool. You can use it now."
-
- async def _arun(self) -> str:
- new_tool = DynamicTool(
- name=f"dynamic_tool_{len(self.server_manager.tools)}", description="A dynamically created tool."
- )
- self.server_manager.add_tool(new_tool)
- return "Hello, World! I've added a new tool. You can use it now."
-
-
-class SimpleServerManager(BaseServerManager):
- """A simple server manager that provides a HelloWorldTool."""
-
- def __init__(self):
- self._tools: list[BaseTool] = []
- self._initialized = False
- # Pass a reference to the server manager to the tool
+async def main():
+ """Run the example with default logging and optional custom middleware."""
+ # Load environment variables
+ load_dotenv()
+
+ # Create custom middleware
+ class TimingMiddleware(Middleware):
+ async def on_request(self, context: MiddlewareContext[Any], call_next: NextFunctionT) -> Any:
+ start = time.time()
+ try:
+ print("--------------------------------")
+ print(f"{context.method} started")
+ print("--------------------------------")
+ print(f"{context.params}, {context.metadata}, {context.timestamp}, {context.connection_id}")
+ print("--------------------------------")
+ result = await call_next(context)
+ return result
+ finally:
+ duration = time.time() - start
+ print("--------------------------------")
+ print(f"{context.method} took {int(1000 * duration)}ms")
+ print("--------------------------------")
+
+ # Middleware that demonstrates mutating params and adding headers-like metadata
+ class MutationMiddleware(Middleware):
+ async def on_call_tool(self, context: MiddlewareContext[Any], call_next: NextFunctionT) -> Any:
+ # Defensive mutation of params: ensure `arguments` exists before writing
+ try:
+ print("[MutationMiddleware] context.params=", context.params)
+ args = getattr(context.params, "arguments", None)
```
-This class is important because it defines how MCP Use Tutorial: Full-Stack MCP Development Across Agents, Clients, Servers, and Inspector implements the patterns covered in this chapter.
+This function is important because it defines how MCP Use Tutorial: Full-Stack MCP Development Across Agents, Clients, Servers, and Inspector implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[DynamicTool]
- B[HelloWorldTool]
+ A[MutationMiddleware]
+ B[main]
A --> B
```
diff --git a/tutorials/mcp-use-tutorial/05-python-server-framework-and-debug-endpoints.md b/tutorials/mcp-use-tutorial/05-python-server-framework-and-debug-endpoints.md
index 9b943b33..d8652e8d 100644
--- a/tutorials/mcp-use-tutorial/05-python-server-framework-and-debug-endpoints.md
+++ b/tutorials/mcp-use-tutorial/05-python-server-framework-and-debug-endpoints.md
@@ -39,98 +39,96 @@ You now have a practical Python server development and debugging baseline.
Next: [Chapter 6: Inspector Debugging and Chat App Workflows](06-inspector-debugging-and-chat-app-workflows.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `libraries/python/examples/simple_server_manager_use.py`
+### `libraries/python/examples/openai_integration_example.py`
-The `SimpleServerManager` class in [`libraries/python/examples/simple_server_manager_use.py`](https://github.com/mcp-use/mcp-use/blob/HEAD/libraries/python/examples/simple_server_manager_use.py) handles a key part of this chapter's functionality:
+The `main` function in [`libraries/python/examples/openai_integration_example.py`](https://github.com/mcp-use/mcp-use/blob/HEAD/libraries/python/examples/openai_integration_example.py) handles a key part of this chapter's functionality:
```py
- description: str = "Returns the string 'Hello, World!' and adds a new dynamic tool."
- args_schema: type[BaseModel] | None = None
- server_manager: "SimpleServerManager"
- def _run(self) -> str:
- new_tool = DynamicTool(
- name=f"dynamic_tool_{len(self.server_manager.tools)}", description="A dynamically created tool."
- )
- self.server_manager.add_tool(new_tool)
- return "Hello, World! I've added a new tool. You can use it now."
- async def _arun(self) -> str:
- new_tool = DynamicTool(
- name=f"dynamic_tool_{len(self.server_manager.tools)}", description="A dynamically created tool."
- )
- self.server_manager.add_tool(new_tool)
- return "Hello, World! I've added a new tool. You can use it now."
+async def main():
+ config = {
+ "mcpServers": {
+ "airbnb": {"command": "npx", "args": ["-y", "@openbnb/mcp-server-airbnb", "--ignore-robots-txt"]},
+ }
+ }
+ try:
+ client = MCPClient(config=config)
-class SimpleServerManager(BaseServerManager):
- """A simple server manager that provides a HelloWorldTool."""
+ # Creates the adapter for OpenAI's format
+ adapter = OpenAIMCPAdapter()
- def __init__(self):
- self._tools: list[BaseTool] = []
- self._initialized = False
- # Pass a reference to the server manager to the tool
- self._tools.append(HelloWorldTool(server_manager=self))
+ # Convert tools from active connectors to the OpenAI's format
+ # this will populates the list of tools, resources and prompts
+ await adapter.create_all(client)
- def add_tool(self, tool: BaseTool):
- self._tools.append(tool)
+ # If you don't want to create all tools, you can call single functions
+ # await adapter.create_tools(client)
+ # await adapter.create_resources(client)
+ # await adapter.create_prompts(client)
+
+ # If you decided to create all tools (list concatenation)
+ openai_tools = adapter.tools + adapter.resources + adapter.prompts
+
+ # Use tools with OpenAI's SDK (not agent in this case)
+ openai = OpenAI()
+ messages = [{"role": "user", "content": "Please tell me the cheapest hotel for two people in Trapani."}]
+ response = openai.chat.completions.create(model="gpt-4o", messages=messages, tools=openai_tools)
- async def initialize(self) -> None:
```
-This class is important because it defines how MCP Use Tutorial: Full-Stack MCP Development Across Agents, Clients, Servers, and Inspector implements the patterns covered in this chapter.
+This function is important because it defines how MCP Use Tutorial: Full-Stack MCP Development Across Agents, Clients, Servers, and Inspector implements the patterns covered in this chapter.
### `libraries/python/examples/simple_server_manager_use.py`
-The `main` function in [`libraries/python/examples/simple_server_manager_use.py`](https://github.com/mcp-use/mcp-use/blob/HEAD/libraries/python/examples/simple_server_manager_use.py) handles a key part of this chapter's functionality:
+The `DynamicTool` class in [`libraries/python/examples/simple_server_manager_use.py`](https://github.com/mcp-use/mcp-use/blob/HEAD/libraries/python/examples/simple_server_manager_use.py) handles a key part of this chapter's functionality:
```py
-async def main():
- # Initialize the LLM
- llm = ChatOpenAI(model="gpt-5")
-
- # Instantiate the custom server manager
- simple_server_manager = SimpleServerManager()
-
- # Create an MCPAgent with the custom server manager
- agent = MCPAgent(
- llm=llm,
- use_server_manager=True,
- server_manager=simple_server_manager,
- pretty_print=True,
- )
-
- # Manually initialize the agent
- await agent.initialize()
-
- # Run the agent with a query that uses the custom tool
- print("--- First run: calling hello_world ---")
- result = await agent.run("Use the hello_world tool", manage_connector=False)
- print(result)
-
- # Clear the conversation history to avoid confusion
- agent.clear_conversation_history()
-
- # Run the agent again to show that the new tool is available
- print("\n--- Second run: calling the new dynamic tool ---")
- result = await agent.run("Use the dynamic_tool_1", manage_connector=False)
- print(result)
+class DynamicTool(BaseTool):
+ """A tool that is created dynamically."""
+
+ name: str
+ description: str
+ args_schema: type[BaseModel] | None = None
+
+ def _run(self) -> str:
+ return f"Hello from {self.name}!"
+
+ async def _arun(self) -> str:
+ return f"Hello from {self.name}!"
+
+
+class HelloWorldTool(BaseTool):
+ """A simple tool that returns a greeting and adds a new tool."""
+
+ name: str = "hello_world"
+ description: str = "Returns the string 'Hello, World!' and adds a new dynamic tool."
+ args_schema: type[BaseModel] | None = None
+ server_manager: "SimpleServerManager"
+
+ def _run(self) -> str:
+ new_tool = DynamicTool(
+ name=f"dynamic_tool_{len(self.server_manager.tools)}", description="A dynamically created tool."
+ )
+ self.server_manager.add_tool(new_tool)
+ return "Hello, World! I've added a new tool. You can use it now."
+
+ async def _arun(self) -> str:
```
-This function is important because it defines how MCP Use Tutorial: Full-Stack MCP Development Across Agents, Clients, Servers, and Inspector implements the patterns covered in this chapter.
+This class is important because it defines how MCP Use Tutorial: Full-Stack MCP Development Across Agents, Clients, Servers, and Inspector implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[SimpleServerManager]
- B[main]
+ A[main]
+ B[DynamicTool]
A --> B
```
diff --git a/tutorials/mcp-use-tutorial/06-inspector-debugging-and-chat-app-workflows.md b/tutorials/mcp-use-tutorial/06-inspector-debugging-and-chat-app-workflows.md
index 65b805f3..1da3df22 100644
--- a/tutorials/mcp-use-tutorial/06-inspector-debugging-and-chat-app-workflows.md
+++ b/tutorials/mcp-use-tutorial/06-inspector-debugging-and-chat-app-workflows.md
@@ -38,98 +38,96 @@ You now have a repeatable inspector workflow for debugging and quality validatio
Next: [Chapter 7: Security, Runtime Controls, and Production Hardening](07-security-runtime-controls-and-production-hardening.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `libraries/python/examples/anthropic_integration_example.py`
+### `libraries/python/examples/simple_server_manager_use.py`
-The `main` function in [`libraries/python/examples/anthropic_integration_example.py`](https://github.com/mcp-use/mcp-use/blob/HEAD/libraries/python/examples/anthropic_integration_example.py) handles a key part of this chapter's functionality:
+The `HelloWorldTool` class in [`libraries/python/examples/simple_server_manager_use.py`](https://github.com/mcp-use/mcp-use/blob/HEAD/libraries/python/examples/simple_server_manager_use.py) handles a key part of this chapter's functionality:
```py
-async def main():
- config = {
- "mcpServers": {
- "airbnb": {"command": "npx", "args": ["-y", "@openbnb/mcp-server-airbnb", "--ignore-robots-txt"]},
- }
- }
-
- try:
- client = MCPClient(config=config)
+class HelloWorldTool(BaseTool):
+ """A simple tool that returns a greeting and adds a new tool."""
- # Creates the adapter for Anthropic's format
- adapter = AnthropicMCPAdapter()
+ name: str = "hello_world"
+ description: str = "Returns the string 'Hello, World!' and adds a new dynamic tool."
+ args_schema: type[BaseModel] | None = None
+ server_manager: "SimpleServerManager"
- # Convert tools from active connectors to the Anthropic's format
- await adapter.create_all(client)
+ def _run(self) -> str:
+ new_tool = DynamicTool(
+ name=f"dynamic_tool_{len(self.server_manager.tools)}", description="A dynamically created tool."
+ )
+ self.server_manager.add_tool(new_tool)
+ return "Hello, World! I've added a new tool. You can use it now."
- # List concatenation (if you loaded all tools)
- anthropic_tools = adapter.tools + adapter.resources + adapter.prompts
+ async def _arun(self) -> str:
+ new_tool = DynamicTool(
+ name=f"dynamic_tool_{len(self.server_manager.tools)}", description="A dynamically created tool."
+ )
+ self.server_manager.add_tool(new_tool)
+ return "Hello, World! I've added a new tool. You can use it now."
- # If you don't want to create all tools, you can call single functions
- # await adapter.create_tools(client)
- # await adapter.create_resources(client)
- # await adapter.create_prompts(client)
- # Use tools with Anthropic's SDK (not agent in this case)
- anthropic = Anthropic()
+class SimpleServerManager(BaseServerManager):
+ """A simple server manager that provides a HelloWorldTool."""
- # Initial request
- messages = [{"role": "user", "content": "Please tell me the cheapest hotel for two people in Trapani."}]
- response = anthropic.messages.create(
+ def __init__(self):
+ self._tools: list[BaseTool] = []
+ self._initialized = False
+ # Pass a reference to the server manager to the tool
```
-This function is important because it defines how MCP Use Tutorial: Full-Stack MCP Development Across Agents, Clients, Servers, and Inspector implements the patterns covered in this chapter.
+This class is important because it defines how MCP Use Tutorial: Full-Stack MCP Development Across Agents, Clients, Servers, and Inspector implements the patterns covered in this chapter.
-### `libraries/python/examples/limited_memory_chat.py`
+### `libraries/python/examples/simple_server_manager_use.py`
-The `run_limited_memory_chat` function in [`libraries/python/examples/limited_memory_chat.py`](https://github.com/mcp-use/mcp-use/blob/HEAD/libraries/python/examples/limited_memory_chat.py) handles a key part of this chapter's functionality:
+The `SimpleServerManager` class in [`libraries/python/examples/simple_server_manager_use.py`](https://github.com/mcp-use/mcp-use/blob/HEAD/libraries/python/examples/simple_server_manager_use.py) handles a key part of this chapter's functionality:
```py
-
-
-async def run_limited_memory_chat():
- """Run a chat using MCPAgent with limited conversation memory."""
- # Load environment variables for API keys
- load_dotenv()
-
- config = {
- "mcpServers": {"playwright": {"command": "npx", "args": ["@playwright/mcp@latest"], "env": {"DISPLAY": ":1"}}}
- }
- # Create MCPClient from config file
- client = MCPClient(config=config)
- llm = ChatOpenAI(model="gpt-5")
- # Create agent with memory_enabled=False but pass external history
- agent = MCPAgent(
- llm=llm,
- client=client,
- max_steps=15,
- memory_enabled=True, # Disable built-in memory, use external history
- pretty_print=True,
- )
-
- # Configuration: Limited history mode
- MAX_HISTORY_MESSAGES = 5
-
- print("\n===== Interactive MCP Chat (Limited Memory) =====")
- print("Type 'exit' or 'quit' to end the conversation")
- print("Type 'clear' to clear conversation history")
- print("==================================\n")
-
- try:
- # Main chat loop with limited history
+ description: str = "Returns the string 'Hello, World!' and adds a new dynamic tool."
+ args_schema: type[BaseModel] | None = None
+ server_manager: "SimpleServerManager"
+
+ def _run(self) -> str:
+ new_tool = DynamicTool(
+ name=f"dynamic_tool_{len(self.server_manager.tools)}", description="A dynamically created tool."
+ )
+ self.server_manager.add_tool(new_tool)
+ return "Hello, World! I've added a new tool. You can use it now."
+
+ async def _arun(self) -> str:
+ new_tool = DynamicTool(
+ name=f"dynamic_tool_{len(self.server_manager.tools)}", description="A dynamically created tool."
+ )
+ self.server_manager.add_tool(new_tool)
+ return "Hello, World! I've added a new tool. You can use it now."
+
+
+class SimpleServerManager(BaseServerManager):
+ """A simple server manager that provides a HelloWorldTool."""
+
+ def __init__(self):
+ self._tools: list[BaseTool] = []
+ self._initialized = False
+ # Pass a reference to the server manager to the tool
+ self._tools.append(HelloWorldTool(server_manager=self))
+
+ def add_tool(self, tool: BaseTool):
+ self._tools.append(tool)
+
+ async def initialize(self) -> None:
```
-This function is important because it defines how MCP Use Tutorial: Full-Stack MCP Development Across Agents, Clients, Servers, and Inspector implements the patterns covered in this chapter.
+This class is important because it defines how MCP Use Tutorial: Full-Stack MCP Development Across Agents, Clients, Servers, and Inspector implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[main]
- B[run_limited_memory_chat]
+ A[HelloWorldTool]
+ B[SimpleServerManager]
A --> B
```
diff --git a/tutorials/mcp-use-tutorial/07-security-runtime-controls-and-production-hardening.md b/tutorials/mcp-use-tutorial/07-security-runtime-controls-and-production-hardening.md
index 31dbb2e9..20bf9a02 100644
--- a/tutorials/mcp-use-tutorial/07-security-runtime-controls-and-production-hardening.md
+++ b/tutorials/mcp-use-tutorial/07-security-runtime-controls-and-production-hardening.md
@@ -41,87 +41,86 @@ You now have a pragmatic hardening baseline for mcp-use deployments.
Next: [Chapter 8: Operations, Observability, and Contribution Model](08-operations-observability-and-contribution-model.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `libraries/python/mcp_use/logging.py`
+### `libraries/python/examples/simple_server_manager_use.py`
-The `Logger` class in [`libraries/python/mcp_use/logging.py`](https://github.com/mcp-use/mcp-use/blob/HEAD/libraries/python/mcp_use/logging.py) handles a key part of this chapter's functionality:
+The `main` function in [`libraries/python/examples/simple_server_manager_use.py`](https://github.com/mcp-use/mcp-use/blob/HEAD/libraries/python/examples/simple_server_manager_use.py) handles a key part of this chapter's functionality:
```py
-"""
-Logger module for mcp_use.
-
-This module provides a centralized logging configuration for the mcp_use library,
-with customizable log levels and formatters.
-"""
-
-import logging
-import os
-import sys
-from langchain_core.globals import set_debug as langchain_set_debug
-# Global debug flag - can be set programmatically or from environment
-MCP_USE_DEBUG = 1
+async def main():
+ # Initialize the LLM
+ llm = ChatOpenAI(model="gpt-5")
+ # Instantiate the custom server manager
+ simple_server_manager = SimpleServerManager()
-class Logger:
- """Centralized logger for mcp_use.
+ # Create an MCPAgent with the custom server manager
+ agent = MCPAgent(
+ llm=llm,
+ use_server_manager=True,
+ server_manager=simple_server_manager,
+ pretty_print=True,
+ )
- This class provides logging functionality with configurable levels,
- formatters, and handlers.
- """
+ # Manually initialize the agent
+ await agent.initialize()
- # Default log format
- DEFAULT_FORMAT = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+ # Run the agent with a query that uses the custom tool
+ print("--- First run: calling hello_world ---")
+ result = await agent.run("Use the hello_world tool", manage_connector=False)
+ print(result)
- # Module-specific loggers
- _loggers = {}
+ # Clear the conversation history to avoid confusion
+ agent.clear_conversation_history()
- @classmethod
+ # Run the agent again to show that the new tool is available
+ print("\n--- Second run: calling the new dynamic tool ---")
+ result = await agent.run("Use the dynamic_tool_1", manage_connector=False)
+ print(result)
```
-This class is important because it defines how MCP Use Tutorial: Full-Stack MCP Development Across Agents, Clients, Servers, and Inspector implements the patterns covered in this chapter.
+This function is important because it defines how MCP Use Tutorial: Full-Stack MCP Development Across Agents, Clients, Servers, and Inspector implements the patterns covered in this chapter.
-### `libraries/python/mcp_use/logging.py`
+### `libraries/python/examples/structured_output.py`
-The `provides` class in [`libraries/python/mcp_use/logging.py`](https://github.com/mcp-use/mcp-use/blob/HEAD/libraries/python/mcp_use/logging.py) handles a key part of this chapter's functionality:
+The `CityInfo` class in [`libraries/python/examples/structured_output.py`](https://github.com/mcp-use/mcp-use/blob/HEAD/libraries/python/examples/structured_output.py) handles a key part of this chapter's functionality:
```py
-Logger module for mcp_use.
-
-This module provides a centralized logging configuration for the mcp_use library,
-with customizable log levels and formatters.
-"""
-
-import logging
-import os
-import sys
-
-from langchain_core.globals import set_debug as langchain_set_debug
-
-# Global debug flag - can be set programmatically or from environment
-MCP_USE_DEBUG = 1
-
-
-class Logger:
- """Centralized logger for mcp_use.
-
- This class provides logging functionality with configurable levels,
- formatters, and handlers.
- """
-
- # Default log format
- DEFAULT_FORMAT = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
- # Module-specific loggers
- _loggers = {}
- @classmethod
- def get_logger(cls, name: str = "mcp_use") -> logging.Logger:
- """Get a logger instance for the specified name.
+class CityInfo(BaseModel):
+ """Comprehensive information about a city"""
+
+ name: str = Field(description="Official name of the city")
+ country: str = Field(description="Country where the city is located")
+ region: str = Field(description="Region or state within the country")
+ population: int = Field(description="Current population count")
+ area_km2: float = Field(description="Area in square kilometers")
+ foundation_date: str = Field(description="When the city was founded (approximate year or period)")
+ mayor: str = Field(description="Current mayor or city leader")
+ famous_landmarks: list[str] = Field(description="List of famous landmarks, monuments, or attractions")
+ universities: list[str] = Field(description="List of major universities or educational institutions")
+ economy_sectors: list[str] = Field(description="Main economic sectors or industries")
+ sister_cities: list[str] = Field(description="Twin cities or sister cities partnerships")
+ historical_significance: str = Field(description="Brief description of historical importance")
+ climate_type: str | None = Field(description="Type of climate (e.g., Mediterranean, Continental)", default=None)
+ elevation_meters: int | None = Field(description="Elevation above sea level in meters", default=None)
+
+
+async def main():
+ """Research Padova using intelligent structured output."""
+ load_dotenv()
+
+ config = {
+ "mcpServers": {"playwright": {"command": "npx", "args": ["@playwright/mcp@latest"], "env": {"DISPLAY": ":1"}}}
+ }
+
+ client = MCPClient(config=config)
+ llm = ChatOpenAI(model="gpt-5")
+ agent = MCPAgent(llm=llm, client=client, max_steps=50, pretty_print=True)
```
This class is important because it defines how MCP Use Tutorial: Full-Stack MCP Development Across Agents, Clients, Servers, and Inspector implements the patterns covered in this chapter.
@@ -131,7 +130,7 @@ This class is important because it defines how MCP Use Tutorial: Full-Stack MCP
```mermaid
flowchart TD
- A[Logger]
- B[provides]
+ A[main]
+ B[CityInfo]
A --> B
```
diff --git a/tutorials/mcp-use-tutorial/08-operations-observability-and-contribution-model.md b/tutorials/mcp-use-tutorial/08-operations-observability-and-contribution-model.md
index 1974154b..f2b53e84 100644
--- a/tutorials/mcp-use-tutorial/08-operations-observability-and-contribution-model.md
+++ b/tutorials/mcp-use-tutorial/08-operations-observability-and-contribution-model.md
@@ -40,53 +40,10 @@ You now have an end-to-end operational model for running and evolving mcp-use ba
Next: Continue with [MCP TypeScript SDK Tutorial](../mcp-typescript-sdk-tutorial/)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `libraries/python/examples/structured_output.py`
-The `CityInfo` class in [`libraries/python/examples/structured_output.py`](https://github.com/mcp-use/mcp-use/blob/HEAD/libraries/python/examples/structured_output.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-class CityInfo(BaseModel):
- """Comprehensive information about a city"""
-
- name: str = Field(description="Official name of the city")
- country: str = Field(description="Country where the city is located")
- region: str = Field(description="Region or state within the country")
- population: int = Field(description="Current population count")
- area_km2: float = Field(description="Area in square kilometers")
- foundation_date: str = Field(description="When the city was founded (approximate year or period)")
- mayor: str = Field(description="Current mayor or city leader")
- famous_landmarks: list[str] = Field(description="List of famous landmarks, monuments, or attractions")
- universities: list[str] = Field(description="List of major universities or educational institutions")
- economy_sectors: list[str] = Field(description="Main economic sectors or industries")
- sister_cities: list[str] = Field(description="Twin cities or sister cities partnerships")
- historical_significance: str = Field(description="Brief description of historical importance")
- climate_type: str | None = Field(description="Type of climate (e.g., Mediterranean, Continental)", default=None)
- elevation_meters: int | None = Field(description="Elevation above sea level in meters", default=None)
-
-
-async def main():
- """Research Padova using intelligent structured output."""
- load_dotenv()
-
- config = {
- "mcpServers": {"playwright": {"command": "npx", "args": ["@playwright/mcp@latest"], "env": {"DISPLAY": ":1"}}}
- }
-
- client = MCPClient(config=config)
- llm = ChatOpenAI(model="gpt-5")
- agent = MCPAgent(llm=llm, client=client, max_steps=50, pretty_print=True)
-```
-
-This class is important because it defines how MCP Use Tutorial: Full-Stack MCP Development Across Agents, Clients, Servers, and Inspector implements the patterns covered in this chapter.
-
-### `libraries/python/examples/structured_output.py`
-
The `main` function in [`libraries/python/examples/structured_output.py`](https://github.com/mcp-use/mcp-use/blob/HEAD/libraries/python/examples/structured_output.py) handles a key part of this chapter's functionality:
```py
@@ -126,12 +83,53 @@ async def main():
This function is important because it defines how MCP Use Tutorial: Full-Stack MCP Development Across Agents, Clients, Servers, and Inspector implements the patterns covered in this chapter.
+### `libraries/python/examples/limited_memory_chat.py`
+
+The `run_limited_memory_chat` function in [`libraries/python/examples/limited_memory_chat.py`](https://github.com/mcp-use/mcp-use/blob/HEAD/libraries/python/examples/limited_memory_chat.py) handles a key part of this chapter's functionality:
+
+```py
+
+
+async def run_limited_memory_chat():
+ """Run a chat using MCPAgent with limited conversation memory."""
+ # Load environment variables for API keys
+ load_dotenv()
+
+ config = {
+ "mcpServers": {"playwright": {"command": "npx", "args": ["@playwright/mcp@latest"], "env": {"DISPLAY": ":1"}}}
+ }
+ # Create MCPClient from config file
+ client = MCPClient(config=config)
+ llm = ChatOpenAI(model="gpt-5")
+ # Create agent with memory_enabled=False but pass external history
+ agent = MCPAgent(
+ llm=llm,
+ client=client,
+ max_steps=15,
+ memory_enabled=True, # Disable built-in memory, use external history
+ pretty_print=True,
+ )
+
+ # Configuration: Limited history mode
+ MAX_HISTORY_MESSAGES = 5
+
+ print("\n===== Interactive MCP Chat (Limited Memory) =====")
+ print("Type 'exit' or 'quit' to end the conversation")
+ print("Type 'clear' to clear conversation history")
+ print("==================================\n")
+
+ try:
+ # Main chat loop with limited history
+```
+
+This function is important because it defines how MCP Use Tutorial: Full-Stack MCP Development Across Agents, Clients, Servers, and Inspector implements the patterns covered in this chapter.
+
## How These Components Connect
```mermaid
flowchart TD
- A[CityInfo]
- B[main]
+ A[main]
+ B[run_limited_memory_chat]
A --> B
```
diff --git a/tutorials/mcpb-tutorial/01-getting-started-and-bundle-fundamentals.md b/tutorials/mcpb-tutorial/01-getting-started-and-bundle-fundamentals.md
index fb16cbe5..69a937f9 100644
--- a/tutorials/mcpb-tutorial/01-getting-started-and-bundle-fundamentals.md
+++ b/tutorials/mcpb-tutorial/01-getting-started-and-bundle-fundamentals.md
@@ -39,8 +39,6 @@ You now have a baseline model for creating MCP bundles from local server project
Next: [Chapter 2: Manifest Model, Metadata, and Compatibility](02-manifest-model-metadata-and-compatibility.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `src/types.ts`
diff --git a/tutorials/mcpb-tutorial/02-manifest-model-metadata-and-compatibility.md b/tutorials/mcpb-tutorial/02-manifest-model-metadata-and-compatibility.md
index 6c66f148..388ba4a5 100644
--- a/tutorials/mcpb-tutorial/02-manifest-model-metadata-and-compatibility.md
+++ b/tutorials/mcpb-tutorial/02-manifest-model-metadata-and-compatibility.md
@@ -39,8 +39,6 @@ You now have a manifest-first strategy for bundle interoperability and lifecycle
Next: [Chapter 3: Server Configuration and Runtime Packaging](03-server-configuration-and-runtime-packaging.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `src/cli/init.ts`
diff --git a/tutorials/mcpb-tutorial/03-server-configuration-and-runtime-packaging.md b/tutorials/mcpb-tutorial/03-server-configuration-and-runtime-packaging.md
index f94492a0..30da70f1 100644
--- a/tutorials/mcpb-tutorial/03-server-configuration-and-runtime-packaging.md
+++ b/tutorials/mcpb-tutorial/03-server-configuration-and-runtime-packaging.md
@@ -41,8 +41,6 @@ You now have a runtime packaging model for reliable MCPB installation and execut
Next: [Chapter 4: Tools, Prompts, User Config, and Localization](04-tools-prompts-user-config-and-localization.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `src/cli/init.ts`
diff --git a/tutorials/mcpb-tutorial/04-tools-prompts-user-config-and-localization.md b/tutorials/mcpb-tutorial/04-tools-prompts-user-config-and-localization.md
index 231a5e1f..576f2bea 100644
--- a/tutorials/mcpb-tutorial/04-tools-prompts-user-config-and-localization.md
+++ b/tutorials/mcpb-tutorial/04-tools-prompts-user-config-and-localization.md
@@ -39,8 +39,6 @@ You now have a configuration and localization strategy for robust bundle UX.
Next: [Chapter 5: CLI Workflows: Init, Validate, and Pack](05-cli-workflows-init-validate-and-pack.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `src/cli/init.ts`
diff --git a/tutorials/mcpb-tutorial/05-cli-workflows-init-validate-and-pack.md b/tutorials/mcpb-tutorial/05-cli-workflows-init-validate-and-pack.md
index 42c3a50b..d8153212 100644
--- a/tutorials/mcpb-tutorial/05-cli-workflows-init-validate-and-pack.md
+++ b/tutorials/mcpb-tutorial/05-cli-workflows-init-validate-and-pack.md
@@ -38,8 +38,6 @@ You now have a repeatable packaging workflow for MCPB bundle production.
Next: [Chapter 6: Signing, Verification, and Trust Controls](06-signing-verification-and-trust-controls.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `src/cli/init.ts`
diff --git a/tutorials/mcpb-tutorial/06-signing-verification-and-trust-controls.md b/tutorials/mcpb-tutorial/06-signing-verification-and-trust-controls.md
index 9185d652..e40855ca 100644
--- a/tutorials/mcpb-tutorial/06-signing-verification-and-trust-controls.md
+++ b/tutorials/mcpb-tutorial/06-signing-verification-and-trust-controls.md
@@ -40,8 +40,6 @@ You now have a security-oriented workflow for trusted MCPB distribution.
Next: [Chapter 7: Examples, Language Patterns, and Distribution Readiness](07-examples-language-patterns-and-distribution-readiness.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `src/node/sign.ts`
diff --git a/tutorials/mcpb-tutorial/07-examples-language-patterns-and-distribution-readiness.md b/tutorials/mcpb-tutorial/07-examples-language-patterns-and-distribution-readiness.md
index a714268a..e5044348 100644
--- a/tutorials/mcpb-tutorial/07-examples-language-patterns-and-distribution-readiness.md
+++ b/tutorials/mcpb-tutorial/07-examples-language-patterns-and-distribution-readiness.md
@@ -37,170 +37,168 @@ You now have an example-driven framework for taking bundles from prototype to ha
Next: [Chapter 8: Release, Governance, and Ecosystem Operations](08-release-governance-and-ecosystem-operations.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/cli/pack.ts`
+### `src/shared/config.ts`
-The `formatFileSize` function in [`src/cli/pack.ts`](https://github.com/modelcontextprotocol/mcpb/blob/HEAD/src/cli/pack.ts) handles a key part of this chapter's functionality:
+The `getMcpConfigForManifest` function in [`src/shared/config.ts`](https://github.com/modelcontextprotocol/mcpb/blob/HEAD/src/shared/config.ts) handles a key part of this chapter's functionality:
```ts
}
-function formatFileSize(bytes: number): string {
- if (bytes < 1024) {
- return `${bytes}B`;
- } else if (bytes < 1024 * 1024) {
- return `${(bytes / 1024).toFixed(1)}kB`;
- } else {
- return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+export async function getMcpConfigForManifest(
+ options: GetMcpConfigForManifestOptions,
+): Promise<McpbManifestAny["server"]["mcp_config"] | undefined> {
+ const {
+ manifest,
+ extensionPath,
+ systemDirs,
+ userConfig,
+ pathSeparator,
+ logger,
+ } = options;
+ const baseConfig = manifest.server?.mcp_config;
+ if (!baseConfig) {
+ return undefined;
}
-}
-function sanitizeNameForFilename(name: string): string {
- // Replace spaces with hyphens
- // Remove or replace characters that are problematic in filenames
- return name
- .toLowerCase()
- .replace(/\s+/g, "-") // Replace spaces with hyphens
- .replace(/[^a-z0-9-_.]/g, "") // Keep only alphanumeric, hyphens, underscores, and dots
- .replace(/-+/g, "-") // Replace multiple hyphens with single hyphen
- .replace(/^-+|-+$/g, "") // Remove leading/trailing hyphens
- .substring(0, 100); // Limit length to 100 characters
-}
+ let result: McpbManifestAny["server"]["mcp_config"] = {
+ ...baseConfig,
+ };
-export async function packExtension({
- extensionPath,
- outputPath,
- silent,
-}: PackOptions): Promise<boolean> {
- const resolvedPath = resolve(extensionPath);
- const logger = getLogger({ silent });
+ if (baseConfig.platform_overrides) {
+ if (process.platform in baseConfig.platform_overrides) {
+ const platformConfig = baseConfig.platform_overrides[process.platform];
+
+ result.command = platformConfig.command || result.command;
+ result.args = platformConfig.args || result.args;
+ result.env = platformConfig.env || result.env;
+ }
+ }
```
This function is important because it defines how MCPB Tutorial: Packaging and Distributing Local MCP Servers as Bundles implements the patterns covered in this chapter.
-### `src/cli/pack.ts`
+### `src/shared/config.ts`
-The `sanitizeNameForFilename` function in [`src/cli/pack.ts`](https://github.com/modelcontextprotocol/mcpb/blob/HEAD/src/cli/pack.ts) handles a key part of this chapter's functionality:
+The `isInvalidSingleValue` function in [`src/shared/config.ts`](https://github.com/modelcontextprotocol/mcpb/blob/HEAD/src/shared/config.ts) handles a key part of this chapter's functionality:
```ts
}
-function sanitizeNameForFilename(name: string): string {
- // Replace spaces with hyphens
- // Remove or replace characters that are problematic in filenames
- return name
- .toLowerCase()
- .replace(/\s+/g, "-") // Replace spaces with hyphens
- .replace(/[^a-z0-9-_.]/g, "") // Keep only alphanumeric, hyphens, underscores, and dots
- .replace(/-+/g, "-") // Replace multiple hyphens with single hyphen
- .replace(/^-+|-+$/g, "") // Remove leading/trailing hyphens
- .substring(0, 100); // Limit length to 100 characters
+function isInvalidSingleValue(value: unknown): boolean {
+ return value === undefined || value === null || value === "";
}
-export async function packExtension({
- extensionPath,
- outputPath,
- silent,
-}: PackOptions): Promise<boolean> {
- const resolvedPath = resolve(extensionPath);
- const logger = getLogger({ silent });
-
- // Check if directory exists
- if (!existsSync(resolvedPath) || !statSync(resolvedPath).isDirectory()) {
- logger.error(`ERROR: Directory not found: ${extensionPath}`);
+/**
+ * Check if an extension has missing required configuration
+ * @param manifest The extension manifest
+ * @param userConfig The user configuration
+ * @returns true if required configuration is missing
+ */
+export function hasRequiredConfigMissing({
+ manifest,
+ userConfig,
+}: HasRequiredConfigMissingOptions): boolean {
+ if (!manifest.user_config) {
return false;
}
- // Check if manifest exists
- const manifestPath = join(resolvedPath, "manifest.json");
- if (!existsSync(manifestPath)) {
- logger.log(`No manifest.json found in ${extensionPath}`);
+ const config = userConfig || {};
+
+ for (const [key, configOption] of Object.entries(manifest.user_config)) {
+ if (configOption.required) {
+ const value = config[key];
+ if (
+ isInvalidSingleValue(value) ||
+ (Array.isArray(value) &&
+ (value.length === 0 || value.some(isInvalidSingleValue)))
+ ) {
+ return true;
+ }
```
This function is important because it defines how MCPB Tutorial: Packaging and Distributing Local MCP Servers as Bundles implements the patterns covered in this chapter.
-### `src/cli/pack.ts`
+### `src/shared/config.ts`
-The `packExtension` function in [`src/cli/pack.ts`](https://github.com/modelcontextprotocol/mcpb/blob/HEAD/src/cli/pack.ts) handles a key part of this chapter's functionality:
+The `hasRequiredConfigMissing` function in [`src/shared/config.ts`](https://github.com/modelcontextprotocol/mcpb/blob/HEAD/src/shared/config.ts) handles a key part of this chapter's functionality:
```ts
-}
-export async function packExtension({
- extensionPath,
- outputPath,
- silent,
-}: PackOptions): Promise<boolean> {
- const resolvedPath = resolve(extensionPath);
- const logger = getLogger({ silent });
-
- // Check if directory exists
- if (!existsSync(resolvedPath) || !statSync(resolvedPath).isDirectory()) {
- logger.error(`ERROR: Directory not found: ${extensionPath}`);
- return false;
+ // Check if required configuration is missing
+ if (hasRequiredConfigMissing({ manifest, userConfig })) {
+ logger?.warn(
+ `Extension ${manifest.name} has missing required configuration, skipping MCP config`,
+ );
+ return undefined;
}
- // Check if manifest exists
- const manifestPath = join(resolvedPath, "manifest.json");
- if (!existsSync(manifestPath)) {
- logger.log(`No manifest.json found in ${extensionPath}`);
- const shouldInit = await confirm({
- message: "Would you like to create a manifest.json file?",
- default: true,
- });
-
- if (shouldInit) {
- const success = await initExtension(extensionPath);
- if (!success) {
- logger.error("ERROR: Failed to create manifest");
- return false;
+ const variables: Record<string, string | string[]> = {
+ __dirname: extensionPath,
+ pathSeparator,
+ "/": pathSeparator,
+ ...systemDirs,
+ };
+
+ // Build merged configuration from defaults and user settings
+ const mergedConfig: Record<string, unknown> = {};
+
+ // First, add defaults from manifest
+ if (manifest.user_config) {
+ for (const [key, configOption] of Object.entries(manifest.user_config)) {
+ if (configOption.default !== undefined) {
+ mergedConfig[key] = configOption.default;
}
- } else {
+ }
+ }
+
+ // Then, override with user settings
+ if (userConfig) {
+ Object.assign(mergedConfig, userConfig);
+ }
```
This function is important because it defines how MCPB Tutorial: Packaging and Distributing Local MCP Servers as Bundles implements the patterns covered in this chapter.
-### `src/cli/pack.ts`
+### `src/shared/config.ts`
-The `PackOptions` interface in [`src/cli/pack.ts`](https://github.com/modelcontextprotocol/mcpb/blob/HEAD/src/cli/pack.ts) handles a key part of this chapter's functionality:
+The `GetMcpConfigForManifestOptions` interface in [`src/shared/config.ts`](https://github.com/modelcontextprotocol/mcpb/blob/HEAD/src/shared/config.ts) handles a key part of this chapter's functionality:
```ts
-import { initExtension } from "./init.js";
+}
-interface PackOptions {
+interface GetMcpConfigForManifestOptions {
+ manifest: McpbManifestAny;
extensionPath: string;
- outputPath?: string;
- silent?: boolean;
+ systemDirs: Record<string, string>;
+ userConfig: z.infer<typeof McpbUserConfigValuesSchema>;
+ pathSeparator: string;
+ logger?: Logger;
}
-function formatFileSize(bytes: number): string {
- if (bytes < 1024) {
- return `${bytes}B`;
- } else if (bytes < 1024 * 1024) {
- return `${(bytes / 1024).toFixed(1)}kB`;
- } else {
- return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+export async function getMcpConfigForManifest(
+ options: GetMcpConfigForManifestOptions,
+): Promise<McpbManifestAny["server"]["mcp_config"] | undefined> {
+ const {
+ manifest,
+ extensionPath,
+ systemDirs,
+ userConfig,
+ pathSeparator,
+ logger,
+ } = options;
+ const baseConfig = manifest.server?.mcp_config;
+ if (!baseConfig) {
+ return undefined;
}
-}
-function sanitizeNameForFilename(name: string): string {
- // Replace spaces with hyphens
- // Remove or replace characters that are problematic in filenames
- return name
- .toLowerCase()
- .replace(/\s+/g, "-") // Replace spaces with hyphens
- .replace(/[^a-z0-9-_.]/g, "") // Keep only alphanumeric, hyphens, underscores, and dots
- .replace(/-+/g, "-") // Replace multiple hyphens with single hyphen
- .replace(/^-+|-+$/g, "") // Remove leading/trailing hyphens
- .substring(0, 100); // Limit length to 100 characters
-}
+ let result: McpbManifestAny["server"]["mcp_config"] = {
+ ...baseConfig,
+ };
-export async function packExtension({
- extensionPath,
+ if (baseConfig.platform_overrides) {
```
This interface is important because it defines how MCPB Tutorial: Packaging and Distributing Local MCP Servers as Bundles implements the patterns covered in this chapter.
@@ -210,11 +208,11 @@ This interface is important because it defines how MCPB Tutorial: Packaging and
```mermaid
flowchart TD
- A[formatFileSize]
- B[sanitizeNameForFilename]
- C[packExtension]
- D[PackOptions]
- E[isPNG]
+ A[getMcpConfigForManifest]
+ B[isInvalidSingleValue]
+ C[hasRequiredConfigMissing]
+ D[GetMcpConfigForManifestOptions]
+ E[HasRequiredConfigMissingOptions]
A --> B
B --> C
C --> D
diff --git a/tutorials/mcpb-tutorial/08-release-governance-and-ecosystem-operations.md b/tutorials/mcpb-tutorial/08-release-governance-and-ecosystem-operations.md
index 04157cf4..b561d0c6 100644
--- a/tutorials/mcpb-tutorial/08-release-governance-and-ecosystem-operations.md
+++ b/tutorials/mcpb-tutorial/08-release-governance-and-ecosystem-operations.md
@@ -39,12 +39,92 @@ You now have a governance model for operating MCPB packaging and distribution at
Return to the [MCPB Tutorial index](README.md).
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `src/node/validate.ts`
+The `isPNG` function in [`src/node/validate.ts`](https://github.com/modelcontextprotocol/mcpb/blob/HEAD/src/node/validate.ts) handles a key part of this chapter's functionality:
+
+```ts
+ * Check if a buffer contains a valid PNG file signature
+ */
+function isPNG(buffer: Buffer): boolean {
+ // PNG signature: 89 50 4E 47 0D 0A 1A 0A
+ return (
+ buffer.length >= 8 &&
+ buffer[0] === 0x89 &&
+ buffer[1] === 0x50 &&
+ buffer[2] === 0x4e &&
+ buffer[3] === 0x47 &&
+ buffer[4] === 0x0d &&
+ buffer[5] === 0x0a &&
+ buffer[6] === 0x1a &&
+ buffer[7] === 0x0a
+ );
+}
+
+/**
+ * Validate icon field in manifest
+ * @param iconPath - The icon path from manifest.json
+ * @param baseDir - The base directory containing the manifest
+ * @returns Validation result with errors and warnings
+ */
+function validateIcon(
+ iconPath: string,
+ baseDir: string,
+): { valid: boolean; errors: string[]; warnings: string[] } {
+ const errors: string[] = [];
+ const warnings: string[] = [];
+
+ const isRemoteUrl =
+ iconPath.startsWith("http://") || iconPath.startsWith("https://");
+```
+
+This function is important because it defines how MCPB Tutorial: Packaging and Distributing Local MCP Servers as Bundles implements the patterns covered in this chapter.
+
+### `src/node/validate.ts`
+
+The `validateIcon` function in [`src/node/validate.ts`](https://github.com/modelcontextprotocol/mcpb/blob/HEAD/src/node/validate.ts) handles a key part of this chapter's functionality:
+
+```ts
+ * @returns Validation result with errors and warnings
+ */
+function validateIcon(
+ iconPath: string,
+ baseDir: string,
+): { valid: boolean; errors: string[]; warnings: string[] } {
+ const errors: string[] = [];
+ const warnings: string[] = [];
+
+ const isRemoteUrl =
+ iconPath.startsWith("http://") || iconPath.startsWith("https://");
+ const hasVariableSubstitution = iconPath.includes("${__dirname}");
+ const isAbsolutePath = isAbsolute(iconPath);
+
+ // Warn about remote URLs (best practice: use local files)
+ if (isRemoteUrl) {
+ warnings.push(
+ "Icon path uses a remote URL. " +
+ 'Best practice for local MCP servers: Use local files like "icon": "icon.png" for maximum compatibility. ' +
+ "Claude Desktop currently only supports local icon files in bundles.",
+ );
+ }
+
+ // Check for ${__dirname} variable (error - doesn't work)
+ if (hasVariableSubstitution) {
+ errors.push(
+ "Icon path should not use ${__dirname} variable substitution. " +
+ 'Use a simple relative path like "icon.png" instead of "${__dirname}/icon.png".',
+ );
+ }
+
+ // Check for absolute path (error - not portable)
+```
+
+This function is important because it defines how MCPB Tutorial: Packaging and Distributing Local MCP Servers as Bundles implements the patterns covered in this chapter.
+
+### `src/node/validate.ts`
+
The `validateManifest` function in [`src/node/validate.ts`](https://github.com/modelcontextprotocol/mcpb/blob/HEAD/src/node/validate.ts) handles a key part of this chapter's functionality:
```ts
@@ -125,98 +205,16 @@ export async function cleanMcpb(inputPath: string) {
This function is important because it defines how MCPB Tutorial: Packaging and Distributing Local MCP Servers as Bundles implements the patterns covered in this chapter.
-### `src/shared/config.ts`
-
-The `replaceVariables` function in [`src/shared/config.ts`](https://github.com/modelcontextprotocol/mcpb/blob/HEAD/src/shared/config.ts) handles a key part of this chapter's functionality:
-
-```ts
- * @returns The processed value with all variables replaced
- */
-export function replaceVariables(
- value: unknown,
- variables: Record<string, string | string[]>,
-): unknown {
- if (typeof value === "string") {
- let result = value;
-
- // Replace all variables in the string
- for (const [key, replacement] of Object.entries(variables)) {
- const pattern = new RegExp(`\\$\\{${key}\\}`, "g");
-
- // Check if this pattern actually exists in the string
- if (result.match(pattern)) {
- if (Array.isArray(replacement)) {
- console.warn(
- `Cannot replace ${key} with array value in string context: "${value}"`,
- { key, replacement },
- );
- } else {
- result = result.replace(pattern, replacement);
- }
- }
- }
-
- return result;
- } else if (Array.isArray(value)) {
- // For arrays, we need to handle special case of array expansion
- const result: unknown[] = [];
-
- for (const item of value) {
-```
-
-This function is important because it defines how MCPB Tutorial: Packaging and Distributing Local MCP Servers as Bundles implements the patterns covered in this chapter.
-
-### `src/shared/config.ts`
-
-The `getMcpConfigForManifest` function in [`src/shared/config.ts`](https://github.com/modelcontextprotocol/mcpb/blob/HEAD/src/shared/config.ts) handles a key part of this chapter's functionality:
-
-```ts
-}
-
-export async function getMcpConfigForManifest(
- options: GetMcpConfigForManifestOptions,
-): Promise<McpbManifestAny["server"]["mcp_config"] | undefined> {
- const {
- manifest,
- extensionPath,
- systemDirs,
- userConfig,
- pathSeparator,
- logger,
- } = options;
- const baseConfig = manifest.server?.mcp_config;
- if (!baseConfig) {
- return undefined;
- }
-
- let result: McpbManifestAny["server"]["mcp_config"] = {
- ...baseConfig,
- };
-
- if (baseConfig.platform_overrides) {
- if (process.platform in baseConfig.platform_overrides) {
- const platformConfig = baseConfig.platform_overrides[process.platform];
-
- result.command = platformConfig.command || result.command;
- result.args = platformConfig.args || result.args;
- result.env = platformConfig.env || result.env;
- }
- }
-
-```
-
-This function is important because it defines how MCPB Tutorial: Packaging and Distributing Local MCP Servers as Bundles implements the patterns covered in this chapter.
-
## How These Components Connect
```mermaid
flowchart TD
- A[validateManifest]
- B[cleanMcpb]
- C[replaceVariables]
- D[getMcpConfigForManifest]
- E[isInvalidSingleValue]
+ A[isPNG]
+ B[validateIcon]
+ C[validateManifest]
+ D[cleanMcpb]
+ E[formatFileSize]
A --> B
B --> C
C --> D
diff --git a/tutorials/mem0-tutorial/01-getting-started.md b/tutorials/mem0-tutorial/01-getting-started.md
index 39c8767c..3b5e85da 100644
--- a/tutorials/mem0-tutorial/01-getting-started.md
+++ b/tutorials/mem0-tutorial/01-getting-started.md
@@ -11,6 +11,17 @@ Welcome to Mem0! If you've ever built AI applications and wished they could reme
## What Makes Mem0 Special?
+```mermaid
+flowchart LR
+ A[User Input] --> B[mem0.Memory]
+ B --> C[add memory]
+ C --> D[Vector Store]
+ D --> E[search relevant]
+ E --> F[LLM + context]
+ F --> G[Personalized response]
+ G --> H[update memory]
+```
+
Mem0 revolutionizes AI memory with:
- **+26% Accuracy** over traditional memory approaches on industry benchmarks
- **91% Faster Responses** through intelligent memory retrieval
diff --git a/tutorials/mem0-tutorial/02-memory-architecture.md b/tutorials/mem0-tutorial/02-memory-architecture.md
index 0908e9d8..96d37b3f 100644
--- a/tutorials/mem0-tutorial/02-memory-architecture.md
+++ b/tutorials/mem0-tutorial/02-memory-architecture.md
@@ -14,6 +14,19 @@ Welcome to **Chapter 2: Memory Architecture & Types**. In this part of **Mem0 Tu
## 🎯 Overview
+```mermaid
+flowchart TD
+ A[Memory Layer] --> B[User Memory]
+ A --> C[Agent Memory]
+ A --> D[Session Memory]
+ B --> E[Long-term preferences]
+ C --> F[Task state]
+ D --> G[Conversation context]
+ B --> H[(Vector Store)]
+ C --> H
+ D --> H
+```
+
This chapter dives deep into Mem0's memory architecture, exploring the different types of memory, storage mechanisms, and how the system manages context across conversations. You'll understand how Mem0 creates a scalable, intelligent memory layer for AI applications.
## 🏗️ Memory Architecture Overview
diff --git a/tutorials/mem0-tutorial/03-memory-operations.md b/tutorials/mem0-tutorial/03-memory-operations.md
index d944c817..96219f58 100644
--- a/tutorials/mem0-tutorial/03-memory-operations.md
+++ b/tutorials/mem0-tutorial/03-memory-operations.md
@@ -14,6 +14,18 @@ Welcome to **Chapter 3: Core Memory Operations**. In this part of **Mem0 Tutoria
## 🎯 Overview
+```mermaid
+flowchart LR
+ A[memory.add text user_id] --> B[Embed text]
+ B --> C[Store vector]
+ C --> D[(Vector DB)]
+ E[memory.search query user_id] --> F[Embed query]
+ F --> G[ANN search]
+ G --> D
+ D --> H[Relevant memories]
+ I[memory.delete mem_id] --> D
+```
+
This chapter covers the core operations you can perform with Mem0 memories, including creating, retrieving, updating, and deleting memories. You'll learn how to effectively manage memory content and metadata for optimal AI agent performance.
## ➕ Adding Memories
diff --git a/tutorials/mem0-tutorial/04-advanced-features.md b/tutorials/mem0-tutorial/04-advanced-features.md
index 9b629598..36119b5c 100644
--- a/tutorials/mem0-tutorial/04-advanced-features.md
+++ b/tutorials/mem0-tutorial/04-advanced-features.md
@@ -14,6 +14,17 @@ Welcome to **Chapter 4: Advanced Memory Features**. In this part of **Mem0 Tutor
## 🎯 Overview
+```mermaid
+flowchart TD
+ A[New memory candidate] --> B{Duplicate check}
+ B -->|duplicate| C[Skip]
+ B -->|new| D[Semantic dedup]
+ D --> E[Store memory]
+ E --> F[Consolidation job]
+ F --> G[Merged memories]
+ G --> H[(Optimized store)]
+```
+
This chapter explores Mem0's advanced features including semantic search capabilities, memory consolidation algorithms, intelligent memory optimization, and adaptive learning systems that make AI agents truly intelligent and personalized.
## 🔍 Semantic Search and Retrieval
diff --git a/tutorials/mem0-tutorial/05-llm-integration.md b/tutorials/mem0-tutorial/05-llm-integration.md
index c819fab3..c7ee6bea 100644
--- a/tutorials/mem0-tutorial/05-llm-integration.md
+++ b/tutorials/mem0-tutorial/05-llm-integration.md
@@ -14,6 +14,17 @@ Welcome to **Chapter 5: Integrating with LLMs**. In this part of **Mem0 Tutorial
## 🎯 Overview
+```mermaid
+flowchart LR
+ A[Provider config] --> B{LLM backend}
+ B -->|OpenAI| C[gpt-4o]
+ B -->|Anthropic| D[claude-3-5-sonnet]
+ B -->|Ollama| E[local model]
+ C --> F[Memory-augmented completion]
+ D --> F
+ E --> F
+```
+
This chapter covers integrating Mem0 with different LLM providers, implementing memory-augmented conversations, and building sophisticated AI agents that leverage persistent memory for more intelligent and personalized interactions.
## 🤖 LLM Provider Integration
diff --git a/tutorials/mem0-tutorial/06-memory-applications.md b/tutorials/mem0-tutorial/06-memory-applications.md
index 52b59f8c..87df0af9 100644
--- a/tutorials/mem0-tutorial/06-memory-applications.md
+++ b/tutorials/mem0-tutorial/06-memory-applications.md
@@ -14,6 +14,16 @@ Welcome to **Chapter 6: Building Memory-Enabled Applications**. In this part of
## 🎯 Overview
+```mermaid
+flowchart TD
+ A[User query] --> B[search memories]
+ B --> C[Top-K memories]
+ C --> D[Build prompt with context]
+ D --> E[LLM response]
+ E --> F[add new memories from turn]
+ F --> G[Updated user model]
+```
+
This chapter demonstrates practical applications of Mem0 across different domains, showing how to build memory-enabled AI systems for customer support, content creation, learning platforms, and more. You'll learn to integrate memory capabilities into complete applications.
## 💬 Customer Support Chatbot
diff --git a/tutorials/mem0-tutorial/07-performance-optimization.md b/tutorials/mem0-tutorial/07-performance-optimization.md
index 66cc714c..89ffda24 100644
--- a/tutorials/mem0-tutorial/07-performance-optimization.md
+++ b/tutorials/mem0-tutorial/07-performance-optimization.md
@@ -14,6 +14,17 @@ Welcome to **Chapter 7: Performance Optimization**. In this part of **Mem0 Tutor
## 🎯 Overview
+```mermaid
+flowchart LR
+ A[Memory write] --> B[Async queue]
+ B --> C[Batch embed]
+ C --> D[Bulk upsert vector DB]
+ E[Memory read] --> F[Cache layer]
+ F -->|hit| G[Return cached]
+ F -->|miss| H[Vector search]
+ H --> F
+```
+
This chapter covers performance optimization techniques for Mem0 memory systems, including indexing strategies, caching mechanisms, batch processing, and scaling approaches to handle enterprise-level workloads efficiently.
## 🚀 Memory Indexing Strategies
diff --git a/tutorials/mem0-tutorial/08-production-deployment.md b/tutorials/mem0-tutorial/08-production-deployment.md
index 0bfac216..32e693b1 100644
--- a/tutorials/mem0-tutorial/08-production-deployment.md
+++ b/tutorials/mem0-tutorial/08-production-deployment.md
@@ -15,6 +15,17 @@ Welcome to **Chapter 8: Production Deployment & Scaling**. In this part of **Mem
## Production Architecture
+```mermaid
+flowchart TD
+ A[mem0 API server] --> B[Auth middleware]
+ B --> C[Rate limiter]
+ C --> D[Memory service]
+ D --> E[(Vector DB cluster)]
+ D --> F[(Relational DB)]
+ G[Monitoring] --> D
+ H[Health checks] --> A
+```
+
Recommended production setup:
```
diff --git a/tutorials/metagpt-tutorial/01-getting-started.md b/tutorials/metagpt-tutorial/01-getting-started.md
index 1bf33830..cf9a74fc 100644
--- a/tutorials/metagpt-tutorial/01-getting-started.md
+++ b/tutorials/metagpt-tutorial/01-getting-started.md
@@ -272,6 +272,16 @@ The core engine works as an event-driven loop:
In this chapter you installed MetaGPT, configured it for your LLM provider, and ran your first multi-agent generation. You saw how a single requirement flows through ProductManager, Architect, Engineer, and QA agents to produce a complete project.
+## Source Code Walkthrough
+
+Key source files to explore in [`geekan/MetaGPT`](https://github.com/geekan/MetaGPT):
+
+- [`metagpt/software_company.py`](https://github.com/geekan/MetaGPT/blob/main/metagpt/software_company.py) -- entry point for `generate_repo`; shows how the team is assembled and the run loop started
+- [`metagpt/config2.py`](https://github.com/geekan/MetaGPT/blob/main/metagpt/config2.py) -- `Config` dataclass with `llm`, `max_budget`, and workspace settings
+- [`metagpt/team.py`](https://github.com/geekan/MetaGPT/blob/main/metagpt/team.py) -- `Team.run()` method: the main event loop that drives all role executions
+
+Suggested trace: follow `Team.run()` → `Role._act()` → `Action.run()` to understand the full execution chain from requirement to output.
+
**Next:** [Chapter 2: Agent Roles](02-agent-roles.md) -- dive deep into each built-in role and learn how to customize agent behavior.
---
diff --git a/tutorials/metagpt-tutorial/02-agent-roles.md b/tutorials/metagpt-tutorial/02-agent-roles.md
index ed771545..134970a5 100644
--- a/tutorials/metagpt-tutorial/02-agent-roles.md
+++ b/tutorials/metagpt-tutorial/02-agent-roles.md
@@ -370,6 +370,16 @@ class CodeReviewer(Role):
Every MetaGPT agent is a `Role` with a defined profile, goal, constraints, and set of actions. The built-in roles -- ProductManager, Architect, Engineer, and QA -- form a complete software development pipeline. You can extend this by creating custom roles with their own actions and watch patterns.
+## Source Code Walkthrough
+
+Key source files in [`geekan/MetaGPT`](https://github.com/geekan/MetaGPT):
+
+- [`metagpt/roles/role.py`](https://github.com/geekan/MetaGPT/blob/main/metagpt/roles/role.py) -- base `Role` class: `_watch`, `_act`, `_observe` methods; how roles subscribe to messages
+- [`metagpt/roles/product_manager.py`](https://github.com/geekan/MetaGPT/blob/main/metagpt/roles/product_manager.py) -- ProductManager role definition and its `PrepareDocuments` + `WritePRD` action set
+- [`metagpt/roles/engineer.py`](https://github.com/geekan/MetaGPT/blob/main/metagpt/roles/engineer.py) -- Engineer role with `WriteCode` and `WriteCodeReview` action assignment
+
+Suggested trace: `Role._observe()` reads from the message bus; `Role._think()` selects the next action; `Role._act()` executes it.
+
**Next:** [Chapter 3: SOPs and Workflows](03-sop-and-workflows.md) -- learn how Standardized Operating Procedures govern role collaboration.
---
diff --git a/tutorials/metagpt-tutorial/03-sop-and-workflows.md b/tutorials/metagpt-tutorial/03-sop-and-workflows.md
index d35bafde..d7ef2378 100644
--- a/tutorials/metagpt-tutorial/03-sop-and-workflows.md
+++ b/tutorials/metagpt-tutorial/03-sop-and-workflows.md
@@ -395,6 +395,14 @@ asyncio.run(custom_pipeline())
SOPs are the backbone of MetaGPT's reliability. They transform unstructured multi-agent chat into a predictable, auditable pipeline. The key patterns -- sequential, fan-out, and feedback loop -- can be combined to model any team workflow. The message bus and watch mechanism enforce these patterns without requiring explicit orchestration code.
+## Source Code Walkthrough
+
+Key source files in [`geekan/MetaGPT`](https://github.com/geekan/MetaGPT):
+
+- [`metagpt/environment/base_env.py`](https://github.com/geekan/MetaGPT/blob/main/metagpt/environment/base_env.py) -- `Environment` class: message bus (`publish_message`, `get_messages`) used by all roles
+- [`metagpt/roles/role.py`](https://github.com/geekan/MetaGPT/blob/main/metagpt/roles/role.py) -- `_watch` and `_observe` methods define the SOP's implicit sequencing rules
+- [`metagpt/actions/write_prd.py`](https://github.com/geekan/MetaGPT/blob/main/metagpt/actions/write_prd.py) -- example action that reads context from the environment and produces a structured artifact
+
**Next:** [Chapter 4: Action System](04-action-system.md) -- learn how to build the individual actions that roles execute.
---
diff --git a/tutorials/metagpt-tutorial/04-action-system.md b/tutorials/metagpt-tutorial/04-action-system.md
index d7aae92c..671c3412 100644
--- a/tutorials/metagpt-tutorial/04-action-system.md
+++ b/tutorials/metagpt-tutorial/04-action-system.md
@@ -378,6 +378,14 @@ class DataPipelineBuilder(Role):
Actions are the building blocks of everything agents do in MetaGPT. Simple actions use `_aask()` for free-form LLM calls. Action Nodes enforce structured output through schemas, automatic parsing, and retry logic. You can compose nodes into trees, chain actions into multi-step workflows, and add validation logic for reliability.
+## Source Code Walkthrough
+
+Key source files in [`geekan/MetaGPT`](https://github.com/geekan/MetaGPT):
+
+- [`metagpt/actions/action.py`](https://github.com/geekan/MetaGPT/blob/main/metagpt/actions/action.py) -- base `Action` class; `_aask()` wraps LLM calls with prompt template and context
+- [`metagpt/actions/action_node.py`](https://github.com/geekan/MetaGPT/blob/main/metagpt/actions/action_node.py) -- `ActionNode`: schema-driven LLM output with JSON parsing, validation, and retry
+- [`metagpt/actions/write_code.py`](https://github.com/geekan/MetaGPT/blob/main/metagpt/actions/write_code.py) -- concrete action example showing how Engineer's code-writing action is implemented
+
**Next:** [Chapter 5: Memory and Context](05-memory-and-context.md) -- learn how agents remember and share information.
---
diff --git a/tutorials/metagpt-tutorial/05-memory-and-context.md b/tutorials/metagpt-tutorial/05-memory-and-context.md
index 285f804d..9859a83c 100644
--- a/tutorials/metagpt-tutorial/05-memory-and-context.md
+++ b/tutorials/metagpt-tutorial/05-memory-and-context.md
@@ -392,6 +392,14 @@ def load_memory(path: str) -> Memory:
MetaGPT's memory system operates at three levels: private agent memory, working memory for the current task, and the shared message bus. Messages carry routing metadata that enables the watch/subscribe pattern. For large projects, context window management through summarization and selective retrieval keeps prompts focused and efficient. Vector-based memory enables semantic search when keyword matching is insufficient.
+## Source Code Walkthrough
+
+Key source files in [`geekan/MetaGPT`](https://github.com/geekan/MetaGPT):
+
+- [`metagpt/memory/memory.py`](https://github.com/geekan/MetaGPT/blob/main/metagpt/memory/memory.py) -- `Memory` class: stores messages; `get_by_actions()` for selective retrieval
+- [`metagpt/schema.py`](https://github.com/geekan/MetaGPT/blob/main/metagpt/schema.py) -- `Message` dataclass with `role`, `content`, `cause_by`, and `sent_to` routing fields
+- [`metagpt/environment/base_env.py`](https://github.com/geekan/MetaGPT/blob/main/metagpt/environment/base_env.py) -- shared `history` list acts as the global message bus accessible to all roles
+
**Next:** [Chapter 6: Tool Integration](06-tool-integration.md) -- give your agents access to the outside world.
---
diff --git a/tutorials/metagpt-tutorial/06-tool-integration.md b/tutorials/metagpt-tutorial/06-tool-integration.md
index 36a6ba78..f051b528 100644
--- a/tutorials/metagpt-tutorial/06-tool-integration.md
+++ b/tutorials/metagpt-tutorial/06-tool-integration.md
@@ -411,6 +411,14 @@ Tool integration details:
MetaGPT tools bridge the gap between LLM reasoning and real-world action. Built-in tools cover web browsing, search, code execution, and file management. Custom tools follow a simple pattern: create a tool class with the integration logic, then use it inside an Action. The framework handles error isolation, output truncation, and async execution.
+## Source Code Walkthrough
+
+Key source files in [`geekan/MetaGPT`](https://github.com/geekan/MetaGPT):
+
+- [`metagpt/tools/web_browser_engine.py`](https://github.com/geekan/MetaGPT/blob/main/metagpt/tools/web_browser_engine.py) -- browser tool wrapping Playwright/Selenium; `run()` method fetches and parses web content
+- [`metagpt/tools/search_engine.py`](https://github.com/geekan/MetaGPT/blob/main/metagpt/tools/search_engine.py) -- search abstraction supporting Google, DuckDuckGo, and SerpAPI backends
+- [`metagpt/actions/research.py`](https://github.com/geekan/MetaGPT/blob/main/metagpt/actions/research.py) -- example action combining search + browsing into a research pipeline
+
**Next:** [Chapter 7: Multi-Agent Orchestration](07-multi-agent-orchestration.md) -- compose agents into sophisticated teams.
---
diff --git a/tutorials/metagpt-tutorial/07-multi-agent-orchestration.md b/tutorials/metagpt-tutorial/07-multi-agent-orchestration.md
index c0f5b7aa..40c00320 100644
--- a/tutorials/metagpt-tutorial/07-multi-agent-orchestration.md
+++ b/tutorials/metagpt-tutorial/07-multi-agent-orchestration.md
@@ -472,6 +472,14 @@ async def inspect_team():
Multi-agent orchestration in MetaGPT is managed through the Team and Environment abstractions. Teams are composed by hiring roles, and the environment manages round-based execution, message routing, and convergence detection. Advanced patterns include parallel execution with aggregation, dynamic team formation, and hierarchical task decomposition. Budget and round controls ensure predictable resource usage.
+## Source Code Walkthrough
+
+Key source files in [`geekan/MetaGPT`](https://github.com/geekan/MetaGPT):
+
+- [`metagpt/team.py`](https://github.com/geekan/MetaGPT/blob/main/metagpt/team.py) -- `Team.hire()` registers roles; `Team.run(n_round)` drives the execution loop with budget/round guards
+- [`metagpt/environment/base_env.py`](https://github.com/geekan/MetaGPT/blob/main/metagpt/environment/base_env.py) -- `run_one_round()` iterates all roles; tracks `is_idle` state for convergence
+- [`metagpt/roles/role.py`](https://github.com/geekan/MetaGPT/blob/main/metagpt/roles/role.py) -- `is_idle` property: `True` when no pending messages match the role's watch set
+
**Next:** [Chapter 8: Production Deployment](08-production-deployment.md) -- deploy MetaGPT systems at scale.
---
diff --git a/tutorials/metagpt-tutorial/08-production-deployment.md b/tutorials/metagpt-tutorial/08-production-deployment.md
index 6fdd296e..59abd08c 100644
--- a/tutorials/metagpt-tutorial/08-production-deployment.md
+++ b/tutorials/metagpt-tutorial/08-production-deployment.md
@@ -593,6 +593,14 @@ Production deployment principles:
Running MetaGPT in production requires attention to cost management, error recovery, observability, and security. The key patterns are: multi-model configuration for cost optimization, checkpoint-based resumption for reliability, structured logging for observability, and API wrapping for system integration. With these patterns in place, MetaGPT can serve as a reliable component in enterprise software delivery pipelines.
+## Source Code Walkthrough
+
+Key source files in [`geekan/MetaGPT`](https://github.com/geekan/MetaGPT):
+
+- [`metagpt/config2.py`](https://github.com/geekan/MetaGPT/blob/main/metagpt/config2.py) -- `Config.max_budget` field and `CostManager` integration for spend tracking
+- [`metagpt/utils/cost_manager.py`](https://github.com/geekan/MetaGPT/blob/main/metagpt/utils/cost_manager.py) -- tracks token consumption per run; raises `BudgetExceededException` when limit hit
+- [`metagpt/actions/action.py`](https://github.com/geekan/MetaGPT/blob/main/metagpt/actions/action.py) -- retry logic via `tenacity`; wraps `_aask()` calls with exponential backoff
+
---
[Previous: Chapter 7: Multi-Agent Orchestration](07-multi-agent-orchestration.md) | [Back to Tutorial Index](README.md)
diff --git a/tutorials/mini-swe-agent-tutorial/01-getting-started.md b/tutorials/mini-swe-agent-tutorial/01-getting-started.md
index 089434eb..d3aed9bd 100644
--- a/tutorials/mini-swe-agent-tutorial/01-getting-started.md
+++ b/tutorials/mini-swe-agent-tutorial/01-getting-started.md
@@ -38,92 +38,8 @@ You now have a working mini-swe-agent baseline.
Next: [Chapter 2: Core Architecture and Minimal Design](02-core-architecture-and-minimal-design.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/minisweagent/agents/interactive.py`
-
-The `InteractiveAgentConfig` class in [`src/minisweagent/agents/interactive.py`](https://github.com/SWE-agent/mini-swe-agent/blob/HEAD/src/minisweagent/agents/interactive.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-class InteractiveAgentConfig(AgentConfig):
- mode: Literal["human", "confirm", "yolo"] = "confirm"
- """Whether to confirm actions."""
- whitelist_actions: list[str] = []
- """Never confirm actions that match these regular expressions."""
- confirm_exit: bool = True
- """If the agent wants to finish, do we ask for confirmation from user?"""
-
-
-class InteractiveAgent(DefaultAgent):
- _MODE_COMMANDS_MAPPING = {"/u": "human", "/c": "confirm", "/y": "yolo"}
-
- def __init__(self, *args, config_class=InteractiveAgentConfig, **kwargs):
- super().__init__(*args, config_class=config_class, **kwargs)
- self.cost_last_confirmed = 0.0
-
- def _interrupt(self, content: str, *, itype: str = "UserInterruption") -> NoReturn:
- raise UserInterruption({"role": "user", "content": content, "extra": {"interrupt_type": itype}})
-
- def add_messages(self, *messages: dict) -> list[dict]:
- # Extend supermethod to print messages
- for msg in messages:
- role, content = msg.get("role") or msg.get("type", "unknown"), get_content_string(msg)
- if role == "assistant":
- console.print(
- f"\n[red][bold]mini-swe-agent[/bold] (step [bold]{self.n_calls}[/bold], [bold]${self.cost:.2f}[/bold]):[/red]\n",
- end="",
- highlight=False,
- )
- else:
-```
-
-This class is important because it defines how Mini-SWE-Agent Tutorial: Minimal Autonomous Code Agent Design at Benchmark Scale implements the patterns covered in this chapter.
-
-### `src/minisweagent/agents/interactive.py`
-
-The `InteractiveAgent` class in [`src/minisweagent/agents/interactive.py`](https://github.com/SWE-agent/mini-swe-agent/blob/HEAD/src/minisweagent/agents/interactive.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-class InteractiveAgentConfig(AgentConfig):
- mode: Literal["human", "confirm", "yolo"] = "confirm"
- """Whether to confirm actions."""
- whitelist_actions: list[str] = []
- """Never confirm actions that match these regular expressions."""
- confirm_exit: bool = True
- """If the agent wants to finish, do we ask for confirmation from user?"""
-
-
-class InteractiveAgent(DefaultAgent):
- _MODE_COMMANDS_MAPPING = {"/u": "human", "/c": "confirm", "/y": "yolo"}
-
- def __init__(self, *args, config_class=InteractiveAgentConfig, **kwargs):
- super().__init__(*args, config_class=config_class, **kwargs)
- self.cost_last_confirmed = 0.0
-
- def _interrupt(self, content: str, *, itype: str = "UserInterruption") -> NoReturn:
- raise UserInterruption({"role": "user", "content": content, "extra": {"interrupt_type": itype}})
-
- def add_messages(self, *messages: dict) -> list[dict]:
- # Extend supermethod to print messages
- for msg in messages:
- role, content = msg.get("role") or msg.get("type", "unknown"), get_content_string(msg)
- if role == "assistant":
- console.print(
- f"\n[red][bold]mini-swe-agent[/bold] (step [bold]{self.n_calls}[/bold], [bold]${self.cost:.2f}[/bold]):[/red]\n",
- end="",
- highlight=False,
- )
- else:
-```
-
-This class is important because it defines how Mini-SWE-Agent Tutorial: Minimal Autonomous Code Agent Design at Benchmark Scale implements the patterns covered in this chapter.
-
### `src/minisweagent/__init__.py`
The `Model` class in [`src/minisweagent/__init__.py`](https://github.com/SWE-agent/mini-swe-agent/blob/HEAD/src/minisweagent/__init__.py) handles a key part of this chapter's functionality:
@@ -206,16 +122,89 @@ __all__ = [
This class is important because it defines how Mini-SWE-Agent Tutorial: Minimal Autonomous Code Agent Design at Benchmark Scale implements the patterns covered in this chapter.
+### `src/minisweagent/__init__.py`
+
+The `Agent` class in [`src/minisweagent/__init__.py`](https://github.com/SWE-agent/mini-swe-agent/blob/HEAD/src/minisweagent/__init__.py) handles a key part of this chapter's functionality:
+
+```py
+
+
+class Agent(Protocol):
+ """Protocol for agents."""
+
+ config: Any
+
+ def run(self, task: str, **kwargs) -> dict: ...
+
+ def save(self, path: Path | None, *extra_dicts) -> dict: ...
+
+
+__all__ = [
+ "Agent",
+ "Model",
+ "Environment",
+ "package_dir",
+ "__version__",
+ "global_config_file",
+ "global_config_dir",
+ "logger",
+]
+
+```
+
+This class is important because it defines how Mini-SWE-Agent Tutorial: Minimal Autonomous Code Agent Design at Benchmark Scale implements the patterns covered in this chapter.
+
+### `src/minisweagent/models/portkey_model.py`
+
+The `PortkeyModelConfig` class in [`src/minisweagent/models/portkey_model.py`](https://github.com/SWE-agent/mini-swe-agent/blob/HEAD/src/minisweagent/models/portkey_model.py) handles a key part of this chapter's functionality:
+
+```py
+
+
+class PortkeyModelConfig(BaseModel):
+ model_name: str
+ model_kwargs: dict[str, Any] = {}
+ provider: str = ""
+ """The LLM provider to use (e.g., 'openai', 'anthropic', 'google').
+ If not specified, will be auto-detected from model_name.
+ Required by Portkey when not using a virtual key.
+ """
+ litellm_model_registry: Path | str | None = os.getenv("LITELLM_MODEL_REGISTRY_PATH")
+ """We currently use litellm to calculate costs. Here you can register additional models to litellm's model registry.
+ Note that this might change if we get better support for Portkey and change how we calculate costs.
+ """
+ litellm_model_name_override: str = ""
+ """We currently use litellm to calculate costs. Here you can override the model name to use for litellm in case it
+ doesn't match the Portkey model name.
+ Note that this might change if we get better support for Portkey and change how we calculate costs.
+ """
+ set_cache_control: Literal["default_end"] | None = None
+ """Set explicit cache control markers, for example for Anthropic models"""
+ cost_tracking: Literal["default", "ignore_errors"] = os.getenv("MSWEA_COST_TRACKING", "default")
+ """Cost tracking mode for this model. Can be "default" or "ignore_errors" (ignore errors/missing cost info)"""
+ format_error_template: str = "{{ error }}"
+ """Template used when the LM's output is not in the expected format."""
+ observation_template: str = (
+ "{% if output.exception_info %}<exception>{{output.exception_info}}</exception>\n{% endif %}"
+ "<returncode>{{output.returncode}}</returncode>\n<output>\n{{output.output}}</output>"
+ )
+ """Template used to render the observation after executing an action."""
+ multimodal_regex: str = ""
+ """Regex to extract multimodal content. Empty string disables multimodal processing."""
+```
+
+This class is important because it defines how Mini-SWE-Agent Tutorial: Minimal Autonomous Code Agent Design at Benchmark Scale implements the patterns covered in this chapter.
+
## How These Components Connect
```mermaid
flowchart TD
- A[InteractiveAgentConfig]
- B[InteractiveAgent]
- C[Model]
- D[Environment]
- E[Agent]
+ A[Model]
+ B[Environment]
+ C[Agent]
+ D[PortkeyModelConfig]
+ E[PortkeyModel]
A --> B
B --> C
C --> D
diff --git a/tutorials/mini-swe-agent-tutorial/02-core-architecture-and-minimal-design.md b/tutorials/mini-swe-agent-tutorial/02-core-architecture-and-minimal-design.md
index 1096fa69..dfdaa1be 100644
--- a/tutorials/mini-swe-agent-tutorial/02-core-architecture-and-minimal-design.md
+++ b/tutorials/mini-swe-agent-tutorial/02-core-architecture-and-minimal-design.md
@@ -38,15 +38,23 @@ You now understand how mini-swe-agent keeps performance and simplicity aligned.
Next: [Chapter 3: CLI, Batch, and Inspector Workflows](03-cli-batch-and-inspector-workflows.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `src/minisweagent/exceptions.py`
-The `LimitsExceeded` class in [`src/minisweagent/exceptions.py`](https://github.com/SWE-agent/mini-swe-agent/blob/HEAD/src/minisweagent/exceptions.py) handles a key part of this chapter's functionality:
+The `InterruptAgentFlow` class in [`src/minisweagent/exceptions.py`](https://github.com/SWE-agent/mini-swe-agent/blob/HEAD/src/minisweagent/exceptions.py) handles a key part of this chapter's functionality:
```py
+class InterruptAgentFlow(Exception):
+ """Raised to interrupt the agent flow and add messages."""
+
+ def __init__(self, *messages: dict):
+ self.messages = messages
+ super().__init__()
+
+
+class Submitted(InterruptAgentFlow):
+ """Raised when the agent has completed its task."""
class LimitsExceeded(InterruptAgentFlow):
@@ -66,11 +74,19 @@ This class is important because it defines how Mini-SWE-Agent Tutorial: Minimal
### `src/minisweagent/exceptions.py`
-The `UserInterruption` class in [`src/minisweagent/exceptions.py`](https://github.com/SWE-agent/mini-swe-agent/blob/HEAD/src/minisweagent/exceptions.py) handles a key part of this chapter's functionality:
+The `Submitted` class in [`src/minisweagent/exceptions.py`](https://github.com/SWE-agent/mini-swe-agent/blob/HEAD/src/minisweagent/exceptions.py) handles a key part of this chapter's functionality:
```py
+class Submitted(InterruptAgentFlow):
+ """Raised when the agent has completed its task."""
+
+
+class LimitsExceeded(InterruptAgentFlow):
+ """Raised when the agent has exceeded its cost or step limit."""
+
+
class UserInterruption(InterruptAgentFlow):
"""Raised when the user interrupts the agent."""
@@ -84,11 +100,19 @@ This class is important because it defines how Mini-SWE-Agent Tutorial: Minimal
### `src/minisweagent/exceptions.py`
-The `FormatError` class in [`src/minisweagent/exceptions.py`](https://github.com/SWE-agent/mini-swe-agent/blob/HEAD/src/minisweagent/exceptions.py) handles a key part of this chapter's functionality:
+The `LimitsExceeded` class in [`src/minisweagent/exceptions.py`](https://github.com/SWE-agent/mini-swe-agent/blob/HEAD/src/minisweagent/exceptions.py) handles a key part of this chapter's functionality:
```py
+class LimitsExceeded(InterruptAgentFlow):
+ """Raised when the agent has exceeded its cost or step limit."""
+
+
+class UserInterruption(InterruptAgentFlow):
+ """Raised when the user interrupts the agent."""
+
+
class FormatError(InterruptAgentFlow):
"""Raised when the LM's output is not in the expected format."""
@@ -96,43 +120,20 @@ class FormatError(InterruptAgentFlow):
This class is important because it defines how Mini-SWE-Agent Tutorial: Minimal Autonomous Code Agent Design at Benchmark Scale implements the patterns covered in this chapter.
-### `src/minisweagent/models/portkey_model.py`
+### `src/minisweagent/exceptions.py`
-The `PortkeyModelConfig` class in [`src/minisweagent/models/portkey_model.py`](https://github.com/SWE-agent/mini-swe-agent/blob/HEAD/src/minisweagent/models/portkey_model.py) handles a key part of this chapter's functionality:
+The `UserInterruption` class in [`src/minisweagent/exceptions.py`](https://github.com/SWE-agent/mini-swe-agent/blob/HEAD/src/minisweagent/exceptions.py) handles a key part of this chapter's functionality:
```py
-class PortkeyModelConfig(BaseModel):
- model_name: str
- model_kwargs: dict[str, Any] = {}
- provider: str = ""
- """The LLM provider to use (e.g., 'openai', 'anthropic', 'google').
- If not specified, will be auto-detected from model_name.
- Required by Portkey when not using a virtual key.
- """
- litellm_model_registry: Path | str | None = os.getenv("LITELLM_MODEL_REGISTRY_PATH")
- """We currently use litellm to calculate costs. Here you can register additional models to litellm's model registry.
- Note that this might change if we get better support for Portkey and change how we calculate costs.
- """
- litellm_model_name_override: str = ""
- """We currently use litellm to calculate costs. Here you can override the model name to use for litellm in case it
- doesn't match the Portkey model name.
- Note that this might change if we get better support for Portkey and change how we calculate costs.
- """
- set_cache_control: Literal["default_end"] | None = None
- """Set explicit cache control markers, for example for Anthropic models"""
- cost_tracking: Literal["default", "ignore_errors"] = os.getenv("MSWEA_COST_TRACKING", "default")
- """Cost tracking mode for this model. Can be "default" or "ignore_errors" (ignore errors/missing cost info)"""
- format_error_template: str = "{{ error }}"
- """Template used when the LM's output is not in the expected format."""
- observation_template: str = (
- "{% if output.exception_info %}<exception>{{output.exception_info}}</exception>\n{% endif %}"
- "<returncode>{{output.returncode}}</returncode>\n<output>\n{{output.output}}</output>"
- )
- """Template used to render the observation after executing an action."""
- multimodal_regex: str = ""
- """Regex to extract multimodal content. Empty string disables multimodal processing."""
+class UserInterruption(InterruptAgentFlow):
+ """Raised when the user interrupts the agent."""
+
+
+class FormatError(InterruptAgentFlow):
+ """Raised when the LM's output is not in the expected format."""
+
```
This class is important because it defines how Mini-SWE-Agent Tutorial: Minimal Autonomous Code Agent Design at Benchmark Scale implements the patterns covered in this chapter.
@@ -142,11 +143,11 @@ This class is important because it defines how Mini-SWE-Agent Tutorial: Minimal
```mermaid
flowchart TD
- A[LimitsExceeded]
- B[UserInterruption]
- C[FormatError]
- D[PortkeyModelConfig]
- E[PortkeyModel]
+ A[InterruptAgentFlow]
+ B[Submitted]
+ C[LimitsExceeded]
+ D[UserInterruption]
+ E[FormatError]
A --> B
B --> C
C --> D
diff --git a/tutorials/mini-swe-agent-tutorial/03-cli-batch-and-inspector-workflows.md b/tutorials/mini-swe-agent-tutorial/03-cli-batch-and-inspector-workflows.md
index 0c64e277..615a7fcd 100644
--- a/tutorials/mini-swe-agent-tutorial/03-cli-batch-and-inspector-workflows.md
+++ b/tutorials/mini-swe-agent-tutorial/03-cli-batch-and-inspector-workflows.md
@@ -38,136 +38,93 @@ You now have a practical operating model for both interactive and benchmark runs
Next: [Chapter 4: Global and YAML Configuration Strategy](04-global-and-yaml-configuration-strategy.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/minisweagent/environments/docker.py`
+### `src/minisweagent/models/openrouter_model.py`
-The `DockerEnvironmentConfig` class in [`src/minisweagent/environments/docker.py`](https://github.com/SWE-agent/mini-swe-agent/blob/HEAD/src/minisweagent/environments/docker.py) handles a key part of this chapter's functionality:
+The `OpenRouterAuthenticationError` class in [`src/minisweagent/models/openrouter_model.py`](https://github.com/SWE-agent/mini-swe-agent/blob/HEAD/src/minisweagent/models/openrouter_model.py) handles a key part of this chapter's functionality:
```py
-class DockerEnvironmentConfig(BaseModel):
- image: str
- cwd: str = "/"
- """Working directory in which to execute commands."""
- env: dict[str, str] = {}
- """Environment variables to set in the container."""
- forward_env: list[str] = []
- """Environment variables to forward to the container.
- Variables are only forwarded if they are set in the host environment.
- In case of conflict with `env`, the `env` variables take precedence.
- """
- timeout: int = 30
- """Timeout for executing commands in the container."""
- executable: str = os.getenv("MSWEA_DOCKER_EXECUTABLE", "docker")
- """Path to the docker/container executable."""
- run_args: list[str] = ["--rm"]
- """Additional arguments to pass to the docker/container executable.
- Default is ["--rm"], which removes the container after it exits.
- """
- container_timeout: str = "2h"
- """Max duration to keep container running. Uses the same format as the sleep command."""
- pull_timeout: int = 120
- """Timeout in seconds for pulling images."""
- interpreter: list[str] = ["bash", "-lc"]
- """Interpreter to use to execute commands. Default is ["bash", "-lc"].
- The actual command will be appended as argument to this. Override this to e.g., modify shell flags
- (e.g., to remove the `-l` flag to disable login shell) or to use python instead of bash to interpret commands.
- """
-
-
-```
+class OpenRouterAuthenticationError(Exception):
+ """Custom exception for OpenRouter authentication errors."""
-This class is important because it defines how Mini-SWE-Agent Tutorial: Minimal Autonomous Code Agent Design at Benchmark Scale implements the patterns covered in this chapter.
-### `src/minisweagent/environments/docker.py`
+class OpenRouterRateLimitError(Exception):
+ """Custom exception for OpenRouter rate limit errors."""
-The `DockerEnvironment` class in [`src/minisweagent/environments/docker.py`](https://github.com/SWE-agent/mini-swe-agent/blob/HEAD/src/minisweagent/environments/docker.py) handles a key part of this chapter's functionality:
-```py
+class OpenRouterModel:
+ abort_exceptions: list[type[Exception]] = [OpenRouterAuthenticationError, KeyboardInterrupt]
+ def __init__(self, **kwargs):
+ self.config = OpenRouterModelConfig(**kwargs)
+ self._api_url = "https://openrouter.ai/api/v1/chat/completions"
+ self._api_key = os.getenv("OPENROUTER_API_KEY", "")
-class DockerEnvironmentConfig(BaseModel):
- image: str
- cwd: str = "/"
- """Working directory in which to execute commands."""
- env: dict[str, str] = {}
- """Environment variables to set in the container."""
- forward_env: list[str] = []
- """Environment variables to forward to the container.
- Variables are only forwarded if they are set in the host environment.
- In case of conflict with `env`, the `env` variables take precedence.
- """
- timeout: int = 30
- """Timeout for executing commands in the container."""
- executable: str = os.getenv("MSWEA_DOCKER_EXECUTABLE", "docker")
- """Path to the docker/container executable."""
- run_args: list[str] = ["--rm"]
- """Additional arguments to pass to the docker/container executable.
- Default is ["--rm"], which removes the container after it exits.
- """
- container_timeout: str = "2h"
- """Max duration to keep container running. Uses the same format as the sleep command."""
- pull_timeout: int = 120
- """Timeout in seconds for pulling images."""
- interpreter: list[str] = ["bash", "-lc"]
- """Interpreter to use to execute commands. Default is ["bash", "-lc"].
- The actual command will be appended as argument to this. Override this to e.g., modify shell flags
- (e.g., to remove the `-l` flag to disable login shell) or to use python instead of bash to interpret commands.
- """
+ def _query(self, messages: list[dict[str, str]], **kwargs):
+ headers = {
+ "Authorization": f"Bearer {self._api_key}",
+ "Content-Type": "application/json",
+ }
+ payload = {
+ "model": self.config.model_name,
+ "messages": messages,
+ "tools": [BASH_TOOL],
+ "usage": {"include": True},
+ **(self.config.model_kwargs | kwargs),
+ }
```
This class is important because it defines how Mini-SWE-Agent Tutorial: Minimal Autonomous Code Agent Design at Benchmark Scale implements the patterns covered in this chapter.
-### `src/minisweagent/environments/docker.py`
+### `src/minisweagent/models/openrouter_model.py`
-The `executes` class in [`src/minisweagent/environments/docker.py`](https://github.com/SWE-agent/mini-swe-agent/blob/HEAD/src/minisweagent/environments/docker.py) handles a key part of this chapter's functionality:
+The `OpenRouterRateLimitError` class in [`src/minisweagent/models/openrouter_model.py`](https://github.com/SWE-agent/mini-swe-agent/blob/HEAD/src/minisweagent/models/openrouter_model.py) handles a key part of this chapter's functionality:
```py
- **kwargs,
- ):
- """This class executes bash commands in a Docker container using direct docker commands.
- See `DockerEnvironmentConfig` for keyword arguments.
- """
- self.logger = logger or logging.getLogger("minisweagent.environment")
- self.container_id: str | None = None
- self.config = config_class(**kwargs)
- self._start_container()
- def get_template_vars(self, **kwargs) -> dict[str, Any]:
- return recursive_merge(self.config.model_dump(), platform.uname()._asdict(), kwargs)
- def serialize(self) -> dict:
- return {
- "info": {
- "config": {
- "environment": self.config.model_dump(mode="json"),
- "environment_type": f"{self.__class__.__module__}.{self.__class__.__name__}",
- }
- }
+class OpenRouterRateLimitError(Exception):
+ """Custom exception for OpenRouter rate limit errors."""
+
+
+class OpenRouterModel:
+ abort_exceptions: list[type[Exception]] = [OpenRouterAuthenticationError, KeyboardInterrupt]
+
+ def __init__(self, **kwargs):
+ self.config = OpenRouterModelConfig(**kwargs)
+ self._api_url = "https://openrouter.ai/api/v1/chat/completions"
+ self._api_key = os.getenv("OPENROUTER_API_KEY", "")
+
+ def _query(self, messages: list[dict[str, str]], **kwargs):
+ headers = {
+ "Authorization": f"Bearer {self._api_key}",
+ "Content-Type": "application/json",
+ }
+
+ payload = {
+ "model": self.config.model_name,
+ "messages": messages,
+ "tools": [BASH_TOOL],
+ "usage": {"include": True},
+ **(self.config.model_kwargs | kwargs),
}
- def _start_container(self):
- """Start the Docker container and return the container ID."""
- container_name = f"minisweagent-{uuid.uuid4().hex[:8]}"
- cmd = [
- self.config.executable,
- "run",
- "-d",
- "--name",
- container_name,
+ try:
+ response = requests.post(self._api_url, headers=headers, data=json.dumps(payload), timeout=60)
+ response.raise_for_status()
+ return response.json()
```
This class is important because it defines how Mini-SWE-Agent Tutorial: Minimal Autonomous Code Agent Design at Benchmark Scale implements the patterns covered in this chapter.
### `src/minisweagent/models/openrouter_model.py`
-The `OpenRouterModelConfig` class in [`src/minisweagent/models/openrouter_model.py`](https://github.com/SWE-agent/mini-swe-agent/blob/HEAD/src/minisweagent/models/openrouter_model.py) handles a key part of this chapter's functionality:
+The `OpenRouterModel` class in [`src/minisweagent/models/openrouter_model.py`](https://github.com/SWE-agent/mini-swe-agent/blob/HEAD/src/minisweagent/models/openrouter_model.py) handles a key part of this chapter's functionality:
```py
@@ -206,16 +163,57 @@ class OpenRouterRateLimitError(Exception):
This class is important because it defines how Mini-SWE-Agent Tutorial: Minimal Autonomous Code Agent Design at Benchmark Scale implements the patterns covered in this chapter.
+### `src/minisweagent/models/openrouter_model.py`
+
+The `_DictToObj` class in [`src/minisweagent/models/openrouter_model.py`](https://github.com/SWE-agent/mini-swe-agent/blob/HEAD/src/minisweagent/models/openrouter_model.py) handles a key part of this chapter's functionality:
+
+```py
+ """Parse tool calls from the response. Raises FormatError if unknown tool."""
+ tool_calls = response["choices"][0]["message"].get("tool_calls") or []
+ tool_calls = [_DictToObj(tc) for tc in tool_calls]
+ return parse_toolcall_actions(tool_calls, format_error_template=self.config.format_error_template)
+
+ def format_message(self, **kwargs) -> dict:
+ return expand_multimodal_content(kwargs, pattern=self.config.multimodal_regex)
+
+ def format_observation_messages(
+ self, message: dict, outputs: list[dict], template_vars: dict | None = None
+ ) -> list[dict]:
+ """Format execution outputs into tool result messages."""
+ actions = message.get("extra", {}).get("actions", [])
+ return format_toolcall_observation_messages(
+ actions=actions,
+ outputs=outputs,
+ observation_template=self.config.observation_template,
+ template_vars=template_vars,
+ multimodal_regex=self.config.multimodal_regex,
+ )
+
+ def get_template_vars(self, **kwargs) -> dict[str, Any]:
+ return self.config.model_dump()
+
+ def serialize(self) -> dict:
+ return {
+ "info": {
+ "config": {
+ "model": self.config.model_dump(mode="json"),
+ "model_type": f"{self.__class__.__module__}.{self.__class__.__name__}",
+ },
+ }
+```
+
+This class is important because it defines how Mini-SWE-Agent Tutorial: Minimal Autonomous Code Agent Design at Benchmark Scale implements the patterns covered in this chapter.
+
## How These Components Connect
```mermaid
flowchart TD
- A[DockerEnvironmentConfig]
- B[DockerEnvironment]
- C[executes]
- D[OpenRouterModelConfig]
- E[OpenRouterAPIError]
+ A[OpenRouterAuthenticationError]
+ B[OpenRouterRateLimitError]
+ C[OpenRouterModel]
+ D[_DictToObj]
+ E[LitellmModelConfig]
A --> B
B --> C
C --> D
diff --git a/tutorials/mini-swe-agent-tutorial/04-global-and-yaml-configuration-strategy.md b/tutorials/mini-swe-agent-tutorial/04-global-and-yaml-configuration-strategy.md
index b9d48d98..eca4317c 100644
--- a/tutorials/mini-swe-agent-tutorial/04-global-and-yaml-configuration-strategy.md
+++ b/tutorials/mini-swe-agent-tutorial/04-global-and-yaml-configuration-strategy.md
@@ -38,170 +38,166 @@ You now have a disciplined configuration strategy for mini-swe-agent.
Next: [Chapter 5: Environments, Sandboxing, and Deployment](05-environments-sandboxing-and-deployment.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/minisweagent/models/openrouter_model.py`
+### `src/minisweagent/agents/default.py`
-The `OpenRouterModel` class in [`src/minisweagent/models/openrouter_model.py`](https://github.com/SWE-agent/mini-swe-agent/blob/HEAD/src/minisweagent/models/openrouter_model.py) handles a key part of this chapter's functionality:
+The `DefaultAgent` class in [`src/minisweagent/agents/default.py`](https://github.com/SWE-agent/mini-swe-agent/blob/HEAD/src/minisweagent/agents/default.py) handles a key part of this chapter's functionality:
```py
-class OpenRouterModelConfig(BaseModel):
- model_name: str
- model_kwargs: dict[str, Any] = {}
- set_cache_control: Literal["default_end"] | None = None
- """Set explicit cache control markers, for example for Anthropic models"""
- cost_tracking: Literal["default", "ignore_errors"] = os.getenv("MSWEA_COST_TRACKING", "default")
- """Cost tracking mode for this model. Can be "default" or "ignore_errors" (ignore errors/missing cost info)"""
- format_error_template: str = "{{ error }}"
- """Template used when the LM's output is not in the expected format."""
- observation_template: str = (
- "{% if output.exception_info %}<exception>{{output.exception_info}}</exception>\n{% endif %}"
- "<returncode>{{output.returncode}}</returncode>\n<output>\n{{output.output}}</output>"
- )
- """Template used to render the observation after executing an action."""
- multimodal_regex: str = ""
- """Regex to extract multimodal content. Empty string disables multimodal processing."""
-
-
-class OpenRouterAPIError(Exception):
- """Custom exception for OpenRouter API errors."""
-
-
-class OpenRouterAuthenticationError(Exception):
- """Custom exception for OpenRouter authentication errors."""
-
+class DefaultAgent:
+ def __init__(self, model: Model, env: Environment, *, config_class: type = AgentConfig, **kwargs):
+ """See the `AgentConfig` class for permitted keyword arguments."""
+ self.config = config_class(**kwargs)
+ self.messages: list[dict] = []
+ self.model = model
+ self.env = env
+ self.extra_template_vars = {}
+ self.logger = logging.getLogger("agent")
+ self.cost = 0.0
+ self.n_calls = 0
+
+ def get_template_vars(self, **kwargs) -> dict:
+ return recursive_merge(
+ self.config.model_dump(),
+ self.env.get_template_vars(),
+ self.model.get_template_vars(),
+ {"n_model_calls": self.n_calls, "model_cost": self.cost},
+ self.extra_template_vars,
+ kwargs,
+ )
-class OpenRouterRateLimitError(Exception):
- """Custom exception for OpenRouter rate limit errors."""
+ def _render_template(self, template: str) -> str:
+ return Template(template, undefined=StrictUndefined).render(**self.get_template_vars())
+ def add_messages(self, *messages: dict) -> list[dict]:
+ self.logger.debug(messages) # set log level to debug to see
+ self.messages.extend(messages)
+ return list(messages)
```
This class is important because it defines how Mini-SWE-Agent Tutorial: Minimal Autonomous Code Agent Design at Benchmark Scale implements the patterns covered in this chapter.
-### `src/minisweagent/models/openrouter_model.py`
+### `src/minisweagent/agents/default.py`
-The `_DictToObj` class in [`src/minisweagent/models/openrouter_model.py`](https://github.com/SWE-agent/mini-swe-agent/blob/HEAD/src/minisweagent/models/openrouter_model.py) handles a key part of this chapter's functionality:
+The `for` class in [`src/minisweagent/agents/default.py`](https://github.com/SWE-agent/mini-swe-agent/blob/HEAD/src/minisweagent/agents/default.py) handles a key part of this chapter's functionality:
```py
- """Parse tool calls from the response. Raises FormatError if unknown tool."""
- tool_calls = response["choices"][0]["message"].get("tool_calls") or []
- tool_calls = [_DictToObj(tc) for tc in tool_calls]
- return parse_toolcall_actions(tool_calls, format_error_template=self.config.format_error_template)
-
- def format_message(self, **kwargs) -> dict:
- return expand_multimodal_content(kwargs, pattern=self.config.multimodal_regex)
-
- def format_observation_messages(
- self, message: dict, outputs: list[dict], template_vars: dict | None = None
- ) -> list[dict]:
- """Format execution outputs into tool result messages."""
- actions = message.get("extra", {}).get("actions", [])
- return format_toolcall_observation_messages(
- actions=actions,
- outputs=outputs,
- observation_template=self.config.observation_template,
- template_vars=template_vars,
- multimodal_regex=self.config.multimodal_regex,
- )
-
- def get_template_vars(self, **kwargs) -> dict[str, Any]:
- return self.config.model_dump()
-
- def serialize(self) -> dict:
- return {
- "info": {
- "config": {
- "model": self.config.model_dump(mode="json"),
- "model_type": f"{self.__class__.__module__}.{self.__class__.__name__}",
- },
- }
+"""Basic agent class. See https://mini-swe-agent.com/latest/advanced/control_flow/ for visual explanation
+or https://minimal-agent.com for a tutorial on the basic building principles.
+"""
+
+import json
+import logging
+import traceback
+from pathlib import Path
+
+from jinja2 import StrictUndefined, Template
+from pydantic import BaseModel
+
+from minisweagent import Environment, Model, __version__
+from minisweagent.exceptions import InterruptAgentFlow, LimitsExceeded
+from minisweagent.utils.serialize import recursive_merge
+
+
+class AgentConfig(BaseModel):
+ """Check the config files in minisweagent/config for example settings."""
+
+ system_template: str
+ """Template for the system message (the first message)."""
+ instance_template: str
+ """Template for the first user message specifying the task (the second message overall)."""
+ step_limit: int = 0
+ """Maximum number of steps the agent can take."""
+ cost_limit: float = 3.0
+ """Stop agent after exceeding (!) this cost."""
+ output_path: Path | None = None
+ """Save the trajectory to this path."""
```
This class is important because it defines how Mini-SWE-Agent Tutorial: Minimal Autonomous Code Agent Design at Benchmark Scale implements the patterns covered in this chapter.
-### `src/minisweagent/models/portkey_response_model.py`
+### `src/minisweagent/environments/docker.py`
-The `PortkeyResponseAPIModelConfig` class in [`src/minisweagent/models/portkey_response_model.py`](https://github.com/SWE-agent/mini-swe-agent/blob/HEAD/src/minisweagent/models/portkey_response_model.py) handles a key part of this chapter's functionality:
+The `DockerEnvironmentConfig` class in [`src/minisweagent/environments/docker.py`](https://github.com/SWE-agent/mini-swe-agent/blob/HEAD/src/minisweagent/environments/docker.py) handles a key part of this chapter's functionality:
```py
-class PortkeyResponseAPIModelConfig(BaseModel):
- model_name: str
- model_kwargs: dict[str, Any] = {}
- litellm_model_registry: Path | str | None = os.getenv("LITELLM_MODEL_REGISTRY_PATH")
- litellm_model_name_override: str = ""
- cost_tracking: Literal["default", "ignore_errors"] = os.getenv("MSWEA_COST_TRACKING", "default")
- format_error_template: str = "{{ error }}"
- observation_template: str = (
- "{% if output.exception_info %}<exception>{{output.exception_info}}</exception>\n{% endif %}"
- "<returncode>{{output.returncode}}</returncode>\n<output>\n{{output.output}}</output>"
- )
- multimodal_regex: str = ""
-
-
-class PortkeyResponseAPIModel:
- """Portkey model using the Responses API with native tool calling.
-
- Note: This implementation is stateless - each request must include
- the full conversation history. previous_response_id is not used.
+class DockerEnvironmentConfig(BaseModel):
+ image: str
+ cwd: str = "/"
+ """Working directory in which to execute commands."""
+ env: dict[str, str] = {}
+ """Environment variables to set in the container."""
+ forward_env: list[str] = []
+ """Environment variables to forward to the container.
+ Variables are only forwarded if they are set in the host environment.
+ In case of conflict with `env`, the `env` variables take precedence.
+ """
+ timeout: int = 30
+ """Timeout for executing commands in the container."""
+ executable: str = os.getenv("MSWEA_DOCKER_EXECUTABLE", "docker")
+ """Path to the docker/container executable."""
+ run_args: list[str] = ["--rm"]
+ """Additional arguments to pass to the docker/container executable.
+ Default is ["--rm"], which removes the container after it exits.
+ """
+ container_timeout: str = "2h"
+ """Max duration to keep container running. Uses the same format as the sleep command."""
+ pull_timeout: int = 120
+ """Timeout in seconds for pulling images."""
+ interpreter: list[str] = ["bash", "-lc"]
+ """Interpreter to use to execute commands. Default is ["bash", "-lc"].
+ The actual command will be appended as argument to this. Override this to e.g., modify shell flags
+ (e.g., to remove the `-l` flag to disable login shell) or to use python instead of bash to interpret commands.
"""
- abort_exceptions: list[type[Exception]] = [KeyboardInterrupt, TypeError, ValueError]
-
- def __init__(self, **kwargs):
- self.config = PortkeyResponseAPIModelConfig(**kwargs)
- if self.config.litellm_model_registry and Path(self.config.litellm_model_registry).is_file():
- litellm.utils.register_model(json.loads(Path(self.config.litellm_model_registry).read_text()))
- self._api_key = os.getenv("PORTKEY_API_KEY")
- if not self._api_key:
```
This class is important because it defines how Mini-SWE-Agent Tutorial: Minimal Autonomous Code Agent Design at Benchmark Scale implements the patterns covered in this chapter.
-### `src/minisweagent/models/portkey_response_model.py`
+### `src/minisweagent/environments/docker.py`
-The `PortkeyResponseAPIModel` class in [`src/minisweagent/models/portkey_response_model.py`](https://github.com/SWE-agent/mini-swe-agent/blob/HEAD/src/minisweagent/models/portkey_response_model.py) handles a key part of this chapter's functionality:
+The `DockerEnvironment` class in [`src/minisweagent/environments/docker.py`](https://github.com/SWE-agent/mini-swe-agent/blob/HEAD/src/minisweagent/environments/docker.py) handles a key part of this chapter's functionality:
```py
-except ImportError:
- raise ImportError(
- "The portkey-ai package is required to use PortkeyResponseAPIModel. Please install it with: pip install portkey-ai"
- )
-
-
-class PortkeyResponseAPIModelConfig(BaseModel):
- model_name: str
- model_kwargs: dict[str, Any] = {}
- litellm_model_registry: Path | str | None = os.getenv("LITELLM_MODEL_REGISTRY_PATH")
- litellm_model_name_override: str = ""
- cost_tracking: Literal["default", "ignore_errors"] = os.getenv("MSWEA_COST_TRACKING", "default")
- format_error_template: str = "{{ error }}"
- observation_template: str = (
- "{% if output.exception_info %}<exception>{{output.exception_info}}</exception>\n{% endif %}"
- "<returncode>{{output.returncode}}</returncode>\n<output>\n{{output.output}}</output>"
- )
- multimodal_regex: str = ""
-
-
-class PortkeyResponseAPIModel:
- """Portkey model using the Responses API with native tool calling.
-
- Note: This implementation is stateless - each request must include
- the full conversation history. previous_response_id is not used.
+
+
+class DockerEnvironmentConfig(BaseModel):
+ image: str
+ cwd: str = "/"
+ """Working directory in which to execute commands."""
+ env: dict[str, str] = {}
+ """Environment variables to set in the container."""
+ forward_env: list[str] = []
+ """Environment variables to forward to the container.
+ Variables are only forwarded if they are set in the host environment.
+ In case of conflict with `env`, the `env` variables take precedence.
+ """
+ timeout: int = 30
+ """Timeout for executing commands in the container."""
+ executable: str = os.getenv("MSWEA_DOCKER_EXECUTABLE", "docker")
+ """Path to the docker/container executable."""
+ run_args: list[str] = ["--rm"]
+ """Additional arguments to pass to the docker/container executable.
+ Default is ["--rm"], which removes the container after it exits.
+ """
+ container_timeout: str = "2h"
+ """Max duration to keep container running. Uses the same format as the sleep command."""
+ pull_timeout: int = 120
+ """Timeout in seconds for pulling images."""
+ interpreter: list[str] = ["bash", "-lc"]
+ """Interpreter to use to execute commands. Default is ["bash", "-lc"].
+ The actual command will be appended as argument to this. Override this to e.g., modify shell flags
+ (e.g., to remove the `-l` flag to disable login shell) or to use python instead of bash to interpret commands.
"""
- abort_exceptions: list[type[Exception]] = [KeyboardInterrupt, TypeError, ValueError]
- def __init__(self, **kwargs):
- self.config = PortkeyResponseAPIModelConfig(**kwargs)
- if self.config.litellm_model_registry and Path(self.config.litellm_model_registry).is_file():
```
This class is important because it defines how Mini-SWE-Agent Tutorial: Minimal Autonomous Code Agent Design at Benchmark Scale implements the patterns covered in this chapter.
@@ -211,11 +207,11 @@ This class is important because it defines how Mini-SWE-Agent Tutorial: Minimal
```mermaid
flowchart TD
- A[OpenRouterModel]
- B[_DictToObj]
- C[PortkeyResponseAPIModelConfig]
- D[PortkeyResponseAPIModel]
- E[RequestyModelConfig]
+ A[DefaultAgent]
+ B[for]
+ C[DockerEnvironmentConfig]
+ D[DockerEnvironment]
+ E[executes]
A --> B
B --> C
C --> D
diff --git a/tutorials/mini-swe-agent-tutorial/05-environments-sandboxing-and-deployment.md b/tutorials/mini-swe-agent-tutorial/05-environments-sandboxing-and-deployment.md
index 1b0f4562..130ec318 100644
--- a/tutorials/mini-swe-agent-tutorial/05-environments-sandboxing-and-deployment.md
+++ b/tutorials/mini-swe-agent-tutorial/05-environments-sandboxing-and-deployment.md
@@ -38,170 +38,168 @@ You now have a safer deployment baseline for mini-swe-agent tasks.
Next: [Chapter 6: Benchmarking and SWE-bench Practices](06-benchmarking-and-swe-bench-practices.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/minisweagent/models/requesty_model.py`
+### `src/minisweagent/models/openrouter_response_model.py`
-The `RequestyRateLimitError` class in [`src/minisweagent/models/requesty_model.py`](https://github.com/SWE-agent/mini-swe-agent/blob/HEAD/src/minisweagent/models/requesty_model.py) handles a key part of this chapter's functionality:
+The `OpenRouterResponseModelConfig` class in [`src/minisweagent/models/openrouter_response_model.py`](https://github.com/SWE-agent/mini-swe-agent/blob/HEAD/src/minisweagent/models/openrouter_response_model.py) handles a key part of this chapter's functionality:
```py
-class RequestyRateLimitError(Exception):
- """Custom exception for Requesty rate limit errors."""
-
+class OpenRouterResponseModelConfig(OpenRouterModelConfig):
pass
-class RequestyModel:
- abort_exceptions: list[type[Exception]] = [RequestyAuthenticationError, KeyboardInterrupt]
+class OpenRouterResponseModel(OpenRouterModel):
+ """OpenRouter model using the Responses API with native tool calling.
+
+ Note: OpenRouter's Responses API is stateless - each request must include
+ the full conversation history. previous_response_id is not supported.
+ See: https://openrouter.ai/docs/api/reference/responses/overview
+ """
def __init__(self, **kwargs):
- self.config = RequestyModelConfig(**kwargs)
- self._api_url = "https://router.requesty.ai/v1/chat/completions"
- self._api_key = os.getenv("REQUESTY_API_KEY", "")
+ super().__init__(**kwargs)
+ self.config = OpenRouterResponseModelConfig(**kwargs)
+ self._api_url = "https://openrouter.ai/api/v1/responses"
def _query(self, messages: list[dict[str, str]], **kwargs):
headers = {
"Authorization": f"Bearer {self._api_key}",
"Content-Type": "application/json",
- "HTTP-Referer": "https://github.com/SWE-agent/mini-swe-agent",
- "X-Title": "mini-swe-agent",
}
-
payload = {
"model": self.config.model_name,
- "messages": messages,
- "tools": [BASH_TOOL],
+ "input": messages,
+ "tools": [BASH_TOOL_RESPONSE_API],
**(self.config.model_kwargs | kwargs),
}
-
try:
+ response = requests.post(self._api_url, headers=headers, data=json.dumps(payload), timeout=60)
```
This class is important because it defines how Mini-SWE-Agent Tutorial: Minimal Autonomous Code Agent Design at Benchmark Scale implements the patterns covered in this chapter.
-### `src/minisweagent/models/requesty_model.py`
+### `src/minisweagent/models/openrouter_response_model.py`
-The `RequestyModel` class in [`src/minisweagent/models/requesty_model.py`](https://github.com/SWE-agent/mini-swe-agent/blob/HEAD/src/minisweagent/models/requesty_model.py) handles a key part of this chapter's functionality:
+The `OpenRouterResponseModel` class in [`src/minisweagent/models/openrouter_response_model.py`](https://github.com/SWE-agent/mini-swe-agent/blob/HEAD/src/minisweagent/models/openrouter_response_model.py) handles a key part of this chapter's functionality:
```py
-class RequestyModelConfig(BaseModel):
- model_name: str
- model_kwargs: dict[str, Any] = {}
- set_cache_control: Literal["default_end"] | None = None
- """Set explicit cache control markers, for example for Anthropic models"""
- format_error_template: str = "{{ error }}"
- """Template used when the LM's output is not in the expected format."""
- observation_template: str = (
- "{% if output.exception_info %}<exception>{{output.exception_info}}</exception>\n{% endif %}"
- "<returncode>{{output.returncode}}</returncode>\n<output>\n{{output.output}}</output>"
- )
- """Template used to render the observation after executing an action."""
- multimodal_regex: str = ""
- """Regex to extract multimodal content. Empty string disables multimodal processing."""
-
-
-class RequestyAPIError(Exception):
- """Custom exception for Requesty API errors."""
-
+class OpenRouterResponseModelConfig(OpenRouterModelConfig):
pass
-class RequestyAuthenticationError(Exception):
- """Custom exception for Requesty authentication errors."""
+class OpenRouterResponseModel(OpenRouterModel):
+ """OpenRouter model using the Responses API with native tool calling.
- pass
+ Note: OpenRouter's Responses API is stateless - each request must include
+ the full conversation history. previous_response_id is not supported.
+ See: https://openrouter.ai/docs/api/reference/responses/overview
+ """
+ def __init__(self, **kwargs):
+ super().__init__(**kwargs)
+ self.config = OpenRouterResponseModelConfig(**kwargs)
+ self._api_url = "https://openrouter.ai/api/v1/responses"
-class RequestyRateLimitError(Exception):
- """Custom exception for Requesty rate limit errors."""
+ def _query(self, messages: list[dict[str, str]], **kwargs):
+ headers = {
+ "Authorization": f"Bearer {self._api_key}",
+ "Content-Type": "application/json",
+ }
+ payload = {
+ "model": self.config.model_name,
+ "input": messages,
+ "tools": [BASH_TOOL_RESPONSE_API],
+ **(self.config.model_kwargs | kwargs),
+ }
+ try:
+ response = requests.post(self._api_url, headers=headers, data=json.dumps(payload), timeout=60)
```
This class is important because it defines how Mini-SWE-Agent Tutorial: Minimal Autonomous Code Agent Design at Benchmark Scale implements the patterns covered in this chapter.
-### `src/minisweagent/models/requesty_model.py`
+### `src/minisweagent/models/litellm_response_model.py`
-The `_DictToObj` class in [`src/minisweagent/models/requesty_model.py`](https://github.com/SWE-agent/mini-swe-agent/blob/HEAD/src/minisweagent/models/requesty_model.py) handles a key part of this chapter's functionality:
+The `LitellmResponseModelConfig` class in [`src/minisweagent/models/litellm_response_model.py`](https://github.com/SWE-agent/mini-swe-agent/blob/HEAD/src/minisweagent/models/litellm_response_model.py) handles a key part of this chapter's functionality:
```py
- """Parse tool calls from the response. Raises FormatError if unknown tool."""
- tool_calls = response["choices"][0]["message"].get("tool_calls") or []
- tool_calls = [_DictToObj(tc) for tc in tool_calls]
- return parse_toolcall_actions(tool_calls, format_error_template=self.config.format_error_template)
-
- def format_message(self, **kwargs) -> dict:
- return expand_multimodal_content(kwargs, pattern=self.config.multimodal_regex)
-
- def format_observation_messages(
- self, message: dict, outputs: list[dict], template_vars: dict | None = None
- ) -> list[dict]:
- """Format execution outputs into tool result messages."""
- actions = message.get("extra", {}).get("actions", [])
- return format_toolcall_observation_messages(
- actions=actions,
- outputs=outputs,
- observation_template=self.config.observation_template,
- template_vars=template_vars,
- multimodal_regex=self.config.multimodal_regex,
- )
-
- def get_template_vars(self, **kwargs) -> dict[str, Any]:
- return self.config.model_dump()
-
- def serialize(self) -> dict:
- return {
- "info": {
- "config": {
- "model": self.config.model_dump(mode="json"),
- "model_type": f"{self.__class__.__module__}.{self.__class__.__name__}",
- },
- }
+
+
+class LitellmResponseModelConfig(LitellmModelConfig):
+ pass
+
+
+class LitellmResponseModel(LitellmModel):
+ def __init__(self, *, config_class: Callable = LitellmResponseModelConfig, **kwargs):
+ super().__init__(config_class=config_class, **kwargs)
+
+ def _prepare_messages_for_api(self, messages: list[dict]) -> list[dict]:
+ """Flatten response objects into their output items for stateless API calls."""
+ result = []
+ for msg in messages:
+ if msg.get("object") == "response":
+ for item in msg.get("output", []):
+ result.append({k: v for k, v in item.items() if k != "extra"})
+ else:
+ result.append({k: v for k, v in msg.items() if k != "extra"})
+ return result
+
+ def _query(self, messages: list[dict[str, str]], **kwargs):
+ try:
+ return litellm.responses(
+ model=self.config.model_name,
+ input=messages,
+ tools=[BASH_TOOL_RESPONSE_API],
+ **(self.config.model_kwargs | kwargs),
+ )
+ except litellm.exceptions.AuthenticationError as e:
+ e.message += " You can permanently set your API key with `mini-extra config set KEY VALUE`."
+ raise e
```
This class is important because it defines how Mini-SWE-Agent Tutorial: Minimal Autonomous Code Agent Design at Benchmark Scale implements the patterns covered in this chapter.
-### `src/minisweagent/agents/default.py`
+### `src/minisweagent/models/litellm_response_model.py`
-The `AgentConfig` class in [`src/minisweagent/agents/default.py`](https://github.com/SWE-agent/mini-swe-agent/blob/HEAD/src/minisweagent/agents/default.py) handles a key part of this chapter's functionality:
+The `LitellmResponseModel` class in [`src/minisweagent/models/litellm_response_model.py`](https://github.com/SWE-agent/mini-swe-agent/blob/HEAD/src/minisweagent/models/litellm_response_model.py) handles a key part of this chapter's functionality:
```py
-class AgentConfig(BaseModel):
- """Check the config files in minisweagent/config for example settings."""
-
- system_template: str
- """Template for the system message (the first message)."""
- instance_template: str
- """Template for the first user message specifying the task (the second message overall)."""
- step_limit: int = 0
- """Maximum number of steps the agent can take."""
- cost_limit: float = 3.0
- """Stop agent after exceeding (!) this cost."""
- output_path: Path | None = None
- """Save the trajectory to this path."""
-
-
-class DefaultAgent:
- def __init__(self, model: Model, env: Environment, *, config_class: type = AgentConfig, **kwargs):
- """See the `AgentConfig` class for permitted keyword arguments."""
- self.config = config_class(**kwargs)
- self.messages: list[dict] = []
- self.model = model
- self.env = env
- self.extra_template_vars = {}
- self.logger = logging.getLogger("agent")
- self.cost = 0.0
- self.n_calls = 0
-
- def get_template_vars(self, **kwargs) -> dict:
- return recursive_merge(
- self.config.model_dump(),
+class LitellmResponseModelConfig(LitellmModelConfig):
+ pass
+
+
+class LitellmResponseModel(LitellmModel):
+ def __init__(self, *, config_class: Callable = LitellmResponseModelConfig, **kwargs):
+ super().__init__(config_class=config_class, **kwargs)
+
+ def _prepare_messages_for_api(self, messages: list[dict]) -> list[dict]:
+ """Flatten response objects into their output items for stateless API calls."""
+ result = []
+ for msg in messages:
+ if msg.get("object") == "response":
+ for item in msg.get("output", []):
+ result.append({k: v for k, v in item.items() if k != "extra"})
+ else:
+ result.append({k: v for k, v in msg.items() if k != "extra"})
+ return result
+
+ def _query(self, messages: list[dict[str, str]], **kwargs):
+ try:
+ return litellm.responses(
+ model=self.config.model_name,
+ input=messages,
+ tools=[BASH_TOOL_RESPONSE_API],
+ **(self.config.model_kwargs | kwargs),
+ )
+ except litellm.exceptions.AuthenticationError as e:
+ e.message += " You can permanently set your API key with `mini-extra config set KEY VALUE`."
+ raise e
```
This class is important because it defines how Mini-SWE-Agent Tutorial: Minimal Autonomous Code Agent Design at Benchmark Scale implements the patterns covered in this chapter.
@@ -211,11 +209,11 @@ This class is important because it defines how Mini-SWE-Agent Tutorial: Minimal
```mermaid
flowchart TD
- A[RequestyRateLimitError]
- B[RequestyModel]
- C[_DictToObj]
- D[AgentConfig]
- E[DefaultAgent]
+ A[OpenRouterResponseModelConfig]
+ B[OpenRouterResponseModel]
+ C[LitellmResponseModelConfig]
+ D[LitellmResponseModel]
+ E[GlobalModelStats]
A --> B
B --> C
C --> D
diff --git a/tutorials/mini-swe-agent-tutorial/06-benchmarking-and-swe-bench-practices.md b/tutorials/mini-swe-agent-tutorial/06-benchmarking-and-swe-bench-practices.md
index d9c172c6..5691e867 100644
--- a/tutorials/mini-swe-agent-tutorial/06-benchmarking-and-swe-bench-practices.md
+++ b/tutorials/mini-swe-agent-tutorial/06-benchmarking-and-swe-bench-practices.md
@@ -39,170 +39,168 @@ You now have a benchmark workflow that is both rigorous and reproducible.
Next: [Chapter 7: Cookbook Extensions and Python Bindings](07-cookbook-extensions-and-python-bindings.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/minisweagent/environments/singularity.py`
+### `src/minisweagent/models/__init__.py`
-The `SingularityEnvironment` class in [`src/minisweagent/environments/singularity.py`](https://github.com/SWE-agent/mini-swe-agent/blob/HEAD/src/minisweagent/environments/singularity.py) handles a key part of this chapter's functionality:
+The `get_model_name` function in [`src/minisweagent/models/__init__.py`](https://github.com/SWE-agent/mini-swe-agent/blob/HEAD/src/minisweagent/models/__init__.py) handles a key part of this chapter's functionality:
```py
+def get_model(input_model_name: str | None = None, config: dict | None = None) -> Model:
+ """Get an initialized model object from any kind of user input or settings."""
+ resolved_model_name = get_model_name(input_model_name, config)
+ if config is None:
+ config = {}
+ config = copy.deepcopy(config)
+ config["model_name"] = resolved_model_name
+
+ model_class = get_model_class(resolved_model_name, config.pop("model_class", ""))
+
+ if (
+ any(s in resolved_model_name.lower() for s in ["anthropic", "sonnet", "opus", "claude"])
+ and "set_cache_control" not in config
+ ):
+ # Select cache control for Anthropic models by default
+ config["set_cache_control"] = "default_end"
+ return model_class(**config)
-class SingularityEnvironmentConfig(BaseModel):
- image: str
- cwd: str = "/"
- env: dict[str, str] = {}
- """Environment variables to set in the container."""
- forward_env: list[str] = []
- """Environment variables to forward to the container."""
- timeout: int = 30
- """Timeout for executing commands in the container."""
- executable: str = os.getenv("MSWEA_SINGULARITY_EXECUTABLE", "singularity")
- """Path to the singularity executable."""
- sandbox_build_retries: int = 3
- """Number of retries for building the sandbox if an error occurs."""
- global_args: list[str] = ["--quiet"]
- """Global arguments passed before the subcommand (e.g., --quiet, --debug)."""
- exec_args: list[str] = ["--contain", "--cleanenv", "--fakeroot"]
- """Arguments passed to `singularity exec`."""
-
-
-class SingularityEnvironment:
- def __init__(
- self, *, config_class: type = SingularityEnvironmentConfig, logger: logging.Logger | None = None, **kwargs
- ):
- """Singularity environment. See `SingularityEnvironmentConfig` for kwargs."""
- self.logger = logger or logging.getLogger("minisweagent.environment")
- self.config = config_class(**kwargs)
- self.sandbox_dir = self._build_sandbox()
- def _build_sandbox(self) -> Path:
- # Building the sandbox can fail (very rarely), so we retry it
+def get_model_name(input_model_name: str | None = None, config: dict | None = None) -> str:
+ """Get a model name from any kind of user input or settings."""
+ if config is None:
+ config = {}
+ if input_model_name:
+ return input_model_name
+ if from_config := config.get("model_name"):
+ return from_config
+ if from_env := os.getenv("MSWEA_MODEL_NAME"):
+ return from_env
+ raise ValueError("No default model set. Please run `mini-extra config setup` to set one.")
+
```
-This class is important because it defines how Mini-SWE-Agent Tutorial: Minimal Autonomous Code Agent Design at Benchmark Scale implements the patterns covered in this chapter.
+This function is important because it defines how Mini-SWE-Agent Tutorial: Minimal Autonomous Code Agent Design at Benchmark Scale implements the patterns covered in this chapter.
-### `src/minisweagent/models/openrouter_response_model.py`
+### `src/minisweagent/models/__init__.py`
-The `OpenRouterResponseModelConfig` class in [`src/minisweagent/models/openrouter_response_model.py`](https://github.com/SWE-agent/mini-swe-agent/blob/HEAD/src/minisweagent/models/openrouter_response_model.py) handles a key part of this chapter's functionality:
+The `get_model_class` function in [`src/minisweagent/models/__init__.py`](https://github.com/SWE-agent/mini-swe-agent/blob/HEAD/src/minisweagent/models/__init__.py) handles a key part of this chapter's functionality:
```py
+ config["model_name"] = resolved_model_name
+ model_class = get_model_class(resolved_model_name, config.pop("model_class", ""))
-class OpenRouterResponseModelConfig(OpenRouterModelConfig):
- pass
-
-
-class OpenRouterResponseModel(OpenRouterModel):
- """OpenRouter model using the Responses API with native tool calling.
-
- Note: OpenRouter's Responses API is stateless - each request must include
- the full conversation history. previous_response_id is not supported.
- See: https://openrouter.ai/docs/api/reference/responses/overview
- """
-
- def __init__(self, **kwargs):
- super().__init__(**kwargs)
- self.config = OpenRouterResponseModelConfig(**kwargs)
- self._api_url = "https://openrouter.ai/api/v1/responses"
-
- def _query(self, messages: list[dict[str, str]], **kwargs):
- headers = {
- "Authorization": f"Bearer {self._api_key}",
- "Content-Type": "application/json",
- }
- payload = {
- "model": self.config.model_name,
- "input": messages,
- "tools": [BASH_TOOL_RESPONSE_API],
- **(self.config.model_kwargs | kwargs),
- }
- try:
- response = requests.post(self._api_url, headers=headers, data=json.dumps(payload), timeout=60)
+ if (
+ any(s in resolved_model_name.lower() for s in ["anthropic", "sonnet", "opus", "claude"])
+ and "set_cache_control" not in config
+ ):
+ # Select cache control for Anthropic models by default
+ config["set_cache_control"] = "default_end"
+
+ return model_class(**config)
+
+
+def get_model_name(input_model_name: str | None = None, config: dict | None = None) -> str:
+ """Get a model name from any kind of user input or settings."""
+ if config is None:
+ config = {}
+ if input_model_name:
+ return input_model_name
+ if from_config := config.get("model_name"):
+ return from_config
+ if from_env := os.getenv("MSWEA_MODEL_NAME"):
+ return from_env
+ raise ValueError("No default model set. Please run `mini-extra config setup` to set one.")
+
+
+_MODEL_CLASS_MAPPING = {
+ "litellm": "minisweagent.models.litellm_model.LitellmModel",
+ "litellm_textbased": "minisweagent.models.litellm_textbased_model.LitellmTextbasedModel",
+ "litellm_response": "minisweagent.models.litellm_response_model.LitellmResponseModel",
+ "openrouter": "minisweagent.models.openrouter_model.OpenRouterModel",
```
-This class is important because it defines how Mini-SWE-Agent Tutorial: Minimal Autonomous Code Agent Design at Benchmark Scale implements the patterns covered in this chapter.
+This function is important because it defines how Mini-SWE-Agent Tutorial: Minimal Autonomous Code Agent Design at Benchmark Scale implements the patterns covered in this chapter.
-### `src/minisweagent/models/openrouter_response_model.py`
+### `src/minisweagent/run/mini.py`
-The `OpenRouterResponseModel` class in [`src/minisweagent/models/openrouter_response_model.py`](https://github.com/SWE-agent/mini-swe-agent/blob/HEAD/src/minisweagent/models/openrouter_response_model.py) handles a key part of this chapter's functionality:
+The `to` class in [`src/minisweagent/run/mini.py`](https://github.com/SWE-agent/mini-swe-agent/blob/HEAD/src/minisweagent/run/mini.py) handles a key part of this chapter's functionality:
```py
+"""
+
+_CONFIG_SPEC_HELP_TEXT = """Path to config files, filenames, or key-value pairs.
+[bold red]IMPORTANT:[/bold red] [red]If you set this option, the default config file will not be used.[/red]
+So you need to explicitly set it e.g., with [bold green]-c mini.yaml <other options>[/bold green]
-class OpenRouterResponseModelConfig(OpenRouterModelConfig):
- pass
-
-
-class OpenRouterResponseModel(OpenRouterModel):
- """OpenRouter model using the Responses API with native tool calling.
-
- Note: OpenRouter's Responses API is stateless - each request must include
- the full conversation history. previous_response_id is not supported.
- See: https://openrouter.ai/docs/api/reference/responses/overview
- """
-
- def __init__(self, **kwargs):
- super().__init__(**kwargs)
- self.config = OpenRouterResponseModelConfig(**kwargs)
- self._api_url = "https://openrouter.ai/api/v1/responses"
-
- def _query(self, messages: list[dict[str, str]], **kwargs):
- headers = {
- "Authorization": f"Bearer {self._api_key}",
- "Content-Type": "application/json",
- }
- payload = {
- "model": self.config.model_name,
- "input": messages,
- "tools": [BASH_TOOL_RESPONSE_API],
- **(self.config.model_kwargs | kwargs),
- }
- try:
- response = requests.post(self._api_url, headers=headers, data=json.dumps(payload), timeout=60)
+Multiple configs will be recursively merged.
+
+Examples:
+
+[bold red]-c model.model_kwargs.temperature=0[/bold red] [red]You forgot to add the default config file! See above.[/red]
+
+[bold green]-c mini.yaml -c model.model_kwargs.temperature=0.5[/bold green]
+
+[bold green]-c swebench.yaml agent.mode=yolo[/bold green]
+"""
+
+console = Console(highlight=False)
+app = typer.Typer(rich_markup_mode="rich")
+
+
+# fmt: off
+@app.command(help=_HELP_TEXT)
+def main(
+ model_name: str | None = typer.Option(None, "-m", "--model", help="Model to use",),
+ model_class: str | None = typer.Option(None, "--model-class", help="Model class to use (e.g., 'litellm' or 'minisweagent.models.litellm_model.LitellmModel')", rich_help_panel="Advanced"),
+ agent_class: str | None = typer.Option(None, "--agent-class", help="Agent class to use (e.g., 'interactive' or 'minisweagent.agents.interactive.InteractiveAgent')", rich_help_panel="Advanced"),
+ environment_class: str | None = typer.Option(None, "--environment-class", help="Environment class to use (e.g., 'local' or 'minisweagent.environments.local.LocalEnvironment')", rich_help_panel="Advanced"),
+ task: str | None = typer.Option(None, "-t", "--task", help="Task/problem statement", show_default=False),
+ yolo: bool = typer.Option(False, "-y", "--yolo", help="Run without confirmation"),
+ cost_limit: float | None = typer.Option(None, "-l", "--cost-limit", help="Cost limit. Set to 0 to disable."),
```
This class is important because it defines how Mini-SWE-Agent Tutorial: Minimal Autonomous Code Agent Design at Benchmark Scale implements the patterns covered in this chapter.
-### `src/minisweagent/models/__init__.py`
+### `src/minisweagent/run/mini.py`
-The `GlobalModelStats` class in [`src/minisweagent/models/__init__.py`](https://github.com/SWE-agent/mini-swe-agent/blob/HEAD/src/minisweagent/models/__init__.py) handles a key part of this chapter's functionality:
+The `to` class in [`src/minisweagent/run/mini.py`](https://github.com/SWE-agent/mini-swe-agent/blob/HEAD/src/minisweagent/run/mini.py) handles a key part of this chapter's functionality:
```py
+"""
+
+_CONFIG_SPEC_HELP_TEXT = """Path to config files, filenames, or key-value pairs.
+
+[bold red]IMPORTANT:[/bold red] [red]If you set this option, the default config file will not be used.[/red]
+So you need to explicitly set it e.g., with [bold green]-c mini.yaml <other options>[/bold green]
+Multiple configs will be recursively merged.
-class GlobalModelStats:
- """Global model statistics tracker with optional limits."""
+Examples:
- def __init__(self):
- self._cost = 0.0
- self._n_calls = 0
- self._lock = threading.Lock()
- self.cost_limit = float(os.getenv("MSWEA_GLOBAL_COST_LIMIT", "0"))
- self.call_limit = int(os.getenv("MSWEA_GLOBAL_CALL_LIMIT", "0"))
- if (self.cost_limit > 0 or self.call_limit > 0) and not os.getenv("MSWEA_SILENT_STARTUP"):
- print(f"Global cost/call limit: ${self.cost_limit:.4f} / {self.call_limit}")
+[bold red]-c model.model_kwargs.temperature=0[/bold red] [red]You forgot to add the default config file! See above.[/red]
- def add(self, cost: float) -> None:
- """Add a model call with its cost, checking limits."""
- with self._lock:
- self._cost += cost
- self._n_calls += 1
- if 0 < self.cost_limit < self._cost or 0 < self.call_limit < self._n_calls + 1:
- raise RuntimeError(f"Global cost/call limit exceeded: ${self._cost:.4f} / {self._n_calls}")
+[bold green]-c mini.yaml -c model.model_kwargs.temperature=0.5[/bold green]
- @property
- def cost(self) -> float:
- return self._cost
+[bold green]-c swebench.yaml agent.mode=yolo[/bold green]
+"""
- @property
- def n_calls(self) -> int:
- return self._n_calls
+console = Console(highlight=False)
+app = typer.Typer(rich_markup_mode="rich")
-GLOBAL_MODEL_STATS = GlobalModelStats()
+# fmt: off
+@app.command(help=_HELP_TEXT)
+def main(
+ model_name: str | None = typer.Option(None, "-m", "--model", help="Model to use",),
+ model_class: str | None = typer.Option(None, "--model-class", help="Model class to use (e.g., 'litellm' or 'minisweagent.models.litellm_model.LitellmModel')", rich_help_panel="Advanced"),
+ agent_class: str | None = typer.Option(None, "--agent-class", help="Agent class to use (e.g., 'interactive' or 'minisweagent.agents.interactive.InteractiveAgent')", rich_help_panel="Advanced"),
+ environment_class: str | None = typer.Option(None, "--environment-class", help="Environment class to use (e.g., 'local' or 'minisweagent.environments.local.LocalEnvironment')", rich_help_panel="Advanced"),
+ task: str | None = typer.Option(None, "-t", "--task", help="Task/problem statement", show_default=False),
+ yolo: bool = typer.Option(False, "-y", "--yolo", help="Run without confirmation"),
+ cost_limit: float | None = typer.Option(None, "-l", "--cost-limit", help="Cost limit. Set to 0 to disable."),
```
This class is important because it defines how Mini-SWE-Agent Tutorial: Minimal Autonomous Code Agent Design at Benchmark Scale implements the patterns covered in this chapter.
@@ -212,11 +210,11 @@ This class is important because it defines how Mini-SWE-Agent Tutorial: Minimal
```mermaid
flowchart TD
- A[SingularityEnvironment]
- B[OpenRouterResponseModelConfig]
- C[OpenRouterResponseModel]
- D[GlobalModelStats]
- E[is]
+ A[get_model_name]
+ B[get_model_class]
+ C[to]
+ D[to]
+ E[to]
A --> B
B --> C
C --> D
diff --git a/tutorials/mini-swe-agent-tutorial/07-cookbook-extensions-and-python-bindings.md b/tutorials/mini-swe-agent-tutorial/07-cookbook-extensions-and-python-bindings.md
index 9114f628..6beffd1f 100644
--- a/tutorials/mini-swe-agent-tutorial/07-cookbook-extensions-and-python-bindings.md
+++ b/tutorials/mini-swe-agent-tutorial/07-cookbook-extensions-and-python-bindings.md
@@ -38,119 +38,54 @@ You now have a path to custom behavior while preserving the minimal architecture
Next: [Chapter 8: Contribution Workflow and Governance](08-contribution-workflow-and-governance.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/minisweagent/models/__init__.py`
-
-The `get_model_class` function in [`src/minisweagent/models/__init__.py`](https://github.com/SWE-agent/mini-swe-agent/blob/HEAD/src/minisweagent/models/__init__.py) handles a key part of this chapter's functionality:
-
-```py
- config["model_name"] = resolved_model_name
-
- model_class = get_model_class(resolved_model_name, config.pop("model_class", ""))
-
- if (
- any(s in resolved_model_name.lower() for s in ["anthropic", "sonnet", "opus", "claude"])
- and "set_cache_control" not in config
- ):
- # Select cache control for Anthropic models by default
- config["set_cache_control"] = "default_end"
-
- return model_class(**config)
-
-
-def get_model_name(input_model_name: str | None = None, config: dict | None = None) -> str:
- """Get a model name from any kind of user input or settings."""
- if config is None:
- config = {}
- if input_model_name:
- return input_model_name
- if from_config := config.get("model_name"):
- return from_config
- if from_env := os.getenv("MSWEA_MODEL_NAME"):
- return from_env
- raise ValueError("No default model set. Please run `mini-extra config setup` to set one.")
-
-
-_MODEL_CLASS_MAPPING = {
- "litellm": "minisweagent.models.litellm_model.LitellmModel",
- "litellm_textbased": "minisweagent.models.litellm_textbased_model.LitellmTextbasedModel",
- "litellm_response": "minisweagent.models.litellm_response_model.LitellmResponseModel",
- "openrouter": "minisweagent.models.openrouter_model.OpenRouterModel",
-```
-
-This function is important because it defines how Mini-SWE-Agent Tutorial: Minimal Autonomous Code Agent Design at Benchmark Scale implements the patterns covered in this chapter.
-
### `src/minisweagent/run/mini.py`
-The `to` class in [`src/minisweagent/run/mini.py`](https://github.com/SWE-agent/mini-swe-agent/blob/HEAD/src/minisweagent/run/mini.py) handles a key part of this chapter's functionality:
+The `or` class in [`src/minisweagent/run/mini.py`](https://github.com/SWE-agent/mini-swe-agent/blob/HEAD/src/minisweagent/run/mini.py) handles a key part of this chapter's functionality:
```py
-"""
+# Read this first: https://mini-swe-agent.com/latest/usage/mini/ (usage)
-_CONFIG_SPEC_HELP_TEXT = """Path to config files, filenames, or key-value pairs.
+import os
+from pathlib import Path
+from typing import Any
-[bold red]IMPORTANT:[/bold red] [red]If you set this option, the default config file will not be used.[/red]
-So you need to explicitly set it e.g., with [bold green]-c mini.yaml <other options>[/bold green]
+import typer
+from rich.console import Console
-Multiple configs will be recursively merged.
+from minisweagent import global_config_dir
+from minisweagent.agents import get_agent
+from minisweagent.agents.utils.prompt_user import _multiline_prompt
+from minisweagent.config import builtin_config_dir, get_config_from_spec
+from minisweagent.environments import get_environment
+from minisweagent.models import get_model
+from minisweagent.run.utilities.config import configure_if_first_time
+from minisweagent.utils.serialize import UNSET, recursive_merge
-Examples:
+DEFAULT_CONFIG_FILE = Path(os.getenv("MSWEA_MINI_CONFIG_PATH", builtin_config_dir / "mini.yaml"))
+DEFAULT_OUTPUT_FILE = global_config_dir / "last_mini_run.traj.json"
-[bold red]-c model.model_kwargs.temperature=0[/bold red] [red]You forgot to add the default config file! See above.[/red]
-[bold green]-c mini.yaml -c model.model_kwargs.temperature=0.5[/bold green]
+_HELP_TEXT = """Run mini-SWE-agent in your local environment.
-[bold green]-c swebench.yaml agent.mode=yolo[/bold green]
+[not dim]
+More information about the usage: [bold green]https://mini-swe-agent.com/latest/usage/mini/[/bold green]
+[/not dim]
"""
-console = Console(highlight=False)
-app = typer.Typer(rich_markup_mode="rich")
-
+_CONFIG_SPEC_HELP_TEXT = """Path to config files, filenames, or key-value pairs.
-# fmt: off
-@app.command(help=_HELP_TEXT)
-def main(
- model_name: str | None = typer.Option(None, "-m", "--model", help="Model to use",),
- model_class: str | None = typer.Option(None, "--model-class", help="Model class to use (e.g., 'litellm' or 'minisweagent.models.litellm_model.LitellmModel')", rich_help_panel="Advanced"),
- agent_class: str | None = typer.Option(None, "--agent-class", help="Agent class to use (e.g., 'interactive' or 'minisweagent.agents.interactive.InteractiveAgent')", rich_help_panel="Advanced"),
- environment_class: str | None = typer.Option(None, "--environment-class", help="Environment class to use (e.g., 'local' or 'minisweagent.environments.local.LocalEnvironment')", rich_help_panel="Advanced"),
- task: str | None = typer.Option(None, "-t", "--task", help="Task/problem statement", show_default=False),
- yolo: bool = typer.Option(False, "-y", "--yolo", help="Run without confirmation"),
- cost_limit: float | None = typer.Option(None, "-l", "--cost-limit", help="Cost limit. Set to 0 to disable."),
+[bold red]IMPORTANT:[/bold red] [red]If you set this option, the default config file will not be used.[/red]
```
This class is important because it defines how Mini-SWE-Agent Tutorial: Minimal Autonomous Code Agent Design at Benchmark Scale implements the patterns covered in this chapter.
### `src/minisweagent/run/mini.py`
-The `to` class in [`src/minisweagent/run/mini.py`](https://github.com/SWE-agent/mini-swe-agent/blob/HEAD/src/minisweagent/run/mini.py) handles a key part of this chapter's functionality:
+The `main` function in [`src/minisweagent/run/mini.py`](https://github.com/SWE-agent/mini-swe-agent/blob/HEAD/src/minisweagent/run/mini.py) handles a key part of this chapter's functionality:
```py
-"""
-
-_CONFIG_SPEC_HELP_TEXT = """Path to config files, filenames, or key-value pairs.
-
-[bold red]IMPORTANT:[/bold red] [red]If you set this option, the default config file will not be used.[/red]
-So you need to explicitly set it e.g., with [bold green]-c mini.yaml <other options>[/bold green]
-
-Multiple configs will be recursively merged.
-
-Examples:
-
-[bold red]-c model.model_kwargs.temperature=0[/bold red] [red]You forgot to add the default config file! See above.[/red]
-
-[bold green]-c mini.yaml -c model.model_kwargs.temperature=0.5[/bold green]
-
-[bold green]-c swebench.yaml agent.mode=yolo[/bold green]
-"""
-
-console = Console(highlight=False)
-app = typer.Typer(rich_markup_mode="rich")
-
-
# fmt: off
@app.command(help=_HELP_TEXT)
def main(
@@ -161,47 +96,110 @@ def main(
task: str | None = typer.Option(None, "-t", "--task", help="Task/problem statement", show_default=False),
yolo: bool = typer.Option(False, "-y", "--yolo", help="Run without confirmation"),
cost_limit: float | None = typer.Option(None, "-l", "--cost-limit", help="Cost limit. Set to 0 to disable."),
+ config_spec: list[str] = typer.Option([str(DEFAULT_CONFIG_FILE)], "-c", "--config", help=_CONFIG_SPEC_HELP_TEXT),
+ output: Path | None = typer.Option(DEFAULT_OUTPUT_FILE, "-o", "--output", help="Output trajectory file"),
+ exit_immediately: bool = typer.Option(False, "--exit-immediately", help="Exit immediately when the agent wants to finish instead of prompting.", rich_help_panel="Advanced"),
+) -> Any:
+ # fmt: on
+ configure_if_first_time()
+
+ # Build the config from the command line arguments
+ console.print(f"Building agent config from specs: [bold green]{config_spec}[/bold green]")
+ configs = [get_config_from_spec(spec) for spec in config_spec]
+ configs.append({
+ "run": {
+ "task": task or UNSET,
+ },
+ "agent": {
+ "agent_class": agent_class or UNSET,
+ "mode": "yolo" if yolo else UNSET,
+ "cost_limit": cost_limit or UNSET,
+ "confirm_exit": False if exit_immediately else UNSET,
+ "output_path": output or UNSET,
+ },
+ "model": {
```
-This class is important because it defines how Mini-SWE-Agent Tutorial: Minimal Autonomous Code Agent Design at Benchmark Scale implements the patterns covered in this chapter.
+This function is important because it defines how Mini-SWE-Agent Tutorial: Minimal Autonomous Code Agent Design at Benchmark Scale implements the patterns covered in this chapter.
-### `src/minisweagent/run/mini.py`
+### `src/minisweagent/models/litellm_textbased_model.py`
-The `to` class in [`src/minisweagent/run/mini.py`](https://github.com/SWE-agent/mini-swe-agent/blob/HEAD/src/minisweagent/run/mini.py) handles a key part of this chapter's functionality:
+The `LitellmTextbasedModelConfig` class in [`src/minisweagent/models/litellm_textbased_model.py`](https://github.com/SWE-agent/mini-swe-agent/blob/HEAD/src/minisweagent/models/litellm_textbased_model.py) handles a key part of this chapter's functionality:
```py
-"""
-
-_CONFIG_SPEC_HELP_TEXT = """Path to config files, filenames, or key-value pairs.
-
-[bold red]IMPORTANT:[/bold red] [red]If you set this option, the default config file will not be used.[/red]
-So you need to explicitly set it e.g., with [bold green]-c mini.yaml <other options>[/bold green]
-Multiple configs will be recursively merged.
-Examples:
+class LitellmTextbasedModelConfig(LitellmModelConfig):
+ action_regex: str = r"```mswea_bash_command\s*\n(.*?)\n```"
+ """Regex to extract the action from the LM's output."""
+ format_error_template: str = (
+ "Please always provide EXACTLY ONE action in triple backticks, found {{actions|length}} actions."
+ )
+ """Template used when the LM's output is not in the expected format."""
+
+
+class LitellmTextbasedModel(LitellmModel):
+ def __init__(self, **kwargs):
+ super().__init__(config_class=LitellmTextbasedModelConfig, **kwargs)
+
+ def _query(self, messages: list[dict[str, str]], **kwargs):
+ try:
+ return litellm.completion(
+ model=self.config.model_name, messages=messages, **(self.config.model_kwargs | kwargs)
+ )
+ except litellm.exceptions.AuthenticationError as e:
+ e.message += " You can permanently set your API key with `mini-extra config set KEY VALUE`."
+ raise e
+
+ def _parse_actions(self, response: dict) -> list[dict]:
+ """Parse actions from the model response. Raises FormatError if not exactly one action."""
+ content = response.choices[0].message.content or ""
+ return parse_regex_actions(
+ content, action_regex=self.config.action_regex, format_error_template=self.config.format_error_template
+ )
+
+ def format_observation_messages(
+```
-[bold red]-c model.model_kwargs.temperature=0[/bold red] [red]You forgot to add the default config file! See above.[/red]
+This class is important because it defines how Mini-SWE-Agent Tutorial: Minimal Autonomous Code Agent Design at Benchmark Scale implements the patterns covered in this chapter.
-[bold green]-c mini.yaml -c model.model_kwargs.temperature=0.5[/bold green]
+### `src/minisweagent/models/litellm_textbased_model.py`
-[bold green]-c swebench.yaml agent.mode=yolo[/bold green]
-"""
+The `LitellmTextbasedModel` class in [`src/minisweagent/models/litellm_textbased_model.py`](https://github.com/SWE-agent/mini-swe-agent/blob/HEAD/src/minisweagent/models/litellm_textbased_model.py) handles a key part of this chapter's functionality:
-console = Console(highlight=False)
-app = typer.Typer(rich_markup_mode="rich")
+```py
-# fmt: off
-@app.command(help=_HELP_TEXT)
-def main(
- model_name: str | None = typer.Option(None, "-m", "--model", help="Model to use",),
- model_class: str | None = typer.Option(None, "--model-class", help="Model class to use (e.g., 'litellm' or 'minisweagent.models.litellm_model.LitellmModel')", rich_help_panel="Advanced"),
- agent_class: str | None = typer.Option(None, "--agent-class", help="Agent class to use (e.g., 'interactive' or 'minisweagent.agents.interactive.InteractiveAgent')", rich_help_panel="Advanced"),
- environment_class: str | None = typer.Option(None, "--environment-class", help="Environment class to use (e.g., 'local' or 'minisweagent.environments.local.LocalEnvironment')", rich_help_panel="Advanced"),
- task: str | None = typer.Option(None, "-t", "--task", help="Task/problem statement", show_default=False),
- yolo: bool = typer.Option(False, "-y", "--yolo", help="Run without confirmation"),
- cost_limit: float | None = typer.Option(None, "-l", "--cost-limit", help="Cost limit. Set to 0 to disable."),
+class LitellmTextbasedModelConfig(LitellmModelConfig):
+ action_regex: str = r"```mswea_bash_command\s*\n(.*?)\n```"
+ """Regex to extract the action from the LM's output."""
+ format_error_template: str = (
+ "Please always provide EXACTLY ONE action in triple backticks, found {{actions|length}} actions."
+ )
+ """Template used when the LM's output is not in the expected format."""
+
+
+class LitellmTextbasedModel(LitellmModel):
+ def __init__(self, **kwargs):
+ super().__init__(config_class=LitellmTextbasedModelConfig, **kwargs)
+
+ def _query(self, messages: list[dict[str, str]], **kwargs):
+ try:
+ return litellm.completion(
+ model=self.config.model_name, messages=messages, **(self.config.model_kwargs | kwargs)
+ )
+ except litellm.exceptions.AuthenticationError as e:
+ e.message += " You can permanently set your API key with `mini-extra config set KEY VALUE`."
+ raise e
+
+ def _parse_actions(self, response: dict) -> list[dict]:
+ """Parse actions from the model response. Raises FormatError if not exactly one action."""
+ content = response.choices[0].message.content or ""
+ return parse_regex_actions(
+ content, action_regex=self.config.action_regex, format_error_template=self.config.format_error_template
+ )
+
+ def format_observation_messages(
```
This class is important because it defines how Mini-SWE-Agent Tutorial: Minimal Autonomous Code Agent Design at Benchmark Scale implements the patterns covered in this chapter.
@@ -211,11 +209,11 @@ This class is important because it defines how Mini-SWE-Agent Tutorial: Minimal
```mermaid
flowchart TD
- A[get_model_class]
- B[to]
- C[to]
- D[to]
- E[or]
+ A[or]
+ B[main]
+ C[LitellmTextbasedModelConfig]
+ D[LitellmTextbasedModel]
+ E[OpenRouterTextbasedModelConfig]
A --> B
B --> C
C --> D
diff --git a/tutorials/mini-swe-agent-tutorial/08-contribution-workflow-and-governance.md b/tutorials/mini-swe-agent-tutorial/08-contribution-workflow-and-governance.md
index f460d363..b88b9453 100644
--- a/tutorials/mini-swe-agent-tutorial/08-contribution-workflow-and-governance.md
+++ b/tutorials/mini-swe-agent-tutorial/08-contribution-workflow-and-governance.md
@@ -39,92 +39,8 @@ You now have a full mini-swe-agent track from first run to sustainable contribut
Next tutorial: [Qwen-Agent Tutorial](../qwen-agent-tutorial/)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/minisweagent/run/mini.py`
-
-The `main` function in [`src/minisweagent/run/mini.py`](https://github.com/SWE-agent/mini-swe-agent/blob/HEAD/src/minisweagent/run/mini.py) handles a key part of this chapter's functionality:
-
-```py
-# fmt: off
-@app.command(help=_HELP_TEXT)
-def main(
- model_name: str | None = typer.Option(None, "-m", "--model", help="Model to use",),
- model_class: str | None = typer.Option(None, "--model-class", help="Model class to use (e.g., 'litellm' or 'minisweagent.models.litellm_model.LitellmModel')", rich_help_panel="Advanced"),
- agent_class: str | None = typer.Option(None, "--agent-class", help="Agent class to use (e.g., 'interactive' or 'minisweagent.agents.interactive.InteractiveAgent')", rich_help_panel="Advanced"),
- environment_class: str | None = typer.Option(None, "--environment-class", help="Environment class to use (e.g., 'local' or 'minisweagent.environments.local.LocalEnvironment')", rich_help_panel="Advanced"),
- task: str | None = typer.Option(None, "-t", "--task", help="Task/problem statement", show_default=False),
- yolo: bool = typer.Option(False, "-y", "--yolo", help="Run without confirmation"),
- cost_limit: float | None = typer.Option(None, "-l", "--cost-limit", help="Cost limit. Set to 0 to disable."),
- config_spec: list[str] = typer.Option([str(DEFAULT_CONFIG_FILE)], "-c", "--config", help=_CONFIG_SPEC_HELP_TEXT),
- output: Path | None = typer.Option(DEFAULT_OUTPUT_FILE, "-o", "--output", help="Output trajectory file"),
- exit_immediately: bool = typer.Option(False, "--exit-immediately", help="Exit immediately when the agent wants to finish instead of prompting.", rich_help_panel="Advanced"),
-) -> Any:
- # fmt: on
- configure_if_first_time()
-
- # Build the config from the command line arguments
- console.print(f"Building agent config from specs: [bold green]{config_spec}[/bold green]")
- configs = [get_config_from_spec(spec) for spec in config_spec]
- configs.append({
- "run": {
- "task": task or UNSET,
- },
- "agent": {
- "agent_class": agent_class or UNSET,
- "mode": "yolo" if yolo else UNSET,
- "cost_limit": cost_limit or UNSET,
- "confirm_exit": False if exit_immediately else UNSET,
- "output_path": output or UNSET,
- },
- "model": {
-```
-
-This function is important because it defines how Mini-SWE-Agent Tutorial: Minimal Autonomous Code Agent Design at Benchmark Scale implements the patterns covered in this chapter.
-
-### `src/minisweagent/environments/local.py`
-
-The `LocalEnvironmentConfig` class in [`src/minisweagent/environments/local.py`](https://github.com/SWE-agent/mini-swe-agent/blob/HEAD/src/minisweagent/environments/local.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-class LocalEnvironmentConfig(BaseModel):
- cwd: str = ""
- env: dict[str, str] = {}
- timeout: int = 30
-
-
-class LocalEnvironment:
- def __init__(self, *, config_class: type = LocalEnvironmentConfig, **kwargs):
- """This class executes bash commands directly on the local machine."""
- self.config = config_class(**kwargs)
-
- def execute(self, action: dict, cwd: str = "", *, timeout: int | None = None) -> dict[str, Any]:
- """Execute a command in the local environment and return the result as a dict."""
- command = action.get("command", "")
- cwd = cwd or self.config.cwd or os.getcwd()
- try:
- result = subprocess.run(
- command,
- shell=True,
- text=True,
- cwd=cwd,
- env=os.environ | self.config.env,
- timeout=timeout or self.config.timeout,
- encoding="utf-8",
- errors="replace",
- stdout=subprocess.PIPE,
- stderr=subprocess.STDOUT,
- )
- output = {"output": result.stdout, "returncode": result.returncode, "exception_info": ""}
- except Exception as e:
-```
-
-This class is important because it defines how Mini-SWE-Agent Tutorial: Minimal Autonomous Code Agent Design at Benchmark Scale implements the patterns covered in this chapter.
-
### `src/minisweagent/environments/local.py`
The `LocalEnvironment` class in [`src/minisweagent/environments/local.py`](https://github.com/SWE-agent/mini-swe-agent/blob/HEAD/src/minisweagent/environments/local.py) handles a key part of this chapter's functionality:
@@ -207,16 +123,98 @@ class LocalEnvironment:
This class is important because it defines how Mini-SWE-Agent Tutorial: Minimal Autonomous Code Agent Design at Benchmark Scale implements the patterns covered in this chapter.
+### `src/minisweagent/models/portkey_response_model.py`
+
+The `PortkeyResponseAPIModelConfig` class in [`src/minisweagent/models/portkey_response_model.py`](https://github.com/SWE-agent/mini-swe-agent/blob/HEAD/src/minisweagent/models/portkey_response_model.py) handles a key part of this chapter's functionality:
+
+```py
+
+
+class PortkeyResponseAPIModelConfig(BaseModel):
+ model_name: str
+ model_kwargs: dict[str, Any] = {}
+ litellm_model_registry: Path | str | None = os.getenv("LITELLM_MODEL_REGISTRY_PATH")
+ litellm_model_name_override: str = ""
+ cost_tracking: Literal["default", "ignore_errors"] = os.getenv("MSWEA_COST_TRACKING", "default")
+ format_error_template: str = "{{ error }}"
+ observation_template: str = (
+ "{% if output.exception_info %}<exception>{{output.exception_info}}</exception>\n{% endif %}"
+ "<returncode>{{output.returncode}}</returncode>\n<output>\n{{output.output}}</output>"
+ )
+ multimodal_regex: str = ""
+
+
+class PortkeyResponseAPIModel:
+ """Portkey model using the Responses API with native tool calling.
+
+ Note: This implementation is stateless - each request must include
+ the full conversation history. previous_response_id is not used.
+ """
+
+ abort_exceptions: list[type[Exception]] = [KeyboardInterrupt, TypeError, ValueError]
+
+ def __init__(self, **kwargs):
+ self.config = PortkeyResponseAPIModelConfig(**kwargs)
+ if self.config.litellm_model_registry and Path(self.config.litellm_model_registry).is_file():
+ litellm.utils.register_model(json.loads(Path(self.config.litellm_model_registry).read_text()))
+
+ self._api_key = os.getenv("PORTKEY_API_KEY")
+ if not self._api_key:
+```
+
+This class is important because it defines how Mini-SWE-Agent Tutorial: Minimal Autonomous Code Agent Design at Benchmark Scale implements the patterns covered in this chapter.
+
+### `src/minisweagent/models/portkey_response_model.py`
+
+The `PortkeyResponseAPIModel` class in [`src/minisweagent/models/portkey_response_model.py`](https://github.com/SWE-agent/mini-swe-agent/blob/HEAD/src/minisweagent/models/portkey_response_model.py) handles a key part of this chapter's functionality:
+
+```py
+except ImportError:
+ raise ImportError(
+ "The portkey-ai package is required to use PortkeyResponseAPIModel. Please install it with: pip install portkey-ai"
+ )
+
+
+class PortkeyResponseAPIModelConfig(BaseModel):
+ model_name: str
+ model_kwargs: dict[str, Any] = {}
+ litellm_model_registry: Path | str | None = os.getenv("LITELLM_MODEL_REGISTRY_PATH")
+ litellm_model_name_override: str = ""
+ cost_tracking: Literal["default", "ignore_errors"] = os.getenv("MSWEA_COST_TRACKING", "default")
+ format_error_template: str = "{{ error }}"
+ observation_template: str = (
+ "{% if output.exception_info %}<exception>{{output.exception_info}}</exception>\n{% endif %}"
+ "<returncode>{{output.returncode}}</returncode>\n<output>\n{{output.output}}</output>"
+ )
+ multimodal_regex: str = ""
+
+
+class PortkeyResponseAPIModel:
+ """Portkey model using the Responses API with native tool calling.
+
+ Note: This implementation is stateless - each request must include
+ the full conversation history. previous_response_id is not used.
+ """
+
+ abort_exceptions: list[type[Exception]] = [KeyboardInterrupt, TypeError, ValueError]
+
+ def __init__(self, **kwargs):
+ self.config = PortkeyResponseAPIModelConfig(**kwargs)
+ if self.config.litellm_model_registry and Path(self.config.litellm_model_registry).is_file():
+```
+
+This class is important because it defines how Mini-SWE-Agent Tutorial: Minimal Autonomous Code Agent Design at Benchmark Scale implements the patterns covered in this chapter.
+
## How These Components Connect
```mermaid
flowchart TD
- A[main]
- B[LocalEnvironmentConfig]
- C[LocalEnvironment]
- D[executes]
- E[LitellmResponseModelConfig]
+ A[LocalEnvironment]
+ B[executes]
+ C[PortkeyResponseAPIModelConfig]
+ D[PortkeyResponseAPIModel]
+ E[RequestyModelConfig]
A --> B
B --> C
C --> D
diff --git a/tutorials/mistral-vibe-tutorial/01-getting-started.md b/tutorials/mistral-vibe-tutorial/01-getting-started.md
index ab3a37b4..1e315aef 100644
--- a/tutorials/mistral-vibe-tutorial/01-getting-started.md
+++ b/tutorials/mistral-vibe-tutorial/01-getting-started.md
@@ -42,170 +42,168 @@ You now have Vibe running in interactive mode with project context.
Next: [Chapter 2: Agent Profiles and Trust Model](02-agent-profiles-and-trust-model.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `scripts/prepare_release.py`
+### `scripts/bump_version.py`
-The `run_git_command` function in [`scripts/prepare_release.py`](https://github.com/mistralai/mistral-vibe/blob/HEAD/scripts/prepare_release.py) handles a key part of this chapter's functionality:
+The `parse_version` function in [`scripts/bump_version.py`](https://github.com/mistralai/mistral-vibe/blob/HEAD/scripts/bump_version.py) handles a key part of this chapter's functionality:
```py
-def run_git_command(
- *args: str, check: bool = True, capture_output: bool = False
-) -> subprocess.CompletedProcess[str]:
- """Run a git command and return the result."""
- result = subprocess.run(
- ["git"] + list(args), check=check, capture_output=capture_output, text=True
- )
- return result
+def parse_version(version_str: str) -> tuple[int, int, int]:
+ match = re.match(r"^(\d+)\.(\d+)\.(\d+)$", version_str.strip())
+ if not match:
+ raise ValueError(f"Invalid version format: {version_str}")
+
+ return int(match.group(1)), int(match.group(2)), int(match.group(3))
+
+
+def format_version(major: int, minor: int, patch: int) -> str:
+ return f"{major}.{minor}.{patch}"
-def ensure_public_remote() -> None:
- result = run_git_command("remote", "-v", capture_output=True, check=False)
- remotes = result.stdout
+def bump_version(version: str, bump_type: BumpType) -> str:
+ major, minor, patch = parse_version(version)
- public_remote_url = "git@github.com:mistralai/mistral-vibe.git"
- if public_remote_url in remotes:
- print("Public remote already exists with correct URL")
- return
+ match bump_type:
+ case "major":
+ return format_version(major + 1, 0, 0)
+ case "minor":
+ return format_version(major, minor + 1, 0)
+ case "micro" | "patch":
+ return format_version(major, minor, patch + 1)
- print(f"Creating public remote: {public_remote_url}")
- run_git_command("remote", "add", "public", public_remote_url)
- print("Public remote created successfully")
+def update_hard_values_files(filepath: str, patterns: list[tuple[str, str]]) -> None:
+ path = Path(filepath)
-def switch_to_tag(version: str) -> None:
- tag = f"v{version}"
- print(f"Switching to tag {tag}...")
+ if not path.exists():
+ raise FileNotFoundError(f"{filepath} not found in current directory")
- result = run_git_command(
- "rev-parse", "--verify", tag, capture_output=True, check=False
```
This function is important because it defines how Mistral Vibe Tutorial: Minimal CLI Coding Agent by Mistral implements the patterns covered in this chapter.
-### `scripts/prepare_release.py`
+### `scripts/bump_version.py`
-The `ensure_public_remote` function in [`scripts/prepare_release.py`](https://github.com/mistralai/mistral-vibe/blob/HEAD/scripts/prepare_release.py) handles a key part of this chapter's functionality:
+The `format_version` function in [`scripts/bump_version.py`](https://github.com/mistralai/mistral-vibe/blob/HEAD/scripts/bump_version.py) handles a key part of this chapter's functionality:
```py
-def ensure_public_remote() -> None:
- result = run_git_command("remote", "-v", capture_output=True, check=False)
- remotes = result.stdout
+def format_version(major: int, minor: int, patch: int) -> str:
+ return f"{major}.{minor}.{patch}"
- public_remote_url = "git@github.com:mistralai/mistral-vibe.git"
- if public_remote_url in remotes:
- print("Public remote already exists with correct URL")
- return
- print(f"Creating public remote: {public_remote_url}")
- run_git_command("remote", "add", "public", public_remote_url)
- print("Public remote created successfully")
+def bump_version(version: str, bump_type: BumpType) -> str:
+ major, minor, patch = parse_version(version)
+ match bump_type:
+ case "major":
+ return format_version(major + 1, 0, 0)
+ case "minor":
+ return format_version(major, minor + 1, 0)
+ case "micro" | "patch":
+ return format_version(major, minor, patch + 1)
-def switch_to_tag(version: str) -> None:
- tag = f"v{version}"
- print(f"Switching to tag {tag}...")
- result = run_git_command(
- "rev-parse", "--verify", tag, capture_output=True, check=False
- )
- if result.returncode != 0:
- raise ValueError(f"Tag {tag} does not exist")
+def update_hard_values_files(filepath: str, patterns: list[tuple[str, str]]) -> None:
+ path = Path(filepath)
- run_git_command("switch", "--detach", tag)
- print(f"Successfully switched to tag {tag}")
+ if not path.exists():
+ raise FileNotFoundError(f"{filepath} not found in current directory")
+ for pattern, replacement in patterns:
+ content = path.read_text()
+ updated_content = re.sub(pattern, replacement, content, flags=re.MULTILINE)
-def get_version_from_pyproject() -> str:
- pyproject_path = Path("pyproject.toml")
+ if updated_content == content:
+ raise ValueError(f"pattern {pattern} not found in {filepath}")
+
+ path.write_text(updated_content)
```
This function is important because it defines how Mistral Vibe Tutorial: Minimal CLI Coding Agent by Mistral implements the patterns covered in this chapter.
-### `scripts/prepare_release.py`
+### `scripts/bump_version.py`
-The `switch_to_tag` function in [`scripts/prepare_release.py`](https://github.com/mistralai/mistral-vibe/blob/HEAD/scripts/prepare_release.py) handles a key part of this chapter's functionality:
+The `bump_version` function in [`scripts/bump_version.py`](https://github.com/mistralai/mistral-vibe/blob/HEAD/scripts/bump_version.py) handles a key part of this chapter's functionality:
```py
-def switch_to_tag(version: str) -> None:
- tag = f"v{version}"
- print(f"Switching to tag {tag}...")
+def bump_version(version: str, bump_type: BumpType) -> str:
+ major, minor, patch = parse_version(version)
- result = run_git_command(
- "rev-parse", "--verify", tag, capture_output=True, check=False
- )
- if result.returncode != 0:
- raise ValueError(f"Tag {tag} does not exist")
+ match bump_type:
+ case "major":
+ return format_version(major + 1, 0, 0)
+ case "minor":
+ return format_version(major, minor + 1, 0)
+ case "micro" | "patch":
+ return format_version(major, minor, patch + 1)
- run_git_command("switch", "--detach", tag)
- print(f"Successfully switched to tag {tag}")
+def update_hard_values_files(filepath: str, patterns: list[tuple[str, str]]) -> None:
+ path = Path(filepath)
-def get_version_from_pyproject() -> str:
- pyproject_path = Path("pyproject.toml")
- if not pyproject_path.exists():
- raise FileNotFoundError("pyproject.toml not found in current directory")
+ if not path.exists():
+ raise FileNotFoundError(f"{filepath} not found in current directory")
- content = pyproject_path.read_text()
- version_match = re.search(r'^version = "([^"]+)"$', content, re.MULTILINE)
- if not version_match:
- raise ValueError("Version not found in pyproject.toml")
+ for pattern, replacement in patterns:
+ content = path.read_text()
+ updated_content = re.sub(pattern, replacement, content, flags=re.MULTILINE)
+
+ if updated_content == content:
+ raise ValueError(f"pattern {pattern} not found in {filepath}")
+
+ path.write_text(updated_content)
- return version_match.group(1)
+ print(f"Updated version in {filepath}")
-def get_latest_version() -> str:
- result = run_git_command("ls-remote", "--tags", "public", capture_output=True)
- remote_tags_output = (
```
This function is important because it defines how Mistral Vibe Tutorial: Minimal CLI Coding Agent by Mistral implements the patterns covered in this chapter.
-### `scripts/prepare_release.py`
+### `scripts/bump_version.py`
-The `get_version_from_pyproject` function in [`scripts/prepare_release.py`](https://github.com/mistralai/mistral-vibe/blob/HEAD/scripts/prepare_release.py) handles a key part of this chapter's functionality:
+The `update_hard_values_files` function in [`scripts/bump_version.py`](https://github.com/mistralai/mistral-vibe/blob/HEAD/scripts/bump_version.py) handles a key part of this chapter's functionality:
```py
-def get_version_from_pyproject() -> str:
+def update_hard_values_files(filepath: str, patterns: list[tuple[str, str]]) -> None:
+ path = Path(filepath)
+
+ if not path.exists():
+ raise FileNotFoundError(f"{filepath} not found in current directory")
+
+ for pattern, replacement in patterns:
+ content = path.read_text()
+ updated_content = re.sub(pattern, replacement, content, flags=re.MULTILINE)
+
+ if updated_content == content:
+ raise ValueError(f"pattern {pattern} not found in {filepath}")
+
+ path.write_text(updated_content)
+
+ print(f"Updated version in {filepath}")
+
+
+def get_current_version() -> str:
pyproject_path = Path("pyproject.toml")
+
if not pyproject_path.exists():
raise FileNotFoundError("pyproject.toml not found in current directory")
content = pyproject_path.read_text()
+
version_match = re.search(r'^version = "([^"]+)"$', content, re.MULTILINE)
if not version_match:
raise ValueError("Version not found in pyproject.toml")
- return version_match.group(1)
-
-
-def get_latest_version() -> str:
- result = run_git_command("ls-remote", "--tags", "public", capture_output=True)
- remote_tags_output = (
- result.stdout.strip().split("\n") if result.stdout.strip() else []
- )
-
- if not remote_tags_output:
- raise ValueError("No version tags found on public remote")
-
- versions: list[tuple[int, int, int, str]] = []
- MIN_PARTS_IN_LS_REMOTE_LINE = 2 # hash and ref
- for line in remote_tags_output:
- parts = line.split()
- if len(parts) < MIN_PARTS_IN_LS_REMOTE_LINE:
- continue
-
- _hash, tag_ref = parts[0], parts[1]
```
This function is important because it defines how Mistral Vibe Tutorial: Minimal CLI Coding Agent by Mistral implements the patterns covered in this chapter.
@@ -215,11 +213,11 @@ This function is important because it defines how Mistral Vibe Tutorial: Minimal
```mermaid
flowchart TD
- A[run_git_command]
- B[ensure_public_remote]
- C[switch_to_tag]
- D[get_version_from_pyproject]
- E[get_latest_version]
+ A[parse_version]
+ B[format_version]
+ C[bump_version]
+ D[update_hard_values_files]
+ E[get_current_version]
A --> B
B --> C
C --> D
diff --git a/tutorials/mistral-vibe-tutorial/02-agent-profiles-and-trust-model.md b/tutorials/mistral-vibe-tutorial/02-agent-profiles-and-trust-model.md
index b27f416c..4985d971 100644
--- a/tutorials/mistral-vibe-tutorial/02-agent-profiles-and-trust-model.md
+++ b/tutorials/mistral-vibe-tutorial/02-agent-profiles-and-trust-model.md
@@ -37,184 +37,182 @@ You now understand how to pick agent profiles and use trust controls safely.
Next: [Chapter 3: Tooling and Approval Workflow](03-tooling-and-approval-workflow.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `scripts/bump_version.py`
+### `scripts/prepare_release.py`
-The `fill_whats_new_message` function in [`scripts/bump_version.py`](https://github.com/mistralai/mistral-vibe/blob/HEAD/scripts/bump_version.py) handles a key part of this chapter's functionality:
+The `get_commits_summary` function in [`scripts/prepare_release.py`](https://github.com/mistralai/mistral-vibe/blob/HEAD/scripts/prepare_release.py) handles a key part of this chapter's functionality:
```py
-def fill_whats_new_message(new_version: str) -> None:
- whats_new_path = Path("vibe/whats_new.md")
- if not whats_new_path.exists():
- raise FileNotFoundError("whats_new.md not found in current directory")
-
- whats_new_path.write_text("")
-
- print("Filling whats_new.md...")
- prompt = f"""Fill vibe/whats_new.md using only the CHANGELOG.md section for version {new_version}.
-
-Rules:
-- Include only the most important user-facing changes: visible CLI/UI behavior, new commands or key bindings, UX improvements. Exclude internal refactors, API-only changes, and dev/tooling updates.
-- If there are no such changes, write nothing (empty file).
-- Otherwise: first line must be "# What's new in v{new_version}" (no extra heading). Then one bullet per item, format: "- **Feature**: short summary" (e.g. - **Interactive resume**: Added a /resume command to choose which session to resume). One line per bullet, concise.
-- Do not copy the full changelog; summarize only what matters to someone reading "what's new" in the app."""
- try:
- result = subprocess.run(
- ["vibe", "-p", prompt], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL
- )
- if result.returncode != 0:
- raise RuntimeError("Failed to auto-fill whats_new.md")
- except Exception:
- print(
- "Warning: failed to auto-fill whats_new.md, please fill it manually.",
- file=sys.stderr,
- )
-
-
-def main() -> None:
- os.chdir(Path(__file__).parent.parent)
-```
-
-This function is important because it defines how Mistral Vibe Tutorial: Minimal CLI Coding Agent by Mistral implements the patterns covered in this chapter.
-
-### `scripts/bump_version.py`
+def get_commits_summary(previous_version: str, current_version: str) -> str:
+ previous_tag = f"v{previous_version}-private"
+ current_tag = f"v{current_version}-private"
-The `main` function in [`scripts/bump_version.py`](https://github.com/mistralai/mistral-vibe/blob/HEAD/scripts/bump_version.py) handles a key part of this chapter's functionality:
+ result = run_git_command(
+ "log", f"{previous_tag}..{current_tag}", "--oneline", capture_output=True
+ )
+ return result.stdout.strip()
-```py
+def get_changelog_entry(version: str) -> str:
+ changelog_path = Path("CHANGELOG.md")
+ if not changelog_path.exists():
+ return "CHANGELOG.md not found"
-def main() -> None:
- os.chdir(Path(__file__).parent.parent)
+ content = changelog_path.read_text()
- parser = argparse.ArgumentParser(
- description="Bump semver version in pyproject.toml",
- formatter_class=argparse.RawDescriptionHelpFormatter,
- epilog="""
-Examples:
- uv run scripts/bump_version.py major # 1.0.0 -> 2.0.0
- uv run scripts/bump_version.py minor # 1.0.0 -> 1.1.0
- uv run scripts/bump_version.py micro # 1.0.0 -> 1.0.1
- uv run scripts/bump_version.py patch # 1.0.0 -> 1.0.1
- """,
- )
+ pattern = rf"^## \[{re.escape(version)}\] - .+?(?=^## \[|\Z)"
+ match = re.search(pattern, content, re.MULTILINE | re.DOTALL)
- parser.add_argument(
- "bump_type", choices=BUMP_TYPES, help="Type of version bump to perform"
- )
+ if not match:
+ return f"No changelog entry found for version {version}"
- args = parser.parse_args()
-
- try:
- # Get current version
- current_version = get_current_version()
- print(f"Current version: {current_version}")
+ return match.group(0).strip()
- # Calculate new version
- new_version = bump_version(current_version, args.bump_type)
- print(f"New version: {new_version}\n")
+def print_summary(
+ current_version: str,
+ previous_version: str,
+ commits_summary: str,
```
This function is important because it defines how Mistral Vibe Tutorial: Minimal CLI Coding Agent by Mistral implements the patterns covered in this chapter.
-### `vibe/core/agent_loop.py`
+### `scripts/prepare_release.py`
-The `ToolExecutionResponse` class in [`vibe/core/agent_loop.py`](https://github.com/mistralai/mistral-vibe/blob/HEAD/vibe/core/agent_loop.py) handles a key part of this chapter's functionality:
+The `get_changelog_entry` function in [`scripts/prepare_release.py`](https://github.com/mistralai/mistral-vibe/blob/HEAD/scripts/prepare_release.py) handles a key part of this chapter's functionality:
```py
-class ToolExecutionResponse(StrEnum):
- SKIP = auto()
- EXECUTE = auto()
+def get_changelog_entry(version: str) -> str:
+ changelog_path = Path("CHANGELOG.md")
+ if not changelog_path.exists():
+ return "CHANGELOG.md not found"
+ content = changelog_path.read_text()
-class ToolDecision(BaseModel):
- verdict: ToolExecutionResponse
- approval_type: ToolPermission
- feedback: str | None = None
+ pattern = rf"^## \[{re.escape(version)}\] - .+?(?=^## \[|\Z)"
+ match = re.search(pattern, content, re.MULTILINE | re.DOTALL)
+ if not match:
+ return f"No changelog entry found for version {version}"
-class AgentLoopError(Exception):
- """Base exception for AgentLoop errors."""
+ return match.group(0).strip()
-class AgentLoopStateError(AgentLoopError):
- """Raised when agent loop is in an invalid state."""
-
-
-class AgentLoopLLMResponseError(AgentLoopError):
- """Raised when LLM response is malformed or missing expected data."""
-
-
-class TeleportError(AgentLoopError):
- """Raised when teleport to Vibe Nuage fails."""
-
-
-def _should_raise_rate_limit_error(e: Exception) -> bool:
- return isinstance(e, BackendError) and e.status == HTTPStatus.TOO_MANY_REQUESTS
+def print_summary(
+ current_version: str,
+ previous_version: str,
+ commits_summary: str,
+ changelog_entry: str,
+ squash: bool,
+) -> None:
+ print("\n" + "=" * 80)
+ print("RELEASE PREPARATION SUMMARY")
+ print("=" * 80)
+ print(f"\nVersion: {current_version}")
+ print(f"Previous version: {previous_version}")
+ print(f"Release branch: release/v{current_version}")
```
-This class is important because it defines how Mistral Vibe Tutorial: Minimal CLI Coding Agent by Mistral implements the patterns covered in this chapter.
+This function is important because it defines how Mistral Vibe Tutorial: Minimal CLI Coding Agent by Mistral implements the patterns covered in this chapter.
-### `vibe/core/agent_loop.py`
+### `scripts/prepare_release.py`
-The `ToolDecision` class in [`vibe/core/agent_loop.py`](https://github.com/mistralai/mistral-vibe/blob/HEAD/vibe/core/agent_loop.py) handles a key part of this chapter's functionality:
+The `print_summary` function in [`scripts/prepare_release.py`](https://github.com/mistralai/mistral-vibe/blob/HEAD/scripts/prepare_release.py) handles a key part of this chapter's functionality:
```py
-class ToolDecision(BaseModel):
- verdict: ToolExecutionResponse
- approval_type: ToolPermission
- feedback: str | None = None
-
-
-class AgentLoopError(Exception):
- """Base exception for AgentLoop errors."""
+def print_summary(
+ current_version: str,
+ previous_version: str,
+ commits_summary: str,
+ changelog_entry: str,
+ squash: bool,
+) -> None:
+ print("\n" + "=" * 80)
+ print("RELEASE PREPARATION SUMMARY")
+ print("=" * 80)
+ print(f"\nVersion: {current_version}")
+ print(f"Previous version: {previous_version}")
+ print(f"Release branch: release/v{current_version}")
+
+ print("\n" + "-" * 80)
+ print("COMMITS IN THIS RELEASE")
+ print("-" * 80)
+ if commits_summary:
+ print(commits_summary)
+ else:
+ print("No commits found")
+
+ print("\n" + "-" * 80)
+ print("CHANGELOG ENTRY")
+ print("-" * 80)
+ print(changelog_entry)
+
+ print("\n" + "-" * 80)
+ if not squash:
+ print("NEXT STEPS")
+```
+This function is important because it defines how Mistral Vibe Tutorial: Minimal CLI Coding Agent by Mistral implements the patterns covered in this chapter.
-class AgentLoopStateError(AgentLoopError):
- """Raised when agent loop is in an invalid state."""
+### `scripts/prepare_release.py`
+The `main` function in [`scripts/prepare_release.py`](https://github.com/mistralai/mistral-vibe/blob/HEAD/scripts/prepare_release.py) handles a key part of this chapter's functionality:
-class AgentLoopLLMResponseError(AgentLoopError):
- """Raised when LLM response is malformed or missing expected data."""
+```py
+ print(
+ " ✓ Review and update the changelog if needed "
+ "(should be made in the private main branch)"
+ )
+ print("\n" + "=" * 80)
-class TeleportError(AgentLoopError):
- """Raised when teleport to Vibe Nuage fails."""
+def main() -> None:
+ parser = argparse.ArgumentParser(
+ description="Prepare a release branch by cherry-picking from private tags",
+ formatter_class=argparse.RawDescriptionHelpFormatter,
+ )
+ parser.add_argument("version", help="Version to prepare release for (e.g., 1.1.3)")
+ parser.add_argument(
+ "--no-squash",
+ action="store_false",
+ dest="squash",
+ default=True,
+ help="Disable squashing of commits into a single release commit",
+ )
-def _should_raise_rate_limit_error(e: Exception) -> bool:
- return isinstance(e, BackendError) and e.status == HTTPStatus.TOO_MANY_REQUESTS
+ args = parser.parse_args()
+ current_version = args.version
+ squash = args.squash
+ try:
+ # Step 1: Ensure public remote exists
+ ensure_public_remote()
-class AgentLoop:
- def __init__(
- self,
- config: VibeConfig,
+ # Step 2: Fetch all remotes
+ print("Fetching all remotes...")
```
-This class is important because it defines how Mistral Vibe Tutorial: Minimal CLI Coding Agent by Mistral implements the patterns covered in this chapter.
+This function is important because it defines how Mistral Vibe Tutorial: Minimal CLI Coding Agent by Mistral implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[fill_whats_new_message]
- B[main]
- C[ToolExecutionResponse]
- D[ToolDecision]
- E[AgentLoopError]
+ A[get_commits_summary]
+ B[get_changelog_entry]
+ C[print_summary]
+ D[main]
+ E[ToolExecutionResponse]
A --> B
B --> C
C --> D
diff --git a/tutorials/mistral-vibe-tutorial/03-tooling-and-approval-workflow.md b/tutorials/mistral-vibe-tutorial/03-tooling-and-approval-workflow.md
index 5f78c61c..260393bd 100644
--- a/tutorials/mistral-vibe-tutorial/03-tooling-and-approval-workflow.md
+++ b/tutorials/mistral-vibe-tutorial/03-tooling-and-approval-workflow.md
@@ -36,169 +36,167 @@ You now understand how Vibe turns prompts into controlled tool execution loops.
Next: [Chapter 4: Skills and Slash Command Extensions](04-skills-and-slash-command-extensions.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `vibe/core/middleware.py`
+### `vibe/core/types.py`
-The `AutoCompactMiddleware` class in [`vibe/core/middleware.py`](https://github.com/mistralai/mistral-vibe/blob/HEAD/vibe/core/middleware.py) handles a key part of this chapter's functionality:
+The `AgentStats` class in [`vibe/core/types.py`](https://github.com/mistralai/mistral-vibe/blob/HEAD/vibe/core/types.py) handles a key part of this chapter's functionality:
```py
-class AutoCompactMiddleware:
- async def before_turn(self, context: ConversationContext) -> MiddlewareResult:
- threshold = context.config.get_active_model().auto_compact_threshold
- if threshold > 0 and context.stats.context_tokens >= threshold:
- return MiddlewareResult(
- action=MiddlewareAction.COMPACT,
- metadata={
- "old_tokens": context.stats.context_tokens,
- "threshold": threshold,
- },
- )
- return MiddlewareResult()
+class AgentStats(BaseModel):
+ steps: int = 0
+ session_prompt_tokens: int = 0
+ session_completion_tokens: int = 0
+ tool_calls_agreed: int = 0
+ tool_calls_rejected: int = 0
+ tool_calls_failed: int = 0
+ tool_calls_succeeded: int = 0
- def reset(self, reset_reason: ResetReason = ResetReason.STOP) -> None:
- pass
+ context_tokens: int = 0
+ last_turn_prompt_tokens: int = 0
+ last_turn_completion_tokens: int = 0
+ last_turn_duration: float = 0.0
+ tokens_per_second: float = 0.0
-class ContextWarningMiddleware:
- def __init__(self, threshold_percent: float = 0.5) -> None:
- self.threshold_percent = threshold_percent
- self.has_warned = False
+ input_price_per_million: float = 0.0
+ output_price_per_million: float = 0.0
- async def before_turn(self, context: ConversationContext) -> MiddlewareResult:
- if self.has_warned:
- return MiddlewareResult()
+ _listeners: dict[str, Callable[[AgentStats], None]] = PrivateAttr(
+ default_factory=dict
+ )
- max_context = context.config.get_active_model().auto_compact_threshold
- if max_context <= 0:
- return MiddlewareResult()
+ def __setattr__(self, name: str, value: Any) -> None:
+ super().__setattr__(name, value)
+ if name in self._listeners:
+ self._listeners[name](self)
+ def trigger_listeners(self) -> None:
+ for listener in self._listeners.values():
```
This class is important because it defines how Mistral Vibe Tutorial: Minimal CLI Coding Agent by Mistral implements the patterns covered in this chapter.
-### `vibe/core/middleware.py`
+### `vibe/core/types.py`
-The `ContextWarningMiddleware` class in [`vibe/core/middleware.py`](https://github.com/mistralai/mistral-vibe/blob/HEAD/vibe/core/middleware.py) handles a key part of this chapter's functionality:
+The `SessionInfo` class in [`vibe/core/types.py`](https://github.com/mistralai/mistral-vibe/blob/HEAD/vibe/core/types.py) handles a key part of this chapter's functionality:
```py
-class ContextWarningMiddleware:
- def __init__(self, threshold_percent: float = 0.5) -> None:
- self.threshold_percent = threshold_percent
- self.has_warned = False
-
- async def before_turn(self, context: ConversationContext) -> MiddlewareResult:
- if self.has_warned:
- return MiddlewareResult()
+class SessionInfo(BaseModel):
+ session_id: str
+ start_time: str
+ message_count: int
+ stats: AgentStats
+ save_dir: str
- max_context = context.config.get_active_model().auto_compact_threshold
- if max_context <= 0:
- return MiddlewareResult()
- if context.stats.context_tokens >= max_context * self.threshold_percent:
- self.has_warned = True
+class SessionMetadata(BaseModel):
+ session_id: str
+ start_time: str
+ end_time: str | None
+ git_commit: str | None
+ git_branch: str | None
+ environment: dict[str, str | None]
+ username: str
- percentage_used = (context.stats.context_tokens / max_context) * 100
- warning_msg = f"<{VIBE_WARNING_TAG}>You have used {percentage_used:.0f}% of your total context ({context.stats.context_tokens:,}/{max_context:,} tokens)</{VIBE_WARNING_TAG}>"
- return MiddlewareResult(
- action=MiddlewareAction.INJECT_MESSAGE, message=warning_msg
- )
+class ClientMetadata(BaseModel):
+ name: str
+ version: str
- return MiddlewareResult()
- def reset(self, reset_reason: ResetReason = ResetReason.STOP) -> None:
- self.has_warned = False
+class EntrypointMetadata(BaseModel):
+ agent_entrypoint: Literal["cli", "acp", "programmatic"]
+ agent_version: str
+ client_name: str
+ client_version: str
-def make_plan_agent_reminder(plan_file_path: str) -> str:
```
This class is important because it defines how Mistral Vibe Tutorial: Minimal CLI Coding Agent by Mistral implements the patterns covered in this chapter.
-### `vibe/core/middleware.py`
+### `vibe/core/types.py`
-The `ReadOnlyAgentMiddleware` class in [`vibe/core/middleware.py`](https://github.com/mistralai/mistral-vibe/blob/HEAD/vibe/core/middleware.py) handles a key part of this chapter's functionality:
+The `SessionMetadata` class in [`vibe/core/types.py`](https://github.com/mistralai/mistral-vibe/blob/HEAD/vibe/core/types.py) handles a key part of this chapter's functionality:
```py
-class ReadOnlyAgentMiddleware:
- def __init__(
- self,
- profile_getter: Callable[[], AgentProfile],
- agent_name: str,
- reminder: str | Callable[[], str],
- exit_message: str,
- ) -> None:
- self._profile_getter = profile_getter
- self._agent_name = agent_name
- self._reminder = reminder
- self.exit_message = exit_message
- self._was_active = False
-
- @property
- def reminder(self) -> str:
- return self._reminder() if callable(self._reminder) else self._reminder
-
- def _is_active(self) -> bool:
- return self._profile_getter().name == self._agent_name
-
- async def before_turn(self, context: ConversationContext) -> MiddlewareResult:
- is_active = self._is_active()
- was_active = self._was_active
-
- if was_active and not is_active:
- self._was_active = False
- return MiddlewareResult(
- action=MiddlewareAction.INJECT_MESSAGE, message=self.exit_message
- )
+class SessionMetadata(BaseModel):
+ session_id: str
+ start_time: str
+ end_time: str | None
+ git_commit: str | None
+ git_branch: str | None
+ environment: dict[str, str | None]
+ username: str
+
+
+class ClientMetadata(BaseModel):
+ name: str
+ version: str
+
+
+class EntrypointMetadata(BaseModel):
+ agent_entrypoint: Literal["cli", "acp", "programmatic"]
+ agent_version: str
+ client_name: str
+ client_version: str
+
+
+StrToolChoice = Literal["auto", "none", "any", "required"]
+
+
+class AvailableFunction(BaseModel):
+ name: str
+ description: str
+ parameters: dict[str, Any]
+
```
This class is important because it defines how Mistral Vibe Tutorial: Minimal CLI Coding Agent by Mistral implements the patterns covered in this chapter.
-### `vibe/core/middleware.py`
+### `vibe/core/types.py`
-The `MiddlewarePipeline` class in [`vibe/core/middleware.py`](https://github.com/mistralai/mistral-vibe/blob/HEAD/vibe/core/middleware.py) handles a key part of this chapter's functionality:
+The `ClientMetadata` class in [`vibe/core/types.py`](https://github.com/mistralai/mistral-vibe/blob/HEAD/vibe/core/types.py) handles a key part of this chapter's functionality:
```py
-class MiddlewarePipeline:
- def __init__(self) -> None:
- self.middlewares: list[ConversationMiddleware] = []
+class ClientMetadata(BaseModel):
+ name: str
+ version: str
+
+
+class EntrypointMetadata(BaseModel):
+ agent_entrypoint: Literal["cli", "acp", "programmatic"]
+ agent_version: str
+ client_name: str
+ client_version: str
+
+
+StrToolChoice = Literal["auto", "none", "any", "required"]
+
- def add(self, middleware: ConversationMiddleware) -> MiddlewarePipeline:
- self.middlewares.append(middleware)
- return self
+class AvailableFunction(BaseModel):
+ name: str
+ description: str
+ parameters: dict[str, Any]
- def clear(self) -> None:
- self.middlewares.clear()
- def reset(self, reset_reason: ResetReason = ResetReason.STOP) -> None:
- for mw in self.middlewares:
- mw.reset(reset_reason)
+class AvailableTool(BaseModel):
+ type: Literal["function"] = "function"
+ function: AvailableFunction
- async def run_before_turn(self, context: ConversationContext) -> MiddlewareResult:
- messages_to_inject = []
- for mw in self.middlewares:
- result = await mw.before_turn(context)
- if result.action == MiddlewareAction.INJECT_MESSAGE and result.message:
- messages_to_inject.append(result.message)
- elif result.action in {MiddlewareAction.STOP, MiddlewareAction.COMPACT}:
- return result
- if messages_to_inject:
- combined_message = "\n\n".join(messages_to_inject)
- return MiddlewareResult(
- action=MiddlewareAction.INJECT_MESSAGE, message=combined_message
- )
+class FunctionCall(BaseModel):
+ name: str | None = None
+ arguments: str | None = None
```
@@ -209,11 +207,11 @@ This class is important because it defines how Mistral Vibe Tutorial: Minimal CL
```mermaid
flowchart TD
- A[AutoCompactMiddleware]
- B[ContextWarningMiddleware]
- C[ReadOnlyAgentMiddleware]
- D[MiddlewarePipeline]
- E[make_plan_agent_reminder]
+ A[AgentStats]
+ B[SessionInfo]
+ C[SessionMetadata]
+ D[ClientMetadata]
+ E[EntrypointMetadata]
A --> B
B --> C
C --> D
diff --git a/tutorials/mistral-vibe-tutorial/04-skills-and-slash-command-extensions.md b/tutorials/mistral-vibe-tutorial/04-skills-and-slash-command-extensions.md
index 62762818..7b4f072c 100644
--- a/tutorials/mistral-vibe-tutorial/04-skills-and-slash-command-extensions.md
+++ b/tutorials/mistral-vibe-tutorial/04-skills-and-slash-command-extensions.md
@@ -36,182 +36,182 @@ You now have a strategy for turning ad hoc prompt patterns into reusable Vibe sk
Next: [Chapter 5: Subagents and Task Delegation](05-subagents-and-task-delegation.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `vibe/acp/utils.py`
+### `vibe/core/types.py`
-The `import` interface in [`vibe/acp/utils.py`](https://github.com/mistralai/mistral-vibe/blob/HEAD/vibe/acp/utils.py) handles a key part of this chapter's functionality:
+The `ReasoningEvent` class in [`vibe/core/types.py`](https://github.com/mistralai/mistral-vibe/blob/HEAD/vibe/core/types.py) handles a key part of this chapter's functionality:
```py
-from __future__ import annotations
-
-from enum import StrEnum
-from typing import TYPE_CHECKING, Literal, cast
-
-from acp.schema import (
- AgentMessageChunk,
- AgentThoughtChunk,
- ContentToolCallContent,
- ModelInfo,
- PermissionOption,
- SessionConfigOption,
- SessionConfigOptionSelect,
- SessionConfigSelectOption,
- SessionMode,
- SessionModelState,
- SessionModeState,
- TextContentBlock,
- ToolCallProgress,
- ToolCallStart,
- UserMessageChunk,
-)
-
-from vibe.core.agents.models import AgentProfile, AgentType
-from vibe.core.proxy_setup import SUPPORTED_PROXY_VARS, get_current_proxy_settings
-from vibe.core.types import CompactEndEvent, CompactStartEvent, LLMMessage
-from vibe.core.utils import compact_reduction_display
-
-if TYPE_CHECKING:
- from vibe.core.config import ModelConfig
+
+
+class ReasoningEvent(BaseEvent):
+ content: str
+ message_id: str | None = None
+
+
+class ToolCallEvent(BaseEvent):
+ tool_call_id: str
+ tool_name: str
+ tool_class: type[BaseTool]
+ tool_call_index: int | None = None
+ args: BaseModel | None = None
+
+
+class ToolResultEvent(BaseEvent):
+ tool_name: str
+ tool_class: type[BaseTool] | None
+ result: BaseModel | None = None
+ error: str | None = None
+ skipped: bool = False
+ skip_reason: str | None = None
+ cancelled: bool = False
+ duration: float | None = None
+ tool_call_id: str
+
+
+class ToolStreamEvent(BaseEvent):
+ tool_name: str
+ message: str
+ tool_call_id: str
+
```
-This interface is important because it defines how Mistral Vibe Tutorial: Minimal CLI Coding Agent by Mistral implements the patterns covered in this chapter.
+This class is important because it defines how Mistral Vibe Tutorial: Minimal CLI Coding Agent by Mistral implements the patterns covered in this chapter.
-### `vibe/core/system_prompt.py`
+### `vibe/core/types.py`
-The `ProjectContextProvider` class in [`vibe/core/system_prompt.py`](https://github.com/mistralai/mistral-vibe/blob/HEAD/vibe/core/system_prompt.py) handles a key part of this chapter's functionality:
+The `ToolCallEvent` class in [`vibe/core/types.py`](https://github.com/mistralai/mistral-vibe/blob/HEAD/vibe/core/types.py) handles a key part of this chapter's functionality:
```py
-class ProjectContextProvider:
- def __init__(
- self, config: ProjectContextConfig, root_path: str | Path = "."
- ) -> None:
- self.root_path = Path(root_path).resolve()
- self.config = config
-
- def get_git_status(self) -> str:
- if self.root_path in _git_status_cache:
- return _git_status_cache[self.root_path]
-
- result = self._fetch_git_status()
- _git_status_cache[self.root_path] = result
- return result
-
- def _fetch_git_status(self) -> str:
- try:
- timeout = min(self.config.timeout_seconds, 10.0)
- num_commits = self.config.default_commit_count
-
- current_branch = subprocess.run(
- ["git", "branch", "--show-current"],
- capture_output=True,
- check=True,
- cwd=self.root_path,
- stdin=subprocess.DEVNULL if is_windows() else None,
- text=True,
- timeout=timeout,
- ).stdout.strip()
+class ToolCallEvent(BaseEvent):
+ tool_call_id: str
+ tool_name: str
+ tool_class: type[BaseTool]
+ tool_call_index: int | None = None
+ args: BaseModel | None = None
+
+
+class ToolResultEvent(BaseEvent):
+ tool_name: str
+ tool_class: type[BaseTool] | None
+ result: BaseModel | None = None
+ error: str | None = None
+ skipped: bool = False
+ skip_reason: str | None = None
+ cancelled: bool = False
+ duration: float | None = None
+ tool_call_id: str
+
+
+class ToolStreamEvent(BaseEvent):
+ tool_name: str
+ message: str
+ tool_call_id: str
+
+class WaitingForInputEvent(BaseEvent):
+ task_id: str
+ label: str | None = None
+ predefined_answers: list[str] | None = None
```
This class is important because it defines how Mistral Vibe Tutorial: Minimal CLI Coding Agent by Mistral implements the patterns covered in this chapter.
-### `vibe/core/system_prompt.py`
+### `vibe/core/types.py`
-The `in` class in [`vibe/core/system_prompt.py`](https://github.com/mistralai/mistral-vibe/blob/HEAD/vibe/core/system_prompt.py) handles a key part of this chapter's functionality:
+The `ToolResultEvent` class in [`vibe/core/types.py`](https://github.com/mistralai/mistral-vibe/blob/HEAD/vibe/core/types.py) handles a key part of this chapter's functionality:
```py
-import os
-from pathlib import Path
-from string import Template
-import subprocess
-import sys
-from typing import TYPE_CHECKING
-
-from vibe.core.config.harness_files import get_harness_files_manager
-from vibe.core.paths import VIBE_HOME
-from vibe.core.prompts import UtilityPrompt
-from vibe.core.utils import is_dangerous_directory, is_windows
-
-if TYPE_CHECKING:
- from vibe.core.agents import AgentManager
- from vibe.core.config import ProjectContextConfig, VibeConfig
- from vibe.core.skills.manager import SkillManager
- from vibe.core.tools.manager import ToolManager
-
-_git_status_cache: dict[Path, str] = {}
-
-
-class ProjectContextProvider:
- def __init__(
- self, config: ProjectContextConfig, root_path: str | Path = "."
- ) -> None:
- self.root_path = Path(root_path).resolve()
- self.config = config
-
- def get_git_status(self) -> str:
- if self.root_path in _git_status_cache:
- return _git_status_cache[self.root_path]
+
+class ToolResultEvent(BaseEvent):
+ tool_name: str
+ tool_class: type[BaseTool] | None
+ result: BaseModel | None = None
+ error: str | None = None
+ skipped: bool = False
+ skip_reason: str | None = None
+ cancelled: bool = False
+ duration: float | None = None
+ tool_call_id: str
+
+
+class ToolStreamEvent(BaseEvent):
+ tool_name: str
+ message: str
+ tool_call_id: str
+
+
+class WaitingForInputEvent(BaseEvent):
+ task_id: str
+ label: str | None = None
+ predefined_answers: list[str] | None = None
+
+
+class CompactStartEvent(BaseEvent):
+ current_context_tokens: int
+ threshold: int
+ # WORKAROUND: Using tool_call to communicate compact events to the client.
+ # This should be revisited when the ACP protocol defines how compact events
+ # should be represented.
```
This class is important because it defines how Mistral Vibe Tutorial: Minimal CLI Coding Agent by Mistral implements the patterns covered in this chapter.
-### `vibe/core/system_prompt.py`
+### `vibe/core/types.py`
-The `get_universal_system_prompt` function in [`vibe/core/system_prompt.py`](https://github.com/mistralai/mistral-vibe/blob/HEAD/vibe/core/system_prompt.py) handles a key part of this chapter's functionality:
+The `ToolStreamEvent` class in [`vibe/core/types.py`](https://github.com/mistralai/mistral-vibe/blob/HEAD/vibe/core/types.py) handles a key part of this chapter's functionality:
```py
-def get_universal_system_prompt(
- tool_manager: ToolManager,
- config: VibeConfig,
- skill_manager: SkillManager,
- agent_manager: AgentManager,
-) -> str:
- sections = [config.system_prompt]
-
- if config.include_commit_signature:
- sections.append(_add_commit_signature())
-
- if config.include_model_info:
- sections.append(f"Your model name is: `{config.active_model}`")
-
- if config.include_prompt_detail:
- sections.append(_get_os_system_prompt())
- tool_prompts = []
- for tool_class in tool_manager.available_tools.values():
- if prompt := tool_class.get_tool_prompt():
- tool_prompts.append(prompt)
- if tool_prompts:
- sections.append("\n---\n".join(tool_prompts))
-
- skills_section = _get_available_skills_section(skill_manager)
- if skills_section:
- sections.append(skills_section)
-
- subagents_section = _get_available_subagents_section(agent_manager)
- if subagents_section:
- sections.append(subagents_section)
+class ToolStreamEvent(BaseEvent):
+ tool_name: str
+ message: str
+ tool_call_id: str
+
+
+class WaitingForInputEvent(BaseEvent):
+ task_id: str
+ label: str | None = None
+ predefined_answers: list[str] | None = None
+
+
+class CompactStartEvent(BaseEvent):
+ current_context_tokens: int
+ threshold: int
+ # WORKAROUND: Using tool_call to communicate compact events to the client.
+ # This should be revisited when the ACP protocol defines how compact events
+ # should be represented.
+ # [RFD](https://agentclientprotocol.com/rfds/session-usage)
+ tool_call_id: str
+
+
+class CompactEndEvent(BaseEvent):
+ old_context_tokens: int
+ new_context_tokens: int
+ summary_length: int
+ # WORKAROUND: Using tool_call to communicate compact events to the client.
+ # This should be revisited when the ACP protocol defines how compact events
+ # should be represented.
+ # [RFD](https://agentclientprotocol.com/rfds/session-usage)
```
-This function is important because it defines how Mistral Vibe Tutorial: Minimal CLI Coding Agent by Mistral implements the patterns covered in this chapter.
+This class is important because it defines how Mistral Vibe Tutorial: Minimal CLI Coding Agent by Mistral implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[import]
- B[ProjectContextProvider]
- C[in]
- D[get_universal_system_prompt]
- E[TaggedText]
+ A[ReasoningEvent]
+ B[ToolCallEvent]
+ C[ToolResultEvent]
+ D[ToolStreamEvent]
+ E[WaitingForInputEvent]
A --> B
B --> C
C --> D
diff --git a/tutorials/mistral-vibe-tutorial/05-subagents-and-task-delegation.md b/tutorials/mistral-vibe-tutorial/05-subagents-and-task-delegation.md
index c1818574..e74d1f22 100644
--- a/tutorials/mistral-vibe-tutorial/05-subagents-and-task-delegation.md
+++ b/tutorials/mistral-vibe-tutorial/05-subagents-and-task-delegation.md
@@ -35,184 +35,169 @@ You now know how to use subagents to scale complex coding tasks.
Next: [Chapter 6: Programmatic and Non-Interactive Modes](06-programmatic-and-non-interactive-modes.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `vibe/core/types.py`
+### `vibe/cli/cli.py`
-The `AgentStats` class in [`vibe/core/types.py`](https://github.com/mistralai/mistral-vibe/blob/HEAD/vibe/core/types.py) handles a key part of this chapter's functionality:
+The `run_cli` function in [`vibe/cli/cli.py`](https://github.com/mistralai/mistral-vibe/blob/HEAD/vibe/cli/cli.py) handles a key part of this chapter's functionality:
```py
-class AgentStats(BaseModel):
- steps: int = 0
- session_prompt_tokens: int = 0
- session_completion_tokens: int = 0
- tool_calls_agreed: int = 0
- tool_calls_rejected: int = 0
- tool_calls_failed: int = 0
- tool_calls_succeeded: int = 0
-
- context_tokens: int = 0
-
- last_turn_prompt_tokens: int = 0
- last_turn_completion_tokens: int = 0
- last_turn_duration: float = 0.0
- tokens_per_second: float = 0.0
-
- input_price_per_million: float = 0.0
- output_price_per_million: float = 0.0
-
- _listeners: dict[str, Callable[[AgentStats], None]] = PrivateAttr(
- default_factory=dict
- )
-
- def __setattr__(self, name: str, value: Any) -> None:
- super().__setattr__(name, value)
- if name in self._listeners:
- self._listeners[name](self)
-
- def trigger_listeners(self) -> None:
- for listener in self._listeners.values():
+def run_cli(args: argparse.Namespace) -> None:
+ load_dotenv_values()
+ bootstrap_config_files()
+
+ if args.setup:
+ run_onboarding()
+ sys.exit(0)
+
+ try:
+ initial_agent_name = get_initial_agent_name(args)
+ config = load_config_or_exit()
+ setup_tracing(config)
+
+ if args.enabled_tools:
+ config.enabled_tools = args.enabled_tools
+
+ loaded_session = load_session(args, config)
+
+ stdin_prompt = get_prompt_from_stdin()
+ if args.prompt is not None:
+ config.disabled_tools = [*config.disabled_tools, "ask_user_question"]
+ programmatic_prompt = args.prompt or stdin_prompt
+ if not programmatic_prompt:
+ print(
+ "Error: No prompt provided for programmatic mode", file=sys.stderr
+ )
+ sys.exit(1)
+ output_format = OutputFormat(
+ args.output if hasattr(args, "output") else "text"
+ )
```
-This class is important because it defines how Mistral Vibe Tutorial: Minimal CLI Coding Agent by Mistral implements the patterns covered in this chapter.
+This function is important because it defines how Mistral Vibe Tutorial: Minimal CLI Coding Agent by Mistral implements the patterns covered in this chapter.
-### `vibe/core/types.py`
+### `vibe/acp/acp_agent_loop.py`
-The `SessionInfo` class in [`vibe/core/types.py`](https://github.com/mistralai/mistral-vibe/blob/HEAD/vibe/core/types.py) handles a key part of this chapter's functionality:
+The `AcpSessionLoop` class in [`vibe/acp/acp_agent_loop.py`](https://github.com/mistralai/mistral-vibe/blob/HEAD/vibe/acp/acp_agent_loop.py) handles a key part of this chapter's functionality:
```py
-class SessionInfo(BaseModel):
- session_id: str
- start_time: str
- message_count: int
- stats: AgentStats
- save_dir: str
-
-
-class SessionMetadata(BaseModel):
- session_id: str
- start_time: str
- end_time: str | None
- git_commit: str | None
- git_branch: str | None
- environment: dict[str, str | None]
- username: str
-
-
-class ClientMetadata(BaseModel):
- name: str
- version: str
-
-
-class EntrypointMetadata(BaseModel):
- agent_entrypoint: Literal["cli", "acp", "programmatic"]
- agent_version: str
- client_name: str
- client_version: str
-
-
+class AcpSessionLoop(BaseModel):
+ model_config = ConfigDict(arbitrary_types_allowed=True)
+ id: str
+ agent_loop: AgentLoop
+ task: asyncio.Task[None] | None = None
+
+
+class VibeAcpAgentLoop(AcpAgent):
+ client: Client
+
+ def __init__(self) -> None:
+ self.sessions: dict[str, AcpSessionLoop] = {}
+ self.client_capabilities: ClientCapabilities | None = None
+ self.client_info: Implementation | None = None
+
+ @override
+ async def initialize(
+ self,
+ protocol_version: int,
+ client_capabilities: ClientCapabilities | None = None,
+ client_info: Implementation | None = None,
+ **kwargs: Any,
+ ) -> InitializeResponse:
+ self.client_capabilities = client_capabilities
+ self.client_info = client_info
+
+ # The ACP Agent process can be launched in 3 different ways, depending on installation
+ # - dev mode: `uv run vibe-acp`, ran from the project root
+ # - uv tool install: `vibe-acp`, similar to dev mode, but uv takes care of path resolution
+ # - bundled binary: `./vibe-acp` from binary location
```
This class is important because it defines how Mistral Vibe Tutorial: Minimal CLI Coding Agent by Mistral implements the patterns covered in this chapter.
-### `vibe/core/types.py`
+### `vibe/acp/acp_agent_loop.py`
-The `SessionMetadata` class in [`vibe/core/types.py`](https://github.com/mistralai/mistral-vibe/blob/HEAD/vibe/core/types.py) handles a key part of this chapter's functionality:
+The `VibeAcpAgentLoop` class in [`vibe/acp/acp_agent_loop.py`](https://github.com/mistralai/mistral-vibe/blob/HEAD/vibe/acp/acp_agent_loop.py) handles a key part of this chapter's functionality:
```py
-class SessionMetadata(BaseModel):
- session_id: str
- start_time: str
- end_time: str | None
- git_commit: str | None
- git_branch: str | None
- environment: dict[str, str | None]
- username: str
-
-
-class ClientMetadata(BaseModel):
- name: str
- version: str
-
-
-class EntrypointMetadata(BaseModel):
- agent_entrypoint: Literal["cli", "acp", "programmatic"]
- agent_version: str
- client_name: str
- client_version: str
-
-
-StrToolChoice = Literal["auto", "none", "any", "required"]
-
-
-class AvailableFunction(BaseModel):
- name: str
- description: str
- parameters: dict[str, Any]
-
+class VibeAcpAgentLoop(AcpAgent):
+ client: Client
+
+ def __init__(self) -> None:
+ self.sessions: dict[str, AcpSessionLoop] = {}
+ self.client_capabilities: ClientCapabilities | None = None
+ self.client_info: Implementation | None = None
+
+ @override
+ async def initialize(
+ self,
+ protocol_version: int,
+ client_capabilities: ClientCapabilities | None = None,
+ client_info: Implementation | None = None,
+ **kwargs: Any,
+ ) -> InitializeResponse:
+ self.client_capabilities = client_capabilities
+ self.client_info = client_info
+
+ # The ACP Agent process can be launched in 3 different ways, depending on installation
+ # - dev mode: `uv run vibe-acp`, ran from the project root
+ # - uv tool install: `vibe-acp`, similar to dev mode, but uv takes care of path resolution
+ # - bundled binary: `./vibe-acp` from binary location
+ # The 2 first modes are working similarly, under the hood uv runs `/some/python /my/entrypoint.py``
+ # The last mode is quite different as our bundler also includes the python install.
+ # So sys.executable is already /path/to/binary/vibe-acp.
+ # For this reason, we make a distinction in the way we call the setup command
+ command = sys.executable
+ if "python" not in Path(command).name:
+ # It's the case for bundled binaries, we don't need any other arguments
```
This class is important because it defines how Mistral Vibe Tutorial: Minimal CLI Coding Agent by Mistral implements the patterns covered in this chapter.
-### `vibe/core/types.py`
+### `vibe/acp/acp_agent_loop.py`
-The `ClientMetadata` class in [`vibe/core/types.py`](https://github.com/mistralai/mistral-vibe/blob/HEAD/vibe/core/types.py) handles a key part of this chapter's functionality:
+The `run_acp_server` function in [`vibe/acp/acp_agent_loop.py`](https://github.com/mistralai/mistral-vibe/blob/HEAD/vibe/acp/acp_agent_loop.py) handles a key part of this chapter's functionality:
```py
-class ClientMetadata(BaseModel):
- name: str
- version: str
-
-
-class EntrypointMetadata(BaseModel):
- agent_entrypoint: Literal["cli", "acp", "programmatic"]
- agent_version: str
- client_name: str
- client_version: str
-
-
-StrToolChoice = Literal["auto", "none", "any", "required"]
-
-
-class AvailableFunction(BaseModel):
- name: str
- description: str
- parameters: dict[str, Any]
-
-
-class AvailableTool(BaseModel):
- type: Literal["function"] = "function"
- function: AvailableFunction
-
-
-class FunctionCall(BaseModel):
- name: str | None = None
- arguments: str | None = None
+def run_acp_server() -> None:
+ try:
+ asyncio.run(
+ run_agent(
+ agent=VibeAcpAgentLoop(),
+ use_unstable_protocol=True,
+ observers=[acp_message_observer],
+ )
+ )
+ except KeyboardInterrupt:
+ # This is expected when the server is terminated
+ pass
+ except Exception as e:
+ # Log any unexpected errors
+ print(f"ACP Agent Server error: {e}", file=sys.stderr)
+ raise
```
-This class is important because it defines how Mistral Vibe Tutorial: Minimal CLI Coding Agent by Mistral implements the patterns covered in this chapter.
+This function is important because it defines how Mistral Vibe Tutorial: Minimal CLI Coding Agent by Mistral implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[AgentStats]
- B[SessionInfo]
- C[SessionMetadata]
- D[ClientMetadata]
- E[EntrypointMetadata]
+ A[run_cli]
+ B[AcpSessionLoop]
+ C[VibeAcpAgentLoop]
+ D[run_acp_server]
+ E[from]
A --> B
B --> C
C --> D
diff --git a/tutorials/mistral-vibe-tutorial/06-programmatic-and-non-interactive-modes.md b/tutorials/mistral-vibe-tutorial/06-programmatic-and-non-interactive-modes.md
index 03677d6c..ab0ef2d1 100644
--- a/tutorials/mistral-vibe-tutorial/06-programmatic-and-non-interactive-modes.md
+++ b/tutorials/mistral-vibe-tutorial/06-programmatic-and-non-interactive-modes.md
@@ -35,184 +35,182 @@ You now understand how to use Vibe for script-friendly and CI-ready tasks.
Next: [Chapter 7: ACP and Editor Integrations](07-acp-and-editor-integrations.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `vibe/core/types.py`
+### `vibe/acp/utils.py`
-The `ToolCallEvent` class in [`vibe/core/types.py`](https://github.com/mistralai/mistral-vibe/blob/HEAD/vibe/core/types.py) handles a key part of this chapter's functionality:
+The `get_proxy_help_text` function in [`vibe/acp/utils.py`](https://github.com/mistralai/mistral-vibe/blob/HEAD/vibe/acp/utils.py) handles a key part of this chapter's functionality:
```py
-class ToolCallEvent(BaseEvent):
- tool_call_id: str
- tool_name: str
- tool_class: type[BaseTool]
- tool_call_index: int | None = None
- args: BaseModel | None = None
-
-
-class ToolResultEvent(BaseEvent):
- tool_name: str
- tool_class: type[BaseTool] | None
- result: BaseModel | None = None
- error: str | None = None
- skipped: bool = False
- skip_reason: str | None = None
- cancelled: bool = False
- duration: float | None = None
- tool_call_id: str
-
-
-class ToolStreamEvent(BaseEvent):
- tool_name: str
- message: str
- tool_call_id: str
-
-
-class CompactStartEvent(BaseEvent):
- current_context_tokens: int
- threshold: int
- # WORKAROUND: Using tool_call to communicate compact events to the client.
+def get_proxy_help_text() -> str:
+ lines = [
+ "## Proxy Configuration",
+ "",
+ "Configure proxy and SSL settings for HTTP requests.",
+ "",
+ "### Usage:",
+ "- `/proxy-setup` - Show this help and current settings",
+ "- `/proxy-setup KEY value` - Set an environment variable",
+ "- `/proxy-setup KEY` - Remove an environment variable",
+ "",
+ "### Supported Variables:",
+ ]
+
+ for key, description in SUPPORTED_PROXY_VARS.items():
+ lines.append(f"- `{key}`: {description}")
+
+ lines.extend(["", "### Current Settings:"])
+
+ current = get_current_proxy_settings()
+ any_set = False
+ for key, value in current.items():
+ if value:
+ lines.append(f"- `{key}={value}`")
+ any_set = True
+
+ if not any_set:
+ lines.append("- (none configured)")
+
+ return "\n".join(lines)
```
-This class is important because it defines how Mistral Vibe Tutorial: Minimal CLI Coding Agent by Mistral implements the patterns covered in this chapter.
+This function is important because it defines how Mistral Vibe Tutorial: Minimal CLI Coding Agent by Mistral implements the patterns covered in this chapter.
-### `vibe/core/types.py`
+### `vibe/acp/utils.py`
-The `ToolResultEvent` class in [`vibe/core/types.py`](https://github.com/mistralai/mistral-vibe/blob/HEAD/vibe/core/types.py) handles a key part of this chapter's functionality:
+The `create_user_message_replay` function in [`vibe/acp/utils.py`](https://github.com/mistralai/mistral-vibe/blob/HEAD/vibe/acp/utils.py) handles a key part of this chapter's functionality:
```py
-class ToolResultEvent(BaseEvent):
- tool_name: str
- tool_class: type[BaseTool] | None
- result: BaseModel | None = None
- error: str | None = None
- skipped: bool = False
- skip_reason: str | None = None
- cancelled: bool = False
- duration: float | None = None
- tool_call_id: str
+def create_user_message_replay(msg: LLMMessage) -> UserMessageChunk:
+ content = msg.content if isinstance(msg.content, str) else ""
+ return UserMessageChunk(
+ session_update="user_message_chunk",
+ content=TextContentBlock(type="text", text=content),
+ message_id=msg.message_id,
+ )
-class ToolStreamEvent(BaseEvent):
- tool_name: str
- message: str
- tool_call_id: str
+def create_assistant_message_replay(msg: LLMMessage) -> AgentMessageChunk | None:
+ content = msg.content if isinstance(msg.content, str) else ""
+ if not content:
+ return None
+ return AgentMessageChunk(
+ session_update="agent_message_chunk",
+ content=TextContentBlock(type="text", text=content),
+ message_id=msg.message_id,
+ )
-class CompactStartEvent(BaseEvent):
- current_context_tokens: int
- threshold: int
- # WORKAROUND: Using tool_call to communicate compact events to the client.
- # This should be revisited when the ACP protocol defines how compact events
- # should be represented.
- # [RFD](https://agentclientprotocol.com/rfds/session-usage)
- tool_call_id: str
+def create_reasoning_replay(msg: LLMMessage) -> AgentThoughtChunk | None:
+ if not isinstance(msg.reasoning_content, str) or not msg.reasoning_content:
+ return None
-class CompactEndEvent(BaseEvent):
- old_context_tokens: int
+ return AgentThoughtChunk(
+ session_update="agent_thought_chunk",
+ content=TextContentBlock(type="text", text=msg.reasoning_content),
+ message_id=msg.reasoning_message_id,
+ )
```
-This class is important because it defines how Mistral Vibe Tutorial: Minimal CLI Coding Agent by Mistral implements the patterns covered in this chapter.
+This function is important because it defines how Mistral Vibe Tutorial: Minimal CLI Coding Agent by Mistral implements the patterns covered in this chapter.
-### `vibe/core/types.py`
+### `vibe/acp/utils.py`
-The `ToolStreamEvent` class in [`vibe/core/types.py`](https://github.com/mistralai/mistral-vibe/blob/HEAD/vibe/core/types.py) handles a key part of this chapter's functionality:
+The `create_assistant_message_replay` function in [`vibe/acp/utils.py`](https://github.com/mistralai/mistral-vibe/blob/HEAD/vibe/acp/utils.py) handles a key part of this chapter's functionality:
```py
-class ToolStreamEvent(BaseEvent):
- tool_name: str
- message: str
- tool_call_id: str
+def create_assistant_message_replay(msg: LLMMessage) -> AgentMessageChunk | None:
+ content = msg.content if isinstance(msg.content, str) else ""
+ if not content:
+ return None
+ return AgentMessageChunk(
+ session_update="agent_message_chunk",
+ content=TextContentBlock(type="text", text=content),
+ message_id=msg.message_id,
+ )
-class CompactStartEvent(BaseEvent):
- current_context_tokens: int
- threshold: int
- # WORKAROUND: Using tool_call to communicate compact events to the client.
- # This should be revisited when the ACP protocol defines how compact events
- # should be represented.
- # [RFD](https://agentclientprotocol.com/rfds/session-usage)
- tool_call_id: str
+def create_reasoning_replay(msg: LLMMessage) -> AgentThoughtChunk | None:
+ if not isinstance(msg.reasoning_content, str) or not msg.reasoning_content:
+ return None
-class CompactEndEvent(BaseEvent):
- old_context_tokens: int
- new_context_tokens: int
- summary_length: int
- # WORKAROUND: Using tool_call to communicate compact events to the client.
- # This should be revisited when the ACP protocol defines how compact events
- # should be represented.
- # [RFD](https://agentclientprotocol.com/rfds/session-usage)
- tool_call_id: str
+ return AgentThoughtChunk(
+ session_update="agent_thought_chunk",
+ content=TextContentBlock(type="text", text=msg.reasoning_content),
+ message_id=msg.reasoning_message_id,
+ )
-class OutputFormat(StrEnum):
- TEXT = auto()
- JSON = auto()
+def create_tool_call_replay(
+ tool_call_id: str, tool_name: str, arguments: str | None
+) -> ToolCallStart:
+ return ToolCallStart(
+ session_update="tool_call",
+ title=tool_name,
+ tool_call_id=tool_call_id,
```
-This class is important because it defines how Mistral Vibe Tutorial: Minimal CLI Coding Agent by Mistral implements the patterns covered in this chapter.
+This function is important because it defines how Mistral Vibe Tutorial: Minimal CLI Coding Agent by Mistral implements the patterns covered in this chapter.
-### `vibe/core/types.py`
+### `vibe/acp/utils.py`
-The `CompactStartEvent` class in [`vibe/core/types.py`](https://github.com/mistralai/mistral-vibe/blob/HEAD/vibe/core/types.py) handles a key part of this chapter's functionality:
+The `create_reasoning_replay` function in [`vibe/acp/utils.py`](https://github.com/mistralai/mistral-vibe/blob/HEAD/vibe/acp/utils.py) handles a key part of this chapter's functionality:
```py
-class CompactStartEvent(BaseEvent):
- current_context_tokens: int
- threshold: int
- # WORKAROUND: Using tool_call to communicate compact events to the client.
- # This should be revisited when the ACP protocol defines how compact events
- # should be represented.
- # [RFD](https://agentclientprotocol.com/rfds/session-usage)
- tool_call_id: str
+def create_reasoning_replay(msg: LLMMessage) -> AgentThoughtChunk | None:
+ if not isinstance(msg.reasoning_content, str) or not msg.reasoning_content:
+ return None
+ return AgentThoughtChunk(
+ session_update="agent_thought_chunk",
+ content=TextContentBlock(type="text", text=msg.reasoning_content),
+ message_id=msg.reasoning_message_id,
+ )
-class CompactEndEvent(BaseEvent):
- old_context_tokens: int
- new_context_tokens: int
- summary_length: int
- # WORKAROUND: Using tool_call to communicate compact events to the client.
- # This should be revisited when the ACP protocol defines how compact events
- # should be represented.
- # [RFD](https://agentclientprotocol.com/rfds/session-usage)
- tool_call_id: str
+def create_tool_call_replay(
+ tool_call_id: str, tool_name: str, arguments: str | None
+) -> ToolCallStart:
+ return ToolCallStart(
+ session_update="tool_call",
+ title=tool_name,
+ tool_call_id=tool_call_id,
+ kind="other",
+ raw_input=arguments,
+ )
-class OutputFormat(StrEnum):
- TEXT = auto()
- JSON = auto()
- STREAMING = auto()
+def create_tool_result_replay(msg: LLMMessage) -> ToolCallProgress | None:
+ if not msg.tool_call_id:
+ return None
-type ApprovalCallback = Callable[
- [str, BaseModel, str], Awaitable[tuple[ApprovalResponse, str | None]]
-]
+ content = msg.content if isinstance(msg.content, str) else ""
+ return ToolCallProgress(
+ session_update="tool_call_update",
```
-This class is important because it defines how Mistral Vibe Tutorial: Minimal CLI Coding Agent by Mistral implements the patterns covered in this chapter.
+This function is important because it defines how Mistral Vibe Tutorial: Minimal CLI Coding Agent by Mistral implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[ToolCallEvent]
- B[ToolResultEvent]
- C[ToolStreamEvent]
- D[CompactStartEvent]
- E[CompactEndEvent]
+ A[get_proxy_help_text]
+ B[create_user_message_replay]
+ C[create_assistant_message_replay]
+ D[create_reasoning_replay]
+ E[create_tool_call_replay]
A --> B
B --> C
C --> D
diff --git a/tutorials/mistral-vibe-tutorial/07-acp-and-editor-integrations.md b/tutorials/mistral-vibe-tutorial/07-acp-and-editor-integrations.md
index 1aca1967..7c96a1dd 100644
--- a/tutorials/mistral-vibe-tutorial/07-acp-and-editor-integrations.md
+++ b/tutorials/mistral-vibe-tutorial/07-acp-and-editor-integrations.md
@@ -30,184 +30,178 @@ You now have a clear model for connecting Vibe to ACP-capable editor environment
Next: [Chapter 8: Production Operations and Governance](08-production-operations-and-governance.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `vibe/cli/cli.py`
+### `vibe/core/middleware.py`
-The `get_initial_agent_name` function in [`vibe/cli/cli.py`](https://github.com/mistralai/mistral-vibe/blob/HEAD/vibe/cli/cli.py) handles a key part of this chapter's functionality:
+The `MiddlewarePipeline` class in [`vibe/core/middleware.py`](https://github.com/mistralai/mistral-vibe/blob/HEAD/vibe/core/middleware.py) handles a key part of this chapter's functionality:
```py
-def get_initial_agent_name(args: argparse.Namespace) -> str:
- if args.prompt is not None and args.agent == BuiltinAgentName.DEFAULT:
- return BuiltinAgentName.AUTO_APPROVE
- return args.agent
-
-
-def get_prompt_from_stdin() -> str | None:
- if sys.stdin.isatty():
- return None
- try:
- if content := sys.stdin.read().strip():
- sys.stdin = sys.__stdin__ = open("/dev/tty")
- return content
- except KeyboardInterrupt:
- pass
- except OSError:
- return None
-
- return None
-
-
-def load_config_or_exit() -> VibeConfig:
- try:
- return VibeConfig.load()
- except MissingAPIKeyError:
- run_onboarding()
- return VibeConfig.load()
- except MissingPromptFileError as e:
- rprint(f"[yellow]Invalid system prompt id: {e}[/]")
- sys.exit(1)
-```
+class MiddlewarePipeline:
+ def __init__(self) -> None:
+ self.middlewares: list[ConversationMiddleware] = []
-This function is important because it defines how Mistral Vibe Tutorial: Minimal CLI Coding Agent by Mistral implements the patterns covered in this chapter.
+ def add(self, middleware: ConversationMiddleware) -> MiddlewarePipeline:
+ self.middlewares.append(middleware)
+ return self
-### `vibe/cli/cli.py`
+ def clear(self) -> None:
+ self.middlewares.clear()
-The `get_prompt_from_stdin` function in [`vibe/cli/cli.py`](https://github.com/mistralai/mistral-vibe/blob/HEAD/vibe/cli/cli.py) handles a key part of this chapter's functionality:
+ def reset(self, reset_reason: ResetReason = ResetReason.STOP) -> None:
+ for mw in self.middlewares:
+ mw.reset(reset_reason)
-```py
+ async def run_before_turn(self, context: ConversationContext) -> MiddlewareResult:
+ messages_to_inject = []
+ for mw in self.middlewares:
+ result = await mw.before_turn(context)
+ if result.action == MiddlewareAction.INJECT_MESSAGE and result.message:
+ messages_to_inject.append(result.message)
+ elif result.action in {MiddlewareAction.STOP, MiddlewareAction.COMPACT}:
+ return result
+ if messages_to_inject:
+ combined_message = "\n\n".join(messages_to_inject)
+ return MiddlewareResult(
+ action=MiddlewareAction.INJECT_MESSAGE, message=combined_message
+ )
-def get_prompt_from_stdin() -> str | None:
- if sys.stdin.isatty():
- return None
- try:
- if content := sys.stdin.read().strip():
- sys.stdin = sys.__stdin__ = open("/dev/tty")
- return content
- except KeyboardInterrupt:
- pass
- except OSError:
- return None
-
- return None
-
-
-def load_config_or_exit() -> VibeConfig:
- try:
- return VibeConfig.load()
- except MissingAPIKeyError:
- run_onboarding()
- return VibeConfig.load()
- except MissingPromptFileError as e:
- rprint(f"[yellow]Invalid system prompt id: {e}[/]")
- sys.exit(1)
- except ValueError as e:
- rprint(f"[yellow]{e}[/]")
- sys.exit(1)
-
-
-def bootstrap_config_files() -> None:
```
-This function is important because it defines how Mistral Vibe Tutorial: Minimal CLI Coding Agent by Mistral implements the patterns covered in this chapter.
+This class is important because it defines how Mistral Vibe Tutorial: Minimal CLI Coding Agent by Mistral implements the patterns covered in this chapter.
-### `vibe/cli/cli.py`
+### `vibe/core/middleware.py`
-The `load_config_or_exit` function in [`vibe/cli/cli.py`](https://github.com/mistralai/mistral-vibe/blob/HEAD/vibe/cli/cli.py) handles a key part of this chapter's functionality:
+The `make_plan_agent_reminder` function in [`vibe/core/middleware.py`](https://github.com/mistralai/mistral-vibe/blob/HEAD/vibe/core/middleware.py) handles a key part of this chapter's functionality:
```py
-def load_config_or_exit() -> VibeConfig:
- try:
- return VibeConfig.load()
- except MissingAPIKeyError:
- run_onboarding()
- return VibeConfig.load()
- except MissingPromptFileError as e:
- rprint(f"[yellow]Invalid system prompt id: {e}[/]")
- sys.exit(1)
- except ValueError as e:
- rprint(f"[yellow]{e}[/]")
- sys.exit(1)
-
-
-def bootstrap_config_files() -> None:
- mgr = get_harness_files_manager()
- config_file = mgr.user_config_file
- if not config_file.exists():
- try:
- config_file.parent.mkdir(parents=True, exist_ok=True)
- with config_file.open("wb") as f:
- tomli_w.dump(VibeConfig.create_default(), f)
- except Exception as e:
- rprint(f"[yellow]Could not create default config file: {e}[/]")
-
- history_file = HISTORY_FILE.path
- if not history_file.exists():
- try:
- history_file.parent.mkdir(parents=True, exist_ok=True)
- history_file.write_text("Hello Vibe!\n", "utf-8")
+def make_plan_agent_reminder(plan_file_path: str) -> str:
+ return f"""<{VIBE_WARNING_TAG}>Plan mode is active. You MUST NOT make any edits (except to the plan file below), run any non-readonly tools (including changing configs or making commits), or otherwise make any changes to the system. This supersedes any other instructions you have received.
+
+## Plan File Info
+Create or edit your plan at {plan_file_path} using the write_file and search_replace tools.
+Build your plan incrementally by writing to or editing this file.
+This is the only file you are allowed to edit. Make sure to create it early and edit as soon as you internally update your plan.
+
+## Instructions
+1. Research the user's query using read-only tools (grep, read_file, etc.)
+2. If you are unsure about requirements or approach, use the ask_user_question tool to clarify before finalizing your plan
+3. Write your plan to the plan file above
+4. When your plan is complete, call the exit_plan_mode tool to request user approval and switch to implementation mode</{VIBE_WARNING_TAG}>"""
+
+
+PLAN_AGENT_EXIT = f"""<{VIBE_WARNING_TAG}>Plan mode has ended. If you have a plan ready, you can now start executing it. If not, you can now use editing tools and make changes to the system.</{VIBE_WARNING_TAG}>"""
+
+CHAT_AGENT_REMINDER = f"""<{VIBE_WARNING_TAG}>Chat mode is active. The user wants to have a conversation -- ask questions, get explanations, or discuss code and architecture. You MUST NOT make any edits, run any non-readonly tools, or otherwise make any changes to the system. This supersedes any other instructions you have received. Instead, you should:
+1. Answer the user's questions directly and comprehensively
+2. Explain code, concepts, or architecture as requested
+3. Use read-only tools (grep, read_file) to look up relevant code when needed
+4. Focus on being informative and conversational -- your response IS the deliverable, not a precursor to action</{VIBE_WARNING_TAG}>"""
+
+CHAT_AGENT_EXIT = f"""<{VIBE_WARNING_TAG}>Chat mode has ended. You can now use editing tools and make changes to the system.</{VIBE_WARNING_TAG}>"""
+
+
+class ReadOnlyAgentMiddleware:
+ def __init__(
+ self,
+ profile_getter: Callable[[], AgentProfile],
```
This function is important because it defines how Mistral Vibe Tutorial: Minimal CLI Coding Agent by Mistral implements the patterns covered in this chapter.
-### `vibe/cli/cli.py`
+### `vibe/core/middleware.py`
-The `bootstrap_config_files` function in [`vibe/cli/cli.py`](https://github.com/mistralai/mistral-vibe/blob/HEAD/vibe/cli/cli.py) handles a key part of this chapter's functionality:
+The `import` interface in [`vibe/core/middleware.py`](https://github.com/mistralai/mistral-vibe/blob/HEAD/vibe/core/middleware.py) handles a key part of this chapter's functionality:
```py
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from enum import StrEnum, auto
+from typing import TYPE_CHECKING, Any, Protocol
+from vibe.core.agents import AgentProfile
+from vibe.core.utils import VIBE_WARNING_TAG
-def bootstrap_config_files() -> None:
- mgr = get_harness_files_manager()
- config_file = mgr.user_config_file
- if not config_file.exists():
- try:
- config_file.parent.mkdir(parents=True, exist_ok=True)
- with config_file.open("wb") as f:
- tomli_w.dump(VibeConfig.create_default(), f)
- except Exception as e:
- rprint(f"[yellow]Could not create default config file: {e}[/]")
-
- history_file = HISTORY_FILE.path
- if not history_file.exists():
- try:
- history_file.parent.mkdir(parents=True, exist_ok=True)
- history_file.write_text("Hello Vibe!\n", "utf-8")
- except Exception as e:
- rprint(f"[yellow]Could not create history file: {e}[/]")
-
-
-def load_session(
- args: argparse.Namespace, config: VibeConfig
-) -> tuple[list[LLMMessage], Path] | None:
- if not args.continue_session and not args.resume:
- return None
-
- if not config.session_logging.enabled:
- rprint(
- "[red]Session logging is disabled. "
- "Enable it in config to use --continue or --resume[/]"
+if TYPE_CHECKING:
+ from vibe.core.config import VibeConfig
+ from vibe.core.types import AgentStats, MessageList
+
+
+class MiddlewareAction(StrEnum):
+ CONTINUE = auto()
+ STOP = auto()
+ COMPACT = auto()
+ INJECT_MESSAGE = auto()
+
+
+class ResetReason(StrEnum):
+ STOP = auto()
+ COMPACT = auto()
+
+
+@dataclass
+class ConversationContext:
+ messages: MessageList
```
-This function is important because it defines how Mistral Vibe Tutorial: Minimal CLI Coding Agent by Mistral implements the patterns covered in this chapter.
+This interface is important because it defines how Mistral Vibe Tutorial: Minimal CLI Coding Agent by Mistral implements the patterns covered in this chapter.
+
+### `vibe/cli/commands.py`
+
+The `import` class in [`vibe/cli/commands.py`](https://github.com/mistralai/mistral-vibe/blob/HEAD/vibe/cli/commands.py) handles a key part of this chapter's functionality:
+
+```py
+from __future__ import annotations
+
+from dataclasses import dataclass
+import sys
+
+ALT_KEY = "⌥" if sys.platform == "darwin" else "Alt"
+
+
+@dataclass
+class Command:
+ aliases: frozenset[str]
+ description: str
+ handler: str
+ exits: bool = False
+
+
+class CommandRegistry:
+ def __init__(self, excluded_commands: list[str] | None = None) -> None:
+ if excluded_commands is None:
+ excluded_commands = []
+ self.commands = {
+ "help": Command(
+ aliases=frozenset(["/help"]),
+ description="Show help message",
+ handler="_show_help",
+ ),
+ "config": Command(
+ aliases=frozenset(["/config"]),
+ description="Edit config settings",
+ handler="_show_config",
+```
+
+This class is important because it defines how Mistral Vibe Tutorial: Minimal CLI Coding Agent by Mistral implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[get_initial_agent_name]
- B[get_prompt_from_stdin]
- C[load_config_or_exit]
- D[bootstrap_config_files]
- E[load_session]
+ A[MiddlewarePipeline]
+ B[make_plan_agent_reminder]
+ C[import]
+ D[import]
+ E[class]
A --> B
B --> C
C --> D
diff --git a/tutorials/mistral-vibe-tutorial/08-production-operations-and-governance.md b/tutorials/mistral-vibe-tutorial/08-production-operations-and-governance.md
index 2289eafd..29056632 100644
--- a/tutorials/mistral-vibe-tutorial/08-production-operations-and-governance.md
+++ b/tutorials/mistral-vibe-tutorial/08-production-operations-and-governance.md
@@ -30,171 +30,159 @@ Production Vibe usage requires policy around approvals, tool permissions, and up
You now have a practical baseline for responsible team-scale Vibe adoption.
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `vibe/cli/entrypoint.py`
+### `vibe/core/output_formatters.py`
-The `parse_arguments` function in [`vibe/cli/entrypoint.py`](https://github.com/mistralai/mistral-vibe/blob/HEAD/vibe/cli/entrypoint.py) handles a key part of this chapter's functionality:
+The `StreamingJsonOutputFormatter` class in [`vibe/core/output_formatters.py`](https://github.com/mistralai/mistral-vibe/blob/HEAD/vibe/core/output_formatters.py) handles a key part of this chapter's functionality:
```py
-def parse_arguments() -> argparse.Namespace:
- parser = argparse.ArgumentParser(description="Run the Mistral Vibe interactive CLI")
- parser.add_argument(
- "-v", "--version", action="version", version=f"%(prog)s {__version__}"
- )
- parser.add_argument(
- "initial_prompt",
- nargs="?",
- metavar="PROMPT",
- help="Initial prompt to start the interactive session with.",
- )
- parser.add_argument(
- "-p",
- "--prompt",
- nargs="?",
- const="",
- metavar="TEXT",
- help="Run in programmatic mode: send prompt, auto-approve all tools, "
- "output response, and exit.",
- )
- parser.add_argument(
- "--max-turns",
- type=int,
- metavar="N",
- help="Maximum number of assistant turns "
- "(only applies in programmatic mode with -p).",
- )
- parser.add_argument(
- "--max-price",
- type=float,
-```
+class StreamingJsonOutputFormatter(OutputFormatter):
+ def on_message_added(self, message: LLMMessage) -> None:
+ json.dump(message.model_dump(mode="json"), self.stream, ensure_ascii=False)
+ self.stream.write("\n")
+ self.stream.flush()
-This function is important because it defines how Mistral Vibe Tutorial: Minimal CLI Coding Agent by Mistral implements the patterns covered in this chapter.
+ def on_event(self, event: BaseEvent) -> None:
+ pass
-### `vibe/cli/entrypoint.py`
+ def finalize(self) -> str | None:
+ return None
-The `check_and_resolve_trusted_folder` function in [`vibe/cli/entrypoint.py`](https://github.com/mistralai/mistral-vibe/blob/HEAD/vibe/cli/entrypoint.py) handles a key part of this chapter's functionality:
-```py
+def create_formatter(
+ format_type: OutputFormat, stream: TextIO = sys.stdout
+) -> OutputFormatter:
+ formatters = {
+ OutputFormat.TEXT: TextOutputFormatter,
+ OutputFormat.JSON: JsonOutputFormatter,
+ OutputFormat.STREAMING: StreamingJsonOutputFormatter,
+ }
+ formatter_class = formatters.get(format_type, TextOutputFormatter)
+ return formatter_class(stream)
-def check_and_resolve_trusted_folder() -> None:
- try:
- cwd = Path.cwd()
- except FileNotFoundError:
- rprint(
- "[red]Error: Current working directory no longer exists.[/]\n"
- "[yellow]The directory you started vibe from has been deleted. "
- "Please change to an existing directory and try again, "
- "or use --workdir to specify a working directory.[/]"
- )
- sys.exit(1)
+```
+
+This class is important because it defines how Mistral Vibe Tutorial: Minimal CLI Coding Agent by Mistral implements the patterns covered in this chapter.
+
+### `vibe/core/output_formatters.py`
- if not has_trustable_content(cwd) or cwd.resolve() == Path.home().resolve():
- return
+The `create_formatter` function in [`vibe/core/output_formatters.py`](https://github.com/mistralai/mistral-vibe/blob/HEAD/vibe/core/output_formatters.py) handles a key part of this chapter's functionality:
+
+```py
- is_folder_trusted = trusted_folders_manager.is_trusted(cwd)
- if is_folder_trusted is not None:
- return
+def create_formatter(
+ format_type: OutputFormat, stream: TextIO = sys.stdout
+) -> OutputFormatter:
+ formatters = {
+ OutputFormat.TEXT: TextOutputFormatter,
+ OutputFormat.JSON: JsonOutputFormatter,
+ OutputFormat.STREAMING: StreamingJsonOutputFormatter,
+ }
- try:
- is_folder_trusted = ask_trust_folder(cwd)
- except (KeyboardInterrupt, EOFError, TrustDialogQuitException):
- sys.exit(0)
- except Exception as e:
- rprint(f"[yellow]Error showing trust dialog: {e}[/]")
- return
+ formatter_class = formatters.get(format_type, TextOutputFormatter)
+ return formatter_class(stream)
- if is_folder_trusted is True:
- trusted_folders_manager.add_trusted(cwd)
```
This function is important because it defines how Mistral Vibe Tutorial: Minimal CLI Coding Agent by Mistral implements the patterns covered in this chapter.
-### `vibe/cli/entrypoint.py`
+### `vibe/core/programmatic.py`
-The `main` function in [`vibe/cli/entrypoint.py`](https://github.com/mistralai/mistral-vibe/blob/HEAD/vibe/cli/entrypoint.py) handles a key part of this chapter's functionality:
+The `run_programmatic` function in [`vibe/core/programmatic.py`](https://github.com/mistralai/mistral-vibe/blob/HEAD/vibe/core/programmatic.py) handles a key part of this chapter's functionality:
```py
+from vibe.core.utils import ConversationLimitException
+
+__all__ = ["TeleportError", "run_programmatic"]
+
+_DEFAULT_CLIENT_METADATA = ClientMetadata(name="vibe_programmatic", version=__version__)
+
+
+def run_programmatic(
+ config: VibeConfig,
+ prompt: str,
+ max_turns: int | None = None,
+ max_price: float | None = None,
+ output_format: OutputFormat = OutputFormat.TEXT,
+ previous_messages: list[LLMMessage] | None = None,
+ agent_name: str = BuiltinAgentName.AUTO_APPROVE,
+ client_metadata: ClientMetadata = _DEFAULT_CLIENT_METADATA,
+ teleport: bool = False,
+) -> str | None:
+ formatter = create_formatter(output_format)
+
+ agent_loop = AgentLoop(
+ config,
+ agent_name=agent_name,
+ message_observer=formatter.on_message_added,
+ max_turns=max_turns,
+ max_price=max_price,
+ enable_streaming=False,
+ entrypoint_metadata=EntrypointMetadata(
+ agent_entrypoint="programmatic",
+ agent_version=__version__,
+ client_name=client_metadata.name,
+ client_version=client_metadata.version,
+```
+This function is important because it defines how Mistral Vibe Tutorial: Minimal CLI Coding Agent by Mistral implements the patterns covered in this chapter.
-def main() -> None:
- args = parse_arguments()
+### `vibe/acp/exceptions.py`
- if args.workdir:
- workdir = args.workdir.expanduser().resolve()
- if not workdir.is_dir():
- rprint(
- f"[red]Error: --workdir does not exist or is not a directory: {workdir}[/]"
- )
- sys.exit(1)
- os.chdir(workdir)
+The `VibeRequestError` class in [`vibe/acp/exceptions.py`](https://github.com/mistralai/mistral-vibe/blob/HEAD/vibe/acp/exceptions.py) handles a key part of this chapter's functionality:
- is_interactive = args.prompt is None
- if is_interactive:
- check_and_resolve_trusted_folder()
- init_harness_files_manager("user", "project")
+```py
- from vibe.cli.cli import run_cli
- run_cli(args)
+class VibeRequestError(RequestError):
+ code: int
+ def __init__(self, message: str, data: dict[str, Any] | None = None) -> None:
+ super().__init__(self.code, message, data)
-if __name__ == "__main__":
- main()
-```
+class UnauthenticatedError(VibeRequestError):
+ code = UNAUTHENTICATED
-This function is important because it defines how Mistral Vibe Tutorial: Minimal CLI Coding Agent by Mistral implements the patterns covered in this chapter.
+ def __init__(self, detail: str) -> None:
+ super().__init__(message=detail)
-### `vibe/cli/clipboard.py`
+ @classmethod
+ def from_missing_api_key(cls, exc: MissingAPIKeyError) -> UnauthenticatedError:
+ return cls(f"Missing API key for {exc.provider_name} provider.")
-The `copy_selection_to_clipboard` function in [`vibe/cli/clipboard.py`](https://github.com/mistralai/mistral-vibe/blob/HEAD/vibe/cli/clipboard.py) handles a key part of this chapter's functionality:
-```py
+class NotImplementedMethodError(VibeRequestError):
+ code = METHOD_NOT_FOUND
+ def __init__(self, method: str) -> None:
+ super().__init__(
+ message=f"Method not implemented: {method}", data={"method": method}
+ )
-def copy_selection_to_clipboard(app: App, show_toast: bool = True) -> str | None:
- selected_texts = _get_selected_texts(app)
- if not selected_texts:
- return None
- combined_text = "\n".join(selected_texts)
- try:
- _copy_to_clipboard(combined_text)
- if show_toast:
- app.notify(
- f'"{_shorten_preview(selected_texts)}" copied to clipboard',
- severity="information",
- timeout=2,
- markup=False,
- )
- return combined_text
- except Exception:
- app.notify(
- "Failed to copy - clipboard not available", severity="warning", timeout=3
- )
- return None
+class InvalidRequestError(VibeRequestError):
+ code = INVALID_PARAMS
```
-This function is important because it defines how Mistral Vibe Tutorial: Minimal CLI Coding Agent by Mistral implements the patterns covered in this chapter.
+This class is important because it defines how Mistral Vibe Tutorial: Minimal CLI Coding Agent by Mistral implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[parse_arguments]
- B[check_and_resolve_trusted_folder]
- C[main]
- D[copy_selection_to_clipboard]
- E[import]
+ A[StreamingJsonOutputFormatter]
+ B[create_formatter]
+ C[run_programmatic]
+ D[VibeRequestError]
+ E[UnauthenticatedError]
A --> B
B --> C
C --> D
diff --git a/tutorials/n8n-ai-tutorial/01-getting-started.md b/tutorials/n8n-ai-tutorial/01-getting-started.md
index b57171e0..e58780c4 100644
--- a/tutorials/n8n-ai-tutorial/01-getting-started.md
+++ b/tutorials/n8n-ai-tutorial/01-getting-started.md
@@ -13,6 +13,24 @@ Welcome to **Chapter 1: Getting Started with n8n AI**. In this part of **n8n AI
> Install n8n, create your first workflow, and add AI capabilities to your automations.
+## n8n Workflow Architecture
+
+```mermaid
+flowchart LR
+ T[Trigger Node\nWebhook / Schedule / Manual] --> PROC[Processing Nodes\nSet, Code, Function]
+ PROC --> AI[AI Nodes\nOpenAI / Anthropic / Ollama]
+ AI --> LOGIC[Logic Nodes\nIF / Switch / Merge]
+ LOGIC --> OUT[Output Nodes\nSlack / Email / Database / HTTP]
+
+ subgraph n8n Canvas
+ T
+ PROC
+ AI
+ LOGIC
+ OUT
+ end
+```
+
## Overview
n8n is a powerful workflow automation platform that integrates AI capabilities. This chapter covers installation, basic setup, and your first AI-powered workflow.
@@ -485,16 +503,13 @@ When debugging, walk this sequence in order and confirm each stage has explicit
## Source Walkthrough
-Use the following upstream sources to verify implementation details while reading this chapter:
+Key source files in [`n8n-io/n8n`](https://github.com/n8n-io/n8n):
-- [View Repo](https://github.com/n8n-io/n8n)
- Why it matters: authoritative reference on `View Repo` (github.com).
-- [Awesome Code Docs](https://github.com/johnxie/awesome-code-docs)
- Why it matters: authoritative reference on `Awesome Code Docs` (github.com).
+- [`packages/nodes-base/`](https://github.com/n8n-io/n8n/tree/master/packages/nodes-base) -- all built-in node implementations; each node is a TypeScript class with `execute()` method
+- [`packages/@n8n/nodes-langchain/`](https://github.com/n8n-io/n8n/tree/master/packages/%40n8n/nodes-langchain) -- AI/LangChain nodes: OpenAI, Anthropic, Ollama, Agent, Vector Store nodes
+- [`packages/core/src/WorkflowExecute.ts`](https://github.com/n8n-io/n8n/blob/master/packages/core/src/WorkflowExecute.ts) -- workflow execution engine; `runNodeInThisProcess()` dispatches node execution
-Suggested trace strategy:
-- search upstream code for `json` and `nodes` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+Suggested trace: find `WorkflowExecute.processRunExecutionData()` to understand how data flows from one node to the next through the `INodeExecutionData` array.
## Chapter Connections
diff --git a/tutorials/n8n-ai-tutorial/02-ai-nodes.md b/tutorials/n8n-ai-tutorial/02-ai-nodes.md
index 1f6d7872..725a7689 100644
--- a/tutorials/n8n-ai-tutorial/02-ai-nodes.md
+++ b/tutorials/n8n-ai-tutorial/02-ai-nodes.md
@@ -13,6 +13,22 @@ Welcome to **Chapter 2: AI Nodes and LLM Integration**. In this part of **n8n AI
> Configure and use different AI providers, manage credentials, and build multi-model workflows.
+## AI Node Ecosystem
+
+```mermaid
+flowchart TD
+ N8N[n8n AI Nodes] --> CHAT[Chat Model Nodes]
+ N8N --> EMB[Embedding Nodes]
+ N8N --> TOOLS[Tool Nodes]
+
+ CHAT --> OAI[@n8n/n8n-nodes-langchain.openAi\nGPT-4o, GPT-4-turbo]
+ CHAT --> ANT[@n8n/n8n-nodes-langchain.anthropic\nClaude 3.5 Sonnet]
+ CHAT --> OLLAMA[@n8n/n8n-nodes-langchain.lmChatOllama\nLocal models]
+ EMB --> OAIE[OpenAI Embeddings]
+ TOOLS --> WEB[HTTP Request Tool]
+ TOOLS --> CODE[Code Execution Tool]
+```
+
## AI Node Overview
n8n provides dedicated nodes for various AI providers, each with specific capabilities and configuration options.
@@ -648,16 +664,13 @@ When debugging, walk this sequence in order and confirm each stage has explicit
## Source Walkthrough
-Use the following upstream sources to verify implementation details while reading this chapter:
+Key source files in [`n8n-io/n8n`](https://github.com/n8n-io/n8n):
-- [View Repo](https://github.com/n8n-io/n8n)
- Why it matters: authoritative reference on `View Repo` (github.com).
-- [Awesome Code Docs](https://github.com/johnxie/awesome-code-docs)
- Why it matters: authoritative reference on `Awesome Code Docs` (github.com).
+- [`packages/@n8n/nodes-langchain/nodes/llms/LmChatOpenAi/`](https://github.com/n8n-io/n8n/tree/master/packages/%40n8n/nodes-langchain/nodes/llms/LmChatOpenAi) -- OpenAI chat model node; `supplyData()` returns a `ChatOpenAI` LangChain instance
+- [`packages/@n8n/nodes-langchain/nodes/llms/LmChatAnthropic/`](https://github.com/n8n-io/n8n/tree/master/packages/%40n8n/nodes-langchain/nodes/llms/LmChatAnthropic) -- Anthropic Claude node implementation
+- [`packages/@n8n/nodes-langchain/nodes/llms/LmChatOllama/`](https://github.com/n8n-io/n8n/tree/master/packages/%40n8n/nodes-langchain/nodes/llms/LmChatOllama) -- local Ollama chat model node
-Suggested trace strategy:
-- search upstream code for `name` and `json` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+Suggested trace: all LLM nodes implement `INodeType` and expose a `supplyData()` method that returns a LangChain `BaseChatModel`; this is how the Agent node consumes them.
## Chapter Connections
diff --git a/tutorials/n8n-ai-tutorial/03-document-ai.md b/tutorials/n8n-ai-tutorial/03-document-ai.md
index 4730e8e1..a57291d2 100644
--- a/tutorials/n8n-ai-tutorial/03-document-ai.md
+++ b/tutorials/n8n-ai-tutorial/03-document-ai.md
@@ -13,6 +13,17 @@ Welcome to **Chapter 3: Document AI and Content Processing**. In this part of **
> Extract information from PDFs, images, web pages, and documents using AI-powered processing.
+## Document AI Pipeline
+
+```mermaid
+flowchart LR
+ SRC[Source: Email / S3 / URL] --> LOAD[Document Loader\nPDF, HTML, CSV]
+ LOAD --> SPLIT[Text Splitter\nRecursiveCharacterTextSplitter]
+ SPLIT --> AI[AI Node\nExtract / Summarize / Classify]
+ AI --> OUT[Structured Output\nJSON fields]
+ OUT --> STORE[Database / Spreadsheet]
+```
+
## Document Processing Nodes
n8n provides various nodes for processing different document types with AI assistance.
@@ -628,16 +639,13 @@ When debugging, walk this sequence in order and confirm each stage has explicit
## Source Walkthrough
-Use the following upstream sources to verify implementation details while reading this chapter:
+Key source files in [`n8n-io/n8n`](https://github.com/n8n-io/n8n):
-- [View Repo](https://github.com/n8n-io/n8n)
- Why it matters: authoritative reference on `View Repo` (github.com).
-- [Awesome Code Docs](https://github.com/johnxie/awesome-code-docs)
- Why it matters: authoritative reference on `Awesome Code Docs` (github.com).
+- [`packages/@n8n/nodes-langchain/nodes/document_loaders/`](https://github.com/n8n-io/n8n/tree/master/packages/%40n8n/nodes-langchain/nodes/document_loaders) -- document loader nodes: PDF, URL, JSON, CSV, binary data loaders
+- [`packages/@n8n/nodes-langchain/nodes/text_splitters/`](https://github.com/n8n-io/n8n/tree/master/packages/%40n8n/nodes-langchain/nodes/text_splitters) -- text splitter nodes wrapping LangChain's `RecursiveCharacterTextSplitter`, `TokenTextSplitter`
+- [`packages/@n8n/nodes-langchain/nodes/output_parser/`](https://github.com/n8n-io/n8n/tree/master/packages/%40n8n/nodes-langchain/nodes/output_parser) -- structured output parsers for extracting JSON from LLM responses
-Suggested trace strategy:
-- search upstream code for `content` and `json` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+Suggested trace: follow a PDF document loader node's `supplyData()` to see how it returns a LangChain `Document[]` array for downstream vector store ingestion.
## Chapter Connections
diff --git a/tutorials/n8n-ai-tutorial/04-ai-agents.md b/tutorials/n8n-ai-tutorial/04-ai-agents.md
index 13dd38bf..c43af518 100644
--- a/tutorials/n8n-ai-tutorial/04-ai-agents.md
+++ b/tutorials/n8n-ai-tutorial/04-ai-agents.md
@@ -13,6 +13,23 @@ Welcome to **Chapter 4: Building AI Agents with Tools**. In this part of **n8n A
> Create autonomous AI agents that can use tools, make decisions, and perform complex tasks.
+## n8n AI Agent Architecture
+
+```mermaid
+flowchart TD
+ INPUT[User Input / Trigger] --> AGENT[AI Agent Node\n@n8n/n8n-nodes-langchain.agent]
+ AGENT --> LLM[Chat Model\nGPT-4o / Claude]
+ AGENT --> MEMORY[Memory\nWindow Buffer / Postgres]
+ AGENT --> TOOLS[Tool Nodes]
+ TOOLS --> T1[HTTP Request]
+ TOOLS --> T2[Code Tool]
+ TOOLS --> T3[Vector Store Search]
+ TOOLS --> T4[n8n Workflow Tool]
+ LLM --> DECIDE{Tool needed?}
+ DECIDE -->|Yes| TOOLS
+ DECIDE -->|No| RESP[Final Response]
+```
+
## AI Agent Fundamentals
AI agents in n8n can access tools, maintain memory, and make autonomous decisions to accomplish goals.
@@ -584,16 +601,13 @@ When debugging, walk this sequence in order and confirm each stage has explicit
## Source Walkthrough
-Use the following upstream sources to verify implementation details while reading this chapter:
+Key source files in [`n8n-io/n8n`](https://github.com/n8n-io/n8n):
-- [View Repo](https://github.com/n8n-io/n8n)
- Why it matters: authoritative reference on `View Repo` (github.com).
-- [Awesome Code Docs](https://github.com/johnxie/awesome-code-docs)
- Why it matters: authoritative reference on `Awesome Code Docs` (github.com).
+- [`packages/@n8n/nodes-langchain/nodes/agents/Agent/`](https://github.com/n8n-io/n8n/tree/master/packages/%40n8n/nodes-langchain/nodes/agents/Agent) -- main AI Agent node: `execute()` method assembles LLM + tools + memory into a LangChain AgentExecutor
+- [`packages/@n8n/nodes-langchain/nodes/memory/`](https://github.com/n8n-io/n8n/tree/master/packages/%40n8n/nodes-langchain/nodes/memory) -- memory nodes: Window Buffer Memory, Postgres Chat Memory
+- [`packages/@n8n/nodes-langchain/nodes/tools/`](https://github.com/n8n-io/n8n/tree/master/packages/%40n8n/nodes-langchain/nodes/tools) -- tool nodes: HTTP Request Tool, Code Tool, Calculator, WikipediaTool
-Suggested trace strategy:
-- search upstream code for `json` and `name` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+Suggested trace: in the Agent node's `execute()` method, find how it collects sub-nodes (tools, memory, LLM) via `getInputConnectionData()` and passes them to LangChain's agent executor.
## Chapter Connections
diff --git a/tutorials/n8n-ai-tutorial/05-rag.md b/tutorials/n8n-ai-tutorial/05-rag.md
index bb3d3f95..b5dc8fa8 100644
--- a/tutorials/n8n-ai-tutorial/05-rag.md
+++ b/tutorials/n8n-ai-tutorial/05-rag.md
@@ -13,6 +13,26 @@ Welcome to **Chapter 5: Retrieval-Augmented Generation (RAG)**. In this part of
> Build knowledge-based AI systems that retrieve relevant information and generate accurate responses.
+## RAG Workflow in n8n
+
+```mermaid
+flowchart TD
+ subgraph Ingestion
+ DOC[Documents] --> LOAD[Document Loader]
+ LOAD --> SPLIT[Text Splitter]
+ SPLIT --> EMBED[Embeddings Node]
+ EMBED --> VS[(Vector Store\nPinecone / Qdrant / Supabase)]
+ end
+
+ subgraph Query
+ Q[User Question] --> QEMBED[Embeddings Node]
+ QEMBED --> SEARCH[Vector Store Search]
+ SEARCH --> CTX[Retrieved Context]
+ CTX --> LLM[AI Chat Node]
+ LLM --> ANS[Answer]
+ end
+```
+
## RAG Fundamentals
RAG combines retrieval of relevant documents with generative AI to provide accurate, context-aware responses.
@@ -534,16 +554,13 @@ When debugging, walk this sequence in order and confirm each stage has explicit
## Source Walkthrough
-Use the following upstream sources to verify implementation details while reading this chapter:
+Key source files in [`n8n-io/n8n`](https://github.com/n8n-io/n8n):
-- [View Repo](https://github.com/n8n-io/n8n)
- Why it matters: authoritative reference on `View Repo` (github.com).
-- [Awesome Code Docs](https://github.com/johnxie/awesome-code-docs)
- Why it matters: authoritative reference on `Awesome Code Docs` (github.com).
+- [`packages/@n8n/nodes-langchain/nodes/vector_store/`](https://github.com/n8n-io/n8n/tree/master/packages/%40n8n/nodes-langchain/nodes/vector_store) -- vector store nodes: Pinecone, Qdrant, Supabase, PGVector, In-Memory
+- [`packages/@n8n/nodes-langchain/nodes/retrievers/`](https://github.com/n8n-io/n8n/tree/master/packages/%40n8n/nodes-langchain/nodes/retrievers) -- retriever nodes; wrap vector stores for use as Agent tools
+- [`packages/@n8n/nodes-langchain/nodes/chains/ChainRetrievalQA/`](https://github.com/n8n-io/n8n/tree/master/packages/%40n8n/nodes-langchain/nodes/chains/ChainRetrievalQA) -- RAG chain node: connects retriever + LLM into a question-answering pipeline
-Suggested trace strategy:
-- search upstream code for `json` and `text` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+Suggested trace: find how `VectorStoreQA` chain node calls `loadQAStuffChain()` and see how retrieved documents are formatted into the LLM prompt context.
## Chapter Connections
diff --git a/tutorials/n8n-ai-tutorial/06-decisions.md b/tutorials/n8n-ai-tutorial/06-decisions.md
index 49294c62..71a31d93 100644
--- a/tutorials/n8n-ai-tutorial/06-decisions.md
+++ b/tutorials/n8n-ai-tutorial/06-decisions.md
@@ -13,6 +13,18 @@ Welcome to **Chapter 6: AI-Powered Decision Making and Routing**. In this part o
> Build intelligent workflows that make decisions, route data, and adapt based on AI analysis.
+## AI Decision Flow Pattern
+
+```mermaid
+flowchart TD
+ INPUT[Input Data] --> AI[AI Classification Node]
+ AI --> SWITCH[Switch Node\nroute by AI output]
+ SWITCH -->|urgent| SLACK[Notify Slack]
+ SWITCH -->|support| TICKET[Create Helpdesk Ticket]
+ SWITCH -->|spam| ARCHIVE[Archive + Ignore]
+ SWITCH -->|unknown| HUMAN[Escalate to Human]
+```
+
## Conditional Logic with AI
### AI-Powered Routing
@@ -374,16 +386,13 @@ When debugging, walk this sequence in order and confirm each stage has explicit
## Source Walkthrough
-Use the following upstream sources to verify implementation details while reading this chapter:
+Key source files in [`n8n-io/n8n`](https://github.com/n8n-io/n8n):
-- [View Repo](https://github.com/n8n-io/n8n)
- Why it matters: authoritative reference on `View Repo` (github.com).
-- [Awesome Code Docs](https://github.com/johnxie/awesome-code-docs)
- Why it matters: authoritative reference on `Awesome Code Docs` (github.com).
+- [`packages/nodes-base/nodes/If/If.node.ts`](https://github.com/n8n-io/n8n/blob/master/packages/nodes-base/nodes/If/If.node.ts) -- IF node: evaluates conditions against input data and routes to true/false outputs
+- [`packages/nodes-base/nodes/Switch/Switch.node.ts`](https://github.com/n8n-io/n8n/blob/master/packages/nodes-base/nodes/Switch/Switch.node.ts) -- Switch node: multi-branch routing based on expressions or rule sets
+- [`packages/@n8n/nodes-langchain/nodes/output_parser/OutputParserStructured/`](https://github.com/n8n-io/n8n/tree/master/packages/%40n8n/nodes-langchain/nodes/output_parser/OutputParserStructured) -- structured JSON output parser; enables type-safe AI classification output for use in IF/Switch nodes
-Suggested trace strategy:
-- search upstream code for `json` and `nodes` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+Suggested trace: see how `If.node.ts` evaluates its condition rules against `INodeExecutionData` items and splits them into separate output branches.
## Chapter Connections
diff --git a/tutorials/n8n-ai-tutorial/07-custom-tools.md b/tutorials/n8n-ai-tutorial/07-custom-tools.md
index a2f80c17..909472b9 100644
--- a/tutorials/n8n-ai-tutorial/07-custom-tools.md
+++ b/tutorials/n8n-ai-tutorial/07-custom-tools.md
@@ -13,6 +13,20 @@ Welcome to **Chapter 7: Building Custom AI Tools and Integrations**. In this par
> Extend n8n's capabilities with custom AI tools, integrations, and specialized functions.
+## Custom Tool Types in n8n
+
+```mermaid
+flowchart TD
+ CUSTOM[Custom AI Tools] --> HTTP[HTTP Request Tool\ncall any REST API]
+ CUSTOM --> CODE[Code Tool\nrun JavaScript/Python]
+ CUSTOM --> WF[n8n Workflow Tool\nexpose workflow as tool]
+ CUSTOM --> MCP[MCP Tool Node\nModel Context Protocol servers]
+ HTTP --> AGENT[AI Agent Node]
+ CODE --> AGENT
+ WF --> AGENT
+ MCP --> AGENT
+```
+
## Custom Tool Development
### HTTP Request Tools
@@ -500,16 +514,13 @@ When debugging, walk this sequence in order and confirm each stage has explicit
## Source Walkthrough
-Use the following upstream sources to verify implementation details while reading this chapter:
+Key source files in [`n8n-io/n8n`](https://github.com/n8n-io/n8n):
-- [View Repo](https://github.com/n8n-io/n8n)
- Why it matters: authoritative reference on `View Repo` (github.com).
-- [Awesome Code Docs](https://github.com/johnxie/awesome-code-docs)
- Why it matters: authoritative reference on `Awesome Code Docs` (github.com).
+- [`packages/@n8n/nodes-langchain/nodes/tools/ToolHttpRequest/`](https://github.com/n8n-io/n8n/tree/master/packages/%40n8n/nodes-langchain/nodes/tools/ToolHttpRequest) -- HTTP Request Tool node: wraps any REST API call as an AI agent tool
+- [`packages/@n8n/nodes-langchain/nodes/tools/ToolCode/`](https://github.com/n8n-io/n8n/tree/master/packages/%40n8n/nodes-langchain/nodes/tools/ToolCode) -- Code Tool node: runs JavaScript in a sandboxed environment as a callable tool
+- [`packages/@n8n/nodes-langchain/nodes/tools/ToolWorkflow/`](https://github.com/n8n-io/n8n/tree/master/packages/%40n8n/nodes-langchain/nodes/tools/ToolWorkflow) -- Workflow Tool node: exposes any n8n workflow as a tool callable by an agent
-Suggested trace strategy:
-- search upstream code for `text` and `json` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+Suggested trace: the `ToolWorkflow` node's `supplyData()` creates a LangChain `DynamicTool` that invokes another workflow via `WorkflowRunner.run()` when called.
## Chapter Connections
diff --git a/tutorials/n8n-ai-tutorial/08-production.md b/tutorials/n8n-ai-tutorial/08-production.md
index 9b12f978..a60aae54 100644
--- a/tutorials/n8n-ai-tutorial/08-production.md
+++ b/tutorials/n8n-ai-tutorial/08-production.md
@@ -13,6 +13,20 @@ Welcome to **Chapter 8: Production Deployment and Scaling**. In this part of **n
> Deploy n8n AI workflows to production with monitoring, security, and enterprise features.
+## Production Deployment Architecture
+
+```mermaid
+flowchart TD
+ LB[Load Balancer] --> W1[n8n Worker 1]
+ LB --> W2[n8n Worker 2]
+ W1 --> PG[(PostgreSQL\nworkflows + executions)]
+ W2 --> PG
+ W1 --> REDIS[(Redis\nexecution queue)]
+ W2 --> REDIS
+ W1 --> AI[AI Providers\nOpenAI / Anthropic]
+ W1 --> MON[Monitoring\nPrometheus + Grafana]
+```
+
## Production Architecture
### Scalable Deployment Options
@@ -557,16 +571,13 @@ When debugging, walk this sequence in order and confirm each stage has explicit
## Source Walkthrough
-Use the following upstream sources to verify implementation details while reading this chapter:
+Key source files in [`n8n-io/n8n`](https://github.com/n8n-io/n8n):
-- [View Repo](https://github.com/n8n-io/n8n)
- Why it matters: authoritative reference on `View Repo` (github.com).
-- [Awesome Code Docs](https://github.com/johnxie/awesome-code-docs)
- Why it matters: authoritative reference on `Awesome Code Docs` (github.com).
+- [`docker-compose.yml`](https://github.com/n8n-io/n8n/blob/master/docker-compose.yml) -- reference compose with PostgreSQL + Redis + n8n main/worker/webhook services
+- [`packages/cli/src/config/schema.ts`](https://github.com/n8n-io/n8n/blob/master/packages/cli/src/config/schema.ts) -- all `N8N_*` environment variables and their defaults for production configuration
+- [`packages/cli/src/Queue.ts`](https://github.com/n8n-io/n8n/blob/master/packages/cli/src/Queue.ts) -- Bull queue implementation; defines how execution jobs are distributed across worker instances
-Suggested trace strategy:
-- search upstream code for `name` and `workflowStats` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+Suggested trace: review `config/schema.ts` for all scaling-related options (`N8N_CONCURRENCY_PRODUCTION_LIMIT`, `QUEUE_BULL_*`), then see how `Queue.ts` uses Bull to dispatch executions to workers.
## Chapter Connections
diff --git a/tutorials/nanocoder-tutorial/01-getting-started.md b/tutorials/nanocoder-tutorial/01-getting-started.md
index dd18f2a1..57d04ea3 100644
--- a/tutorials/nanocoder-tutorial/01-getting-started.md
+++ b/tutorials/nanocoder-tutorial/01-getting-started.md
@@ -6,6 +6,7 @@ has_children: false
parent: "Nanocoder - AI Coding Agent Deep Dive"
---
+
# Chapter 1: Getting Started
Welcome to **Chapter 1: Getting Started**. In this part of **Nanocoder Tutorial: Building and Understanding AI Coding Agents**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
@@ -270,370 +271,182 @@ In [Chapter 2: Architecture & Agent Loop](02-architecture-agent-loop.md), we'll
## Depth Expansion Playbook
-<!-- depth-expansion-v2 -->
-
-This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
-
-### Strategic Context
-
-- tutorial: **Nanocoder Tutorial: Building and Understanding AI Coding Agents**
-- tutorial slug: **nanocoder-tutorial**
-- chapter focus: **Chapter 1: Getting Started**
-- system context: **Nanocoder Tutorial**
-- objective: move from surface-level usage to repeatable engineering operation
-
-### Architecture Decomposition
-
-1. Define the runtime boundary for `Chapter 1: Getting Started`.
-2. Separate control-plane decisions from data-plane execution.
-3. Capture input contracts, transformation points, and output contracts.
-4. Trace state transitions across request lifecycle stages.
-5. Identify extension hooks and policy interception points.
-6. Map ownership boundaries for team and automation workflows.
-7. Specify rollback and recovery paths for unsafe changes.
-8. Track observability signals for correctness, latency, and cost.
-
-### Operator Decision Matrix
-
-| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
-|:--------------|:--------------|:------------------|:---------|
-| Runtime mode | managed defaults | explicit policy config | speed vs control |
-| State handling | local ephemeral | durable persisted state | simplicity vs auditability |
-| Tool integration | direct API use | mediated adapter layer | velocity vs governance |
-| Rollout method | manual change | staged + canary rollout | effort vs safety |
-| Incident response | best effort logs | runbooks + SLO alerts | cost vs reliability |
-
-### Failure Modes and Countermeasures
-
-| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
-|:-------------|:-------------|:-------------------|:---------------|
-| stale context | inconsistent outputs | missing refresh window | enforce context TTL and refresh hooks |
-| policy drift | unexpected execution | ad hoc overrides | centralize policy profiles |
-| auth mismatch | 401/403 bursts | credential sprawl | rotation schedule + scope minimization |
-| schema breakage | parser/validation errors | unmanaged upstream changes | contract tests per release |
-| retry storms | queue congestion | no backoff controls | jittered backoff + circuit breakers |
-| silent regressions | quality drop without alerts | weak baseline metrics | eval harness with thresholds |
-
-### Implementation Runbook
-
-1. Establish a reproducible baseline environment.
-2. Capture chapter-specific success criteria before changes.
-3. Implement minimal viable path with explicit interfaces.
-4. Add observability before expanding feature scope.
-5. Run deterministic tests for happy-path behavior.
-6. Inject failure scenarios for negative-path validation.
-7. Compare output quality against baseline snapshots.
-8. Promote through staged environments with rollback gates.
-9. Record operational lessons in release notes.
-
-### Quality Gate Checklist
-
-- [ ] chapter-level assumptions are explicit and testable
-- [ ] API/tool boundaries are documented with input/output examples
-- [ ] failure handling includes retry, timeout, and fallback policy
-- [ ] security controls include auth scopes and secret rotation plans
-- [ ] observability includes logs, metrics, traces, and alert thresholds
-- [ ] deployment guidance includes canary and rollback paths
-- [ ] docs include links to upstream sources and related tracks
-- [ ] post-release verification confirms expected behavior under load
-
-### Source Alignment
-
-- [Nanocoder Repository](https://github.com/Nano-Collective/nanocoder)
-- [Nanocoder Releases](https://github.com/Nano-Collective/nanocoder/releases)
-- [Nanocoder Documentation Directory](https://github.com/Nano-Collective/nanocoder/tree/main/docs)
-- [Nanocoder MCP Configuration Guide](https://github.com/Nano-Collective/nanocoder/blob/main/docs/mcp-configuration.md)
-- [Nano Collective Website](https://nanocollective.org/)
-
-### Cross-Tutorial Connection Map
-
-- [Aider Tutorial](../aider-tutorial/)
-- [Claude Code Tutorial](../claude-code-tutorial/)
-- [Continue Tutorial](../continue-tutorial/)
-- [OpenHands Tutorial](../openhands-tutorial/)
-- [Chapter 1: Getting Started](01-getting-started.md)
-
-### Advanced Practice Exercises
-
-1. Build a minimal end-to-end implementation for `Chapter 1: Getting Started`.
-2. Add instrumentation and measure baseline latency and error rate.
-3. Introduce one controlled failure and confirm graceful recovery.
-4. Add policy constraints and verify they are enforced consistently.
-5. Run a staged rollout and document rollback decision criteria.
-
-### Review Questions
-
-1. Which execution boundary matters most for this chapter and why?
-2. What signal detects regressions earliest in your environment?
-3. What tradeoff did you make between delivery speed and governance?
-4. How would you recover from the highest-impact failure mode?
-5. What must be automated before scaling to team-wide adoption?
-
-### Scenario Playbook 1: Chapter 1: Getting Started
-
-- tutorial context: **Nanocoder Tutorial: Building and Understanding AI Coding Agents**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 2: Chapter 1: Getting Started
-
-- tutorial context: **Nanocoder Tutorial: Building and Understanding AI Coding Agents**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 3: Chapter 1: Getting Started
-
-- tutorial context: **Nanocoder Tutorial: Building and Understanding AI Coding Agents**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 4: Chapter 1: Getting Started
-
-- tutorial context: **Nanocoder Tutorial: Building and Understanding AI Coding Agents**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 5: Chapter 1: Getting Started
-
-- tutorial context: **Nanocoder Tutorial: Building and Understanding AI Coding Agents**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 6: Chapter 1: Getting Started
-
-- tutorial context: **Nanocoder Tutorial: Building and Understanding AI Coding Agents**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 7: Chapter 1: Getting Started
-
-- tutorial context: **Nanocoder Tutorial: Building and Understanding AI Coding Agents**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 8: Chapter 1: Getting Started
-
-- tutorial context: **Nanocoder Tutorial: Building and Understanding AI Coding Agents**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 9: Chapter 1: Getting Started
-
-- tutorial context: **Nanocoder Tutorial: Building and Understanding AI Coding Agents**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 10: Chapter 1: Getting Started
-
-- tutorial context: **Nanocoder Tutorial: Building and Understanding AI Coding Agents**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 11: Chapter 1: Getting Started
-
-- tutorial context: **Nanocoder Tutorial: Building and Understanding AI Coding Agents**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 12: Chapter 1: Getting Started
-
-- tutorial context: **Nanocoder Tutorial: Building and Understanding AI Coding Agents**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 13: Chapter 1: Getting Started
-
-- tutorial context: **Nanocoder Tutorial: Building and Understanding AI Coding Agents**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 14: Chapter 1: Getting Started
-
-- tutorial context: **Nanocoder Tutorial: Building and Understanding AI Coding Agents**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 15: Chapter 1: Getting Started
-
-- tutorial context: **Nanocoder Tutorial: Building and Understanding AI Coding Agents**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 16: Chapter 1: Getting Started
-
-- tutorial context: **Nanocoder Tutorial: Building and Understanding AI Coding Agents**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 17: Chapter 1: Getting Started
-
-- tutorial context: **Nanocoder Tutorial: Building and Understanding AI Coding Agents**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 18: Chapter 1: Getting Started
-
-- tutorial context: **Nanocoder Tutorial: Building and Understanding AI Coding Agents**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-## What Problem Does This Solve?
-
-Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for `nanocoder`, `model`, `json` so behavior stays predictable as complexity grows.
-
-In practical terms, this chapter helps you avoid three common failures:
-
-- coupling core logic too tightly to one implementation path
-- missing the handoff boundaries between setup, execution, and validation
-- shipping changes without clear rollback or observability strategy
-
-After working through this chapter, you should be able to reason about `Chapter 1: Getting Started` as an operating subsystem inside **Nanocoder Tutorial: Building and Understanding AI Coding Agents**, with explicit contracts for inputs, state transitions, and outputs.
-
-Use the implementation notes around `config`, `Tool`, `project` as your checklist when adapting these patterns to your own repository.
-
-## How it Works Under the Hood
-
-Under the hood, `Chapter 1: Getting Started` usually follows a repeatable control path:
-
-1. **Context bootstrap**: initialize runtime config and prerequisites for `nanocoder`.
-2. **Input normalization**: shape incoming data so `model` receives stable contracts.
-3. **Core execution**: run the main logic branch and propagate intermediate state through `json`.
-4. **Policy and safety checks**: enforce limits, auth scopes, and failure boundaries.
-5. **Output composition**: return canonical result payloads for downstream consumers.
-6. **Operational telemetry**: emit logs/metrics needed for debugging and performance tuning.
-
-When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
-
-## Source Walkthrough
-
-Use the following upstream sources to verify implementation details while reading this chapter:
-
-- [Nanocoder Repository](https://github.com/Nano-Collective/nanocoder)
- Why it matters: authoritative reference on `Nanocoder Repository` (github.com).
-- [Nanocoder Releases](https://github.com/Nano-Collective/nanocoder/releases)
- Why it matters: authoritative reference on `Nanocoder Releases` (github.com).
-- [Nanocoder Documentation Directory](https://github.com/Nano-Collective/nanocoder/tree/main/docs)
- Why it matters: authoritative reference on `Nanocoder Documentation Directory` (github.com).
-- [Nanocoder MCP Configuration Guide](https://github.com/Nano-Collective/nanocoder/blob/main/docs/mcp-configuration.md)
- Why it matters: authoritative reference on `Nanocoder MCP Configuration Guide` (github.com).
-- [Nano Collective Website](https://nanocollective.org/)
- Why it matters: authoritative reference on `Nano Collective Website` (nanocollective.org).
-
-Suggested trace strategy:
-- search upstream code for `nanocoder` and `model` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
-
-## Chapter Connections
-
-- [Tutorial Index](README.md)
-- [Next Chapter: Chapter 2: Architecture & Agent Loop](02-architecture-agent-loop.md)
-- [Main Catalog](../../README.md#-tutorial-catalog)
-- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
+## Source Code Walkthrough
+
+### `nanocoder-dummy-file.ts`
+
+The `greet` function in [`nanocoder-dummy-file.ts`](https://github.com/Nano-Collective/nanocoder/blob/HEAD/nanocoder-dummy-file.ts) handles a key part of this chapter's functionality:
+
+```ts
+// A simple file to give to models to test Nanocoder's functionality
+
+export function greet(name: string): string {
+ return `Hello ${name}!`;
+}
+
+export function add(a: number, b: number): number {
+ return a + b;
+}
+
+export function multiply(x: number, y: number): number {
+ return x * y;
+}
+
+// More functions to make a medium-sized file
+
+export function subtract(a: number, b: number): number {
+ return a - b;
+}
+
+export function divide(a: number, b: number): number {
+ if (b === 0) {
+ throw new Error('Division by zero');
+ }
+ return a / b;
+}
+
+export function power(base: number, exponent: number): number {
+ return Math.pow(base, exponent);
+}
+
+export function sqrt(n: number): number {
+```
+
+This function is important because it defines how Nanocoder Tutorial: Building and Understanding AI Coding Agents implements the patterns covered in this chapter.
+
+### `nanocoder-dummy-file.ts`
+
+The `add` function in [`nanocoder-dummy-file.ts`](https://github.com/Nano-Collective/nanocoder/blob/HEAD/nanocoder-dummy-file.ts) handles a key part of this chapter's functionality:
+
+```ts
+}
+
+export function add(a: number, b: number): number {
+ return a + b;
+}
+
+export function multiply(x: number, y: number): number {
+ return x * y;
+}
+
+// More functions to make a medium-sized file
+
+export function subtract(a: number, b: number): number {
+ return a - b;
+}
+
+export function divide(a: number, b: number): number {
+ if (b === 0) {
+ throw new Error('Division by zero');
+ }
+ return a / b;
+}
+
+export function power(base: number, exponent: number): number {
+ return Math.pow(base, exponent);
+}
+
+export function sqrt(n: number): number {
+ return Math.sqrt(n);
+}
+
+export function abs(n: number): number {
+```
+
+This function is important because it defines how Nanocoder Tutorial: Building and Understanding AI Coding Agents implements the patterns covered in this chapter.
+
+### `nanocoder-dummy-file.ts`
+
+The `multiply` function in [`nanocoder-dummy-file.ts`](https://github.com/Nano-Collective/nanocoder/blob/HEAD/nanocoder-dummy-file.ts) handles a key part of this chapter's functionality:
+
+```ts
+}
+
+export function multiply(x: number, y: number): number {
+ return x * y;
+}
+
+// More functions to make a medium-sized file
+
+export function subtract(a: number, b: number): number {
+ return a - b;
+}
+
+export function divide(a: number, b: number): number {
+ if (b === 0) {
+ throw new Error('Division by zero');
+ }
+ return a / b;
+}
+
+export function power(base: number, exponent: number): number {
+ return Math.pow(base, exponent);
+}
+
+export function sqrt(n: number): number {
+ return Math.sqrt(n);
+}
+
+export function abs(n: number): number {
+ return Math.abs(n);
+}
+
+export function round(n: number): number {
+```
+
+This function is important because it defines how Nanocoder Tutorial: Building and Understanding AI Coding Agents implements the patterns covered in this chapter.
+
+### `nanocoder-dummy-file.ts`
+
+The `subtract` function in [`nanocoder-dummy-file.ts`](https://github.com/Nano-Collective/nanocoder/blob/HEAD/nanocoder-dummy-file.ts) handles a key part of this chapter's functionality:
+
+```ts
+// More functions to make a medium-sized file
+
+export function subtract(a: number, b: number): number {
+ return a - b;
+}
+
+export function divide(a: number, b: number): number {
+ if (b === 0) {
+ throw new Error('Division by zero');
+ }
+ return a / b;
+}
+
+export function power(base: number, exponent: number): number {
+ return Math.pow(base, exponent);
+}
+
+export function sqrt(n: number): number {
+ return Math.sqrt(n);
+}
+
+export function abs(n: number): number {
+ return Math.abs(n);
+}
+
+export function round(n: number): number {
+ return Math.round(n);
+}
+
+export function floor(n: number): number {
+ return Math.floor(n);
+}
+```
+
+This function is important because it defines how Nanocoder Tutorial: Building and Understanding AI Coding Agents implements the patterns covered in this chapter.
+
+
+## How These Components Connect
+
+```mermaid
+flowchart TD
+ A[greet]
+ B[add]
+ C[multiply]
+ D[subtract]
+ A --> B
+ B --> C
+ C --> D
+```
diff --git a/tutorials/nanocoder-tutorial/02-architecture-agent-loop.md b/tutorials/nanocoder-tutorial/02-architecture-agent-loop.md
index d0df9e20..b2e10249 100644
--- a/tutorials/nanocoder-tutorial/02-architecture-agent-loop.md
+++ b/tutorials/nanocoder-tutorial/02-architecture-agent-loop.md
@@ -6,6 +6,7 @@ has_children: false
parent: "Nanocoder - AI Coding Agent Deep Dive"
---
+
# Chapter 2: Architecture & Agent Loop
Welcome to **Chapter 2: Architecture & Agent Loop**. In this part of **Nanocoder Tutorial: Building and Understanding AI Coding Agents**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
@@ -398,251 +399,158 @@ In [Chapter 3: Tool System Internals](03-tool-system-internals.md), we'll explor
## Depth Expansion Playbook
-<!-- depth-expansion-v2 -->
-
-This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
-
-### Strategic Context
-
-- tutorial: **Nanocoder Tutorial: Building and Understanding AI Coding Agents**
-- tutorial slug: **nanocoder-tutorial**
-- chapter focus: **Chapter 2: Architecture & Agent Loop**
-- system context: **Nanocoder Tutorial**
-- objective: move from surface-level usage to repeatable engineering operation
-
-### Architecture Decomposition
-
-1. Define the runtime boundary for `Chapter 2: Architecture & Agent Loop`.
-2. Separate control-plane decisions from data-plane execution.
-3. Capture input contracts, transformation points, and output contracts.
-4. Trace state transitions across request lifecycle stages.
-5. Identify extension hooks and policy interception points.
-6. Map ownership boundaries for team and automation workflows.
-7. Specify rollback and recovery paths for unsafe changes.
-8. Track observability signals for correctness, latency, and cost.
-
-### Operator Decision Matrix
-
-| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
-|:--------------|:--------------|:------------------|:---------|
-| Runtime mode | managed defaults | explicit policy config | speed vs control |
-| State handling | local ephemeral | durable persisted state | simplicity vs auditability |
-| Tool integration | direct API use | mediated adapter layer | velocity vs governance |
-| Rollout method | manual change | staged + canary rollout | effort vs safety |
-| Incident response | best effort logs | runbooks + SLO alerts | cost vs reliability |
-
-### Failure Modes and Countermeasures
-
-| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
-|:-------------|:-------------|:-------------------|:---------------|
-| stale context | inconsistent outputs | missing refresh window | enforce context TTL and refresh hooks |
-| policy drift | unexpected execution | ad hoc overrides | centralize policy profiles |
-| auth mismatch | 401/403 bursts | credential sprawl | rotation schedule + scope minimization |
-| schema breakage | parser/validation errors | unmanaged upstream changes | contract tests per release |
-| retry storms | queue congestion | no backoff controls | jittered backoff + circuit breakers |
-| silent regressions | quality drop without alerts | weak baseline metrics | eval harness with thresholds |
-
-### Implementation Runbook
-
-1. Establish a reproducible baseline environment.
-2. Capture chapter-specific success criteria before changes.
-3. Implement minimal viable path with explicit interfaces.
-4. Add observability before expanding feature scope.
-5. Run deterministic tests for happy-path behavior.
-6. Inject failure scenarios for negative-path validation.
-7. Compare output quality against baseline snapshots.
-8. Promote through staged environments with rollback gates.
-9. Record operational lessons in release notes.
-
-### Quality Gate Checklist
-
-- [ ] chapter-level assumptions are explicit and testable
-- [ ] API/tool boundaries are documented with input/output examples
-- [ ] failure handling includes retry, timeout, and fallback policy
-- [ ] security controls include auth scopes and secret rotation plans
-- [ ] observability includes logs, metrics, traces, and alert thresholds
-- [ ] deployment guidance includes canary and rollback paths
-- [ ] docs include links to upstream sources and related tracks
-- [ ] post-release verification confirms expected behavior under load
-
-### Source Alignment
-
-- [Nanocoder Repository](https://github.com/Nano-Collective/nanocoder)
-- [Nanocoder Releases](https://github.com/Nano-Collective/nanocoder/releases)
-- [Nanocoder Documentation Directory](https://github.com/Nano-Collective/nanocoder/tree/main/docs)
-- [Nanocoder MCP Configuration Guide](https://github.com/Nano-Collective/nanocoder/blob/main/docs/mcp-configuration.md)
-- [Nano Collective Website](https://nanocollective.org/)
-
-### Cross-Tutorial Connection Map
-
-- [Aider Tutorial](../aider-tutorial/)
-- [Claude Code Tutorial](../claude-code-tutorial/)
-- [Continue Tutorial](../continue-tutorial/)
-- [OpenHands Tutorial](../openhands-tutorial/)
-- [Chapter 1: Getting Started](01-getting-started.md)
-
-### Advanced Practice Exercises
-
-1. Build a minimal end-to-end implementation for `Chapter 2: Architecture & Agent Loop`.
-2. Add instrumentation and measure baseline latency and error rate.
-3. Introduce one controlled failure and confirm graceful recovery.
-4. Add policy constraints and verify they are enforced consistently.
-5. Run a staged rollout and document rollback decision criteria.
-
-### Review Questions
-
-1. Which execution boundary matters most for this chapter and why?
-2. What signal detects regressions earliest in your environment?
-3. What tradeoff did you make between delivery speed and governance?
-4. How would you recover from the highest-impact failure mode?
-5. What must be automated before scaling to team-wide adoption?
-
-### Scenario Playbook 1: Chapter 2: Architecture & Agent Loop
-
-- tutorial context: **Nanocoder Tutorial: Building and Understanding AI Coding Agents**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 2: Chapter 2: Architecture & Agent Loop
-
-- tutorial context: **Nanocoder Tutorial: Building and Understanding AI Coding Agents**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 3: Chapter 2: Architecture & Agent Loop
-
-- tutorial context: **Nanocoder Tutorial: Building and Understanding AI Coding Agents**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 4: Chapter 2: Architecture & Agent Loop
-
-- tutorial context: **Nanocoder Tutorial: Building and Understanding AI Coding Agents**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 5: Chapter 2: Architecture & Agent Loop
-
-- tutorial context: **Nanocoder Tutorial: Building and Understanding AI Coding Agents**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 6: Chapter 2: Architecture & Agent Loop
-
-- tutorial context: **Nanocoder Tutorial: Building and Understanding AI Coding Agents**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 7: Chapter 2: Architecture & Agent Loop
-
-- tutorial context: **Nanocoder Tutorial: Building and Understanding AI Coding Agents**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 8: Chapter 2: Architecture & Agent Loop
-
-- tutorial context: **Nanocoder Tutorial: Building and Understanding AI Coding Agents**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-## What Problem Does This Solve?
-
-Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for `messages`, `Loop`, `content` so behavior stays predictable as complexity grows.
-
-In practical terms, this chapter helps you avoid three common failures:
-
-- coupling core logic too tightly to one implementation path
-- missing the handoff boundaries between setup, execution, and validation
-- shipping changes without clear rollback or observability strategy
-
-After working through this chapter, you should be able to reason about `Chapter 2: Architecture & Agent Loop` as an operating subsystem inside **Nanocoder Tutorial: Building and Understanding AI Coding Agents**, with explicit contracts for inputs, state transitions, and outputs.
-
-Use the implementation notes around `tools`, `push`, `chunk` as your checklist when adapting these patterns to your own repository.
-
-## How it Works Under the Hood
-
-Under the hood, `Chapter 2: Architecture & Agent Loop` usually follows a repeatable control path:
-
-1. **Context bootstrap**: initialize runtime config and prerequisites for `messages`.
-2. **Input normalization**: shape incoming data so `Loop` receives stable contracts.
-3. **Core execution**: run the main logic branch and propagate intermediate state through `content`.
-4. **Policy and safety checks**: enforce limits, auth scopes, and failure boundaries.
-5. **Output composition**: return canonical result payloads for downstream consumers.
-6. **Operational telemetry**: emit logs/metrics needed for debugging and performance tuning.
-
-When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
-
-## Source Walkthrough
-
-Use the following upstream sources to verify implementation details while reading this chapter:
-
-- [Nanocoder Repository](https://github.com/Nano-Collective/nanocoder)
- Why it matters: authoritative reference on `Nanocoder Repository` (github.com).
-- [Nanocoder Releases](https://github.com/Nano-Collective/nanocoder/releases)
- Why it matters: authoritative reference on `Nanocoder Releases` (github.com).
-- [Nanocoder Documentation Directory](https://github.com/Nano-Collective/nanocoder/tree/main/docs)
- Why it matters: authoritative reference on `Nanocoder Documentation Directory` (github.com).
-- [Nanocoder MCP Configuration Guide](https://github.com/Nano-Collective/nanocoder/blob/main/docs/mcp-configuration.md)
- Why it matters: authoritative reference on `Nanocoder MCP Configuration Guide` (github.com).
-- [Nano Collective Website](https://nanocollective.org/)
- Why it matters: authoritative reference on `Nano Collective Website` (nanocollective.org).
-
-Suggested trace strategy:
-- search upstream code for `messages` and `Loop` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
-
-## Chapter Connections
-
-- [Tutorial Index](README.md)
-- [Previous Chapter: Chapter 1: Getting Started](01-getting-started.md)
-- [Next Chapter: Chapter 3: Tool System Internals](03-tool-system-internals.md)
-- [Main Catalog](../../README.md#-tutorial-catalog)
-- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
+## Source Code Walkthrough
+
+### `nanocoder-dummy-file.ts`
+
+The `divide` function in [`nanocoder-dummy-file.ts`](https://github.com/Nano-Collective/nanocoder/blob/HEAD/nanocoder-dummy-file.ts) handles a key part of this chapter's functionality:
+
+```ts
+}
+
+export function divide(a: number, b: number): number {
+ if (b === 0) {
+ throw new Error('Division by zero');
+ }
+ return a / b;
+}
+
+export function power(base: number, exponent: number): number {
+ return Math.pow(base, exponent);
+}
+
+export function sqrt(n: number): number {
+ return Math.sqrt(n);
+}
+
+export function abs(n: number): number {
+ return Math.abs(n);
+}
+
+export function round(n: number): number {
+ return Math.round(n);
+}
+
+export function floor(n: number): number {
+ return Math.floor(n);
+}
+
+export function ceil(n: number): number {
+ return Math.ceil(n);
+}
+```
+
+This function is important because it defines how Nanocoder Tutorial: Building and Understanding AI Coding Agents implements the patterns covered in this chapter.
+
+### `nanocoder-dummy-file.ts`
+
+The `power` function in [`nanocoder-dummy-file.ts`](https://github.com/Nano-Collective/nanocoder/blob/HEAD/nanocoder-dummy-file.ts) handles a key part of this chapter's functionality:
+
+```ts
+}
+
+export function power(base: number, exponent: number): number {
+ return Math.pow(base, exponent);
+}
+
+export function sqrt(n: number): number {
+ return Math.sqrt(n);
+}
+
+export function abs(n: number): number {
+ return Math.abs(n);
+}
+
+export function round(n: number): number {
+ return Math.round(n);
+}
+
+export function floor(n: number): number {
+ return Math.floor(n);
+}
+
+export function ceil(n: number): number {
+ return Math.ceil(n);
+}
+
+// End of test file
+
+```
+
+This function is important because it defines how Nanocoder Tutorial: Building and Understanding AI Coding Agents implements the patterns covered in this chapter.
+
+### `nanocoder-dummy-file.ts`
+
+The `sqrt` function in [`nanocoder-dummy-file.ts`](https://github.com/Nano-Collective/nanocoder/blob/HEAD/nanocoder-dummy-file.ts) handles a key part of this chapter's functionality:
+
+```ts
+}
+
+export function sqrt(n: number): number {
+ return Math.sqrt(n);
+}
+
+export function abs(n: number): number {
+ return Math.abs(n);
+}
+
+export function round(n: number): number {
+ return Math.round(n);
+}
+
+export function floor(n: number): number {
+ return Math.floor(n);
+}
+
+export function ceil(n: number): number {
+ return Math.ceil(n);
+}
+
+// End of test file
+
+```
+
+This function is important because it defines how Nanocoder Tutorial: Building and Understanding AI Coding Agents implements the patterns covered in this chapter.
+
+### `nanocoder-dummy-file.ts`
+
+The `abs` function in [`nanocoder-dummy-file.ts`](https://github.com/Nano-Collective/nanocoder/blob/HEAD/nanocoder-dummy-file.ts) handles a key part of this chapter's functionality:
+
+```ts
+}
+
+export function abs(n: number): number {
+ return Math.abs(n);
+}
+
+export function round(n: number): number {
+ return Math.round(n);
+}
+
+export function floor(n: number): number {
+ return Math.floor(n);
+}
+
+export function ceil(n: number): number {
+ return Math.ceil(n);
+}
+
+// End of test file
+
+```
+
+This function is important because it defines how Nanocoder Tutorial: Building and Understanding AI Coding Agents implements the patterns covered in this chapter.
+
+
+## How These Components Connect
+
+```mermaid
+flowchart TD
+ A[divide]
+ B[power]
+ C[sqrt]
+ D[abs]
+ A --> B
+ B --> C
+ C --> D
+```
diff --git a/tutorials/nanocoder-tutorial/03-tool-system-internals.md b/tutorials/nanocoder-tutorial/03-tool-system-internals.md
index c8b3e668..9ab53c6c 100644
--- a/tutorials/nanocoder-tutorial/03-tool-system-internals.md
+++ b/tutorials/nanocoder-tutorial/03-tool-system-internals.md
@@ -6,6 +6,7 @@ has_children: false
parent: "Nanocoder - AI Coding Agent Deep Dive"
---
+
# Chapter 3: Tool System Internals
Welcome to **Chapter 3: Tool System Internals**. In this part of **Nanocoder Tutorial: Building and Understanding AI Coding Agents**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
@@ -472,167 +473,122 @@ In [Chapter 4: Multi-Provider Integration](04-multi-provider-integration.md), we
## Depth Expansion Playbook
-<!-- depth-expansion-v2 -->
-
-This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
-
-### Strategic Context
-
-- tutorial: **Nanocoder Tutorial: Building and Understanding AI Coding Agents**
-- tutorial slug: **nanocoder-tutorial**
-- chapter focus: **Chapter 3: Tool System Internals**
-- system context: **Nanocoder Tutorial**
-- objective: move from surface-level usage to repeatable engineering operation
-
-### Architecture Decomposition
-
-1. Define the runtime boundary for `Chapter 3: Tool System Internals`.
-2. Separate control-plane decisions from data-plane execution.
-3. Capture input contracts, transformation points, and output contracts.
-4. Trace state transitions across request lifecycle stages.
-5. Identify extension hooks and policy interception points.
-6. Map ownership boundaries for team and automation workflows.
-7. Specify rollback and recovery paths for unsafe changes.
-8. Track observability signals for correctness, latency, and cost.
-
-### Operator Decision Matrix
+## Source Code Walkthrough
+
+### `nanocoder-dummy-file.ts`
+
+The `round` function in [`nanocoder-dummy-file.ts`](https://github.com/Nano-Collective/nanocoder/blob/HEAD/nanocoder-dummy-file.ts) handles a key part of this chapter's functionality:
+
+```ts
+}
+
+export function round(n: number): number {
+ return Math.round(n);
+}
+
+export function floor(n: number): number {
+ return Math.floor(n);
+}
-| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
-|:--------------|:--------------|:------------------|:---------|
-| Runtime mode | managed defaults | explicit policy config | speed vs control |
-| State handling | local ephemeral | durable persisted state | simplicity vs auditability |
-| Tool integration | direct API use | mediated adapter layer | velocity vs governance |
-| Rollout method | manual change | staged + canary rollout | effort vs safety |
-| Incident response | best effort logs | runbooks + SLO alerts | cost vs reliability |
+export function ceil(n: number): number {
+ return Math.ceil(n);
+}
-### Failure Modes and Countermeasures
-
-| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
-|:-------------|:-------------|:-------------------|:---------------|
-| stale context | inconsistent outputs | missing refresh window | enforce context TTL and refresh hooks |
-| policy drift | unexpected execution | ad hoc overrides | centralize policy profiles |
-| auth mismatch | 401/403 bursts | credential sprawl | rotation schedule + scope minimization |
-| schema breakage | parser/validation errors | unmanaged upstream changes | contract tests per release |
-| retry storms | queue congestion | no backoff controls | jittered backoff + circuit breakers |
-| silent regressions | quality drop without alerts | weak baseline metrics | eval harness with thresholds |
+// End of test file
-### Implementation Runbook
+```
-1. Establish a reproducible baseline environment.
-2. Capture chapter-specific success criteria before changes.
-3. Implement minimal viable path with explicit interfaces.
-4. Add observability before expanding feature scope.
-5. Run deterministic tests for happy-path behavior.
-6. Inject failure scenarios for negative-path validation.
-7. Compare output quality against baseline snapshots.
-8. Promote through staged environments with rollback gates.
-9. Record operational lessons in release notes.
-
-### Quality Gate Checklist
+This function is important because it defines how Nanocoder Tutorial: Building and Understanding AI Coding Agents implements the patterns covered in this chapter.
-- [ ] chapter-level assumptions are explicit and testable
-- [ ] API/tool boundaries are documented with input/output examples
-- [ ] failure handling includes retry, timeout, and fallback policy
-- [ ] security controls include auth scopes and secret rotation plans
-- [ ] observability includes logs, metrics, traces, and alert thresholds
-- [ ] deployment guidance includes canary and rollback paths
-- [ ] docs include links to upstream sources and related tracks
-- [ ] post-release verification confirms expected behavior under load
-
-### Source Alignment
-
-- [Nanocoder Repository](https://github.com/Nano-Collective/nanocoder)
-- [Nanocoder Releases](https://github.com/Nano-Collective/nanocoder/releases)
-- [Nanocoder Documentation Directory](https://github.com/Nano-Collective/nanocoder/tree/main/docs)
-- [Nanocoder MCP Configuration Guide](https://github.com/Nano-Collective/nanocoder/blob/main/docs/mcp-configuration.md)
-- [Nano Collective Website](https://nanocollective.org/)
-
-### Cross-Tutorial Connection Map
-
-- [Aider Tutorial](../aider-tutorial/)
-- [Claude Code Tutorial](../claude-code-tutorial/)
-- [Continue Tutorial](../continue-tutorial/)
-- [OpenHands Tutorial](../openhands-tutorial/)
-- [Chapter 1: Getting Started](01-getting-started.md)
-
-### Advanced Practice Exercises
-
-1. Build a minimal end-to-end implementation for `Chapter 3: Tool System Internals`.
-2. Add instrumentation and measure baseline latency and error rate.
-3. Introduce one controlled failure and confirm graceful recovery.
-4. Add policy constraints and verify they are enforced consistently.
-5. Run a staged rollout and document rollback decision criteria.
-
-### Review Questions
-
-1. Which execution boundary matters most for this chapter and why?
-2. What signal detects regressions earliest in your environment?
-3. What tradeoff did you make between delivery speed and governance?
-4. How would you recover from the highest-impact failure mode?
-5. What must be automated before scaling to team-wide adoption?
-
-### Scenario Playbook 1: Chapter 3: Tool System Internals
-
-- tutorial context: **Nanocoder Tutorial: Building and Understanding AI Coding Agents**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-## What Problem Does This Solve?
-
-Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for `args`, `path`, `description` so behavior stays predictable as complexity grows.
-
-In practical terms, this chapter helps you avoid three common failures:
-
-- coupling core logic too tightly to one implementation path
-- missing the handoff boundaries between setup, execution, and validation
-- shipping changes without clear rollback or observability strategy
-
-After working through this chapter, you should be able to reason about `Chapter 3: Tool System Internals` as an operating subsystem inside **Nanocoder Tutorial: Building and Understanding AI Coding Agents**, with explicit contracts for inputs, state transitions, and outputs.
-
-Use the implementation notes around `name`, `file`, `requiresApproval` as your checklist when adapting these patterns to your own repository.
-
-## How it Works Under the Hood
-
-Under the hood, `Chapter 3: Tool System Internals` usually follows a repeatable control path:
-
-1. **Context bootstrap**: initialize runtime config and prerequisites for `args`.
-2. **Input normalization**: shape incoming data so `path` receives stable contracts.
-3. **Core execution**: run the main logic branch and propagate intermediate state through `description`.
-4. **Policy and safety checks**: enforce limits, auth scopes, and failure boundaries.
-5. **Output composition**: return canonical result payloads for downstream consumers.
-6. **Operational telemetry**: emit logs/metrics needed for debugging and performance tuning.
-
-When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
-
-## Source Walkthrough
-
-Use the following upstream sources to verify implementation details while reading this chapter:
+### `nanocoder-dummy-file.ts`
-- [Nanocoder Repository](https://github.com/Nano-Collective/nanocoder)
- Why it matters: authoritative reference on `Nanocoder Repository` (github.com).
-- [Nanocoder Releases](https://github.com/Nano-Collective/nanocoder/releases)
- Why it matters: authoritative reference on `Nanocoder Releases` (github.com).
-- [Nanocoder Documentation Directory](https://github.com/Nano-Collective/nanocoder/tree/main/docs)
- Why it matters: authoritative reference on `Nanocoder Documentation Directory` (github.com).
-- [Nanocoder MCP Configuration Guide](https://github.com/Nano-Collective/nanocoder/blob/main/docs/mcp-configuration.md)
- Why it matters: authoritative reference on `Nanocoder MCP Configuration Guide` (github.com).
-- [Nano Collective Website](https://nanocollective.org/)
- Why it matters: authoritative reference on `Nano Collective Website` (nanocollective.org).
+The `floor` function in [`nanocoder-dummy-file.ts`](https://github.com/Nano-Collective/nanocoder/blob/HEAD/nanocoder-dummy-file.ts) handles a key part of this chapter's functionality:
-Suggested trace strategy:
-- search upstream code for `args` and `path` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+```ts
+}
-## Chapter Connections
+export function floor(n: number): number {
+ return Math.floor(n);
+}
+
+export function ceil(n: number): number {
+ return Math.ceil(n);
+}
+
+// End of test file
+
+```
+
+This function is important because it defines how Nanocoder Tutorial: Building and Understanding AI Coding Agents implements the patterns covered in this chapter.
+
+### `nanocoder-dummy-file.ts`
+
+The `ceil` function in [`nanocoder-dummy-file.ts`](https://github.com/Nano-Collective/nanocoder/blob/HEAD/nanocoder-dummy-file.ts) handles a key part of this chapter's functionality:
+
+```ts
+}
-- [Tutorial Index](README.md)
-- [Previous Chapter: Chapter 2: Architecture & Agent Loop](02-architecture-agent-loop.md)
-- [Next Chapter: Chapter 4: Multi-Provider Integration](04-multi-provider-integration.md)
-- [Main Catalog](../../README.md#-tutorial-catalog)
-- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
+export function ceil(n: number): number {
+ return Math.ceil(n);
+}
+
+// End of test file
+
+```
+
+This function is important because it defines how Nanocoder Tutorial: Building and Understanding AI Coding Agents implements the patterns covered in this chapter.
+
+### `source/client-factory.ts`
+
+The `for` class in [`source/client-factory.ts`](https://github.com/Nano-Collective/nanocoder/blob/HEAD/source/client-factory.ts) handles a key part of this chapter's functionality:
+
+```ts
+import {isLocalURL} from '@/utils/url-utils';
+
+// Custom error class for configuration errors that need special UI handling
+export class ConfigurationError extends Error {
+ constructor(
+ message: string,
+ public configPath: string,
+ public cwdPath?: string,
+ public isEmptyConfig: boolean = false,
+ ) {
+ super(message);
+ this.name = 'ConfigurationError';
+ }
+}
+
+export async function createLLMClient(
+ provider?: string,
+ model?: string,
+): Promise<{client: LLMClient; actualProvider: string}> {
+ // Check if agents.config.json exists
+ const agentsJsonPath = getClosestConfigFile('agents.config.json');
+ const hasConfigFile = existsSync(agentsJsonPath);
+
+ // Use AI SDK - it handles both tool-calling and non-tool-calling models
+ return createAISDKClient(provider, model, hasConfigFile);
+}
+
+async function createAISDKClient(
+ requestedProvider?: string,
+ requestedModel?: string,
+ hasConfigFile = true,
+): Promise<{client: LLMClient; actualProvider: string}> {
+```
+
+This class is important because it defines how Nanocoder Tutorial: Building and Understanding AI Coding Agents implements the patterns covered in this chapter.
+
+
+## How These Components Connect
+
+```mermaid
+flowchart TD
+ A[round]
+ B[floor]
+ C[ceil]
+ D[for]
+ A --> B
+ B --> C
+ C --> D
+```
diff --git a/tutorials/nanocoder-tutorial/04-multi-provider-integration.md b/tutorials/nanocoder-tutorial/04-multi-provider-integration.md
index f7c8c429..e14bc90e 100644
--- a/tutorials/nanocoder-tutorial/04-multi-provider-integration.md
+++ b/tutorials/nanocoder-tutorial/04-multi-provider-integration.md
@@ -6,6 +6,7 @@ has_children: false
parent: "Nanocoder - AI Coding Agent Deep Dive"
---
+
# Chapter 4: Multi-Provider Integration
Welcome to **Chapter 4: Multi-Provider Integration**. In this part of **Nanocoder Tutorial: Building and Understanding AI Coding Agents**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
@@ -489,155 +490,182 @@ In [Chapter 5: Context Management](05-context-management.md), we'll explore how
## Depth Expansion Playbook
-<!-- depth-expansion-v2 -->
-
-This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
-
-### Strategic Context
+## Source Code Walkthrough
-- tutorial: **Nanocoder Tutorial: Building and Understanding AI Coding Agents**
-- tutorial slug: **nanocoder-tutorial**
-- chapter focus: **Chapter 4: Multi-Provider Integration**
-- system context: **Nanocoder Tutorial**
-- objective: move from surface-level usage to repeatable engineering operation
+### `source/client-factory.ts`
-### Architecture Decomposition
+The `ConfigurationError` class in [`source/client-factory.ts`](https://github.com/Nano-Collective/nanocoder/blob/HEAD/source/client-factory.ts) handles a key part of this chapter's functionality:
-1. Define the runtime boundary for `Chapter 4: Multi-Provider Integration`.
-2. Separate control-plane decisions from data-plane execution.
-3. Capture input contracts, transformation points, and output contracts.
-4. Trace state transitions across request lifecycle stages.
-5. Identify extension hooks and policy interception points.
-6. Map ownership boundaries for team and automation workflows.
-7. Specify rollback and recovery paths for unsafe changes.
-8. Track observability signals for correctness, latency, and cost.
+```ts
-### Operator Decision Matrix
+// Custom error class for configuration errors that need special UI handling
+export class ConfigurationError extends Error {
+ constructor(
+ message: string,
+ public configPath: string,
+ public cwdPath?: string,
+ public isEmptyConfig: boolean = false,
+ ) {
+ super(message);
+ this.name = 'ConfigurationError';
+ }
+}
-| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
-|:--------------|:--------------|:------------------|:---------|
-| Runtime mode | managed defaults | explicit policy config | speed vs control |
-| State handling | local ephemeral | durable persisted state | simplicity vs auditability |
-| Tool integration | direct API use | mediated adapter layer | velocity vs governance |
-| Rollout method | manual change | staged + canary rollout | effort vs safety |
-| Incident response | best effort logs | runbooks + SLO alerts | cost vs reliability |
+export async function createLLMClient(
+ provider?: string,
+ model?: string,
+): Promise<{client: LLMClient; actualProvider: string}> {
+ // Check if agents.config.json exists
+ const agentsJsonPath = getClosestConfigFile('agents.config.json');
+ const hasConfigFile = existsSync(agentsJsonPath);
-### Failure Modes and Countermeasures
+ // Use AI SDK - it handles both tool-calling and non-tool-calling models
+ return createAISDKClient(provider, model, hasConfigFile);
+}
-| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
-|:-------------|:-------------|:-------------------|:---------------|
-| stale context | inconsistent outputs | missing refresh window | enforce context TTL and refresh hooks |
-| policy drift | unexpected execution | ad hoc overrides | centralize policy profiles |
-| auth mismatch | 401/403 bursts | credential sprawl | rotation schedule + scope minimization |
-| schema breakage | parser/validation errors | unmanaged upstream changes | contract tests per release |
-| retry storms | queue congestion | no backoff controls | jittered backoff + circuit breakers |
-| silent regressions | quality drop without alerts | weak baseline metrics | eval harness with thresholds |
+async function createAISDKClient(
+ requestedProvider?: string,
+ requestedModel?: string,
+ hasConfigFile = true,
+): Promise<{client: LLMClient; actualProvider: string}> {
+ // Load provider configs
+```
-### Implementation Runbook
+This class is important because it defines how Nanocoder Tutorial: Building and Understanding AI Coding Agents implements the patterns covered in this chapter.
-1. Establish a reproducible baseline environment.
-2. Capture chapter-specific success criteria before changes.
-3. Implement minimal viable path with explicit interfaces.
-4. Add observability before expanding feature scope.
-5. Run deterministic tests for happy-path behavior.
-6. Inject failure scenarios for negative-path validation.
-7. Compare output quality against baseline snapshots.
-8. Promote through staged environments with rollback gates.
-9. Record operational lessons in release notes.
+### `source/client-factory.ts`
-### Quality Gate Checklist
+The `createLLMClient` function in [`source/client-factory.ts`](https://github.com/Nano-Collective/nanocoder/blob/HEAD/source/client-factory.ts) handles a key part of this chapter's functionality:
-- [ ] chapter-level assumptions are explicit and testable
-- [ ] API/tool boundaries are documented with input/output examples
-- [ ] failure handling includes retry, timeout, and fallback policy
-- [ ] security controls include auth scopes and secret rotation plans
-- [ ] observability includes logs, metrics, traces, and alert thresholds
-- [ ] deployment guidance includes canary and rollback paths
-- [ ] docs include links to upstream sources and related tracks
-- [ ] post-release verification confirms expected behavior under load
+```ts
+}
-### Source Alignment
+export async function createLLMClient(
+ provider?: string,
+ model?: string,
+): Promise<{client: LLMClient; actualProvider: string}> {
+ // Check if agents.config.json exists
+ const agentsJsonPath = getClosestConfigFile('agents.config.json');
+ const hasConfigFile = existsSync(agentsJsonPath);
-- [Nanocoder Repository](https://github.com/Nano-Collective/nanocoder)
-- [Nanocoder Releases](https://github.com/Nano-Collective/nanocoder/releases)
-- [Nanocoder Documentation Directory](https://github.com/Nano-Collective/nanocoder/tree/main/docs)
-- [Nanocoder MCP Configuration Guide](https://github.com/Nano-Collective/nanocoder/blob/main/docs/mcp-configuration.md)
-- [Nano Collective Website](https://nanocollective.org/)
+ // Use AI SDK - it handles both tool-calling and non-tool-calling models
+ return createAISDKClient(provider, model, hasConfigFile);
+}
-### Cross-Tutorial Connection Map
+async function createAISDKClient(
+ requestedProvider?: string,
+ requestedModel?: string,
+ hasConfigFile = true,
+): Promise<{client: LLMClient; actualProvider: string}> {
+ // Load provider configs
+ const providers = loadProviderConfigs();
+
+ const configPath = getClosestConfigFile('agents.config.json');
+ const cwd = process.cwd();
+ const isInCwd = configPath.startsWith(cwd);
+ const cwdPath = !isInCwd ? join(cwd, 'agents.config.json') : undefined;
+
+ if (providers.length === 0) {
+ if (!hasConfigFile) {
+ throw new ConfigurationError(
+ 'No agents.config.json found',
+ configPath,
+```
-- [Aider Tutorial](../aider-tutorial/)
-- [Claude Code Tutorial](../claude-code-tutorial/)
-- [Continue Tutorial](../continue-tutorial/)
-- [OpenHands Tutorial](../openhands-tutorial/)
-- [Chapter 1: Getting Started](01-getting-started.md)
+This function is important because it defines how Nanocoder Tutorial: Building and Understanding AI Coding Agents implements the patterns covered in this chapter.
-### Advanced Practice Exercises
+### `source/client-factory.ts`
-1. Build a minimal end-to-end implementation for `Chapter 4: Multi-Provider Integration`.
-2. Add instrumentation and measure baseline latency and error rate.
-3. Introduce one controlled failure and confirm graceful recovery.
-4. Add policy constraints and verify they are enforced consistently.
-5. Run a staged rollout and document rollback decision criteria.
+The `createAISDKClient` function in [`source/client-factory.ts`](https://github.com/Nano-Collective/nanocoder/blob/HEAD/source/client-factory.ts) handles a key part of this chapter's functionality:
-### Review Questions
+```ts
-1. Which execution boundary matters most for this chapter and why?
-2. What signal detects regressions earliest in your environment?
-3. What tradeoff did you make between delivery speed and governance?
-4. How would you recover from the highest-impact failure mode?
-5. What must be automated before scaling to team-wide adoption?
+ // Use AI SDK - it handles both tool-calling and non-tool-calling models
+ return createAISDKClient(provider, model, hasConfigFile);
+}
+
+async function createAISDKClient(
+ requestedProvider?: string,
+ requestedModel?: string,
+ hasConfigFile = true,
+): Promise<{client: LLMClient; actualProvider: string}> {
+ // Load provider configs
+ const providers = loadProviderConfigs();
+
+ const configPath = getClosestConfigFile('agents.config.json');
+ const cwd = process.cwd();
+ const isInCwd = configPath.startsWith(cwd);
+ const cwdPath = !isInCwd ? join(cwd, 'agents.config.json') : undefined;
+
+ if (providers.length === 0) {
+ if (!hasConfigFile) {
+ throw new ConfigurationError(
+ 'No agents.config.json found',
+ configPath,
+ cwdPath,
+ false,
+ );
+ } else {
+ throw new ConfigurationError(
+ 'No providers configured in agents.config.json',
+ configPath,
+ cwdPath,
+ true,
+```
-## What Problem Does This Solve?
-
-Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for `name`, `config`, `request` so behavior stays predictable as complexity grows.
-
-In practical terms, this chapter helps you avoid three common failures:
-
-- coupling core logic too tightly to one implementation path
-- missing the handoff boundaries between setup, execution, and validation
-- shipping changes without clear rollback or observability strategy
-
-After working through this chapter, you should be able to reason about `Chapter 4: Multi-Provider Integration` as an operating subsystem inside **Nanocoder Tutorial: Building and Understanding AI Coding Agents**, with explicit contracts for inputs, state transitions, and outputs.
-
-Use the implementation notes around `response`, `providers`, `model` as your checklist when adapting these patterns to your own repository.
-
-## How it Works Under the Hood
-
-Under the hood, `Chapter 4: Multi-Provider Integration` usually follows a repeatable control path:
-
-1. **Context bootstrap**: initialize runtime config and prerequisites for `name`.
-2. **Input normalization**: shape incoming data so `config` receives stable contracts.
-3. **Core execution**: run the main logic branch and propagate intermediate state through `request`.
-4. **Policy and safety checks**: enforce limits, auth scopes, and failure boundaries.
-5. **Output composition**: return canonical result payloads for downstream consumers.
-6. **Operational telemetry**: emit logs/metrics needed for debugging and performance tuning.
-
-When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
-
-## Source Walkthrough
-
-Use the following upstream sources to verify implementation details while reading this chapter:
+This function is important because it defines how Nanocoder Tutorial: Building and Understanding AI Coding Agents implements the patterns covered in this chapter.
+
+### `source/client-factory.ts`
+
+The `loadProviderConfigs` function in [`source/client-factory.ts`](https://github.com/Nano-Collective/nanocoder/blob/HEAD/source/client-factory.ts) handles a key part of this chapter's functionality:
+
+```ts
+): Promise<{client: LLMClient; actualProvider: string}> {
+ // Load provider configs
+ const providers = loadProviderConfigs();
+
+ const configPath = getClosestConfigFile('agents.config.json');
+ const cwd = process.cwd();
+ const isInCwd = configPath.startsWith(cwd);
+ const cwdPath = !isInCwd ? join(cwd, 'agents.config.json') : undefined;
+
+ if (providers.length === 0) {
+ if (!hasConfigFile) {
+ throw new ConfigurationError(
+ 'No agents.config.json found',
+ configPath,
+ cwdPath,
+ false,
+ );
+ } else {
+ throw new ConfigurationError(
+ 'No providers configured in agents.config.json',
+ configPath,
+ cwdPath,
+ true,
+ );
+ }
+ }
+
+ // Determine which provider to try first
+ let targetProvider: string;
+ if (requestedProvider) {
+ targetProvider = requestedProvider;
+ } else {
+```
-- [Nanocoder Repository](https://github.com/Nano-Collective/nanocoder)
- Why it matters: authoritative reference on `Nanocoder Repository` (github.com).
-- [Nanocoder Releases](https://github.com/Nano-Collective/nanocoder/releases)
- Why it matters: authoritative reference on `Nanocoder Releases` (github.com).
-- [Nanocoder Documentation Directory](https://github.com/Nano-Collective/nanocoder/tree/main/docs)
- Why it matters: authoritative reference on `Nanocoder Documentation Directory` (github.com).
-- [Nanocoder MCP Configuration Guide](https://github.com/Nano-Collective/nanocoder/blob/main/docs/mcp-configuration.md)
- Why it matters: authoritative reference on `Nanocoder MCP Configuration Guide` (github.com).
-- [Nano Collective Website](https://nanocollective.org/)
- Why it matters: authoritative reference on `Nano Collective Website` (nanocollective.org).
+This function is important because it defines how Nanocoder Tutorial: Building and Understanding AI Coding Agents implements the patterns covered in this chapter.
-Suggested trace strategy:
-- search upstream code for `name` and `config` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
-## Chapter Connections
+## How These Components Connect
-- [Tutorial Index](README.md)
-- [Previous Chapter: Chapter 3: Tool System Internals](03-tool-system-internals.md)
-- [Next Chapter: Chapter 5: Context Management](05-context-management.md)
-- [Main Catalog](../../README.md#-tutorial-catalog)
-- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
+```mermaid
+flowchart TD
+ A[ConfigurationError]
+ B[createLLMClient]
+ C[createAISDKClient]
+ D[loadProviderConfigs]
+ A --> B
+ B --> C
+ C --> D
+```
diff --git a/tutorials/nanocoder-tutorial/05-context-management.md b/tutorials/nanocoder-tutorial/05-context-management.md
index 183dbdac..45ff9c18 100644
--- a/tutorials/nanocoder-tutorial/05-context-management.md
+++ b/tutorials/nanocoder-tutorial/05-context-management.md
@@ -6,6 +6,7 @@ has_children: false
parent: "Nanocoder - AI Coding Agent Deep Dive"
---
+
# Chapter 5: Context Management
Welcome to **Chapter 5: Context Management**. In this part of **Nanocoder Tutorial: Building and Understanding AI Coding Agents**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
@@ -410,239 +411,182 @@ In [Chapter 6: Configuration & Customization](06-configuration-customization.md)
## Depth Expansion Playbook
-<!-- depth-expansion-v2 -->
-
-This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
-
-### Strategic Context
-
-- tutorial: **Nanocoder Tutorial: Building and Understanding AI Coding Agents**
-- tutorial slug: **nanocoder-tutorial**
-- chapter focus: **Chapter 5: Context Management**
-- system context: **Nanocoder Tutorial**
-- objective: move from surface-level usage to repeatable engineering operation
-
-### Architecture Decomposition
-
-1. Define the runtime boundary for `Chapter 5: Context Management`.
-2. Separate control-plane decisions from data-plane execution.
-3. Capture input contracts, transformation points, and output contracts.
-4. Trace state transitions across request lifecycle stages.
-5. Identify extension hooks and policy interception points.
-6. Map ownership boundaries for team and automation workflows.
-7. Specify rollback and recovery paths for unsafe changes.
-8. Track observability signals for correctness, latency, and cost.
-
-### Operator Decision Matrix
-
-| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
-|:--------------|:--------------|:------------------|:---------|
-| Runtime mode | managed defaults | explicit policy config | speed vs control |
-| State handling | local ephemeral | durable persisted state | simplicity vs auditability |
-| Tool integration | direct API use | mediated adapter layer | velocity vs governance |
-| Rollout method | manual change | staged + canary rollout | effort vs safety |
-| Incident response | best effort logs | runbooks + SLO alerts | cost vs reliability |
-
-### Failure Modes and Countermeasures
-
-| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
-|:-------------|:-------------|:-------------------|:---------------|
-| stale context | inconsistent outputs | missing refresh window | enforce context TTL and refresh hooks |
-| policy drift | unexpected execution | ad hoc overrides | centralize policy profiles |
-| auth mismatch | 401/403 bursts | credential sprawl | rotation schedule + scope minimization |
-| schema breakage | parser/validation errors | unmanaged upstream changes | contract tests per release |
-| retry storms | queue congestion | no backoff controls | jittered backoff + circuit breakers |
-| silent regressions | quality drop without alerts | weak baseline metrics | eval harness with thresholds |
-
-### Implementation Runbook
-
-1. Establish a reproducible baseline environment.
-2. Capture chapter-specific success criteria before changes.
-3. Implement minimal viable path with explicit interfaces.
-4. Add observability before expanding feature scope.
-5. Run deterministic tests for happy-path behavior.
-6. Inject failure scenarios for negative-path validation.
-7. Compare output quality against baseline snapshots.
-8. Promote through staged environments with rollback gates.
-9. Record operational lessons in release notes.
-
-### Quality Gate Checklist
-
-- [ ] chapter-level assumptions are explicit and testable
-- [ ] API/tool boundaries are documented with input/output examples
-- [ ] failure handling includes retry, timeout, and fallback policy
-- [ ] security controls include auth scopes and secret rotation plans
-- [ ] observability includes logs, metrics, traces, and alert thresholds
-- [ ] deployment guidance includes canary and rollback paths
-- [ ] docs include links to upstream sources and related tracks
-- [ ] post-release verification confirms expected behavior under load
-
-### Source Alignment
-
-- [Nanocoder Repository](https://github.com/Nano-Collective/nanocoder)
-- [Nanocoder Releases](https://github.com/Nano-Collective/nanocoder/releases)
-- [Nanocoder Documentation Directory](https://github.com/Nano-Collective/nanocoder/tree/main/docs)
-- [Nanocoder MCP Configuration Guide](https://github.com/Nano-Collective/nanocoder/blob/main/docs/mcp-configuration.md)
-- [Nano Collective Website](https://nanocollective.org/)
-
-### Cross-Tutorial Connection Map
-
-- [Aider Tutorial](../aider-tutorial/)
-- [Claude Code Tutorial](../claude-code-tutorial/)
-- [Continue Tutorial](../continue-tutorial/)
-- [OpenHands Tutorial](../openhands-tutorial/)
-- [Chapter 1: Getting Started](01-getting-started.md)
-
-### Advanced Practice Exercises
-
-1. Build a minimal end-to-end implementation for `Chapter 5: Context Management`.
-2. Add instrumentation and measure baseline latency and error rate.
-3. Introduce one controlled failure and confirm graceful recovery.
-4. Add policy constraints and verify they are enforced consistently.
-5. Run a staged rollout and document rollback decision criteria.
-
-### Review Questions
-
-1. Which execution boundary matters most for this chapter and why?
-2. What signal detects regressions earliest in your environment?
-3. What tradeoff did you make between delivery speed and governance?
-4. How would you recover from the highest-impact failure mode?
-5. What must be automated before scaling to team-wide adoption?
-
-### Scenario Playbook 1: Chapter 5: Context Management
-
-- tutorial context: **Nanocoder Tutorial: Building and Understanding AI Coding Agents**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 2: Chapter 5: Context Management
-
-- tutorial context: **Nanocoder Tutorial: Building and Understanding AI Coding Agents**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 3: Chapter 5: Context Management
-
-- tutorial context: **Nanocoder Tutorial: Building and Understanding AI Coding Agents**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 4: Chapter 5: Context Management
-
-- tutorial context: **Nanocoder Tutorial: Building and Understanding AI Coding Agents**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 5: Chapter 5: Context Management
-
-- tutorial context: **Nanocoder Tutorial: Building and Understanding AI Coding Agents**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 6: Chapter 5: Context Management
-
-- tutorial context: **Nanocoder Tutorial: Building and Understanding AI Coding Agents**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 7: Chapter 5: Context Management
-
-- tutorial context: **Nanocoder Tutorial: Building and Understanding AI Coding Agents**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-## What Problem Does This Solve?
-
-Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for `taggedFiles`, `tokens`, `content` so behavior stays predictable as complexity grows.
-
-In practical terms, this chapter helps you avoid three common failures:
-
-- coupling core logic too tightly to one implementation path
-- missing the handoff boundaries between setup, execution, and validation
-- shipping changes without clear rollback or observability strategy
-
-After working through this chapter, you should be able to reason about `Chapter 5: Context Management` as an operating subsystem inside **Nanocoder Tutorial: Building and Understanding AI Coding Agents**, with explicit contracts for inputs, state transitions, and outputs.
-
-Use the implementation notes around `path`, `file`, `model` as your checklist when adapting these patterns to your own repository.
-
-## How it Works Under the Hood
-
-Under the hood, `Chapter 5: Context Management` usually follows a repeatable control path:
-
-1. **Context bootstrap**: initialize runtime config and prerequisites for `taggedFiles`.
-2. **Input normalization**: shape incoming data so `tokens` receives stable contracts.
-3. **Core execution**: run the main logic branch and propagate intermediate state through `content`.
-4. **Policy and safety checks**: enforce limits, auth scopes, and failure boundaries.
-5. **Output composition**: return canonical result payloads for downstream consumers.
-6. **Operational telemetry**: emit logs/metrics needed for debugging and performance tuning.
-
-When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
-
-## Source Walkthrough
-
-Use the following upstream sources to verify implementation details while reading this chapter:
-
-- [Nanocoder Repository](https://github.com/Nano-Collective/nanocoder)
- Why it matters: authoritative reference on `Nanocoder Repository` (github.com).
-- [Nanocoder Releases](https://github.com/Nano-Collective/nanocoder/releases)
- Why it matters: authoritative reference on `Nanocoder Releases` (github.com).
-- [Nanocoder Documentation Directory](https://github.com/Nano-Collective/nanocoder/tree/main/docs)
- Why it matters: authoritative reference on `Nanocoder Documentation Directory` (github.com).
-- [Nanocoder MCP Configuration Guide](https://github.com/Nano-Collective/nanocoder/blob/main/docs/mcp-configuration.md)
- Why it matters: authoritative reference on `Nanocoder MCP Configuration Guide` (github.com).
-- [Nano Collective Website](https://nanocollective.org/)
- Why it matters: authoritative reference on `Nano Collective Website` (nanocollective.org).
-
-Suggested trace strategy:
-- search upstream code for `taggedFiles` and `tokens` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
-
-## Chapter Connections
-
-- [Tutorial Index](README.md)
-- [Previous Chapter: Chapter 4: Multi-Provider Integration](04-multi-provider-integration.md)
-- [Next Chapter: Chapter 6: Configuration & Customization](06-configuration-customization.md)
-- [Main Catalog](../../README.md#-tutorial-catalog)
-- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
+## Source Code Walkthrough
+
+### `source/client-factory.ts`
+
+The `testProviderConnection` function in [`source/client-factory.ts`](https://github.com/Nano-Collective/nanocoder/blob/HEAD/source/client-factory.ts) handles a key part of this chapter's functionality:
+
+```ts
+
+ // Test provider connection
+ await testProviderConnection(providerConfig);
+
+ const client = await AISDKClient.create(providerConfig);
+
+ // Set model if specified
+ if (requestedModel) {
+ client.setModel(requestedModel);
+ }
+
+ return {client, actualProvider: providerType};
+ } catch (error: unknown) {
+ const errorMessage =
+ error instanceof Error ? error.message : 'Unknown error';
+ errors.push(`${providerType}: ${errorMessage}`);
+ }
+ }
+
+ // If we get here, all providers failed
+ if (!hasConfigFile) {
+ const combinedError = `No providers available: ${
+ errors[0]?.split(': ')[1] || 'Unknown error'
+ }\n\nPlease create an agents.config.json file with provider configuration.`;
+ throw new Error(combinedError);
+ } else {
+ const combinedError = `All configured providers failed:\n${errors
+ .map(e => `• ${e}`)
+ .join(
+ '\n',
+ )}\n\nPlease check your provider configuration in agents.config.json`;
+ throw new Error(combinedError);
+```
+
+This function is important because it defines how Nanocoder Tutorial: Building and Understanding AI Coding Agents implements the patterns covered in this chapter.
+
+### `scripts/fetch-models.js`
+
+The `fetchModels` function in [`scripts/fetch-models.js`](https://github.com/Nano-Collective/nanocoder/blob/HEAD/scripts/fetch-models.js) handles a key part of this chapter's functionality:
+
+```js
+ * Fetch models data from models.dev
+ */
+async function fetchModels() {
+ console.log('Fetching model metadata from models.dev...');
+
+ try {
+ const response = await request(MODELS_DEV_API_URL, {
+ method: 'GET',
+ headersTimeout: 10000,
+ bodyTimeout: 30000,
+ });
+
+ if (response.statusCode !== 200) {
+ throw new Error(`HTTP ${response.statusCode}`);
+ }
+
+ const data = await response.body.json();
+
+ // Count models for logging
+ let totalModels = 0;
+ for (const provider of Object.values(data)) {
+ totalModels += Object.keys(provider.models).length;
+ }
+
+ console.log(
+ `✅ Successfully fetched ${totalModels} models from ${
+ Object.keys(data).length
+ } providers`,
+ );
+
+ return data;
+ } catch (error) {
+```
+
+This function is important because it defines how Nanocoder Tutorial: Building and Understanding AI Coding Agents implements the patterns covered in this chapter.
+
+### `scripts/fetch-models.js`
+
+The `ensureCacheDir` function in [`scripts/fetch-models.js`](https://github.com/Nano-Collective/nanocoder/blob/HEAD/scripts/fetch-models.js) handles a key part of this chapter's functionality:
+
+```js
+ * Ensure cache directory exists
+ */
+function ensureCacheDir() {
+ if (!fs.existsSync(cacheDir)) {
+ fs.mkdirSync(cacheDir, {recursive: true});
+ }
+}
+
+/**
+ * Write data to cache
+ */
+function writeCache(data) {
+ try {
+ ensureCacheDir();
+
+ const cached = {
+ data,
+ fetchedAt: Date.now(),
+ expiresAt: Date.now() + CACHE_EXPIRATION_MS,
+ };
+
+ fs.writeFileSync(cacheFilePath, JSON.stringify(cached, null, 2), 'utf-8');
+ console.log(`💾 Cached to: ${cacheFilePath}`);
+ } catch (error) {
+ console.warn('⚠️ Failed to write cache:', error.message);
+ }
+}
+
+/**
+ * Check if existing cache is valid
+ */
+function isCacheValid() {
+```
+
+This function is important because it defines how Nanocoder Tutorial: Building and Understanding AI Coding Agents implements the patterns covered in this chapter.
+
+### `scripts/fetch-models.js`
+
+The `writeCache` function in [`scripts/fetch-models.js`](https://github.com/Nano-Collective/nanocoder/blob/HEAD/scripts/fetch-models.js) handles a key part of this chapter's functionality:
+
+```js
+ * Write data to cache
+ */
+function writeCache(data) {
+ try {
+ ensureCacheDir();
+
+ const cached = {
+ data,
+ fetchedAt: Date.now(),
+ expiresAt: Date.now() + CACHE_EXPIRATION_MS,
+ };
+
+ fs.writeFileSync(cacheFilePath, JSON.stringify(cached, null, 2), 'utf-8');
+ console.log(`💾 Cached to: ${cacheFilePath}`);
+ } catch (error) {
+ console.warn('⚠️ Failed to write cache:', error.message);
+ }
+}
+
+/**
+ * Check if existing cache is valid
+ */
+function isCacheValid() {
+ try {
+ if (!fs.existsSync(cacheFilePath)) {
+ return false;
+ }
+
+ const content = fs.readFileSync(cacheFilePath, 'utf-8');
+ const cached = JSON.parse(content);
+
+ return Date.now() < cached.expiresAt;
+```
+
+This function is important because it defines how Nanocoder Tutorial: Building and Understanding AI Coding Agents implements the patterns covered in this chapter.
+
+
+## How These Components Connect
+
+```mermaid
+flowchart TD
+ A[testProviderConnection]
+ B[fetchModels]
+ C[ensureCacheDir]
+ D[writeCache]
+ A --> B
+ B --> C
+ C --> D
+```
diff --git a/tutorials/nanocoder-tutorial/06-configuration-customization.md b/tutorials/nanocoder-tutorial/06-configuration-customization.md
index d053879e..10f27a32 100644
--- a/tutorials/nanocoder-tutorial/06-configuration-customization.md
+++ b/tutorials/nanocoder-tutorial/06-configuration-customization.md
@@ -6,6 +6,7 @@ has_children: false
parent: "Nanocoder - AI Coding Agent Deep Dive"
---
+
# Chapter 6: Configuration & Customization
Welcome to **Chapter 6: Configuration & Customization**. In this part of **Nanocoder Tutorial: Building and Understanding AI Coding Agents**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
@@ -422,227 +423,182 @@ In [Chapter 7: Building Your Own Agent](07-building-your-own-agent.md), we'll pu
## Depth Expansion Playbook
-<!-- depth-expansion-v2 -->
-
-This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
-
-### Strategic Context
-
-- tutorial: **Nanocoder Tutorial: Building and Understanding AI Coding Agents**
-- tutorial slug: **nanocoder-tutorial**
-- chapter focus: **Chapter 6: Configuration & Customization**
-- system context: **Nanocoder Tutorial**
-- objective: move from surface-level usage to repeatable engineering operation
-
-### Architecture Decomposition
-
-1. Define the runtime boundary for `Chapter 6: Configuration & Customization`.
-2. Separate control-plane decisions from data-plane execution.
-3. Capture input contracts, transformation points, and output contracts.
-4. Trace state transitions across request lifecycle stages.
-5. Identify extension hooks and policy interception points.
-6. Map ownership boundaries for team and automation workflows.
-7. Specify rollback and recovery paths for unsafe changes.
-8. Track observability signals for correctness, latency, and cost.
-
-### Operator Decision Matrix
-
-| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
-|:--------------|:--------------|:------------------|:---------|
-| Runtime mode | managed defaults | explicit policy config | speed vs control |
-| State handling | local ephemeral | durable persisted state | simplicity vs auditability |
-| Tool integration | direct API use | mediated adapter layer | velocity vs governance |
-| Rollout method | manual change | staged + canary rollout | effort vs safety |
-| Incident response | best effort logs | runbooks + SLO alerts | cost vs reliability |
-
-### Failure Modes and Countermeasures
-
-| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
-|:-------------|:-------------|:-------------------|:---------------|
-| stale context | inconsistent outputs | missing refresh window | enforce context TTL and refresh hooks |
-| policy drift | unexpected execution | ad hoc overrides | centralize policy profiles |
-| auth mismatch | 401/403 bursts | credential sprawl | rotation schedule + scope minimization |
-| schema breakage | parser/validation errors | unmanaged upstream changes | contract tests per release |
-| retry storms | queue congestion | no backoff controls | jittered backoff + circuit breakers |
-| silent regressions | quality drop without alerts | weak baseline metrics | eval harness with thresholds |
-
-### Implementation Runbook
-
-1. Establish a reproducible baseline environment.
-2. Capture chapter-specific success criteria before changes.
-3. Implement minimal viable path with explicit interfaces.
-4. Add observability before expanding feature scope.
-5. Run deterministic tests for happy-path behavior.
-6. Inject failure scenarios for negative-path validation.
-7. Compare output quality against baseline snapshots.
-8. Promote through staged environments with rollback gates.
-9. Record operational lessons in release notes.
-
-### Quality Gate Checklist
-
-- [ ] chapter-level assumptions are explicit and testable
-- [ ] API/tool boundaries are documented with input/output examples
-- [ ] failure handling includes retry, timeout, and fallback policy
-- [ ] security controls include auth scopes and secret rotation plans
-- [ ] observability includes logs, metrics, traces, and alert thresholds
-- [ ] deployment guidance includes canary and rollback paths
-- [ ] docs include links to upstream sources and related tracks
-- [ ] post-release verification confirms expected behavior under load
-
-### Source Alignment
-
-- [Nanocoder Repository](https://github.com/Nano-Collective/nanocoder)
-- [Nanocoder Releases](https://github.com/Nano-Collective/nanocoder/releases)
-- [Nanocoder Documentation Directory](https://github.com/Nano-Collective/nanocoder/tree/main/docs)
-- [Nanocoder MCP Configuration Guide](https://github.com/Nano-Collective/nanocoder/blob/main/docs/mcp-configuration.md)
-- [Nano Collective Website](https://nanocollective.org/)
-
-### Cross-Tutorial Connection Map
-
-- [Aider Tutorial](../aider-tutorial/)
-- [Claude Code Tutorial](../claude-code-tutorial/)
-- [Continue Tutorial](../continue-tutorial/)
-- [OpenHands Tutorial](../openhands-tutorial/)
-- [Chapter 1: Getting Started](01-getting-started.md)
-
-### Advanced Practice Exercises
-
-1. Build a minimal end-to-end implementation for `Chapter 6: Configuration & Customization`.
-2. Add instrumentation and measure baseline latency and error rate.
-3. Introduce one controlled failure and confirm graceful recovery.
-4. Add policy constraints and verify they are enforced consistently.
-5. Run a staged rollout and document rollback decision criteria.
-
-### Review Questions
-
-1. Which execution boundary matters most for this chapter and why?
-2. What signal detects regressions earliest in your environment?
-3. What tradeoff did you make between delivery speed and governance?
-4. How would you recover from the highest-impact failure mode?
-5. What must be automated before scaling to team-wide adoption?
-
-### Scenario Playbook 1: Chapter 6: Configuration & Customization
-
-- tutorial context: **Nanocoder Tutorial: Building and Understanding AI Coding Agents**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 2: Chapter 6: Configuration & Customization
-
-- tutorial context: **Nanocoder Tutorial: Building and Understanding AI Coding Agents**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 3: Chapter 6: Configuration & Customization
-
-- tutorial context: **Nanocoder Tutorial: Building and Understanding AI Coding Agents**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 4: Chapter 6: Configuration & Customization
-
-- tutorial context: **Nanocoder Tutorial: Building and Understanding AI Coding Agents**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 5: Chapter 6: Configuration & Customization
-
-- tutorial context: **Nanocoder Tutorial: Building and Understanding AI Coding Agents**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 6: Chapter 6: Configuration & Customization
-
-- tutorial context: **Nanocoder Tutorial: Building and Understanding AI Coding Agents**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-## What Problem Does This Solve?
-
-Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for `config`, `patterns`, `provider` so behavior stays predictable as complexity grows.
-
-In practical terms, this chapter helps you avoid three common failures:
-
-- coupling core logic too tightly to one implementation path
-- missing the handoff boundaries between setup, execution, and validation
-- shipping changes without clear rollback or observability strategy
-
-After working through this chapter, you should be able to reason about `Chapter 6: Configuration & Customization` as an operating subsystem inside **Nanocoder Tutorial: Building and Understanding AI Coding Agents**, with explicit contracts for inputs, state transitions, and outputs.
-
-Use the implementation notes around `temperature`, `tools`, `ignore` as your checklist when adapting these patterns to your own repository.
-
-## How it Works Under the Hood
-
-Under the hood, `Chapter 6: Configuration & Customization` usually follows a repeatable control path:
-
-1. **Context bootstrap**: initialize runtime config and prerequisites for `config`.
-2. **Input normalization**: shape incoming data so `patterns` receives stable contracts.
-3. **Core execution**: run the main logic branch and propagate intermediate state through `provider`.
-4. **Policy and safety checks**: enforce limits, auth scopes, and failure boundaries.
-5. **Output composition**: return canonical result payloads for downstream consumers.
-6. **Operational telemetry**: emit logs/metrics needed for debugging and performance tuning.
-
-When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
-
-## Source Walkthrough
-
-Use the following upstream sources to verify implementation details while reading this chapter:
-
-- [Nanocoder Repository](https://github.com/Nano-Collective/nanocoder)
- Why it matters: authoritative reference on `Nanocoder Repository` (github.com).
-- [Nanocoder Releases](https://github.com/Nano-Collective/nanocoder/releases)
- Why it matters: authoritative reference on `Nanocoder Releases` (github.com).
-- [Nanocoder Documentation Directory](https://github.com/Nano-Collective/nanocoder/tree/main/docs)
- Why it matters: authoritative reference on `Nanocoder Documentation Directory` (github.com).
-- [Nanocoder MCP Configuration Guide](https://github.com/Nano-Collective/nanocoder/blob/main/docs/mcp-configuration.md)
- Why it matters: authoritative reference on `Nanocoder MCP Configuration Guide` (github.com).
-- [Nano Collective Website](https://nanocollective.org/)
- Why it matters: authoritative reference on `Nano Collective Website` (nanocollective.org).
-
-Suggested trace strategy:
-- search upstream code for `config` and `patterns` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
-
-## Chapter Connections
-
-- [Tutorial Index](README.md)
-- [Previous Chapter: Chapter 5: Context Management](05-context-management.md)
-- [Next Chapter: Chapter 7: Building Your Own Agent](07-building-your-own-agent.md)
-- [Main Catalog](../../README.md#-tutorial-catalog)
-- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
+## Source Code Walkthrough
+
+### `scripts/fetch-models.js`
+
+The `isCacheValid` function in [`scripts/fetch-models.js`](https://github.com/Nano-Collective/nanocoder/blob/HEAD/scripts/fetch-models.js) handles a key part of this chapter's functionality:
+
+```js
+ * Check if existing cache is valid
+ */
+function isCacheValid() {
+ try {
+ if (!fs.existsSync(cacheFilePath)) {
+ return false;
+ }
+
+ const content = fs.readFileSync(cacheFilePath, 'utf-8');
+ const cached = JSON.parse(content);
+
+ return Date.now() < cached.expiresAt;
+ } catch {
+ return false;
+ }
+}
+
+/**
+ * Main execution
+ */
+async function main() {
+ // Skip if in CI environment (don't spam models.dev API)
+ if (process.env.CI === 'true') {
+ console.log('ℹ️ Skipping models.dev fetch in CI environment');
+ return;
+ }
+
+ // Check if cache is still valid
+ if (isCacheValid()) {
+ console.log('✅ Models cache is still valid, skipping fetch');
+ return;
+ }
+```
+
+This function is important because it defines how Nanocoder Tutorial: Building and Understanding AI Coding Agents implements the patterns covered in this chapter.
+
+### `scripts/fetch-models.js`
+
+The `main` function in [`scripts/fetch-models.js`](https://github.com/Nano-Collective/nanocoder/blob/HEAD/scripts/fetch-models.js) handles a key part of this chapter's functionality:
+
+```js
+ * Main execution
+ */
+async function main() {
+ // Skip if in CI environment (don't spam models.dev API)
+ if (process.env.CI === 'true') {
+ console.log('ℹ️ Skipping models.dev fetch in CI environment');
+ return;
+ }
+
+ // Check if cache is still valid
+ if (isCacheValid()) {
+ console.log('✅ Models cache is still valid, skipping fetch');
+ return;
+ }
+
+ // Fetch and cache models data
+ const data = await fetchModels();
+
+ if (data) {
+ writeCache(data);
+ } else {
+ console.log('ℹ️ Installation will continue without model metadata cache');
+ console.log('ℹ️ Model metadata will be fetched on first use');
+ }
+}
+
+// Run the script
+main().catch(error => {
+ // Don't fail the installation if this script fails
+ console.error('⚠️ Post-install script error:', error.message);
+ process.exit(0); // Exit with success to not break installation
+});
+```
+
+This function is important because it defines how Nanocoder Tutorial: Building and Understanding AI Coding Agents implements the patterns covered in this chapter.
+
+### `source/prompt-history.ts`
+
+The `PromptHistory` class in [`source/prompt-history.ts`](https://github.com/Nano-Collective/nanocoder/blob/HEAD/source/prompt-history.ts) handles a key part of this chapter's functionality:
+
+```ts
+const JSON_FORMAT_MARKER = '---JSON_FORMAT---';
+
+export class PromptHistory {
+ private history: InputState[] = [];
+ private currentIndex: number = -1;
+ private readonly historyFile: string;
+ private savePromise: Promise<void> = Promise.resolve();
+
+ constructor(historyFile?: string) {
+ this.historyFile =
+ historyFile ?? getClosestConfigFile('.nano-coder-history');
+ }
+
+ async loadHistory(): Promise<void> {
+ try {
+ const content = await fs.readFile(this.historyFile, 'utf8');
+
+ if (content.startsWith(JSON_FORMAT_MARKER)) {
+ // New JSON format with InputState objects
+ const jsonContent = content.slice(JSON_FORMAT_MARKER.length);
+ this.history = JSON.parse(jsonContent) as InputState[];
+ } else if (content.includes(ENTRY_SEPARATOR)) {
+ // Legacy format with separator - migrate to InputState
+ const stringEntries = content
+ .split(ENTRY_SEPARATOR)
+ .filter(entry => entry.trim() !== '');
+ this.history = this.migrateStringArrayToInputState(stringEntries);
+ } else {
+ // Very old format - single lines - migrate to InputState
+ const stringEntries = content
+ .split('\n')
+ .filter(line => line.trim() !== '');
+```
+
+This class is important because it defines how Nanocoder Tutorial: Building and Understanding AI Coding Agents implements the patterns covered in this chapter.
+
+### `.husky/pre-commit.js`
+
+The `getPlatformPaths` function in [`.husky/pre-commit.js`](https://github.com/Nano-Collective/nanocoder/blob/HEAD/.husky/pre-commit.js) handles a key part of this chapter's functionality:
+
+```js
+ */
+
+function getPlatformPaths() {
+ const platform = os.platform();
+
+ if (platform === 'win32') {
+ // Windows paths
+ const homeDir = process.env.USERPROFILE || process.env.HOMEPATH;
+ const appData = process.env.APPDATA;
+ const localAppData = process.env.LOCALAPPDATA;
+
+ const paths = [];
+
+ // Add common Windows pnpm locations
+ if (localAppData) {
+ paths.push(join(localAppData, 'pnpm'));
+ }
+ if (appData) {
+ paths.push(join(appData, 'pnpm'));
+ }
+
+ // Add common system paths
+ paths.push('C:\\Program Files\\nodejs');
+ paths.push('C:\\Program Files\\Git\\usr\\bin');
+
+ return paths;
+ } else {
+ // Unix-like systems (Linux, macOS)
+ const homeDir = process.env.HOME || process.env.USERPROFILE;
+ const paths = [];
+
+ if (homeDir) {
+```
+
+This function is important because it defines how Nanocoder Tutorial: Building and Understanding AI Coding Agents implements the patterns covered in this chapter.
+
+
+## How These Components Connect
+
+```mermaid
+flowchart TD
+ A[isCacheValid]
+ B[main]
+ C[PromptHistory]
+ D[getPlatformPaths]
+ A --> B
+ B --> C
+ C --> D
+```
diff --git a/tutorials/nocodb-tutorial/01-system-overview.md b/tutorials/nocodb-tutorial/01-system-overview.md
index 53f7fbd4..5ac5edf8 100644
--- a/tutorials/nocodb-tutorial/01-system-overview.md
+++ b/tutorials/nocodb-tutorial/01-system-overview.md
@@ -6,6 +6,7 @@ has_children: false
parent: "NocoDB Database Platform"
---
+
# Chapter 1: NocoDB System Overview
Welcome to **Chapter 1: NocoDB System Overview**. In this part of **NocoDB: Deep Dive Tutorial**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
@@ -486,106 +487,96 @@ Suggested trace strategy:
## Depth Expansion Playbook
-<!-- depth-expansion-v2 -->
-
-This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
-
-### Strategic Context
-
-- tutorial: **NocoDB: Deep Dive Tutorial**
-- tutorial slug: **nocodb-tutorial**
-- chapter focus: **Chapter 1: NocoDB System Overview**
-- system context: **Nocodb Database Platform**
-- objective: move from surface-level usage to repeatable engineering operation
-
-### Architecture Decomposition
-
-1. Define the runtime boundary for `Chapter 1: NocoDB System Overview`.
-2. Separate control-plane decisions from data-plane execution.
-3. Capture input contracts, transformation points, and output contracts.
-4. Trace state transitions across request lifecycle stages.
-5. Identify extension hooks and policy interception points.
-6. Map ownership boundaries for team and automation workflows.
-7. Specify rollback and recovery paths for unsafe changes.
-8. Track observability signals for correctness, latency, and cost.
-
-### Operator Decision Matrix
-
-| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
-|:--------------|:--------------|:------------------|:---------|
-| Runtime mode | managed defaults | explicit policy config | speed vs control |
-| State handling | local ephemeral | durable persisted state | simplicity vs auditability |
-| Tool integration | direct API use | mediated adapter layer | velocity vs governance |
-| Rollout method | manual change | staged + canary rollout | effort vs safety |
-| Incident response | best effort logs | runbooks + SLO alerts | cost vs reliability |
-
-### Failure Modes and Countermeasures
-
-| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
-|:-------------|:-------------|:-------------------|:---------------|
-| stale context | inconsistent outputs | missing refresh window | enforce context TTL and refresh hooks |
-| policy drift | unexpected execution | ad hoc overrides | centralize policy profiles |
-| auth mismatch | 401/403 bursts | credential sprawl | rotation schedule + scope minimization |
-| schema breakage | parser/validation errors | unmanaged upstream changes | contract tests per release |
-| retry storms | queue congestion | no backoff controls | jittered backoff + circuit breakers |
-| silent regressions | quality drop without alerts | weak baseline metrics | eval harness with thresholds |
-
-### Implementation Runbook
-
-1. Establish a reproducible baseline environment.
-2. Capture chapter-specific success criteria before changes.
-3. Implement minimal viable path with explicit interfaces.
-4. Add observability before expanding feature scope.
-5. Run deterministic tests for happy-path behavior.
-6. Inject failure scenarios for negative-path validation.
-7. Compare output quality against baseline snapshots.
-8. Promote through staged environments with rollback gates.
-9. Record operational lessons in release notes.
-
-### Quality Gate Checklist
-
-- [ ] chapter-level assumptions are explicit and testable
-- [ ] API/tool boundaries are documented with input/output examples
-- [ ] failure handling includes retry, timeout, and fallback policy
-- [ ] security controls include auth scopes and secret rotation plans
-- [ ] observability includes logs, metrics, traces, and alert thresholds
-- [ ] deployment guidance includes canary and rollback paths
-- [ ] docs include links to upstream sources and related tracks
-- [ ] post-release verification confirms expected behavior under load
-
-### Source Alignment
-
-- [NocoDB](https://github.com/nocodb/nocodb)
-- [AI Codebase Knowledge Builder](https://github.com/The-Pocket/Tutorial-Codebase-Knowledge)
-
-### Cross-Tutorial Connection Map
-
-- Related tutorials are listed in this tutorial index.
-
-### Advanced Practice Exercises
+## Source Code Walkthrough
+
+### `packages/nc-gui/nuxt.config.ts`
+
+The `for` interface in [`packages/nc-gui/nuxt.config.ts`](https://github.com/nocodb/nocodb/blob/HEAD/packages/nc-gui/nuxt.config.ts) handles a key part of this chapter's functionality:
+
+```ts
+ layoutTransition: false,
+
+ /** In production build we need to load assets using absolute path for history-mode routing */
+ cdnURL: process.env.NODE_ENV === 'production' ? process.env.NC_CDN_URL || '/' : undefined,
+ head: {
+ link: [
+ {
+ rel: 'icon',
+ type: 'image/x-icon',
+ href: '/favicon.ico',
+ },
+ {
+ rel: 'apple-touch-icon',
+ href: '/apple-touch-icon-180x180.png',
+ sizes: '180x180',
+ },
+
+ ...(process.env.NC_CDN_URL
+ ? [
+ {
+ rel: 'preload',
+ as: 'font',
+ href: new URL('/shared/style/material.woff2', process.env.NC_CDN_URL).href,
+ type: 'font/woff2',
+ crossorigin: 'anonymous',
+ } as any,
+ { rel: 'stylesheet', href: new URL('/shared/style/fonts-new.css', process.env.NC_CDN_URL).href },
+ ]
+ : []),
+ ],
+ meta: [
+ { charset: 'utf-8' },
+```
-1. Build a minimal end-to-end implementation for `Chapter 1: NocoDB System Overview`.
-2. Add instrumentation and measure baseline latency and error rate.
-3. Introduce one controlled failure and confirm graceful recovery.
-4. Add policy constraints and verify they are enforced consistently.
-5. Run a staged rollout and document rollback decision criteria.
+This interface is important because it defines how NocoDB: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+### `packages/nc-gui/nuxt.config.ts`
+
+The `for` interface in [`packages/nc-gui/nuxt.config.ts`](https://github.com/nocodb/nocodb/blob/HEAD/packages/nc-gui/nuxt.config.ts) handles a key part of this chapter's functionality:
+
+```ts
+ layoutTransition: false,
+
+ /** In production build we need to load assets using absolute path for history-mode routing */
+ cdnURL: process.env.NODE_ENV === 'production' ? process.env.NC_CDN_URL || '/' : undefined,
+ head: {
+ link: [
+ {
+ rel: 'icon',
+ type: 'image/x-icon',
+ href: '/favicon.ico',
+ },
+ {
+ rel: 'apple-touch-icon',
+ href: '/apple-touch-icon-180x180.png',
+ sizes: '180x180',
+ },
+
+ ...(process.env.NC_CDN_URL
+ ? [
+ {
+ rel: 'preload',
+ as: 'font',
+ href: new URL('/shared/style/material.woff2', process.env.NC_CDN_URL).href,
+ type: 'font/woff2',
+ crossorigin: 'anonymous',
+ } as any,
+ { rel: 'stylesheet', href: new URL('/shared/style/fonts-new.css', process.env.NC_CDN_URL).href },
+ ]
+ : []),
+ ],
+ meta: [
+ { charset: 'utf-8' },
+```
-### Review Questions
+This interface is important because it defines how NocoDB: Deep Dive Tutorial implements the patterns covered in this chapter.
-1. Which execution boundary matters most for this chapter and why?
-2. What signal detects regressions earliest in your environment?
-3. What tradeoff did you make between delivery speed and governance?
-4. How would you recover from the highest-impact failure mode?
-5. What must be automated before scaling to team-wide adoption?
-### Scenario Playbook 1: Chapter 1: NocoDB System Overview
+## How These Components Connect
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
+```mermaid
+flowchart TD
+ A[for]
+ B[for]
+ A --> B
+```
diff --git a/tutorials/nocodb-tutorial/05-query-builder.md b/tutorials/nocodb-tutorial/05-query-builder.md
index 523388eb..10808729 100644
--- a/tutorials/nocodb-tutorial/05-query-builder.md
+++ b/tutorials/nocodb-tutorial/05-query-builder.md
@@ -6,6 +6,7 @@ has_children: false
parent: "NocoDB Database Platform"
---
+
# Chapter 5: Query Builder
Welcome to **Chapter 5: Query Builder**. In this part of **NocoDB: Deep Dive Tutorial**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
@@ -96,490 +97,94 @@ Suggested trace strategy:
## Depth Expansion Playbook
-<!-- depth-expansion-v2 -->
-
-This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
-
-### Strategic Context
-
-- tutorial: **NocoDB: Deep Dive Tutorial**
-- tutorial slug: **nocodb-tutorial**
-- chapter focus: **Chapter 5: Query Builder**
-- system context: **Nocodb Database Platform**
-- objective: move from surface-level usage to repeatable engineering operation
-
-### Architecture Decomposition
-
-1. Define the runtime boundary for `Chapter 5: Query Builder`.
-2. Separate control-plane decisions from data-plane execution.
-3. Capture input contracts, transformation points, and output contracts.
-4. Trace state transitions across request lifecycle stages.
-5. Identify extension hooks and policy interception points.
-6. Map ownership boundaries for team and automation workflows.
-7. Specify rollback and recovery paths for unsafe changes.
-8. Track observability signals for correctness, latency, and cost.
-
-### Operator Decision Matrix
-
-| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
-|:--------------|:--------------|:------------------|:---------|
-| Runtime mode | managed defaults | explicit policy config | speed vs control |
-| State handling | local ephemeral | durable persisted state | simplicity vs auditability |
-| Tool integration | direct API use | mediated adapter layer | velocity vs governance |
-| Rollout method | manual change | staged + canary rollout | effort vs safety |
-| Incident response | best effort logs | runbooks + SLO alerts | cost vs reliability |
-
-### Failure Modes and Countermeasures
-
-| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
-|:-------------|:-------------|:-------------------|:---------------|
-| stale context | inconsistent outputs | missing refresh window | enforce context TTL and refresh hooks |
-| policy drift | unexpected execution | ad hoc overrides | centralize policy profiles |
-| auth mismatch | 401/403 bursts | credential sprawl | rotation schedule + scope minimization |
-| schema breakage | parser/validation errors | unmanaged upstream changes | contract tests per release |
-| retry storms | queue congestion | no backoff controls | jittered backoff + circuit breakers |
-| silent regressions | quality drop without alerts | weak baseline metrics | eval harness with thresholds |
-
-### Implementation Runbook
-
-1. Establish a reproducible baseline environment.
-2. Capture chapter-specific success criteria before changes.
-3. Implement minimal viable path with explicit interfaces.
-4. Add observability before expanding feature scope.
-5. Run deterministic tests for happy-path behavior.
-6. Inject failure scenarios for negative-path validation.
-7. Compare output quality against baseline snapshots.
-8. Promote through staged environments with rollback gates.
-9. Record operational lessons in release notes.
-
-### Quality Gate Checklist
-
-- [ ] chapter-level assumptions are explicit and testable
-- [ ] API/tool boundaries are documented with input/output examples
-- [ ] failure handling includes retry, timeout, and fallback policy
-- [ ] security controls include auth scopes and secret rotation plans
-- [ ] observability includes logs, metrics, traces, and alert thresholds
-- [ ] deployment guidance includes canary and rollback paths
-- [ ] docs include links to upstream sources and related tracks
-- [ ] post-release verification confirms expected behavior under load
-
-### Source Alignment
-
-- [NocoDB](https://github.com/nocodb/nocodb)
-- [AI Codebase Knowledge Builder](https://github.com/The-Pocket/Tutorial-Codebase-Knowledge)
-
-### Cross-Tutorial Connection Map
-
-- Related tutorials are listed in this tutorial index.
-
-### Advanced Practice Exercises
-
-1. Build a minimal end-to-end implementation for `Chapter 5: Query Builder`.
-2. Add instrumentation and measure baseline latency and error rate.
-3. Introduce one controlled failure and confirm graceful recovery.
-4. Add policy constraints and verify they are enforced consistently.
-5. Run a staged rollout and document rollback decision criteria.
-
-### Review Questions
-
-1. Which execution boundary matters most for this chapter and why?
-2. What signal detects regressions earliest in your environment?
-3. What tradeoff did you make between delivery speed and governance?
-4. How would you recover from the highest-impact failure mode?
-5. What must be automated before scaling to team-wide adoption?
-
-### Scenario Playbook 1: Chapter 5: Query Builder
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 2: Chapter 5: Query Builder
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 3: Chapter 5: Query Builder
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 4: Chapter 5: Query Builder
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 5: Chapter 5: Query Builder
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 6: Chapter 5: Query Builder
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 7: Chapter 5: Query Builder
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 8: Chapter 5: Query Builder
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 9: Chapter 5: Query Builder
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 10: Chapter 5: Query Builder
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 11: Chapter 5: Query Builder
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 12: Chapter 5: Query Builder
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 13: Chapter 5: Query Builder
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 14: Chapter 5: Query Builder
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 15: Chapter 5: Query Builder
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 16: Chapter 5: Query Builder
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 17: Chapter 5: Query Builder
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 18: Chapter 5: Query Builder
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 19: Chapter 5: Query Builder
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 20: Chapter 5: Query Builder
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 21: Chapter 5: Query Builder
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 22: Chapter 5: Query Builder
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 23: Chapter 5: Query Builder
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 24: Chapter 5: Query Builder
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 25: Chapter 5: Query Builder
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 26: Chapter 5: Query Builder
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 27: Chapter 5: Query Builder
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 28: Chapter 5: Query Builder
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 29: Chapter 5: Query Builder
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 30: Chapter 5: Query Builder
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 31: Chapter 5: Query Builder
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 32: Chapter 5: Query Builder
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 33: Chapter 5: Query Builder
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
+## Source Code Walkthrough
+
+### `packages/noco-integrations/nocodb-sdk-reference.ts`
+
+The `FormBuilderElement` interface in [`packages/noco-integrations/nocodb-sdk-reference.ts`](https://github.com/nocodb/nocodb/blob/HEAD/packages/noco-integrations/nocodb-sdk-reference.ts) handles a key part of this chapter's functionality:
+
+```ts
+}
+
+export interface FormBuilderElement {
+ // element type
+ type: FormBuilderInputType;
+ // property path in the form JSON
+ model?: string;
+ // default value
+ defaultValue?: string[] | string | boolean | number | null;
+ // label for the element
+ label?: string;
+ // placeholder for the element (if applicable)
+ placeholder?: string;
+ // percentage width of the element
+ width?: number;
+ // category of the element - same category elements are grouped together
+ category?: string;
+ // help text for the element
+ // options for select element
+ options?: { value: string; label: string }[];
+ // select mode for the element (if applicable) - default is single
+ selectMode?: 'single' | 'multiple' | 'multipleWithInput';
+ // integration type filter for integration element
+ integrationFilter?: {
+ type?: string;
+ sub_type?: string;
+ };
+ // oauth meta
+ oauthMeta?: {
+ // oauth provider
+ provider: string;
+ // oauth auth uri
+```
+
+This interface is important because it defines how NocoDB: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+### `packages/noco-integrations/nocodb-sdk-reference.ts`
+
+The `SyncType` interface in [`packages/noco-integrations/nocodb-sdk-reference.ts`](https://github.com/nocodb/nocodb/blob/HEAD/packages/noco-integrations/nocodb-sdk-reference.ts) handles a key part of this chapter's functionality:
+
+```ts
+export enum SyncType {
+ Full = 'full',
+ Incremental = 'incremental',
+}
+
+export enum SyncTrigger {
+ Manual = 'manual',
+ Schedule = 'schedule',
+ Webhook = 'webhook',
+}
+
+export enum OnDeleteAction {
+ Delete = 'delete',
+ MarkDeleted = 'mark_deleted',
+}
+
+export enum SyncCategory {
+ TICKETING = 'ticketing',
+ CRM = 'crm',
+ FILE_STORAGE = 'file_storage',
+ CUSTOM = 'custom',
+}
+
+export const SyncTriggerMeta = {
+ [SyncTrigger.Manual]: {
+ value: SyncTrigger.Manual,
+ label: 'Manual',
+ description: 'Sync data manually',
+ },
+ [SyncTrigger.Schedule]: {
+```
+
+This interface is important because it defines how NocoDB: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+
+## How These Components Connect
+
+```mermaid
+flowchart TD
+ A[FormBuilderElement]
+ B[SyncType]
+ A --> B
+```
diff --git a/tutorials/nocodb-tutorial/06-auth-system.md b/tutorials/nocodb-tutorial/06-auth-system.md
index c84fbe70..d4f5036d 100644
--- a/tutorials/nocodb-tutorial/06-auth-system.md
+++ b/tutorials/nocodb-tutorial/06-auth-system.md
@@ -6,6 +6,7 @@ has_children: false
parent: "NocoDB Database Platform"
---
+
# Chapter 6: Auth System
Welcome to **Chapter 6: Auth System**. In this part of **NocoDB: Deep Dive Tutorial**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
@@ -97,490 +98,96 @@ Suggested trace strategy:
## Depth Expansion Playbook
-<!-- depth-expansion-v2 -->
-
-This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
-
-### Strategic Context
-
-- tutorial: **NocoDB: Deep Dive Tutorial**
-- tutorial slug: **nocodb-tutorial**
-- chapter focus: **Chapter 6: Auth System**
-- system context: **Nocodb Database Platform**
-- objective: move from surface-level usage to repeatable engineering operation
-
-### Architecture Decomposition
-
-1. Define the runtime boundary for `Chapter 6: Auth System`.
-2. Separate control-plane decisions from data-plane execution.
-3. Capture input contracts, transformation points, and output contracts.
-4. Trace state transitions across request lifecycle stages.
-5. Identify extension hooks and policy interception points.
-6. Map ownership boundaries for team and automation workflows.
-7. Specify rollback and recovery paths for unsafe changes.
-8. Track observability signals for correctness, latency, and cost.
-
-### Operator Decision Matrix
-
-| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
-|:--------------|:--------------|:------------------|:---------|
-| Runtime mode | managed defaults | explicit policy config | speed vs control |
-| State handling | local ephemeral | durable persisted state | simplicity vs auditability |
-| Tool integration | direct API use | mediated adapter layer | velocity vs governance |
-| Rollout method | manual change | staged + canary rollout | effort vs safety |
-| Incident response | best effort logs | runbooks + SLO alerts | cost vs reliability |
-
-### Failure Modes and Countermeasures
-
-| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
-|:-------------|:-------------|:-------------------|:---------------|
-| stale context | inconsistent outputs | missing refresh window | enforce context TTL and refresh hooks |
-| policy drift | unexpected execution | ad hoc overrides | centralize policy profiles |
-| auth mismatch | 401/403 bursts | credential sprawl | rotation schedule + scope minimization |
-| schema breakage | parser/validation errors | unmanaged upstream changes | contract tests per release |
-| retry storms | queue congestion | no backoff controls | jittered backoff + circuit breakers |
-| silent regressions | quality drop without alerts | weak baseline metrics | eval harness with thresholds |
-
-### Implementation Runbook
-
-1. Establish a reproducible baseline environment.
-2. Capture chapter-specific success criteria before changes.
-3. Implement minimal viable path with explicit interfaces.
-4. Add observability before expanding feature scope.
-5. Run deterministic tests for happy-path behavior.
-6. Inject failure scenarios for negative-path validation.
-7. Compare output quality against baseline snapshots.
-8. Promote through staged environments with rollback gates.
-9. Record operational lessons in release notes.
-
-### Quality Gate Checklist
-
-- [ ] chapter-level assumptions are explicit and testable
-- [ ] API/tool boundaries are documented with input/output examples
-- [ ] failure handling includes retry, timeout, and fallback policy
-- [ ] security controls include auth scopes and secret rotation plans
-- [ ] observability includes logs, metrics, traces, and alert thresholds
-- [ ] deployment guidance includes canary and rollback paths
-- [ ] docs include links to upstream sources and related tracks
-- [ ] post-release verification confirms expected behavior under load
-
-### Source Alignment
-
-- [NocoDB](https://github.com/nocodb/nocodb)
-- [AI Codebase Knowledge Builder](https://github.com/The-Pocket/Tutorial-Codebase-Knowledge)
-
-### Cross-Tutorial Connection Map
-
-- Related tutorials are listed in this tutorial index.
-
-### Advanced Practice Exercises
-
-1. Build a minimal end-to-end implementation for `Chapter 6: Auth System`.
-2. Add instrumentation and measure baseline latency and error rate.
-3. Introduce one controlled failure and confirm graceful recovery.
-4. Add policy constraints and verify they are enforced consistently.
-5. Run a staged rollout and document rollback decision criteria.
-
-### Review Questions
-
-1. Which execution boundary matters most for this chapter and why?
-2. What signal detects regressions earliest in your environment?
-3. What tradeoff did you make between delivery speed and governance?
-4. How would you recover from the highest-impact failure mode?
-5. What must be automated before scaling to team-wide adoption?
-
-### Scenario Playbook 1: Chapter 6: Auth System
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 2: Chapter 6: Auth System
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 3: Chapter 6: Auth System
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 4: Chapter 6: Auth System
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 5: Chapter 6: Auth System
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 6: Chapter 6: Auth System
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 7: Chapter 6: Auth System
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 8: Chapter 6: Auth System
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 9: Chapter 6: Auth System
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 10: Chapter 6: Auth System
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 11: Chapter 6: Auth System
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 12: Chapter 6: Auth System
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 13: Chapter 6: Auth System
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 14: Chapter 6: Auth System
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 15: Chapter 6: Auth System
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 16: Chapter 6: Auth System
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 17: Chapter 6: Auth System
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 18: Chapter 6: Auth System
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 19: Chapter 6: Auth System
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 20: Chapter 6: Auth System
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 21: Chapter 6: Auth System
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 22: Chapter 6: Auth System
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 23: Chapter 6: Auth System
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 24: Chapter 6: Auth System
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 25: Chapter 6: Auth System
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 26: Chapter 6: Auth System
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 27: Chapter 6: Auth System
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 28: Chapter 6: Auth System
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 29: Chapter 6: Auth System
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 30: Chapter 6: Auth System
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 31: Chapter 6: Auth System
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 32: Chapter 6: Auth System
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 33: Chapter 6: Auth System
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
+## Source Code Walkthrough
+
+### `packages/noco-integrations/nocodb-sdk-reference.ts`
+
+The `SyncTrigger` interface in [`packages/noco-integrations/nocodb-sdk-reference.ts`](https://github.com/nocodb/nocodb/blob/HEAD/packages/noco-integrations/nocodb-sdk-reference.ts) handles a key part of this chapter's functionality:
+
+```ts
+}
+
+export enum SyncTrigger {
+ Manual = 'manual',
+ Schedule = 'schedule',
+ Webhook = 'webhook',
+}
+
+export enum OnDeleteAction {
+ Delete = 'delete',
+ MarkDeleted = 'mark_deleted',
+}
+
+export enum SyncCategory {
+ TICKETING = 'ticketing',
+ CRM = 'crm',
+ FILE_STORAGE = 'file_storage',
+ CUSTOM = 'custom',
+}
+
+export const SyncTriggerMeta = {
+ [SyncTrigger.Manual]: {
+ value: SyncTrigger.Manual,
+ label: 'Manual',
+ description: 'Sync data manually',
+ },
+ [SyncTrigger.Schedule]: {
+ value: SyncTrigger.Schedule,
+ label: 'Scheduled',
+ description: 'Sync data on a schedule',
+ },
+ [SyncTrigger.Webhook]: {
+```
+
+This interface is important because it defines how NocoDB: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+### `packages/noco-integrations/nocodb-sdk-reference.ts`
+
+The `OnDeleteAction` interface in [`packages/noco-integrations/nocodb-sdk-reference.ts`](https://github.com/nocodb/nocodb/blob/HEAD/packages/noco-integrations/nocodb-sdk-reference.ts) handles a key part of this chapter's functionality:
+
+```ts
+}
+
+export enum OnDeleteAction {
+ Delete = 'delete',
+ MarkDeleted = 'mark_deleted',
+}
+
+export enum SyncCategory {
+ TICKETING = 'ticketing',
+ CRM = 'crm',
+ FILE_STORAGE = 'file_storage',
+ CUSTOM = 'custom',
+}
+
+export const SyncTriggerMeta = {
+ [SyncTrigger.Manual]: {
+ value: SyncTrigger.Manual,
+ label: 'Manual',
+ description: 'Sync data manually',
+ },
+ [SyncTrigger.Schedule]: {
+ value: SyncTrigger.Schedule,
+ label: 'Scheduled',
+ description: 'Sync data on a schedule',
+ },
+ [SyncTrigger.Webhook]: {
+ value: SyncTrigger.Webhook,
+ label: 'Webhook',
+ description: 'Sync data via a webhook',
+ },
+};
+
+```
+
+This interface is important because it defines how NocoDB: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+
+## How These Components Connect
+
+```mermaid
+flowchart TD
+ A[SyncTrigger]
+ B[OnDeleteAction]
+ A --> B
+```
diff --git a/tutorials/nocodb-tutorial/07-vue-components.md b/tutorials/nocodb-tutorial/07-vue-components.md
index 17e24228..b8a4e067 100644
--- a/tutorials/nocodb-tutorial/07-vue-components.md
+++ b/tutorials/nocodb-tutorial/07-vue-components.md
@@ -6,6 +6,7 @@ has_children: false
parent: "NocoDB Database Platform"
---
+
# Chapter 7: Vue Components
Welcome to **Chapter 7: Vue Components**. In this part of **NocoDB: Deep Dive Tutorial**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
@@ -95,490 +96,96 @@ Suggested trace strategy:
## Depth Expansion Playbook
-<!-- depth-expansion-v2 -->
-
-This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
-
-### Strategic Context
-
-- tutorial: **NocoDB: Deep Dive Tutorial**
-- tutorial slug: **nocodb-tutorial**
-- chapter focus: **Chapter 7: Vue Components**
-- system context: **Nocodb Database Platform**
-- objective: move from surface-level usage to repeatable engineering operation
-
-### Architecture Decomposition
-
-1. Define the runtime boundary for `Chapter 7: Vue Components`.
-2. Separate control-plane decisions from data-plane execution.
-3. Capture input contracts, transformation points, and output contracts.
-4. Trace state transitions across request lifecycle stages.
-5. Identify extension hooks and policy interception points.
-6. Map ownership boundaries for team and automation workflows.
-7. Specify rollback and recovery paths for unsafe changes.
-8. Track observability signals for correctness, latency, and cost.
-
-### Operator Decision Matrix
-
-| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
-|:--------------|:--------------|:------------------|:---------|
-| Runtime mode | managed defaults | explicit policy config | speed vs control |
-| State handling | local ephemeral | durable persisted state | simplicity vs auditability |
-| Tool integration | direct API use | mediated adapter layer | velocity vs governance |
-| Rollout method | manual change | staged + canary rollout | effort vs safety |
-| Incident response | best effort logs | runbooks + SLO alerts | cost vs reliability |
-
-### Failure Modes and Countermeasures
-
-| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
-|:-------------|:-------------|:-------------------|:---------------|
-| stale context | inconsistent outputs | missing refresh window | enforce context TTL and refresh hooks |
-| policy drift | unexpected execution | ad hoc overrides | centralize policy profiles |
-| auth mismatch | 401/403 bursts | credential sprawl | rotation schedule + scope minimization |
-| schema breakage | parser/validation errors | unmanaged upstream changes | contract tests per release |
-| retry storms | queue congestion | no backoff controls | jittered backoff + circuit breakers |
-| silent regressions | quality drop without alerts | weak baseline metrics | eval harness with thresholds |
-
-### Implementation Runbook
-
-1. Establish a reproducible baseline environment.
-2. Capture chapter-specific success criteria before changes.
-3. Implement minimal viable path with explicit interfaces.
-4. Add observability before expanding feature scope.
-5. Run deterministic tests for happy-path behavior.
-6. Inject failure scenarios for negative-path validation.
-7. Compare output quality against baseline snapshots.
-8. Promote through staged environments with rollback gates.
-9. Record operational lessons in release notes.
-
-### Quality Gate Checklist
-
-- [ ] chapter-level assumptions are explicit and testable
-- [ ] API/tool boundaries are documented with input/output examples
-- [ ] failure handling includes retry, timeout, and fallback policy
-- [ ] security controls include auth scopes and secret rotation plans
-- [ ] observability includes logs, metrics, traces, and alert thresholds
-- [ ] deployment guidance includes canary and rollback paths
-- [ ] docs include links to upstream sources and related tracks
-- [ ] post-release verification confirms expected behavior under load
-
-### Source Alignment
-
-- [NocoDB](https://github.com/nocodb/nocodb)
-- [AI Codebase Knowledge Builder](https://github.com/The-Pocket/Tutorial-Codebase-Knowledge)
-
-### Cross-Tutorial Connection Map
-
-- Related tutorials are listed in this tutorial index.
-
-### Advanced Practice Exercises
-
-1. Build a minimal end-to-end implementation for `Chapter 7: Vue Components`.
-2. Add instrumentation and measure baseline latency and error rate.
-3. Introduce one controlled failure and confirm graceful recovery.
-4. Add policy constraints and verify they are enforced consistently.
-5. Run a staged rollout and document rollback decision criteria.
-
-### Review Questions
-
-1. Which execution boundary matters most for this chapter and why?
-2. What signal detects regressions earliest in your environment?
-3. What tradeoff did you make between delivery speed and governance?
-4. How would you recover from the highest-impact failure mode?
-5. What must be automated before scaling to team-wide adoption?
-
-### Scenario Playbook 1: Chapter 7: Vue Components
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 2: Chapter 7: Vue Components
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 3: Chapter 7: Vue Components
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 4: Chapter 7: Vue Components
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 5: Chapter 7: Vue Components
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 6: Chapter 7: Vue Components
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 7: Chapter 7: Vue Components
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 8: Chapter 7: Vue Components
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 9: Chapter 7: Vue Components
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 10: Chapter 7: Vue Components
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 11: Chapter 7: Vue Components
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 12: Chapter 7: Vue Components
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 13: Chapter 7: Vue Components
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 14: Chapter 7: Vue Components
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 15: Chapter 7: Vue Components
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 16: Chapter 7: Vue Components
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 17: Chapter 7: Vue Components
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 18: Chapter 7: Vue Components
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 19: Chapter 7: Vue Components
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 20: Chapter 7: Vue Components
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 21: Chapter 7: Vue Components
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 22: Chapter 7: Vue Components
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 23: Chapter 7: Vue Components
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 24: Chapter 7: Vue Components
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 25: Chapter 7: Vue Components
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 26: Chapter 7: Vue Components
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 27: Chapter 7: Vue Components
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 28: Chapter 7: Vue Components
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 29: Chapter 7: Vue Components
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 30: Chapter 7: Vue Components
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 31: Chapter 7: Vue Components
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 32: Chapter 7: Vue Components
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 33: Chapter 7: Vue Components
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
+## Source Code Walkthrough
+
+### `packages/noco-integrations/nocodb-sdk-reference.ts`
+
+The `SyncCategory` interface in [`packages/noco-integrations/nocodb-sdk-reference.ts`](https://github.com/nocodb/nocodb/blob/HEAD/packages/noco-integrations/nocodb-sdk-reference.ts) handles a key part of this chapter's functionality:
+
+```ts
+}
+
+export enum SyncCategory {
+ TICKETING = 'ticketing',
+ CRM = 'crm',
+ FILE_STORAGE = 'file_storage',
+ CUSTOM = 'custom',
+}
+
+export const SyncTriggerMeta = {
+ [SyncTrigger.Manual]: {
+ value: SyncTrigger.Manual,
+ label: 'Manual',
+ description: 'Sync data manually',
+ },
+ [SyncTrigger.Schedule]: {
+ value: SyncTrigger.Schedule,
+ label: 'Scheduled',
+ description: 'Sync data on a schedule',
+ },
+ [SyncTrigger.Webhook]: {
+ value: SyncTrigger.Webhook,
+ label: 'Webhook',
+ description: 'Sync data via a webhook',
+ },
+};
+
+export const OnDeleteActionMeta = {
+ [OnDeleteAction.MarkDeleted]: {
+ value: OnDeleteAction.MarkDeleted,
+ label: 'Ignore',
+ description: 'Keep records even if the source deletes them.',
+```
+
+This interface is important because it defines how NocoDB: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+### `packages/noco-integrations/nocodb-sdk-reference.ts`
+
+The `TARGET_TABLES` interface in [`packages/noco-integrations/nocodb-sdk-reference.ts`](https://github.com/nocodb/nocodb/blob/HEAD/packages/noco-integrations/nocodb-sdk-reference.ts) handles a key part of this chapter's functionality:
+
+```ts
+};
+
+export enum TARGET_TABLES {
+ TICKETING_TICKET = 'ticketing_ticket',
+ TICKETING_USER = 'ticketing_user',
+ TICKETING_COMMENT = 'ticketing_comment',
+ TICKETING_TEAM = 'ticketing_team',
+}
+
+export const TARGET_TABLES_META = {
+ [TARGET_TABLES.TICKETING_TICKET]: {
+ category: SyncCategory.TICKETING,
+ value: TARGET_TABLES.TICKETING_TICKET,
+ icon: 'ncBookOpen',
+ label: 'Ticket',
+ description: 'Sync all ticket data from the source',
+ required: true,
+ },
+ [TARGET_TABLES.TICKETING_USER]: {
+ category: SyncCategory.TICKETING,
+ value: TARGET_TABLES.TICKETING_USER,
+ icon: 'ncUsers',
+ label: 'User',
+ description: 'Sync all users on tickets from the source',
+ required: true,
+ },
+ [TARGET_TABLES.TICKETING_COMMENT]: {
+ category: SyncCategory.TICKETING,
+ value: TARGET_TABLES.TICKETING_COMMENT,
+ icon: 'ncMessageCircle',
+ label: 'Comment',
+ description: 'Sync all comments on tickets',
+```
+
+This interface is important because it defines how NocoDB: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+
+## How These Components Connect
+
+```mermaid
+flowchart TD
+ A[SyncCategory]
+ B[TARGET_TABLES]
+ A --> B
+```
diff --git a/tutorials/nocodb-tutorial/08-realtime-features.md b/tutorials/nocodb-tutorial/08-realtime-features.md
index ef3ba711..b61ecc15 100644
--- a/tutorials/nocodb-tutorial/08-realtime-features.md
+++ b/tutorials/nocodb-tutorial/08-realtime-features.md
@@ -6,6 +6,7 @@ has_children: false
parent: "NocoDB Database Platform"
---
+
# Chapter 8: Realtime Features
Welcome to **Chapter 8: Realtime Features**. In this part of **NocoDB: Deep Dive Tutorial**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
@@ -92,490 +93,96 @@ Suggested trace strategy:
## Depth Expansion Playbook
-<!-- depth-expansion-v2 -->
-
-This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
-
-### Strategic Context
-
-- tutorial: **NocoDB: Deep Dive Tutorial**
-- tutorial slug: **nocodb-tutorial**
-- chapter focus: **Chapter 8: Realtime Features**
-- system context: **Nocodb Database Platform**
-- objective: move from surface-level usage to repeatable engineering operation
-
-### Architecture Decomposition
-
-1. Define the runtime boundary for `Chapter 8: Realtime Features`.
-2. Separate control-plane decisions from data-plane execution.
-3. Capture input contracts, transformation points, and output contracts.
-4. Trace state transitions across request lifecycle stages.
-5. Identify extension hooks and policy interception points.
-6. Map ownership boundaries for team and automation workflows.
-7. Specify rollback and recovery paths for unsafe changes.
-8. Track observability signals for correctness, latency, and cost.
-
-### Operator Decision Matrix
-
-| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
-|:--------------|:--------------|:------------------|:---------|
-| Runtime mode | managed defaults | explicit policy config | speed vs control |
-| State handling | local ephemeral | durable persisted state | simplicity vs auditability |
-| Tool integration | direct API use | mediated adapter layer | velocity vs governance |
-| Rollout method | manual change | staged + canary rollout | effort vs safety |
-| Incident response | best effort logs | runbooks + SLO alerts | cost vs reliability |
-
-### Failure Modes and Countermeasures
-
-| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
-|:-------------|:-------------|:-------------------|:---------------|
-| stale context | inconsistent outputs | missing refresh window | enforce context TTL and refresh hooks |
-| policy drift | unexpected execution | ad hoc overrides | centralize policy profiles |
-| auth mismatch | 401/403 bursts | credential sprawl | rotation schedule + scope minimization |
-| schema breakage | parser/validation errors | unmanaged upstream changes | contract tests per release |
-| retry storms | queue congestion | no backoff controls | jittered backoff + circuit breakers |
-| silent regressions | quality drop without alerts | weak baseline metrics | eval harness with thresholds |
-
-### Implementation Runbook
-
-1. Establish a reproducible baseline environment.
-2. Capture chapter-specific success criteria before changes.
-3. Implement minimal viable path with explicit interfaces.
-4. Add observability before expanding feature scope.
-5. Run deterministic tests for happy-path behavior.
-6. Inject failure scenarios for negative-path validation.
-7. Compare output quality against baseline snapshots.
-8. Promote through staged environments with rollback gates.
-9. Record operational lessons in release notes.
-
-### Quality Gate Checklist
-
-- [ ] chapter-level assumptions are explicit and testable
-- [ ] API/tool boundaries are documented with input/output examples
-- [ ] failure handling includes retry, timeout, and fallback policy
-- [ ] security controls include auth scopes and secret rotation plans
-- [ ] observability includes logs, metrics, traces, and alert thresholds
-- [ ] deployment guidance includes canary and rollback paths
-- [ ] docs include links to upstream sources and related tracks
-- [ ] post-release verification confirms expected behavior under load
-
-### Source Alignment
-
-- [NocoDB](https://github.com/nocodb/nocodb)
-- [AI Codebase Knowledge Builder](https://github.com/The-Pocket/Tutorial-Codebase-Knowledge)
-
-### Cross-Tutorial Connection Map
-
-- Related tutorials are listed in this tutorial index.
-
-### Advanced Practice Exercises
-
-1. Build a minimal end-to-end implementation for `Chapter 8: Realtime Features`.
-2. Add instrumentation and measure baseline latency and error rate.
-3. Introduce one controlled failure and confirm graceful recovery.
-4. Add policy constraints and verify they are enforced consistently.
-5. Run a staged rollout and document rollback decision criteria.
-
-### Review Questions
-
-1. Which execution boundary matters most for this chapter and why?
-2. What signal detects regressions earliest in your environment?
-3. What tradeoff did you make between delivery speed and governance?
-4. How would you recover from the highest-impact failure mode?
-5. What must be automated before scaling to team-wide adoption?
-
-### Scenario Playbook 1: Chapter 8: Realtime Features
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 2: Chapter 8: Realtime Features
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 3: Chapter 8: Realtime Features
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 4: Chapter 8: Realtime Features
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 5: Chapter 8: Realtime Features
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 6: Chapter 8: Realtime Features
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 7: Chapter 8: Realtime Features
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 8: Chapter 8: Realtime Features
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 9: Chapter 8: Realtime Features
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 10: Chapter 8: Realtime Features
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 11: Chapter 8: Realtime Features
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 12: Chapter 8: Realtime Features
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 13: Chapter 8: Realtime Features
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 14: Chapter 8: Realtime Features
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 15: Chapter 8: Realtime Features
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 16: Chapter 8: Realtime Features
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 17: Chapter 8: Realtime Features
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 18: Chapter 8: Realtime Features
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 19: Chapter 8: Realtime Features
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 20: Chapter 8: Realtime Features
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 21: Chapter 8: Realtime Features
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 22: Chapter 8: Realtime Features
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 23: Chapter 8: Realtime Features
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 24: Chapter 8: Realtime Features
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 25: Chapter 8: Realtime Features
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 26: Chapter 8: Realtime Features
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 27: Chapter 8: Realtime Features
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 28: Chapter 8: Realtime Features
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 29: Chapter 8: Realtime Features
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 30: Chapter 8: Realtime Features
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 31: Chapter 8: Realtime Features
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 32: Chapter 8: Realtime Features
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 33: Chapter 8: Realtime Features
-
-- tutorial context: **NocoDB: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
+## Source Code Walkthrough
+
+### `packages/noco-integrations/nocodb-sdk-reference.ts`
+
+The `FormBuilderInputType` interface in [`packages/noco-integrations/nocodb-sdk-reference.ts`](https://github.com/nocodb/nocodb/blob/HEAD/packages/noco-integrations/nocodb-sdk-reference.ts) handles a key part of this chapter's functionality:
+
+```ts
+};
+
+export enum FormBuilderInputType {
+ Input = 'input',
+ Select = 'select',
+ Switch = 'switch',
+ Space = 'space',
+ Password = 'password',
+ SelectIntegration = 'integration',
+ SelectBase = 'select-base',
+ OAuth = 'oauth',
+}
+
+export interface FormBuilderCondition {
+ // model path to check for condition
+ model: string;
+ // value to check for condition
+ value?: string;
+ // check if the value is equal to the model value
+ equal?: string;
+ // check if the value is in the array
+ in?: string[];
+ // check if the value is empty
+ empty?: boolean;
+ // check if the value is not empty
+ notEmpty?: boolean;
+}
+
+export enum FormBuilderValidatorType {
+ Required = 'required',
+}
+
+```
+
+This interface is important because it defines how NocoDB: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+### `packages/noco-integrations/nocodb-sdk-reference.ts`
+
+The `FormBuilderValidatorType` interface in [`packages/noco-integrations/nocodb-sdk-reference.ts`](https://github.com/nocodb/nocodb/blob/HEAD/packages/noco-integrations/nocodb-sdk-reference.ts) handles a key part of this chapter's functionality:
+
+```ts
+}
+
+export enum FormBuilderValidatorType {
+ Required = 'required',
+}
+
+export interface FormBuilderElement {
+ // element type
+ type: FormBuilderInputType;
+ // property path in the form JSON
+ model?: string;
+ // default value
+ defaultValue?: string[] | string | boolean | number | null;
+ // label for the element
+ label?: string;
+ // placeholder for the element (if applicable)
+ placeholder?: string;
+ // percentage width of the element
+ width?: number;
+ // category of the element - same category elements are grouped together
+ category?: string;
+ // help text for the element
+ // options for select element
+ options?: { value: string; label: string }[];
+ // select mode for the element (if applicable) - default is single
+ selectMode?: 'single' | 'multiple' | 'multipleWithInput';
+ // integration type filter for integration element
+ integrationFilter?: {
+ type?: string;
+ sub_type?: string;
+ };
+ // oauth meta
+```
+
+This interface is important because it defines how NocoDB: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+
+## How These Components Connect
+
+```mermaid
+flowchart TD
+ A[FormBuilderInputType]
+ B[FormBuilderValidatorType]
+ A --> B
+```
diff --git a/tutorials/obsidian-outliner-tutorial/01-plugin-architecture.md b/tutorials/obsidian-outliner-tutorial/01-plugin-architecture.md
index e53721e1..d431adec 100644
--- a/tutorials/obsidian-outliner-tutorial/01-plugin-architecture.md
+++ b/tutorials/obsidian-outliner-tutorial/01-plugin-architecture.md
@@ -6,6 +6,7 @@ has_children: false
parent: "Obsidian Outliner Plugin"
---
+
# Chapter 1: Obsidian Plugin Architecture
Welcome to **Chapter 1: Obsidian Plugin Architecture**. In this part of **Obsidian Outliner Plugin: Deep Dive Tutorial**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
@@ -523,94 +524,184 @@ Suggested trace strategy:
## Depth Expansion Playbook
-<!-- depth-expansion-v2 -->
-
-This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
-
-### Strategic Context
-
-- tutorial: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- tutorial slug: **obsidian-outliner-tutorial**
-- chapter focus: **Chapter 1: Obsidian Plugin Architecture**
-- system context: **Obsidian Outliner Plugin**
-- objective: move from surface-level usage to repeatable engineering operation
-
-### Architecture Decomposition
-
-1. Define the runtime boundary for `Chapter 1: Obsidian Plugin Architecture`.
-2. Separate control-plane decisions from data-plane execution.
-3. Capture input contracts, transformation points, and output contracts.
-4. Trace state transitions across request lifecycle stages.
-5. Identify extension hooks and policy interception points.
-6. Map ownership boundaries for team and automation workflows.
-7. Specify rollback and recovery paths for unsafe changes.
-8. Track observability signals for correctness, latency, and cost.
-
-### Operator Decision Matrix
-
-| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
-|:--------------|:--------------|:------------------|:---------|
-| Runtime mode | managed defaults | explicit policy config | speed vs control |
-| State handling | local ephemeral | durable persisted state | simplicity vs auditability |
-| Tool integration | direct API use | mediated adapter layer | velocity vs governance |
-| Rollout method | manual change | staged + canary rollout | effort vs safety |
-| Incident response | best effort logs | runbooks + SLO alerts | cost vs reliability |
-
-### Failure Modes and Countermeasures
-
-| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
-|:-------------|:-------------|:-------------------|:---------------|
-| stale context | inconsistent outputs | missing refresh window | enforce context TTL and refresh hooks |
-| policy drift | unexpected execution | ad hoc overrides | centralize policy profiles |
-| auth mismatch | 401/403 bursts | credential sprawl | rotation schedule + scope minimization |
-| schema breakage | parser/validation errors | unmanaged upstream changes | contract tests per release |
-| retry storms | queue congestion | no backoff controls | jittered backoff + circuit breakers |
-| silent regressions | quality drop without alerts | weak baseline metrics | eval harness with thresholds |
-
-### Implementation Runbook
-
-1. Establish a reproducible baseline environment.
-2. Capture chapter-specific success criteria before changes.
-3. Implement minimal viable path with explicit interfaces.
-4. Add observability before expanding feature scope.
-5. Run deterministic tests for happy-path behavior.
-6. Inject failure scenarios for negative-path validation.
-7. Compare output quality against baseline snapshots.
-8. Promote through staged environments with rollback gates.
-9. Record operational lessons in release notes.
-
-### Quality Gate Checklist
-
-- [ ] chapter-level assumptions are explicit and testable
-- [ ] API/tool boundaries are documented with input/output examples
-- [ ] failure handling includes retry, timeout, and fallback policy
-- [ ] security controls include auth scopes and secret rotation plans
-- [ ] observability includes logs, metrics, traces, and alert thresholds
-- [ ] deployment guidance includes canary and rollback paths
-- [ ] docs include links to upstream sources and related tracks
-- [ ] post-release verification confirms expected behavior under load
-
-### Source Alignment
+## Source Code Walkthrough
-- [Obsidian Outliner](https://github.com/vslinko/obsidian-outliner)
-- [AI Codebase Knowledge Builder](https://github.com/The-Pocket/Tutorial-Codebase-Knowledge)
+### `jest/global-setup.js`
+
+The `wait` function in [`jest/global-setup.js`](https://github.com/vslinko/obsidian-outliner/blob/HEAD/jest/global-setup.js) handles a key part of this chapter's functionality:
+
+```js
+global.KILL_CMD = KILL_CMD;
+
+function wait(t) {
+ return new Promise((resolve) => setTimeout(resolve, t));
+}
+
+function runForAWhile({ timeout, fileToCheck }) {
+ return new Promise(async (resolve, reject) => {
+ const start = Date.now();
+ const obsidian = cp.spawn(OBSIDIAN_APP_CMD[0], OBSIDIAN_APP_CMD.slice(1));
+ obsidian.on("error", reject);
+ const i = setInterval(() => {
+ if (fs.existsSync(fileToCheck)) {
+ clearInterval(i);
+ setTimeout(() => {
+ cp.spawnSync(KILL_CMD[0], KILL_CMD.slice(1));
+ resolve();
+ }, 1000);
+ return;
+ }
+ const diff = Date.now() - start;
+ if (diff > timeout) {
+ clearInterval(i);
+ cp.spawnSync(KILL_CMD[0], KILL_CMD.slice(1));
+ reject();
+ }
+ }, 1000);
+ });
+}
-### Cross-Tutorial Connection Map
+async function prepareObsidian() {
+ debug(`Preparing Obsidian`);
+```
-- Related tutorials are listed in this tutorial index.
+This function is important because it defines how Obsidian Outliner Plugin: Deep Dive Tutorial implements the patterns covered in this chapter.
-### Advanced Practice Exercises
+### `jest/global-setup.js`
-1. Build a minimal end-to-end implementation for `Chapter 1: Obsidian Plugin Architecture`.
-2. Add instrumentation and measure baseline latency and error rate.
-3. Introduce one controlled failure and confirm graceful recovery.
-4. Add policy constraints and verify they are enforced consistently.
-5. Run a staged rollout and document rollback decision criteria.
+The `runForAWhile` function in [`jest/global-setup.js`](https://github.com/vslinko/obsidian-outliner/blob/HEAD/jest/global-setup.js) handles a key part of this chapter's functionality:
-### Review Questions
+```js
+}
+
+function runForAWhile({ timeout, fileToCheck }) {
+ return new Promise(async (resolve, reject) => {
+ const start = Date.now();
+ const obsidian = cp.spawn(OBSIDIAN_APP_CMD[0], OBSIDIAN_APP_CMD.slice(1));
+ obsidian.on("error", reject);
+ const i = setInterval(() => {
+ if (fs.existsSync(fileToCheck)) {
+ clearInterval(i);
+ setTimeout(() => {
+ cp.spawnSync(KILL_CMD[0], KILL_CMD.slice(1));
+ resolve();
+ }, 1000);
+ return;
+ }
+ const diff = Date.now() - start;
+ if (diff > timeout) {
+ clearInterval(i);
+ cp.spawnSync(KILL_CMD[0], KILL_CMD.slice(1));
+ reject();
+ }
+ }, 1000);
+ });
+}
+
+async function prepareObsidian() {
+ debug(`Preparing Obsidian`);
+
+ if (!fs.existsSync(OBSIDIAN_CONFIG_PATH)) {
+ debug(` Creating ${OBSIDIAN_CONFIG_PATH}`);
+ mkdirp.sync(OBSIDIAN_CONFIG_DIR);
+```
+
+This function is important because it defines how Obsidian Outliner Plugin: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+### `jest/global-setup.js`
+
+The `prepareObsidian` function in [`jest/global-setup.js`](https://github.com/vslinko/obsidian-outliner/blob/HEAD/jest/global-setup.js) handles a key part of this chapter's functionality:
+
+```js
+}
+
+async function prepareObsidian() {
+ debug(`Preparing Obsidian`);
+
+ if (!fs.existsSync(OBSIDIAN_CONFIG_PATH)) {
+ debug(` Creating ${OBSIDIAN_CONFIG_PATH}`);
+ mkdirp.sync(OBSIDIAN_CONFIG_DIR);
+ fs.writeFileSync(
+ OBSIDIAN_CONFIG_PATH,
+ '{"vaults":{},"updateDisabled":true}',
+ );
-1. Which execution boundary matters most for this chapter and why?
-2. What signal detects regressions earliest in your environment?
-3. What tradeoff did you make between delivery speed and governance?
-4. How would you recover from the highest-impact failure mode?
-5. What must be automated before scaling to team-wide adoption?
+ debug(" Running Obsidian for 90 seconds to setup");
+ await runForAWhile({
+ timeout: 90000,
+ fileToCheck: OBSIDIAN_LOCAL_STORAGE_PATH,
+ });
+ await wait(2000);
+ }
+
+ originalObsidianConfig = fs.readFileSync(OBSIDIAN_CONFIG_PATH, "utf-8");
+
+ const obsidianConfig = JSON.parse(originalObsidianConfig);
+ for (const key of Object.keys(obsidianConfig.vaults)) {
+ debug(` Closing vault ${obsidianConfig.vaults[key].path}`);
+ obsidianConfig.vaults[key].open = false;
+ }
+ debug(` Opening vault ${VAULT_DIR}`);
+ obsidianConfig.vaults[OBISDIAN_TEST_VAULT_ID] = {
+ path: VAULT_DIR,
+ ts: Date.now(),
+```
+
+This function is important because it defines how Obsidian Outliner Plugin: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+### `jest/global-setup.js`
+
+The `prepareVault` function in [`jest/global-setup.js`](https://github.com/vslinko/obsidian-outliner/blob/HEAD/jest/global-setup.js) handles a key part of this chapter's functionality:
+
+```js
+}
+
+async function prepareVault() {
+ debug(`Prepare vault`);
+
+ mkdirp.sync(VAULT_DIR);
+ fs.writeFileSync(VAULT_DIR + "/test.md", "");
+
+ const vaultConfigFilePath = `${VAULT_DIR}/.obsidian/app.json`;
+ const vaultCommunityPluginsConfigFilePath = `${VAULT_DIR}/.obsidian/community-plugins.json`;
+ const vaultPluginDir = `${VAULT_DIR}/.obsidian/plugins/obsidian-outliner`;
+
+ if (!fs.existsSync(vaultConfigFilePath)) {
+ debug(" Running Obsidian for 90 seconds to setup vault");
+ await runForAWhile({ timeout: 90000, fileToCheck: vaultConfigFilePath });
+ await wait(2000);
+ }
+
+ const vaultConfig = JSON.parse(fs.readFileSync(vaultConfigFilePath));
+ const newVaultConfig = {
+ ...vaultConfig,
+ foldHeading: true,
+ foldIndent: true,
+ useTab: false,
+ tabSize: 2,
+ legacyEditor: false,
+ };
+ if (JSON.stringify(vaultConfig) !== JSON.stringify(newVaultConfig)) {
+ debug(` Saving ${vaultConfigFilePath}`);
+ fs.writeFileSync(vaultConfigFilePath, JSON.stringify(newVaultConfig));
+ }
+
+```
+
+This function is important because it defines how Obsidian Outliner Plugin: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+
+## How These Components Connect
+
+```mermaid
+flowchart TD
+ A[wait]
+ B[runForAWhile]
+ C[prepareObsidian]
+ D[prepareVault]
+ E[stateToString]
+ A --> B
+ B --> C
+ C --> D
+ D --> E
+```
diff --git a/tutorials/obsidian-outliner-tutorial/02-text-editing.md b/tutorials/obsidian-outliner-tutorial/02-text-editing.md
index 9989a2c9..587b05fd 100644
--- a/tutorials/obsidian-outliner-tutorial/02-text-editing.md
+++ b/tutorials/obsidian-outliner-tutorial/02-text-editing.md
@@ -24,6 +24,23 @@ By the end of this chapter, you'll understand:
## 📝 Obsidian Editor Architecture
+```mermaid
+flowchart TD
+ A[Keyboard event] --> B[Obsidian command handler]
+ B --> C[OutlinerPlugin.handleKeydown]
+ C --> D[Get CodeMirror editor state]
+ D --> E[Parse current line as list item]
+ E --> F{Action type}
+ F -->|indent| G[AddInnerBullet operation]
+ F -->|move| H[MoveListDown/Up operation]
+ F -->|fold| I[FoldBullet operation]
+ G --> J[Apply editor transaction]
+ H --> J
+ I --> J
+ J --> K[Updated editor state]
+```
+
+
Obsidian's editor is built on CodeMirror 6, a powerful text editing framework. The Outliner plugin extends this foundation with advanced list and tree manipulation features.
### **Editor Component Hierarchy**
@@ -709,6 +726,16 @@ Under the hood, `Chapter 2: Text Editing Implementation` usually follows a repea
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## Source Code Walkthrough
+
+### `src/services/Parser.ts`
+
+The [`src/services/Parser.ts`](https://github.com/vslinko/obsidian-outliner/blob/HEAD/src/services/Parser.ts) file parses the editor's current list content into a tree structure. Its `parse` method reads the current CodeMirror editor state, identifies list item boundaries, and constructs the `IList`/`IRoot` tree that all editing operations work against.
+
+### `src/features/` — editing feature modules
+
+The [`src/features/`](https://github.com/vslinko/obsidian-outliner/tree/HEAD/src/features) directory contains individual feature classes like `MoveItemDown.ts`, `IndentList.ts`, and `AddInnerBullet.ts`. Each feature registers a command and implements an `execute(editor)` method that calls the parser, performs the tree operation, and applies the result as a CodeMirror transaction.
+
## Source Walkthrough
Use the following upstream sources to verify implementation details while reading this chapter:
diff --git a/tutorials/obsidian-outliner-tutorial/03-tree-structures.md b/tutorials/obsidian-outliner-tutorial/03-tree-structures.md
index 2c766d31..2218caf7 100644
--- a/tutorials/obsidian-outliner-tutorial/03-tree-structures.md
+++ b/tutorials/obsidian-outliner-tutorial/03-tree-structures.md
@@ -24,6 +24,19 @@ By the end of this chapter, you'll understand:
## 🌳 Tree Data Structure Fundamentals
+```mermaid
+flowchart TD
+ A[IRoot root node] --> B[IList item 1]
+ A --> C[IList item 2]
+ B --> D[IList child 1.1]
+ B --> E[IList child 1.2]
+ C --> F[IList child 2.1]
+ D --> G[IList leaf 1.1.1]
+ B --> H[content: bullet marker + text]
+ D --> I[content: indented bullet]
+```
+
+
### **Outline Tree Representation**
The Outliner plugin uses a tree structure to represent hierarchical content, where each node represents a list item and edges represent parent-child relationships.
@@ -884,6 +897,16 @@ Under the hood, `Chapter 3: Tree Data Structures` usually follows a repeatable c
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## Source Code Walkthrough
+
+### `src/root/` — IRoot and IList types
+
+The [`src/root/`](https://github.com/vslinko/obsidian-outliner/tree/HEAD/src/root) directory defines the `IRoot` and `IList` interfaces and their implementations. `IRoot` is the top-level container returned by the parser. `IList` represents a single outline node with `getChildren()`, `getParent()`, `getIndent()`, and `getContent()` methods that drive all tree traversal and manipulation algorithms.
+
+### `src/services/Parser.ts` — tree construction
+
+The `Parser` class in [`src/services/Parser.ts`](https://github.com/vslinko/obsidian-outliner/blob/HEAD/src/services/Parser.ts) converts raw editor line ranges into the `IRoot`/`IList` tree. Its indent-tracking logic determines parent-child relationships by comparing leading whitespace, implementing the tree construction algorithm described in this chapter.
+
## Source Walkthrough
Use the following upstream sources to verify implementation details while reading this chapter:
diff --git a/tutorials/obsidian-outliner-tutorial/04-advanced-features.md b/tutorials/obsidian-outliner-tutorial/04-advanced-features.md
index 8a26420d..2afda4e4 100644
--- a/tutorials/obsidian-outliner-tutorial/04-advanced-features.md
+++ b/tutorials/obsidian-outliner-tutorial/04-advanced-features.md
@@ -24,6 +24,21 @@ By the end of this chapter, you'll understand:
## ⚡ Performance Optimization
+```mermaid
+flowchart TD
+ A[Large outline document] --> B[Parser reads line range]
+ B --> C{Document size}
+ C -->|small| D[Full tree parse]
+ C -->|large| E[Incremental parse affected subtree]
+ D --> F[Tree operations]
+ E --> F
+ F --> G[Apply CodeMirror transaction]
+ G --> H[Drag-and-drop on tree nodes]
+ G --> I[Fold/unfold subtree]
+ G --> J[Virtualized scroll for large outlines]
+```
+
+
### **Efficient Rendering for Large Documents**
```typescript
@@ -890,6 +905,16 @@ Under the hood, `Chapter 4: Advanced Features` usually follows a repeatable cont
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## Source Code Walkthrough
+
+### `src/features/DragAndDrop.ts`
+
+The [`src/features/DragAndDrop.ts`](https://github.com/vslinko/obsidian-outliner/blob/HEAD/src/features/DragAndDrop.ts) file implements drag-and-drop list reordering. Its `getEditorViewFromHTMLElement` helper resolves the CodeMirror `EditorView` from the DOM event target, enabling the plugin to map mouse events to specific list items for drag-based tree manipulation.
+
+### `src/features/FoldBullet.ts`
+
+The fold/unfold feature in [`src/features/`](https://github.com/vslinko/obsidian-outliner/tree/HEAD/src/features) uses CodeMirror 6 folding decorations to hide subtrees. The fold state is tracked per-node and persists across editor reloads through Obsidian's workspace state API — the mechanism for the fold persistence behavior described in this chapter.
+
## Source Walkthrough
Use the following upstream sources to verify implementation details while reading this chapter:
diff --git a/tutorials/obsidian-outliner-tutorial/05-keyboard-shortcuts.md b/tutorials/obsidian-outliner-tutorial/05-keyboard-shortcuts.md
index 8d9f6591..4233a0f4 100644
--- a/tutorials/obsidian-outliner-tutorial/05-keyboard-shortcuts.md
+++ b/tutorials/obsidian-outliner-tutorial/05-keyboard-shortcuts.md
@@ -6,6 +6,7 @@ has_children: false
parent: "Obsidian Outliner Plugin"
---
+
# Chapter 5: Keyboard Shortcuts
Welcome to **Chapter 5: Keyboard Shortcuts**. In this part of **Obsidian Outliner Plugin: Deep Dive Tutorial**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
@@ -85,502 +86,184 @@ Suggested trace strategy:
## Depth Expansion Playbook
-<!-- depth-expansion-v2 -->
-
-This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
-
-### Strategic Context
-
-- tutorial: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- tutorial slug: **obsidian-outliner-tutorial**
-- chapter focus: **Chapter 5: Keyboard Shortcuts**
-- system context: **Obsidian Outliner Plugin**
-- objective: move from surface-level usage to repeatable engineering operation
-
-### Architecture Decomposition
-
-1. Define the runtime boundary for `Chapter 5: Keyboard Shortcuts`.
-2. Separate control-plane decisions from data-plane execution.
-3. Capture input contracts, transformation points, and output contracts.
-4. Trace state transitions across request lifecycle stages.
-5. Identify extension hooks and policy interception points.
-6. Map ownership boundaries for team and automation workflows.
-7. Specify rollback and recovery paths for unsafe changes.
-8. Track observability signals for correctness, latency, and cost.
-
-### Operator Decision Matrix
-
-| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
-|:--------------|:--------------|:------------------|:---------|
-| Runtime mode | managed defaults | explicit policy config | speed vs control |
-| State handling | local ephemeral | durable persisted state | simplicity vs auditability |
-| Tool integration | direct API use | mediated adapter layer | velocity vs governance |
-| Rollout method | manual change | staged + canary rollout | effort vs safety |
-| Incident response | best effort logs | runbooks + SLO alerts | cost vs reliability |
-
-### Failure Modes and Countermeasures
-
-| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
-|:-------------|:-------------|:-------------------|:---------------|
-| stale context | inconsistent outputs | missing refresh window | enforce context TTL and refresh hooks |
-| policy drift | unexpected execution | ad hoc overrides | centralize policy profiles |
-| auth mismatch | 401/403 bursts | credential sprawl | rotation schedule + scope minimization |
-| schema breakage | parser/validation errors | unmanaged upstream changes | contract tests per release |
-| retry storms | queue congestion | no backoff controls | jittered backoff + circuit breakers |
-| silent regressions | quality drop without alerts | weak baseline metrics | eval harness with thresholds |
-
-### Implementation Runbook
-
-1. Establish a reproducible baseline environment.
-2. Capture chapter-specific success criteria before changes.
-3. Implement minimal viable path with explicit interfaces.
-4. Add observability before expanding feature scope.
-5. Run deterministic tests for happy-path behavior.
-6. Inject failure scenarios for negative-path validation.
-7. Compare output quality against baseline snapshots.
-8. Promote through staged environments with rollback gates.
-9. Record operational lessons in release notes.
-
-### Quality Gate Checklist
-
-- [ ] chapter-level assumptions are explicit and testable
-- [ ] API/tool boundaries are documented with input/output examples
-- [ ] failure handling includes retry, timeout, and fallback policy
-- [ ] security controls include auth scopes and secret rotation plans
-- [ ] observability includes logs, metrics, traces, and alert thresholds
-- [ ] deployment guidance includes canary and rollback paths
-- [ ] docs include links to upstream sources and related tracks
-- [ ] post-release verification confirms expected behavior under load
-
-### Source Alignment
-
-- [Obsidian Outliner](https://github.com/vslinko/obsidian-outliner)
-- [AI Codebase Knowledge Builder](https://github.com/The-Pocket/Tutorial-Codebase-Knowledge)
-
-### Cross-Tutorial Connection Map
-
-- Related tutorials are listed in this tutorial index.
-
-### Advanced Practice Exercises
-
-1. Build a minimal end-to-end implementation for `Chapter 5: Keyboard Shortcuts`.
-2. Add instrumentation and measure baseline latency and error rate.
-3. Introduce one controlled failure and confirm graceful recovery.
-4. Add policy constraints and verify they are enforced consistently.
-5. Run a staged rollout and document rollback decision criteria.
-
-### Review Questions
-
-1. Which execution boundary matters most for this chapter and why?
-2. What signal detects regressions earliest in your environment?
-3. What tradeoff did you make between delivery speed and governance?
-4. How would you recover from the highest-impact failure mode?
-5. What must be automated before scaling to team-wide adoption?
-
-### Scenario Playbook 1: Chapter 5: Keyboard Shortcuts
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 2: Chapter 5: Keyboard Shortcuts
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 3: Chapter 5: Keyboard Shortcuts
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 4: Chapter 5: Keyboard Shortcuts
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 5: Chapter 5: Keyboard Shortcuts
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 6: Chapter 5: Keyboard Shortcuts
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 7: Chapter 5: Keyboard Shortcuts
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 8: Chapter 5: Keyboard Shortcuts
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 9: Chapter 5: Keyboard Shortcuts
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 10: Chapter 5: Keyboard Shortcuts
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 11: Chapter 5: Keyboard Shortcuts
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 12: Chapter 5: Keyboard Shortcuts
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 13: Chapter 5: Keyboard Shortcuts
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 14: Chapter 5: Keyboard Shortcuts
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 15: Chapter 5: Keyboard Shortcuts
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 16: Chapter 5: Keyboard Shortcuts
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 17: Chapter 5: Keyboard Shortcuts
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 18: Chapter 5: Keyboard Shortcuts
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 19: Chapter 5: Keyboard Shortcuts
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 20: Chapter 5: Keyboard Shortcuts
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 21: Chapter 5: Keyboard Shortcuts
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 22: Chapter 5: Keyboard Shortcuts
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 23: Chapter 5: Keyboard Shortcuts
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 24: Chapter 5: Keyboard Shortcuts
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 25: Chapter 5: Keyboard Shortcuts
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 26: Chapter 5: Keyboard Shortcuts
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 27: Chapter 5: Keyboard Shortcuts
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 28: Chapter 5: Keyboard Shortcuts
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 29: Chapter 5: Keyboard Shortcuts
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 30: Chapter 5: Keyboard Shortcuts
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 31: Chapter 5: Keyboard Shortcuts
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 32: Chapter 5: Keyboard Shortcuts
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 33: Chapter 5: Keyboard Shortcuts
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 34: Chapter 5: Keyboard Shortcuts
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
+## Source Code Walkthrough
+
+### `src/features/DragAndDrop.ts`
+
+The `getEditorViewFromHTMLElement` function in [`src/features/DragAndDrop.ts`](https://github.com/vslinko/obsidian-outliner/blob/HEAD/src/features/DragAndDrop.ts) handles a key part of this chapter's functionality:
+
+```ts
+ }
+
+ const view = getEditorViewFromHTMLElement(e.target as HTMLElement);
+ if (!view) {
+ return;
+ }
+
+ e.preventDefault();
+ e.stopPropagation();
+
+ this.preStart = {
+ x: e.x,
+ y: e.y,
+ view,
+ };
+ };
+
+ private handleMouseMove = (e: MouseEvent) => {
+ if (this.preStart) {
+ this.startDragging();
+ }
+ if (this.state) {
+ this.detectAndDrawDropZone(e.x, e.y);
+ }
+ };
+
+ private handleMouseUp = () => {
+ if (this.preStart) {
+ this.preStart = null;
+ }
+ if (this.state) {
+ this.stopDragging();
+```
+
+This function is important because it defines how Obsidian Outliner Plugin: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+### `src/features/DragAndDrop.ts`
+
+The `isClickOnBullet` function in [`src/features/DragAndDrop.ts`](https://github.com/vslinko/obsidian-outliner/blob/HEAD/src/features/DragAndDrop.ts) handles a key part of this chapter's functionality:
+
+```ts
+ !isFeatureSupported() ||
+ !this.settings.dragAndDrop ||
+ !isClickOnBullet(e)
+ ) {
+ return;
+ }
+
+ const view = getEditorViewFromHTMLElement(e.target as HTMLElement);
+ if (!view) {
+ return;
+ }
+
+ e.preventDefault();
+ e.stopPropagation();
+
+ this.preStart = {
+ x: e.x,
+ y: e.y,
+ view,
+ };
+ };
+
+ private handleMouseMove = (e: MouseEvent) => {
+ if (this.preStart) {
+ this.startDragging();
+ }
+ if (this.state) {
+ this.detectAndDrawDropZone(e.x, e.y);
+ }
+ };
+
+ private handleMouseUp = () => {
+```
+
+This function is important because it defines how Obsidian Outliner Plugin: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+### `src/features/DragAndDrop.ts`
+
+The `isSameRoots` function in [`src/features/DragAndDrop.ts`](https://github.com/vslinko/obsidian-outliner/blob/HEAD/src/features/DragAndDrop.ts) handles a key part of this chapter's functionality:
+
+```ts
+
+ const newRoot = this.parser.parse(editor, root.getContentStart());
+ if (!isSameRoots(root, newRoot)) {
+ new Notice(
+ `The item cannot be moved. The page content changed during the move.`,
+ 5000,
+ );
+ return;
+ }
+
+ this.operationPerformer.eval(
+ root,
+ new MoveListToDifferentPosition(
+ root,
+ list,
+ dropVariant.placeToMove,
+ dropVariant.whereToMove,
+ this.obisidian.getDefaultIndentChars(),
+ ),
+ editor,
+ );
+ }
+
+ private highlightDraggingLines() {
+ const { state } = this;
+ const { list, editor, view } = state;
+
+ const lines = [];
+ const fromLine = list.getFirstLineContentStart().line;
+ const tillLine = list.getContentEndIncludingChildren().line;
+ for (let i = fromLine; i <= tillLine; i++) {
+ lines.push(editor.posToOffset({ line: i, ch: 0 }));
+```
+
+This function is important because it defines how Obsidian Outliner Plugin: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+### `src/features/DragAndDrop.ts`
+
+The `isFeatureSupported` function in [`src/features/DragAndDrop.ts`](https://github.com/vslinko/obsidian-outliner/blob/HEAD/src/features/DragAndDrop.ts) handles a key part of this chapter's functionality:
+
+```ts
+
+ private handleSettingsChange = () => {
+ if (!isFeatureSupported()) {
+ return;
+ }
+
+ if (this.settings.dragAndDrop) {
+ document.body.classList.add(BODY_CLASS);
+ } else {
+ document.body.classList.remove(BODY_CLASS);
+ }
+ };
+
+ private handleMouseDown = (e: MouseEvent) => {
+ if (
+ !isFeatureSupported() ||
+ !this.settings.dragAndDrop ||
+ !isClickOnBullet(e)
+ ) {
+ return;
+ }
+
+ const view = getEditorViewFromHTMLElement(e.target as HTMLElement);
+ if (!view) {
+ return;
+ }
+
+ e.preventDefault();
+ e.stopPropagation();
+
+ this.preStart = {
+ x: e.x,
+```
+
+This function is important because it defines how Obsidian Outliner Plugin: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+
+## How These Components Connect
+
+```mermaid
+flowchart TD
+ A[getEditorViewFromHTMLElement]
+ B[isClickOnBullet]
+ C[isSameRoots]
+ D[isFeatureSupported]
+ E[DropVariant]
+ A --> B
+ B --> C
+ C --> D
+ D --> E
+```
diff --git a/tutorials/obsidian-outliner-tutorial/06-testing-debugging.md b/tutorials/obsidian-outliner-tutorial/06-testing-debugging.md
index be3422b7..79546038 100644
--- a/tutorials/obsidian-outliner-tutorial/06-testing-debugging.md
+++ b/tutorials/obsidian-outliner-tutorial/06-testing-debugging.md
@@ -6,6 +6,7 @@ has_children: false
parent: "Obsidian Outliner Plugin"
---
+
# Chapter 6: Testing and Debugging
Welcome to **Chapter 6: Testing and Debugging**. In this part of **Obsidian Outliner Plugin: Deep Dive Tutorial**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
@@ -96,490 +97,184 @@ Suggested trace strategy:
## Depth Expansion Playbook
-<!-- depth-expansion-v2 -->
-
-This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
-
-### Strategic Context
-
-- tutorial: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- tutorial slug: **obsidian-outliner-tutorial**
-- chapter focus: **Chapter 6: Testing and Debugging**
-- system context: **Obsidian Outliner Plugin**
-- objective: move from surface-level usage to repeatable engineering operation
-
-### Architecture Decomposition
-
-1. Define the runtime boundary for `Chapter 6: Testing and Debugging`.
-2. Separate control-plane decisions from data-plane execution.
-3. Capture input contracts, transformation points, and output contracts.
-4. Trace state transitions across request lifecycle stages.
-5. Identify extension hooks and policy interception points.
-6. Map ownership boundaries for team and automation workflows.
-7. Specify rollback and recovery paths for unsafe changes.
-8. Track observability signals for correctness, latency, and cost.
-
-### Operator Decision Matrix
-
-| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
-|:--------------|:--------------|:------------------|:---------|
-| Runtime mode | managed defaults | explicit policy config | speed vs control |
-| State handling | local ephemeral | durable persisted state | simplicity vs auditability |
-| Tool integration | direct API use | mediated adapter layer | velocity vs governance |
-| Rollout method | manual change | staged + canary rollout | effort vs safety |
-| Incident response | best effort logs | runbooks + SLO alerts | cost vs reliability |
-
-### Failure Modes and Countermeasures
-
-| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
-|:-------------|:-------------|:-------------------|:---------------|
-| stale context | inconsistent outputs | missing refresh window | enforce context TTL and refresh hooks |
-| policy drift | unexpected execution | ad hoc overrides | centralize policy profiles |
-| auth mismatch | 401/403 bursts | credential sprawl | rotation schedule + scope minimization |
-| schema breakage | parser/validation errors | unmanaged upstream changes | contract tests per release |
-| retry storms | queue congestion | no backoff controls | jittered backoff + circuit breakers |
-| silent regressions | quality drop without alerts | weak baseline metrics | eval harness with thresholds |
-
-### Implementation Runbook
-
-1. Establish a reproducible baseline environment.
-2. Capture chapter-specific success criteria before changes.
-3. Implement minimal viable path with explicit interfaces.
-4. Add observability before expanding feature scope.
-5. Run deterministic tests for happy-path behavior.
-6. Inject failure scenarios for negative-path validation.
-7. Compare output quality against baseline snapshots.
-8. Promote through staged environments with rollback gates.
-9. Record operational lessons in release notes.
-
-### Quality Gate Checklist
-
-- [ ] chapter-level assumptions are explicit and testable
-- [ ] API/tool boundaries are documented with input/output examples
-- [ ] failure handling includes retry, timeout, and fallback policy
-- [ ] security controls include auth scopes and secret rotation plans
-- [ ] observability includes logs, metrics, traces, and alert thresholds
-- [ ] deployment guidance includes canary and rollback paths
-- [ ] docs include links to upstream sources and related tracks
-- [ ] post-release verification confirms expected behavior under load
-
-### Source Alignment
+## Source Code Walkthrough
-- [Obsidian Outliner](https://github.com/vslinko/obsidian-outliner)
-- [AI Codebase Knowledge Builder](https://github.com/The-Pocket/Tutorial-Codebase-Knowledge)
-
-### Cross-Tutorial Connection Map
-
-- Related tutorials are listed in this tutorial index.
-
-### Advanced Practice Exercises
-
-1. Build a minimal end-to-end implementation for `Chapter 6: Testing and Debugging`.
-2. Add instrumentation and measure baseline latency and error rate.
-3. Introduce one controlled failure and confirm graceful recovery.
-4. Add policy constraints and verify they are enforced consistently.
-5. Run a staged rollout and document rollback decision criteria.
-
-### Review Questions
-
-1. Which execution boundary matters most for this chapter and why?
-2. What signal detects regressions earliest in your environment?
-3. What tradeoff did you make between delivery speed and governance?
-4. How would you recover from the highest-impact failure mode?
-5. What must be automated before scaling to team-wide adoption?
-
-### Scenario Playbook 1: Chapter 6: Testing and Debugging
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 2: Chapter 6: Testing and Debugging
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 3: Chapter 6: Testing and Debugging
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 4: Chapter 6: Testing and Debugging
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 5: Chapter 6: Testing and Debugging
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 6: Chapter 6: Testing and Debugging
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 7: Chapter 6: Testing and Debugging
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 8: Chapter 6: Testing and Debugging
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 9: Chapter 6: Testing and Debugging
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 10: Chapter 6: Testing and Debugging
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 11: Chapter 6: Testing and Debugging
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 12: Chapter 6: Testing and Debugging
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 13: Chapter 6: Testing and Debugging
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 14: Chapter 6: Testing and Debugging
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 15: Chapter 6: Testing and Debugging
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 16: Chapter 6: Testing and Debugging
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 17: Chapter 6: Testing and Debugging
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 18: Chapter 6: Testing and Debugging
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 19: Chapter 6: Testing and Debugging
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 20: Chapter 6: Testing and Debugging
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 21: Chapter 6: Testing and Debugging
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 22: Chapter 6: Testing and Debugging
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 23: Chapter 6: Testing and Debugging
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 24: Chapter 6: Testing and Debugging
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 25: Chapter 6: Testing and Debugging
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 26: Chapter 6: Testing and Debugging
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 27: Chapter 6: Testing and Debugging
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 28: Chapter 6: Testing and Debugging
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 29: Chapter 6: Testing and Debugging
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 30: Chapter 6: Testing and Debugging
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 31: Chapter 6: Testing and Debugging
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 32: Chapter 6: Testing and Debugging
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 33: Chapter 6: Testing and Debugging
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
+### `src/services/Parser.ts`
+
+The `ReaderPosition` interface in [`src/services/Parser.ts`](https://github.com/vslinko/obsidian-outliner/blob/HEAD/src/services/Parser.ts) handles a key part of this chapter's functionality:
+
+```ts
+);
+
+export interface ReaderPosition {
+ line: number;
+ ch: number;
+}
+
+export interface ReaderSelection {
+ anchor: ReaderPosition;
+ head: ReaderPosition;
+}
+
+export interface Reader {
+ getCursor(): ReaderPosition;
+ getLine(n: number): string;
+ lastLine(): number;
+ listSelections(): ReaderSelection[];
+ getAllFoldedLines(): number[];
+}
+
+interface ParseListList {
+ getFirstLineIndent(): string;
+ setNotesIndent(notesIndent: string): void;
+ getNotesIndent(): string | null;
+ addLine(text: string): void;
+ getParent(): ParseListList | null;
+ addAfterAll(list: ParseListList): void;
+}
+
+export class Parser {
+ constructor(
+ private logger: Logger,
+```
+
+This interface is important because it defines how Obsidian Outliner Plugin: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+### `src/services/Parser.ts`
+
+The `ReaderSelection` interface in [`src/services/Parser.ts`](https://github.com/vslinko/obsidian-outliner/blob/HEAD/src/services/Parser.ts) handles a key part of this chapter's functionality:
+
+```ts
+}
+
+export interface ReaderSelection {
+ anchor: ReaderPosition;
+ head: ReaderPosition;
+}
+
+export interface Reader {
+ getCursor(): ReaderPosition;
+ getLine(n: number): string;
+ lastLine(): number;
+ listSelections(): ReaderSelection[];
+ getAllFoldedLines(): number[];
+}
+
+interface ParseListList {
+ getFirstLineIndent(): string;
+ setNotesIndent(notesIndent: string): void;
+ getNotesIndent(): string | null;
+ addLine(text: string): void;
+ getParent(): ParseListList | null;
+ addAfterAll(list: ParseListList): void;
+}
+
+export class Parser {
+ constructor(
+ private logger: Logger,
+ private settings: Settings,
+ ) {}
+
+ parseRange(editor: Reader, fromLine = 0, toLine = editor.lastLine()): Root[] {
+ const lists: Root[] = [];
+```
+
+This interface is important because it defines how Obsidian Outliner Plugin: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+### `src/services/Parser.ts`
+
+The `Reader` interface in [`src/services/Parser.ts`](https://github.com/vslinko/obsidian-outliner/blob/HEAD/src/services/Parser.ts) handles a key part of this chapter's functionality:
+
+```ts
+);
+
+export interface ReaderPosition {
+ line: number;
+ ch: number;
+}
+
+export interface ReaderSelection {
+ anchor: ReaderPosition;
+ head: ReaderPosition;
+}
+
+export interface Reader {
+ getCursor(): ReaderPosition;
+ getLine(n: number): string;
+ lastLine(): number;
+ listSelections(): ReaderSelection[];
+ getAllFoldedLines(): number[];
+}
+
+interface ParseListList {
+ getFirstLineIndent(): string;
+ setNotesIndent(notesIndent: string): void;
+ getNotesIndent(): string | null;
+ addLine(text: string): void;
+ getParent(): ParseListList | null;
+ addAfterAll(list: ParseListList): void;
+}
+
+export class Parser {
+ constructor(
+ private logger: Logger,
+```
+
+This interface is important because it defines how Obsidian Outliner Plugin: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+### `src/services/Parser.ts`
+
+The `ParseListList` interface in [`src/services/Parser.ts`](https://github.com/vslinko/obsidian-outliner/blob/HEAD/src/services/Parser.ts) handles a key part of this chapter's functionality:
+
+```ts
+}
+
+interface ParseListList {
+ getFirstLineIndent(): string;
+ setNotesIndent(notesIndent: string): void;
+ getNotesIndent(): string | null;
+ addLine(text: string): void;
+ getParent(): ParseListList | null;
+ addAfterAll(list: ParseListList): void;
+}
+
+export class Parser {
+ constructor(
+ private logger: Logger,
+ private settings: Settings,
+ ) {}
+
+ parseRange(editor: Reader, fromLine = 0, toLine = editor.lastLine()): Root[] {
+ const lists: Root[] = [];
+
+ for (let i = fromLine; i <= toLine; i++) {
+ const line = editor.getLine(i);
+
+ if (i === fromLine || this.isListItem(line)) {
+ const list = this.parseWithLimits(editor, i, fromLine, toLine);
+
+ if (list) {
+ lists.push(list);
+ i = list.getContentEnd().line;
+ }
+ }
+ }
+```
+
+This interface is important because it defines how Obsidian Outliner Plugin: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+
+## How These Components Connect
+
+```mermaid
+flowchart TD
+ A[ReaderPosition]
+ B[ReaderSelection]
+ C[Reader]
+ D[ParseListList]
+ E[CreateNewItem]
+ A --> B
+ B --> C
+ C --> D
+ D --> E
+```
diff --git a/tutorials/obsidian-outliner-tutorial/07-plugin-packaging.md b/tutorials/obsidian-outliner-tutorial/07-plugin-packaging.md
index 419c03b8..d399938b 100644
--- a/tutorials/obsidian-outliner-tutorial/07-plugin-packaging.md
+++ b/tutorials/obsidian-outliner-tutorial/07-plugin-packaging.md
@@ -6,6 +6,7 @@ has_children: false
parent: "Obsidian Outliner Plugin"
---
+
# Chapter 7: Plugin Packaging
Welcome to **Chapter 7: Plugin Packaging**. In this part of **Obsidian Outliner Plugin: Deep Dive Tutorial**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
@@ -89,502 +90,173 @@ Suggested trace strategy:
## Depth Expansion Playbook
-<!-- depth-expansion-v2 -->
-
-This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
-
-### Strategic Context
-
-- tutorial: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- tutorial slug: **obsidian-outliner-tutorial**
-- chapter focus: **Chapter 7: Plugin Packaging**
-- system context: **Obsidian Outliner Plugin**
-- objective: move from surface-level usage to repeatable engineering operation
-
-### Architecture Decomposition
-
-1. Define the runtime boundary for `Chapter 7: Plugin Packaging`.
-2. Separate control-plane decisions from data-plane execution.
-3. Capture input contracts, transformation points, and output contracts.
-4. Trace state transitions across request lifecycle stages.
-5. Identify extension hooks and policy interception points.
-6. Map ownership boundaries for team and automation workflows.
-7. Specify rollback and recovery paths for unsafe changes.
-8. Track observability signals for correctness, latency, and cost.
-
-### Operator Decision Matrix
-
-| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
-|:--------------|:--------------|:------------------|:---------|
-| Runtime mode | managed defaults | explicit policy config | speed vs control |
-| State handling | local ephemeral | durable persisted state | simplicity vs auditability |
-| Tool integration | direct API use | mediated adapter layer | velocity vs governance |
-| Rollout method | manual change | staged + canary rollout | effort vs safety |
-| Incident response | best effort logs | runbooks + SLO alerts | cost vs reliability |
-
-### Failure Modes and Countermeasures
-
-| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
-|:-------------|:-------------|:-------------------|:---------------|
-| stale context | inconsistent outputs | missing refresh window | enforce context TTL and refresh hooks |
-| policy drift | unexpected execution | ad hoc overrides | centralize policy profiles |
-| auth mismatch | 401/403 bursts | credential sprawl | rotation schedule + scope minimization |
-| schema breakage | parser/validation errors | unmanaged upstream changes | contract tests per release |
-| retry storms | queue congestion | no backoff controls | jittered backoff + circuit breakers |
-| silent regressions | quality drop without alerts | weak baseline metrics | eval harness with thresholds |
-
-### Implementation Runbook
-
-1. Establish a reproducible baseline environment.
-2. Capture chapter-specific success criteria before changes.
-3. Implement minimal viable path with explicit interfaces.
-4. Add observability before expanding feature scope.
-5. Run deterministic tests for happy-path behavior.
-6. Inject failure scenarios for negative-path validation.
-7. Compare output quality against baseline snapshots.
-8. Promote through staged environments with rollback gates.
-9. Record operational lessons in release notes.
-
-### Quality Gate Checklist
-
-- [ ] chapter-level assumptions are explicit and testable
-- [ ] API/tool boundaries are documented with input/output examples
-- [ ] failure handling includes retry, timeout, and fallback policy
-- [ ] security controls include auth scopes and secret rotation plans
-- [ ] observability includes logs, metrics, traces, and alert thresholds
-- [ ] deployment guidance includes canary and rollback paths
-- [ ] docs include links to upstream sources and related tracks
-- [ ] post-release verification confirms expected behavior under load
-
-### Source Alignment
+## Source Code Walkthrough
-- [Obsidian Outliner](https://github.com/vslinko/obsidian-outliner)
-- [AI Codebase Knowledge Builder](https://github.com/The-Pocket/Tutorial-Codebase-Knowledge)
-
-### Cross-Tutorial Connection Map
-
-- Related tutorials are listed in this tutorial index.
-
-### Advanced Practice Exercises
-
-1. Build a minimal end-to-end implementation for `Chapter 7: Plugin Packaging`.
-2. Add instrumentation and measure baseline latency and error rate.
-3. Introduce one controlled failure and confirm graceful recovery.
-4. Add policy constraints and verify they are enforced consistently.
-5. Run a staged rollout and document rollback decision criteria.
-
-### Review Questions
-
-1. Which execution boundary matters most for this chapter and why?
-2. What signal detects regressions earliest in your environment?
-3. What tradeoff did you make between delivery speed and governance?
-4. How would you recover from the highest-impact failure mode?
-5. What must be automated before scaling to team-wide adoption?
-
-### Scenario Playbook 1: Chapter 7: Plugin Packaging
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 2: Chapter 7: Plugin Packaging
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 3: Chapter 7: Plugin Packaging
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 4: Chapter 7: Plugin Packaging
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 5: Chapter 7: Plugin Packaging
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 6: Chapter 7: Plugin Packaging
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 7: Chapter 7: Plugin Packaging
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 8: Chapter 7: Plugin Packaging
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 9: Chapter 7: Plugin Packaging
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 10: Chapter 7: Plugin Packaging
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 11: Chapter 7: Plugin Packaging
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 12: Chapter 7: Plugin Packaging
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 13: Chapter 7: Plugin Packaging
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 14: Chapter 7: Plugin Packaging
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 15: Chapter 7: Plugin Packaging
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 16: Chapter 7: Plugin Packaging
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 17: Chapter 7: Plugin Packaging
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 18: Chapter 7: Plugin Packaging
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 19: Chapter 7: Plugin Packaging
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 20: Chapter 7: Plugin Packaging
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 21: Chapter 7: Plugin Packaging
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 22: Chapter 7: Plugin Packaging
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 23: Chapter 7: Plugin Packaging
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 24: Chapter 7: Plugin Packaging
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 25: Chapter 7: Plugin Packaging
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 26: Chapter 7: Plugin Packaging
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 27: Chapter 7: Plugin Packaging
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 28: Chapter 7: Plugin Packaging
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 29: Chapter 7: Plugin Packaging
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 30: Chapter 7: Plugin Packaging
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 31: Chapter 7: Plugin Packaging
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 32: Chapter 7: Plugin Packaging
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 33: Chapter 7: Plugin Packaging
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 34: Chapter 7: Plugin Packaging
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
+### `src/features/SettingsTab.ts`
+
+The `SettingsTab` class in [`src/features/SettingsTab.ts`](https://github.com/vslinko/obsidian-outliner/blob/HEAD/src/features/SettingsTab.ts) handles a key part of this chapter's functionality:
+
+```ts
+}
+
+export class SettingsTab implements Feature {
+ constructor(
+ private plugin: Plugin,
+ private settings: Settings,
+ ) {}
+
+ async load() {
+ this.plugin.addSettingTab(
+ new ObsidianOutlinerPluginSettingTab(
+ this.plugin.app,
+ this.plugin,
+ this.settings,
+ ),
+ );
+ }
+
+ async unload() {}
+}
+
+```
+
+This class is important because it defines how Obsidian Outliner Plugin: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+### `src/features/VimOBehaviourOverride.ts`
+
+The `VimOBehaviourOverride` class in [`src/features/VimOBehaviourOverride.ts`](https://github.com/vslinko/obsidian-outliner/blob/HEAD/src/features/VimOBehaviourOverride.ts) handles a key part of this chapter's functionality:
+
+```ts
+}
+
+export class VimOBehaviourOverride implements Feature {
+ private inited = false;
+
+ constructor(
+ private plugin: Plugin,
+ private settings: Settings,
+ private obsidianSettings: ObsidianSettings,
+ private parser: Parser,
+ private operationPerformer: OperationPerformer,
+ ) {}
+
+ async load() {
+ this.settings.onChange(this.handleSettingsChange);
+ this.handleSettingsChange();
+ }
+
+ private handleSettingsChange = () => {
+ if (!this.settings.overrideVimOBehaviour) {
+ return;
+ }
+
+ if (!window.CodeMirrorAdapter || !window.CodeMirrorAdapter.Vim) {
+ console.error("Vim adapter not found");
+ return;
+ }
+
+ const vim = window.CodeMirrorAdapter.Vim;
+ const plugin = this.plugin;
+ const parser = this.parser;
+ const obsidianSettings = this.obsidianSettings;
+```
+
+This class is important because it defines how Obsidian Outliner Plugin: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+### `src/features/VimOBehaviourOverride.ts`
+
+The `Vim` interface in [`src/features/VimOBehaviourOverride.ts`](https://github.com/vslinko/obsidian-outliner/blob/HEAD/src/features/VimOBehaviourOverride.ts) handles a key part of this chapter's functionality:
+
+```ts
+ type CM = object;
+
+ interface Vim {
+ defineAction<T>(name: string, fn: (cm: CM, args: T) => void): void;
+
+ handleEx(cm: CM, command: string): void;
+
+ enterInsertMode(cm: CM): void;
+
+ mapCommand(
+ keys: string,
+ type: string,
+ name: string,
+ args: Record<string, unknown>,
+ extra: Record<string, unknown>,
+ ): void;
+ }
+
+ interface Window {
+ CodeMirrorAdapter?: {
+ Vim?: Vim;
+ };
+ }
+}
+
+export class VimOBehaviourOverride implements Feature {
+ private inited = false;
+
+ constructor(
+ private plugin: Plugin,
+ private settings: Settings,
+ private obsidianSettings: ObsidianSettings,
+```
+
+This interface is important because it defines how Obsidian Outliner Plugin: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+### `src/features/VimOBehaviourOverride.ts`
+
+The `Window` interface in [`src/features/VimOBehaviourOverride.ts`](https://github.com/vslinko/obsidian-outliner/blob/HEAD/src/features/VimOBehaviourOverride.ts) handles a key part of this chapter's functionality:
+
+```ts
+ }
+
+ interface Window {
+ CodeMirrorAdapter?: {
+ Vim?: Vim;
+ };
+ }
+}
+
+export class VimOBehaviourOverride implements Feature {
+ private inited = false;
+
+ constructor(
+ private plugin: Plugin,
+ private settings: Settings,
+ private obsidianSettings: ObsidianSettings,
+ private parser: Parser,
+ private operationPerformer: OperationPerformer,
+ ) {}
+
+ async load() {
+ this.settings.onChange(this.handleSettingsChange);
+ this.handleSettingsChange();
+ }
+
+ private handleSettingsChange = () => {
+ if (!this.settings.overrideVimOBehaviour) {
+ return;
+ }
+
+ if (!window.CodeMirrorAdapter || !window.CodeMirrorAdapter.Vim) {
+ console.error("Vim adapter not found");
+```
+
+This interface is important because it defines how Obsidian Outliner Plugin: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+
+## How These Components Connect
+
+```mermaid
+flowchart TD
+ A[SettingsTab]
+ B[VimOBehaviourOverride]
+ C[Vim]
+ D[Window]
+ E[ChangesApplicator]
+ A --> B
+ B --> C
+ C --> D
+ D --> E
+```
diff --git a/tutorials/obsidian-outliner-tutorial/08-production-maintenance.md b/tutorials/obsidian-outliner-tutorial/08-production-maintenance.md
index e562965a..660acef4 100644
--- a/tutorials/obsidian-outliner-tutorial/08-production-maintenance.md
+++ b/tutorials/obsidian-outliner-tutorial/08-production-maintenance.md
@@ -6,6 +6,7 @@ has_children: false
parent: "Obsidian Outliner Plugin"
---
+
# Chapter 8: Production Maintenance
Welcome to **Chapter 8: Production Maintenance**. In this part of **Obsidian Outliner Plugin: Deep Dive Tutorial**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
@@ -89,502 +90,184 @@ Suggested trace strategy:
## Depth Expansion Playbook
-<!-- depth-expansion-v2 -->
-
-This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
-
-### Strategic Context
-
-- tutorial: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- tutorial slug: **obsidian-outliner-tutorial**
-- chapter focus: **Chapter 8: Production Maintenance**
-- system context: **Obsidian Outliner Plugin**
-- objective: move from surface-level usage to repeatable engineering operation
-
-### Architecture Decomposition
-
-1. Define the runtime boundary for `Chapter 8: Production Maintenance`.
-2. Separate control-plane decisions from data-plane execution.
-3. Capture input contracts, transformation points, and output contracts.
-4. Trace state transitions across request lifecycle stages.
-5. Identify extension hooks and policy interception points.
-6. Map ownership boundaries for team and automation workflows.
-7. Specify rollback and recovery paths for unsafe changes.
-8. Track observability signals for correctness, latency, and cost.
-
-### Operator Decision Matrix
-
-| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
-|:--------------|:--------------|:------------------|:---------|
-| Runtime mode | managed defaults | explicit policy config | speed vs control |
-| State handling | local ephemeral | durable persisted state | simplicity vs auditability |
-| Tool integration | direct API use | mediated adapter layer | velocity vs governance |
-| Rollout method | manual change | staged + canary rollout | effort vs safety |
-| Incident response | best effort logs | runbooks + SLO alerts | cost vs reliability |
-
-### Failure Modes and Countermeasures
-
-| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
-|:-------------|:-------------|:-------------------|:---------------|
-| stale context | inconsistent outputs | missing refresh window | enforce context TTL and refresh hooks |
-| policy drift | unexpected execution | ad hoc overrides | centralize policy profiles |
-| auth mismatch | 401/403 bursts | credential sprawl | rotation schedule + scope minimization |
-| schema breakage | parser/validation errors | unmanaged upstream changes | contract tests per release |
-| retry storms | queue congestion | no backoff controls | jittered backoff + circuit breakers |
-| silent regressions | quality drop without alerts | weak baseline metrics | eval harness with thresholds |
-
-### Implementation Runbook
-
-1. Establish a reproducible baseline environment.
-2. Capture chapter-specific success criteria before changes.
-3. Implement minimal viable path with explicit interfaces.
-4. Add observability before expanding feature scope.
-5. Run deterministic tests for happy-path behavior.
-6. Inject failure scenarios for negative-path validation.
-7. Compare output quality against baseline snapshots.
-8. Promote through staged environments with rollback gates.
-9. Record operational lessons in release notes.
-
-### Quality Gate Checklist
-
-- [ ] chapter-level assumptions are explicit and testable
-- [ ] API/tool boundaries are documented with input/output examples
-- [ ] failure handling includes retry, timeout, and fallback policy
-- [ ] security controls include auth scopes and secret rotation plans
-- [ ] observability includes logs, metrics, traces, and alert thresholds
-- [ ] deployment guidance includes canary and rollback paths
-- [ ] docs include links to upstream sources and related tracks
-- [ ] post-release verification confirms expected behavior under load
-
-### Source Alignment
+## Source Code Walkthrough
-- [Obsidian Outliner](https://github.com/vslinko/obsidian-outliner)
-- [AI Codebase Knowledge Builder](https://github.com/The-Pocket/Tutorial-Codebase-Knowledge)
-
-### Cross-Tutorial Connection Map
-
-- Related tutorials are listed in this tutorial index.
-
-### Advanced Practice Exercises
-
-1. Build a minimal end-to-end implementation for `Chapter 8: Production Maintenance`.
-2. Add instrumentation and measure baseline latency and error rate.
-3. Introduce one controlled failure and confirm graceful recovery.
-4. Add policy constraints and verify they are enforced consistently.
-5. Run a staged rollout and document rollback decision criteria.
-
-### Review Questions
-
-1. Which execution boundary matters most for this chapter and why?
-2. What signal detects regressions earliest in your environment?
-3. What tradeoff did you make between delivery speed and governance?
-4. How would you recover from the highest-impact failure mode?
-5. What must be automated before scaling to team-wide adoption?
-
-### Scenario Playbook 1: Chapter 8: Production Maintenance
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 2: Chapter 8: Production Maintenance
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 3: Chapter 8: Production Maintenance
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 4: Chapter 8: Production Maintenance
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 5: Chapter 8: Production Maintenance
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 6: Chapter 8: Production Maintenance
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 7: Chapter 8: Production Maintenance
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 8: Chapter 8: Production Maintenance
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 9: Chapter 8: Production Maintenance
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 10: Chapter 8: Production Maintenance
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 11: Chapter 8: Production Maintenance
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 12: Chapter 8: Production Maintenance
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 13: Chapter 8: Production Maintenance
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 14: Chapter 8: Production Maintenance
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 15: Chapter 8: Production Maintenance
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 16: Chapter 8: Production Maintenance
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 17: Chapter 8: Production Maintenance
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 18: Chapter 8: Production Maintenance
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 19: Chapter 8: Production Maintenance
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 20: Chapter 8: Production Maintenance
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 21: Chapter 8: Production Maintenance
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 22: Chapter 8: Production Maintenance
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 23: Chapter 8: Production Maintenance
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 24: Chapter 8: Production Maintenance
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 25: Chapter 8: Production Maintenance
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 26: Chapter 8: Production Maintenance
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 27: Chapter 8: Production Maintenance
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 28: Chapter 8: Production Maintenance
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 29: Chapter 8: Production Maintenance
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 30: Chapter 8: Production Maintenance
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 31: Chapter 8: Production Maintenance
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 32: Chapter 8: Production Maintenance
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 33: Chapter 8: Production Maintenance
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 34: Chapter 8: Production Maintenance
-
-- tutorial context: **Obsidian Outliner Plugin: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
+### `src/editor/index.ts`
+
+The `MyEditorPosition` class in [`src/editor/index.ts`](https://github.com/vslinko/obsidian-outliner/blob/HEAD/src/editor/index.ts) handles a key part of this chapter's functionality:
+
+```ts
+import { EditorView, runScopeHandlers } from "@codemirror/view";
+
+export class MyEditorPosition {
+ line: number;
+ ch: number;
+}
+
+export class MyEditorRange {
+ from: MyEditorPosition;
+ to: MyEditorPosition;
+}
+
+export class MyEditorSelection {
+ anchor: MyEditorPosition;
+ head: MyEditorPosition;
+}
+
+export function getEditorFromState(state: EditorState) {
+ const { editor } = state.field(editorInfoField);
+
+ if (!editor) {
+ return null;
+ }
+
+ return new MyEditor(editor);
+}
+
+declare global {
+ interface Window {
+ ObsidianZoomPlugin?: {
+ getZoomRange(e: Editor): MyEditorRange;
+ zoomOut(e: Editor): void;
+```
+
+This class is important because it defines how Obsidian Outliner Plugin: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+### `src/editor/index.ts`
+
+The `MyEditorRange` class in [`src/editor/index.ts`](https://github.com/vslinko/obsidian-outliner/blob/HEAD/src/editor/index.ts) handles a key part of this chapter's functionality:
+
+```ts
+}
+
+export class MyEditorRange {
+ from: MyEditorPosition;
+ to: MyEditorPosition;
+}
+
+export class MyEditorSelection {
+ anchor: MyEditorPosition;
+ head: MyEditorPosition;
+}
+
+export function getEditorFromState(state: EditorState) {
+ const { editor } = state.field(editorInfoField);
+
+ if (!editor) {
+ return null;
+ }
+
+ return new MyEditor(editor);
+}
+
+declare global {
+ interface Window {
+ ObsidianZoomPlugin?: {
+ getZoomRange(e: Editor): MyEditorRange;
+ zoomOut(e: Editor): void;
+ zoomIn(e: Editor, line: number): void;
+ refreshZoom?(e: Editor): void;
+ };
+ }
+}
+```
+
+This class is important because it defines how Obsidian Outliner Plugin: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+### `src/editor/index.ts`
+
+The `MyEditorSelection` class in [`src/editor/index.ts`](https://github.com/vslinko/obsidian-outliner/blob/HEAD/src/editor/index.ts) handles a key part of this chapter's functionality:
+
+```ts
+}
+
+export class MyEditorSelection {
+ anchor: MyEditorPosition;
+ head: MyEditorPosition;
+}
+
+export function getEditorFromState(state: EditorState) {
+ const { editor } = state.field(editorInfoField);
+
+ if (!editor) {
+ return null;
+ }
+
+ return new MyEditor(editor);
+}
+
+declare global {
+ interface Window {
+ ObsidianZoomPlugin?: {
+ getZoomRange(e: Editor): MyEditorRange;
+ zoomOut(e: Editor): void;
+ zoomIn(e: Editor, line: number): void;
+ refreshZoom?(e: Editor): void;
+ };
+ }
+}
+
+function foldInside(view: EditorView, from: number, to: number) {
+ let found: { from: number; to: number } | null = null;
+ foldedRanges(view.state).between(from, to, (from, to) => {
+ if (!found || found.from > from) found = { from, to };
+```
+
+This class is important because it defines how Obsidian Outliner Plugin: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+### `src/editor/index.ts`
+
+The `MyEditor` class in [`src/editor/index.ts`](https://github.com/vslinko/obsidian-outliner/blob/HEAD/src/editor/index.ts) handles a key part of this chapter's functionality:
+
+```ts
+import { EditorView, runScopeHandlers } from "@codemirror/view";
+
+export class MyEditorPosition {
+ line: number;
+ ch: number;
+}
+
+export class MyEditorRange {
+ from: MyEditorPosition;
+ to: MyEditorPosition;
+}
+
+export class MyEditorSelection {
+ anchor: MyEditorPosition;
+ head: MyEditorPosition;
+}
+
+export function getEditorFromState(state: EditorState) {
+ const { editor } = state.field(editorInfoField);
+
+ if (!editor) {
+ return null;
+ }
+
+ return new MyEditor(editor);
+}
+
+declare global {
+ interface Window {
+ ObsidianZoomPlugin?: {
+ getZoomRange(e: Editor): MyEditorRange;
+ zoomOut(e: Editor): void;
+```
+
+This class is important because it defines how Obsidian Outliner Plugin: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+
+## How These Components Connect
+
+```mermaid
+flowchart TD
+ A[MyEditorPosition]
+ B[MyEditorRange]
+ C[MyEditorSelection]
+ D[MyEditor]
+ E[getEditorFromState]
+ A --> B
+ B --> C
+ C --> D
+ D --> E
+```
diff --git a/tutorials/ollama-tutorial/01-getting-started.md b/tutorials/ollama-tutorial/01-getting-started.md
index b563312a..703ce9db 100644
--- a/tutorials/ollama-tutorial/01-getting-started.md
+++ b/tutorials/ollama-tutorial/01-getting-started.md
@@ -6,6 +6,7 @@ has_children: false
parent: Ollama Tutorial
---
+
# Chapter 1: Getting Started with Ollama
Welcome to **Chapter 1: Getting Started with Ollama**. In this part of **Ollama Tutorial: Running and Serving LLMs Locally**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
@@ -449,186 +450,184 @@ The `config.json` file is rarely needed -- environment variables and CLI flags c
Next: [Chapter 2: Models & Modelfiles](02-models.md)
-## Depth Expansion Playbook
+## Source Code Walkthrough
+
+### `middleware/anthropic.go`
+
+The `writeError` function in [`middleware/anthropic.go`](https://github.com/ollama/ollama/blob/HEAD/middleware/anthropic.go) handles a key part of this chapter's functionality:
+
+```go
+}
-<!-- depth-expansion-v2 -->
-
-This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
-
-### Strategic Context
-
-- tutorial: **Ollama Tutorial: Running and Serving LLMs Locally**
-- tutorial slug: **ollama-tutorial**
-- chapter focus: **Chapter 1: Getting Started with Ollama**
-- system context: **Ollama Tutorial**
-- objective: move from surface-level usage to repeatable engineering operation
-
-### Architecture Decomposition
-
-1. Define the runtime boundary for `Chapter 1: Getting Started with Ollama`.
-2. Separate control-plane decisions from data-plane execution.
-3. Capture input contracts, transformation points, and output contracts.
-4. Trace state transitions across request lifecycle stages.
-5. Identify extension hooks and policy interception points.
-6. Map ownership boundaries for team and automation workflows.
-7. Specify rollback and recovery paths for unsafe changes.
-8. Track observability signals for correctness, latency, and cost.
-
-### Operator Decision Matrix
-
-| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
-|:--------------|:--------------|:------------------|:---------|
-| Runtime mode | managed defaults | explicit policy config | speed vs control |
-| State handling | local ephemeral | durable persisted state | simplicity vs auditability |
-| Tool integration | direct API use | mediated adapter layer | velocity vs governance |
-| Rollout method | manual change | staged + canary rollout | effort vs safety |
-| Incident response | best effort logs | runbooks + SLO alerts | cost vs reliability |
-
-### Failure Modes and Countermeasures
-
-| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
-|:-------------|:-------------|:-------------------|:---------------|
-| stale context | inconsistent outputs | missing refresh window | enforce context TTL and refresh hooks |
-| policy drift | unexpected execution | ad hoc overrides | centralize policy profiles |
-| auth mismatch | 401/403 bursts | credential sprawl | rotation schedule + scope minimization |
-| schema breakage | parser/validation errors | unmanaged upstream changes | contract tests per release |
-| retry storms | queue congestion | no backoff controls | jittered backoff + circuit breakers |
-| silent regressions | quality drop without alerts | weak baseline metrics | eval harness with thresholds |
-
-### Implementation Runbook
-
-1. Establish a reproducible baseline environment.
-2. Capture chapter-specific success criteria before changes.
-3. Implement minimal viable path with explicit interfaces.
-4. Add observability before expanding feature scope.
-5. Run deterministic tests for happy-path behavior.
-6. Inject failure scenarios for negative-path validation.
-7. Compare output quality against baseline snapshots.
-8. Promote through staged environments with rollback gates.
-9. Record operational lessons in release notes.
-
-### Quality Gate Checklist
-
-- [ ] chapter-level assumptions are explicit and testable
-- [ ] API/tool boundaries are documented with input/output examples
-- [ ] failure handling includes retry, timeout, and fallback policy
-- [ ] security controls include auth scopes and secret rotation plans
-- [ ] observability includes logs, metrics, traces, and alert thresholds
-- [ ] deployment guidance includes canary and rollback paths
-- [ ] docs include links to upstream sources and related tracks
-- [ ] post-release verification confirms expected behavior under load
+func (w *AnthropicWriter) writeError(data []byte) (int, error) {
+ var errData struct {
+ Error string `json:"error"`
+ }
+ if err := json.Unmarshal(data, &errData); err != nil {
+ // If the error response isn't valid JSON, use the raw bytes as the
+ // error message rather than surfacing a confusing JSON parse error.
+ errData.Error = string(data)
+ }
-### Source Alignment
-
-- [Ollama Repository](https://github.com/ollama/ollama)
-- [Ollama Releases](https://github.com/ollama/ollama/releases)
-- [Ollama Website and Docs](https://ollama.com/)
-
-### Cross-Tutorial Connection Map
+ w.ResponseWriter.Header().Set("Content-Type", "application/json")
+ if err := json.NewEncoder(w.ResponseWriter).Encode(anthropic.NewError(w.Status(), errData.Error)); err != nil {
+ return 0, err
+ }
-- [Open WebUI Tutorial](../open-webui-tutorial/)
-- [LiteLLM Tutorial](../litellm-tutorial/)
-- [Llama.cpp Tutorial](../llama-cpp-tutorial/)
-- [VLLM Tutorial](../vllm-tutorial/)
-- [Chapter 1: Getting Started](01-getting-started.md)
-
-### Advanced Practice Exercises
-
-1. Build a minimal end-to-end implementation for `Chapter 1: Getting Started with Ollama`.
-2. Add instrumentation and measure baseline latency and error rate.
-3. Introduce one controlled failure and confirm graceful recovery.
-4. Add policy constraints and verify they are enforced consistently.
-5. Run a staged rollout and document rollback decision criteria.
-
-### Review Questions
-
-1. Which execution boundary matters most for this chapter and why?
-2. What signal detects regressions earliest in your environment?
-3. What tradeoff did you make between delivery speed and governance?
-4. How would you recover from the highest-impact failure mode?
-5. What must be automated before scaling to team-wide adoption?
-
-### Scenario Playbook 1: Chapter 1: Getting Started with Ollama
-
-- tutorial context: **Ollama Tutorial: Running and Serving LLMs Locally**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 2: Chapter 1: Getting Started with Ollama
-
-- tutorial context: **Ollama Tutorial: Running and Serving LLMs Locally**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 3: Chapter 1: Getting Started with Ollama
-
-- tutorial context: **Ollama Tutorial: Running and Serving LLMs Locally**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-## What Problem Does This Solve?
-
-Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for `ollama`, `model`, `content` so behavior stays predictable as complexity grows.
-
-In practical terms, this chapter helps you avoid three common failures:
-
-- coupling core logic too tightly to one implementation path
-- missing the handoff boundaries between setup, execution, and validation
-- shipping changes without clear rollback or observability strategy
+ return len(data), nil
+}
+
+func (w *AnthropicWriter) writeEvent(eventType string, data any) error {
+ return writeSSE(w.ResponseWriter, eventType, data)
+}
+
+func (w *AnthropicWriter) writeResponse(data []byte) (int, error) {
+ var chatResponse api.ChatResponse
+ err := json.Unmarshal(data, &chatResponse)
+ if err != nil {
+ return 0, err
+ }
+
+ if w.stream {
+```
-After working through this chapter, you should be able to reason about `Chapter 1: Getting Started with Ollama` as an operating subsystem inside **Ollama Tutorial: Running and Serving LLMs Locally**, with explicit contracts for inputs, state transitions, and outputs.
-
-Use the implementation notes around `llama3`, `chat`, `role` as your checklist when adapting these patterns to your own repository.
-
-## How it Works Under the Hood
-
-Under the hood, `Chapter 1: Getting Started with Ollama` usually follows a repeatable control path:
+This function is important because it defines how Ollama Tutorial: Running and Serving LLMs Locally implements the patterns covered in this chapter.
-1. **Context bootstrap**: initialize runtime config and prerequisites for `ollama`.
-2. **Input normalization**: shape incoming data so `model` receives stable contracts.
-3. **Core execution**: run the main logic branch and propagate intermediate state through `content`.
-4. **Policy and safety checks**: enforce limits, auth scopes, and failure boundaries.
-5. **Output composition**: return canonical result payloads for downstream consumers.
-6. **Operational telemetry**: emit logs/metrics needed for debugging and performance tuning.
+### `middleware/anthropic.go`
-When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+The `writeEvent` function in [`middleware/anthropic.go`](https://github.com/ollama/ollama/blob/HEAD/middleware/anthropic.go) handles a key part of this chapter's functionality:
-## Source Walkthrough
+```go
+}
-Use the following upstream sources to verify implementation details while reading this chapter:
+func (w *AnthropicWriter) writeEvent(eventType string, data any) error {
+ return writeSSE(w.ResponseWriter, eventType, data)
+}
-- [Ollama Repository](https://github.com/ollama/ollama)
- Why it matters: authoritative reference on `Ollama Repository` (github.com).
-- [Ollama Releases](https://github.com/ollama/ollama/releases)
- Why it matters: authoritative reference on `Ollama Releases` (github.com).
-- [Ollama Website and Docs](https://ollama.com/)
- Why it matters: authoritative reference on `Ollama Website and Docs` (ollama.com).
+func (w *AnthropicWriter) writeResponse(data []byte) (int, error) {
+ var chatResponse api.ChatResponse
+ err := json.Unmarshal(data, &chatResponse)
+ if err != nil {
+ return 0, err
+ }
+
+ if w.stream {
+ w.ResponseWriter.Header().Set("Content-Type", "text/event-stream")
+
+ events := w.converter.Process(chatResponse)
+ logutil.Trace("anthropic middleware: stream chunk", "resp", anthropic.TraceChatResponse(chatResponse), "events", len(events))
+ for _, event := range events {
+ if err := w.writeEvent(event.Event, event.Data); err != nil {
+ return 0, err
+ }
+ }
+ return len(data), nil
+ }
+
+ w.ResponseWriter.Header().Set("Content-Type", "application/json")
+ response := anthropic.ToMessagesResponse(w.id, chatResponse)
+ logutil.Trace("anthropic middleware: converted response", "resp", anthropic.TraceMessagesResponse(response))
+ return len(data), json.NewEncoder(w.ResponseWriter).Encode(response)
+}
+
+```
+
+This function is important because it defines how Ollama Tutorial: Running and Serving LLMs Locally implements the patterns covered in this chapter.
+
+### `middleware/anthropic.go`
+
+The `writeResponse` function in [`middleware/anthropic.go`](https://github.com/ollama/ollama/blob/HEAD/middleware/anthropic.go) handles a key part of this chapter's functionality:
+
+```go
+}
+
+func (w *AnthropicWriter) writeResponse(data []byte) (int, error) {
+ var chatResponse api.ChatResponse
+ err := json.Unmarshal(data, &chatResponse)
+ if err != nil {
+ return 0, err
+ }
+
+ if w.stream {
+ w.ResponseWriter.Header().Set("Content-Type", "text/event-stream")
+
+ events := w.converter.Process(chatResponse)
+ logutil.Trace("anthropic middleware: stream chunk", "resp", anthropic.TraceChatResponse(chatResponse), "events", len(events))
+ for _, event := range events {
+ if err := w.writeEvent(event.Event, event.Data); err != nil {
+ return 0, err
+ }
+ }
+ return len(data), nil
+ }
+
+ w.ResponseWriter.Header().Set("Content-Type", "application/json")
+ response := anthropic.ToMessagesResponse(w.id, chatResponse)
+ logutil.Trace("anthropic middleware: converted response", "resp", anthropic.TraceMessagesResponse(response))
+ return len(data), json.NewEncoder(w.ResponseWriter).Encode(response)
+}
+
+func (w *AnthropicWriter) Write(data []byte) (int, error) {
+ code := w.ResponseWriter.Status()
+ if code != http.StatusOK {
+ return w.writeError(data)
+```
-Suggested trace strategy:
-- search upstream code for `ollama` and `model` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
+This function is important because it defines how Ollama Tutorial: Running and Serving LLMs Locally implements the patterns covered in this chapter.
-## Chapter Connections
+### `middleware/anthropic.go`
-- [Tutorial Index](README.md)
-- [Next Chapter: Chapter 2: Models, Pulling, and Modelfiles](02-models.md)
-- [Main Catalog](../../README.md#-tutorial-catalog)
-- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
+The `Write` function in [`middleware/anthropic.go`](https://github.com/ollama/ollama/blob/HEAD/middleware/anthropic.go) handles a key part of this chapter's functionality:
+
+```go
+)
+
+// AnthropicWriter wraps the response writer to transform Ollama responses to Anthropic format
+type AnthropicWriter struct {
+ BaseWriter
+ stream bool
+ id string
+ converter *anthropic.StreamConverter
+}
+
+func (w *AnthropicWriter) writeError(data []byte) (int, error) {
+ var errData struct {
+ Error string `json:"error"`
+ }
+ if err := json.Unmarshal(data, &errData); err != nil {
+ // If the error response isn't valid JSON, use the raw bytes as the
+ // error message rather than surfacing a confusing JSON parse error.
+ errData.Error = string(data)
+ }
+
+ w.ResponseWriter.Header().Set("Content-Type", "application/json")
+ if err := json.NewEncoder(w.ResponseWriter).Encode(anthropic.NewError(w.Status(), errData.Error)); err != nil {
+ return 0, err
+ }
+
+ return len(data), nil
+}
+
+func (w *AnthropicWriter) writeEvent(eventType string, data any) error {
+ return writeSSE(w.ResponseWriter, eventType, data)
+}
+
+```
+
+This function is important because it defines how Ollama Tutorial: Running and Serving LLMs Locally implements the patterns covered in this chapter.
+
+
+## How These Components Connect
+
+```mermaid
+flowchart TD
+ A[writeError]
+ B[writeEvent]
+ C[writeResponse]
+ D[Write]
+ E[Error]
+ A --> B
+ B --> C
+ C --> D
+ D --> E
+```
diff --git a/tutorials/ollama-tutorial/02-models.md b/tutorials/ollama-tutorial/02-models.md
index 9eb78bb1..de1c8a99 100644
--- a/tutorials/ollama-tutorial/02-models.md
+++ b/tutorials/ollama-tutorial/02-models.md
@@ -6,6 +6,7 @@ has_children: false
parent: Ollama Tutorial
---
+
# Chapter 2: Models, Pulling, and Modelfiles
Welcome to **Chapter 2: Models, Pulling, and Modelfiles**. In this part of **Ollama Tutorial: Running and Serving LLMs Locally**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
@@ -568,151 +569,184 @@ In this chapter you learned how to browse and pull models, compare popular optio
Previous: [Chapter 1: Getting Started](01-getting-started.md) | Next: [Chapter 3: Chat & Completions](03-chat-completions.md)
-## Depth Expansion Playbook
-
-<!-- depth-expansion-v2 -->
-
-This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
-
-### Strategic Context
-
-- tutorial: **Ollama Tutorial: Running and Serving LLMs Locally**
-- tutorial slug: **ollama-tutorial**
-- chapter focus: **Chapter 2: Models, Pulling, and Modelfiles**
-- system context: **Ollama Tutorial**
-- objective: move from surface-level usage to repeatable engineering operation
-
-### Architecture Decomposition
-
-1. Define the runtime boundary for `Chapter 2: Models, Pulling, and Modelfiles`.
-2. Separate control-plane decisions from data-plane execution.
-3. Capture input contracts, transformation points, and output contracts.
-4. Trace state transitions across request lifecycle stages.
-5. Identify extension hooks and policy interception points.
-6. Map ownership boundaries for team and automation workflows.
-7. Specify rollback and recovery paths for unsafe changes.
-8. Track observability signals for correctness, latency, and cost.
-
-### Operator Decision Matrix
-
-| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
-|:--------------|:--------------|:------------------|:---------|
-| Runtime mode | managed defaults | explicit policy config | speed vs control |
-| State handling | local ephemeral | durable persisted state | simplicity vs auditability |
-| Tool integration | direct API use | mediated adapter layer | velocity vs governance |
-| Rollout method | manual change | staged + canary rollout | effort vs safety |
-| Incident response | best effort logs | runbooks + SLO alerts | cost vs reliability |
-
-### Failure Modes and Countermeasures
+## Source Code Walkthrough
-| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
-|:-------------|:-------------|:-------------------|:---------------|
-| stale context | inconsistent outputs | missing refresh window | enforce context TTL and refresh hooks |
-| policy drift | unexpected execution | ad hoc overrides | centralize policy profiles |
-| auth mismatch | 401/403 bursts | credential sprawl | rotation schedule + scope minimization |
-| schema breakage | parser/validation errors | unmanaged upstream changes | contract tests per release |
-| retry storms | queue congestion | no backoff controls | jittered backoff + circuit breakers |
-| silent regressions | quality drop without alerts | weak baseline metrics | eval harness with thresholds |
+### `server/images.go`
-### Implementation Runbook
+The `Capabilities` function in [`server/images.go`](https://github.com/ollama/ollama/blob/HEAD/server/images.go) handles a key part of this chapter's functionality:
-1. Establish a reproducible baseline environment.
-2. Capture chapter-specific success criteria before changes.
-3. Implement minimal viable path with explicit interfaces.
-4. Add observability before expanding feature scope.
-5. Run deterministic tests for happy-path behavior.
-6. Inject failure scenarios for negative-path validation.
-7. Compare output quality against baseline snapshots.
-8. Promote through staged environments with rollback gates.
-9. Record operational lessons in release notes.
+```go
-### Quality Gate Checklist
+var (
+ errCapabilities = errors.New("does not support")
+ errCapabilityCompletion = errors.New("completion")
+ errCapabilityTools = errors.New("tools")
+ errCapabilityInsert = errors.New("insert")
+ errCapabilityVision = errors.New("vision")
+ errCapabilityAudio = errors.New("audio")
+ errCapabilityEmbedding = errors.New("embedding")
+ errCapabilityThinking = errors.New("thinking")
+ errCapabilityImage = errors.New("image generation")
+ errInsecureProtocol = errors.New("insecure protocol http")
+)
-- [ ] chapter-level assumptions are explicit and testable
-- [ ] API/tool boundaries are documented with input/output examples
-- [ ] failure handling includes retry, timeout, and fallback policy
-- [ ] security controls include auth scopes and secret rotation plans
-- [ ] observability includes logs, metrics, traces, and alert thresholds
-- [ ] deployment guidance includes canary and rollback paths
-- [ ] docs include links to upstream sources and related tracks
-- [ ] post-release verification confirms expected behavior under load
+type registryOptions struct {
+ Insecure bool
+ Username string
+ Password string
+ Token string
-### Source Alignment
+ CheckRedirect func(req *http.Request, via []*http.Request) error
+}
-- [Ollama Repository](https://github.com/ollama/ollama)
-- [Ollama Releases](https://github.com/ollama/ollama/releases)
-- [Ollama Website and Docs](https://ollama.com/)
+type Model struct {
+ Name string `json:"name"`
+ Config model.ConfigV2
+ ShortName string
+ ModelPath string
+ ParentModel string
+ AdapterPaths []string
+ ProjectorPaths []string
+ System string
+```
-### Cross-Tutorial Connection Map
+This function is important because it defines how Ollama Tutorial: Running and Serving LLMs Locally implements the patterns covered in this chapter.
-- [Open WebUI Tutorial](../open-webui-tutorial/)
-- [LiteLLM Tutorial](../litellm-tutorial/)
-- [Llama.cpp Tutorial](../llama-cpp-tutorial/)
-- [VLLM Tutorial](../vllm-tutorial/)
-- [Chapter 1: Getting Started](01-getting-started.md)
+### `server/images.go`
-### Advanced Practice Exercises
+The `CheckCapabilities` function in [`server/images.go`](https://github.com/ollama/ollama/blob/HEAD/server/images.go) handles a key part of this chapter's functionality:
-1. Build a minimal end-to-end implementation for `Chapter 2: Models, Pulling, and Modelfiles`.
-2. Add instrumentation and measure baseline latency and error rate.
-3. Introduce one controlled failure and confirm graceful recovery.
-4. Add policy constraints and verify they are enforced consistently.
-5. Run a staged rollout and document rollback decision criteria.
+```go
+}
-### Review Questions
+// CheckCapabilities checks if the model has the specified capabilities returning an error describing
+// any missing or unknown capabilities
+func (m *Model) CheckCapabilities(want ...model.Capability) error {
+ available := m.Capabilities()
+ var errs []error
+
+ // Map capabilities to their corresponding error
+ capToErr := map[model.Capability]error{
+ model.CapabilityCompletion: errCapabilityCompletion,
+ model.CapabilityTools: errCapabilityTools,
+ model.CapabilityInsert: errCapabilityInsert,
+ model.CapabilityVision: errCapabilityVision,
+ model.CapabilityAudio: errCapabilityAudio,
+ model.CapabilityEmbedding: errCapabilityEmbedding,
+ model.CapabilityThinking: errCapabilityThinking,
+ model.CapabilityImage: errCapabilityImage,
+ }
+
+ for _, cap := range want {
+ err, ok := capToErr[cap]
+ if !ok {
+ slog.Error("unknown capability", "capability", cap)
+ return fmt.Errorf("unknown capability: %s", cap)
+ }
+
+ if !slices.Contains(available, cap) {
+ errs = append(errs, err)
+ }
+ }
-1. Which execution boundary matters most for this chapter and why?
-2. What signal detects regressions earliest in your environment?
-3. What tradeoff did you make between delivery speed and governance?
-4. How would you recover from the highest-impact failure mode?
-5. What must be automated before scaling to team-wide adoption?
+```
-## What Problem Does This Solve?
+This function is important because it defines how Ollama Tutorial: Running and Serving LLMs Locally implements the patterns covered in this chapter.
-Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for `ollama`, `PARAMETER`, `model` so behavior stays predictable as complexity grows.
+### `server/images.go`
-In practical terms, this chapter helps you avoid three common failures:
+The `String` function in [`server/images.go`](https://github.com/ollama/ollama/blob/HEAD/server/images.go) handles a key part of this chapter's functionality:
-- coupling core logic too tightly to one implementation path
-- missing the handoff boundaries between setup, execution, and validation
-- shipping changes without clear rollback or observability strategy
-
-After working through this chapter, you should be able to reason about `Chapter 2: Models, Pulling, and Modelfiles` as an operating subsystem inside **Ollama Tutorial: Running and Serving LLMs Locally**, with explicit contracts for inputs, state transitions, and outputs.
+```go
+}
-Use the implementation notes around `Modelfile`, `llama3`, `assistant` as your checklist when adapting these patterns to your own repository.
+func (m *Model) String() string {
+ var modelfile parser.Modelfile
+
+ modelfile.Commands = append(modelfile.Commands, parser.Command{
+ Name: "model",
+ Args: m.ModelPath,
+ })
+
+ for _, adapter := range m.AdapterPaths {
+ modelfile.Commands = append(modelfile.Commands, parser.Command{
+ Name: "adapter",
+ Args: adapter,
+ })
+ }
+
+ for _, projector := range m.ProjectorPaths {
+ modelfile.Commands = append(modelfile.Commands, parser.Command{
+ Name: "model",
+ Args: projector,
+ })
+ }
+
+ if m.Template != nil {
+ modelfile.Commands = append(modelfile.Commands, parser.Command{
+ Name: "template",
+ Args: m.Template.String(),
+ })
+ }
+
+ if m.System != "" {
+```
-## How it Works Under the Hood
+This function is important because it defines how Ollama Tutorial: Running and Serving LLMs Locally implements the patterns covered in this chapter.
-Under the hood, `Chapter 2: Models, Pulling, and Modelfiles` usually follows a repeatable control path:
-
-1. **Context bootstrap**: initialize runtime config and prerequisites for `ollama`.
-2. **Input normalization**: shape incoming data so `PARAMETER` receives stable contracts.
-3. **Core execution**: run the main logic branch and propagate intermediate state through `model`.
-4. **Policy and safety checks**: enforce limits, auth scopes, and failure boundaries.
-5. **Output composition**: return canonical result payloads for downstream consumers.
-6. **Operational telemetry**: emit logs/metrics needed for debugging and performance tuning.
+### `server/images.go`
-When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+The `GetModel` function in [`server/images.go`](https://github.com/ollama/ollama/blob/HEAD/server/images.go) handles a key part of this chapter's functionality:
-## Source Walkthrough
+```go
+}
-Use the following upstream sources to verify implementation details while reading this chapter:
+func GetModel(name string) (*Model, error) {
+ n := model.ParseName(name)
+ mf, err := manifest.ParseNamedManifest(n)
+ if err != nil {
+ return nil, err
+ }
+
+ m := &Model{
+ Name: n.String(),
+ ShortName: n.DisplayShortest(),
+ Digest: mf.Digest(),
+ Template: template.DefaultTemplate,
+ }
+
+ if mf.Config.Digest != "" {
+ filename, err := manifest.BlobsPath(mf.Config.Digest)
+ if err != nil {
+ return nil, err
+ }
+
+ configFile, err := os.Open(filename)
+ if err != nil {
+ return nil, err
+ }
+ defer configFile.Close()
+
+ if err := json.NewDecoder(configFile).Decode(&m.Config); err != nil {
+ return nil, err
+ }
+ }
+```
-- [Ollama Repository](https://github.com/ollama/ollama)
- Why it matters: authoritative reference on `Ollama Repository` (github.com).
-- [Ollama Releases](https://github.com/ollama/ollama/releases)
- Why it matters: authoritative reference on `Ollama Releases` (github.com).
-- [Ollama Website and Docs](https://ollama.com/)
- Why it matters: authoritative reference on `Ollama Website and Docs` (ollama.com).
+This function is important because it defines how Ollama Tutorial: Running and Serving LLMs Locally implements the patterns covered in this chapter.
-Suggested trace strategy:
-- search upstream code for `ollama` and `PARAMETER` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
-## Chapter Connections
+## How These Components Connect
-- [Tutorial Index](README.md)
-- [Previous Chapter: Chapter 1: Getting Started with Ollama](01-getting-started.md)
-- [Next Chapter: Chapter 3: Chat, Completions, and Parameters](03-chat-completions.md)
-- [Main Catalog](../../README.md#-tutorial-catalog)
-- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
+```mermaid
+flowchart TD
+ A[Capabilities]
+ B[CheckCapabilities]
+ C[String]
+ D[GetModel]
+ E[CopyModel]
+ A --> B
+ B --> C
+ C --> D
+ D --> E
+```
diff --git a/tutorials/ollama-tutorial/05-modelfiles-custom.md b/tutorials/ollama-tutorial/05-modelfiles-custom.md
index a4d67872..68a7b7d9 100644
--- a/tutorials/ollama-tutorial/05-modelfiles-custom.md
+++ b/tutorials/ollama-tutorial/05-modelfiles-custom.md
@@ -6,6 +6,7 @@ has_children: false
parent: Ollama Tutorial
---
+
# Chapter 5: Modelfiles, Templates, and Custom Models
Welcome to **Chapter 5: Modelfiles, Templates, and Custom Models**. In this part of **Ollama Tutorial: Running and Serving LLMs Locally**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
@@ -571,151 +572,184 @@ ollama push yourname/code-reviewer:v1.0
| Next | [Chapter 6: Performance & Hardware Tuning](./06-performance.md) |
| Index | [Ollama Tutorial Home](./README.md) |
-## Depth Expansion Playbook
-
-<!-- depth-expansion-v2 -->
-
-This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
-
-### Strategic Context
-
-- tutorial: **Ollama Tutorial: Running and Serving LLMs Locally**
-- tutorial slug: **ollama-tutorial**
-- chapter focus: **Chapter 5: Modelfiles, Templates, and Custom Models**
-- system context: **Ollama Tutorial**
-- objective: move from surface-level usage to repeatable engineering operation
-
-### Architecture Decomposition
-
-1. Define the runtime boundary for `Chapter 5: Modelfiles, Templates, and Custom Models`.
-2. Separate control-plane decisions from data-plane execution.
-3. Capture input contracts, transformation points, and output contracts.
-4. Trace state transitions across request lifecycle stages.
-5. Identify extension hooks and policy interception points.
-6. Map ownership boundaries for team and automation workflows.
-7. Specify rollback and recovery paths for unsafe changes.
-8. Track observability signals for correctness, latency, and cost.
-
-### Operator Decision Matrix
-
-| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
-|:--------------|:--------------|:------------------|:---------|
-| Runtime mode | managed defaults | explicit policy config | speed vs control |
-| State handling | local ephemeral | durable persisted state | simplicity vs auditability |
-| Tool integration | direct API use | mediated adapter layer | velocity vs governance |
-| Rollout method | manual change | staged + canary rollout | effort vs safety |
-| Incident response | best effort logs | runbooks + SLO alerts | cost vs reliability |
-
-### Failure Modes and Countermeasures
-
-| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
-|:-------------|:-------------|:-------------------|:---------------|
-| stale context | inconsistent outputs | missing refresh window | enforce context TTL and refresh hooks |
-| policy drift | unexpected execution | ad hoc overrides | centralize policy profiles |
-| auth mismatch | 401/403 bursts | credential sprawl | rotation schedule + scope minimization |
-| schema breakage | parser/validation errors | unmanaged upstream changes | contract tests per release |
-| retry storms | queue congestion | no backoff controls | jittered backoff + circuit breakers |
-| silent regressions | quality drop without alerts | weak baseline metrics | eval harness with thresholds |
-
-### Implementation Runbook
-
-1. Establish a reproducible baseline environment.
-2. Capture chapter-specific success criteria before changes.
-3. Implement minimal viable path with explicit interfaces.
-4. Add observability before expanding feature scope.
-5. Run deterministic tests for happy-path behavior.
-6. Inject failure scenarios for negative-path validation.
-7. Compare output quality against baseline snapshots.
-8. Promote through staged environments with rollback gates.
-9. Record operational lessons in release notes.
-
-### Quality Gate Checklist
+## Source Code Walkthrough
-- [ ] chapter-level assumptions are explicit and testable
-- [ ] API/tool boundaries are documented with input/output examples
-- [ ] failure handling includes retry, timeout, and fallback policy
-- [ ] security controls include auth scopes and secret rotation plans
-- [ ] observability includes logs, metrics, traces, and alert thresholds
-- [ ] deployment guidance includes canary and rollback paths
-- [ ] docs include links to upstream sources and related tracks
-- [ ] post-release verification confirms expected behavior under load
+### `ml/device.go`
-### Source Alignment
+The `updateVisibleDevicesEnv` function in [`ml/device.go`](https://github.com/ollama/ollama/blob/HEAD/ml/device.go) handles a key part of this chapter's functionality:
-- [Ollama Repository](https://github.com/ollama/ollama)
-- [Ollama Releases](https://github.com/ollama/ollama/releases)
-- [Ollama Website and Docs](https://ollama.com/)
-
-### Cross-Tutorial Connection Map
-
-- [Open WebUI Tutorial](../open-webui-tutorial/)
-- [LiteLLM Tutorial](../litellm-tutorial/)
-- [Llama.cpp Tutorial](../llama-cpp-tutorial/)
-- [VLLM Tutorial](../vllm-tutorial/)
-- [Chapter 1: Getting Started](01-getting-started.md)
-
-### Advanced Practice Exercises
-
-1. Build a minimal end-to-end implementation for `Chapter 5: Modelfiles, Templates, and Custom Models`.
-2. Add instrumentation and measure baseline latency and error rate.
-3. Introduce one controlled failure and confirm graceful recovery.
-4. Add policy constraints and verify they are enforced consistently.
-5. Run a staged rollout and document rollback decision criteria.
+```go
+ env := map[string]string{}
+ for _, d := range l {
+ d.updateVisibleDevicesEnv(env, mustFilter)
+ }
+ return env
+}
-### Review Questions
+// NeedsInitValidation returns true if the device in question has the potential
+// to crash at inference time and requires deeper validation before we include
+// it in the supported devices list.
+func (d DeviceInfo) NeedsInitValidation() bool {
+ // ROCm: rocblas will crash on unsupported devices.
+ // CUDA: verify CC is supported by the version of the library
+ return d.Library == "ROCm" || d.Library == "CUDA"
+}
-1. Which execution boundary matters most for this chapter and why?
-2. What signal detects regressions earliest in your environment?
-3. What tradeoff did you make between delivery speed and governance?
-4. How would you recover from the highest-impact failure mode?
-5. What must be automated before scaling to team-wide adoption?
+// Set the init validation environment variable
+func (d DeviceInfo) AddInitValidation(env map[string]string) {
+ env["GGML_CUDA_INIT"] = "1" // force deep initialization to trigger crash on unsupported GPUs
+}
-## What Problem Does This Solve?
+// PreferredLibrary returns true if this library is preferred over the other input
+// library
+// Used to filter out Vulkan in favor of CUDA or ROCm
+func (d DeviceInfo) PreferredLibrary(other DeviceInfo) bool {
+ // TODO in the future if we find Vulkan is better than ROCm on some devices
+ // that implementation can live here.
-Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for `PARAMETER`, `code`, `ollama` so behavior stays predictable as complexity grows.
+ if d.Library == "CUDA" || d.Library == "ROCm" {
+ return true
+ }
+ return false
+```
-In practical terms, this chapter helps you avoid three common failures:
+This function is important because it defines how Ollama Tutorial: Running and Serving LLMs Locally implements the patterns covered in this chapter.
-- coupling core logic too tightly to one implementation path
-- missing the handoff boundaries between setup, execution, and validation
-- shipping changes without clear rollback or observability strategy
-
-After working through this chapter, you should be able to reason about `Chapter 5: Modelfiles, Templates, and Custom Models` as an operating subsystem inside **Ollama Tutorial: Running and Serving LLMs Locally**, with explicit contracts for inputs, state transitions, and outputs.
+### `ml/device.go`
-Use the implementation notes around `reviewer`, `System`, `Modelfile` as your checklist when adapting these patterns to your own repository.
+The `GetDevicesFromRunner` function in [`ml/device.go`](https://github.com/ollama/ollama/blob/HEAD/ml/device.go) handles a key part of this chapter's functionality:
-## How it Works Under the Hood
+```go
+}
-Under the hood, `Chapter 5: Modelfiles, Templates, and Custom Models` usually follows a repeatable control path:
-
-1. **Context bootstrap**: initialize runtime config and prerequisites for `PARAMETER`.
-2. **Input normalization**: shape incoming data so `code` receives stable contracts.
-3. **Core execution**: run the main logic branch and propagate intermediate state through `ollama`.
-4. **Policy and safety checks**: enforce limits, auth scopes, and failure boundaries.
-5. **Output composition**: return canonical result payloads for downstream consumers.
-6. **Operational telemetry**: emit logs/metrics needed for debugging and performance tuning.
+func GetDevicesFromRunner(ctx context.Context, runner BaseRunner) ([]DeviceInfo, error) {
+ var moreDevices []DeviceInfo
+ port := runner.GetPort()
+ tick := time.Tick(10 * time.Millisecond)
+ for {
+ select {
+ case <-ctx.Done():
+ return nil, fmt.Errorf("failed to finish discovery before timeout")
+ case <-tick:
+ r, err := http.NewRequestWithContext(ctx, http.MethodGet, fmt.Sprintf("http://127.0.0.1:%d/info", port), nil)
+ if err != nil {
+ return nil, fmt.Errorf("failed to create request: %w", err)
+ }
+ r.Header.Set("Content-Type", "application/json")
+
+ resp, err := http.DefaultClient.Do(r)
+ if err != nil {
+ // slog.Warn("failed to send request", "error", err)
+ if runner.HasExited() {
+ return nil, fmt.Errorf("runner crashed")
+ }
+ continue
+ }
+ defer resp.Body.Close()
+
+ if resp.StatusCode == http.StatusNotFound {
+ // old runner, fall back to bootstrapping model
+ return nil, fmt.Errorf("llamarunner free vram reporting not supported")
+ }
+
+```
+
+This function is important because it defines how Ollama Tutorial: Running and Serving LLMs Locally implements the patterns covered in this chapter.
+
+### `convert/convert_glmocr.go`
+
+The `normalToNeoXRepacker` function in [`convert/convert_glmocr.go`](https://github.com/ollama/ollama/blob/HEAD/convert/convert_glmocr.go) handles a key part of this chapter's functionality:
+
+```go
+)
+
+// normalToNeoXRepacker creates a repacker that permutes Q/K weights from interleaved (LLaMA)
+// to NeoX ordering for compatibility with GGML's M-RoPE kernel.
+//
+// For weights: reshape [out, in] -> [n_heads, head_dim, in], permute rotary dims, reshape back
+// For biases: reshape [out] -> [n_heads, head_dim], permute rotary dims, reshape back
+func normalToNeoXRepacker(nHeads, headDim int, partialRotaryFactor float32) func(string, []float32, []uint64) ([]float32, error) {
+ return func(_ string, data []float32, shape []uint64) ([]float32, error) {
+ rotaryDim := int(float32(headDim) * partialRotaryFactor)
+ if rotaryDim%2 != 0 {
+ rotaryDim = (rotaryDim / 2) * 2 // Round down to even
+ }
+
+ // Handle 1D (bias) or 2D (weight) tensors
+ is1D := len(shape) == 1
+ var inFeatures int
+ if is1D {
+ inFeatures = 1
+ } else {
+ inFeatures = int(shape[1])
+ }
+ outFeatures := int(shape[0])
+ nEffectiveHeads := outFeatures / headDim
+
+ if nEffectiveHeads != nHeads {
+ slog.Warn("normalToNeoX: unexpected head count", "effective", nEffectiveHeads, "expected", nHeads)
+ }
+
+ // Reshape to [n_heads, head_dim, in_features]
+ reshaped := make([]float32, len(data))
+ copy(reshaped, data)
+```
+
+This function is important because it defines how Ollama Tutorial: Running and Serving LLMs Locally implements the patterns covered in this chapter.
+
+### `convert/convert_glmocr.go`
+
+The `parseMore` function in [`convert/convert_glmocr.go`](https://github.com/ollama/ollama/blob/HEAD/convert/convert_glmocr.go) handles a key part of this chapter's functionality:
+
+```go
+var _ ModelConverter = (*glmOcrModel)(nil)
+
+func (m *glmOcrModel) parseMore(fsys fs.FS) error {
+ bts, err := fs.ReadFile(fsys, "preprocessor_config.json")
+ if err != nil {
+ return err
+ }
+
+ return json.Unmarshal(bts, &m.Preprocessor)
+}
-When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+func (m *glmOcrModel) KV(t *Tokenizer) KV {
+ kv := m.ModelParameters.KV(t)
+ kv["general.architecture"] = "glmocr"
-## Source Walkthrough
+ // Text model parameters
+ kv["glmocr.block_count"] = cmp.Or(m.TextConfig.NumHiddenLayers, 16)
+ kv["glmocr.embedding_length"] = cmp.Or(m.TextConfig.HiddenSize, 1536)
+ kv["glmocr.attention.head_count"] = cmp.Or(m.TextConfig.NumAttentionHeads, 16)
+ kv["glmocr.attention.head_count_kv"] = cmp.Or(m.TextConfig.NumKeyValueHeads, 8)
+ headDim := cmp.Or(m.TextConfig.HeadDim, m.TextConfig.HiddenSize/m.TextConfig.NumAttentionHeads)
+ kv["glmocr.attention.key_length"] = headDim
+ kv["glmocr.attention.value_length"] = headDim
+ kv["glmocr.feed_forward_length"] = cmp.Or(m.TextConfig.IntermediateSize, 4608)
+ kv["glmocr.attention.layer_norm_rms_epsilon"] = cmp.Or(m.TextConfig.RMSNormEps, 1e-5)
+ kv["glmocr.context_length"] = cmp.Or(m.TextConfig.MaxPositionEmbed, 131072)
+ kv["glmocr.rope.freq_base"] = cmp.Or(m.TextConfig.RopeParameters.RopeTheta, float32(10000))
+ kv["glmocr.rope.partial_rotary_factor"] = cmp.Or(m.TextConfig.RopeParameters.PartialRotaryFactor, m.TextConfig.PartialRotaryFactor, float32(1.0))
+ if len(m.TextConfig.RopeParameters.MRopeSection) > 0 {
+ kv["glmocr.rope.mrope_section"] = m.TextConfig.RopeParameters.MRopeSection
+ }
-Use the following upstream sources to verify implementation details while reading this chapter:
+```
-- [Ollama Repository](https://github.com/ollama/ollama)
- Why it matters: authoritative reference on `Ollama Repository` (github.com).
-- [Ollama Releases](https://github.com/ollama/ollama/releases)
- Why it matters: authoritative reference on `Ollama Releases` (github.com).
-- [Ollama Website and Docs](https://ollama.com/)
- Why it matters: authoritative reference on `Ollama Website and Docs` (ollama.com).
+This function is important because it defines how Ollama Tutorial: Running and Serving LLMs Locally implements the patterns covered in this chapter.
-Suggested trace strategy:
-- search upstream code for `PARAMETER` and `code` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
-## Chapter Connections
+## How These Components Connect
-- [Tutorial Index](README.md)
-- [Previous Chapter: Chapter 4: Embeddings and RAG with Ollama](04-embeddings-rag.md)
-- [Next Chapter: Chapter 6: Performance, GPU Tuning, and Quantization](06-performance.md)
-- [Main Catalog](../../README.md#-tutorial-catalog)
-- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
+```mermaid
+flowchart TD
+ A[updateVisibleDevicesEnv]
+ B[GetDevicesFromRunner]
+ C[normalToNeoXRepacker]
+ D[parseMore]
+ E[KV]
+ A --> B
+ B --> C
+ C --> D
+ D --> E
+```
diff --git a/tutorials/ollama-tutorial/06-performance.md b/tutorials/ollama-tutorial/06-performance.md
index 0028b0f8..82584947 100644
--- a/tutorials/ollama-tutorial/06-performance.md
+++ b/tutorials/ollama-tutorial/06-performance.md
@@ -6,6 +6,7 @@ has_children: false
parent: Ollama Tutorial
---
+
# Chapter 6: Performance, GPU Tuning, and Quantization
Welcome to **Chapter 6: Performance, GPU Tuning, and Quantization**. In this part of **Ollama Tutorial: Running and Serving LLMs Locally**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
@@ -505,151 +506,184 @@ Here are ready-to-use option sets for common scenarios.
| Next | [Chapter 7: Integrations](./07-integrations.md) |
| Index | [Ollama Tutorial Home](./README.md) |
-## Depth Expansion Playbook
-
-<!-- depth-expansion-v2 -->
-
-This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
-
-### Strategic Context
+## Source Code Walkthrough
-- tutorial: **Ollama Tutorial: Running and Serving LLMs Locally**
-- tutorial slug: **ollama-tutorial**
-- chapter focus: **Chapter 6: Performance, GPU Tuning, and Quantization**
-- system context: **Ollama Tutorial**
-- objective: move from surface-level usage to repeatable engineering operation
+### `server/sched.go`
-### Architecture Decomposition
+The `processPending` function in [`server/sched.go`](https://github.com/ollama/ollama/blob/HEAD/server/sched.go) handles a key part of this chapter's functionality:
-1. Define the runtime boundary for `Chapter 6: Performance, GPU Tuning, and Quantization`.
-2. Separate control-plane decisions from data-plane execution.
-3. Capture input contracts, transformation points, and output contracts.
-4. Trace state transitions across request lifecycle stages.
-5. Identify extension hooks and policy interception points.
-6. Map ownership boundaries for team and automation workflows.
-7. Specify rollback and recovery paths for unsafe changes.
-8. Track observability signals for correctness, latency, and cost.
+```go
+ slog.Debug("starting llm scheduler")
+ go func() {
+ s.processPending(ctx)
+ }()
-### Operator Decision Matrix
+ go func() {
+ s.processCompleted(ctx)
+ }()
+}
-| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
-|:--------------|:--------------|:------------------|:---------|
-| Runtime mode | managed defaults | explicit policy config | speed vs control |
-| State handling | local ephemeral | durable persisted state | simplicity vs auditability |
-| Tool integration | direct API use | mediated adapter layer | velocity vs governance |
-| Rollout method | manual change | staged + canary rollout | effort vs safety |
-| Incident response | best effort logs | runbooks + SLO alerts | cost vs reliability |
+func (s *Scheduler) processPending(ctx context.Context) {
+ maxRunners := envconfig.MaxRunners()
+
+ for {
+ select {
+ case <-ctx.Done():
+ slog.Debug("shutting down scheduler pending loop")
+ return
+ case pending := <-s.pendingReqCh:
+ // Block other requests until we get this pending request running
+ pending.schedAttempts++
+
+ if pending.ctx.Err() != nil {
+ slog.Debug("pending request cancelled or timed out, skipping scheduling")
+ continue
+ }
+ logutil.Trace("processing incoming request", "model", pending.model.ModelPath)
+
+ for {
+ var runnerToExpire *runnerRef
+ pendingKey := schedulerModelKey(pending.model)
+ s.loadedMu.Lock()
+```
-### Failure Modes and Countermeasures
+This function is important because it defines how Ollama Tutorial: Running and Serving LLMs Locally implements the patterns covered in this chapter.
-| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
-|:-------------|:-------------|:-------------------|:---------------|
-| stale context | inconsistent outputs | missing refresh window | enforce context TTL and refresh hooks |
-| policy drift | unexpected execution | ad hoc overrides | centralize policy profiles |
-| auth mismatch | 401/403 bursts | credential sprawl | rotation schedule + scope minimization |
-| schema breakage | parser/validation errors | unmanaged upstream changes | contract tests per release |
-| retry storms | queue congestion | no backoff controls | jittered backoff + circuit breakers |
-| silent regressions | quality drop without alerts | weak baseline metrics | eval harness with thresholds |
+### `server/sched.go`
-### Implementation Runbook
+The `processCompleted` function in [`server/sched.go`](https://github.com/ollama/ollama/blob/HEAD/server/sched.go) handles a key part of this chapter's functionality:
-1. Establish a reproducible baseline environment.
-2. Capture chapter-specific success criteria before changes.
-3. Implement minimal viable path with explicit interfaces.
-4. Add observability before expanding feature scope.
-5. Run deterministic tests for happy-path behavior.
-6. Inject failure scenarios for negative-path validation.
-7. Compare output quality against baseline snapshots.
-8. Promote through staged environments with rollback gates.
-9. Record operational lessons in release notes.
+```go
-### Quality Gate Checklist
+ go func() {
+ s.processCompleted(ctx)
+ }()
+}
-- [ ] chapter-level assumptions are explicit and testable
-- [ ] API/tool boundaries are documented with input/output examples
-- [ ] failure handling includes retry, timeout, and fallback policy
-- [ ] security controls include auth scopes and secret rotation plans
-- [ ] observability includes logs, metrics, traces, and alert thresholds
-- [ ] deployment guidance includes canary and rollback paths
-- [ ] docs include links to upstream sources and related tracks
-- [ ] post-release verification confirms expected behavior under load
+func (s *Scheduler) processPending(ctx context.Context) {
+ maxRunners := envconfig.MaxRunners()
+
+ for {
+ select {
+ case <-ctx.Done():
+ slog.Debug("shutting down scheduler pending loop")
+ return
+ case pending := <-s.pendingReqCh:
+ // Block other requests until we get this pending request running
+ pending.schedAttempts++
+
+ if pending.ctx.Err() != nil {
+ slog.Debug("pending request cancelled or timed out, skipping scheduling")
+ continue
+ }
+ logutil.Trace("processing incoming request", "model", pending.model.ModelPath)
+
+ for {
+ var runnerToExpire *runnerRef
+ pendingKey := schedulerModelKey(pending.model)
+ s.loadedMu.Lock()
+ runner := s.loaded[pendingKey]
+ loadedCount := len(s.loaded)
+ runnersSnapshot := make([]ml.FilteredRunnerDiscovery, 0, len(s.loaded))
+ for _, r := range s.loaded {
+```
-### Source Alignment
+This function is important because it defines how Ollama Tutorial: Running and Serving LLMs Locally implements the patterns covered in this chapter.
-- [Ollama Repository](https://github.com/ollama/ollama)
-- [Ollama Releases](https://github.com/ollama/ollama/releases)
-- [Ollama Website and Docs](https://ollama.com/)
+### `server/sched.go`
-### Cross-Tutorial Connection Map
+The `useLoadedRunner` function in [`server/sched.go`](https://github.com/ollama/ollama/blob/HEAD/server/sched.go) handles a key part of this chapter's functionality:
-- [Open WebUI Tutorial](../open-webui-tutorial/)
-- [LiteLLM Tutorial](../litellm-tutorial/)
-- [Llama.cpp Tutorial](../llama-cpp-tutorial/)
-- [VLLM Tutorial](../vllm-tutorial/)
-- [Chapter 1: Getting Started](01-getting-started.md)
+```go
+ s.loadedMu.Unlock()
+ if runner != nil && !runner.needsReload(c, req) {
+ req.useLoadedRunner(runner, s.finishedReqCh)
+ } else {
+ select {
+ case s.pendingReqCh <- req:
+ default:
+ req.errCh <- ErrMaxQueue
+ }
+ }
+ return req.successCh, req.errCh
+}
-### Advanced Practice Exercises
+// Returns immediately, spawns go routines for the scheduler which will shutdown when ctx is done
+func (s *Scheduler) Run(ctx context.Context) {
+ slog.Debug("starting llm scheduler")
+ go func() {
+ s.processPending(ctx)
+ }()
-1. Build a minimal end-to-end implementation for `Chapter 6: Performance, GPU Tuning, and Quantization`.
-2. Add instrumentation and measure baseline latency and error rate.
-3. Introduce one controlled failure and confirm graceful recovery.
-4. Add policy constraints and verify they are enforced consistently.
-5. Run a staged rollout and document rollback decision criteria.
+ go func() {
+ s.processCompleted(ctx)
+ }()
+}
-### Review Questions
+func (s *Scheduler) processPending(ctx context.Context) {
+ maxRunners := envconfig.MaxRunners()
-1. Which execution boundary matters most for this chapter and why?
-2. What signal detects regressions earliest in your environment?
-3. What tradeoff did you make between delivery speed and governance?
-4. How would you recover from the highest-impact failure mode?
-5. What must be automated before scaling to team-wide adoption?
+ for {
+ select {
+ case <-ctx.Done():
+ slog.Debug("shutting down scheduler pending loop")
+```
-## What Problem Does This Solve?
+This function is important because it defines how Ollama Tutorial: Running and Serving LLMs Locally implements the patterns covered in this chapter.
-Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for `ollama`, `num_ctx`, `llama3` so behavior stays predictable as complexity grows.
+### `server/sched.go`
-In practical terms, this chapter helps you avoid three common failures:
+The `load` function in [`server/sched.go`](https://github.com/ollama/ollama/blob/HEAD/server/sched.go) handles a key part of this chapter's functionality:
-- coupling core logic too tightly to one implementation path
-- missing the handoff boundaries between setup, execution, and validation
-- shipping changes without clear rollback or observability strategy
-
-After working through this chapter, you should be able to reason about `Chapter 6: Performance, GPU Tuning, and Quantization` as an operating subsystem inside **Ollama Tutorial: Running and Serving LLMs Locally**, with explicit contracts for inputs, state transitions, and outputs.
+```go
+ finishedReqCh chan *LlmRequest
+ expiredCh chan *runnerRef
+ unloadedCh chan any
-Use the implementation notes around `eval`, `echo`, `num_batch` as your checklist when adapting these patterns to your own repository.
+ // loadedMu protects loaded and activeLoading
+ loadedMu sync.Mutex
-## How it Works Under the Hood
+ // activeLoading is the model that we are currently working on loading,
+ // including by evicting one or more other models. We can only load
+ // one model at a time but new requests to models that already loaded can
+ // happen in parallel
+ activeLoading llm.LlamaServer
+ loaded map[string]*runnerRef
-Under the hood, `Chapter 6: Performance, GPU Tuning, and Quantization` usually follows a repeatable control path:
-
-1. **Context bootstrap**: initialize runtime config and prerequisites for `ollama`.
-2. **Input normalization**: shape incoming data so `num_ctx` receives stable contracts.
-3. **Core execution**: run the main logic branch and propagate intermediate state through `llama3`.
-4. **Policy and safety checks**: enforce limits, auth scopes, and failure boundaries.
-5. **Output composition**: return canonical result payloads for downstream consumers.
-6. **Operational telemetry**: emit logs/metrics needed for debugging and performance tuning.
+ loadFn func(req *LlmRequest, systemInfo ml.SystemInfo, gpus []ml.DeviceInfo, requireFull bool) bool
+ newServerFn func(systemInfo ml.SystemInfo, gpus []ml.DeviceInfo, model string, f *ggml.GGML, adapters []string, projectors []string, opts api.Options, numParallel int) (llm.LlamaServer, error)
+ getGpuFn func(ctx context.Context, runners []ml.FilteredRunnerDiscovery) []ml.DeviceInfo
+ getSystemInfoFn func() ml.SystemInfo
+ waitForRecovery time.Duration
+}
-When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+// Default automatic value for number of models we allow per GPU
+// Model will still need to fit in VRAM, but loading many small models
+// on a large GPU can cause stalling
+var defaultModelsPerGPU = 3
-## Source Walkthrough
+var ErrMaxQueue = errors.New("server busy, please try again. maximum pending requests exceeded")
-Use the following upstream sources to verify implementation details while reading this chapter:
+func InitScheduler(ctx context.Context) *Scheduler {
+ maxQueue := envconfig.MaxQueue()
+ sched := &Scheduler{
+ pendingReqCh: make(chan *LlmRequest, maxQueue),
+```
-- [Ollama Repository](https://github.com/ollama/ollama)
- Why it matters: authoritative reference on `Ollama Repository` (github.com).
-- [Ollama Releases](https://github.com/ollama/ollama/releases)
- Why it matters: authoritative reference on `Ollama Releases` (github.com).
-- [Ollama Website and Docs](https://ollama.com/)
- Why it matters: authoritative reference on `Ollama Website and Docs` (ollama.com).
+This function is important because it defines how Ollama Tutorial: Running and Serving LLMs Locally implements the patterns covered in this chapter.
-Suggested trace strategy:
-- search upstream code for `ollama` and `num_ctx` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
-## Chapter Connections
+## How These Components Connect
-- [Tutorial Index](README.md)
-- [Previous Chapter: Chapter 5: Modelfiles, Templates, and Custom Models](05-modelfiles-custom.md)
-- [Next Chapter: Chapter 7: Integrations with OpenAI API, LangChain, and LlamaIndex](07-integrations.md)
-- [Main Catalog](../../README.md#-tutorial-catalog)
-- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
+```mermaid
+flowchart TD
+ A[processPending]
+ B[processCompleted]
+ C[useLoadedRunner]
+ D[load]
+ E[updateFreeSpace]
+ A --> B
+ B --> C
+ C --> D
+ D --> E
+```
diff --git a/tutorials/onlook-tutorial/01-getting-started.md b/tutorials/onlook-tutorial/01-getting-started.md
index 0b2de33a..5cbf813a 100644
--- a/tutorials/onlook-tutorial/01-getting-started.md
+++ b/tutorials/onlook-tutorial/01-getting-started.md
@@ -46,37 +46,8 @@ You now have a working Onlook baseline for visual and prompt-driven iteration.
Next: [Chapter 2: Product and Architecture Foundations](02-product-and-architecture-foundations.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `docker-compose.yml`
-
-The `docker-compose` module in [`docker-compose.yml`](https://github.com/onlook-dev/onlook/blob/HEAD/docker-compose.yml) handles a key part of this chapter's functionality:
-
-```yml
-name: onlook
-
-services:
- web-client:
- build:
- context: .
- dockerfile: Dockerfile
- env_file:
- - apps/web/client/.env
- ports:
- - "3000:3000"
- restart: unless-stopped
- network_mode: host
-
-networks:
- supabase_network_onlook-web:
- external: true
-
-```
-
-This module is important because it defines how Onlook Tutorial: Visual-First AI Coding for Next.js and Tailwind implements the patterns covered in this chapter.
-
### `docs/next.config.ts`
The `next.config` module in [`docs/next.config.ts`](https://github.com/onlook-dev/onlook/blob/HEAD/docs/next.config.ts) handles a key part of this chapter's functionality:
@@ -106,21 +77,46 @@ export default withMDX(nextConfig);
This module is important because it defines how Onlook Tutorial: Visual-First AI Coding for Next.js and Tailwind implements the patterns covered in this chapter.
-### `eslint.config.js`
-
-The `eslint.config` module in [`eslint.config.js`](https://github.com/onlook-dev/onlook/blob/HEAD/eslint.config.js) handles a key part of this chapter's functionality:
-
-```js
-import baseConfig from "@onlook/eslint/base";
-
-/** @type {import('typescript-eslint').Config} */
-export default [
- ...baseConfig,
- {
- files: ["tooling/**/*.js"],
+### `docs/tsconfig.json`
+
+The `tsconfig` module in [`docs/tsconfig.json`](https://github.com/onlook-dev/onlook/blob/HEAD/docs/tsconfig.json) handles a key part of this chapter's functionality:
+
+```json
+{
+ "compilerOptions": {
+ "baseUrl": ".",
+ "target": "ESNext",
+ "lib": [
+ "dom",
+ "dom.iterable",
+ "esnext"
+ ],
+ "allowJs": true,
+ "skipLibCheck": true,
+ "strict": true,
+ "forceConsistentCasingInFileNames": true,
+ "noEmit": true,
+ "esModuleInterop": true,
+ "module": "esnext",
+ "moduleResolution": "bundler",
+ "resolveJsonModule": true,
+ "isolatedModules": true,
+ "jsx": "react-jsx",
+ "incremental": true,
+ "paths": {
+ "@/.source": [
+ "./.source/index.ts"
+ ],
+ "@/*": [
+ "./src/*"
+ ]
+ },
+ "plugins": [
+ {
+ "name": "next"
+ }
+ ]
},
-];
-
```
This module is important because it defines how Onlook Tutorial: Visual-First AI Coding for Next.js and Tailwind implements the patterns covered in this chapter.
@@ -130,9 +126,7 @@ This module is important because it defines how Onlook Tutorial: Visual-First AI
```mermaid
flowchart TD
- A[docker-compose]
- B[next.config]
- C[eslint.config]
+ A[next.config]
+ B[tsconfig]
A --> B
- B --> C
```
diff --git a/tutorials/onlook-tutorial/02-product-and-architecture-foundations.md b/tutorials/onlook-tutorial/02-product-and-architecture-foundations.md
index 90dd28e7..19158921 100644
--- a/tutorials/onlook-tutorial/02-product-and-architecture-foundations.md
+++ b/tutorials/onlook-tutorial/02-product-and-architecture-foundations.md
@@ -47,37 +47,8 @@ You now have a systems-level model for how Onlook transforms edits into code.
Next: [Chapter 3: Visual Editing and Code Mapping](03-visual-editing-and-code-mapping.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `docker-compose.yml`
-
-The `docker-compose` module in [`docker-compose.yml`](https://github.com/onlook-dev/onlook/blob/HEAD/docker-compose.yml) handles a key part of this chapter's functionality:
-
-```yml
-name: onlook
-
-services:
- web-client:
- build:
- context: .
- dockerfile: Dockerfile
- env_file:
- - apps/web/client/.env
- ports:
- - "3000:3000"
- restart: unless-stopped
- network_mode: host
-
-networks:
- supabase_network_onlook-web:
- external: true
-
-```
-
-This module is important because it defines how Onlook Tutorial: Visual-First AI Coding for Next.js and Tailwind implements the patterns covered in this chapter.
-
### `docs/next.config.ts`
The `next.config` module in [`docs/next.config.ts`](https://github.com/onlook-dev/onlook/blob/HEAD/docs/next.config.ts) handles a key part of this chapter's functionality:
@@ -107,21 +78,46 @@ export default withMDX(nextConfig);
This module is important because it defines how Onlook Tutorial: Visual-First AI Coding for Next.js and Tailwind implements the patterns covered in this chapter.
-### `eslint.config.js`
-
-The `eslint.config` module in [`eslint.config.js`](https://github.com/onlook-dev/onlook/blob/HEAD/eslint.config.js) handles a key part of this chapter's functionality:
-
-```js
-import baseConfig from "@onlook/eslint/base";
-
-/** @type {import('typescript-eslint').Config} */
-export default [
- ...baseConfig,
- {
- files: ["tooling/**/*.js"],
+### `docs/tsconfig.json`
+
+The `tsconfig` module in [`docs/tsconfig.json`](https://github.com/onlook-dev/onlook/blob/HEAD/docs/tsconfig.json) handles a key part of this chapter's functionality:
+
+```json
+{
+ "compilerOptions": {
+ "baseUrl": ".",
+ "target": "ESNext",
+ "lib": [
+ "dom",
+ "dom.iterable",
+ "esnext"
+ ],
+ "allowJs": true,
+ "skipLibCheck": true,
+ "strict": true,
+ "forceConsistentCasingInFileNames": true,
+ "noEmit": true,
+ "esModuleInterop": true,
+ "module": "esnext",
+ "moduleResolution": "bundler",
+ "resolveJsonModule": true,
+ "isolatedModules": true,
+ "jsx": "react-jsx",
+ "incremental": true,
+ "paths": {
+ "@/.source": [
+ "./.source/index.ts"
+ ],
+ "@/*": [
+ "./src/*"
+ ]
+ },
+ "plugins": [
+ {
+ "name": "next"
+ }
+ ]
},
-];
-
```
This module is important because it defines how Onlook Tutorial: Visual-First AI Coding for Next.js and Tailwind implements the patterns covered in this chapter.
@@ -131,9 +127,7 @@ This module is important because it defines how Onlook Tutorial: Visual-First AI
```mermaid
flowchart TD
- A[docker-compose]
- B[next.config]
- C[eslint.config]
+ A[next.config]
+ B[tsconfig]
A --> B
- B --> C
```
diff --git a/tutorials/onlook-tutorial/03-visual-editing-and-code-mapping.md b/tutorials/onlook-tutorial/03-visual-editing-and-code-mapping.md
index 56ecc32f..d778f218 100644
--- a/tutorials/onlook-tutorial/03-visual-editing-and-code-mapping.md
+++ b/tutorials/onlook-tutorial/03-visual-editing-and-code-mapping.md
@@ -48,37 +48,8 @@ You now understand how to run visual editing loops while keeping code quality in
Next: [Chapter 4: AI Chat, Branching, and Iteration](04-ai-chat-branching-and-iteration.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `docker-compose.yml`
-
-The `docker-compose` module in [`docker-compose.yml`](https://github.com/onlook-dev/onlook/blob/HEAD/docker-compose.yml) handles a key part of this chapter's functionality:
-
-```yml
-name: onlook
-
-services:
- web-client:
- build:
- context: .
- dockerfile: Dockerfile
- env_file:
- - apps/web/client/.env
- ports:
- - "3000:3000"
- restart: unless-stopped
- network_mode: host
-
-networks:
- supabase_network_onlook-web:
- external: true
-
-```
-
-This module is important because it defines how Onlook Tutorial: Visual-First AI Coding for Next.js and Tailwind implements the patterns covered in this chapter.
-
### `docs/next.config.ts`
The `next.config` module in [`docs/next.config.ts`](https://github.com/onlook-dev/onlook/blob/HEAD/docs/next.config.ts) handles a key part of this chapter's functionality:
@@ -108,21 +79,46 @@ export default withMDX(nextConfig);
This module is important because it defines how Onlook Tutorial: Visual-First AI Coding for Next.js and Tailwind implements the patterns covered in this chapter.
-### `eslint.config.js`
-
-The `eslint.config` module in [`eslint.config.js`](https://github.com/onlook-dev/onlook/blob/HEAD/eslint.config.js) handles a key part of this chapter's functionality:
-
-```js
-import baseConfig from "@onlook/eslint/base";
-
-/** @type {import('typescript-eslint').Config} */
-export default [
- ...baseConfig,
- {
- files: ["tooling/**/*.js"],
+### `docs/tsconfig.json`
+
+The `tsconfig` module in [`docs/tsconfig.json`](https://github.com/onlook-dev/onlook/blob/HEAD/docs/tsconfig.json) handles a key part of this chapter's functionality:
+
+```json
+{
+ "compilerOptions": {
+ "baseUrl": ".",
+ "target": "ESNext",
+ "lib": [
+ "dom",
+ "dom.iterable",
+ "esnext"
+ ],
+ "allowJs": true,
+ "skipLibCheck": true,
+ "strict": true,
+ "forceConsistentCasingInFileNames": true,
+ "noEmit": true,
+ "esModuleInterop": true,
+ "module": "esnext",
+ "moduleResolution": "bundler",
+ "resolveJsonModule": true,
+ "isolatedModules": true,
+ "jsx": "react-jsx",
+ "incremental": true,
+ "paths": {
+ "@/.source": [
+ "./.source/index.ts"
+ ],
+ "@/*": [
+ "./src/*"
+ ]
+ },
+ "plugins": [
+ {
+ "name": "next"
+ }
+ ]
},
-];
-
```
This module is important because it defines how Onlook Tutorial: Visual-First AI Coding for Next.js and Tailwind implements the patterns covered in this chapter.
@@ -132,9 +128,7 @@ This module is important because it defines how Onlook Tutorial: Visual-First AI
```mermaid
flowchart TD
- A[docker-compose]
- B[next.config]
- C[eslint.config]
+ A[next.config]
+ B[tsconfig]
A --> B
- B --> C
```
diff --git a/tutorials/onlook-tutorial/04-ai-chat-branching-and-iteration.md b/tutorials/onlook-tutorial/04-ai-chat-branching-and-iteration.md
index f4c4705c..579081bd 100644
--- a/tutorials/onlook-tutorial/04-ai-chat-branching-and-iteration.md
+++ b/tutorials/onlook-tutorial/04-ai-chat-branching-and-iteration.md
@@ -46,37 +46,8 @@ You now have a practical pattern for controlled, high-speed AI-assisted UI itera
Next: [Chapter 5: Local Development and Runtime Setup](05-local-development-and-runtime-setup.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `docker-compose.yml`
-
-The `docker-compose` module in [`docker-compose.yml`](https://github.com/onlook-dev/onlook/blob/HEAD/docker-compose.yml) handles a key part of this chapter's functionality:
-
-```yml
-name: onlook
-
-services:
- web-client:
- build:
- context: .
- dockerfile: Dockerfile
- env_file:
- - apps/web/client/.env
- ports:
- - "3000:3000"
- restart: unless-stopped
- network_mode: host
-
-networks:
- supabase_network_onlook-web:
- external: true
-
-```
-
-This module is important because it defines how Onlook Tutorial: Visual-First AI Coding for Next.js and Tailwind implements the patterns covered in this chapter.
-
### `docs/next.config.ts`
The `next.config` module in [`docs/next.config.ts`](https://github.com/onlook-dev/onlook/blob/HEAD/docs/next.config.ts) handles a key part of this chapter's functionality:
@@ -106,21 +77,46 @@ export default withMDX(nextConfig);
This module is important because it defines how Onlook Tutorial: Visual-First AI Coding for Next.js and Tailwind implements the patterns covered in this chapter.
-### `eslint.config.js`
-
-The `eslint.config` module in [`eslint.config.js`](https://github.com/onlook-dev/onlook/blob/HEAD/eslint.config.js) handles a key part of this chapter's functionality:
-
-```js
-import baseConfig from "@onlook/eslint/base";
-
-/** @type {import('typescript-eslint').Config} */
-export default [
- ...baseConfig,
- {
- files: ["tooling/**/*.js"],
+### `docs/tsconfig.json`
+
+The `tsconfig` module in [`docs/tsconfig.json`](https://github.com/onlook-dev/onlook/blob/HEAD/docs/tsconfig.json) handles a key part of this chapter's functionality:
+
+```json
+{
+ "compilerOptions": {
+ "baseUrl": ".",
+ "target": "ESNext",
+ "lib": [
+ "dom",
+ "dom.iterable",
+ "esnext"
+ ],
+ "allowJs": true,
+ "skipLibCheck": true,
+ "strict": true,
+ "forceConsistentCasingInFileNames": true,
+ "noEmit": true,
+ "esModuleInterop": true,
+ "module": "esnext",
+ "moduleResolution": "bundler",
+ "resolveJsonModule": true,
+ "isolatedModules": true,
+ "jsx": "react-jsx",
+ "incremental": true,
+ "paths": {
+ "@/.source": [
+ "./.source/index.ts"
+ ],
+ "@/*": [
+ "./src/*"
+ ]
+ },
+ "plugins": [
+ {
+ "name": "next"
+ }
+ ]
},
-];
-
```
This module is important because it defines how Onlook Tutorial: Visual-First AI Coding for Next.js and Tailwind implements the patterns covered in this chapter.
@@ -130,9 +126,7 @@ This module is important because it defines how Onlook Tutorial: Visual-First AI
```mermaid
flowchart TD
- A[docker-compose]
- B[next.config]
- C[eslint.config]
+ A[next.config]
+ B[tsconfig]
A --> B
- B --> C
```
diff --git a/tutorials/onlook-tutorial/05-local-development-and-runtime-setup.md b/tutorials/onlook-tutorial/05-local-development-and-runtime-setup.md
index 502fa9fc..4918f8ee 100644
--- a/tutorials/onlook-tutorial/05-local-development-and-runtime-setup.md
+++ b/tutorials/onlook-tutorial/05-local-development-and-runtime-setup.md
@@ -58,37 +58,8 @@ You now have a repeatable foundation for local Onlook development.
Next: [Chapter 6: Deployment and Team Collaboration](06-deployment-and-team-collaboration.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `docker-compose.yml`
-
-The `docker-compose` module in [`docker-compose.yml`](https://github.com/onlook-dev/onlook/blob/HEAD/docker-compose.yml) handles a key part of this chapter's functionality:
-
-```yml
-name: onlook
-
-services:
- web-client:
- build:
- context: .
- dockerfile: Dockerfile
- env_file:
- - apps/web/client/.env
- ports:
- - "3000:3000"
- restart: unless-stopped
- network_mode: host
-
-networks:
- supabase_network_onlook-web:
- external: true
-
-```
-
-This module is important because it defines how Onlook Tutorial: Visual-First AI Coding for Next.js and Tailwind implements the patterns covered in this chapter.
-
### `docs/next.config.ts`
The `next.config` module in [`docs/next.config.ts`](https://github.com/onlook-dev/onlook/blob/HEAD/docs/next.config.ts) handles a key part of this chapter's functionality:
@@ -118,21 +89,46 @@ export default withMDX(nextConfig);
This module is important because it defines how Onlook Tutorial: Visual-First AI Coding for Next.js and Tailwind implements the patterns covered in this chapter.
-### `eslint.config.js`
-
-The `eslint.config` module in [`eslint.config.js`](https://github.com/onlook-dev/onlook/blob/HEAD/eslint.config.js) handles a key part of this chapter's functionality:
-
-```js
-import baseConfig from "@onlook/eslint/base";
-
-/** @type {import('typescript-eslint').Config} */
-export default [
- ...baseConfig,
- {
- files: ["tooling/**/*.js"],
+### `docs/tsconfig.json`
+
+The `tsconfig` module in [`docs/tsconfig.json`](https://github.com/onlook-dev/onlook/blob/HEAD/docs/tsconfig.json) handles a key part of this chapter's functionality:
+
+```json
+{
+ "compilerOptions": {
+ "baseUrl": ".",
+ "target": "ESNext",
+ "lib": [
+ "dom",
+ "dom.iterable",
+ "esnext"
+ ],
+ "allowJs": true,
+ "skipLibCheck": true,
+ "strict": true,
+ "forceConsistentCasingInFileNames": true,
+ "noEmit": true,
+ "esModuleInterop": true,
+ "module": "esnext",
+ "moduleResolution": "bundler",
+ "resolveJsonModule": true,
+ "isolatedModules": true,
+ "jsx": "react-jsx",
+ "incremental": true,
+ "paths": {
+ "@/.source": [
+ "./.source/index.ts"
+ ],
+ "@/*": [
+ "./src/*"
+ ]
+ },
+ "plugins": [
+ {
+ "name": "next"
+ }
+ ]
},
-];
-
```
This module is important because it defines how Onlook Tutorial: Visual-First AI Coding for Next.js and Tailwind implements the patterns covered in this chapter.
@@ -142,9 +138,7 @@ This module is important because it defines how Onlook Tutorial: Visual-First AI
```mermaid
flowchart TD
- A[docker-compose]
- B[next.config]
- C[eslint.config]
+ A[next.config]
+ B[tsconfig]
A --> B
- B --> C
```
diff --git a/tutorials/onlook-tutorial/06-deployment-and-team-collaboration.md b/tutorials/onlook-tutorial/06-deployment-and-team-collaboration.md
index b2791ec6..1351f9fe 100644
--- a/tutorials/onlook-tutorial/06-deployment-and-team-collaboration.md
+++ b/tutorials/onlook-tutorial/06-deployment-and-team-collaboration.md
@@ -46,37 +46,8 @@ You now have a workflow for turning Onlook edits into team-reviewed deployable c
Next: [Chapter 7: Contributing and Quality Workflow](07-contributing-and-quality-workflow.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `docker-compose.yml`
-
-The `docker-compose` module in [`docker-compose.yml`](https://github.com/onlook-dev/onlook/blob/HEAD/docker-compose.yml) handles a key part of this chapter's functionality:
-
-```yml
-name: onlook
-
-services:
- web-client:
- build:
- context: .
- dockerfile: Dockerfile
- env_file:
- - apps/web/client/.env
- ports:
- - "3000:3000"
- restart: unless-stopped
- network_mode: host
-
-networks:
- supabase_network_onlook-web:
- external: true
-
-```
-
-This module is important because it defines how Onlook Tutorial: Visual-First AI Coding for Next.js and Tailwind implements the patterns covered in this chapter.
-
### `docs/next.config.ts`
The `next.config` module in [`docs/next.config.ts`](https://github.com/onlook-dev/onlook/blob/HEAD/docs/next.config.ts) handles a key part of this chapter's functionality:
@@ -106,21 +77,46 @@ export default withMDX(nextConfig);
This module is important because it defines how Onlook Tutorial: Visual-First AI Coding for Next.js and Tailwind implements the patterns covered in this chapter.
-### `eslint.config.js`
-
-The `eslint.config` module in [`eslint.config.js`](https://github.com/onlook-dev/onlook/blob/HEAD/eslint.config.js) handles a key part of this chapter's functionality:
-
-```js
-import baseConfig from "@onlook/eslint/base";
-
-/** @type {import('typescript-eslint').Config} */
-export default [
- ...baseConfig,
- {
- files: ["tooling/**/*.js"],
+### `docs/tsconfig.json`
+
+The `tsconfig` module in [`docs/tsconfig.json`](https://github.com/onlook-dev/onlook/blob/HEAD/docs/tsconfig.json) handles a key part of this chapter's functionality:
+
+```json
+{
+ "compilerOptions": {
+ "baseUrl": ".",
+ "target": "ESNext",
+ "lib": [
+ "dom",
+ "dom.iterable",
+ "esnext"
+ ],
+ "allowJs": true,
+ "skipLibCheck": true,
+ "strict": true,
+ "forceConsistentCasingInFileNames": true,
+ "noEmit": true,
+ "esModuleInterop": true,
+ "module": "esnext",
+ "moduleResolution": "bundler",
+ "resolveJsonModule": true,
+ "isolatedModules": true,
+ "jsx": "react-jsx",
+ "incremental": true,
+ "paths": {
+ "@/.source": [
+ "./.source/index.ts"
+ ],
+ "@/*": [
+ "./src/*"
+ ]
+ },
+ "plugins": [
+ {
+ "name": "next"
+ }
+ ]
},
-];
-
```
This module is important because it defines how Onlook Tutorial: Visual-First AI Coding for Next.js and Tailwind implements the patterns covered in this chapter.
@@ -130,9 +126,7 @@ This module is important because it defines how Onlook Tutorial: Visual-First AI
```mermaid
flowchart TD
- A[docker-compose]
- B[next.config]
- C[eslint.config]
+ A[next.config]
+ B[tsconfig]
A --> B
- B --> C
```
diff --git a/tutorials/onlook-tutorial/07-contributing-and-quality-workflow.md b/tutorials/onlook-tutorial/07-contributing-and-quality-workflow.md
index b8ce6ee0..c0f627ca 100644
--- a/tutorials/onlook-tutorial/07-contributing-and-quality-workflow.md
+++ b/tutorials/onlook-tutorial/07-contributing-and-quality-workflow.md
@@ -43,37 +43,8 @@ You now have the operational contribution baseline for working on Onlook core.
Next: [Chapter 8: Production Operations and Governance](08-production-operations-and-governance.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `docker-compose.yml`
-
-The `docker-compose` module in [`docker-compose.yml`](https://github.com/onlook-dev/onlook/blob/HEAD/docker-compose.yml) handles a key part of this chapter's functionality:
-
-```yml
-name: onlook
-
-services:
- web-client:
- build:
- context: .
- dockerfile: Dockerfile
- env_file:
- - apps/web/client/.env
- ports:
- - "3000:3000"
- restart: unless-stopped
- network_mode: host
-
-networks:
- supabase_network_onlook-web:
- external: true
-
-```
-
-This module is important because it defines how Onlook Tutorial: Visual-First AI Coding for Next.js and Tailwind implements the patterns covered in this chapter.
-
### `docs/next.config.ts`
The `next.config` module in [`docs/next.config.ts`](https://github.com/onlook-dev/onlook/blob/HEAD/docs/next.config.ts) handles a key part of this chapter's functionality:
@@ -103,21 +74,46 @@ export default withMDX(nextConfig);
This module is important because it defines how Onlook Tutorial: Visual-First AI Coding for Next.js and Tailwind implements the patterns covered in this chapter.
-### `eslint.config.js`
-
-The `eslint.config` module in [`eslint.config.js`](https://github.com/onlook-dev/onlook/blob/HEAD/eslint.config.js) handles a key part of this chapter's functionality:
-
-```js
-import baseConfig from "@onlook/eslint/base";
-
-/** @type {import('typescript-eslint').Config} */
-export default [
- ...baseConfig,
- {
- files: ["tooling/**/*.js"],
+### `docs/tsconfig.json`
+
+The `tsconfig` module in [`docs/tsconfig.json`](https://github.com/onlook-dev/onlook/blob/HEAD/docs/tsconfig.json) handles a key part of this chapter's functionality:
+
+```json
+{
+ "compilerOptions": {
+ "baseUrl": ".",
+ "target": "ESNext",
+ "lib": [
+ "dom",
+ "dom.iterable",
+ "esnext"
+ ],
+ "allowJs": true,
+ "skipLibCheck": true,
+ "strict": true,
+ "forceConsistentCasingInFileNames": true,
+ "noEmit": true,
+ "esModuleInterop": true,
+ "module": "esnext",
+ "moduleResolution": "bundler",
+ "resolveJsonModule": true,
+ "isolatedModules": true,
+ "jsx": "react-jsx",
+ "incremental": true,
+ "paths": {
+ "@/.source": [
+ "./.source/index.ts"
+ ],
+ "@/*": [
+ "./src/*"
+ ]
+ },
+ "plugins": [
+ {
+ "name": "next"
+ }
+ ]
},
-];
-
```
This module is important because it defines how Onlook Tutorial: Visual-First AI Coding for Next.js and Tailwind implements the patterns covered in this chapter.
@@ -127,9 +123,7 @@ This module is important because it defines how Onlook Tutorial: Visual-First AI
```mermaid
flowchart TD
- A[docker-compose]
- B[next.config]
- C[eslint.config]
+ A[next.config]
+ B[tsconfig]
A --> B
- B --> C
```
diff --git a/tutorials/onlook-tutorial/08-production-operations-and-governance.md b/tutorials/onlook-tutorial/08-production-operations-and-governance.md
index 031d9243..a6babb30 100644
--- a/tutorials/onlook-tutorial/08-production-operations-and-governance.md
+++ b/tutorials/onlook-tutorial/08-production-operations-and-governance.md
@@ -49,37 +49,8 @@ You now have a complete model for operationalizing Onlook in real product-engine
Compare semantic agent augmentation in the [Serena Tutorial](../serena-tutorial/).
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `docker-compose.yml`
-
-The `docker-compose` module in [`docker-compose.yml`](https://github.com/onlook-dev/onlook/blob/HEAD/docker-compose.yml) handles a key part of this chapter's functionality:
-
-```yml
-name: onlook
-
-services:
- web-client:
- build:
- context: .
- dockerfile: Dockerfile
- env_file:
- - apps/web/client/.env
- ports:
- - "3000:3000"
- restart: unless-stopped
- network_mode: host
-
-networks:
- supabase_network_onlook-web:
- external: true
-
-```
-
-This module is important because it defines how Onlook Tutorial: Visual-First AI Coding for Next.js and Tailwind implements the patterns covered in this chapter.
-
### `docs/next.config.ts`
The `next.config` module in [`docs/next.config.ts`](https://github.com/onlook-dev/onlook/blob/HEAD/docs/next.config.ts) handles a key part of this chapter's functionality:
@@ -109,21 +80,46 @@ export default withMDX(nextConfig);
This module is important because it defines how Onlook Tutorial: Visual-First AI Coding for Next.js and Tailwind implements the patterns covered in this chapter.
-### `eslint.config.js`
-
-The `eslint.config` module in [`eslint.config.js`](https://github.com/onlook-dev/onlook/blob/HEAD/eslint.config.js) handles a key part of this chapter's functionality:
-
-```js
-import baseConfig from "@onlook/eslint/base";
-
-/** @type {import('typescript-eslint').Config} */
-export default [
- ...baseConfig,
- {
- files: ["tooling/**/*.js"],
+### `docs/tsconfig.json`
+
+The `tsconfig` module in [`docs/tsconfig.json`](https://github.com/onlook-dev/onlook/blob/HEAD/docs/tsconfig.json) handles a key part of this chapter's functionality:
+
+```json
+{
+ "compilerOptions": {
+ "baseUrl": ".",
+ "target": "ESNext",
+ "lib": [
+ "dom",
+ "dom.iterable",
+ "esnext"
+ ],
+ "allowJs": true,
+ "skipLibCheck": true,
+ "strict": true,
+ "forceConsistentCasingInFileNames": true,
+ "noEmit": true,
+ "esModuleInterop": true,
+ "module": "esnext",
+ "moduleResolution": "bundler",
+ "resolveJsonModule": true,
+ "isolatedModules": true,
+ "jsx": "react-jsx",
+ "incremental": true,
+ "paths": {
+ "@/.source": [
+ "./.source/index.ts"
+ ],
+ "@/*": [
+ "./src/*"
+ ]
+ },
+ "plugins": [
+ {
+ "name": "next"
+ }
+ ]
},
-];
-
```
This module is important because it defines how Onlook Tutorial: Visual-First AI Coding for Next.js and Tailwind implements the patterns covered in this chapter.
@@ -133,9 +129,7 @@ This module is important because it defines how Onlook Tutorial: Visual-First AI
```mermaid
flowchart TD
- A[docker-compose]
- B[next.config]
- C[eslint.config]
+ A[next.config]
+ B[tsconfig]
A --> B
- B --> C
```
diff --git a/tutorials/opcode-tutorial/01-getting-started.md b/tutorials/opcode-tutorial/01-getting-started.md
index 08092a37..92027143 100644
--- a/tutorials/opcode-tutorial/01-getting-started.md
+++ b/tutorials/opcode-tutorial/01-getting-started.md
@@ -50,8 +50,6 @@ You now have Opcode connected to a working Claude Code environment.
Next: [Chapter 2: Architecture and Platform Stack](02-architecture-and-platform-stack.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `src-tauri/tauri.conf.json`
@@ -177,43 +175,43 @@ function AppContent() {
This function is important because it defines how Opcode Tutorial: GUI Command Center for Claude Code Workflows implements the patterns covered in this chapter.
-### `src/components/Settings.tsx`
+### `src/components/FloatingPromptInput.tsx`
-The `SettingsProps` interface in [`src/components/Settings.tsx`](https://github.com/winfunc/opcode/blob/HEAD/src/components/Settings.tsx) handles a key part of this chapter's functionality:
+The `FloatingPromptInputProps` interface in [`src/components/FloatingPromptInput.tsx`](https://github.com/winfunc/opcode/blob/HEAD/src/components/FloatingPromptInput.tsx) handles a key part of this chapter's functionality:
```tsx
-import { TabPersistenceService } from "@/services/tabPersistence";
+const getCurrentWebviewWindow = tauriGetCurrentWebviewWindow || (() => ({ listen: () => Promise.resolve(() => {}) }));
-interface SettingsProps {
+interface FloatingPromptInputProps {
+ /**
+ * Callback when prompt is sent
+ */
+ onSend: (prompt: string, model: "sonnet" | "opus") => void;
+ /**
+ * Whether the input is loading
+ */
+ isLoading?: boolean;
+ /**
+ * Whether the input is disabled
+ */
+ disabled?: boolean;
+ /**
+ * Default model to select
+ */
+ defaultModel?: "sonnet" | "opus";
/**
- * Callback to go back to the main view
+ * Project path for file picker
*/
- onBack: () => void;
+ projectPath?: string;
/**
* Optional className for styling
*/
className?: string;
-}
-
-interface PermissionRule {
- id: string;
- value: string;
-}
-
-interface EnvironmentVariable {
- id: string;
- key: string;
- value: string;
-}
-
-/**
- * Comprehensive Settings UI for managing Claude Code settings
- * Provides a no-code interface for editing the settings.json file
- */
-export const Settings: React.FC<SettingsProps> = ({
- className,
-}) => {
- const [settings, setSettings] = useState<ClaudeSettings | null>(null);
+ /**
+ * Callback when cancel is clicked (only during loading)
+ */
+ onCancel?: () => void;
+ /**
```
This interface is important because it defines how Opcode Tutorial: GUI Command Center for Claude Code Workflows implements the patterns covered in this chapter.
@@ -226,8 +224,8 @@ flowchart TD
A[for]
B[AppContent]
C[App]
- D[SettingsProps]
- E[PermissionRule]
+ D[FloatingPromptInputProps]
+ E[FloatingPromptInputRef]
A --> B
B --> C
C --> D
diff --git a/tutorials/opcode-tutorial/02-architecture-and-platform-stack.md b/tutorials/opcode-tutorial/02-architecture-and-platform-stack.md
index e5ebfc23..065b47db 100644
--- a/tutorials/opcode-tutorial/02-architecture-and-platform-stack.md
+++ b/tutorials/opcode-tutorial/02-architecture-and-platform-stack.md
@@ -47,15 +47,59 @@ You now understand the core architecture choices that shape Opcode behavior.
Next: [Chapter 3: Projects and Session Management](03-projects-and-session-management.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `src/components/Settings.tsx`
-The `EnvironmentVariable` interface in [`src/components/Settings.tsx`](https://github.com/winfunc/opcode/blob/HEAD/src/components/Settings.tsx) handles a key part of this chapter's functionality:
+The `SettingsProps` interface in [`src/components/Settings.tsx`](https://github.com/winfunc/opcode/blob/HEAD/src/components/Settings.tsx) handles a key part of this chapter's functionality:
```tsx
+import { TabPersistenceService } from "@/services/tabPersistence";
+
+interface SettingsProps {
+ /**
+ * Callback to go back to the main view
+ */
+ onBack: () => void;
+ /**
+ * Optional className for styling
+ */
+ className?: string;
+}
+
+interface PermissionRule {
+ id: string;
+ value: string;
+}
+
+interface EnvironmentVariable {
+ id: string;
+ key: string;
+ value: string;
+}
+
+/**
+ * Comprehensive Settings UI for managing Claude Code settings
+ * Provides a no-code interface for editing the settings.json file
+ */
+export const Settings: React.FC<SettingsProps> = ({
+ className,
+}) => {
+ const [settings, setSettings] = useState<ClaudeSettings | null>(null);
+```
+
+This interface is important because it defines how Opcode Tutorial: GUI Command Center for Claude Code Workflows implements the patterns covered in this chapter.
+
+### `src/components/Settings.tsx`
+
+The `PermissionRule` interface in [`src/components/Settings.tsx`](https://github.com/winfunc/opcode/blob/HEAD/src/components/Settings.tsx) handles a key part of this chapter's functionality:
+
+```tsx
+}
+
+interface PermissionRule {
+ id: string;
+ value: string;
}
interface EnvironmentVariable {
@@ -83,30 +127,15 @@ export const Settings: React.FC<SettingsProps> = ({
// Permission rules state
const [allowRules, setAllowRules] = useState<PermissionRule[]>([]);
- const [denyRules, setDenyRules] = useState<PermissionRule[]>([]);
-
- // Environment variables state
- const [envVars, setEnvVars] = useState<EnvironmentVariable[]>([]);
-
```
This interface is important because it defines how Opcode Tutorial: GUI Command Center for Claude Code Workflows implements the patterns covered in this chapter.
### `src/components/Settings.tsx`
-The `for` interface in [`src/components/Settings.tsx`](https://github.com/winfunc/opcode/blob/HEAD/src/components/Settings.tsx) handles a key part of this chapter's functionality:
+The `EnvironmentVariable` interface in [`src/components/Settings.tsx`](https://github.com/winfunc/opcode/blob/HEAD/src/components/Settings.tsx) handles a key part of this chapter's functionality:
```tsx
- onBack: () => void;
- /**
- * Optional className for styling
- */
- className?: string;
-}
-
-interface PermissionRule {
- id: string;
- value: string;
}
interface EnvironmentVariable {
@@ -129,33 +158,25 @@ export const Settings: React.FC<SettingsProps> = ({
const [activeTab, setActiveTab] = useState("general");
const [currentBinaryPath, setCurrentBinaryPath] = useState<string | null>(null);
const [selectedInstallation, setSelectedInstallation] = useState<ClaudeInstallation | null>(null);
+ const [binaryPathChanged, setBinaryPathChanged] = useState(false);
+ const [toast, setToast] = useState<{ message: string; type: 'success' | 'error' } | null>(null);
+
+ // Permission rules state
+ const [allowRules, setAllowRules] = useState<PermissionRule[]>([]);
+ const [denyRules, setDenyRules] = useState<PermissionRule[]>([]);
+
+ // Environment variables state
+ const [envVars, setEnvVars] = useState<EnvironmentVariable[]>([]);
+
```
This interface is important because it defines how Opcode Tutorial: GUI Command Center for Claude Code Workflows implements the patterns covered in this chapter.
-### `src/components/AgentExecution.tsx`
+### `src/components/Settings.tsx`
-The `AgentExecutionProps` interface in [`src/components/AgentExecution.tsx`](https://github.com/winfunc/opcode/blob/HEAD/src/components/AgentExecution.tsx) handles a key part of this chapter's functionality:
+The `for` interface in [`src/components/Settings.tsx`](https://github.com/winfunc/opcode/blob/HEAD/src/components/Settings.tsx) handles a key part of this chapter's functionality:
```tsx
-import { useTabState } from "@/hooks/useTabState";
-
-interface AgentExecutionProps {
- /**
- * The agent to execute
- */
- agent: Agent;
- /**
- * Optional initial project path
- */
- projectPath?: string;
- /**
- * Optional tab ID for updating tab status
- */
- tabId?: string;
- /**
- * Callback to go back to the agents list
- */
onBack: () => void;
/**
* Optional className for styling
@@ -163,54 +184,31 @@ interface AgentExecutionProps {
className?: string;
}
-export interface ClaudeStreamMessage {
- type: "system" | "assistant" | "user" | "result";
- subtype?: string;
- message?: {
- content?: any[];
- usage?: {
- input_tokens: number;
-```
-
-This interface is important because it defines how Opcode Tutorial: GUI Command Center for Claude Code Workflows implements the patterns covered in this chapter.
-
-### `src/components/AgentExecution.tsx`
-
-The `ClaudeStreamMessage` interface in [`src/components/AgentExecution.tsx`](https://github.com/winfunc/opcode/blob/HEAD/src/components/AgentExecution.tsx) handles a key part of this chapter's functionality:
-
-```tsx
+interface PermissionRule {
+ id: string;
+ value: string;
}
-export interface ClaudeStreamMessage {
- type: "system" | "assistant" | "user" | "result";
- subtype?: string;
- message?: {
- content?: any[];
- usage?: {
- input_tokens: number;
- output_tokens: number;
- };
- };
- usage?: {
- input_tokens: number;
- output_tokens: number;
- };
- [key: string]: any;
+interface EnvironmentVariable {
+ id: string;
+ key: string;
+ value: string;
}
/**
- * AgentExecution component for running CC agents
- *
- * @example
- * <AgentExecution agent={agent} onBack={() => setView('list')} />
+ * Comprehensive Settings UI for managing Claude Code settings
+ * Provides a no-code interface for editing the settings.json file
*/
-export const AgentExecution: React.FC<AgentExecutionProps> = ({
- agent,
- projectPath: initialProjectPath,
- tabId,
- onBack,
+export const Settings: React.FC<SettingsProps> = ({
className,
}) => {
+ const [settings, setSettings] = useState<ClaudeSettings | null>(null);
+ const [loading, setLoading] = useState(true);
+ const [saving, setSaving] = useState(false);
+ const [error, setError] = useState<string | null>(null);
+ const [activeTab, setActiveTab] = useState("general");
+ const [currentBinaryPath, setCurrentBinaryPath] = useState<string | null>(null);
+ const [selectedInstallation, setSelectedInstallation] = useState<ClaudeInstallation | null>(null);
```
This interface is important because it defines how Opcode Tutorial: GUI Command Center for Claude Code Workflows implements the patterns covered in this chapter.
@@ -220,11 +218,11 @@ This interface is important because it defines how Opcode Tutorial: GUI Command
```mermaid
flowchart TD
- A[EnvironmentVariable]
- B[for]
- C[AgentExecutionProps]
- D[ClaudeStreamMessage]
- E[StreamMessageProps]
+ A[SettingsProps]
+ B[PermissionRule]
+ C[EnvironmentVariable]
+ D[for]
+ E[AgentExecutionProps]
A --> B
B --> C
C --> D
diff --git a/tutorials/opcode-tutorial/03-projects-and-session-management.md b/tutorials/opcode-tutorial/03-projects-and-session-management.md
index 3d48f9ef..7c7b2cc9 100644
--- a/tutorials/opcode-tutorial/03-projects-and-session-management.md
+++ b/tutorials/opcode-tutorial/03-projects-and-session-management.md
@@ -43,151 +43,136 @@ You now have a repeatable approach to session control through Opcode's GUI.
Next: [Chapter 4: Custom Agents and Background Runs](04-custom-agents-and-background-runs.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/components/FloatingPromptInput.tsx`
+### `src/components/AgentExecution.tsx`
-The `FloatingPromptInputProps` interface in [`src/components/FloatingPromptInput.tsx`](https://github.com/winfunc/opcode/blob/HEAD/src/components/FloatingPromptInput.tsx) handles a key part of this chapter's functionality:
+The `ClaudeStreamMessage` interface in [`src/components/AgentExecution.tsx`](https://github.com/winfunc/opcode/blob/HEAD/src/components/AgentExecution.tsx) handles a key part of this chapter's functionality:
```tsx
-const getCurrentWebviewWindow = tauriGetCurrentWebviewWindow || (() => ({ listen: () => Promise.resolve(() => {}) }));
-
-interface FloatingPromptInputProps {
- /**
- * Callback when prompt is sent
- */
- onSend: (prompt: string, model: "sonnet" | "opus") => void;
- /**
- * Whether the input is loading
- */
- isLoading?: boolean;
- /**
- * Whether the input is disabled
- */
- disabled?: boolean;
- /**
- * Default model to select
- */
- defaultModel?: "sonnet" | "opus";
- /**
- * Project path for file picker
- */
- projectPath?: string;
- /**
- * Optional className for styling
- */
- className?: string;
- /**
- * Callback when cancel is clicked (only during loading)
- */
- onCancel?: () => void;
- /**
+}
+
+export interface ClaudeStreamMessage {
+ type: "system" | "assistant" | "user" | "result";
+ subtype?: string;
+ message?: {
+ content?: any[];
+ usage?: {
+ input_tokens: number;
+ output_tokens: number;
+ };
+ };
+ usage?: {
+ input_tokens: number;
+ output_tokens: number;
+ };
+ [key: string]: any;
+}
+
+/**
+ * AgentExecution component for running CC agents
+ *
+ * @example
+ * <AgentExecution agent={agent} onBack={() => setView('list')} />
+ */
+export const AgentExecution: React.FC<AgentExecutionProps> = ({
+ agent,
+ projectPath: initialProjectPath,
+ tabId,
+ onBack,
+ className,
+}) => {
```
This interface is important because it defines how Opcode Tutorial: GUI Command Center for Claude Code Workflows implements the patterns covered in this chapter.
-### `src/components/FloatingPromptInput.tsx`
+### `src/components/HooksEditor.tsx`
-The `FloatingPromptInputRef` interface in [`src/components/FloatingPromptInput.tsx`](https://github.com/winfunc/opcode/blob/HEAD/src/components/FloatingPromptInput.tsx) handles a key part of this chapter's functionality:
+The `HooksEditorProps` interface in [`src/components/HooksEditor.tsx`](https://github.com/winfunc/opcode/blob/HEAD/src/components/HooksEditor.tsx) handles a key part of this chapter's functionality:
```tsx
+} from '@/types/hooks';
+
+interface HooksEditorProps {
+ projectPath?: string;
+ scope: 'project' | 'local' | 'user';
+ readOnly?: boolean;
+ className?: string;
+ onChange?: (hasChanges: boolean, getHooks: () => HooksConfiguration) => void;
+ hideActions?: boolean;
}
-export interface FloatingPromptInputRef {
- addImage: (imagePath: string) => void;
+interface EditableHookCommand extends HookCommand {
+ id: string;
}
-/**
- * Thinking mode type definition
- */
-type ThinkingMode = "auto" | "think" | "think_hard" | "think_harder" | "ultrathink";
+interface EditableHookMatcher extends Omit<HookMatcher, 'hooks'> {
+ id: string;
+ hooks: EditableHookCommand[];
+ expanded?: boolean;
+}
-/**
- * Thinking mode configuration
- */
-type ThinkingModeConfig = {
- id: ThinkingMode;
- name: string;
- description: string;
- level: number; // 0-4 for visual indicator
- phrase?: string; // The phrase to append
- icon: React.ReactNode;
- color: string;
- shortName: string;
-};
-
-const THINKING_MODES: ThinkingModeConfig[] = [
- {
- id: "auto",
- name: "Auto",
- description: "Let Claude decide",
- level: 0,
- icon: <Sparkles className="h-3.5 w-3.5" />,
+const EVENT_INFO: Record<HookEvent, { label: string; description: string; icon: React.ReactNode }> = {
+ PreToolUse: {
+ label: 'Pre Tool Use',
+ description: 'Runs before tool calls, can block and provide feedback',
+ icon: <Shield className="h-4 w-4" />
+ },
+ PostToolUse: {
+ label: 'Post Tool Use',
+ description: 'Runs after successful tool completion',
+ icon: <PlayCircle className="h-4 w-4" />
+ },
```
This interface is important because it defines how Opcode Tutorial: GUI Command Center for Claude Code Workflows implements the patterns covered in this chapter.
-### `src/components/UsageDashboard.tsx`
+### `src/components/HooksEditor.tsx`
-The `UsageDashboardProps` interface in [`src/components/UsageDashboard.tsx`](https://github.com/winfunc/opcode/blob/HEAD/src/components/UsageDashboard.tsx) handles a key part of this chapter's functionality:
+The `EditableHookCommand` interface in [`src/components/HooksEditor.tsx`](https://github.com/winfunc/opcode/blob/HEAD/src/components/HooksEditor.tsx) handles a key part of this chapter's functionality:
```tsx
-} from "lucide-react";
+}
-interface UsageDashboardProps {
- /**
- * Callback when back button is clicked
- */
- onBack: () => void;
+interface EditableHookCommand extends HookCommand {
+ id: string;
}
-// Cache for storing fetched data
-const dataCache = new Map<string, { data: any; timestamp: number }>();
-const CACHE_DURATION = 10 * 60 * 1000; // 10 minutes cache - increased for better performance
+interface EditableHookMatcher extends Omit<HookMatcher, 'hooks'> {
+ id: string;
+ hooks: EditableHookCommand[];
+ expanded?: boolean;
+}
-/**
- * Optimized UsageDashboard component with caching and progressive loading
- */
-export const UsageDashboard: React.FC<UsageDashboardProps> = ({ }) => {
- const [loading, setLoading] = useState(true);
- const [error, setError] = useState<string | null>(null);
- const [stats, setStats] = useState<UsageStats | null>(null);
- const [sessionStats, setSessionStats] = useState<ProjectUsage[] | null>(null);
- const [selectedDateRange, setSelectedDateRange] = useState<"all" | "7d" | "30d">("7d");
- const [activeTab, setActiveTab] = useState("overview");
- const [hasLoadedTabs, setHasLoadedTabs] = useState<Set<string>>(new Set(["overview"]));
-
- // Pagination states
- const [projectsPage, setProjectsPage] = useState(1);
- const [sessionsPage, setSessionsPage] = useState(1);
- const ITEMS_PER_PAGE = 10;
-
- // Memoized formatters to prevent recreation on each render
- const formatCurrency = useMemo(() => (amount: number): string => {
+const EVENT_INFO: Record<HookEvent, { label: string; description: string; icon: React.ReactNode }> = {
+ PreToolUse: {
+ label: 'Pre Tool Use',
+ description: 'Runs before tool calls, can block and provide feedback',
+ icon: <Shield className="h-4 w-4" />
+ },
+ PostToolUse: {
+ label: 'Post Tool Use',
+ description: 'Runs after successful tool completion',
+ icon: <PlayCircle className="h-4 w-4" />
+ },
+ Notification: {
+ label: 'Notification',
+ description: 'Customizes notifications when Claude needs attention',
+ icon: <Zap className="h-4 w-4" />
+ },
+ Stop: {
+ label: 'Stop',
+ description: 'Runs when Claude finishes responding',
+ icon: <Code2 className="h-4 w-4" />
```
This interface is important because it defines how Opcode Tutorial: GUI Command Center for Claude Code Workflows implements the patterns covered in this chapter.
### `src/components/HooksEditor.tsx`
-The `HooksEditorProps` interface in [`src/components/HooksEditor.tsx`](https://github.com/winfunc/opcode/blob/HEAD/src/components/HooksEditor.tsx) handles a key part of this chapter's functionality:
+The `EditableHookMatcher` interface in [`src/components/HooksEditor.tsx`](https://github.com/winfunc/opcode/blob/HEAD/src/components/HooksEditor.tsx) handles a key part of this chapter's functionality:
```tsx
-} from '@/types/hooks';
-
-interface HooksEditorProps {
- projectPath?: string;
- scope: 'project' | 'local' | 'user';
- readOnly?: boolean;
- className?: string;
- onChange?: (hasChanges: boolean, getHooks: () => HooksConfiguration) => void;
- hideActions?: boolean;
-}
-
-interface EditableHookCommand extends HookCommand {
- id: string;
}
interface EditableHookMatcher extends Omit<HookMatcher, 'hooks'> {
@@ -207,6 +192,19 @@ const EVENT_INFO: Record<HookEvent, { label: string; description: string; icon:
description: 'Runs after successful tool completion',
icon: <PlayCircle className="h-4 w-4" />
},
+ Notification: {
+ label: 'Notification',
+ description: 'Customizes notifications when Claude needs attention',
+ icon: <Zap className="h-4 w-4" />
+ },
+ Stop: {
+ label: 'Stop',
+ description: 'Runs when Claude finishes responding',
+ icon: <Code2 className="h-4 w-4" />
+ },
+ SubagentStop: {
+ label: 'Subagent Stop',
+ description: 'Runs when a Claude subagent (Task) finishes',
```
This interface is important because it defines how Opcode Tutorial: GUI Command Center for Claude Code Workflows implements the patterns covered in this chapter.
@@ -216,11 +214,11 @@ This interface is important because it defines how Opcode Tutorial: GUI Command
```mermaid
flowchart TD
- A[FloatingPromptInputProps]
- B[FloatingPromptInputRef]
- C[UsageDashboardProps]
- D[HooksEditorProps]
- E[EditableHookCommand]
+ A[ClaudeStreamMessage]
+ B[HooksEditorProps]
+ C[EditableHookCommand]
+ D[EditableHookMatcher]
+ E[TableInfo]
A --> B
B --> C
C --> D
diff --git a/tutorials/opcode-tutorial/04-custom-agents-and-background-runs.md b/tutorials/opcode-tutorial/04-custom-agents-and-background-runs.md
index 6955b264..a271d28d 100644
--- a/tutorials/opcode-tutorial/04-custom-agents-and-background-runs.md
+++ b/tutorials/opcode-tutorial/04-custom-agents-and-background-runs.md
@@ -43,59 +43,13 @@ You now know how to build and operate specialized agent workflows in Opcode.
Next: [Chapter 5: MCP and Context Management](05-mcp-and-context-management.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/components/HooksEditor.tsx`
-
-The `EditableHookMatcher` interface in [`src/components/HooksEditor.tsx`](https://github.com/winfunc/opcode/blob/HEAD/src/components/HooksEditor.tsx) handles a key part of this chapter's functionality:
-
-```tsx
-}
-
-interface EditableHookMatcher extends Omit<HookMatcher, 'hooks'> {
- id: string;
- hooks: EditableHookCommand[];
- expanded?: boolean;
-}
-
-const EVENT_INFO: Record<HookEvent, { label: string; description: string; icon: React.ReactNode }> = {
- PreToolUse: {
- label: 'Pre Tool Use',
- description: 'Runs before tool calls, can block and provide feedback',
- icon: <Shield className="h-4 w-4" />
- },
- PostToolUse: {
- label: 'Post Tool Use',
- description: 'Runs after successful tool completion',
- icon: <PlayCircle className="h-4 w-4" />
- },
- Notification: {
- label: 'Notification',
- description: 'Customizes notifications when Claude needs attention',
- icon: <Zap className="h-4 w-4" />
- },
- Stop: {
- label: 'Stop',
- description: 'Runs when Claude finishes responding',
- icon: <Code2 className="h-4 w-4" />
- },
- SubagentStop: {
- label: 'Subagent Stop',
- description: 'Runs when a Claude subagent (Task) finishes',
-```
-
-This interface is important because it defines how Opcode Tutorial: GUI Command Center for Claude Code Workflows implements the patterns covered in this chapter.
-
### `src/components/StorageTab.tsx`
-The `TableInfo` interface in [`src/components/StorageTab.tsx`](https://github.com/winfunc/opcode/blob/HEAD/src/components/StorageTab.tsx) handles a key part of this chapter's functionality:
+The `ColumnInfo` interface in [`src/components/StorageTab.tsx`](https://github.com/winfunc/opcode/blob/HEAD/src/components/StorageTab.tsx) handles a key part of this chapter's functionality:
```tsx
-import { Toast, ToastContainer } from "./ui/toast";
-
-interface TableInfo {
name: string;
row_count: number;
columns: ColumnInfo[];
@@ -125,27 +79,18 @@ interface QueryResult {
rows: any[][];
rows_affected?: number;
last_insert_rowid?: number;
+}
+
+/**
```
This interface is important because it defines how Opcode Tutorial: GUI Command Center for Claude Code Workflows implements the patterns covered in this chapter.
### `src/components/StorageTab.tsx`
-The `ColumnInfo` interface in [`src/components/StorageTab.tsx`](https://github.com/winfunc/opcode/blob/HEAD/src/components/StorageTab.tsx) handles a key part of this chapter's functionality:
+The `TableData` interface in [`src/components/StorageTab.tsx`](https://github.com/winfunc/opcode/blob/HEAD/src/components/StorageTab.tsx) handles a key part of this chapter's functionality:
```tsx
- name: string;
- row_count: number;
- columns: ColumnInfo[];
-}
-
-interface ColumnInfo {
- cid: number;
- name: string;
- type_name: string;
- notnull: boolean;
- dflt_value: string | null;
- pk: boolean;
}
interface TableData {
@@ -166,27 +111,29 @@ interface QueryResult {
}
/**
+ * StorageTab component - A beautiful SQLite database viewer/editor
+ */
+export const StorageTab: React.FC = () => {
+ const [tables, setTables] = useState<TableInfo[]>([]);
+ const [selectedTable, setSelectedTable] = useState<string>("");
+ const [tableData, setTableData] = useState<TableData | null>(null);
+ const [currentPage, setCurrentPage] = useState(1);
+ const [pageSize] = useState(25);
+ const [searchQuery, setSearchQuery] = useState("");
+ const [loading, setLoading] = useState(false);
+ const [error, setError] = useState<string | null>(null);
+
```
This interface is important because it defines how Opcode Tutorial: GUI Command Center for Claude Code Workflows implements the patterns covered in this chapter.
### `src/components/StorageTab.tsx`
-The `TableData` interface in [`src/components/StorageTab.tsx`](https://github.com/winfunc/opcode/blob/HEAD/src/components/StorageTab.tsx) handles a key part of this chapter's functionality:
+The `QueryResult` interface in [`src/components/StorageTab.tsx`](https://github.com/winfunc/opcode/blob/HEAD/src/components/StorageTab.tsx) handles a key part of this chapter's functionality:
```tsx
}
-interface TableData {
- table_name: string;
- columns: ColumnInfo[];
- rows: Record<string, any>[];
- total_rows: number;
- page: number;
- page_size: number;
- total_pages: number;
-}
-
interface QueryResult {
columns: string[];
rows: any[][];
@@ -207,20 +154,71 @@ export const StorageTab: React.FC = () => {
const [loading, setLoading] = useState(false);
const [error, setError] = useState<string | null>(null);
+ // Dialog states
+ const [editingRow, setEditingRow] = useState<Record<string, any> | null>(null);
+ const [newRow, setNewRow] = useState<Record<string, any> | null>(null);
+ const [deletingRow, setDeletingRow] = useState<Record<string, any> | null>(null);
+ const [showResetConfirm, setShowResetConfirm] = useState(false);
+ const [showSqlEditor, setShowSqlEditor] = useState(false);
+ const [sqlQuery, setSqlQuery] = useState("");
+ const [sqlResult, setSqlResult] = useState<QueryResult | null>(null);
+ const [sqlError, setSqlError] = useState<string | null>(null);
+ const [toast, setToast] = useState<{ message: string; type: "success" | "error" } | null>(null);
```
This interface is important because it defines how Opcode Tutorial: GUI Command Center for Claude Code Workflows implements the patterns covered in this chapter.
+### `src/components/AgentRunOutputViewer.tsx`
+
+The `AgentRunOutputViewer` function in [`src/components/AgentRunOutputViewer.tsx`](https://github.com/winfunc/opcode/blob/HEAD/src/components/AgentRunOutputViewer.tsx) handles a key part of this chapter's functionality:
+
+```tsx
+import { useTabState } from '@/hooks/useTabState';
+
+interface AgentRunOutputViewerProps {
+ /**
+ * The agent run ID to display
+ */
+ agentRunId: string;
+ /**
+ * Tab ID for this agent run
+ */
+ tabId: string;
+ /**
+ * Optional className for styling
+ */
+ className?: string;
+}
+
+/**
+ * AgentRunOutputViewer - Modal component for viewing agent execution output
+ *
+ * @example
+ * <AgentRunOutputViewer
+ * run={agentRun}
+ * onClose={() => setSelectedRun(null)}
+ * />
+ */
+export function AgentRunOutputViewer({
+ agentRunId,
+ tabId,
+ className
+}: AgentRunOutputViewerProps) {
+ const { updateTabTitle, updateTabStatus } = useTabState();
+```
+
+This function is important because it defines how Opcode Tutorial: GUI Command Center for Claude Code Workflows implements the patterns covered in this chapter.
+
## How These Components Connect
```mermaid
flowchart TD
- A[EditableHookMatcher]
- B[TableInfo]
- C[ColumnInfo]
- D[TableData]
- E[QueryResult]
+ A[ColumnInfo]
+ B[TableData]
+ C[QueryResult]
+ D[AgentRunOutputViewer]
+ E[AgentRunOutputViewerProps]
A --> B
B --> C
C --> D
diff --git a/tutorials/opcode-tutorial/05-mcp-and-context-management.md b/tutorials/opcode-tutorial/05-mcp-and-context-management.md
index 3cee4279..dcb1414f 100644
--- a/tutorials/opcode-tutorial/05-mcp-and-context-management.md
+++ b/tutorials/opcode-tutorial/05-mcp-and-context-management.md
@@ -43,8 +43,6 @@ You now have a structured approach to managing integrations and context artifact
Next: [Chapter 6: Timeline, Checkpoints, and Recovery](06-timeline-checkpoints-and-recovery.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `src-tauri/src/web_server.rs`
diff --git a/tutorials/opcode-tutorial/06-timeline-checkpoints-and-recovery.md b/tutorials/opcode-tutorial/06-timeline-checkpoints-and-recovery.md
index 85016e2e..60e4894a 100644
--- a/tutorials/opcode-tutorial/06-timeline-checkpoints-and-recovery.md
+++ b/tutorials/opcode-tutorial/06-timeline-checkpoints-and-recovery.md
@@ -39,8 +39,6 @@ You now know how to use checkpointing as a first-class safety primitive in Opcod
Next: [Chapter 7: Development Workflow and Build from Source](07-development-workflow-and-build-from-source.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `src-tauri/src/web_server.rs`
@@ -84,128 +82,128 @@ async fn serve_frontend() -> Html<&'static str> {
This interface is important because it defines how Opcode Tutorial: GUI Command Center for Claude Code Workflows implements the patterns covered in this chapter.
-### `src/components/AgentRunOutputViewer.tsx`
+### `src/components/UsageDashboard.tsx`
-The `AgentRunOutputViewer` function in [`src/components/AgentRunOutputViewer.tsx`](https://github.com/winfunc/opcode/blob/HEAD/src/components/AgentRunOutputViewer.tsx) handles a key part of this chapter's functionality:
+The `UsageDashboardProps` interface in [`src/components/UsageDashboard.tsx`](https://github.com/winfunc/opcode/blob/HEAD/src/components/UsageDashboard.tsx) handles a key part of this chapter's functionality:
```tsx
-import { useTabState } from '@/hooks/useTabState';
+} from "lucide-react";
-interface AgentRunOutputViewerProps {
- /**
- * The agent run ID to display
- */
- agentRunId: string;
+interface UsageDashboardProps {
/**
- * Tab ID for this agent run
+ * Callback when back button is clicked
*/
- tabId: string;
- /**
- * Optional className for styling
- */
- className?: string;
+ onBack: () => void;
}
+// Cache for storing fetched data
+const dataCache = new Map<string, { data: any; timestamp: number }>();
+const CACHE_DURATION = 10 * 60 * 1000; // 10 minutes cache - increased for better performance
+
/**
- * AgentRunOutputViewer - Modal component for viewing agent execution output
- *
- * @example
- * <AgentRunOutputViewer
- * run={agentRun}
- * onClose={() => setSelectedRun(null)}
- * />
+ * Optimized UsageDashboard component with caching and progressive loading
*/
-export function AgentRunOutputViewer({
- agentRunId,
- tabId,
- className
-}: AgentRunOutputViewerProps) {
- const { updateTabTitle, updateTabStatus } = useTabState();
+export const UsageDashboard: React.FC<UsageDashboardProps> = ({ }) => {
+ const [loading, setLoading] = useState(true);
+ const [error, setError] = useState<string | null>(null);
+ const [stats, setStats] = useState<UsageStats | null>(null);
+ const [sessionStats, setSessionStats] = useState<ProjectUsage[] | null>(null);
+ const [selectedDateRange, setSelectedDateRange] = useState<"all" | "7d" | "30d">("7d");
+ const [activeTab, setActiveTab] = useState("overview");
+ const [hasLoadedTabs, setHasLoadedTabs] = useState<Set<string>>(new Set(["overview"]));
+
+ // Pagination states
+ const [projectsPage, setProjectsPage] = useState(1);
+ const [sessionsPage, setSessionsPage] = useState(1);
+ const ITEMS_PER_PAGE = 10;
+
+ // Memoized formatters to prevent recreation on each render
+ const formatCurrency = useMemo(() => (amount: number): string => {
```
-This function is important because it defines how Opcode Tutorial: GUI Command Center for Claude Code Workflows implements the patterns covered in this chapter.
+This interface is important because it defines how Opcode Tutorial: GUI Command Center for Claude Code Workflows implements the patterns covered in this chapter.
-### `src/components/AgentRunOutputViewer.tsx`
+### `src/components/SlashCommandsManager.tsx`
-The `AgentRunOutputViewerProps` interface in [`src/components/AgentRunOutputViewer.tsx`](https://github.com/winfunc/opcode/blob/HEAD/src/components/AgentRunOutputViewer.tsx) handles a key part of this chapter's functionality:
+The `SlashCommandsManagerProps` interface in [`src/components/SlashCommandsManager.tsx`](https://github.com/winfunc/opcode/blob/HEAD/src/components/SlashCommandsManager.tsx) handles a key part of this chapter's functionality:
```tsx
-import { useTabState } from '@/hooks/useTabState';
+import { useTrackEvent } from "@/hooks";
-interface AgentRunOutputViewerProps {
- /**
- * The agent run ID to display
- */
- agentRunId: string;
- /**
- * Tab ID for this agent run
- */
- tabId: string;
- /**
- * Optional className for styling
- */
+interface SlashCommandsManagerProps {
+ projectPath?: string;
className?: string;
+ scopeFilter?: 'project' | 'user' | 'all';
}
-/**
- * AgentRunOutputViewer - Modal component for viewing agent execution output
- *
- * @example
- * <AgentRunOutputViewer
- * run={agentRun}
- * onClose={() => setSelectedRun(null)}
- * />
- */
-export function AgentRunOutputViewer({
- agentRunId,
- tabId,
- className
-}: AgentRunOutputViewerProps) {
- const { updateTabTitle, updateTabStatus } = useTabState();
+interface CommandForm {
+ name: string;
+ namespace: string;
+ content: string;
+ description: string;
+ allowedTools: string[];
+ scope: 'project' | 'user';
+}
+
+const EXAMPLE_COMMANDS = [
+ {
+ name: "review",
+ description: "Review code for best practices",
+ content: "Review the following code for best practices, potential issues, and improvements:\n\n@$ARGUMENTS",
+ allowedTools: ["Read", "Grep"]
+ },
+ {
+ name: "explain",
+ description: "Explain how something works",
+ content: "Explain how $ARGUMENTS works in detail, including its purpose, implementation, and usage examples.",
+ allowedTools: ["Read", "Grep", "WebSearch"]
+ },
+ {
+ name: "fix-issue",
```
This interface is important because it defines how Opcode Tutorial: GUI Command Center for Claude Code Workflows implements the patterns covered in this chapter.
-### `src/components/SessionOutputViewer.tsx`
+### `src/components/SlashCommandsManager.tsx`
-The `SessionOutputViewer` function in [`src/components/SessionOutputViewer.tsx`](https://github.com/winfunc/opcode/blob/HEAD/src/components/SessionOutputViewer.tsx) handles a key part of this chapter's functionality:
+The `CommandForm` interface in [`src/components/SlashCommandsManager.tsx`](https://github.com/winfunc/opcode/blob/HEAD/src/components/SlashCommandsManager.tsx) handles a key part of this chapter's functionality:
```tsx
-import { ErrorBoundary } from './ErrorBoundary';
-
-interface SessionOutputViewerProps {
- session: AgentRun;
- onClose: () => void;
- className?: string;
}
-// Use the same message interface as AgentExecution for consistency
-export interface ClaudeStreamMessage {
- type: "system" | "assistant" | "user" | "result";
- subtype?: string;
- message?: {
- content?: any[];
- usage?: {
- input_tokens: number;
- output_tokens: number;
- };
- };
- usage?: {
- input_tokens: number;
- output_tokens: number;
- };
- [key: string]: any;
+interface CommandForm {
+ name: string;
+ namespace: string;
+ content: string;
+ description: string;
+ allowedTools: string[];
+ scope: 'project' | 'user';
}
-export function SessionOutputViewer({ session, onClose, className }: SessionOutputViewerProps) {
- const [messages, setMessages] = useState<ClaudeStreamMessage[]>([]);
- const [rawJsonlOutput, setRawJsonlOutput] = useState<string[]>([]);
- const [loading, setLoading] = useState(false);
- const [isFullscreen, setIsFullscreen] = useState(false);
- const [refreshing, setRefreshing] = useState(false);
+const EXAMPLE_COMMANDS = [
+ {
+ name: "review",
+ description: "Review code for best practices",
+ content: "Review the following code for best practices, potential issues, and improvements:\n\n@$ARGUMENTS",
+ allowedTools: ["Read", "Grep"]
+ },
+ {
+ name: "explain",
+ description: "Explain how something works",
+ content: "Explain how $ARGUMENTS works in detail, including its purpose, implementation, and usage examples.",
+ allowedTools: ["Read", "Grep", "WebSearch"]
+ },
+ {
+ name: "fix-issue",
+ description: "Fix a specific issue",
+ content: "Fix issue #$ARGUMENTS following our coding standards and best practices.",
+ allowedTools: ["Read", "Edit", "MultiEdit", "Write"]
+ },
+ {
+ name: "test",
```
-This function is important because it defines how Opcode Tutorial: GUI Command Center for Claude Code Workflows implements the patterns covered in this chapter.
+This interface is important because it defines how Opcode Tutorial: GUI Command Center for Claude Code Workflows implements the patterns covered in this chapter.
## How These Components Connect
@@ -213,10 +211,10 @@ This function is important because it defines how Opcode Tutorial: GUI Command C
```mermaid
flowchart TD
A[ApiResponse]
- B[AgentRunOutputViewer]
- C[AgentRunOutputViewerProps]
- D[SessionOutputViewer]
- E[SessionOutputViewerProps]
+ B[UsageDashboardProps]
+ C[SlashCommandsManagerProps]
+ D[CommandForm]
+ E[for]
A --> B
B --> C
C --> D
diff --git a/tutorials/opcode-tutorial/07-development-workflow-and-build-from-source.md b/tutorials/opcode-tutorial/07-development-workflow-and-build-from-source.md
index d450f90f..690e58ac 100644
--- a/tutorials/opcode-tutorial/07-development-workflow-and-build-from-source.md
+++ b/tutorials/opcode-tutorial/07-development-workflow-and-build-from-source.md
@@ -45,24 +45,13 @@ You now have a full contributor baseline for building and validating Opcode.
Next: [Chapter 8: Production Operations and Security](08-production-operations-and-security.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `src/components/SessionOutputViewer.tsx`
-The `as` interface in [`src/components/SessionOutputViewer.tsx`](https://github.com/winfunc/opcode/blob/HEAD/src/components/SessionOutputViewer.tsx) handles a key part of this chapter's functionality:
+The `SessionOutputViewer` function in [`src/components/SessionOutputViewer.tsx`](https://github.com/winfunc/opcode/blob/HEAD/src/components/SessionOutputViewer.tsx) handles a key part of this chapter's functionality:
```tsx
-import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
-import { Badge } from '@/components/ui/badge';
-import { Toast, ToastContainer } from '@/components/ui/toast';
-import { Popover } from '@/components/ui/popover';
-import { api } from '@/lib/api';
-import { useOutputCache } from '@/lib/outputCache';
-import type { AgentRun } from '@/lib/api';
-import { listen, type UnlistenFn } from '@tauri-apps/api/event';
-import { StreamMessage } from './StreamMessage';
import { ErrorBoundary } from './ErrorBoundary';
interface SessionOutputViewerProps {
@@ -86,15 +75,31 @@ export interface ClaudeStreamMessage {
input_tokens: number;
output_tokens: number;
};
+ [key: string]: any;
+}
+
+export function SessionOutputViewer({ session, onClose, className }: SessionOutputViewerProps) {
+ const [messages, setMessages] = useState<ClaudeStreamMessage[]>([]);
+ const [rawJsonlOutput, setRawJsonlOutput] = useState<string[]>([]);
+ const [loading, setLoading] = useState(false);
+ const [isFullscreen, setIsFullscreen] = useState(false);
+ const [refreshing, setRefreshing] = useState(false);
```
-This interface is important because it defines how Opcode Tutorial: GUI Command Center for Claude Code Workflows implements the patterns covered in this chapter.
+This function is important because it defines how Opcode Tutorial: GUI Command Center for Claude Code Workflows implements the patterns covered in this chapter.
### `src/components/SessionOutputViewer.tsx`
-The `ClaudeStreamMessage` interface in [`src/components/SessionOutputViewer.tsx`](https://github.com/winfunc/opcode/blob/HEAD/src/components/SessionOutputViewer.tsx) handles a key part of this chapter's functionality:
+The `SessionOutputViewerProps` interface in [`src/components/SessionOutputViewer.tsx`](https://github.com/winfunc/opcode/blob/HEAD/src/components/SessionOutputViewer.tsx) handles a key part of this chapter's functionality:
```tsx
+import { ErrorBoundary } from './ErrorBoundary';
+
+interface SessionOutputViewerProps {
+ session: AgentRun;
+ onClose: () => void;
+ className?: string;
+}
// Use the same message interface as AgentExecution for consistency
export interface ClaudeStreamMessage {
@@ -120,95 +125,88 @@ export function SessionOutputViewer({ session, onClose, className }: SessionOutp
const [loading, setLoading] = useState(false);
const [isFullscreen, setIsFullscreen] = useState(false);
const [refreshing, setRefreshing] = useState(false);
- const [toast, setToast] = useState<{ message: string; type: "success" | "error" } | null>(null);
- const [copyPopoverOpen, setCopyPopoverOpen] = useState(false);
- const [hasUserScrolled, setHasUserScrolled] = useState(false);
-
- const scrollAreaRef = useRef<HTMLDivElement>(null);
- const outputEndRef = useRef<HTMLDivElement>(null);
- const fullscreenScrollRef = useRef<HTMLDivElement>(null);
```
This interface is important because it defines how Opcode Tutorial: GUI Command Center for Claude Code Workflows implements the patterns covered in this chapter.
-### `src/components/SlashCommandsManager.tsx`
+### `src/components/SessionOutputViewer.tsx`
-The `SlashCommandsManagerProps` interface in [`src/components/SlashCommandsManager.tsx`](https://github.com/winfunc/opcode/blob/HEAD/src/components/SlashCommandsManager.tsx) handles a key part of this chapter's functionality:
+The `as` interface in [`src/components/SessionOutputViewer.tsx`](https://github.com/winfunc/opcode/blob/HEAD/src/components/SessionOutputViewer.tsx) handles a key part of this chapter's functionality:
```tsx
-import { useTrackEvent } from "@/hooks";
+import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
+import { Badge } from '@/components/ui/badge';
+import { Toast, ToastContainer } from '@/components/ui/toast';
+import { Popover } from '@/components/ui/popover';
+import { api } from '@/lib/api';
+import { useOutputCache } from '@/lib/outputCache';
+import type { AgentRun } from '@/lib/api';
+import { listen, type UnlistenFn } from '@tauri-apps/api/event';
+import { StreamMessage } from './StreamMessage';
+import { ErrorBoundary } from './ErrorBoundary';
-interface SlashCommandsManagerProps {
- projectPath?: string;
+interface SessionOutputViewerProps {
+ session: AgentRun;
+ onClose: () => void;
className?: string;
- scopeFilter?: 'project' | 'user' | 'all';
-}
-
-interface CommandForm {
- name: string;
- namespace: string;
- content: string;
- description: string;
- allowedTools: string[];
- scope: 'project' | 'user';
}
-const EXAMPLE_COMMANDS = [
- {
- name: "review",
- description: "Review code for best practices",
- content: "Review the following code for best practices, potential issues, and improvements:\n\n@$ARGUMENTS",
- allowedTools: ["Read", "Grep"]
- },
- {
- name: "explain",
- description: "Explain how something works",
- content: "Explain how $ARGUMENTS works in detail, including its purpose, implementation, and usage examples.",
- allowedTools: ["Read", "Grep", "WebSearch"]
- },
- {
- name: "fix-issue",
+// Use the same message interface as AgentExecution for consistency
+export interface ClaudeStreamMessage {
+ type: "system" | "assistant" | "user" | "result";
+ subtype?: string;
+ message?: {
+ content?: any[];
+ usage?: {
+ input_tokens: number;
+ output_tokens: number;
+ };
+ };
+ usage?: {
+ input_tokens: number;
+ output_tokens: number;
+ };
```
This interface is important because it defines how Opcode Tutorial: GUI Command Center for Claude Code Workflows implements the patterns covered in this chapter.
-### `src/components/SlashCommandsManager.tsx`
+### `src/components/SessionOutputViewer.tsx`
-The `CommandForm` interface in [`src/components/SlashCommandsManager.tsx`](https://github.com/winfunc/opcode/blob/HEAD/src/components/SlashCommandsManager.tsx) handles a key part of this chapter's functionality:
+The `ClaudeStreamMessage` interface in [`src/components/SessionOutputViewer.tsx`](https://github.com/winfunc/opcode/blob/HEAD/src/components/SessionOutputViewer.tsx) handles a key part of this chapter's functionality:
```tsx
-}
-interface CommandForm {
- name: string;
- namespace: string;
- content: string;
- description: string;
- allowedTools: string[];
- scope: 'project' | 'user';
+// Use the same message interface as AgentExecution for consistency
+export interface ClaudeStreamMessage {
+ type: "system" | "assistant" | "user" | "result";
+ subtype?: string;
+ message?: {
+ content?: any[];
+ usage?: {
+ input_tokens: number;
+ output_tokens: number;
+ };
+ };
+ usage?: {
+ input_tokens: number;
+ output_tokens: number;
+ };
+ [key: string]: any;
}
-const EXAMPLE_COMMANDS = [
- {
- name: "review",
- description: "Review code for best practices",
- content: "Review the following code for best practices, potential issues, and improvements:\n\n@$ARGUMENTS",
- allowedTools: ["Read", "Grep"]
- },
- {
- name: "explain",
- description: "Explain how something works",
- content: "Explain how $ARGUMENTS works in detail, including its purpose, implementation, and usage examples.",
- allowedTools: ["Read", "Grep", "WebSearch"]
- },
- {
- name: "fix-issue",
- description: "Fix a specific issue",
- content: "Fix issue #$ARGUMENTS following our coding standards and best practices.",
- allowedTools: ["Read", "Edit", "MultiEdit", "Write"]
- },
- {
- name: "test",
+export function SessionOutputViewer({ session, onClose, className }: SessionOutputViewerProps) {
+ const [messages, setMessages] = useState<ClaudeStreamMessage[]>([]);
+ const [rawJsonlOutput, setRawJsonlOutput] = useState<string[]>([]);
+ const [loading, setLoading] = useState(false);
+ const [isFullscreen, setIsFullscreen] = useState(false);
+ const [refreshing, setRefreshing] = useState(false);
+ const [toast, setToast] = useState<{ message: string; type: "success" | "error" } | null>(null);
+ const [copyPopoverOpen, setCopyPopoverOpen] = useState(false);
+ const [hasUserScrolled, setHasUserScrolled] = useState(false);
+
+ const scrollAreaRef = useRef<HTMLDivElement>(null);
+ const outputEndRef = useRef<HTMLDivElement>(null);
+ const fullscreenScrollRef = useRef<HTMLDivElement>(null);
```
This interface is important because it defines how Opcode Tutorial: GUI Command Center for Claude Code Workflows implements the patterns covered in this chapter.
@@ -218,11 +216,11 @@ This interface is important because it defines how Opcode Tutorial: GUI Command
```mermaid
flowchart TD
- A[as]
- B[ClaudeStreamMessage]
- C[SlashCommandsManagerProps]
- D[CommandForm]
- E[for]
+ A[SessionOutputViewer]
+ B[SessionOutputViewerProps]
+ C[as]
+ D[ClaudeStreamMessage]
+ E[find_claude_binary]
A --> B
B --> C
C --> D
diff --git a/tutorials/opcode-tutorial/08-production-operations-and-security.md b/tutorials/opcode-tutorial/08-production-operations-and-security.md
index 22539cd5..c2cc4313 100644
--- a/tutorials/opcode-tutorial/08-production-operations-and-security.md
+++ b/tutorials/opcode-tutorial/08-production-operations-and-security.md
@@ -47,53 +47,10 @@ You now have a complete runbook for operating Opcode as a governed desktop contr
Compare higher-level orchestration in the [Vibe Kanban Tutorial](../vibe-kanban-tutorial/).
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `src-tauri/src/claude_binary.rs`
-The `find_claude_binary` function in [`src-tauri/src/claude_binary.rs`](https://github.com/winfunc/opcode/blob/HEAD/src-tauri/src/claude_binary.rs) handles a key part of this chapter's functionality:
-
-```rs
-/// Main function to find the Claude binary
-/// Checks database first for stored path and preference, then prioritizes accordingly
-pub fn find_claude_binary(app_handle: &tauri::AppHandle) -> Result<String, String> {
- info!("Searching for claude binary...");
-
- // First check if we have a stored path and preference in the database
- if let Ok(app_data_dir) = app_handle.path().app_data_dir() {
- let db_path = app_data_dir.join("agents.db");
- if db_path.exists() {
- if let Ok(conn) = rusqlite::Connection::open(&db_path) {
- // Check for stored path first
- if let Ok(stored_path) = conn.query_row(
- "SELECT value FROM app_settings WHERE key = 'claude_binary_path'",
- [],
- |row| row.get::<_, String>(0),
- ) {
- info!("Found stored claude path in database: {}", stored_path);
-
- // Check if the path still exists
- let path_buf = PathBuf::from(&stored_path);
- if path_buf.exists() && path_buf.is_file() {
- return Ok(stored_path);
- } else {
- warn!("Stored claude path no longer exists: {}", stored_path);
- }
- }
-
- // Check user preference
- let preference = conn.query_row(
- "SELECT value FROM app_settings WHERE key = 'claude_installation_preference'",
- [],
- |row| row.get::<_, String>(0),
-```
-
-This function is important because it defines how Opcode Tutorial: GUI Command Center for Claude Code Workflows implements the patterns covered in this chapter.
-
-### `src-tauri/src/claude_binary.rs`
-
The `discover_claude_installations` function in [`src-tauri/src/claude_binary.rs`](https://github.com/winfunc/opcode/blob/HEAD/src-tauri/src/claude_binary.rs) handles a key part of this chapter's functionality:
```rs
@@ -215,16 +172,57 @@ pub fn find_claude_binary(app_handle: &tauri::AppHandle) -> Result<String, Strin
This interface is important because it defines how Opcode Tutorial: GUI Command Center for Claude Code Workflows implements the patterns covered in this chapter.
+### `src-tauri/src/claude_binary.rs`
+
+The `InstallationType` interface in [`src-tauri/src/claude_binary.rs`](https://github.com/winfunc/opcode/blob/HEAD/src-tauri/src/claude_binary.rs) handles a key part of this chapter's functionality:
+
+```rs
+/// Type of Claude installation
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+pub enum InstallationType {
+ /// System-installed binary
+ System,
+ /// Custom path specified by user
+ Custom,
+}
+
+/// Represents a Claude installation with metadata
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ClaudeInstallation {
+ /// Full path to the Claude binary
+ pub path: String,
+ /// Version string if available
+ pub version: Option<String>,
+ /// Source of discovery (e.g., "nvm", "system", "homebrew", "which")
+ pub source: String,
+ /// Type of installation
+ pub installation_type: InstallationType,
+}
+
+/// Main function to find the Claude binary
+/// Checks database first for stored path and preference, then prioritizes accordingly
+pub fn find_claude_binary(app_handle: &tauri::AppHandle) -> Result<String, String> {
+ info!("Searching for claude binary...");
+
+ // First check if we have a stored path and preference in the database
+ if let Ok(app_data_dir) = app_handle.path().app_data_dir() {
+ let db_path = app_data_dir.join("agents.db");
+ if db_path.exists() {
+ if let Ok(conn) = rusqlite::Connection::open(&db_path) {
+```
+
+This interface is important because it defines how Opcode Tutorial: GUI Command Center for Claude Code Workflows implements the patterns covered in this chapter.
+
## How These Components Connect
```mermaid
flowchart TD
- A[find_claude_binary]
- B[discover_claude_installations]
- C[create_command_with_env]
- D[ClaudeInstallation]
- E[InstallationType]
+ A[discover_claude_installations]
+ B[create_command_with_env]
+ C[ClaudeInstallation]
+ D[InstallationType]
+ E[UsageDashboardProps]
A --> B
B --> C
C --> D
diff --git a/tutorials/open-swe-tutorial/01-getting-started-and-project-status.md b/tutorials/open-swe-tutorial/01-getting-started-and-project-status.md
index 2a123aaa..39d6d4a5 100644
--- a/tutorials/open-swe-tutorial/01-getting-started-and-project-status.md
+++ b/tutorials/open-swe-tutorial/01-getting-started-and-project-status.md
@@ -36,170 +36,166 @@ You now have the correct operating context for responsible Open SWE usage.
Next: [Chapter 2: LangGraph Architecture and Agent Graphs](02-langgraph-architecture-and-agent-graphs.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `agent/utils/github_comments.py`
+### `scripts/check_pr_merge_status.py`
-The `verify_github_signature` function in [`agent/utils/github_comments.py`](https://github.com/langchain-ai/open-swe/blob/HEAD/agent/utils/github_comments.py) handles a key part of this chapter's functionality:
+The `from` class in [`scripts/check_pr_merge_status.py`](https://github.com/langchain-ai/open-swe/blob/HEAD/scripts/check_pr_merge_status.py) handles a key part of this chapter's functionality:
```py
+"""Check merge status counts for PR URLs exported from LangGraph threads."""
+from __future__ import annotations
-def verify_github_signature(body: bytes, signature: str, *, secret: str) -> bool:
- """Verify the GitHub webhook signature (X-Hub-Signature-256).
-
- Args:
- body: Raw request body bytes.
- signature: The X-Hub-Signature-256 header value.
- secret: The webhook signing secret.
+import argparse
+import asyncio
+import json
+import logging
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlparse
- Returns:
- True if signature is valid or no secret is configured.
- """
- if not secret:
- logger.warning("GITHUB_WEBHOOK_SECRET is not configured — rejecting webhook request")
- return False
+import httpx
- expected = "sha256=" + hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
- return hmac.compare_digest(expected, signature)
+logger = logging.getLogger(__name__)
+DEFAULT_INPUT_PATH = "pr_urls.json"
+DEFAULT_CONCURRENCY = 20
+GITHUB_API_VERSION = "2022-11-28"
-def get_thread_id_from_branch(branch_name: str) -> str | None:
- match = re.search(
- r"[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}",
- branch_name,
- re.IGNORECASE,
- )
- return match.group(0) if match else None
+def _load_dotenv_if_available() -> None:
+ try:
+ from dotenv import load_dotenv
+ except ImportError:
+ return
+ load_dotenv()
-def sanitize_github_comment_body(body: str) -> str:
- """Strip reserved trust wrapper tags from raw GitHub comment bodies."""
```
-This function is important because it defines how Open SWE Tutorial: Asynchronous Cloud Coding Agent Architecture and Migration Playbook implements the patterns covered in this chapter.
+This class is important because it defines how Open SWE Tutorial: Asynchronous Cloud Coding Agent Architecture and Migration Playbook implements the patterns covered in this chapter.
-### `agent/utils/github_comments.py`
+### `scripts/check_pr_merge_status.py`
-The `get_thread_id_from_branch` function in [`agent/utils/github_comments.py`](https://github.com/langchain-ai/open-swe/blob/HEAD/agent/utils/github_comments.py) handles a key part of this chapter's functionality:
+The `PullRequestRef` class in [`scripts/check_pr_merge_status.py`](https://github.com/langchain-ai/open-swe/blob/HEAD/scripts/check_pr_merge_status.py) handles a key part of this chapter's functionality:
```py
-
-def get_thread_id_from_branch(branch_name: str) -> str | None:
- match = re.search(
- r"[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}",
- branch_name,
- re.IGNORECASE,
- )
- return match.group(0) if match else None
-
-
-def sanitize_github_comment_body(body: str) -> str:
- """Strip reserved trust wrapper tags from raw GitHub comment bodies."""
- sanitized = body.replace(
- UNTRUSTED_GITHUB_COMMENT_OPEN_TAG,
- _SANITIZED_UNTRUSTED_GITHUB_COMMENT_OPEN_TAG,
- ).replace(
- UNTRUSTED_GITHUB_COMMENT_CLOSE_TAG,
- _SANITIZED_UNTRUSTED_GITHUB_COMMENT_CLOSE_TAG,
+@dataclass(frozen=True)
+class PullRequestRef:
+ owner: str
+ repo: str
+ number: int
+ url: str
+
+
+def parse_github_pr_url(pr_url: str) -> PullRequestRef:
+ parsed_url = urlparse(pr_url)
+ if parsed_url.scheme not in {"http", "https"}:
+ raise ValueError(f"Unsupported PR URL scheme: {pr_url}")
+ if parsed_url.netloc not in {"github.com", "www.github.com"}:
+ raise ValueError(f"Unsupported PR URL host: {pr_url}")
+
+ path_parts = [part for part in parsed_url.path.split("/") if part]
+ if len(path_parts) < 4 or path_parts[2] != "pull":
+ raise ValueError(f"Unsupported GitHub PR URL path: {pr_url}")
+
+ try:
+ number = int(path_parts[3])
+ except ValueError as exc:
+ raise ValueError(f"Invalid GitHub PR number in URL: {pr_url}") from exc
+
+ return PullRequestRef(
+ owner=path_parts[0],
+ repo=path_parts[1],
+ number=number,
+ url=pr_url,
)
- if sanitized != body:
- logger.warning("Sanitized reserved untrusted-comment tags from GitHub comment body")
- return sanitized
-
-def format_github_comment_body_for_prompt(author: str, body: str) -> str:
- """Format a GitHub comment body for prompt inclusion."""
- sanitized_body = sanitize_github_comment_body(body)
- if author in GITHUB_USER_EMAIL_MAP:
- return sanitized_body
-
- return (
```
-This function is important because it defines how Open SWE Tutorial: Asynchronous Cloud Coding Agent Architecture and Migration Playbook implements the patterns covered in this chapter.
+This class is important because it defines how Open SWE Tutorial: Asynchronous Cloud Coding Agent Architecture and Migration Playbook implements the patterns covered in this chapter.
-### `agent/utils/github_comments.py`
+### `scripts/check_pr_merge_status.py`
-The `sanitize_github_comment_body` function in [`agent/utils/github_comments.py`](https://github.com/langchain-ai/open-swe/blob/HEAD/agent/utils/github_comments.py) handles a key part of this chapter's functionality:
+The `parse_github_pr_url` function in [`scripts/check_pr_merge_status.py`](https://github.com/langchain-ai/open-swe/blob/HEAD/scripts/check_pr_merge_status.py) handles a key part of this chapter's functionality:
```py
-def sanitize_github_comment_body(body: str) -> str:
- """Strip reserved trust wrapper tags from raw GitHub comment bodies."""
- sanitized = body.replace(
- UNTRUSTED_GITHUB_COMMENT_OPEN_TAG,
- _SANITIZED_UNTRUSTED_GITHUB_COMMENT_OPEN_TAG,
- ).replace(
- UNTRUSTED_GITHUB_COMMENT_CLOSE_TAG,
- _SANITIZED_UNTRUSTED_GITHUB_COMMENT_CLOSE_TAG,
- )
- if sanitized != body:
- logger.warning("Sanitized reserved untrusted-comment tags from GitHub comment body")
- return sanitized
+def parse_github_pr_url(pr_url: str) -> PullRequestRef:
+ parsed_url = urlparse(pr_url)
+ if parsed_url.scheme not in {"http", "https"}:
+ raise ValueError(f"Unsupported PR URL scheme: {pr_url}")
+ if parsed_url.netloc not in {"github.com", "www.github.com"}:
+ raise ValueError(f"Unsupported PR URL host: {pr_url}")
+ path_parts = [part for part in parsed_url.path.split("/") if part]
+ if len(path_parts) < 4 or path_parts[2] != "pull":
+ raise ValueError(f"Unsupported GitHub PR URL path: {pr_url}")
-def format_github_comment_body_for_prompt(author: str, body: str) -> str:
- """Format a GitHub comment body for prompt inclusion."""
- sanitized_body = sanitize_github_comment_body(body)
- if author in GITHUB_USER_EMAIL_MAP:
- return sanitized_body
+ try:
+ number = int(path_parts[3])
+ except ValueError as exc:
+ raise ValueError(f"Invalid GitHub PR number in URL: {pr_url}") from exc
- return (
- f"{UNTRUSTED_GITHUB_COMMENT_OPEN_TAG}\n"
- f"{sanitized_body}\n"
- f"{UNTRUSTED_GITHUB_COMMENT_CLOSE_TAG}"
+ return PullRequestRef(
+ owner=path_parts[0],
+ repo=path_parts[1],
+ number=number,
+ url=pr_url,
)
-async def react_to_github_comment(
- repo_config: dict[str, str],
- comment_id: int,
+def load_pr_urls(input_path: Path) -> list[str]:
+ payload = json.loads(input_path.read_text(encoding="utf-8"))
+ if not isinstance(payload, list):
+ raise ValueError(f"Expected {input_path} to contain a JSON array of PR URLs")
+
+ unique_urls: list[str] = []
```
This function is important because it defines how Open SWE Tutorial: Asynchronous Cloud Coding Agent Architecture and Migration Playbook implements the patterns covered in this chapter.
-### `agent/utils/github_comments.py`
+### `scripts/check_pr_merge_status.py`
-The `format_github_comment_body_for_prompt` function in [`agent/utils/github_comments.py`](https://github.com/langchain-ai/open-swe/blob/HEAD/agent/utils/github_comments.py) handles a key part of this chapter's functionality:
+The `load_pr_urls` function in [`scripts/check_pr_merge_status.py`](https://github.com/langchain-ai/open-swe/blob/HEAD/scripts/check_pr_merge_status.py) handles a key part of this chapter's functionality:
```py
-def format_github_comment_body_for_prompt(author: str, body: str) -> str:
- """Format a GitHub comment body for prompt inclusion."""
- sanitized_body = sanitize_github_comment_body(body)
- if author in GITHUB_USER_EMAIL_MAP:
- return sanitized_body
+def load_pr_urls(input_path: Path) -> list[str]:
+ payload = json.loads(input_path.read_text(encoding="utf-8"))
+ if not isinstance(payload, list):
+ raise ValueError(f"Expected {input_path} to contain a JSON array of PR URLs")
- return (
- f"{UNTRUSTED_GITHUB_COMMENT_OPEN_TAG}\n"
- f"{sanitized_body}\n"
- f"{UNTRUSTED_GITHUB_COMMENT_CLOSE_TAG}"
- )
+ unique_urls: list[str] = []
+ seen_urls: set[str] = set()
+ for item in payload:
+ if not isinstance(item, str) or not item:
+ raise ValueError(f"Expected every item in {input_path} to be a non-empty string")
+ if item not in seen_urls:
+ seen_urls.add(item)
+ unique_urls.append(item)
+ return unique_urls
+
+
+def classify_pr_state(pr_payload: dict[str, Any]) -> str:
+ if pr_payload.get("merged") or pr_payload.get("merged_at"):
+ return "merged"
+ state = pr_payload.get("state")
+ if state == "open":
+ return "open_or_draft"
+ if state == "closed":
+ return "closed"
-async def react_to_github_comment(
- repo_config: dict[str, str],
- comment_id: int,
- *,
- event_type: str,
- token: str,
- pull_number: int | None = None,
- node_id: str | None = None,
-) -> bool:
- if event_type == "pull_request_review":
- return await _react_via_graphql(node_id, token=token)
+ raise ValueError(f"Unsupported GitHub PR state: {state!r}")
- owner = repo_config.get("owner", "")
- repo = repo_config.get("name", "")
- url_template = _REACTION_ENDPOINTS.get(event_type, _REACTION_ENDPOINTS["issue_comment"])
- url = url_template.format(
+async def _fetch_pr_state(
```
This function is important because it defines how Open SWE Tutorial: Asynchronous Cloud Coding Agent Architecture and Migration Playbook implements the patterns covered in this chapter.
@@ -209,11 +205,11 @@ This function is important because it defines how Open SWE Tutorial: Asynchronou
```mermaid
flowchart TD
- A[verify_github_signature]
- B[get_thread_id_from_branch]
- C[sanitize_github_comment_body]
- D[format_github_comment_body_for_prompt]
- E[react_to_github_comment]
+ A[from]
+ B[PullRequestRef]
+ C[parse_github_pr_url]
+ D[load_pr_urls]
+ E[classify_pr_state]
A --> B
B --> C
C --> D
diff --git a/tutorials/open-swe-tutorial/02-langgraph-architecture-and-agent-graphs.md b/tutorials/open-swe-tutorial/02-langgraph-architecture-and-agent-graphs.md
index a50076e0..90010e22 100644
--- a/tutorials/open-swe-tutorial/02-langgraph-architecture-and-agent-graphs.md
+++ b/tutorials/open-swe-tutorial/02-langgraph-architecture-and-agent-graphs.md
@@ -38,99 +38,144 @@ You now understand Open SWE's core orchestration model and where to customize it
Next: [Chapter 3: Development Environment and Monorepo Setup](03-development-environment-and-monorepo-setup.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `agent/utils/github_comments.py`
+### `agent/server.py`
-The `build_pr_prompt` function in [`agent/utils/github_comments.py`](https://github.com/langchain-ai/open-swe/blob/HEAD/agent/utils/github_comments.py) handles a key part of this chapter's functionality:
+The `graph_loaded_for_execution` function in [`agent/server.py`](https://github.com/langchain-ai/open-swe/blob/HEAD/agent/server.py) handles a key part of this chapter's functionality:
```py
-def build_pr_prompt(comments: list[dict[str, Any]], pr_url: str) -> str:
- """Format PR comments into a human message for the agent."""
- lines: list[str] = []
- for c in comments:
- author = c.get("author", "unknown")
- body = format_github_comment_body_for_prompt(author, c.get("body", ""))
- if c.get("type") == "review_comment":
- path = c.get("path", "")
- line = c.get("line", "")
- loc = f" (file: `{path}`, line: {line})" if path else ""
- lines.append(f"\n**{author}**{loc}:\n{body}\n")
- else:
- lines.append(f"\n**{author}**:\n{body}\n")
-
- comments_text = "".join(lines)
+def graph_loaded_for_execution(config: RunnableConfig) -> bool:
+ """Check if the graph is loaded for actual execution vs introspection."""
return (
- "You've been tagged in GitHub PR comments. Please resolve them.\n\n"
- f"PR: {pr_url}\n\n"
- f"## Comments:\n{comments_text}\n\n"
- "If code changes are needed:\n"
- "1. Make the changes in the sandbox\n"
- "2. Call `commit_and_open_pr` to push them to GitHub — this is REQUIRED, do NOT skip it\n"
- "3. Call `github_comment` with the PR number to post a summary on GitHub\n\n"
- "If no code changes are needed:\n"
- "1. Call `github_comment` with the PR number to explain your answer — this is REQUIRED, never end silently\n\n"
- "**You MUST always call `github_comment` before finishing — whether or not changes were made.**"
+ config["configurable"].get("__is_for_execution__", False)
+ if "configurable" in config
+ else False
)
-async def _fetch_paginated(
+DEFAULT_LLM_MODEL_ID = "anthropic:claude-opus-4-6"
+DEFAULT_RECURSION_LIMIT = 1_000
+
+
+async def get_agent(config: RunnableConfig) -> Pregel: # noqa: PLR0915
+ """Get or create an agent with a sandbox for the given thread."""
+ thread_id = config["configurable"].get("thread_id", None)
+
+ config["recursion_limit"] = DEFAULT_RECURSION_LIMIT
+
+ repo_config = config["configurable"].get("repo", {})
+ repo_owner = repo_config.get("owner")
+ repo_name = repo_config.get("name")
+
+ if thread_id is None or not graph_loaded_for_execution(config):
+ logger.info("No thread_id or not for execution, returning agent without sandbox")
+ return create_deep_agent(
+ system_prompt="",
+ tools=[],
+ ).with_config(config)
+
```
This function is important because it defines how Open SWE Tutorial: Asynchronous Cloud Coding Agent Architecture and Migration Playbook implements the patterns covered in this chapter.
-### `agent/utils/slack.py`
+### `agent/server.py`
-The `replace_bot_mention_with_username` function in [`agent/utils/slack.py`](https://github.com/langchain-ai/open-swe/blob/HEAD/agent/utils/slack.py) handles a key part of this chapter's functionality:
+The `get_agent` function in [`agent/server.py`](https://github.com/langchain-ai/open-swe/blob/HEAD/agent/server.py) handles a key part of this chapter's functionality:
```py
-def replace_bot_mention_with_username(text: str, bot_user_id: str, bot_username: str) -> str:
- """Replace Slack bot ID mention token with @username."""
- if not text:
- return ""
- if bot_user_id and bot_username:
- return text.replace(f"<@{bot_user_id}>", f"@{bot_username}")
- return text
+async def get_agent(config: RunnableConfig) -> Pregel: # noqa: PLR0915
+ """Get or create an agent with a sandbox for the given thread."""
+ thread_id = config["configurable"].get("thread_id", None)
+ config["recursion_limit"] = DEFAULT_RECURSION_LIMIT
-def verify_slack_signature(
- body: bytes,
- timestamp: str,
- signature: str,
- secret: str,
- max_age_seconds: int = 300,
-) -> bool:
- """Verify Slack request signature."""
- if not secret:
- logger.warning("SLACK_SIGNING_SECRET is not configured — rejecting webhook request")
- return False
- if not timestamp or not signature:
- return False
- try:
- request_timestamp = int(timestamp)
- except ValueError:
- return False
- if abs(int(time.time()) - request_timestamp) > max_age_seconds:
- return False
+ repo_config = config["configurable"].get("repo", {})
+ repo_owner = repo_config.get("owner")
+ repo_name = repo_config.get("name")
+
+ if thread_id is None or not graph_loaded_for_execution(config):
+ logger.info("No thread_id or not for execution, returning agent without sandbox")
+ return create_deep_agent(
+ system_prompt="",
+ tools=[],
+ ).with_config(config)
+
+ github_token, new_encrypted = await resolve_github_token(config, thread_id)
+ config["metadata"]["github_token_encrypted"] = new_encrypted
+
+ sandbox_backend = SANDBOX_BACKENDS.get(thread_id)
+ sandbox_id = await get_sandbox_id_from_metadata(thread_id)
+
+ if sandbox_id == SANDBOX_CREATING and not sandbox_backend:
+ logger.info("Sandbox creation in progress, waiting...")
+ sandbox_id = await _wait_for_sandbox_id(thread_id)
+
+ if sandbox_backend:
+ logger.info("Using cached sandbox backend for thread %s", thread_id)
+ metadata = get_config().get("metadata", {})
+```
+
+This function is important because it defines how Open SWE Tutorial: Asynchronous Cloud Coding Agent Architecture and Migration Playbook implements the patterns covered in this chapter.
+
+### `agent/prompt.py`
+
+The `construct_system_prompt` function in [`agent/prompt.py`](https://github.com/langchain-ai/open-swe/blob/HEAD/agent/prompt.py) handles a key part of this chapter's functionality:
+
+```py
+
+
+def construct_system_prompt(
+ working_dir: str,
+ linear_project_id: str = "",
+ linear_issue_number: str = "",
+ agents_md: str = "",
+) -> str:
+ agents_md_section = ""
+ if agents_md:
+ agents_md_section = (
+ "\nThe following text is pulled from the repository's AGENTS.md file. "
+ "It may contain specific instructions and guidelines for the agent.\n"
+ "<agents_md>\n"
+ f"{agents_md}\n"
+ "</agents_md>\n"
+ )
+ return SYSTEM_PROMPT.format(
+ working_dir=working_dir,
+ linear_project_id=linear_project_id or "<PROJECT_ID>",
+ linear_issue_number=linear_issue_number or "<ISSUE_NUMBER>",
+ agents_md_section=agents_md_section,
+ )
- base_string = f"v0:{timestamp}:{body.decode('utf-8', errors='replace')}"
```
This function is important because it defines how Open SWE Tutorial: Asynchronous Cloud Coding Agent Architecture and Migration Playbook implements the patterns covered in this chapter.
### `agent/utils/slack.py`
-The `verify_slack_signature` function in [`agent/utils/slack.py`](https://github.com/langchain-ai/open-swe/blob/HEAD/agent/utils/slack.py) handles a key part of this chapter's functionality:
+The `replace_bot_mention_with_username` function in [`agent/utils/slack.py`](https://github.com/langchain-ai/open-swe/blob/HEAD/agent/utils/slack.py) handles a key part of this chapter's functionality:
```py
+def replace_bot_mention_with_username(text: str, bot_user_id: str, bot_username: str) -> str:
+ """Replace Slack bot ID mention token with @username."""
+ if not text:
+ return ""
+ if bot_user_id and bot_username:
+ return text.replace(f"<@{bot_user_id}>", f"@{bot_username}")
+ return text
+
+
+def convert_mentions_to_slack_format(text: str) -> str:
+ """Convert @Name(USER_ID) patterns to Slack's <@USER_ID> mention format."""
+ return re.sub(r"@[^()]+\(([A-Z0-9]+)\)", r"<@\1>", text)
+
+
def verify_slack_signature(
body: bytes,
timestamp: str,
@@ -147,61 +192,6 @@ def verify_slack_signature(
try:
request_timestamp = int(timestamp)
except ValueError:
- return False
- if abs(int(time.time()) - request_timestamp) > max_age_seconds:
- return False
-
- base_string = f"v0:{timestamp}:{body.decode('utf-8', errors='replace')}"
- expected = (
- "v0="
- + hmac.new(secret.encode("utf-8"), base_string.encode("utf-8"), hashlib.sha256).hexdigest()
- )
- return hmac.compare_digest(expected, signature)
-
-
-def strip_bot_mention(text: str, bot_user_id: str, bot_username: str = "") -> str:
- """Remove bot mention token from Slack text."""
-```
-
-This function is important because it defines how Open SWE Tutorial: Asynchronous Cloud Coding Agent Architecture and Migration Playbook implements the patterns covered in this chapter.
-
-### `agent/utils/slack.py`
-
-The `strip_bot_mention` function in [`agent/utils/slack.py`](https://github.com/langchain-ai/open-swe/blob/HEAD/agent/utils/slack.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def strip_bot_mention(text: str, bot_user_id: str, bot_username: str = "") -> str:
- """Remove bot mention token from Slack text."""
- if not text:
- return ""
- stripped = text
- if bot_user_id:
- stripped = stripped.replace(f"<@{bot_user_id}>", "")
- if bot_username:
- stripped = stripped.replace(f"@{bot_username}", "")
- return stripped.strip()
-
-
-def select_slack_context_messages(
- messages: list[dict[str, Any]],
- current_message_ts: str,
- bot_user_id: str,
- bot_username: str = "",
-) -> tuple[list[dict[str, Any]], str]:
- """Select context from thread start or previous bot mention."""
- if not messages:
- return [], "thread_start"
-
- current_ts = _parse_ts(current_message_ts)
- ordered = sorted(messages, key=lambda item: _parse_ts(item.get("ts")))
- up_to_current = [item for item in ordered if _parse_ts(item.get("ts")) <= current_ts]
- if not up_to_current:
- up_to_current = ordered
-
- mention_tokens = []
- if bot_user_id:
```
This function is important because it defines how Open SWE Tutorial: Asynchronous Cloud Coding Agent Architecture and Migration Playbook implements the patterns covered in this chapter.
@@ -211,11 +201,11 @@ This function is important because it defines how Open SWE Tutorial: Asynchronou
```mermaid
flowchart TD
- A[build_pr_prompt]
- B[replace_bot_mention_with_username]
- C[verify_slack_signature]
- D[strip_bot_mention]
- E[select_slack_context_messages]
+ A[graph_loaded_for_execution]
+ B[get_agent]
+ C[construct_system_prompt]
+ D[replace_bot_mention_with_username]
+ E[convert_mentions_to_slack_format]
A --> B
B --> C
C --> D
diff --git a/tutorials/open-swe-tutorial/03-development-environment-and-monorepo-setup.md b/tutorials/open-swe-tutorial/03-development-environment-and-monorepo-setup.md
index 836504c2..ccfaa349 100644
--- a/tutorials/open-swe-tutorial/03-development-environment-and-monorepo-setup.md
+++ b/tutorials/open-swe-tutorial/03-development-environment-and-monorepo-setup.md
@@ -38,53 +38,10 @@ You now have a repeatable local setup baseline for maintenance and experimentati
Next: [Chapter 4: Usage Patterns: UI and GitHub Workflows](04-usage-patterns-ui-and-github-workflows.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `agent/utils/slack.py`
-The `get_slack_user_names` function in [`agent/utils/slack.py`](https://github.com/langchain-ai/open-swe/blob/HEAD/agent/utils/slack.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-async def get_slack_user_names(user_ids: list[str]) -> dict[str, str]:
- """Get display names for a set of Slack user IDs."""
- unique_ids = sorted({user_id for user_id in user_ids if isinstance(user_id, str) and user_id})
- if not unique_ids:
- return {}
-
- user_infos = await asyncio.gather(
- *(get_slack_user_info(user_id) for user_id in unique_ids),
- return_exceptions=True,
- )
-
- user_names: dict[str, str] = {}
- for user_id, user_info in zip(unique_ids, user_infos, strict=True):
- if isinstance(user_info, dict):
- user_names[user_id] = _extract_slack_user_name(user_info)
- else:
- user_names[user_id] = user_id
- return user_names
-
-
-async def fetch_slack_thread_messages(channel_id: str, thread_ts: str) -> list[dict[str, Any]]:
- """Fetch all messages for a Slack thread."""
- if not SLACK_BOT_TOKEN:
- return []
-
- messages: list[dict[str, Any]] = []
- cursor: str | None = None
-
- async with httpx.AsyncClient() as http_client:
- while True:
-```
-
-This function is important because it defines how Open SWE Tutorial: Asynchronous Cloud Coding Agent Architecture and Migration Playbook implements the patterns covered in this chapter.
-
-### `agent/utils/slack.py`
-
The `fetch_slack_thread_messages` function in [`agent/utils/slack.py`](https://github.com/langchain-ai/open-swe/blob/HEAD/agent/utils/slack.py) handles a key part of this chapter's functionality:
```py
@@ -143,35 +100,84 @@ async def post_slack_trace_reply(channel_id: str, thread_ts: str, run_id: str) -
This function is important because it defines how Open SWE Tutorial: Asynchronous Cloud Coding Agent Architecture and Migration Playbook implements the patterns covered in this chapter.
-### `agent/prompt.py`
+### `agent/utils/github.py`
-The `construct_system_prompt` function in [`agent/prompt.py`](https://github.com/langchain-ai/open-swe/blob/HEAD/agent/prompt.py) handles a key part of this chapter's functionality:
+The `is_valid_git_repo` function in [`agent/utils/github.py`](https://github.com/langchain-ai/open-swe/blob/HEAD/agent/utils/github.py) handles a key part of this chapter's functionality:
```py
-def construct_system_prompt(
- working_dir: str,
- linear_project_id: str = "",
- linear_issue_number: str = "",
- agents_md: str = "",
-) -> str:
- agents_md_section = ""
- if agents_md:
- agents_md_section = (
- "\nThe following text is pulled from the repository's AGENTS.md file. "
- "It may contain specific instructions and guidelines for the agent.\n"
- "<agents_md>\n"
- f"{agents_md}\n"
- "</agents_md>\n"
- )
- return SYSTEM_PROMPT.format(
- working_dir=working_dir,
- linear_project_id=linear_project_id or "<PROJECT_ID>",
- linear_issue_number=linear_issue_number or "<ISSUE_NUMBER>",
- agents_md_section=agents_md_section,
+def is_valid_git_repo(sandbox_backend: SandboxBackendProtocol, repo_dir: str) -> bool:
+ """Check if directory is a valid git repository."""
+ git_dir = f"{repo_dir}/.git"
+ safe_git_dir = shlex.quote(git_dir)
+ result = sandbox_backend.execute(f"test -d {safe_git_dir} && echo exists")
+ return result.exit_code == 0 and "exists" in result.output
+
+
+def remove_directory(sandbox_backend: SandboxBackendProtocol, repo_dir: str) -> bool:
+ """Remove a directory and all its contents."""
+ safe_repo_dir = shlex.quote(repo_dir)
+ result = sandbox_backend.execute(f"rm -rf {safe_repo_dir}")
+ return result.exit_code == 0
+
+
+def git_has_uncommitted_changes(sandbox_backend: SandboxBackendProtocol, repo_dir: str) -> bool:
+ """Check whether the repo has uncommitted changes."""
+ result = _run_git(sandbox_backend, repo_dir, "git status --porcelain")
+ return result.exit_code == 0 and bool(result.output.strip())
+
+
+def git_fetch_origin(sandbox_backend: SandboxBackendProtocol, repo_dir: str) -> ExecuteResponse:
+ """Fetch latest from origin (best-effort)."""
+ return _run_git(sandbox_backend, repo_dir, "git fetch origin 2>/dev/null || true")
+
+
+def git_has_unpushed_commits(sandbox_backend: SandboxBackendProtocol, repo_dir: str) -> bool:
+ """Check whether there are commits not pushed to upstream."""
+ git_log_cmd = (
+ "git log --oneline @{upstream}..HEAD 2>/dev/null "
+```
+
+This function is important because it defines how Open SWE Tutorial: Asynchronous Cloud Coding Agent Architecture and Migration Playbook implements the patterns covered in this chapter.
+
+### `agent/utils/github.py`
+
+The `remove_directory` function in [`agent/utils/github.py`](https://github.com/langchain-ai/open-swe/blob/HEAD/agent/utils/github.py) handles a key part of this chapter's functionality:
+
+```py
+
+
+def remove_directory(sandbox_backend: SandboxBackendProtocol, repo_dir: str) -> bool:
+ """Remove a directory and all its contents."""
+ safe_repo_dir = shlex.quote(repo_dir)
+ result = sandbox_backend.execute(f"rm -rf {safe_repo_dir}")
+ return result.exit_code == 0
+
+
+def git_has_uncommitted_changes(sandbox_backend: SandboxBackendProtocol, repo_dir: str) -> bool:
+ """Check whether the repo has uncommitted changes."""
+ result = _run_git(sandbox_backend, repo_dir, "git status --porcelain")
+ return result.exit_code == 0 and bool(result.output.strip())
+
+
+def git_fetch_origin(sandbox_backend: SandboxBackendProtocol, repo_dir: str) -> ExecuteResponse:
+ """Fetch latest from origin (best-effort)."""
+ return _run_git(sandbox_backend, repo_dir, "git fetch origin 2>/dev/null || true")
+
+
+def git_has_unpushed_commits(sandbox_backend: SandboxBackendProtocol, repo_dir: str) -> bool:
+ """Check whether there are commits not pushed to upstream."""
+ git_log_cmd = (
+ "git log --oneline @{upstream}..HEAD 2>/dev/null "
+ "|| git log --oneline origin/HEAD..HEAD 2>/dev/null || echo ''"
)
+ result = _run_git(sandbox_backend, repo_dir, git_log_cmd)
+ return result.exit_code == 0 and bool(result.output.strip())
+
+def git_current_branch(sandbox_backend: SandboxBackendProtocol, repo_dir: str) -> str:
+ """Get the current git branch name."""
```
This function is important because it defines how Open SWE Tutorial: Asynchronous Cloud Coding Agent Architecture and Migration Playbook implements the patterns covered in this chapter.
@@ -181,11 +187,11 @@ This function is important because it defines how Open SWE Tutorial: Asynchronou
```mermaid
flowchart TD
- A[get_slack_user_names]
- B[fetch_slack_thread_messages]
- C[post_slack_trace_reply]
- D[construct_system_prompt]
- E[EncryptionKeyMissingError]
+ A[fetch_slack_thread_messages]
+ B[post_slack_trace_reply]
+ C[is_valid_git_repo]
+ D[remove_directory]
+ E[git_has_uncommitted_changes]
A --> B
B --> C
C --> D
diff --git a/tutorials/open-swe-tutorial/04-usage-patterns-ui-and-github-workflows.md b/tutorials/open-swe-tutorial/04-usage-patterns-ui-and-github-workflows.md
index b5dca8e8..e4185c4e 100644
--- a/tutorials/open-swe-tutorial/04-usage-patterns-ui-and-github-workflows.md
+++ b/tutorials/open-swe-tutorial/04-usage-patterns-ui-and-github-workflows.md
@@ -38,170 +38,168 @@ You now understand how Open SWE connects user requests to async implementation w
Next: [Chapter 5: Planning Control and Human-in-the-Loop](05-planning-control-and-human-in-the-loop.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `agent/utils/auth.py`
+### `agent/utils/github.py`
-The `get_secret_key_for_user` function in [`agent/utils/auth.py`](https://github.com/langchain-ai/open-swe/blob/HEAD/agent/utils/auth.py) handles a key part of this chapter's functionality:
+The `setup_git_credentials` function in [`agent/utils/github.py`](https://github.com/langchain-ai/open-swe/blob/HEAD/agent/utils/github.py) handles a key part of this chapter's functionality:
```py
-def get_secret_key_for_user(
- user_id: str, tenant_id: str, expiration_seconds: int = 300
-) -> tuple[str, Literal["service", "api_key"]]:
- """Create a short-lived service JWT for authenticating as a specific user."""
- if not X_SERVICE_AUTH_JWT_SECRET:
- msg = "X_SERVICE_AUTH_JWT_SECRET is not configured. Cannot generate service keys."
- raise ValueError(msg)
-
- payload = {
- "sub": "unspecified",
- "exp": datetime.now(UTC) + timedelta(seconds=expiration_seconds),
- "user_id": user_id,
- "tenant_id": tenant_id,
- }
- return jwt.encode(payload, X_SERVICE_AUTH_JWT_SECRET, algorithm="HS256"), "service"
-
-
-async def get_ls_user_id_from_email(email: str) -> dict[str, str | None]:
- """Get the LangSmith user ID and tenant ID from a user's email."""
- if not LANGSMITH_API_KEY:
- logger.warning("LangSmith API key not configured; cannot resolve LS user for %s", email)
- return {"ls_user_id": None, "tenant_id": None}
-
- url = f"{LANGSMITH_API_URL}/api/v1/workspaces/current/members/active"
-
- async with httpx.AsyncClient() as client:
- try:
- response = await client.get(
- url,
- headers={"X-API-Key": LANGSMITH_API_KEY},
-```
+def setup_git_credentials(sandbox_backend: SandboxBackendProtocol, github_token: str) -> None:
+ """Write GitHub credentials to a temporary file using the sandbox write API.
-This function is important because it defines how Open SWE Tutorial: Asynchronous Cloud Coding Agent Architecture and Migration Playbook implements the patterns covered in this chapter.
+ The write API sends content in the HTTP body (not via a shell command),
+ so the token never appears in shell history or process listings.
+ """
+ sandbox_backend.write(_CRED_FILE_PATH, f"https://git:{github_token}@github.com\n")
+ sandbox_backend.execute(f"chmod 600 {_CRED_FILE_PATH}")
-### `agent/utils/auth.py`
-The `get_ls_user_id_from_email` function in [`agent/utils/auth.py`](https://github.com/langchain-ai/open-swe/blob/HEAD/agent/utils/auth.py) handles a key part of this chapter's functionality:
+def cleanup_git_credentials(sandbox_backend: SandboxBackendProtocol) -> None:
+ """Remove the temporary credentials file."""
+ sandbox_backend.execute(f"rm -f {_CRED_FILE_PATH}")
-```py
+
+def _git_with_credentials(
+ sandbox_backend: SandboxBackendProtocol,
+ repo_dir: str,
+ command: str,
+) -> ExecuteResponse:
+ """Run a git command using the temporary credential file."""
+ cred_helper = shlex.quote(f"store --file={_CRED_FILE_PATH}")
+ return _run_git(sandbox_backend, repo_dir, f"git -c credential.helper={cred_helper} {command}")
-async def get_ls_user_id_from_email(email: str) -> dict[str, str | None]:
- """Get the LangSmith user ID and tenant ID from a user's email."""
- if not LANGSMITH_API_KEY:
- logger.warning("LangSmith API key not configured; cannot resolve LS user for %s", email)
- return {"ls_user_id": None, "tenant_id": None}
-
- url = f"{LANGSMITH_API_URL}/api/v1/workspaces/current/members/active"
-
- async with httpx.AsyncClient() as client:
- try:
- response = await client.get(
- url,
- headers={"X-API-Key": LANGSMITH_API_KEY},
- params={"emails": [email]},
- )
- response.raise_for_status()
- members = response.json()
-
- if members and len(members) > 0:
- member = members[0]
- return {
- "ls_user_id": member.get("ls_user_id"),
- "tenant_id": member.get("tenant_id"),
- }
- except Exception as e:
- logger.exception("Error getting LangSmith user info for email: %s", e)
- return {"ls_user_id": None, "tenant_id": None}
-
-
-async def get_github_token_for_user(ls_user_id: str, tenant_id: str) -> dict[str, Any]:
+def git_push(
+ sandbox_backend: SandboxBackendProtocol,
+ repo_dir: str,
+ branch: str,
+ github_token: str | None = None,
```
This function is important because it defines how Open SWE Tutorial: Asynchronous Cloud Coding Agent Architecture and Migration Playbook implements the patterns covered in this chapter.
-### `agent/utils/auth.py`
+### `agent/utils/github.py`
-The `get_github_token_for_user` function in [`agent/utils/auth.py`](https://github.com/langchain-ai/open-swe/blob/HEAD/agent/utils/auth.py) handles a key part of this chapter's functionality:
+The `cleanup_git_credentials` function in [`agent/utils/github.py`](https://github.com/langchain-ai/open-swe/blob/HEAD/agent/utils/github.py) handles a key part of this chapter's functionality:
```py
-async def get_github_token_for_user(ls_user_id: str, tenant_id: str) -> dict[str, Any]:
- """Get GitHub OAuth token for a user via LangSmith agent auth."""
- if not GITHUB_OAUTH_PROVIDER_ID:
- logger.error("GitHub auth failed: GITHUB_OAUTH_PROVIDER_ID is not configured")
- return {"error": "GITHUB_OAUTH_PROVIDER_ID not configured"}
-
+def cleanup_git_credentials(sandbox_backend: SandboxBackendProtocol) -> None:
+ """Remove the temporary credentials file."""
+ sandbox_backend.execute(f"rm -f {_CRED_FILE_PATH}")
+
+
+def _git_with_credentials(
+ sandbox_backend: SandboxBackendProtocol,
+ repo_dir: str,
+ command: str,
+) -> ExecuteResponse:
+ """Run a git command using the temporary credential file."""
+ cred_helper = shlex.quote(f"store --file={_CRED_FILE_PATH}")
+ return _run_git(sandbox_backend, repo_dir, f"git -c credential.helper={cred_helper} {command}")
+
+
+def git_push(
+ sandbox_backend: SandboxBackendProtocol,
+ repo_dir: str,
+ branch: str,
+ github_token: str | None = None,
+) -> ExecuteResponse:
+ """Push the branch to origin, using a token if needed."""
+ safe_branch = shlex.quote(branch)
+ if not github_token:
+ return _run_git(sandbox_backend, repo_dir, f"git push origin {safe_branch}")
+ setup_git_credentials(sandbox_backend, github_token)
try:
- headers = {
- "X-Tenant-Id": tenant_id,
- "X-User-Id": ls_user_id,
- }
- secret_key, secret_type = get_secret_key_for_user(ls_user_id, tenant_id)
- if secret_type == "api_key":
- headers["X-API-Key"] = secret_key
- else:
- headers["X-Service-Key"] = secret_key
-
- payload = {
- "provider": GITHUB_OAUTH_PROVIDER_ID,
- "scopes": ["repo"],
- "user_id": ls_user_id,
- "ls_user_id": ls_user_id,
- }
-
- async with httpx.AsyncClient() as client:
- response = await client.post(
- f"{LANGSMITH_HOST_API_URL}/v2/auth/authenticate",
- json=payload,
- headers=headers,
- )
+ return _git_with_credentials(sandbox_backend, repo_dir, f"push origin {safe_branch}")
+ finally:
+ cleanup_git_credentials(sandbox_backend)
```
This function is important because it defines how Open SWE Tutorial: Asynchronous Cloud Coding Agent Architecture and Migration Playbook implements the patterns covered in this chapter.
-### `agent/utils/auth.py`
+### `agent/utils/github.py`
-The `resolve_github_token_from_email` function in [`agent/utils/auth.py`](https://github.com/langchain-ai/open-swe/blob/HEAD/agent/utils/auth.py) handles a key part of this chapter's functionality:
+The `git_push` function in [`agent/utils/github.py`](https://github.com/langchain-ai/open-swe/blob/HEAD/agent/utils/github.py) handles a key part of this chapter's functionality:
```py
-async def resolve_github_token_from_email(email: str) -> dict[str, Any]:
- """Resolve a GitHub token for a user identified by email.
+def git_push(
+ sandbox_backend: SandboxBackendProtocol,
+ repo_dir: str,
+ branch: str,
+ github_token: str | None = None,
+) -> ExecuteResponse:
+ """Push the branch to origin, using a token if needed."""
+ safe_branch = shlex.quote(branch)
+ if not github_token:
+ return _run_git(sandbox_backend, repo_dir, f"git push origin {safe_branch}")
+ setup_git_credentials(sandbox_backend, github_token)
+ try:
+ return _git_with_credentials(sandbox_backend, repo_dir, f"push origin {safe_branch}")
+ finally:
+ cleanup_git_credentials(sandbox_backend)
+
+
+def git_pull_branch(
+ sandbox_backend: SandboxBackendProtocol,
+ repo_dir: str,
+ branch: str,
+ github_token: str | None = None,
+) -> ExecuteResponse:
+ """Pull a specific branch from origin, using a token if needed."""
+ safe_branch = shlex.quote(branch)
+ if not github_token:
+ return _run_git(sandbox_backend, repo_dir, f"git pull origin {safe_branch}")
+ setup_git_credentials(sandbox_backend, github_token)
+ try:
+ return _git_with_credentials(sandbox_backend, repo_dir, f"pull origin {safe_branch}")
+```
- Chains get_ls_user_id_from_email -> get_github_token_for_user.
+This function is important because it defines how Open SWE Tutorial: Asynchronous Cloud Coding Agent Architecture and Migration Playbook implements the patterns covered in this chapter.
- Returns:
- Dict with one of:
- - {"token": str} on success
- - {"auth_url": str} if user needs to authenticate via OAuth
- - {"error": str} on failure; error="no_ls_user" if email not in LangSmith
- """
- user_info = await get_ls_user_id_from_email(email)
- ls_user_id = user_info.get("ls_user_id")
- tenant_id = user_info.get("tenant_id")
+### `agent/utils/github.py`
- if not ls_user_id or not tenant_id:
- logger.warning(
- "No LangSmith user found for email %s (ls_user_id=%s, tenant_id=%s)",
- email,
- ls_user_id,
- tenant_id,
- )
- return {"error": "no_ls_user", "email": email}
+The `git_pull_branch` function in [`agent/utils/github.py`](https://github.com/langchain-ai/open-swe/blob/HEAD/agent/utils/github.py) handles a key part of this chapter's functionality:
- auth_result = await get_github_token_for_user(ls_user_id, tenant_id)
- return auth_result
+```py
-async def leave_failure_comment(
- source: str,
+def git_pull_branch(
+ sandbox_backend: SandboxBackendProtocol,
+ repo_dir: str,
+ branch: str,
+ github_token: str | None = None,
+) -> ExecuteResponse:
+ """Pull a specific branch from origin, using a token if needed."""
+ safe_branch = shlex.quote(branch)
+ if not github_token:
+ return _run_git(sandbox_backend, repo_dir, f"git pull origin {safe_branch}")
+ setup_git_credentials(sandbox_backend, github_token)
+ try:
+ return _git_with_credentials(sandbox_backend, repo_dir, f"pull origin {safe_branch}")
+ finally:
+ cleanup_git_credentials(sandbox_backend)
+
+
+async def create_github_pr(
+ repo_owner: str,
+ repo_name: str,
+ github_token: str,
+ title: str,
+ head_branch: str,
+ base_branch: str,
+ body: str,
+) -> tuple[str | None, int | None, bool]:
+ """Create a draft GitHub pull request via the API.
+
+ Args:
+ repo_owner: Repository owner (e.g., "langchain-ai")
```
This function is important because it defines how Open SWE Tutorial: Asynchronous Cloud Coding Agent Architecture and Migration Playbook implements the patterns covered in this chapter.
@@ -211,11 +209,11 @@ This function is important because it defines how Open SWE Tutorial: Asynchronou
```mermaid
flowchart TD
- A[get_secret_key_for_user]
- B[get_ls_user_id_from_email]
- C[get_github_token_for_user]
- D[resolve_github_token_from_email]
- E[leave_failure_comment]
+ A[setup_git_credentials]
+ B[cleanup_git_credentials]
+ C[git_push]
+ D[git_pull_branch]
+ E[create_github_pr]
A --> B
B --> C
C --> D
diff --git a/tutorials/open-swe-tutorial/05-planning-control-and-human-in-the-loop.md b/tutorials/open-swe-tutorial/05-planning-control-and-human-in-the-loop.md
index 56167112..adeec01f 100644
--- a/tutorials/open-swe-tutorial/05-planning-control-and-human-in-the-loop.md
+++ b/tutorials/open-swe-tutorial/05-planning-control-and-human-in-the-loop.md
@@ -38,170 +38,168 @@ You now have a framework for balancing automation speed with human oversight.
Next: [Chapter 6: Security, Auth, and Operational Constraints](06-security-auth-and-operational-constraints.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `agent/integrations/langsmith.py`
+### `agent/tools/github_review.py`
-The `LangSmithProvider` class in [`agent/integrations/langsmith.py`](https://github.com/langchain-ai/open-swe/blob/HEAD/agent/integrations/langsmith.py) handles a key part of this chapter's functionality:
+The `dismiss_pr_review` function in [`agent/tools/github_review.py`](https://github.com/langchain-ai/open-swe/blob/HEAD/agent/tools/github_review.py) handles a key part of this chapter's functionality:
```py
- """Create or connect to a LangSmith sandbox without automatic cleanup.
- This function directly uses the LangSmithProvider to create/connect to sandboxes
- without the context manager cleanup, allowing sandboxes to persist across
- multiple agent invocations.
+
+def dismiss_pr_review(
+ pull_number: int,
+ review_id: int,
+ message: str,
+) -> dict[str, Any]:
+ """Dismiss a review on a pull request.
Args:
- sandbox_id: Optional existing sandbox ID to connect to.
- If None, creates a new sandbox.
+ pull_number: The PR number.
+ review_id: The ID of the review to dismiss.
+ message: A message explaining why the review is being dismissed.
Returns:
- SandboxBackendProtocol instance
+ Dictionary with success status and the dismissed review data.
"""
- api_key = _get_langsmith_api_key()
- template_name, template_image = _get_sandbox_template_config()
+ repo_config = _get_repo_config()
+ if not repo_config:
+ return {"success": False, "error": "No repo config found"}
- provider = LangSmithProvider(api_key=api_key)
- backend = provider.get_or_create(
- sandbox_id=sandbox_id,
- template=template_name,
- template_image=template_image,
- )
- _update_thread_sandbox_metadata(backend.id)
- return backend
+ token = asyncio.run(_get_token())
+ if not token:
+ return {"success": False, "error": "Failed to get GitHub App installation token"}
+ url = f"{_repo_url(repo_config)}/pulls/{pull_number}/reviews/{review_id}/dismissals"
-def _update_thread_sandbox_metadata(sandbox_id: str) -> None:
- """Update thread metadata with sandbox_id."""
- try:
- import asyncio
-
- from langgraph.config import get_config
+ async def _dismiss() -> dict[str, Any]:
+ async with httpx.AsyncClient() as client:
+ response = await client.put(
+ url, headers=_github_headers(token), json={"message": message}
+ )
```
-This class is important because it defines how Open SWE Tutorial: Asynchronous Cloud Coding Agent Architecture and Migration Playbook implements the patterns covered in this chapter.
+This function is important because it defines how Open SWE Tutorial: Asynchronous Cloud Coding Agent Architecture and Migration Playbook implements the patterns covered in this chapter.
-### `agent/integrations/langsmith.py`
+### `agent/tools/github_review.py`
-The `create_langsmith_sandbox` function in [`agent/integrations/langsmith.py`](https://github.com/langchain-ai/open-swe/blob/HEAD/agent/integrations/langsmith.py) handles a key part of this chapter's functionality:
+The `submit_pr_review` function in [`agent/tools/github_review.py`](https://github.com/langchain-ai/open-swe/blob/HEAD/agent/tools/github_review.py) handles a key part of this chapter's functionality:
```py
-def create_langsmith_sandbox(
- sandbox_id: str | None = None,
-) -> SandboxBackendProtocol:
- """Create or connect to a LangSmith sandbox without automatic cleanup.
+def submit_pr_review(
+ pull_number: int,
+ review_id: int,
+ body: str | None = None,
+ event: str = "COMMENT",
+) -> dict[str, Any]:
+ """Submit a pending review on a pull request.
- This function directly uses the LangSmithProvider to create/connect to sandboxes
- without the context manager cleanup, allowing sandboxes to persist across
- multiple agent invocations.
+ Use this if a review was created without an event (pending state) and needs to be submitted.
Args:
- sandbox_id: Optional existing sandbox ID to connect to.
- If None, creates a new sandbox.
+ pull_number: The PR number.
+ review_id: The ID of the pending review to submit.
+ body: Optional body text for the review submission.
+ event: The review action - one of APPROVE, REQUEST_CHANGES, or COMMENT.
Returns:
- SandboxBackendProtocol instance
+ Dictionary with success status and the submitted review data.
"""
- api_key = _get_langsmith_api_key()
- template_name, template_image = _get_sandbox_template_config()
+ repo_config = _get_repo_config()
+ if not repo_config:
+ return {"success": False, "error": "No repo config found"}
- provider = LangSmithProvider(api_key=api_key)
- backend = provider.get_or_create(
- sandbox_id=sandbox_id,
- template=template_name,
- template_image=template_image,
- )
- _update_thread_sandbox_metadata(backend.id)
- return backend
+ token = asyncio.run(_get_token())
+ if not token:
+ return {"success": False, "error": "Failed to get GitHub App installation token"}
-
-def _update_thread_sandbox_metadata(sandbox_id: str) -> None:
+ url = f"{_repo_url(repo_config)}/pulls/{pull_number}/reviews/{review_id}/events"
+ payload: dict[str, Any] = {"event": event}
+ if body is not None:
```
This function is important because it defines how Open SWE Tutorial: Asynchronous Cloud Coding Agent Architecture and Migration Playbook implements the patterns covered in this chapter.
-### `agent/utils/github.py`
+### `agent/tools/github_review.py`
-The `is_valid_git_repo` function in [`agent/utils/github.py`](https://github.com/langchain-ai/open-swe/blob/HEAD/agent/utils/github.py) handles a key part of this chapter's functionality:
+The `list_pr_review_comments` function in [`agent/tools/github_review.py`](https://github.com/langchain-ai/open-swe/blob/HEAD/agent/tools/github_review.py) handles a key part of this chapter's functionality:
```py
-def is_valid_git_repo(sandbox_backend: SandboxBackendProtocol, repo_dir: str) -> bool:
- """Check if directory is a valid git repository."""
- git_dir = f"{repo_dir}/.git"
- safe_git_dir = shlex.quote(git_dir)
- result = sandbox_backend.execute(f"test -d {safe_git_dir} && echo exists")
- return result.exit_code == 0 and "exists" in result.output
-
-
-def remove_directory(sandbox_backend: SandboxBackendProtocol, repo_dir: str) -> bool:
- """Remove a directory and all its contents."""
- safe_repo_dir = shlex.quote(repo_dir)
- result = sandbox_backend.execute(f"rm -rf {safe_repo_dir}")
- return result.exit_code == 0
-
-
-def git_has_uncommitted_changes(sandbox_backend: SandboxBackendProtocol, repo_dir: str) -> bool:
- """Check whether the repo has uncommitted changes."""
- result = _run_git(sandbox_backend, repo_dir, "git status --porcelain")
- return result.exit_code == 0 and bool(result.output.strip())
-
-
-def git_fetch_origin(sandbox_backend: SandboxBackendProtocol, repo_dir: str) -> ExecuteResponse:
- """Fetch latest from origin (best-effort)."""
- return _run_git(sandbox_backend, repo_dir, "git fetch origin 2>/dev/null || true")
+def list_pr_review_comments(
+ pull_number: int,
+ review_id: int | None = None,
+) -> dict[str, Any]:
+ """List comments on a pull request review.
+ Args:
+ pull_number: The PR number.
+ review_id: If provided, list comments for a specific review.
+ If not provided, list all review comments on the PR.
-def git_has_unpushed_commits(sandbox_backend: SandboxBackendProtocol, repo_dir: str) -> bool:
- """Check whether there are commits not pushed to upstream."""
- git_log_cmd = (
- "git log --oneline @{upstream}..HEAD 2>/dev/null "
+ Returns:
+ Dictionary with success status and the list of review comments.
+ """
+ repo_config = _get_repo_config()
+ if not repo_config:
+ return {"success": False, "error": "No repo config found"}
+
+ token = asyncio.run(_get_token())
+ if not token:
+ return {"success": False, "error": "Failed to get GitHub App installation token"}
+
+ if review_id is not None:
+ url = f"{_repo_url(repo_config)}/pulls/{pull_number}/reviews/{review_id}/comments"
+ else:
+ url = f"{_repo_url(repo_config)}/pulls/{pull_number}/comments"
+
+ async def _fetch() -> dict[str, Any]:
+ async with httpx.AsyncClient() as client:
+ response = await client.get(url, headers=_github_headers(token))
```
This function is important because it defines how Open SWE Tutorial: Asynchronous Cloud Coding Agent Architecture and Migration Playbook implements the patterns covered in this chapter.
-### `agent/utils/github.py`
+### `agent/utils/auth.py`
-The `remove_directory` function in [`agent/utils/github.py`](https://github.com/langchain-ai/open-swe/blob/HEAD/agent/utils/github.py) handles a key part of this chapter's functionality:
+The `is_bot_token_only_mode` function in [`agent/utils/auth.py`](https://github.com/langchain-ai/open-swe/blob/HEAD/agent/utils/auth.py) handles a key part of this chapter's functionality:
```py
-def remove_directory(sandbox_backend: SandboxBackendProtocol, repo_dir: str) -> bool:
- """Remove a directory and all its contents."""
- safe_repo_dir = shlex.quote(repo_dir)
- result = sandbox_backend.execute(f"rm -rf {safe_repo_dir}")
- return result.exit_code == 0
+def is_bot_token_only_mode() -> bool:
+ """Check if we're in bot-token-only mode.
+
+ This is the case when LANGSMITH_API_KEY_PROD is set (deployed) but neither
+ X_SERVICE_AUTH_JWT_SECRET nor USER_ID_API_KEY_MAP is configured, meaning we
+ can't resolve per-user GitHub OAuth tokens. In this mode the GitHub App
+ installation token is used for all git operations instead.
+ """
+ return bool(LANGSMITH_API_KEY and not X_SERVICE_AUTH_JWT_SECRET and not USER_ID_API_KEY_MAP)
-def git_has_uncommitted_changes(sandbox_backend: SandboxBackendProtocol, repo_dir: str) -> bool:
- """Check whether the repo has uncommitted changes."""
- result = _run_git(sandbox_backend, repo_dir, "git status --porcelain")
- return result.exit_code == 0 and bool(result.output.strip())
+def _retry_instruction(source: str) -> str:
+ if source == "slack":
+ return "Once authenticated, mention me again in this Slack thread to retry."
+ return "Once authenticated, reply to this issue mentioning @openswe to retry."
-def git_fetch_origin(sandbox_backend: SandboxBackendProtocol, repo_dir: str) -> ExecuteResponse:
- """Fetch latest from origin (best-effort)."""
- return _run_git(sandbox_backend, repo_dir, "git fetch origin 2>/dev/null || true")
+def _source_account_label(source: str) -> str:
+ if source == "slack":
+ return "Slack"
+ return "Linear"
-def git_has_unpushed_commits(sandbox_backend: SandboxBackendProtocol, repo_dir: str) -> bool:
- """Check whether there are commits not pushed to upstream."""
- git_log_cmd = (
- "git log --oneline @{upstream}..HEAD 2>/dev/null "
- "|| git log --oneline origin/HEAD..HEAD 2>/dev/null || echo ''"
- )
- result = _run_git(sandbox_backend, repo_dir, git_log_cmd)
- return result.exit_code == 0 and bool(result.output.strip())
+def _auth_link_text(source: str, auth_url: str) -> str:
+ if source == "slack":
+ return auth_url
+ return f"[Authenticate with GitHub]({auth_url})"
-def git_current_branch(sandbox_backend: SandboxBackendProtocol, repo_dir: str) -> str:
- """Get the current git branch name."""
+def _work_item_label(source: str) -> str:
```
This function is important because it defines how Open SWE Tutorial: Asynchronous Cloud Coding Agent Architecture and Migration Playbook implements the patterns covered in this chapter.
@@ -211,11 +209,11 @@ This function is important because it defines how Open SWE Tutorial: Asynchronou
```mermaid
flowchart TD
- A[LangSmithProvider]
- B[create_langsmith_sandbox]
- C[is_valid_git_repo]
- D[remove_directory]
- E[git_has_uncommitted_changes]
+ A[dismiss_pr_review]
+ B[submit_pr_review]
+ C[list_pr_review_comments]
+ D[is_bot_token_only_mode]
+ E[get_secret_key_for_user]
A --> B
B --> C
C --> D
diff --git a/tutorials/open-swe-tutorial/06-security-auth-and-operational-constraints.md b/tutorials/open-swe-tutorial/06-security-auth-and-operational-constraints.md
index 7a034845..595c6317 100644
--- a/tutorials/open-swe-tutorial/06-security-auth-and-operational-constraints.md
+++ b/tutorials/open-swe-tutorial/06-security-auth-and-operational-constraints.md
@@ -39,170 +39,168 @@ You now have a practical security model for operating or auditing Open SWE forks
Next: [Chapter 7: Fork Maintenance and Migration Strategy](07-fork-maintenance-and-migration-strategy.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `agent/utils/github.py`
+### `agent/utils/github_comments.py`
-The `git_add_all` function in [`agent/utils/github.py`](https://github.com/langchain-ai/open-swe/blob/HEAD/agent/utils/github.py) handles a key part of this chapter's functionality:
+The `get_thread_id_from_branch` function in [`agent/utils/github_comments.py`](https://github.com/langchain-ai/open-swe/blob/HEAD/agent/utils/github_comments.py) handles a key part of this chapter's functionality:
```py
-def git_add_all(sandbox_backend: SandboxBackendProtocol, repo_dir: str) -> ExecuteResponse:
- """Stage all changes."""
- return _run_git(sandbox_backend, repo_dir, "git add -A")
-
-
-def git_commit(
- sandbox_backend: SandboxBackendProtocol, repo_dir: str, message: str
-) -> ExecuteResponse:
- """Commit staged changes with the given message."""
- safe_message = shlex.quote(message)
- return _run_git(sandbox_backend, repo_dir, f"git commit -m {safe_message}")
-
-
-def git_get_remote_url(sandbox_backend: SandboxBackendProtocol, repo_dir: str) -> str | None:
- """Get the origin remote URL."""
- result = _run_git(sandbox_backend, repo_dir, "git remote get-url origin")
- if result.exit_code != 0:
- return None
- return result.output.strip()
-
-
-_CRED_FILE_PATH = "/tmp/.git-credentials"
-
-
-def setup_git_credentials(sandbox_backend: SandboxBackendProtocol, github_token: str) -> None:
- """Write GitHub credentials to a temporary file using the sandbox write API.
-
- The write API sends content in the HTTP body (not via a shell command),
- so the token never appears in shell history or process listings.
- """
+def get_thread_id_from_branch(branch_name: str) -> str | None:
+ match = re.search(
+ r"[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}",
+ branch_name,
+ re.IGNORECASE,
+ )
+ return match.group(0) if match else None
+
+
+def sanitize_github_comment_body(body: str) -> str:
+ """Strip reserved trust wrapper tags from raw GitHub comment bodies."""
+ sanitized = body.replace(
+ UNTRUSTED_GITHUB_COMMENT_OPEN_TAG,
+ _SANITIZED_UNTRUSTED_GITHUB_COMMENT_OPEN_TAG,
+ ).replace(
+ UNTRUSTED_GITHUB_COMMENT_CLOSE_TAG,
+ _SANITIZED_UNTRUSTED_GITHUB_COMMENT_CLOSE_TAG,
+ )
+ if sanitized != body:
+ logger.warning("Sanitized reserved untrusted-comment tags from GitHub comment body")
+ return sanitized
+
+
+def format_github_comment_body_for_prompt(author: str, body: str) -> str:
+ """Format a GitHub comment body for prompt inclusion."""
+ sanitized_body = sanitize_github_comment_body(body)
+ if author in GITHUB_USER_EMAIL_MAP:
+ return sanitized_body
+
+ return (
```
This function is important because it defines how Open SWE Tutorial: Asynchronous Cloud Coding Agent Architecture and Migration Playbook implements the patterns covered in this chapter.
-### `agent/utils/github.py`
+### `agent/utils/github_comments.py`
-The `git_commit` function in [`agent/utils/github.py`](https://github.com/langchain-ai/open-swe/blob/HEAD/agent/utils/github.py) handles a key part of this chapter's functionality:
+The `sanitize_github_comment_body` function in [`agent/utils/github_comments.py`](https://github.com/langchain-ai/open-swe/blob/HEAD/agent/utils/github_comments.py) handles a key part of this chapter's functionality:
```py
-def git_commit(
- sandbox_backend: SandboxBackendProtocol, repo_dir: str, message: str
-) -> ExecuteResponse:
- """Commit staged changes with the given message."""
- safe_message = shlex.quote(message)
- return _run_git(sandbox_backend, repo_dir, f"git commit -m {safe_message}")
-
-
-def git_get_remote_url(sandbox_backend: SandboxBackendProtocol, repo_dir: str) -> str | None:
- """Get the origin remote URL."""
- result = _run_git(sandbox_backend, repo_dir, "git remote get-url origin")
- if result.exit_code != 0:
- return None
- return result.output.strip()
-
-
-_CRED_FILE_PATH = "/tmp/.git-credentials"
-
-
-def setup_git_credentials(sandbox_backend: SandboxBackendProtocol, github_token: str) -> None:
- """Write GitHub credentials to a temporary file using the sandbox write API.
-
- The write API sends content in the HTTP body (not via a shell command),
- so the token never appears in shell history or process listings.
- """
- sandbox_backend.write(_CRED_FILE_PATH, f"https://git:{github_token}@github.com\n")
- sandbox_backend.execute(f"chmod 600 {_CRED_FILE_PATH}")
-
-
-def cleanup_git_credentials(sandbox_backend: SandboxBackendProtocol) -> None:
+def sanitize_github_comment_body(body: str) -> str:
+ """Strip reserved trust wrapper tags from raw GitHub comment bodies."""
+ sanitized = body.replace(
+ UNTRUSTED_GITHUB_COMMENT_OPEN_TAG,
+ _SANITIZED_UNTRUSTED_GITHUB_COMMENT_OPEN_TAG,
+ ).replace(
+ UNTRUSTED_GITHUB_COMMENT_CLOSE_TAG,
+ _SANITIZED_UNTRUSTED_GITHUB_COMMENT_CLOSE_TAG,
+ )
+ if sanitized != body:
+ logger.warning("Sanitized reserved untrusted-comment tags from GitHub comment body")
+ return sanitized
+
+
+def format_github_comment_body_for_prompt(author: str, body: str) -> str:
+ """Format a GitHub comment body for prompt inclusion."""
+ sanitized_body = sanitize_github_comment_body(body)
+ if author in GITHUB_USER_EMAIL_MAP:
+ return sanitized_body
+
+ return (
+ f"{UNTRUSTED_GITHUB_COMMENT_OPEN_TAG}\n"
+ f"{sanitized_body}\n"
+ f"{UNTRUSTED_GITHUB_COMMENT_CLOSE_TAG}"
+ )
+
+
+async def react_to_github_comment(
+ repo_config: dict[str, str],
+ comment_id: int,
```
This function is important because it defines how Open SWE Tutorial: Asynchronous Cloud Coding Agent Architecture and Migration Playbook implements the patterns covered in this chapter.
-### `agent/utils/github.py`
+### `agent/utils/github_comments.py`
-The `git_get_remote_url` function in [`agent/utils/github.py`](https://github.com/langchain-ai/open-swe/blob/HEAD/agent/utils/github.py) handles a key part of this chapter's functionality:
+The `format_github_comment_body_for_prompt` function in [`agent/utils/github_comments.py`](https://github.com/langchain-ai/open-swe/blob/HEAD/agent/utils/github_comments.py) handles a key part of this chapter's functionality:
```py
-def git_get_remote_url(sandbox_backend: SandboxBackendProtocol, repo_dir: str) -> str | None:
- """Get the origin remote URL."""
- result = _run_git(sandbox_backend, repo_dir, "git remote get-url origin")
- if result.exit_code != 0:
- return None
- return result.output.strip()
-
-
-_CRED_FILE_PATH = "/tmp/.git-credentials"
-
-
-def setup_git_credentials(sandbox_backend: SandboxBackendProtocol, github_token: str) -> None:
- """Write GitHub credentials to a temporary file using the sandbox write API.
-
- The write API sends content in the HTTP body (not via a shell command),
- so the token never appears in shell history or process listings.
- """
- sandbox_backend.write(_CRED_FILE_PATH, f"https://git:{github_token}@github.com\n")
- sandbox_backend.execute(f"chmod 600 {_CRED_FILE_PATH}")
-
-
-def cleanup_git_credentials(sandbox_backend: SandboxBackendProtocol) -> None:
- """Remove the temporary credentials file."""
- sandbox_backend.execute(f"rm -f {_CRED_FILE_PATH}")
-
-
-def _git_with_credentials(
- sandbox_backend: SandboxBackendProtocol,
- repo_dir: str,
- command: str,
+def format_github_comment_body_for_prompt(author: str, body: str) -> str:
+ """Format a GitHub comment body for prompt inclusion."""
+ sanitized_body = sanitize_github_comment_body(body)
+ if author in GITHUB_USER_EMAIL_MAP:
+ return sanitized_body
+
+ return (
+ f"{UNTRUSTED_GITHUB_COMMENT_OPEN_TAG}\n"
+ f"{sanitized_body}\n"
+ f"{UNTRUSTED_GITHUB_COMMENT_CLOSE_TAG}"
+ )
+
+
+async def react_to_github_comment(
+ repo_config: dict[str, str],
+ comment_id: int,
+ *,
+ event_type: str,
+ token: str,
+ pull_number: int | None = None,
+ node_id: str | None = None,
+) -> bool:
+ if event_type == "pull_request_review":
+ return await _react_via_graphql(node_id, token=token)
+
+ owner = repo_config.get("owner", "")
+ repo = repo_config.get("name", "")
+
+ url_template = _REACTION_ENDPOINTS.get(event_type, _REACTION_ENDPOINTS["issue_comment"])
+ url = url_template.format(
```
This function is important because it defines how Open SWE Tutorial: Asynchronous Cloud Coding Agent Architecture and Migration Playbook implements the patterns covered in this chapter.
-### `agent/utils/github.py`
+### `agent/utils/github_comments.py`
-The `setup_git_credentials` function in [`agent/utils/github.py`](https://github.com/langchain-ai/open-swe/blob/HEAD/agent/utils/github.py) handles a key part of this chapter's functionality:
+The `react_to_github_comment` function in [`agent/utils/github_comments.py`](https://github.com/langchain-ai/open-swe/blob/HEAD/agent/utils/github_comments.py) handles a key part of this chapter's functionality:
```py
-def setup_git_credentials(sandbox_backend: SandboxBackendProtocol, github_token: str) -> None:
- """Write GitHub credentials to a temporary file using the sandbox write API.
-
- The write API sends content in the HTTP body (not via a shell command),
- so the token never appears in shell history or process listings.
- """
- sandbox_backend.write(_CRED_FILE_PATH, f"https://git:{github_token}@github.com\n")
- sandbox_backend.execute(f"chmod 600 {_CRED_FILE_PATH}")
-
-
-def cleanup_git_credentials(sandbox_backend: SandboxBackendProtocol) -> None:
- """Remove the temporary credentials file."""
- sandbox_backend.execute(f"rm -f {_CRED_FILE_PATH}")
-
-
-def _git_with_credentials(
- sandbox_backend: SandboxBackendProtocol,
- repo_dir: str,
- command: str,
-) -> ExecuteResponse:
- """Run a git command using the temporary credential file."""
- cred_helper = shlex.quote(f"store --file={_CRED_FILE_PATH}")
- return _run_git(sandbox_backend, repo_dir, f"git -c credential.helper={cred_helper} {command}")
-
-
-def git_push(
- sandbox_backend: SandboxBackendProtocol,
- repo_dir: str,
- branch: str,
- github_token: str | None = None,
+async def react_to_github_comment(
+ repo_config: dict[str, str],
+ comment_id: int,
+ *,
+ event_type: str,
+ token: str,
+ pull_number: int | None = None,
+ node_id: str | None = None,
+) -> bool:
+ if event_type == "pull_request_review":
+ return await _react_via_graphql(node_id, token=token)
+
+ owner = repo_config.get("owner", "")
+ repo = repo_config.get("name", "")
+
+ url_template = _REACTION_ENDPOINTS.get(event_type, _REACTION_ENDPOINTS["issue_comment"])
+ url = url_template.format(
+ owner=owner, repo=repo, comment_id=comment_id, pull_number=pull_number
+ )
+
+ async with httpx.AsyncClient() as http_client:
+ try:
+ response = await http_client.post(
+ url,
+ headers={
+ "Authorization": f"Bearer {token}",
+ "Accept": "application/vnd.github+json",
+ "X-GitHub-Api-Version": "2022-11-28",
+ },
+ json={"content": "eyes"},
```
This function is important because it defines how Open SWE Tutorial: Asynchronous Cloud Coding Agent Architecture and Migration Playbook implements the patterns covered in this chapter.
@@ -212,11 +210,11 @@ This function is important because it defines how Open SWE Tutorial: Asynchronou
```mermaid
flowchart TD
- A[git_add_all]
- B[git_commit]
- C[git_get_remote_url]
- D[setup_git_credentials]
- E[cleanup_git_credentials]
+ A[get_thread_id_from_branch]
+ B[sanitize_github_comment_body]
+ C[format_github_comment_body_for_prompt]
+ D[react_to_github_comment]
+ E[post_github_comment]
A --> B
B --> C
C --> D
diff --git a/tutorials/open-swe-tutorial/07-fork-maintenance-and-migration-strategy.md b/tutorials/open-swe-tutorial/07-fork-maintenance-and-migration-strategy.md
index cf62ea21..ff02bcd7 100644
--- a/tutorials/open-swe-tutorial/07-fork-maintenance-and-migration-strategy.md
+++ b/tutorials/open-swe-tutorial/07-fork-maintenance-and-migration-strategy.md
@@ -39,170 +39,159 @@ You now have a migration-first framework for managing deprecated coding-agent in
Next: [Chapter 8: Contribution, Legacy Support, and Next Steps](08-contribution-legacy-support-and-next-steps.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `agent/utils/sandbox_paths.py`
+### `agent/utils/authorship.py`
-The `aresolve_repo_dir` function in [`agent/utils/sandbox_paths.py`](https://github.com/langchain-ai/open-swe/blob/HEAD/agent/utils/sandbox_paths.py) handles a key part of this chapter's functionality:
+The `add_user_coauthor_trailer` function in [`agent/utils/authorship.py`](https://github.com/langchain-ai/open-swe/blob/HEAD/agent/utils/authorship.py) handles a key part of this chapter's functionality:
```py
-async def aresolve_repo_dir(sandbox_backend: SandboxBackendProtocol, repo_name: str) -> str:
- """Async wrapper around resolve_repo_dir for use in event-loop code."""
- return await asyncio.to_thread(resolve_repo_dir, sandbox_backend, repo_name)
-
-
-def resolve_sandbox_work_dir(sandbox_backend: SandboxBackendProtocol) -> str:
- """Resolve a writable base directory for repository operations."""
- cached_work_dir = getattr(sandbox_backend, _WORK_DIR_CACHE_ATTR, None)
- if isinstance(cached_work_dir, str) and cached_work_dir:
- return cached_work_dir
+def add_user_coauthor_trailer(
+ commit_message: str,
+ identity: CollaboratorIdentity | None,
+) -> str:
+ """Append a Co-authored-by trailer when a user identity is available."""
+ normalized_message = commit_message.rstrip()
+ if not identity:
+ return normalized_message
- checked_candidates: list[str] = []
- for candidate in _iter_work_dir_candidates(sandbox_backend):
- checked_candidates.append(candidate)
- if _is_writable_directory(sandbox_backend, candidate):
- _cache_work_dir(sandbox_backend, candidate)
- return candidate
+ trailer = f"Co-authored-by: {identity.commit_name} <{identity.commit_email}>"
+ if trailer in normalized_message:
+ return normalized_message
+ return f"{normalized_message}\n\n{trailer}"
- msg = "Failed to resolve a writable sandbox work directory"
- if checked_candidates:
- msg = f"{msg}. Candidates checked: {', '.join(checked_candidates)}"
- raise RuntimeError(msg)
+def add_pr_collaboration_note(
+ pr_body: str,
+ identity: CollaboratorIdentity | None,
+) -> str:
+ """Append a best-effort PR attribution note.
-async def aresolve_sandbox_work_dir(sandbox_backend: SandboxBackendProtocol) -> str:
- """Async wrapper around resolve_sandbox_work_dir for use in event-loop code."""
- return await asyncio.to_thread(resolve_sandbox_work_dir, sandbox_backend)
+ GitHub supports commit co-authors, but not PR co-authors. This note makes
+ the collaboration explicit in the automatically-opened PR body.
+ """
+ normalized_body = pr_body.rstrip()
+ if not identity:
+ return normalized_body
-def _iter_work_dir_candidates(
+ note = f"_Opened collaboratively by {identity.display_name} and open-swe._"
```
This function is important because it defines how Open SWE Tutorial: Asynchronous Cloud Coding Agent Architecture and Migration Playbook implements the patterns covered in this chapter.
-### `agent/utils/sandbox_paths.py`
+### `agent/utils/authorship.py`
-The `resolve_sandbox_work_dir` function in [`agent/utils/sandbox_paths.py`](https://github.com/langchain-ai/open-swe/blob/HEAD/agent/utils/sandbox_paths.py) handles a key part of this chapter's functionality:
+The `add_pr_collaboration_note` function in [`agent/utils/authorship.py`](https://github.com/langchain-ai/open-swe/blob/HEAD/agent/utils/authorship.py) handles a key part of this chapter's functionality:
```py
- raise ValueError("repo_name must be a non-empty string")
-
- work_dir = resolve_sandbox_work_dir(sandbox_backend)
- return posixpath.join(work_dir, repo_name)
-
-async def aresolve_repo_dir(sandbox_backend: SandboxBackendProtocol, repo_name: str) -> str:
- """Async wrapper around resolve_repo_dir for use in event-loop code."""
- return await asyncio.to_thread(resolve_repo_dir, sandbox_backend, repo_name)
+def add_pr_collaboration_note(
+ pr_body: str,
+ identity: CollaboratorIdentity | None,
+) -> str:
+ """Append a best-effort PR attribution note.
-def resolve_sandbox_work_dir(sandbox_backend: SandboxBackendProtocol) -> str:
- """Resolve a writable base directory for repository operations."""
- cached_work_dir = getattr(sandbox_backend, _WORK_DIR_CACHE_ATTR, None)
- if isinstance(cached_work_dir, str) and cached_work_dir:
- return cached_work_dir
+ GitHub supports commit co-authors, but not PR co-authors. This note makes
+ the collaboration explicit in the automatically-opened PR body.
+ """
- checked_candidates: list[str] = []
- for candidate in _iter_work_dir_candidates(sandbox_backend):
- checked_candidates.append(candidate)
- if _is_writable_directory(sandbox_backend, candidate):
- _cache_work_dir(sandbox_backend, candidate)
- return candidate
+ normalized_body = pr_body.rstrip()
+ if not identity:
+ return normalized_body
- msg = "Failed to resolve a writable sandbox work directory"
- if checked_candidates:
- msg = f"{msg}. Candidates checked: {', '.join(checked_candidates)}"
- raise RuntimeError(msg)
+ note = f"_Opened collaboratively by {identity.display_name} and open-swe._"
+ if note in normalized_body:
+ return normalized_body
+ if not normalized_body:
+ return note
+ return f"{normalized_body}\n\n{note}"
-
-async def aresolve_sandbox_work_dir(sandbox_backend: SandboxBackendProtocol) -> str:
- """Async wrapper around resolve_sandbox_work_dir for use in event-loop code."""
```
This function is important because it defines how Open SWE Tutorial: Asynchronous Cloud Coding Agent Architecture and Migration Playbook implements the patterns covered in this chapter.
-### `agent/utils/sandbox_paths.py`
+### `agent/middleware/open_pr.py`
-The `aresolve_sandbox_work_dir` function in [`agent/utils/sandbox_paths.py`](https://github.com/langchain-ai/open-swe/blob/HEAD/agent/utils/sandbox_paths.py) handles a key part of this chapter's functionality:
+The `open_pr_if_needed` function in [`agent/middleware/open_pr.py`](https://github.com/langchain-ai/open-swe/blob/HEAD/agent/middleware/open_pr.py) handles a key part of this chapter's functionality:
```py
-
-async def aresolve_sandbox_work_dir(sandbox_backend: SandboxBackendProtocol) -> str:
- """Async wrapper around resolve_sandbox_work_dir for use in event-loop code."""
- return await asyncio.to_thread(resolve_sandbox_work_dir, sandbox_backend)
-
-
-def _iter_work_dir_candidates(
- sandbox_backend: SandboxBackendProtocol,
-) -> Iterable[str]:
- seen: set[str] = set()
-
- for candidate in _iter_provider_paths(sandbox_backend, "get_work_dir"):
- if candidate not in seen:
- seen.add(candidate)
- yield candidate
-
- shell_work_dir = _resolve_shell_path(sandbox_backend, "pwd")
- if shell_work_dir and shell_work_dir not in seen:
- seen.add(shell_work_dir)
- yield shell_work_dir
-
- for candidate in _iter_provider_paths(
- sandbox_backend,
- "get_user_home_dir",
- "get_user_root_dir",
- ):
- if candidate not in seen:
- seen.add(candidate)
- yield candidate
-
- shell_home_dir = _resolve_shell_path(sandbox_backend, "printf '%s' \"$HOME\"")
+@after_agent
+async def open_pr_if_needed(
+ state: AgentState,
+ runtime: Runtime,
+) -> dict[str, Any] | None:
+ """Middleware that commits/pushes changes after agent runs if `commit_and_open_pr` tool didn't."""
+ logger.info("After-agent middleware started")
+
+ try:
+ config = get_config()
+ configurable = config.get("configurable", {})
+ thread_id = configurable.get("thread_id")
+ logger.debug("Middleware running for thread %s", thread_id)
+
+ messages = state.get("messages", [])
+ pr_payload = _extract_pr_params_from_messages(messages)
+
+ if not pr_payload:
+ logger.info("No commit_and_open_pr tool call found, skipping PR creation")
+ return None
+
+ if "success" in pr_payload:
+ # Tool already handled commit/push/PR creation
+ return None
+
+ pr_title = pr_payload.get("title", "feat: Open SWE PR")
+ pr_body = pr_payload.get("body", "Automated PR created by Open SWE agent.")
+ commit_message = pr_payload.get("commit_message", pr_title)
+ github_token = get_github_token()
+ user_identity = await asyncio.to_thread(
+ resolve_triggering_user_identity, config, github_token
```
This function is important because it defines how Open SWE Tutorial: Asynchronous Cloud Coding Agent Architecture and Migration Playbook implements the patterns covered in this chapter.
-### `agent/middleware/ensure_no_empty_msg.py`
+### `agent/utils/linear.py`
-The `get_every_message_since_last_human` function in [`agent/middleware/ensure_no_empty_msg.py`](https://github.com/langchain-ai/open-swe/blob/HEAD/agent/middleware/ensure_no_empty_msg.py) handles a key part of this chapter's functionality:
+The `comment_on_linear_issue` function in [`agent/utils/linear.py`](https://github.com/langchain-ai/open-swe/blob/HEAD/agent/utils/linear.py) handles a key part of this chapter's functionality:
```py
-def get_every_message_since_last_human(state: AgentState) -> list[AnyMessage]:
- messages = state["messages"]
- last_human_idx = -1
- for i in range(len(messages) - 1, -1, -1):
- if messages[i].type == "human":
- last_human_idx = i
- break
- return messages[last_human_idx + 1 :]
-
-
-def check_if_model_already_called_commit_and_open_pr(messages: list[AnyMessage]) -> bool:
- for msg in messages:
- if msg.type == "tool" and msg.name == "commit_and_open_pr":
- return True
- return False
-
-
-def check_if_model_messaged_user(messages: list[AnyMessage]) -> bool:
- for msg in messages:
- if msg.type == "tool" and msg.name in [
- "slack_thread_reply",
- "linear_comment",
- "github_comment",
- ]:
- return True
- return False
+async def comment_on_linear_issue(
+ issue_id: str, comment_body: str, parent_id: str | None = None
+) -> bool:
+ """Add a comment to a Linear issue, optionally as a reply to a specific comment."""
+ mutation = """
+ mutation CommentCreate($issueId: String!, $body: String!, $parentId: String) {
+ commentCreate(input: { issueId: $issueId, body: $body, parentId: $parentId }) {
+ success
+ comment { id }
+ }
+ }
+ """
+ result = await _graphql_request(
+ mutation,
+ {"issueId": issue_id, "body": comment_body, "parentId": parent_id},
+ )
+ return bool(result.get("commentCreate", {}).get("success"))
+
+
+async def post_linear_trace_comment(issue_id: str, run_id: str, triggering_comment_id: str) -> None:
+ """Post a trace URL comment on a Linear issue."""
+ trace_url = get_langsmith_trace_url(run_id)
+ if trace_url:
+ await comment_on_linear_issue(
+ issue_id,
+ f"On it! [View trace]({trace_url})",
+ parent_id=triggering_comment_id or None,
+ )
-def check_if_confirming_completion(messages: list[AnyMessage]) -> bool:
- for msg in messages:
```
This function is important because it defines how Open SWE Tutorial: Asynchronous Cloud Coding Agent Architecture and Migration Playbook implements the patterns covered in this chapter.
@@ -212,11 +201,11 @@ This function is important because it defines how Open SWE Tutorial: Asynchronou
```mermaid
flowchart TD
- A[aresolve_repo_dir]
- B[resolve_sandbox_work_dir]
- C[aresolve_sandbox_work_dir]
- D[get_every_message_since_last_human]
- E[check_if_model_already_called_commit_and_open_pr]
+ A[add_user_coauthor_trailer]
+ B[add_pr_collaboration_note]
+ C[open_pr_if_needed]
+ D[comment_on_linear_issue]
+ E[post_linear_trace_comment]
A --> B
B --> C
C --> D
diff --git a/tutorials/open-swe-tutorial/08-contribution-legacy-support-and-next-steps.md b/tutorials/open-swe-tutorial/08-contribution-legacy-support-and-next-steps.md
index 29038b44..a01c1434 100644
--- a/tutorials/open-swe-tutorial/08-contribution-legacy-support-and-next-steps.md
+++ b/tutorials/open-swe-tutorial/08-contribution-legacy-support-and-next-steps.md
@@ -39,147 +39,95 @@ You now have a complete Open SWE playbook for architecture study, legacy operati
Next tutorial: [SWE-agent Tutorial](../swe-agent-tutorial/)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `agent/middleware/check_message_queue.py`
+### `agent/utils/multimodal.py`
-The `LinearNotifyState` class in [`agent/middleware/check_message_queue.py`](https://github.com/langchain-ai/open-swe/blob/HEAD/agent/middleware/check_message_queue.py) handles a key part of this chapter's functionality:
+The `extract_image_urls` function in [`agent/utils/multimodal.py`](https://github.com/langchain-ai/open-swe/blob/HEAD/agent/utils/multimodal.py) handles a key part of this chapter's functionality:
```py
-class LinearNotifyState(AgentState):
- """Extended agent state for tracking Linear notifications."""
-
- linear_messages_sent_count: int
-
-
-async def _build_blocks_from_payload(
- payload: dict[str, Any],
-) -> list[dict[str, Any]]:
- text = payload.get("text", "")
- image_urls = payload.get("image_urls", []) or []
- blocks: list[dict[str, Any]] = []
- if text:
- blocks.append({"type": "text", "text": text})
-
- if not image_urls:
- return blocks
- async with httpx.AsyncClient() as client:
- for image_url in image_urls:
- image_block = await fetch_image_block(image_url, client)
- if image_block:
- blocks.append(image_block)
- return blocks
-
-
-@before_model(state_schema=LinearNotifyState)
-async def check_message_queue_before_model( # noqa: PLR0911
- state: LinearNotifyState, # noqa: ARG001
- runtime: Runtime, # noqa: ARG001
-) -> dict[str, Any] | None:
-```
-
-This class is important because it defines how Open SWE Tutorial: Asynchronous Cloud Coding Agent Architecture and Migration Playbook implements the patterns covered in this chapter.
+def extract_image_urls(text: str) -> list[str]:
+ """Extract image URLs from markdown image syntax and direct image links."""
+ if not text:
+ return []
-### `agent/middleware/check_message_queue.py`
+ urls: list[str] = []
+ urls.extend(IMAGE_MARKDOWN_RE.findall(text))
+ urls.extend(IMAGE_URL_RE.findall(text))
-The `check_message_queue_before_model` function in [`agent/middleware/check_message_queue.py`](https://github.com/langchain-ai/open-swe/blob/HEAD/agent/middleware/check_message_queue.py) handles a key part of this chapter's functionality:
+ deduped = dedupe_urls(urls)
+ if deduped:
+ logger.debug("Extracted %d image URL(s)", len(deduped))
+ return deduped
-```py
-@before_model(state_schema=LinearNotifyState)
-async def check_message_queue_before_model( # noqa: PLR0911
- state: LinearNotifyState, # noqa: ARG001
- runtime: Runtime, # noqa: ARG001
+async def fetch_image_block(
+ image_url: str,
+ client: httpx.AsyncClient,
) -> dict[str, Any] | None:
- """Middleware that checks for queued messages before each model call.
-
- If messages are found in the queue for this thread, it extracts all messages,
- adds them to the conversation state as new human messages, and clears the queue.
- Messages are processed in FIFO order (oldest first).
-
- This enables handling of follow-up comments that arrive while the agent is busy.
- The agent will see the new messages and can incorporate them into its response.
- """
+ """Fetch image bytes and build an image content block."""
try:
- config = get_config()
- configurable = config.get("configurable", {})
- thread_id = configurable.get("thread_id")
-
- if not thread_id:
- return None
-
- try:
- store = get_store()
- except Exception as e: # noqa: BLE001
- logger.debug("Could not get store from context: %s", e)
- return None
-
- if store is None:
- return None
-
+ logger.debug("Fetching image from %s", image_url)
+ headers = None
+ host = (urlparse(image_url).hostname or "").lower()
+ if host == "uploads.linear.app" or host.endswith(".uploads.linear.app"):
+ linear_api_key = os.environ.get("LINEAR_API_KEY", "")
+ if linear_api_key:
+ headers = {"Authorization": linear_api_key}
+ else:
+ logger.warning(
```
This function is important because it defines how Open SWE Tutorial: Asynchronous Cloud Coding Agent Architecture and Migration Playbook implements the patterns covered in this chapter.
-### `agent/tools/http_request.py`
+### `agent/utils/multimodal.py`
-The `http_request` function in [`agent/tools/http_request.py`](https://github.com/langchain-ai/open-swe/blob/HEAD/agent/tools/http_request.py) handles a key part of this chapter's functionality:
+The `fetch_image_block` function in [`agent/utils/multimodal.py`](https://github.com/langchain-ai/open-swe/blob/HEAD/agent/utils/multimodal.py) handles a key part of this chapter's functionality:
```py
-def http_request(
- url: str,
- method: str = "GET",
- headers: dict[str, str] | None = None,
- data: str | dict | None = None,
- params: dict[str, str] | None = None,
- timeout: int = 30,
-) -> dict[str, Any]:
- """Make HTTP requests to APIs and web services.
-
- Args:
- url: Target URL
- method: HTTP method (GET, POST, PUT, DELETE, etc.)
- headers: HTTP headers to include
- data: Request body data (string or dict)
- params: URL query parameters
- timeout: Request timeout in seconds
-
- Returns:
- Dictionary with response data including status, headers, and content
- """
- is_safe, reason = _is_url_safe(url)
- if not is_safe:
- return _blocked_response(url, reason)
-
+async def fetch_image_block(
+ image_url: str,
+ client: httpx.AsyncClient,
+) -> dict[str, Any] | None:
+ """Fetch image bytes and build an image content block."""
try:
- kwargs: dict[str, Any] = {}
-
- if headers:
- kwargs["headers"] = headers
+ logger.debug("Fetching image from %s", image_url)
+ headers = None
+ host = (urlparse(image_url).hostname or "").lower()
+ if host == "uploads.linear.app" or host.endswith(".uploads.linear.app"):
+ linear_api_key = os.environ.get("LINEAR_API_KEY", "")
+ if linear_api_key:
+ headers = {"Authorization": linear_api_key}
+ else:
+ logger.warning(
+ "LINEAR_API_KEY not set; cannot authenticate image fetch for %s",
+ image_url,
+ )
+ elif host == "files.slack.com" or host.endswith(".files.slack.com"):
+ slack_bot_token = os.environ.get("SLACK_BOT_TOKEN", "")
+ if slack_bot_token:
+ headers = {"Authorization": f"Bearer {slack_bot_token}"}
+ else:
+ logger.warning(
+ "SLACK_BOT_TOKEN not set; cannot authenticate image fetch for %s",
+ image_url,
+ )
+ response = await client.get(image_url, headers=headers, follow_redirects=True)
+ response.raise_for_status()
+ content_type = response.headers.get("Content-Type", "").split(";")[0].strip()
```
This function is important because it defines how Open SWE Tutorial: Asynchronous Cloud Coding Agent Architecture and Migration Playbook implements the patterns covered in this chapter.
### `agent/utils/multimodal.py`
-The `extract_image_urls` function in [`agent/utils/multimodal.py`](https://github.com/langchain-ai/open-swe/blob/HEAD/agent/utils/multimodal.py) handles a key part of this chapter's functionality:
+The `dedupe_urls` function in [`agent/utils/multimodal.py`](https://github.com/langchain-ai/open-swe/blob/HEAD/agent/utils/multimodal.py) handles a key part of this chapter's functionality:
```py
-
-
-def extract_image_urls(text: str) -> list[str]:
- """Extract image URLs from markdown image syntax and direct image links."""
- if not text:
- return []
-
- urls: list[str] = []
- urls.extend(IMAGE_MARKDOWN_RE.findall(text))
urls.extend(IMAGE_URL_RE.findall(text))
deduped = dedupe_urls(urls)
@@ -203,20 +151,70 @@ async def fetch_image_block(
headers = {"Authorization": linear_api_key}
else:
logger.warning(
+ "LINEAR_API_KEY not set; cannot authenticate image fetch for %s",
+ image_url,
+ )
+ elif host == "files.slack.com" or host.endswith(".files.slack.com"):
+ slack_bot_token = os.environ.get("SLACK_BOT_TOKEN", "")
+ if slack_bot_token:
+ headers = {"Authorization": f"Bearer {slack_bot_token}"}
+ else:
+ logger.warning(
```
This function is important because it defines how Open SWE Tutorial: Asynchronous Cloud Coding Agent Architecture and Migration Playbook implements the patterns covered in this chapter.
+### `agent/middleware/check_message_queue.py`
+
+The `LinearNotifyState` class in [`agent/middleware/check_message_queue.py`](https://github.com/langchain-ai/open-swe/blob/HEAD/agent/middleware/check_message_queue.py) handles a key part of this chapter's functionality:
+
+```py
+
+
+class LinearNotifyState(AgentState):
+ """Extended agent state for tracking Linear notifications."""
+
+ linear_messages_sent_count: int
+
+
+async def _build_blocks_from_payload(
+ payload: dict[str, Any],
+) -> list[dict[str, Any]]:
+ text = payload.get("text", "")
+ image_urls = payload.get("image_urls", []) or []
+ blocks: list[dict[str, Any]] = []
+ if text:
+ blocks.append({"type": "text", "text": text})
+
+ if not image_urls:
+ return blocks
+ async with httpx.AsyncClient() as client:
+ for image_url in image_urls:
+ image_block = await fetch_image_block(image_url, client)
+ if image_block:
+ blocks.append(image_block)
+ return blocks
+
+
+@before_model(state_schema=LinearNotifyState)
+async def check_message_queue_before_model( # noqa: PLR0911
+ state: LinearNotifyState, # noqa: ARG001
+ runtime: Runtime, # noqa: ARG001
+) -> dict[str, Any] | None:
+```
+
+This class is important because it defines how Open SWE Tutorial: Asynchronous Cloud Coding Agent Architecture and Migration Playbook implements the patterns covered in this chapter.
+
## How These Components Connect
```mermaid
flowchart TD
- A[LinearNotifyState]
- B[check_message_queue_before_model]
- C[http_request]
- D[extract_image_urls]
- E[fetch_image_block]
+ A[extract_image_urls]
+ B[fetch_image_block]
+ C[dedupe_urls]
+ D[LinearNotifyState]
+ E[check_message_queue_before_model]
A --> B
B --> C
C --> D
diff --git a/tutorials/open-webui-tutorial/01-getting-started.md b/tutorials/open-webui-tutorial/01-getting-started.md
index e7b2f9d9..7678b774 100644
--- a/tutorials/open-webui-tutorial/01-getting-started.md
+++ b/tutorials/open-webui-tutorial/01-getting-started.md
@@ -6,6 +6,7 @@ has_children: false
parent: Open WebUI Tutorial
---
+
# Chapter 1: Getting Started with Open WebUI
Welcome to **Chapter 1: Getting Started with Open WebUI**. In this part of **Open WebUI Tutorial: Self-Hosted AI Workspace and Chat Interface**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
@@ -299,342 +300,13 @@ Now that you have Open WebUI running, let's explore:
You're now ready to explore the full power of self-hosted AI chat interfaces! 🚀
-## Depth Expansion Playbook
+## How These Components Connect
-<!-- depth-expansion-v2 -->
-
-This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
-
-### Strategic Context
-
-- tutorial: **Open WebUI Tutorial: Self-Hosted AI Workspace and Chat Interface**
-- tutorial slug: **open-webui-tutorial**
-- chapter focus: **Chapter 1: Getting Started with Open WebUI**
-- system context: **Open Webui Tutorial**
-- objective: move from surface-level usage to repeatable engineering operation
-
-### Architecture Decomposition
-
-1. Define the runtime boundary for `Chapter 1: Getting Started with Open WebUI`.
-2. Separate control-plane decisions from data-plane execution.
-3. Capture input contracts, transformation points, and output contracts.
-4. Trace state transitions across request lifecycle stages.
-5. Identify extension hooks and policy interception points.
-6. Map ownership boundaries for team and automation workflows.
-7. Specify rollback and recovery paths for unsafe changes.
-8. Track observability signals for correctness, latency, and cost.
-
-### Operator Decision Matrix
-
-| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
-|:--------------|:--------------|:------------------|:---------|
-| Runtime mode | managed defaults | explicit policy config | speed vs control |
-| State handling | local ephemeral | durable persisted state | simplicity vs auditability |
-| Tool integration | direct API use | mediated adapter layer | velocity vs governance |
-| Rollout method | manual change | staged + canary rollout | effort vs safety |
-| Incident response | best effort logs | runbooks + SLO alerts | cost vs reliability |
-
-### Failure Modes and Countermeasures
-
-| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
-|:-------------|:-------------|:-------------------|:---------------|
-| stale context | inconsistent outputs | missing refresh window | enforce context TTL and refresh hooks |
-| policy drift | unexpected execution | ad hoc overrides | centralize policy profiles |
-| auth mismatch | 401/403 bursts | credential sprawl | rotation schedule + scope minimization |
-| schema breakage | parser/validation errors | unmanaged upstream changes | contract tests per release |
-| retry storms | queue congestion | no backoff controls | jittered backoff + circuit breakers |
-| silent regressions | quality drop without alerts | weak baseline metrics | eval harness with thresholds |
-
-### Implementation Runbook
-
-1. Establish a reproducible baseline environment.
-2. Capture chapter-specific success criteria before changes.
-3. Implement minimal viable path with explicit interfaces.
-4. Add observability before expanding feature scope.
-5. Run deterministic tests for happy-path behavior.
-6. Inject failure scenarios for negative-path validation.
-7. Compare output quality against baseline snapshots.
-8. Promote through staged environments with rollback gates.
-9. Record operational lessons in release notes.
-
-### Quality Gate Checklist
-
-- [ ] chapter-level assumptions are explicit and testable
-- [ ] API/tool boundaries are documented with input/output examples
-- [ ] failure handling includes retry, timeout, and fallback policy
-- [ ] security controls include auth scopes and secret rotation plans
-- [ ] observability includes logs, metrics, traces, and alert thresholds
-- [ ] deployment guidance includes canary and rollback paths
-- [ ] docs include links to upstream sources and related tracks
-- [ ] post-release verification confirms expected behavior under load
-
-### Source Alignment
-
-- [Open WebUI Repository](https://github.com/open-webui/open-webui)
-- [Open WebUI Releases](https://github.com/open-webui/open-webui/releases)
-- [Open WebUI Docs](https://docs.openwebui.com/)
-
-### Cross-Tutorial Connection Map
-
-- [Ollama Tutorial](../ollama-tutorial/)
-- [LiteLLM Tutorial](../litellm-tutorial/)
-- [Langfuse Tutorial](../langfuse-tutorial/)
-- [OpenHands Tutorial](../openhands-tutorial/)
-- [Chapter 1: Getting Started](01-getting-started.md)
-
-### Advanced Practice Exercises
-
-1. Build a minimal end-to-end implementation for `Chapter 1: Getting Started with Open WebUI`.
-2. Add instrumentation and measure baseline latency and error rate.
-3. Introduce one controlled failure and confirm graceful recovery.
-4. Add policy constraints and verify they are enforced consistently.
-5. Run a staged rollout and document rollback decision criteria.
-
-### Review Questions
-
-1. Which execution boundary matters most for this chapter and why?
-2. What signal detects regressions earliest in your environment?
-3. What tradeoff did you make between delivery speed and governance?
-4. How would you recover from the highest-impact failure mode?
-5. What must be automated before scaling to team-wide adoption?
-
-### Scenario Playbook 1: Chapter 1: Getting Started with Open WebUI
-
-- tutorial context: **Open WebUI Tutorial: Self-Hosted AI Workspace and Chat Interface**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 2: Chapter 1: Getting Started with Open WebUI
-
-- tutorial context: **Open WebUI Tutorial: Self-Hosted AI Workspace and Chat Interface**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 3: Chapter 1: Getting Started with Open WebUI
-
-- tutorial context: **Open WebUI Tutorial: Self-Hosted AI Workspace and Chat Interface**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 4: Chapter 1: Getting Started with Open WebUI
-
-- tutorial context: **Open WebUI Tutorial: Self-Hosted AI Workspace and Chat Interface**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 5: Chapter 1: Getting Started with Open WebUI
-
-- tutorial context: **Open WebUI Tutorial: Self-Hosted AI Workspace and Chat Interface**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 6: Chapter 1: Getting Started with Open WebUI
-
-- tutorial context: **Open WebUI Tutorial: Self-Hosted AI Workspace and Chat Interface**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 7: Chapter 1: Getting Started with Open WebUI
-
-- tutorial context: **Open WebUI Tutorial: Self-Hosted AI Workspace and Chat Interface**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 8: Chapter 1: Getting Started with Open WebUI
-
-- tutorial context: **Open WebUI Tutorial: Self-Hosted AI Workspace and Chat Interface**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 9: Chapter 1: Getting Started with Open WebUI
-
-- tutorial context: **Open WebUI Tutorial: Self-Hosted AI Workspace and Chat Interface**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 10: Chapter 1: Getting Started with Open WebUI
-
-- tutorial context: **Open WebUI Tutorial: Self-Hosted AI Workspace and Chat Interface**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 11: Chapter 1: Getting Started with Open WebUI
-
-- tutorial context: **Open WebUI Tutorial: Self-Hosted AI Workspace and Chat Interface**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 12: Chapter 1: Getting Started with Open WebUI
-
-- tutorial context: **Open WebUI Tutorial: Self-Hosted AI Workspace and Chat Interface**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 13: Chapter 1: Getting Started with Open WebUI
-
-- tutorial context: **Open WebUI Tutorial: Self-Hosted AI Workspace and Chat Interface**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 14: Chapter 1: Getting Started with Open WebUI
-
-- tutorial context: **Open WebUI Tutorial: Self-Hosted AI Workspace and Chat Interface**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 15: Chapter 1: Getting Started with Open WebUI
-
-- tutorial context: **Open WebUI Tutorial: Self-Hosted AI Workspace and Chat Interface**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 16: Chapter 1: Getting Started with Open WebUI
-
-- tutorial context: **Open WebUI Tutorial: Self-Hosted AI Workspace and Chat Interface**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-## What Problem Does This Solve?
-
-Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for `open`, `webui`, `docker` so behavior stays predictable as complexity grows.
-
-In practical terms, this chapter helps you avoid three common failures:
-
-- coupling core logic too tightly to one implementation path
-- missing the handoff boundaries between setup, execution, and validation
-- shipping changes without clear rollback or observability strategy
-
-After working through this chapter, you should be able to reason about `Chapter 1: Getting Started with Open WebUI` as an operating subsystem inside **Open WebUI Tutorial: Self-Hosted AI Workspace and Chat Interface**, with explicit contracts for inputs, state transitions, and outputs.
-
-Use the implementation notes around `your`, `latest`, `WebUI` as your checklist when adapting these patterns to your own repository.
-
-## How it Works Under the Hood
-
-Under the hood, `Chapter 1: Getting Started with Open WebUI` usually follows a repeatable control path:
-
-1. **Context bootstrap**: initialize runtime config and prerequisites for `open`.
-2. **Input normalization**: shape incoming data so `webui` receives stable contracts.
-3. **Core execution**: run the main logic branch and propagate intermediate state through `docker`.
-4. **Policy and safety checks**: enforce limits, auth scopes, and failure boundaries.
-5. **Output composition**: return canonical result payloads for downstream consumers.
-6. **Operational telemetry**: emit logs/metrics needed for debugging and performance tuning.
-
-When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
-
-## Source Walkthrough
-
-Use the following upstream sources to verify implementation details while reading this chapter:
-
-- [Open WebUI Repository](https://github.com/open-webui/open-webui)
- Why it matters: authoritative reference on `Open WebUI Repository` (github.com).
-- [Open WebUI Releases](https://github.com/open-webui/open-webui/releases)
- Why it matters: authoritative reference on `Open WebUI Releases` (github.com).
-- [Open WebUI Docs](https://docs.openwebui.com/)
- Why it matters: authoritative reference on `Open WebUI Docs` (docs.openwebui.com).
-
-Suggested trace strategy:
-- search upstream code for `open` and `webui` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
-
-## Chapter Connections
-
-- [Tutorial Index](README.md)
-- [Next Chapter: Chapter 2: Model Management & Backend Configuration](02-model-management.md)
-- [Main Catalog](../../README.md#-tutorial-catalog)
-- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
+```mermaid
+flowchart TD
+ A[Docker Container] --> B[Open WebUI Backend]
+ B --> C[Ollama API :11434]
+ B --> D[OpenAI-Compatible API]
+ B --> E[SQLite / Volume Storage]
+ F[Browser :3000] --> B
+```
diff --git a/tutorials/open-webui-tutorial/02-model-management.md b/tutorials/open-webui-tutorial/02-model-management.md
index 6651f353..e2a7a5cb 100644
--- a/tutorials/open-webui-tutorial/02-model-management.md
+++ b/tutorials/open-webui-tutorial/02-model-management.md
@@ -666,6 +666,20 @@ Under the hood, `Chapter 2: Model Management & Backend Configuration` usually fo
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## Architecture Diagram
+
+```mermaid
+flowchart TD
+ A[Open WebUI] --> B{Backend Router}
+ B --> C[Ollama :11434]
+ B --> D[OpenAI API]
+ B --> E[Anthropic API]
+ B --> F[LocalAI / LiteLLM]
+ C --> G[Local Models]
+ D --> H[GPT-4 / GPT-4o]
+ E --> I[Claude Models]
+```
+
## Source Walkthrough
Use the following upstream sources to verify implementation details while reading this chapter:
diff --git a/tutorials/open-webui-tutorial/03-interface-customization.md b/tutorials/open-webui-tutorial/03-interface-customization.md
index 53bc1f38..301cda6f 100644
--- a/tutorials/open-webui-tutorial/03-interface-customization.md
+++ b/tutorials/open-webui-tutorial/03-interface-customization.md
@@ -1087,6 +1087,18 @@ Under the hood, `Chapter 3: Interface Customization & Personalization` usually f
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## Customization Flow
+
+```mermaid
+flowchart LR
+ A[Admin Settings] --> B[Branding & Theme]
+ A --> C[System Prompt Templates]
+ A --> D[Model Defaults]
+ B --> E[Custom Logo / Colors]
+ C --> F[Persona Presets]
+ D --> G[Temperature / Params]
+```
+
## Source Walkthrough
Use the following upstream sources to verify implementation details while reading this chapter:
diff --git a/tutorials/open-webui-tutorial/04-advanced-chat-features.md b/tutorials/open-webui-tutorial/04-advanced-chat-features.md
index f7eda352..5137dfdd 100644
--- a/tutorials/open-webui-tutorial/04-advanced-chat-features.md
+++ b/tutorials/open-webui-tutorial/04-advanced-chat-features.md
@@ -1193,6 +1193,20 @@ Under the hood, `Chapter 4: Advanced Chat Features & Multi-Modal Conversations`
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## Advanced Chat Feature Flow
+
+```mermaid
+flowchart TD
+ A[User Message] --> B{Feature Router}
+ B --> C[Image Upload / Vision]
+ B --> D[Tool / Function Calling]
+ B --> E[Multi-Model Comparison]
+ B --> F[Voice Input]
+ C --> G[Model with Vision Support]
+ D --> H[External Tool Execution]
+ E --> I[Side-by-Side Responses]
+```
+
## Source Walkthrough
Use the following upstream sources to verify implementation details while reading this chapter:
diff --git a/tutorials/open-webui-tutorial/05-data-knowledge.md b/tutorials/open-webui-tutorial/05-data-knowledge.md
index a17c2405..09d24fef 100644
--- a/tutorials/open-webui-tutorial/05-data-knowledge.md
+++ b/tutorials/open-webui-tutorial/05-data-knowledge.md
@@ -1100,6 +1100,21 @@ Under the hood, `Chapter 5: Data, Knowledge Bases & RAG Implementation` usually
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## RAG Pipeline Flow
+
+```mermaid
+flowchart TD
+ A[Document Upload] --> B[Text Extraction]
+ B --> C[Chunking]
+ C --> D[Embedding Model]
+ D --> E[Vector Store]
+ F[User Query] --> G[Query Embedding]
+ G --> E
+ E --> H[Relevant Chunks]
+ H --> I[LLM with Context]
+ I --> J[Grounded Response]
+```
+
## Source Walkthrough
Use the following upstream sources to verify implementation details while reading this chapter:
diff --git a/tutorials/open-webui-tutorial/06-user-management.md b/tutorials/open-webui-tutorial/06-user-management.md
index 81ead817..693f0796 100644
--- a/tutorials/open-webui-tutorial/06-user-management.md
+++ b/tutorials/open-webui-tutorial/06-user-management.md
@@ -904,6 +904,20 @@ Under the hood, `Chapter 6: User Management, Authentication & Access Control` us
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## Access Control Model
+
+```mermaid
+flowchart LR
+ A[Login Request] --> B{Auth Provider}
+ B --> C[Local Auth]
+ B --> D[OAuth / LDAP]
+ C --> E{Role Check}
+ D --> E
+ E -->|Admin| F[Full Access]
+ E -->|User| G[Standard Access]
+ E -->|Pending| H[Blocked]
+```
+
## Source Walkthrough
Use the following upstream sources to verify implementation details while reading this chapter:
diff --git a/tutorials/open-webui-tutorial/07-integrations.md b/tutorials/open-webui-tutorial/07-integrations.md
index 202ead1a..d1cc9e17 100644
--- a/tutorials/open-webui-tutorial/07-integrations.md
+++ b/tutorials/open-webui-tutorial/07-integrations.md
@@ -877,6 +877,19 @@ Under the hood, `Chapter 7: API Integrations, Webhooks & External Service Connec
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## Integration Architecture
+
+```mermaid
+flowchart TD
+ A[Open WebUI] --> B[OpenAI-Compatible Endpoints]
+ A --> C[Webhook Callbacks]
+ A --> D[External Tool APIs]
+ B --> E[LiteLLM Proxy]
+ B --> F[Azure OpenAI]
+ D --> G[Web Search]
+ D --> H[Custom Functions]
+```
+
## Source Walkthrough
Use the following upstream sources to verify implementation details while reading this chapter:
diff --git a/tutorials/open-webui-tutorial/08-production-deployment.md b/tutorials/open-webui-tutorial/08-production-deployment.md
index 4bdf92e8..9e7745c5 100644
--- a/tutorials/open-webui-tutorial/08-production-deployment.md
+++ b/tutorials/open-webui-tutorial/08-production-deployment.md
@@ -1479,6 +1479,18 @@ Under the hood, `Chapter 8: Production Deployment, Scaling & Enterprise Configur
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## Production Deployment Topology
+
+```mermaid
+flowchart LR
+ A[Reverse Proxy / TLS] --> B[Open WebUI Instances]
+ B --> C[Redis Session Store]
+ B --> D[Persistent Volume]
+ B --> E[LLM Backend Pool]
+ F[Monitoring / Alerts] --> B
+ G[CI/CD Pipeline] --> B
+```
+
## Source Walkthrough
Use the following upstream sources to verify implementation details while reading this chapter:
diff --git a/tutorials/openai-python-sdk-tutorial/01-getting-started.md b/tutorials/openai-python-sdk-tutorial/01-getting-started.md
index 44813dca..c867d7cc 100644
--- a/tutorials/openai-python-sdk-tutorial/01-getting-started.md
+++ b/tutorials/openai-python-sdk-tutorial/01-getting-started.md
@@ -68,141 +68,139 @@ You now have a working SDK setup with both sync and async Responses API calls.
Next: [Chapter 2: Chat Completions](02-chat-completions.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `examples/parsing_tools.py`
+### `scripts/detect-breaking-changes.py`
-The `Table` class in [`examples/parsing_tools.py`](https://github.com/openai/openai-python/blob/HEAD/examples/parsing_tools.py) handles a key part of this chapter's functionality:
+The `public_members` function in [`scripts/detect-breaking-changes.py`](https://github.com/openai/openai-python/blob/HEAD/scripts/detect-breaking-changes.py) handles a key part of this chapter's functionality:
```py
-class Table(str, Enum):
- orders = "orders"
- customers = "customers"
- products = "products"
-
-
-class Column(str, Enum):
- id = "id"
- status = "status"
- expected_delivery_date = "expected_delivery_date"
- delivered_at = "delivered_at"
- shipped_at = "shipped_at"
- ordered_at = "ordered_at"
- canceled_at = "canceled_at"
-
-
-class Operator(str, Enum):
- eq = "="
- gt = ">"
- lt = "<"
- le = "<="
- ge = ">="
- ne = "!="
-
-
-class OrderBy(str, Enum):
- asc = "asc"
- desc = "desc"
-
-
+def public_members(obj: griffe.Object | griffe.Alias) -> dict[str, griffe.Object | griffe.Alias]:
+ if isinstance(obj, griffe.Alias):
+ # ignore imports for now, they're technically part of the public API
+ # but we don't have good preventative measures in place to prevent
+ # changing them
+ return {}
+
+ return {name: value for name, value in obj.all_members.items() if not name.startswith("_")}
+
+
+def find_breaking_changes(
+ new_obj: griffe.Object | griffe.Alias,
+ old_obj: griffe.Object | griffe.Alias,
+ *,
+ path: list[str],
+) -> Iterator[Text | str]:
+ new_members = public_members(new_obj)
+ old_members = public_members(old_obj)
+
+ for name, old_member in old_members.items():
+ if isinstance(old_member, griffe.Alias) and len(path) > 2:
+ # ignore imports in `/types/` for now, they're technically part of the public API
+ # but we don't have good preventative measures in place to prevent changing them
+ continue
+
+ new_member = new_members.get(name)
+ if new_member is None:
+ cls_name = old_member.__class__.__name__
+ yield Text(f"({cls_name})", style=Style(color="rgb(119, 119, 119)"))
+ yield from [" " for _ in range(10 - len(cls_name))]
```
-This class is important because it defines how OpenAI Python SDK Tutorial: Production API Patterns implements the patterns covered in this chapter.
+This function is important because it defines how OpenAI Python SDK Tutorial: Production API Patterns implements the patterns covered in this chapter.
-### `examples/parsing_tools.py`
+### `scripts/detect-breaking-changes.py`
-The `Column` class in [`examples/parsing_tools.py`](https://github.com/openai/openai-python/blob/HEAD/examples/parsing_tools.py) handles a key part of this chapter's functionality:
+The `find_breaking_changes` function in [`scripts/detect-breaking-changes.py`](https://github.com/openai/openai-python/blob/HEAD/scripts/detect-breaking-changes.py) handles a key part of this chapter's functionality:
```py
-class Column(str, Enum):
- id = "id"
- status = "status"
- expected_delivery_date = "expected_delivery_date"
- delivered_at = "delivered_at"
- shipped_at = "shipped_at"
- ordered_at = "ordered_at"
- canceled_at = "canceled_at"
-
-
-class Operator(str, Enum):
- eq = "="
- gt = ">"
- lt = "<"
- le = "<="
- ge = ">="
- ne = "!="
-
-
-class OrderBy(str, Enum):
- asc = "asc"
- desc = "desc"
-
-
-class DynamicValue(BaseModel):
- column_name: str
-
-
-class Condition(BaseModel):
- column: str
+def find_breaking_changes(
+ new_obj: griffe.Object | griffe.Alias,
+ old_obj: griffe.Object | griffe.Alias,
+ *,
+ path: list[str],
+) -> Iterator[Text | str]:
+ new_members = public_members(new_obj)
+ old_members = public_members(old_obj)
+
+ for name, old_member in old_members.items():
+ if isinstance(old_member, griffe.Alias) and len(path) > 2:
+ # ignore imports in `/types/` for now, they're technically part of the public API
+ # but we don't have good preventative measures in place to prevent changing them
+ continue
+
+ new_member = new_members.get(name)
+ if new_member is None:
+ cls_name = old_member.__class__.__name__
+ yield Text(f"({cls_name})", style=Style(color="rgb(119, 119, 119)"))
+ yield from [" " for _ in range(10 - len(cls_name))]
+ yield f" {'.'.join(path)}.{name}"
+ yield "\n"
+ continue
+
+ yield from find_breaking_changes(new_member, old_member, path=[*path, name])
+
+
+def main() -> None:
+ try:
+ against_ref = sys.argv[1]
```
-This class is important because it defines how OpenAI Python SDK Tutorial: Production API Patterns implements the patterns covered in this chapter.
+This function is important because it defines how OpenAI Python SDK Tutorial: Production API Patterns implements the patterns covered in this chapter.
-### `examples/parsing_tools.py`
+### `scripts/detect-breaking-changes.py`
-The `Operator` class in [`examples/parsing_tools.py`](https://github.com/openai/openai-python/blob/HEAD/examples/parsing_tools.py) handles a key part of this chapter's functionality:
+The `main` function in [`scripts/detect-breaking-changes.py`](https://github.com/openai/openai-python/blob/HEAD/scripts/detect-breaking-changes.py) handles a key part of this chapter's functionality:
```py
-class Operator(str, Enum):
- eq = "="
- gt = ">"
- lt = "<"
- le = "<="
- ge = ">="
- ne = "!="
+def main() -> None:
+ try:
+ against_ref = sys.argv[1]
+ except IndexError as err:
+ raise RuntimeError("You must specify a base ref to run breaking change detection against") from err
+ package = griffe.load(
+ "openai",
+ search_paths=[Path(__file__).parent.parent.joinpath("src")],
+ )
+ old_package = griffe.load_git(
+ "openai",
+ ref=against_ref,
+ search_paths=["src"],
+ )
+ assert isinstance(package, griffe.Module)
+ assert isinstance(old_package, griffe.Module)
-class OrderBy(str, Enum):
- asc = "asc"
- desc = "desc"
-
-
-class DynamicValue(BaseModel):
- column_name: str
-
+ output = list(find_breaking_changes(package, old_package, path=["openai"]))
+ if output:
+ rich.print(Text("Breaking changes detected!", style=Style(color="rgb(165, 79, 87)")))
+ rich.print()
-class Condition(BaseModel):
- column: str
- operator: Operator
- value: Union[str, int, DynamicValue]
+ for text in output:
+ rich.print(text, end="")
+ sys.exit(1)
-class Query(BaseModel):
- table_name: Table
- columns: List[Column]
- conditions: List[Condition]
- order_by: OrderBy
+main()
```
-This class is important because it defines how OpenAI Python SDK Tutorial: Production API Patterns implements the patterns covered in this chapter.
+This function is important because it defines how OpenAI Python SDK Tutorial: Production API Patterns implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[Table]
- B[Column]
- C[Operator]
+ A[public_members]
+ B[find_breaking_changes]
+ C[main]
A --> B
B --> C
```
diff --git a/tutorials/openai-python-sdk-tutorial/02-chat-completions.md b/tutorials/openai-python-sdk-tutorial/02-chat-completions.md
index 699af3d3..bdb4ad7f 100644
--- a/tutorials/openai-python-sdk-tutorial/02-chat-completions.md
+++ b/tutorials/openai-python-sdk-tutorial/02-chat-completions.md
@@ -64,129 +64,125 @@ You can now support legacy/interoperable message workflows while planning Respon
Next: [Chapter 3: Embeddings and Search](03-embeddings-search.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `examples/parsing_tools.py`
+### `examples/azure_ad.py`
-The `OrderBy` class in [`examples/parsing_tools.py`](https://github.com/openai/openai-python/blob/HEAD/examples/parsing_tools.py) handles a key part of this chapter's functionality:
+The `sync_main` function in [`examples/azure_ad.py`](https://github.com/openai/openai-python/blob/HEAD/examples/azure_ad.py) handles a key part of this chapter's functionality:
```py
-class OrderBy(str, Enum):
- asc = "asc"
- desc = "desc"
+def sync_main() -> None:
+ from azure.identity import DefaultAzureCredential, get_bearer_token_provider
+ token_provider: AzureADTokenProvider = get_bearer_token_provider(DefaultAzureCredential(), scopes)
-class DynamicValue(BaseModel):
- column_name: str
+ client = AzureOpenAI(
+ api_version=api_version,
+ azure_endpoint=endpoint,
+ azure_ad_token_provider=token_provider,
+ )
+ completion = client.chat.completions.create(
+ model=deployment_name,
+ messages=[
+ {
+ "role": "user",
+ "content": "How do I output all files in a directory using Python?",
+ }
+ ],
+ )
-class Condition(BaseModel):
- column: str
- operator: Operator
- value: Union[str, int, DynamicValue]
+ print(completion.to_json())
-class Query(BaseModel):
- table_name: Table
- columns: List[Column]
- conditions: List[Condition]
- order_by: OrderBy
+async def async_main() -> None:
+ from azure.identity.aio import DefaultAzureCredential, get_bearer_token_provider
+ token_provider: AsyncAzureADTokenProvider = get_bearer_token_provider(DefaultAzureCredential(), scopes)
-client = OpenAI()
-
-completion = client.chat.completions.parse(
- model="gpt-4o-2024-08-06",
- messages=[
- {
- "role": "system",
- "content": "You are a helpful assistant. The current date is August 6, 2024. You help users query for the data they are looking for by calling the query function.",
+ client = AsyncAzureOpenAI(
```
-This class is important because it defines how OpenAI Python SDK Tutorial: Production API Patterns implements the patterns covered in this chapter.
+This function is important because it defines how OpenAI Python SDK Tutorial: Production API Patterns implements the patterns covered in this chapter.
-### `examples/parsing_tools.py`
+### `examples/azure_ad.py`
-The `DynamicValue` class in [`examples/parsing_tools.py`](https://github.com/openai/openai-python/blob/HEAD/examples/parsing_tools.py) handles a key part of this chapter's functionality:
+The `async_main` function in [`examples/azure_ad.py`](https://github.com/openai/openai-python/blob/HEAD/examples/azure_ad.py) handles a key part of this chapter's functionality:
```py
-class DynamicValue(BaseModel):
- column_name: str
+async def async_main() -> None:
+ from azure.identity.aio import DefaultAzureCredential, get_bearer_token_provider
+ token_provider: AsyncAzureADTokenProvider = get_bearer_token_provider(DefaultAzureCredential(), scopes)
-class Condition(BaseModel):
- column: str
- operator: Operator
- value: Union[str, int, DynamicValue]
+ client = AsyncAzureOpenAI(
+ api_version=api_version,
+ azure_endpoint=endpoint,
+ azure_ad_token_provider=token_provider,
+ )
+ completion = await client.chat.completions.create(
+ model=deployment_name,
+ messages=[
+ {
+ "role": "user",
+ "content": "How do I output all files in a directory using Python?",
+ }
+ ],
+ )
-class Query(BaseModel):
- table_name: Table
- columns: List[Column]
- conditions: List[Condition]
- order_by: OrderBy
+ print(completion.to_json())
-client = OpenAI()
+sync_main()
+
+asyncio.run(async_main())
-completion = client.chat.completions.parse(
- model="gpt-4o-2024-08-06",
- messages=[
- {
- "role": "system",
- "content": "You are a helpful assistant. The current date is August 6, 2024. You help users query for the data they are looking for by calling the query function.",
- },
- {
- "role": "user",
- "content": "look up all my orders in november of last year that were fulfilled but not delivered on time",
- },
```
-This class is important because it defines how OpenAI Python SDK Tutorial: Production API Patterns implements the patterns covered in this chapter.
+This function is important because it defines how OpenAI Python SDK Tutorial: Production API Patterns implements the patterns covered in this chapter.
### `examples/parsing_tools.py`
-The `Condition` class in [`examples/parsing_tools.py`](https://github.com/openai/openai-python/blob/HEAD/examples/parsing_tools.py) handles a key part of this chapter's functionality:
+The `Table` class in [`examples/parsing_tools.py`](https://github.com/openai/openai-python/blob/HEAD/examples/parsing_tools.py) handles a key part of this chapter's functionality:
```py
-class Condition(BaseModel):
- column: str
- operator: Operator
- value: Union[str, int, DynamicValue]
+class Table(str, Enum):
+ orders = "orders"
+ customers = "customers"
+ products = "products"
-class Query(BaseModel):
- table_name: Table
- columns: List[Column]
- conditions: List[Condition]
- order_by: OrderBy
+class Column(str, Enum):
+ id = "id"
+ status = "status"
+ expected_delivery_date = "expected_delivery_date"
+ delivered_at = "delivered_at"
+ shipped_at = "shipped_at"
+ ordered_at = "ordered_at"
+ canceled_at = "canceled_at"
-client = OpenAI()
+class Operator(str, Enum):
+ eq = "="
+ gt = ">"
+ lt = "<"
+ le = "<="
+ ge = ">="
+ ne = "!="
+
+
+class OrderBy(str, Enum):
+ asc = "asc"
+ desc = "desc"
+
-completion = client.chat.completions.parse(
- model="gpt-4o-2024-08-06",
- messages=[
- {
- "role": "system",
- "content": "You are a helpful assistant. The current date is August 6, 2024. You help users query for the data they are looking for by calling the query function.",
- },
- {
- "role": "user",
- "content": "look up all my orders in november of last year that were fulfilled but not delivered on time",
- },
- ],
- tools=[
- openai.pydantic_function_tool(Query),
- ],
```
This class is important because it defines how OpenAI Python SDK Tutorial: Production API Patterns implements the patterns covered in this chapter.
@@ -196,9 +192,9 @@ This class is important because it defines how OpenAI Python SDK Tutorial: Produ
```mermaid
flowchart TD
- A[OrderBy]
- B[DynamicValue]
- C[Condition]
+ A[sync_main]
+ B[async_main]
+ C[Table]
A --> B
B --> C
```
diff --git a/tutorials/openai-python-sdk-tutorial/03-embeddings-search.md b/tutorials/openai-python-sdk-tutorial/03-embeddings-search.md
index be38ad1f..cf551e00 100644
--- a/tutorials/openai-python-sdk-tutorial/03-embeddings-search.md
+++ b/tutorials/openai-python-sdk-tutorial/03-embeddings-search.md
@@ -55,115 +55,139 @@ You now have the core pieces to build and evaluate a robust embeddings-backed re
Next: [Chapter 4: Agents and Assistants](04-assistants-api.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `examples/parsing_tools.py`
-The `Query` class in [`examples/parsing_tools.py`](https://github.com/openai/openai-python/blob/HEAD/examples/parsing_tools.py) handles a key part of this chapter's functionality:
+The `Column` class in [`examples/parsing_tools.py`](https://github.com/openai/openai-python/blob/HEAD/examples/parsing_tools.py) handles a key part of this chapter's functionality:
```py
-class Query(BaseModel):
- table_name: Table
- columns: List[Column]
- conditions: List[Condition]
- order_by: OrderBy
+class Column(str, Enum):
+ id = "id"
+ status = "status"
+ expected_delivery_date = "expected_delivery_date"
+ delivered_at = "delivered_at"
+ shipped_at = "shipped_at"
+ ordered_at = "ordered_at"
+ canceled_at = "canceled_at"
-client = OpenAI()
+class Operator(str, Enum):
+ eq = "="
+ gt = ">"
+ lt = "<"
+ le = "<="
+ ge = ">="
+ ne = "!="
-completion = client.chat.completions.parse(
- model="gpt-4o-2024-08-06",
- messages=[
- {
- "role": "system",
- "content": "You are a helpful assistant. The current date is August 6, 2024. You help users query for the data they are looking for by calling the query function.",
- },
- {
- "role": "user",
- "content": "look up all my orders in november of last year that were fulfilled but not delivered on time",
- },
- ],
- tools=[
- openai.pydantic_function_tool(Query),
- ],
-)
-tool_call = (completion.choices[0].message.tool_calls or [])[0]
-rich.print(tool_call.function)
-assert isinstance(tool_call.function.parsed_arguments, Query)
-print(tool_call.function.parsed_arguments.table_name)
+class OrderBy(str, Enum):
+ asc = "asc"
+ desc = "desc"
+
+
+class DynamicValue(BaseModel):
+ column_name: str
+
+
+class Condition(BaseModel):
+ column: str
```
This class is important because it defines how OpenAI Python SDK Tutorial: Production API Patterns implements the patterns covered in this chapter.
### `examples/parsing_tools.py`
-The `import` interface in [`examples/parsing_tools.py`](https://github.com/openai/openai-python/blob/HEAD/examples/parsing_tools.py) handles a key part of this chapter's functionality:
+The `Operator` class in [`examples/parsing_tools.py`](https://github.com/openai/openai-python/blob/HEAD/examples/parsing_tools.py) handles a key part of this chapter's functionality:
```py
-from enum import Enum
-from typing import List, Union
-import rich
-from pydantic import BaseModel
-import openai
-from openai import OpenAI
+class Operator(str, Enum):
+ eq = "="
+ gt = ">"
+ lt = "<"
+ le = "<="
+ ge = ">="
+ ne = "!="
-class Table(str, Enum):
- orders = "orders"
- customers = "customers"
- products = "products"
+class OrderBy(str, Enum):
+ asc = "asc"
+ desc = "desc"
-class Column(str, Enum):
- id = "id"
- status = "status"
- expected_delivery_date = "expected_delivery_date"
- delivered_at = "delivered_at"
- shipped_at = "shipped_at"
- ordered_at = "ordered_at"
- canceled_at = "canceled_at"
+class DynamicValue(BaseModel):
+ column_name: str
-class Operator(str, Enum):
- eq = "="
- gt = ">"
- lt = "<"
+class Condition(BaseModel):
+ column: str
+ operator: Operator
+ value: Union[str, int, DynamicValue]
+
+
+class Query(BaseModel):
+ table_name: Table
+ columns: List[Column]
+ conditions: List[Condition]
+ order_by: OrderBy
+
```
-This interface is important because it defines how OpenAI Python SDK Tutorial: Production API Patterns implements the patterns covered in this chapter.
+This class is important because it defines how OpenAI Python SDK Tutorial: Production API Patterns implements the patterns covered in this chapter.
-### `noxfile.py`
+### `examples/parsing_tools.py`
-The `test_pydantic_v1` function in [`noxfile.py`](https://github.com/openai/openai-python/blob/HEAD/noxfile.py) handles a key part of this chapter's functionality:
+The `OrderBy` class in [`examples/parsing_tools.py`](https://github.com/openai/openai-python/blob/HEAD/examples/parsing_tools.py) handles a key part of this chapter's functionality:
```py
-@nox.session(reuse_venv=True, name="test-pydantic-v1")
-def test_pydantic_v1(session: nox.Session) -> None:
- session.install("-r", "requirements-dev.lock")
- session.install("pydantic<2")
- session.run("pytest", "--showlocals", "--ignore=tests/functional", *session.posargs)
+class OrderBy(str, Enum):
+ asc = "asc"
+ desc = "desc"
+
+
+class DynamicValue(BaseModel):
+ column_name: str
+
+class Condition(BaseModel):
+ column: str
+ operator: Operator
+ value: Union[str, int, DynamicValue]
+
+
+class Query(BaseModel):
+ table_name: Table
+ columns: List[Column]
+ conditions: List[Condition]
+ order_by: OrderBy
+
+
+client = OpenAI()
+
+completion = client.chat.completions.parse(
+ model="gpt-4o-2024-08-06",
+ messages=[
+ {
+ "role": "system",
+ "content": "You are a helpful assistant. The current date is August 6, 2024. You help users query for the data they are looking for by calling the query function.",
```
-This function is important because it defines how OpenAI Python SDK Tutorial: Production API Patterns implements the patterns covered in this chapter.
+This class is important because it defines how OpenAI Python SDK Tutorial: Production API Patterns implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[Query]
- B[import]
- C[test_pydantic_v1]
+ A[Column]
+ B[Operator]
+ C[OrderBy]
A --> B
B --> C
```
diff --git a/tutorials/openai-python-sdk-tutorial/04-assistants-api.md b/tutorials/openai-python-sdk-tutorial/04-assistants-api.md
index 750eff99..f8528c85 100644
--- a/tutorials/openai-python-sdk-tutorial/04-assistants-api.md
+++ b/tutorials/openai-python-sdk-tutorial/04-assistants-api.md
@@ -61,141 +61,139 @@ You can now manage assistant-era systems while executing a controlled migration
Next: [Chapter 5: Batch Processing](05-batch-processing.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `scripts/detect-breaking-changes.py`
+### `examples/parsing_tools.py`
-The `public_members` function in [`scripts/detect-breaking-changes.py`](https://github.com/openai/openai-python/blob/HEAD/scripts/detect-breaking-changes.py) handles a key part of this chapter's functionality:
+The `DynamicValue` class in [`examples/parsing_tools.py`](https://github.com/openai/openai-python/blob/HEAD/examples/parsing_tools.py) handles a key part of this chapter's functionality:
```py
-def public_members(obj: griffe.Object | griffe.Alias) -> dict[str, griffe.Object | griffe.Alias]:
- if isinstance(obj, griffe.Alias):
- # ignore imports for now, they're technically part of the public API
- # but we don't have good preventative measures in place to prevent
- # changing them
- return {}
-
- return {name: value for name, value in obj.all_members.items() if not name.startswith("_")}
-
-
-def find_breaking_changes(
- new_obj: griffe.Object | griffe.Alias,
- old_obj: griffe.Object | griffe.Alias,
- *,
- path: list[str],
-) -> Iterator[Text | str]:
- new_members = public_members(new_obj)
- old_members = public_members(old_obj)
-
- for name, old_member in old_members.items():
- if isinstance(old_member, griffe.Alias) and len(path) > 2:
- # ignore imports in `/types/` for now, they're technically part of the public API
- # but we don't have good preventative measures in place to prevent changing them
- continue
-
- new_member = new_members.get(name)
- if new_member is None:
- cls_name = old_member.__class__.__name__
- yield Text(f"({cls_name})", style=Style(color="rgb(119, 119, 119)"))
- yield from [" " for _ in range(10 - len(cls_name))]
-```
+class DynamicValue(BaseModel):
+ column_name: str
-This function is important because it defines how OpenAI Python SDK Tutorial: Production API Patterns implements the patterns covered in this chapter.
-### `scripts/detect-breaking-changes.py`
+class Condition(BaseModel):
+ column: str
+ operator: Operator
+ value: Union[str, int, DynamicValue]
-The `find_breaking_changes` function in [`scripts/detect-breaking-changes.py`](https://github.com/openai/openai-python/blob/HEAD/scripts/detect-breaking-changes.py) handles a key part of this chapter's functionality:
-```py
+class Query(BaseModel):
+ table_name: Table
+ columns: List[Column]
+ conditions: List[Condition]
+ order_by: OrderBy
-def find_breaking_changes(
- new_obj: griffe.Object | griffe.Alias,
- old_obj: griffe.Object | griffe.Alias,
- *,
- path: list[str],
-) -> Iterator[Text | str]:
- new_members = public_members(new_obj)
- old_members = public_members(old_obj)
-
- for name, old_member in old_members.items():
- if isinstance(old_member, griffe.Alias) and len(path) > 2:
- # ignore imports in `/types/` for now, they're technically part of the public API
- # but we don't have good preventative measures in place to prevent changing them
- continue
-
- new_member = new_members.get(name)
- if new_member is None:
- cls_name = old_member.__class__.__name__
- yield Text(f"({cls_name})", style=Style(color="rgb(119, 119, 119)"))
- yield from [" " for _ in range(10 - len(cls_name))]
- yield f" {'.'.join(path)}.{name}"
- yield "\n"
- continue
-
- yield from find_breaking_changes(new_member, old_member, path=[*path, name])
-
-
-def main() -> None:
- try:
- against_ref = sys.argv[1]
+client = OpenAI()
+
+completion = client.chat.completions.parse(
+ model="gpt-4o-2024-08-06",
+ messages=[
+ {
+ "role": "system",
+ "content": "You are a helpful assistant. The current date is August 6, 2024. You help users query for the data they are looking for by calling the query function.",
+ },
+ {
+ "role": "user",
+ "content": "look up all my orders in november of last year that were fulfilled but not delivered on time",
+ },
```
-This function is important because it defines how OpenAI Python SDK Tutorial: Production API Patterns implements the patterns covered in this chapter.
+This class is important because it defines how OpenAI Python SDK Tutorial: Production API Patterns implements the patterns covered in this chapter.
-### `scripts/detect-breaking-changes.py`
+### `examples/parsing_tools.py`
-The `main` function in [`scripts/detect-breaking-changes.py`](https://github.com/openai/openai-python/blob/HEAD/scripts/detect-breaking-changes.py) handles a key part of this chapter's functionality:
+The `Condition` class in [`examples/parsing_tools.py`](https://github.com/openai/openai-python/blob/HEAD/examples/parsing_tools.py) handles a key part of this chapter's functionality:
```py
-def main() -> None:
- try:
- against_ref = sys.argv[1]
- except IndexError as err:
- raise RuntimeError("You must specify a base ref to run breaking change detection against") from err
+class Condition(BaseModel):
+ column: str
+ operator: Operator
+ value: Union[str, int, DynamicValue]
- package = griffe.load(
- "openai",
- search_paths=[Path(__file__).parent.parent.joinpath("src")],
- )
- old_package = griffe.load_git(
- "openai",
- ref=against_ref,
- search_paths=["src"],
- )
- assert isinstance(package, griffe.Module)
- assert isinstance(old_package, griffe.Module)
- output = list(find_breaking_changes(package, old_package, path=["openai"]))
- if output:
- rich.print(Text("Breaking changes detected!", style=Style(color="rgb(165, 79, 87)")))
- rich.print()
+class Query(BaseModel):
+ table_name: Table
+ columns: List[Column]
+ conditions: List[Condition]
+ order_by: OrderBy
+
+
+client = OpenAI()
+
+completion = client.chat.completions.parse(
+ model="gpt-4o-2024-08-06",
+ messages=[
+ {
+ "role": "system",
+ "content": "You are a helpful assistant. The current date is August 6, 2024. You help users query for the data they are looking for by calling the query function.",
+ },
+ {
+ "role": "user",
+ "content": "look up all my orders in november of last year that were fulfilled but not delivered on time",
+ },
+ ],
+ tools=[
+ openai.pydantic_function_tool(Query),
+ ],
+```
- for text in output:
- rich.print(text, end="")
+This class is important because it defines how OpenAI Python SDK Tutorial: Production API Patterns implements the patterns covered in this chapter.
- sys.exit(1)
+### `examples/parsing_tools.py`
+The `Query` class in [`examples/parsing_tools.py`](https://github.com/openai/openai-python/blob/HEAD/examples/parsing_tools.py) handles a key part of this chapter's functionality:
+
+```py
+
+
+class Query(BaseModel):
+ table_name: Table
+ columns: List[Column]
+ conditions: List[Condition]
+ order_by: OrderBy
+
+
+client = OpenAI()
+
+completion = client.chat.completions.parse(
+ model="gpt-4o-2024-08-06",
+ messages=[
+ {
+ "role": "system",
+ "content": "You are a helpful assistant. The current date is August 6, 2024. You help users query for the data they are looking for by calling the query function.",
+ },
+ {
+ "role": "user",
+ "content": "look up all my orders in november of last year that were fulfilled but not delivered on time",
+ },
+ ],
+ tools=[
+ openai.pydantic_function_tool(Query),
+ ],
+)
-main()
+tool_call = (completion.choices[0].message.tool_calls or [])[0]
+rich.print(tool_call.function)
+assert isinstance(tool_call.function.parsed_arguments, Query)
+print(tool_call.function.parsed_arguments.table_name)
```
-This function is important because it defines how OpenAI Python SDK Tutorial: Production API Patterns implements the patterns covered in this chapter.
+This class is important because it defines how OpenAI Python SDK Tutorial: Production API Patterns implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[public_members]
- B[find_breaking_changes]
- C[main]
+ A[DynamicValue]
+ B[Condition]
+ C[Query]
A --> B
B --> C
```
diff --git a/tutorials/openai-python-sdk-tutorial/05-batch-processing.md b/tutorials/openai-python-sdk-tutorial/05-batch-processing.md
index 5446456f..34bde99f 100644
--- a/tutorials/openai-python-sdk-tutorial/05-batch-processing.md
+++ b/tutorials/openai-python-sdk-tutorial/05-batch-processing.md
@@ -69,89 +69,46 @@ You now have a scalable asynchronous processing pattern for bulk OpenAI workload
Next: [Chapter 6: Fine-Tuning](06-fine-tuning.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `examples/azure_ad.py`
-
-The `sync_main` function in [`examples/azure_ad.py`](https://github.com/openai/openai-python/blob/HEAD/examples/azure_ad.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def sync_main() -> None:
- from azure.identity import DefaultAzureCredential, get_bearer_token_provider
-
- token_provider: AzureADTokenProvider = get_bearer_token_provider(DefaultAzureCredential(), scopes)
-
- client = AzureOpenAI(
- api_version=api_version,
- azure_endpoint=endpoint,
- azure_ad_token_provider=token_provider,
- )
-
- completion = client.chat.completions.create(
- model=deployment_name,
- messages=[
- {
- "role": "user",
- "content": "How do I output all files in a directory using Python?",
- }
- ],
- )
-
- print(completion.to_json())
-
-
-async def async_main() -> None:
- from azure.identity.aio import DefaultAzureCredential, get_bearer_token_provider
-
- token_provider: AsyncAzureADTokenProvider = get_bearer_token_provider(DefaultAzureCredential(), scopes)
-
- client = AsyncAzureOpenAI(
-```
-
-This function is important because it defines how OpenAI Python SDK Tutorial: Production API Patterns implements the patterns covered in this chapter.
-
-### `examples/azure_ad.py`
+### `examples/parsing_tools.py`
-The `async_main` function in [`examples/azure_ad.py`](https://github.com/openai/openai-python/blob/HEAD/examples/azure_ad.py) handles a key part of this chapter's functionality:
+The `import` interface in [`examples/parsing_tools.py`](https://github.com/openai/openai-python/blob/HEAD/examples/parsing_tools.py) handles a key part of this chapter's functionality:
```py
+from enum import Enum
+from typing import List, Union
+import rich
+from pydantic import BaseModel
-async def async_main() -> None:
- from azure.identity.aio import DefaultAzureCredential, get_bearer_token_provider
-
- token_provider: AsyncAzureADTokenProvider = get_bearer_token_provider(DefaultAzureCredential(), scopes)
-
- client = AsyncAzureOpenAI(
- api_version=api_version,
- azure_endpoint=endpoint,
- azure_ad_token_provider=token_provider,
- )
+import openai
+from openai import OpenAI
- completion = await client.chat.completions.create(
- model=deployment_name,
- messages=[
- {
- "role": "user",
- "content": "How do I output all files in a directory using Python?",
- }
- ],
- )
- print(completion.to_json())
+class Table(str, Enum):
+ orders = "orders"
+ customers = "customers"
+ products = "products"
-sync_main()
+class Column(str, Enum):
+ id = "id"
+ status = "status"
+ expected_delivery_date = "expected_delivery_date"
+ delivered_at = "delivered_at"
+ shipped_at = "shipped_at"
+ ordered_at = "ordered_at"
+ canceled_at = "canceled_at"
-asyncio.run(async_main())
+class Operator(str, Enum):
+ eq = "="
+ gt = ">"
+ lt = "<"
```
-This function is important because it defines how OpenAI Python SDK Tutorial: Production API Patterns implements the patterns covered in this chapter.
+This interface is important because it defines how OpenAI Python SDK Tutorial: Production API Patterns implements the patterns covered in this chapter.
### `examples/image_stream.py`
@@ -194,13 +151,54 @@ def main() -> None:
This function is important because it defines how OpenAI Python SDK Tutorial: Production API Patterns implements the patterns covered in this chapter.
+### `examples/responses_input_tokens.py`
+
+The `main` function in [`examples/responses_input_tokens.py`](https://github.com/openai/openai-python/blob/HEAD/examples/responses_input_tokens.py) handles a key part of this chapter's functionality:
+
+```py
+
+
+def main() -> None:
+ client = OpenAI()
+ tools: List[ToolParam] = [
+ {
+ "type": "function",
+ "name": "get_current_weather",
+ "description": "Get current weather in a given location",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "location": {
+ "type": "string",
+ "description": "City and state, e.g. San Francisco, CA",
+ },
+ "unit": {
+ "type": "string",
+ "enum": ["c", "f"],
+ "description": "Temperature unit to use",
+ },
+ },
+ "required": ["location", "unit"],
+ "additionalProperties": False,
+ },
+ "strict": True,
+ }
+ ]
+
+ input_items: List[ResponseInputItemParam] = [
+ {
+ "type": "message",
+```
+
+This function is important because it defines how OpenAI Python SDK Tutorial: Production API Patterns implements the patterns covered in this chapter.
+
## How These Components Connect
```mermaid
flowchart TD
- A[sync_main]
- B[async_main]
+ A[import]
+ B[main]
C[main]
A --> B
B --> C
diff --git a/tutorials/openai-python-sdk-tutorial/06-fine-tuning.md b/tutorials/openai-python-sdk-tutorial/06-fine-tuning.md
index c173dac1..69e62b56 100644
--- a/tutorials/openai-python-sdk-tutorial/06-fine-tuning.md
+++ b/tutorials/openai-python-sdk-tutorial/06-fine-tuning.md
@@ -50,99 +50,97 @@ You now have a pragmatic fine-tuning workflow from data curation to job monitori
Next: [Chapter 7: Advanced Patterns](07-advanced-patterns.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `examples/responses_input_tokens.py`
+### `examples/streaming.py`
-The `main` function in [`examples/responses_input_tokens.py`](https://github.com/openai/openai-python/blob/HEAD/examples/responses_input_tokens.py) handles a key part of this chapter's functionality:
+The `sync_main` function in [`examples/streaming.py`](https://github.com/openai/openai-python/blob/HEAD/examples/streaming.py) handles a key part of this chapter's functionality:
```py
-def main() -> None:
+def sync_main() -> None:
client = OpenAI()
- tools: List[ToolParam] = [
- {
- "type": "function",
- "name": "get_current_weather",
- "description": "Get current weather in a given location",
- "parameters": {
- "type": "object",
- "properties": {
- "location": {
- "type": "string",
- "description": "City and state, e.g. San Francisco, CA",
- },
- "unit": {
- "type": "string",
- "enum": ["c", "f"],
- "description": "Temperature unit to use",
- },
- },
- "required": ["location", "unit"],
- "additionalProperties": False,
- },
- "strict": True,
- }
- ]
-
- input_items: List[ResponseInputItemParam] = [
- {
- "type": "message",
+ response = client.completions.create(
+ model="gpt-3.5-turbo-instruct",
+ prompt="1,2,3,",
+ max_tokens=5,
+ temperature=0,
+ stream=True,
+ )
+
+ # You can manually control iteration over the response
+ first = next(response)
+ print(f"got response data: {first.to_json()}")
+
+ # Or you could automatically iterate through all of data.
+ # Note that the for loop will not exit until *all* of the data has been processed.
+ for data in response:
+ print(data.to_json())
+
+
+async def async_main() -> None:
+ client = AsyncOpenAI()
+ response = await client.completions.create(
+ model="gpt-3.5-turbo-instruct",
+ prompt="1,2,3,",
+ max_tokens=5,
+ temperature=0,
+ stream=True,
+ )
+
```
This function is important because it defines how OpenAI Python SDK Tutorial: Production API Patterns implements the patterns covered in this chapter.
-### `examples/parsing_stream.py`
+### `examples/streaming.py`
-The `Step` class in [`examples/parsing_stream.py`](https://github.com/openai/openai-python/blob/HEAD/examples/parsing_stream.py) handles a key part of this chapter's functionality:
+The `async_main` function in [`examples/streaming.py`](https://github.com/openai/openai-python/blob/HEAD/examples/streaming.py) handles a key part of this chapter's functionality:
```py
-class Step(BaseModel):
- explanation: str
- output: str
+async def async_main() -> None:
+ client = AsyncOpenAI()
+ response = await client.completions.create(
+ model="gpt-3.5-turbo-instruct",
+ prompt="1,2,3,",
+ max_tokens=5,
+ temperature=0,
+ stream=True,
+ )
+ # You can manually control iteration over the response.
+ # In Python 3.10+ you can also use the `await anext(response)` builtin instead
+ first = await response.__anext__()
+ print(f"got response data: {first.to_json()}")
-class MathResponse(BaseModel):
- steps: List[Step]
- final_answer: str
+ # Or you could automatically iterate through all of data.
+ # Note that the for loop will not exit until *all* of the data has been processed.
+ async for data in response:
+ print(data.to_json())
-client = OpenAI()
+sync_main()
+
+asyncio.run(async_main())
-with client.chat.completions.stream(
- model="gpt-4o-2024-08-06",
- messages=[
- {"role": "system", "content": "You are a helpful math tutor."},
- {"role": "user", "content": "solve 8x + 31 = 2"},
- ],
- response_format=MathResponse,
-) as stream:
- for event in stream:
- if event.type == "content.delta":
- print(event.delta, end="", flush=True)
- elif event.type == "content.done":
- print("\n")
- if event.parsed is not None:
- print(f"answer: {event.parsed.final_answer}")
- elif event.type == "refusal.delta":
- print(event.delta, end="", flush=True)
- elif event.type == "refusal.done":
```
-This class is important because it defines how OpenAI Python SDK Tutorial: Production API Patterns implements the patterns covered in this chapter.
+This function is important because it defines how OpenAI Python SDK Tutorial: Production API Patterns implements the patterns covered in this chapter.
### `examples/parsing_stream.py`
-The `MathResponse` class in [`examples/parsing_stream.py`](https://github.com/openai/openai-python/blob/HEAD/examples/parsing_stream.py) handles a key part of this chapter's functionality:
+The `Step` class in [`examples/parsing_stream.py`](https://github.com/openai/openai-python/blob/HEAD/examples/parsing_stream.py) handles a key part of this chapter's functionality:
```py
+class Step(BaseModel):
+ explanation: str
+ output: str
+
+
class MathResponse(BaseModel):
steps: List[Step]
final_answer: str
@@ -168,11 +166,6 @@ with client.chat.completions.stream(
elif event.type == "refusal.delta":
print(event.delta, end="", flush=True)
elif event.type == "refusal.done":
- print()
-
-print("---------------")
-rich.print(stream.get_final_completion())
-
```
This class is important because it defines how OpenAI Python SDK Tutorial: Production API Patterns implements the patterns covered in this chapter.
@@ -182,9 +175,9 @@ This class is important because it defines how OpenAI Python SDK Tutorial: Produ
```mermaid
flowchart TD
- A[main]
- B[Step]
- C[MathResponse]
+ A[sync_main]
+ B[async_main]
+ C[Step]
A --> B
B --> C
```
diff --git a/tutorials/openai-python-sdk-tutorial/07-advanced-patterns.md b/tutorials/openai-python-sdk-tutorial/07-advanced-patterns.md
index c92cba41..dbbea090 100644
--- a/tutorials/openai-python-sdk-tutorial/07-advanced-patterns.md
+++ b/tutorials/openai-python-sdk-tutorial/07-advanced-patterns.md
@@ -57,86 +57,89 @@ You now have practical building blocks for resilient, cost-aware, and debuggable
Next: [Chapter 8: Integration Examples](08-integration-examples.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `examples/streaming.py`
+### `examples/parsing_stream.py`
-The `sync_main` function in [`examples/streaming.py`](https://github.com/openai/openai-python/blob/HEAD/examples/streaming.py) handles a key part of this chapter's functionality:
+The `MathResponse` class in [`examples/parsing_stream.py`](https://github.com/openai/openai-python/blob/HEAD/examples/parsing_stream.py) handles a key part of this chapter's functionality:
```py
-def sync_main() -> None:
- client = OpenAI()
- response = client.completions.create(
- model="gpt-3.5-turbo-instruct",
- prompt="1,2,3,",
- max_tokens=5,
- temperature=0,
- stream=True,
- )
-
- # You can manually control iteration over the response
- first = next(response)
- print(f"got response data: {first.to_json()}")
-
- # Or you could automatically iterate through all of data.
- # Note that the for loop will not exit until *all* of the data has been processed.
- for data in response:
- print(data.to_json())
-
-
-async def async_main() -> None:
- client = AsyncOpenAI()
- response = await client.completions.create(
- model="gpt-3.5-turbo-instruct",
- prompt="1,2,3,",
- max_tokens=5,
- temperature=0,
- stream=True,
- )
+class MathResponse(BaseModel):
+ steps: List[Step]
+ final_answer: str
+
+
+client = OpenAI()
+
+with client.chat.completions.stream(
+ model="gpt-4o-2024-08-06",
+ messages=[
+ {"role": "system", "content": "You are a helpful math tutor."},
+ {"role": "user", "content": "solve 8x + 31 = 2"},
+ ],
+ response_format=MathResponse,
+) as stream:
+ for event in stream:
+ if event.type == "content.delta":
+ print(event.delta, end="", flush=True)
+ elif event.type == "content.done":
+ print("\n")
+ if event.parsed is not None:
+ print(f"answer: {event.parsed.final_answer}")
+ elif event.type == "refusal.delta":
+ print(event.delta, end="", flush=True)
+ elif event.type == "refusal.done":
+ print()
+
+print("---------------")
+rich.print(stream.get_final_completion())
```
-This function is important because it defines how OpenAI Python SDK Tutorial: Production API Patterns implements the patterns covered in this chapter.
+This class is important because it defines how OpenAI Python SDK Tutorial: Production API Patterns implements the patterns covered in this chapter.
-### `examples/streaming.py`
+### `examples/parsing_tools_stream.py`
-The `async_main` function in [`examples/streaming.py`](https://github.com/openai/openai-python/blob/HEAD/examples/streaming.py) handles a key part of this chapter's functionality:
+The `GetWeather` class in [`examples/parsing_tools_stream.py`](https://github.com/openai/openai-python/blob/HEAD/examples/parsing_tools_stream.py) handles a key part of this chapter's functionality:
```py
-async def async_main() -> None:
- client = AsyncOpenAI()
- response = await client.completions.create(
- model="gpt-3.5-turbo-instruct",
- prompt="1,2,3,",
- max_tokens=5,
- temperature=0,
- stream=True,
- )
+class GetWeather(BaseModel):
+ city: str
+ country: str
- # You can manually control iteration over the response.
- # In Python 3.10+ you can also use the `await anext(response)` builtin instead
- first = await response.__anext__()
- print(f"got response data: {first.to_json()}")
- # Or you could automatically iterate through all of data.
- # Note that the for loop will not exit until *all* of the data has been processed.
- async for data in response:
- print(data.to_json())
+client = OpenAI()
-sync_main()
+with client.chat.completions.stream(
+ model="gpt-4o-2024-08-06",
+ messages=[
+ {
+ "role": "user",
+ "content": "What's the weather like in SF and New York?",
+ },
+ ],
+ tools=[
+ # because we're using `.parse_stream()`, the returned tool calls
+ # will be automatically deserialized into this `GetWeather` type
+ openai.pydantic_function_tool(GetWeather, name="get_weather"),
+ ],
+ parallel_tool_calls=True,
+) as stream:
+ for event in stream:
+ if event.type == "tool_calls.function.arguments.delta" or event.type == "tool_calls.function.arguments.done":
+ rich.get_console().print(event, width=80)
-asyncio.run(async_main())
+print("----\n")
+rich.print(stream.get_final_completion())
```
-This function is important because it defines how OpenAI Python SDK Tutorial: Production API Patterns implements the patterns covered in this chapter.
+This class is important because it defines how OpenAI Python SDK Tutorial: Production API Patterns implements the patterns covered in this chapter.
### `examples/text_to_speech.py`
@@ -174,8 +177,8 @@ This function is important because it defines how OpenAI Python SDK Tutorial: Pr
```mermaid
flowchart TD
- A[sync_main]
- B[async_main]
+ A[MathResponse]
+ B[GetWeather]
C[main]
A --> B
B --> C
diff --git a/tutorials/openai-python-sdk-tutorial/08-integration-examples.md b/tutorials/openai-python-sdk-tutorial/08-integration-examples.md
index daacc712..ff1f5245 100644
--- a/tutorials/openai-python-sdk-tutorial/08-integration-examples.md
+++ b/tutorials/openai-python-sdk-tutorial/08-integration-examples.md
@@ -62,110 +62,116 @@ Related:
- [OpenAI Realtime Agents Tutorial](../openai-realtime-agents-tutorial/)
- [OpenAI Whisper Tutorial](../openai-whisper-tutorial/)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `examples/parsing_tools_stream.py`
+### `examples/audio.py`
-The `GetWeather` class in [`examples/parsing_tools_stream.py`](https://github.com/openai/openai-python/blob/HEAD/examples/parsing_tools_stream.py) handles a key part of this chapter's functionality:
+The `main` function in [`examples/audio.py`](https://github.com/openai/openai-python/blob/HEAD/examples/audio.py) handles a key part of this chapter's functionality:
```py
-class GetWeather(BaseModel):
- city: str
- country: str
+def main() -> None:
+ # Create text-to-speech audio file
+ with openai.audio.speech.with_streaming_response.create(
+ model="tts-1",
+ voice="alloy",
+ input="the quick brown fox jumped over the lazy dogs",
+ ) as response:
+ response.stream_to_file(speech_file_path)
+ # Create transcription from audio file
+ transcription = openai.audio.transcriptions.create(
+ model="whisper-1",
+ file=speech_file_path,
+ )
+ print(transcription.text)
-client = OpenAI()
+ # Create translation from audio file
+ translation = openai.audio.translations.create(
+ model="whisper-1",
+ file=speech_file_path,
+ )
+ print(translation.text)
-with client.chat.completions.stream(
- model="gpt-4o-2024-08-06",
- messages=[
- {
- "role": "user",
- "content": "What's the weather like in SF and New York?",
- },
- ],
- tools=[
- # because we're using `.parse_stream()`, the returned tool calls
- # will be automatically deserialized into this `GetWeather` type
- openai.pydantic_function_tool(GetWeather, name="get_weather"),
- ],
- parallel_tool_calls=True,
-) as stream:
- for event in stream:
- if event.type == "tool_calls.function.arguments.delta" or event.type == "tool_calls.function.arguments.done":
- rich.get_console().print(event, width=80)
-
-print("----\n")
-rich.print(stream.get_final_completion())
+if __name__ == "__main__":
+ main()
```
-This class is important because it defines how OpenAI Python SDK Tutorial: Production API Patterns implements the patterns covered in this chapter.
+This function is important because it defines how OpenAI Python SDK Tutorial: Production API Patterns implements the patterns covered in this chapter.
-### `examples/speech_to_text.py`
+### `examples/uploads.py`
-The `main` function in [`examples/speech_to_text.py`](https://github.com/openai/openai-python/blob/HEAD/examples/speech_to_text.py) handles a key part of this chapter's functionality:
+The `from_disk` function in [`examples/uploads.py`](https://github.com/openai/openai-python/blob/HEAD/examples/uploads.py) handles a key part of this chapter's functionality:
```py
-async def main() -> None:
- print("Recording for the next 10 seconds...")
- recording = await Microphone(timeout=10).record()
- print("Recording complete")
- transcription = await openai.audio.transcriptions.create(
- model="whisper-1",
- file=recording,
+def from_disk() -> None:
+ print("uploading file from disk")
+
+ upload = client.uploads.upload_file_chunked(
+ file=file,
+ mime_type="txt",
+ purpose="batch",
)
+ rich.print(upload)
- print(transcription.text)
+def from_in_memory() -> None:
+ print("uploading file from memory")
-if __name__ == "__main__":
- asyncio.run(main())
+ # read the data into memory ourselves to simulate
+ # it coming from somewhere else
+ data = file.read_bytes()
+ filename = "my_file.txt"
+
+ upload = client.uploads.upload_file_chunked(
+ file=data,
+ filename=filename,
+ bytes=len(data),
+ mime_type="txt",
+ purpose="batch",
+ )
+ rich.print(upload)
+
+if "memory" in sys.argv:
```
This function is important because it defines how OpenAI Python SDK Tutorial: Production API Patterns implements the patterns covered in this chapter.
-### `examples/audio.py`
+### `examples/uploads.py`
-The `main` function in [`examples/audio.py`](https://github.com/openai/openai-python/blob/HEAD/examples/audio.py) handles a key part of this chapter's functionality:
+The `from_in_memory` function in [`examples/uploads.py`](https://github.com/openai/openai-python/blob/HEAD/examples/uploads.py) handles a key part of this chapter's functionality:
```py
-def main() -> None:
- # Create text-to-speech audio file
- with openai.audio.speech.with_streaming_response.create(
- model="tts-1",
- voice="alloy",
- input="the quick brown fox jumped over the lazy dogs",
- ) as response:
- response.stream_to_file(speech_file_path)
+def from_in_memory() -> None:
+ print("uploading file from memory")
- # Create transcription from audio file
- transcription = openai.audio.transcriptions.create(
- model="whisper-1",
- file=speech_file_path,
- )
- print(transcription.text)
+ # read the data into memory ourselves to simulate
+ # it coming from somewhere else
+ data = file.read_bytes()
+ filename = "my_file.txt"
- # Create translation from audio file
- translation = openai.audio.translations.create(
- model="whisper-1",
- file=speech_file_path,
+ upload = client.uploads.upload_file_chunked(
+ file=data,
+ filename=filename,
+ bytes=len(data),
+ mime_type="txt",
+ purpose="batch",
)
- print(translation.text)
+ rich.print(upload)
-if __name__ == "__main__":
- main()
+if "memory" in sys.argv:
+ from_in_memory()
+else:
+ from_disk()
```
@@ -176,9 +182,9 @@ This function is important because it defines how OpenAI Python SDK Tutorial: Pr
```mermaid
flowchart TD
- A[GetWeather]
- B[main]
- C[main]
+ A[main]
+ B[from_disk]
+ C[from_in_memory]
A --> B
B --> C
```
diff --git a/tutorials/openai-realtime-agents-tutorial/01-getting-started.md b/tutorials/openai-realtime-agents-tutorial/01-getting-started.md
index 418fdae0..c936d3be 100644
--- a/tutorials/openai-realtime-agents-tutorial/01-getting-started.md
+++ b/tutorials/openai-realtime-agents-tutorial/01-getting-started.md
@@ -103,8 +103,6 @@ You now have a reproducible local baseline and a structured way to verify realti
Next: [Chapter 2: Realtime API Fundamentals](02-realtime-api-fundamentals.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `src/app/page.tsx`
@@ -130,29 +128,6 @@ export default function Page() {
This function is important because it defines how OpenAI Realtime Agents Tutorial: Voice-First AI Systems implements the patterns covered in this chapter.
-### `src/app/layout.tsx`
-
-The `RootLayout` function in [`src/app/layout.tsx`](https://github.com/openai/openai-realtime-agents/blob/HEAD/src/app/layout.tsx) handles a key part of this chapter's functionality:
-
-```tsx
-};
-
-export default function RootLayout({
- children,
-}: Readonly<{
- children: React.ReactNode;
-}>) {
- return (
- <html lang="en">
- <body className={`antialiased`}>{children}</body>
- </html>
- );
-}
-
-```
-
-This function is important because it defines how OpenAI Realtime Agents Tutorial: Voice-First AI Systems implements the patterns covered in this chapter.
-
### `src/app/types.ts`
The `ToolParameterProperty` interface in [`src/app/types.ts`](https://github.com/openai/openai-realtime-agents/blob/HEAD/src/app/types.ts) handles a key part of this chapter's functionality:
@@ -235,16 +210,57 @@ export type AllAgentConfigsType = Record<string, AgentConfig[]>;
This interface is important because it defines how OpenAI Realtime Agents Tutorial: Voice-First AI Systems implements the patterns covered in this chapter.
+### `src/app/types.ts`
+
+The `Tool` interface in [`src/app/types.ts`](https://github.com/openai/openai-realtime-agents/blob/HEAD/src/app/types.ts) handles a key part of this chapter's functionality:
+
+```ts
+export type SessionStatus = "DISCONNECTED" | "CONNECTING" | "CONNECTED";
+
+export interface ToolParameterProperty {
+ type: string;
+ description?: string;
+ enum?: string[];
+ pattern?: string;
+ properties?: Record<string, ToolParameterProperty>;
+ required?: string[];
+ additionalProperties?: boolean;
+ items?: ToolParameterProperty;
+}
+
+export interface ToolParameters {
+ type: string;
+ properties: Record<string, ToolParameterProperty>;
+ required?: string[];
+ additionalProperties?: boolean;
+}
+
+export interface Tool {
+ type: "function";
+ name: string;
+ description: string;
+ parameters: ToolParameters;
+}
+
+export interface AgentConfig {
+ name: string;
+ publicDescription: string; // gives context to agent transfer tool
+ instructions: string;
+ tools: Tool[];
+```
+
+This interface is important because it defines how OpenAI Realtime Agents Tutorial: Voice-First AI Systems implements the patterns covered in this chapter.
+
## How These Components Connect
```mermaid
flowchart TD
A[Page]
- B[RootLayout]
- C[ToolParameterProperty]
- D[ToolParameters]
- E[Tool]
+ B[ToolParameterProperty]
+ C[ToolParameters]
+ D[Tool]
+ E[AgentConfig]
A --> B
B --> C
C --> D
diff --git a/tutorials/openai-realtime-agents-tutorial/02-realtime-api-fundamentals.md b/tutorials/openai-realtime-agents-tutorial/02-realtime-api-fundamentals.md
index 57c9366f..1bc490e0 100644
--- a/tutorials/openai-realtime-agents-tutorial/02-realtime-api-fundamentals.md
+++ b/tutorials/openai-realtime-agents-tutorial/02-realtime-api-fundamentals.md
@@ -81,53 +81,10 @@ You now understand the realtime lifecycle and have a framework for protocol-leve
Next: [Chapter 3: Voice Input Processing](03-voice-input-processing.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `src/app/types.ts`
-The `GuardrailResultType` interface in [`src/app/types.ts`](https://github.com/openai/openai-realtime-agents/blob/HEAD/src/app/types.ts) handles a key part of this chapter's functionality:
-
-```ts
-export type AllAgentConfigsType = Record<string, AgentConfig[]>;
-
-export interface GuardrailResultType {
- status: "IN_PROGRESS" | "DONE";
- testText?: string;
- category?: ModerationCategory;
- rationale?: string;
-}
-
-export interface TranscriptItem {
- itemId: string;
- type: "MESSAGE" | "BREADCRUMB";
- role?: "user" | "assistant";
- title?: string;
- data?: Record<string, any>;
- expanded: boolean;
- timestamp: string;
- createdAtMs: number;
- status: "IN_PROGRESS" | "DONE";
- isHidden: boolean;
- guardrailResult?: GuardrailResultType;
-}
-
-export interface Log {
- id: number;
- timestamp: string;
- direction: string;
- eventName: string;
- data: any;
- expanded: boolean;
- type: string;
-}
-```
-
-This interface is important because it defines how OpenAI Realtime Agents Tutorial: Voice-First AI Systems implements the patterns covered in this chapter.
-
-### `src/app/types.ts`
-
The `TranscriptItem` interface in [`src/app/types.ts`](https://github.com/openai/openai-realtime-agents/blob/HEAD/src/app/types.ts) handles a key part of this chapter's functionality:
```ts
@@ -249,16 +206,45 @@ export interface ServerEvent {
This interface is important because it defines how OpenAI Realtime Agents Tutorial: Voice-First AI Systems implements the patterns covered in this chapter.
+### `src/app/types.ts`
+
+The `LoggedEvent` interface in [`src/app/types.ts`](https://github.com/openai/openai-realtime-agents/blob/HEAD/src/app/types.ts) handles a key part of this chapter's functionality:
+
+```ts
+}
+
+export interface LoggedEvent {
+ id: number;
+ direction: "client" | "server";
+ expanded: boolean;
+ timestamp: string;
+ eventName: string;
+ eventData: Record<string, any>; // can have arbitrary objects logged
+}
+
+// Update the GuardrailOutputZod schema to use the shared ModerationCategoryZod
+export const GuardrailOutputZod = z.object({
+ moderationRationale: z.string(),
+ moderationCategory: ModerationCategoryZod,
+ testText: z.string().optional(),
+});
+
+export type GuardrailOutput = z.infer<typeof GuardrailOutputZod>;
+
+```
+
+This interface is important because it defines how OpenAI Realtime Agents Tutorial: Voice-First AI Systems implements the patterns covered in this chapter.
+
## How These Components Connect
```mermaid
flowchart TD
- A[GuardrailResultType]
- B[TranscriptItem]
- C[Log]
- D[ServerEvent]
- E[LoggedEvent]
+ A[TranscriptItem]
+ B[Log]
+ C[ServerEvent]
+ D[LoggedEvent]
+ E[based]
A --> B
B --> C
C --> D
diff --git a/tutorials/openai-realtime-agents-tutorial/03-voice-input-processing.md b/tutorials/openai-realtime-agents-tutorial/03-voice-input-processing.md
index 85ef6fde..daba91e6 100644
--- a/tutorials/openai-realtime-agents-tutorial/03-voice-input-processing.md
+++ b/tutorials/openai-realtime-agents-tutorial/03-voice-input-processing.md
@@ -83,8 +83,6 @@ You now have a robust input architecture pattern that supports low-latency conve
Next: [Chapter 4: Conversational AI](04-conversational-ai.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `src/app/App.tsx`
@@ -260,7 +258,7 @@ flowchart TD
B[Transcript]
C[scrollToBottom]
D[TranscriptProps]
- E[useRealtimeSession]
+ E[useHandleSessionHistory]
A --> B
B --> C
C --> D
diff --git a/tutorials/openai-realtime-agents-tutorial/04-conversational-ai.md b/tutorials/openai-realtime-agents-tutorial/04-conversational-ai.md
index c69bd7dd..b62a436e 100644
--- a/tutorials/openai-realtime-agents-tutorial/04-conversational-ai.md
+++ b/tutorials/openai-realtime-agents-tutorial/04-conversational-ai.md
@@ -83,170 +83,168 @@ You now have a conversation-design framework that holds up under interruption, a
Next: [Chapter 5: Function Calling](05-function-calling.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/app/hooks/useRealtimeSession.ts`
+### `src/app/hooks/useHandleSessionHistory.ts`
-The `RealtimeSessionCallbacks` interface in [`src/app/hooks/useRealtimeSession.ts`](https://github.com/openai/openai-realtime-agents/blob/HEAD/src/app/hooks/useRealtimeSession.ts) handles a key part of this chapter's functionality:
+The `handleAgentToolEnd` function in [`src/app/hooks/useHandleSessionHistory.ts`](https://github.com/openai/openai-realtime-agents/blob/HEAD/src/app/hooks/useHandleSessionHistory.ts) handles a key part of this chapter's functionality:
```ts
-import { SessionStatus } from '../types';
-
-export interface RealtimeSessionCallbacks {
- onConnectionChange?: (status: SessionStatus) => void;
- onAgentHandoff?: (agentName: string) => void;
-}
-
-export interface ConnectOptions {
- getEphemeralKey: () => Promise<string>;
- initialAgents: RealtimeAgent[];
- audioElement?: HTMLAudioElement;
- extraContext?: Record<string, any>;
- outputGuardrails?: any[];
-}
-
-export function useRealtimeSession(callbacks: RealtimeSessionCallbacks = {}) {
- const sessionRef = useRef<RealtimeSession | null>(null);
- const [status, setStatus] = useState<
- SessionStatus
- >('DISCONNECTED');
- const { logClientEvent } = useEvent();
-
- const updateStatus = useCallback(
- (s: SessionStatus) => {
- setStatus(s);
- callbacks.onConnectionChange?.(s);
- logClientEvent({}, s);
- },
- [callbacks],
- );
-
- const { logServerEvent } = useEvent();
+ );
+ }
+ function handleAgentToolEnd(details: any, _agent: any, _functionCall: any, result: any) {
+ const lastFunctionCall = extractFunctionCallByName(_functionCall.name, details?.context?.history);
+ addTranscriptBreadcrumb(
+ `function call result: ${lastFunctionCall?.name}`,
+ maybeParseJson(result)
+ );
+ }
+
+ function handleHistoryAdded(item: any) {
+ console.log("[handleHistoryAdded] ", item);
+ if (!item || item.type !== 'message') return;
+
+ const { itemId, role, content = [] } = item;
+ if (itemId && role) {
+ const isUser = role === "user";
+ let text = extractMessageText(content);
+
+ if (isUser && !text) {
+ text = "[Transcribing...]";
+ }
+
+ // If the guardrail has been tripped, this message is a message that gets sent to the
+ // assistant to correct it, so we add it as a breadcrumb instead of a message.
+ const guardrailMessage = sketchilyDetectGuardrailMessage(text);
+ if (guardrailMessage) {
+ const failureDetails = JSON.parse(guardrailMessage);
+ addTranscriptBreadcrumb('Output Guardrail Active', { details: failureDetails });
+ } else {
+ addTranscriptMessage(itemId, role, text);
+ }
```
-This interface is important because it defines how OpenAI Realtime Agents Tutorial: Voice-First AI Systems implements the patterns covered in this chapter.
+This function is important because it defines how OpenAI Realtime Agents Tutorial: Voice-First AI Systems implements the patterns covered in this chapter.
-### `src/app/hooks/useRealtimeSession.ts`
+### `src/app/hooks/useHandleSessionHistory.ts`
-The `ConnectOptions` interface in [`src/app/hooks/useRealtimeSession.ts`](https://github.com/openai/openai-realtime-agents/blob/HEAD/src/app/hooks/useRealtimeSession.ts) handles a key part of this chapter's functionality:
+The `handleHistoryAdded` function in [`src/app/hooks/useHandleSessionHistory.ts`](https://github.com/openai/openai-realtime-agents/blob/HEAD/src/app/hooks/useHandleSessionHistory.ts) handles a key part of this chapter's functionality:
```ts
-}
-
-export interface ConnectOptions {
- getEphemeralKey: () => Promise<string>;
- initialAgents: RealtimeAgent[];
- audioElement?: HTMLAudioElement;
- extraContext?: Record<string, any>;
- outputGuardrails?: any[];
-}
-
-export function useRealtimeSession(callbacks: RealtimeSessionCallbacks = {}) {
- const sessionRef = useRef<RealtimeSession | null>(null);
- const [status, setStatus] = useState<
- SessionStatus
- >('DISCONNECTED');
- const { logClientEvent } = useEvent();
-
- const updateStatus = useCallback(
- (s: SessionStatus) => {
- setStatus(s);
- callbacks.onConnectionChange?.(s);
- logClientEvent({}, s);
- },
- [callbacks],
- );
-
- const { logServerEvent } = useEvent();
-
- const historyHandlers = useHandleSessionHistory().current;
-
- function handleTransportEvent(event: any) {
- // Handle additional server events that aren't managed by the session
+ }
+
+ function handleHistoryAdded(item: any) {
+ console.log("[handleHistoryAdded] ", item);
+ if (!item || item.type !== 'message') return;
+
+ const { itemId, role, content = [] } = item;
+ if (itemId && role) {
+ const isUser = role === "user";
+ let text = extractMessageText(content);
+
+ if (isUser && !text) {
+ text = "[Transcribing...]";
+ }
+
+ // If the guardrail has been tripped, this message is a message that gets sent to the
+ // assistant to correct it, so we add it as a breadcrumb instead of a message.
+ const guardrailMessage = sketchilyDetectGuardrailMessage(text);
+ if (guardrailMessage) {
+ const failureDetails = JSON.parse(guardrailMessage);
+ addTranscriptBreadcrumb('Output Guardrail Active', { details: failureDetails });
+ } else {
+ addTranscriptMessage(itemId, role, text);
+ }
+ }
+ }
+
+ function handleHistoryUpdated(items: any[]) {
+ console.log("[handleHistoryUpdated] ", items);
+ items.forEach((item: any) => {
+ if (!item || item.type !== 'message') return;
+
```
-This interface is important because it defines how OpenAI Realtime Agents Tutorial: Voice-First AI Systems implements the patterns covered in this chapter.
+This function is important because it defines how OpenAI Realtime Agents Tutorial: Voice-First AI Systems implements the patterns covered in this chapter.
-### `src/app/hooks/useAudioDownload.ts`
+### `src/app/hooks/useHandleSessionHistory.ts`
-The `useAudioDownload` function in [`src/app/hooks/useAudioDownload.ts`](https://github.com/openai/openai-realtime-agents/blob/HEAD/src/app/hooks/useAudioDownload.ts) handles a key part of this chapter's functionality:
+The `handleHistoryUpdated` function in [`src/app/hooks/useHandleSessionHistory.ts`](https://github.com/openai/openai-realtime-agents/blob/HEAD/src/app/hooks/useHandleSessionHistory.ts) handles a key part of this chapter's functionality:
```ts
-import { convertWebMBlobToWav } from "../lib/audioUtils";
-
-function useAudioDownload() {
- // Ref to store the MediaRecorder instance.
- const mediaRecorderRef = useRef<MediaRecorder | null>(null);
- // Ref to collect all recorded Blob chunks.
- const recordedChunksRef = useRef<Blob[]>([]);
-
- /**
- * Starts recording by combining the provided remote stream with
- * the microphone audio.
- * @param remoteStream - The remote MediaStream (e.g., from the audio element).
- */
- const startRecording = async (remoteStream: MediaStream) => {
- let micStream: MediaStream;
- try {
- micStream = await navigator.mediaDevices.getUserMedia({ audio: true });
- } catch (err) {
- console.error("Error getting microphone stream:", err);
- // Fallback to an empty MediaStream if microphone access fails.
- micStream = new MediaStream();
- }
+ }
+
+ function handleHistoryUpdated(items: any[]) {
+ console.log("[handleHistoryUpdated] ", items);
+ items.forEach((item: any) => {
+ if (!item || item.type !== 'message') return;
+
+ const { itemId, content = [] } = item;
- // Create an AudioContext to merge the streams.
- const audioContext = new AudioContext();
- const destination = audioContext.createMediaStreamDestination();
+ const text = extractMessageText(content);
- // Connect the remote audio stream.
- try {
- const remoteSource = audioContext.createMediaStreamSource(remoteStream);
- remoteSource.connect(destination);
- } catch (err) {
+ if (text) {
+ updateTranscriptMessage(itemId, text, false);
+ }
+ });
+ }
+
+ function handleTranscriptionDelta(item: any) {
+ const itemId = item.item_id;
+ const deltaText = item.delta || "";
+ if (itemId) {
+ updateTranscriptMessage(itemId, deltaText, true);
+ }
+ }
+
+ function handleTranscriptionCompleted(item: any) {
+ // History updates don't reliably end in a completed item,
+ // so we need to handle finishing up when the transcription is completed.
+ const itemId = item.item_id;
+ const finalTranscript =
+ !item.transcript || item.transcript === "\n"
+ ? "[inaudible]"
```
This function is important because it defines how OpenAI Realtime Agents Tutorial: Voice-First AI Systems implements the patterns covered in this chapter.
### `src/app/hooks/useHandleSessionHistory.ts`
-The `useHandleSessionHistory` function in [`src/app/hooks/useHandleSessionHistory.ts`](https://github.com/openai/openai-realtime-agents/blob/HEAD/src/app/hooks/useHandleSessionHistory.ts) handles a key part of this chapter's functionality:
+The `handleTranscriptionDelta` function in [`src/app/hooks/useHandleSessionHistory.ts`](https://github.com/openai/openai-realtime-agents/blob/HEAD/src/app/hooks/useHandleSessionHistory.ts) handles a key part of this chapter's functionality:
```ts
-import { useEvent } from "@/app/contexts/EventContext";
-
-export function useHandleSessionHistory() {
- const {
- transcriptItems,
- addTranscriptBreadcrumb,
- addTranscriptMessage,
- updateTranscriptMessage,
- updateTranscriptItem,
- } = useTranscript();
-
- const { logServerEvent } = useEvent();
-
- /* ----------------------- helpers ------------------------- */
-
- const extractMessageText = (content: any[] = []): string => {
- if (!Array.isArray(content)) return "";
-
- return content
- .map((c) => {
- if (!c || typeof c !== "object") return "";
- if (c.type === "input_text") return c.text ?? "";
- if (c.type === "audio") return c.transcript ?? "";
- return "";
- })
- .filter(Boolean)
- .join("\n");
- };
-
- const extractFunctionCallByName = (name: string, content: any[] = []): any => {
- if (!Array.isArray(content)) return undefined;
- return content.find((c: any) => c.type === 'function_call' && c.name === name);
+ }
+
+ function handleTranscriptionDelta(item: any) {
+ const itemId = item.item_id;
+ const deltaText = item.delta || "";
+ if (itemId) {
+ updateTranscriptMessage(itemId, deltaText, true);
+ }
+ }
+
+ function handleTranscriptionCompleted(item: any) {
+ // History updates don't reliably end in a completed item,
+ // so we need to handle finishing up when the transcription is completed.
+ const itemId = item.item_id;
+ const finalTranscript =
+ !item.transcript || item.transcript === "\n"
+ ? "[inaudible]"
+ : item.transcript;
+ if (itemId) {
+ updateTranscriptMessage(itemId, finalTranscript, false);
+ // Use the ref to get the latest transcriptItems
+ const transcriptItem = transcriptItems.find((i) => i.itemId === itemId);
+ updateTranscriptItem(itemId, { status: 'DONE' });
+
+ // If guardrailResult still pending, mark PASS.
+ if (transcriptItem?.guardrailResult?.status === 'IN_PROGRESS') {
+ updateTranscriptItem(itemId, {
+ guardrailResult: {
+ status: 'DONE',
+ category: 'NONE',
+ rationale: '',
+ },
```
This function is important because it defines how OpenAI Realtime Agents Tutorial: Voice-First AI Systems implements the patterns covered in this chapter.
@@ -256,11 +254,11 @@ This function is important because it defines how OpenAI Realtime Agents Tutoria
```mermaid
flowchart TD
- A[RealtimeSessionCallbacks]
- B[ConnectOptions]
- C[useAudioDownload]
- D[useHandleSessionHistory]
- E[handleAgentToolStart]
+ A[handleAgentToolEnd]
+ B[handleHistoryAdded]
+ C[handleHistoryUpdated]
+ D[handleTranscriptionDelta]
+ E[handleTranscriptionCompleted]
A --> B
B --> C
C --> D
diff --git a/tutorials/openai-realtime-agents-tutorial/05-function-calling.md b/tutorials/openai-realtime-agents-tutorial/05-function-calling.md
index fb55c4ed..5f192142 100644
--- a/tutorials/openai-realtime-agents-tutorial/05-function-calling.md
+++ b/tutorials/openai-realtime-agents-tutorial/05-function-calling.md
@@ -78,186 +78,16 @@ You now have a production-safe tool-calling blueprint for realtime agents with c
Next: [Chapter 6: Voice Output](06-voice-output.md)
-## Depth Expansion Playbook
-
-## Source Code Walkthrough
-
-### `src/app/hooks/useHandleSessionHistory.ts`
-
-The `handleHistoryAdded` function in [`src/app/hooks/useHandleSessionHistory.ts`](https://github.com/openai/openai-realtime-agents/blob/HEAD/src/app/hooks/useHandleSessionHistory.ts) handles a key part of this chapter's functionality:
-
-```ts
- }
-
- function handleHistoryAdded(item: any) {
- console.log("[handleHistoryAdded] ", item);
- if (!item || item.type !== 'message') return;
-
- const { itemId, role, content = [] } = item;
- if (itemId && role) {
- const isUser = role === "user";
- let text = extractMessageText(content);
-
- if (isUser && !text) {
- text = "[Transcribing...]";
- }
-
- // If the guardrail has been tripped, this message is a message that gets sent to the
- // assistant to correct it, so we add it as a breadcrumb instead of a message.
- const guardrailMessage = sketchilyDetectGuardrailMessage(text);
- if (guardrailMessage) {
- const failureDetails = JSON.parse(guardrailMessage);
- addTranscriptBreadcrumb('Output Guardrail Active', { details: failureDetails });
- } else {
- addTranscriptMessage(itemId, role, text);
- }
- }
- }
-
- function handleHistoryUpdated(items: any[]) {
- console.log("[handleHistoryUpdated] ", items);
- items.forEach((item: any) => {
- if (!item || item.type !== 'message') return;
-
-```
-
-This function is important because it defines how OpenAI Realtime Agents Tutorial: Voice-First AI Systems implements the patterns covered in this chapter.
-
-### `src/app/hooks/useHandleSessionHistory.ts`
-
-The `handleHistoryUpdated` function in [`src/app/hooks/useHandleSessionHistory.ts`](https://github.com/openai/openai-realtime-agents/blob/HEAD/src/app/hooks/useHandleSessionHistory.ts) handles a key part of this chapter's functionality:
-
-```ts
- }
-
- function handleHistoryUpdated(items: any[]) {
- console.log("[handleHistoryUpdated] ", items);
- items.forEach((item: any) => {
- if (!item || item.type !== 'message') return;
-
- const { itemId, content = [] } = item;
-
- const text = extractMessageText(content);
-
- if (text) {
- updateTranscriptMessage(itemId, text, false);
- }
- });
- }
-
- function handleTranscriptionDelta(item: any) {
- const itemId = item.item_id;
- const deltaText = item.delta || "";
- if (itemId) {
- updateTranscriptMessage(itemId, deltaText, true);
- }
- }
-
- function handleTranscriptionCompleted(item: any) {
- // History updates don't reliably end in a completed item,
- // so we need to handle finishing up when the transcription is completed.
- const itemId = item.item_id;
- const finalTranscript =
- !item.transcript || item.transcript === "\n"
- ? "[inaudible]"
-```
-
-This function is important because it defines how OpenAI Realtime Agents Tutorial: Voice-First AI Systems implements the patterns covered in this chapter.
-
-### `src/app/hooks/useHandleSessionHistory.ts`
-
-The `handleTranscriptionDelta` function in [`src/app/hooks/useHandleSessionHistory.ts`](https://github.com/openai/openai-realtime-agents/blob/HEAD/src/app/hooks/useHandleSessionHistory.ts) handles a key part of this chapter's functionality:
-
-```ts
- }
-
- function handleTranscriptionDelta(item: any) {
- const itemId = item.item_id;
- const deltaText = item.delta || "";
- if (itemId) {
- updateTranscriptMessage(itemId, deltaText, true);
- }
- }
-
- function handleTranscriptionCompleted(item: any) {
- // History updates don't reliably end in a completed item,
- // so we need to handle finishing up when the transcription is completed.
- const itemId = item.item_id;
- const finalTranscript =
- !item.transcript || item.transcript === "\n"
- ? "[inaudible]"
- : item.transcript;
- if (itemId) {
- updateTranscriptMessage(itemId, finalTranscript, false);
- // Use the ref to get the latest transcriptItems
- const transcriptItem = transcriptItems.find((i) => i.itemId === itemId);
- updateTranscriptItem(itemId, { status: 'DONE' });
-
- // If guardrailResult still pending, mark PASS.
- if (transcriptItem?.guardrailResult?.status === 'IN_PROGRESS') {
- updateTranscriptItem(itemId, {
- guardrailResult: {
- status: 'DONE',
- category: 'NONE',
- rationale: '',
- },
-```
-
-This function is important because it defines how OpenAI Realtime Agents Tutorial: Voice-First AI Systems implements the patterns covered in this chapter.
-
-### `src/app/hooks/useHandleSessionHistory.ts`
-
-The `handleTranscriptionCompleted` function in [`src/app/hooks/useHandleSessionHistory.ts`](https://github.com/openai/openai-realtime-agents/blob/HEAD/src/app/hooks/useHandleSessionHistory.ts) handles a key part of this chapter's functionality:
-
-```ts
- }
-
- function handleTranscriptionCompleted(item: any) {
- // History updates don't reliably end in a completed item,
- // so we need to handle finishing up when the transcription is completed.
- const itemId = item.item_id;
- const finalTranscript =
- !item.transcript || item.transcript === "\n"
- ? "[inaudible]"
- : item.transcript;
- if (itemId) {
- updateTranscriptMessage(itemId, finalTranscript, false);
- // Use the ref to get the latest transcriptItems
- const transcriptItem = transcriptItems.find((i) => i.itemId === itemId);
- updateTranscriptItem(itemId, { status: 'DONE' });
-
- // If guardrailResult still pending, mark PASS.
- if (transcriptItem?.guardrailResult?.status === 'IN_PROGRESS') {
- updateTranscriptItem(itemId, {
- guardrailResult: {
- status: 'DONE',
- category: 'NONE',
- rationale: '',
- },
- });
- }
- }
- }
-
- function handleGuardrailTripped(details: any, _agent: any, guardrail: any) {
- console.log("[guardrail tripped]", details, _agent, guardrail);
- const moderation = extractModeration(guardrail.result.output.outputInfo);
-```
-
-This function is important because it defines how OpenAI Realtime Agents Tutorial: Voice-First AI Systems implements the patterns covered in this chapter.
-
## How These Components Connect
```mermaid
flowchart TD
- A[handleHistoryAdded]
- B[handleHistoryUpdated]
- C[handleTranscriptionDelta]
- D[handleTranscriptionCompleted]
- E[handleGuardrailTripped]
- A --> B
- B --> C
- C --> D
- D --> E
+ A[Realtime Session] --> B[Agent Receives User Speech]
+ B --> C[LLM Decides Tool Call]
+ C --> D[function_call Event Fired]
+ D --> E[toolLogic Handler]
+ E --> F[External API / Data]
+ F --> G[function_call_output Sent Back]
+ G --> H[Agent Continues Response]
```
diff --git a/tutorials/openai-realtime-agents-tutorial/06-voice-output.md b/tutorials/openai-realtime-agents-tutorial/06-voice-output.md
index a27844b5..048cdc67 100644
--- a/tutorials/openai-realtime-agents-tutorial/06-voice-output.md
+++ b/tutorials/openai-realtime-agents-tutorial/06-voice-output.md
@@ -73,175 +73,15 @@ You now understand how to tune voice output for perceived speed, clarity, and us
Next: [Chapter 7: Advanced Patterns](07-advanced-patterns.md)
-## Depth Expansion Playbook
-
-## Source Code Walkthrough
-
-### `src/app/agentConfigs/guardrails.ts`
-
-The `createModerationGuardrail` function in [`src/app/agentConfigs/guardrails.ts`](https://github.com/openai/openai-realtime-agents/blob/HEAD/src/app/agentConfigs/guardrails.ts) handles a key part of this chapter's functionality:
-
-```ts
-
-// Creates a guardrail bound to a specific company name for output moderation purposes.
-export function createModerationGuardrail(companyName: string) {
- return {
- name: 'moderation_guardrail',
-
- async execute({ agentOutput }: RealtimeOutputGuardrailArgs): Promise<RealtimeOutputGuardrailResult> {
- try {
- const res = await runGuardrailClassifier(agentOutput, companyName);
- const triggered = res.moderationCategory !== 'NONE';
- return {
- tripwireTriggered: triggered,
- outputInfo: res,
- };
- } catch {
- return {
- tripwireTriggered: false,
- outputInfo: { error: 'guardrail_failed' },
- };
- }
- },
- } as const;
-}
-```
-
-This function is important because it defines how OpenAI Realtime Agents Tutorial: Voice-First AI Systems implements the patterns covered in this chapter.
-
-### `src/app/agentConfigs/guardrails.ts`
-
-The `RealtimeOutputGuardrailResult` interface in [`src/app/agentConfigs/guardrails.ts`](https://github.com/openai/openai-realtime-agents/blob/HEAD/src/app/agentConfigs/guardrails.ts) handles a key part of this chapter's functionality:
-
-```ts
-}
-
-export interface RealtimeOutputGuardrailResult {
- tripwireTriggered: boolean;
- outputInfo: any;
-}
-
-export interface RealtimeOutputGuardrailArgs {
- agentOutput: string;
- agent?: any;
- context?: any;
-}
-
-// Creates a guardrail bound to a specific company name for output moderation purposes.
-export function createModerationGuardrail(companyName: string) {
- return {
- name: 'moderation_guardrail',
-
- async execute({ agentOutput }: RealtimeOutputGuardrailArgs): Promise<RealtimeOutputGuardrailResult> {
- try {
- const res = await runGuardrailClassifier(agentOutput, companyName);
- const triggered = res.moderationCategory !== 'NONE';
- return {
- tripwireTriggered: triggered,
- outputInfo: res,
- };
- } catch {
- return {
- tripwireTriggered: false,
- outputInfo: { error: 'guardrail_failed' },
- };
- }
-```
-
-This interface is important because it defines how OpenAI Realtime Agents Tutorial: Voice-First AI Systems implements the patterns covered in this chapter.
-
-### `src/app/agentConfigs/guardrails.ts`
-
-The `RealtimeOutputGuardrailArgs` interface in [`src/app/agentConfigs/guardrails.ts`](https://github.com/openai/openai-realtime-agents/blob/HEAD/src/app/agentConfigs/guardrails.ts) handles a key part of this chapter's functionality:
-
-```ts
-}
-
-export interface RealtimeOutputGuardrailArgs {
- agentOutput: string;
- agent?: any;
- context?: any;
-}
-
-// Creates a guardrail bound to a specific company name for output moderation purposes.
-export function createModerationGuardrail(companyName: string) {
- return {
- name: 'moderation_guardrail',
-
- async execute({ agentOutput }: RealtimeOutputGuardrailArgs): Promise<RealtimeOutputGuardrailResult> {
- try {
- const res = await runGuardrailClassifier(agentOutput, companyName);
- const triggered = res.moderationCategory !== 'NONE';
- return {
- tripwireTriggered: triggered,
- outputInfo: res,
- };
- } catch {
- return {
- tripwireTriggered: false,
- outputInfo: { error: 'guardrail_failed' },
- };
- }
- },
- } as const;
-}
-```
-
-This interface is important because it defines how OpenAI Realtime Agents Tutorial: Voice-First AI Systems implements the patterns covered in this chapter.
-
-### `src/app/components/Events.tsx`
-
-The `Events` function in [`src/app/components/Events.tsx`](https://github.com/openai/openai-realtime-agents/blob/HEAD/src/app/components/Events.tsx) handles a key part of this chapter's functionality:
-
-```tsx
-import { LoggedEvent } from "@/app/types";
-
-export interface EventsProps {
- isExpanded: boolean;
-}
-
-function Events({ isExpanded }: EventsProps) {
- const [prevEventLogs, setPrevEventLogs] = useState<LoggedEvent[]>([]);
- const eventLogsContainerRef = useRef<HTMLDivElement | null>(null);
-
- const { loggedEvents, toggleExpand } = useEvent();
-
- const getDirectionArrow = (direction: string) => {
- if (direction === "client") return { symbol: "▲", color: "#7f5af0" };
- if (direction === "server") return { symbol: "▼", color: "#2cb67d" };
- return { symbol: "•", color: "#555" };
- };
-
- useEffect(() => {
- const hasNewEvent = loggedEvents.length > prevEventLogs.length;
-
- if (isExpanded && hasNewEvent && eventLogsContainerRef.current) {
- eventLogsContainerRef.current.scrollTop =
- eventLogsContainerRef.current.scrollHeight;
- }
-
- setPrevEventLogs(loggedEvents);
- }, [loggedEvents, isExpanded]);
-
- return (
- <div
- className={
-```
-
-This function is important because it defines how OpenAI Realtime Agents Tutorial: Voice-First AI Systems implements the patterns covered in this chapter.
-
## How These Components Connect
```mermaid
-flowchart TD
- A[createModerationGuardrail]
- B[RealtimeOutputGuardrailResult]
- C[RealtimeOutputGuardrailArgs]
- D[Events]
- E[EventsProps]
- A --> B
- B --> C
- C --> D
- D --> E
+flowchart LR
+ A[Agent Text Response] --> B[Realtime TTS Engine]
+ B --> C[PCM Audio Stream]
+ C --> D[WebRTC Transport]
+ D --> E[Browser Audio Output]
+ F[Interrupt Signal] --> G[Cancel Ongoing Audio]
+ G --> D
```
diff --git a/tutorials/openai-realtime-agents-tutorial/07-advanced-patterns.md b/tutorials/openai-realtime-agents-tutorial/07-advanced-patterns.md
index d2e2f2ef..91b6daba 100644
--- a/tutorials/openai-realtime-agents-tutorial/07-advanced-patterns.md
+++ b/tutorials/openai-realtime-agents-tutorial/07-advanced-patterns.md
@@ -85,27 +85,48 @@ You now have a practical framework for choosing and operating multi-agent realti
Next: [Chapter 8: Production Deployment](08-production-deployment.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/app/contexts/TranscriptContext.tsx`
+### `src/app/components/Events.tsx`
-The `useTranscript` function in [`src/app/contexts/TranscriptContext.tsx`](https://github.com/openai/openai-realtime-agents/blob/HEAD/src/app/contexts/TranscriptContext.tsx) handles a key part of this chapter's functionality:
+The `EventsProps` interface in [`src/app/components/Events.tsx`](https://github.com/openai/openai-realtime-agents/blob/HEAD/src/app/components/Events.tsx) handles a key part of this chapter's functionality:
```tsx
-};
+import { LoggedEvent } from "@/app/types";
-export function useTranscript() {
- const context = useContext(TranscriptContext);
- if (!context) {
- throw new Error("useTranscript must be used within a TranscriptProvider");
- }
- return context;
+export interface EventsProps {
+ isExpanded: boolean;
}
+
+function Events({ isExpanded }: EventsProps) {
+ const [prevEventLogs, setPrevEventLogs] = useState<LoggedEvent[]>([]);
+ const eventLogsContainerRef = useRef<HTMLDivElement | null>(null);
+
+ const { loggedEvents, toggleExpand } = useEvent();
+
+ const getDirectionArrow = (direction: string) => {
+ if (direction === "client") return { symbol: "▲", color: "#7f5af0" };
+ if (direction === "server") return { symbol: "▼", color: "#2cb67d" };
+ return { symbol: "•", color: "#555" };
+ };
+
+ useEffect(() => {
+ const hasNewEvent = loggedEvents.length > prevEventLogs.length;
+
+ if (isExpanded && hasNewEvent && eventLogsContainerRef.current) {
+ eventLogsContainerRef.current.scrollTop =
+ eventLogsContainerRef.current.scrollHeight;
+ }
+
+ setPrevEventLogs(loggedEvents);
+ }, [loggedEvents, isExpanded]);
+
+ return (
+ <div
+ className={
```
-This function is important because it defines how OpenAI Realtime Agents Tutorial: Voice-First AI Systems implements the patterns covered in this chapter.
+This interface is important because it defines how OpenAI Realtime Agents Tutorial: Voice-First AI Systems implements the patterns covered in this chapter.
### `src/app/components/BottomToolbar.tsx`
@@ -235,7 +256,7 @@ This function is important because it defines how OpenAI Realtime Agents Tutoria
```mermaid
flowchart TD
- A[useTranscript]
+ A[EventsProps]
B[BottomToolbar]
C[getConnectionButtonLabel]
D[getConnectionButtonClasses]
diff --git a/tutorials/openai-realtime-agents-tutorial/08-production-deployment.md b/tutorials/openai-realtime-agents-tutorial/08-production-deployment.md
index 34ce4035..e81eefc3 100644
--- a/tutorials/openai-realtime-agents-tutorial/08-production-deployment.md
+++ b/tutorials/openai-realtime-agents-tutorial/08-production-deployment.md
@@ -85,163 +85,17 @@ Related:
- [OpenAI Whisper Tutorial](../openai-whisper-tutorial/)
- [Swarm Tutorial](../swarm-tutorial/)
-## Depth Expansion Playbook
-
-## Source Code Walkthrough
-
-### `src/app/contexts/EventContext.tsx`
-
-The `useEvent` function in [`src/app/contexts/EventContext.tsx`](https://github.com/openai/openai-realtime-agents/blob/HEAD/src/app/contexts/EventContext.tsx) handles a key part of this chapter's functionality:
-
-```tsx
-};
-
-export function useEvent() {
- const context = useContext(EventContext);
- if (!context) {
- throw new Error("useEvent must be used within an EventProvider");
- }
- return context;
-}
-```
-
-This function is important because it defines how OpenAI Realtime Agents Tutorial: Voice-First AI Systems implements the patterns covered in this chapter.
-
-### `src/app/lib/audioUtils.ts`
-
-The `writeString` function in [`src/app/lib/audioUtils.ts`](https://github.com/openai/openai-realtime-agents/blob/HEAD/src/app/lib/audioUtils.ts) handles a key part of this chapter's functionality:
-
-```ts
- * Writes a string into a DataView at the given offset.
- */
-export function writeString(view: DataView, offset: number, str: string) {
- for (let i = 0; i < str.length; i++) {
- view.setUint8(offset + i, str.charCodeAt(i));
- }
-}
-
-/**
- * Converts a Float32Array to 16-bit PCM in a DataView.
- */
-export function floatTo16BitPCM(output: DataView, offset: number, input: Float32Array) {
- for (let i = 0; i < input.length; i++, offset += 2) {
- const s = Math.max(-1, Math.min(1, input[i]));
- output.setInt16(offset, s < 0 ? s * 0x8000 : s * 0x7FFF, true);
- }
-}
-
-/**
- * Encodes a Float32Array as a WAV file.
- */
-export function encodeWAV(samples: Float32Array, sampleRate: number): ArrayBuffer {
- const buffer = new ArrayBuffer(44 + samples.length * 2);
- const view = new DataView(buffer);
-
- // RIFF identifier
- writeString(view, 0, "RIFF");
- // file length minus RIFF identifier length and file description length
- view.setUint32(4, 36 + samples.length * 2, true);
- // RIFF type
- writeString(view, 8, "WAVE");
- // format chunk identifier
-```
-
-This function is important because it defines how OpenAI Realtime Agents Tutorial: Voice-First AI Systems implements the patterns covered in this chapter.
-
-### `src/app/lib/audioUtils.ts`
-
-The `floatTo16BitPCM` function in [`src/app/lib/audioUtils.ts`](https://github.com/openai/openai-realtime-agents/blob/HEAD/src/app/lib/audioUtils.ts) handles a key part of this chapter's functionality:
-
-```ts
- * Converts a Float32Array to 16-bit PCM in a DataView.
- */
-export function floatTo16BitPCM(output: DataView, offset: number, input: Float32Array) {
- for (let i = 0; i < input.length; i++, offset += 2) {
- const s = Math.max(-1, Math.min(1, input[i]));
- output.setInt16(offset, s < 0 ? s * 0x8000 : s * 0x7FFF, true);
- }
-}
-
-/**
- * Encodes a Float32Array as a WAV file.
- */
-export function encodeWAV(samples: Float32Array, sampleRate: number): ArrayBuffer {
- const buffer = new ArrayBuffer(44 + samples.length * 2);
- const view = new DataView(buffer);
-
- // RIFF identifier
- writeString(view, 0, "RIFF");
- // file length minus RIFF identifier length and file description length
- view.setUint32(4, 36 + samples.length * 2, true);
- // RIFF type
- writeString(view, 8, "WAVE");
- // format chunk identifier
- writeString(view, 12, "fmt ");
- // format chunk length
- view.setUint32(16, 16, true);
- // sample format (raw)
- view.setUint16(20, 1, true);
- // channel count - forcing mono here by averaging channels
- view.setUint16(22, 1, true);
- // sample rate
- view.setUint32(24, sampleRate, true);
-```
-
-This function is important because it defines how OpenAI Realtime Agents Tutorial: Voice-First AI Systems implements the patterns covered in this chapter.
-
-### `src/app/lib/audioUtils.ts`
-
-The `encodeWAV` function in [`src/app/lib/audioUtils.ts`](https://github.com/openai/openai-realtime-agents/blob/HEAD/src/app/lib/audioUtils.ts) handles a key part of this chapter's functionality:
-
-```ts
- * Encodes a Float32Array as a WAV file.
- */
-export function encodeWAV(samples: Float32Array, sampleRate: number): ArrayBuffer {
- const buffer = new ArrayBuffer(44 + samples.length * 2);
- const view = new DataView(buffer);
-
- // RIFF identifier
- writeString(view, 0, "RIFF");
- // file length minus RIFF identifier length and file description length
- view.setUint32(4, 36 + samples.length * 2, true);
- // RIFF type
- writeString(view, 8, "WAVE");
- // format chunk identifier
- writeString(view, 12, "fmt ");
- // format chunk length
- view.setUint32(16, 16, true);
- // sample format (raw)
- view.setUint16(20, 1, true);
- // channel count - forcing mono here by averaging channels
- view.setUint16(22, 1, true);
- // sample rate
- view.setUint32(24, sampleRate, true);
- // byte rate (sample rate * block align)
- view.setUint32(28, sampleRate * 2, true);
- // block align (channel count * bytes per sample)
- view.setUint16(32, 2, true);
- // bits per sample
- view.setUint16(34, 16, true);
- // data chunk identifier
- writeString(view, 36, "data");
- // data chunk length
- view.setUint32(40, samples.length * 2, true);
-```
-
-This function is important because it defines how OpenAI Realtime Agents Tutorial: Voice-First AI Systems implements the patterns covered in this chapter.
-
## How These Components Connect
```mermaid
flowchart TD
- A[useEvent]
- B[writeString]
- C[floatTo16BitPCM]
- D[encodeWAV]
- E[convertWebMBlobToWav]
- A --> B
- B --> C
- C --> D
- D --> E
+ A[HTTPS / WSS Entry] --> B[Realtime Session Manager]
+ B --> C{Session Health}
+ C -->|Reconnect| D[Session Recovery]
+ C -->|Healthy| E[Agent Processing]
+ B --> F[Guardrail Layer]
+ F --> G[Input / Output Checks]
+ B --> H[Monitoring / Logging]
+ H --> I[Ops Dashboard]
```
diff --git a/tutorials/openai-whisper-tutorial/01-getting-started.md b/tutorials/openai-whisper-tutorial/01-getting-started.md
index 8bff2684..67af803a 100644
--- a/tutorials/openai-whisper-tutorial/01-getting-started.md
+++ b/tutorials/openai-whisper-tutorial/01-getting-started.md
@@ -106,184 +106,182 @@ Suggested trace strategy:
- [Main Catalog](../../README.md#-tutorial-catalog)
- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `whisper/timing.py`
+### `whisper/utils.py`
-The `from` class in [`whisper/timing.py`](https://github.com/openai/whisper/blob/HEAD/whisper/timing.py) handles a key part of this chapter's functionality:
+The `ResultWriter` class in [`whisper/utils.py`](https://github.com/openai/whisper/blob/HEAD/whisper/utils.py) handles a key part of this chapter's functionality:
```py
-import subprocess
-import warnings
-from dataclasses import dataclass
-from typing import TYPE_CHECKING, List
-import numba
-import numpy as np
-import torch
-import torch.nn.functional as F
-from .audio import HOP_LENGTH, SAMPLE_RATE, TOKENS_PER_SECOND
-from .tokenizer import Tokenizer
+class ResultWriter:
+ extension: str
+
+ def __init__(self, output_dir: str):
+ self.output_dir = output_dir
-if TYPE_CHECKING:
- from .model import Whisper
+ def __call__(
+ self, result: dict, audio_path: str, options: Optional[dict] = None, **kwargs
+ ):
+ audio_basename = os.path.basename(audio_path)
+ audio_basename = os.path.splitext(audio_basename)[0]
+ output_path = os.path.join(
+ self.output_dir, audio_basename + "." + self.extension
+ )
+ with open(output_path, "w", encoding="utf-8") as f:
+ self.write_result(result, file=f, options=options, **kwargs)
-def median_filter(x: torch.Tensor, filter_width: int):
- """Apply a median filter of width `filter_width` along the last dimension of `x`"""
- pad_width = filter_width // 2
- if x.shape[-1] <= pad_width:
- # F.pad requires the padding width to be smaller than the input dimension
- return x
+ def write_result(
+ self, result: dict, file: TextIO, options: Optional[dict] = None, **kwargs
+ ):
+ raise NotImplementedError
- if (ndim := x.ndim) <= 2:
- # `F.pad` does not support 1D or 2D inputs for reflect padding but supports 3D and 4D
- x = x[None, None, :]
- assert (
- filter_width > 0 and filter_width % 2 == 1
- ), "`filter_width` should be an odd number"
+class WriteTXT(ResultWriter):
+ extension: str = "txt"
+ def write_result(
+ self, result: dict, file: TextIO, options: Optional[dict] = None, **kwargs
+ ):
```
This class is important because it defines how OpenAI Whisper Tutorial: Speech Recognition and Translation implements the patterns covered in this chapter.
-### `whisper/timing.py`
+### `whisper/utils.py`
-The `class` class in [`whisper/timing.py`](https://github.com/openai/whisper/blob/HEAD/whisper/timing.py) handles a key part of this chapter's functionality:
+The `WriteTXT` class in [`whisper/utils.py`](https://github.com/openai/whisper/blob/HEAD/whisper/utils.py) handles a key part of this chapter's functionality:
```py
-import subprocess
-import warnings
-from dataclasses import dataclass
-from typing import TYPE_CHECKING, List
-import numba
-import numpy as np
-import torch
-import torch.nn.functional as F
-from .audio import HOP_LENGTH, SAMPLE_RATE, TOKENS_PER_SECOND
-from .tokenizer import Tokenizer
+class WriteTXT(ResultWriter):
+ extension: str = "txt"
+
+ def write_result(
+ self, result: dict, file: TextIO, options: Optional[dict] = None, **kwargs
+ ):
+ for segment in result["segments"]:
+ print(segment["text"].strip(), file=file, flush=True)
+
+
+class SubtitlesWriter(ResultWriter):
+ always_include_hours: bool
+ decimal_marker: str
+
+ def iterate_result(
+ self,
+ result: dict,
+ options: Optional[dict] = None,
+ *,
+ max_line_width: Optional[int] = None,
+ max_line_count: Optional[int] = None,
+ highlight_words: bool = False,
+ max_words_per_line: Optional[int] = None,
+ ):
+ options = options or {}
+ max_line_width = max_line_width or options.get("max_line_width")
+ max_line_count = max_line_count or options.get("max_line_count")
+ highlight_words = highlight_words or options.get("highlight_words", False)
+ max_words_per_line = max_words_per_line or options.get("max_words_per_line")
+ preserve_segments = max_line_count is None or max_line_width is None
+```
-if TYPE_CHECKING:
- from .model import Whisper
+This class is important because it defines how OpenAI Whisper Tutorial: Speech Recognition and Translation implements the patterns covered in this chapter.
+### `whisper/utils.py`
-def median_filter(x: torch.Tensor, filter_width: int):
- """Apply a median filter of width `filter_width` along the last dimension of `x`"""
- pad_width = filter_width // 2
- if x.shape[-1] <= pad_width:
- # F.pad requires the padding width to be smaller than the input dimension
- return x
+The `SubtitlesWriter` class in [`whisper/utils.py`](https://github.com/openai/whisper/blob/HEAD/whisper/utils.py) handles a key part of this chapter's functionality:
- if (ndim := x.ndim) <= 2:
- # `F.pad` does not support 1D or 2D inputs for reflect padding but supports 3D and 4D
- x = x[None, None, :]
+```py
- assert (
- filter_width > 0 and filter_width % 2 == 1
- ), "`filter_width` should be an odd number"
+class SubtitlesWriter(ResultWriter):
+ always_include_hours: bool
+ decimal_marker: str
+
+ def iterate_result(
+ self,
+ result: dict,
+ options: Optional[dict] = None,
+ *,
+ max_line_width: Optional[int] = None,
+ max_line_count: Optional[int] = None,
+ highlight_words: bool = False,
+ max_words_per_line: Optional[int] = None,
+ ):
+ options = options or {}
+ max_line_width = max_line_width or options.get("max_line_width")
+ max_line_count = max_line_count or options.get("max_line_count")
+ highlight_words = highlight_words or options.get("highlight_words", False)
+ max_words_per_line = max_words_per_line or options.get("max_words_per_line")
+ preserve_segments = max_line_count is None or max_line_width is None
+ max_line_width = max_line_width or 1000
+ max_words_per_line = max_words_per_line or 1000
+
+ def iterate_subtitles():
+ line_len = 0
+ line_count = 1
+ # the next subtitle to yield (a list of word timings with whitespace)
+ subtitle: List[dict] = []
+ last: float = get_start(result["segments"]) or 0.0
+ for segment in result["segments"]:
```
This class is important because it defines how OpenAI Whisper Tutorial: Speech Recognition and Translation implements the patterns covered in this chapter.
-### `whisper/timing.py`
+### `whisper/utils.py`
-The `median_filter` function in [`whisper/timing.py`](https://github.com/openai/whisper/blob/HEAD/whisper/timing.py) handles a key part of this chapter's functionality:
+The `WriteVTT` class in [`whisper/utils.py`](https://github.com/openai/whisper/blob/HEAD/whisper/utils.py) handles a key part of this chapter's functionality:
```py
-def median_filter(x: torch.Tensor, filter_width: int):
- """Apply a median filter of width `filter_width` along the last dimension of `x`"""
- pad_width = filter_width // 2
- if x.shape[-1] <= pad_width:
- # F.pad requires the padding width to be smaller than the input dimension
- return x
-
- if (ndim := x.ndim) <= 2:
- # `F.pad` does not support 1D or 2D inputs for reflect padding but supports 3D and 4D
- x = x[None, None, :]
-
- assert (
- filter_width > 0 and filter_width % 2 == 1
- ), "`filter_width` should be an odd number"
-
- result = None
- x = F.pad(x, (filter_width // 2, filter_width // 2, 0, 0), mode="reflect")
- if x.is_cuda:
- try:
- from .triton_ops import median_filter_cuda
-
- result = median_filter_cuda(x, filter_width)
- except (RuntimeError, subprocess.CalledProcessError):
- warnings.warn(
- "Failed to launch Triton kernels, likely due to missing CUDA toolkit; "
- "falling back to a slower median kernel implementation..."
- )
-
- if result is None:
- # sort() is faster than torch.median (https://github.com/pytorch/pytorch/issues/51450)
-```
+class WriteVTT(SubtitlesWriter):
+ extension: str = "vtt"
+ always_include_hours: bool = False
+ decimal_marker: str = "."
-This function is important because it defines how OpenAI Whisper Tutorial: Speech Recognition and Translation implements the patterns covered in this chapter.
+ def write_result(
+ self, result: dict, file: TextIO, options: Optional[dict] = None, **kwargs
+ ):
+ print("WEBVTT\n", file=file)
+ for start, end, text in self.iterate_result(result, options, **kwargs):
+ print(f"{start} --> {end}\n{text}\n", file=file, flush=True)
-### `whisper/timing.py`
-The `backtrace` function in [`whisper/timing.py`](https://github.com/openai/whisper/blob/HEAD/whisper/timing.py) handles a key part of this chapter's functionality:
+class WriteSRT(SubtitlesWriter):
+ extension: str = "srt"
+ always_include_hours: bool = True
+ decimal_marker: str = ","
-```py
+ def write_result(
+ self, result: dict, file: TextIO, options: Optional[dict] = None, **kwargs
+ ):
+ for i, (start, end, text) in enumerate(
+ self.iterate_result(result, options, **kwargs), start=1
+ ):
+ print(f"{i}\n{start} --> {end}\n{text}\n", file=file, flush=True)
-@numba.jit(nopython=True)
-def backtrace(trace: np.ndarray):
- i = trace.shape[0] - 1
- j = trace.shape[1] - 1
- trace[0, :] = 2
- trace[:, 0] = 1
-
- result = []
- while i > 0 or j > 0:
- result.append((i - 1, j - 1))
-
- if trace[i, j] == 0:
- i -= 1
- j -= 1
- elif trace[i, j] == 1:
- i -= 1
- elif trace[i, j] == 2:
- j -= 1
- else:
- raise ValueError("Unexpected trace[i, j]")
-
- result = np.array(result)
- return result[::-1, :].T
-
-
-@numba.jit(nopython=True, parallel=True)
-def dtw_cpu(x: np.ndarray):
- N, M = x.shape
- cost = np.ones((N + 1, M + 1), dtype=np.float32) * np.inf
- trace = -np.ones((N + 1, M + 1), dtype=np.float32)
+class WriteTSV(ResultWriter):
+ """
+ Write a transcript to a file in TSV (tab-separated values) format containing lines like:
```
-This function is important because it defines how OpenAI Whisper Tutorial: Speech Recognition and Translation implements the patterns covered in this chapter.
+This class is important because it defines how OpenAI Whisper Tutorial: Speech Recognition and Translation implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[from]
- B[class]
- C[median_filter]
- D[backtrace]
- E[dtw_cpu]
+ A[ResultWriter]
+ B[WriteTXT]
+ C[SubtitlesWriter]
+ D[WriteVTT]
+ E[WriteSRT]
A --> B
B --> C
C --> D
diff --git a/tutorials/openai-whisper-tutorial/02-model-architecture.md b/tutorials/openai-whisper-tutorial/02-model-architecture.md
index d862a7cc..67805334 100644
--- a/tutorials/openai-whisper-tutorial/02-model-architecture.md
+++ b/tutorials/openai-whisper-tutorial/02-model-architecture.md
@@ -102,186 +102,36 @@ Suggested trace strategy:
- [Main Catalog](../../README.md#-tutorial-catalog)
- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `whisper/timing.py`
-
-The `add_word_timestamps` function in [`whisper/timing.py`](https://github.com/openai/whisper/blob/HEAD/whisper/timing.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def add_word_timestamps(
- *,
- segments: List[dict],
- model: "Whisper",
- tokenizer: Tokenizer,
- mel: torch.Tensor,
- num_frames: int,
- prepend_punctuations: str = "\"'“¿([{-",
- append_punctuations: str = "\"'.。,，!！?？:：”)]}、",
- last_speech_timestamp: float,
- **kwargs,
-):
- if len(segments) == 0:
- return
-
- text_tokens_per_segment = [
- [token for token in segment["tokens"] if token < tokenizer.eot]
- for segment in segments
- ]
-
- text_tokens = list(itertools.chain.from_iterable(text_tokens_per_segment))
- alignment = find_alignment(model, tokenizer, text_tokens, mel, num_frames, **kwargs)
- word_durations = np.array([t.end - t.start for t in alignment])
- word_durations = word_durations[word_durations.nonzero()]
- median_duration = np.median(word_durations) if len(word_durations) > 0 else 0.0
- median_duration = min(0.7, float(median_duration))
- max_duration = median_duration * 2
-
- # hack: truncate long words at sentence boundaries.
- # a better segmentation algorithm based on VAD should be able to replace this.
-```
-
-This function is important because it defines how OpenAI Whisper Tutorial: Speech Recognition and Translation implements the patterns covered in this chapter.
-
-### `whisper/model.py`
-
-The `from` class in [`whisper/model.py`](https://github.com/openai/whisper/blob/HEAD/whisper/model.py) handles a key part of this chapter's functionality:
-
-```py
-import base64
-import gzip
-from contextlib import contextmanager
-from dataclasses import dataclass
-from typing import Dict, Iterable, Optional, Tuple
-
-import numpy as np
-import torch
-import torch.nn.functional as F
-from torch import Tensor, nn
-
-from .decoding import decode as decode_function
-from .decoding import detect_language as detect_language_function
-from .transcribe import transcribe as transcribe_function
-
-try:
- from torch.nn.functional import scaled_dot_product_attention
-
- SDPA_AVAILABLE = True
-except (ImportError, RuntimeError, OSError):
- scaled_dot_product_attention = None
- SDPA_AVAILABLE = False
-
-
-@dataclass
-class ModelDimensions:
- n_mels: int
- n_audio_ctx: int
- n_audio_state: int
- n_audio_head: int
- n_audio_layer: int
- n_vocab: int
-```
-
-This class is important because it defines how OpenAI Whisper Tutorial: Speech Recognition and Translation implements the patterns covered in this chapter.
-
### `whisper/model.py`
-The `class` class in [`whisper/model.py`](https://github.com/openai/whisper/blob/HEAD/whisper/model.py) handles a key part of this chapter's functionality:
+The `MultiHeadAttention` class in [`whisper/model.py`](https://github.com/openai/whisper/blob/HEAD/whisper/model.py) is central to the encoder-decoder architecture covered in this chapter:
```py
-import gzip
-from contextlib import contextmanager
-from dataclasses import dataclass
-from typing import Dict, Iterable, Optional, Tuple
-
-import numpy as np
-import torch
-import torch.nn.functional as F
-from torch import Tensor, nn
-
-from .decoding import decode as decode_function
-from .decoding import detect_language as detect_language_function
-from .transcribe import transcribe as transcribe_function
-
-try:
- from torch.nn.functional import scaled_dot_product_attention
-
- SDPA_AVAILABLE = True
-except (ImportError, RuntimeError, OSError):
- scaled_dot_product_attention = None
- SDPA_AVAILABLE = False
-
-
-@dataclass
-class ModelDimensions:
- n_mels: int
- n_audio_ctx: int
- n_audio_state: int
- n_audio_head: int
- n_audio_layer: int
- n_vocab: int
- n_text_ctx: int
+class MultiHeadAttention(nn.Module):
+ use_sdpa = True
+
+ def __init__(self, n_state: int, n_head: int):
+ super().__init__()
+ self.n_head = n_head
+ self.query = Linear(n_state, n_state)
+ self.key = Linear(n_state, n_state, bias=False)
+ self.value = Linear(n_state, n_state)
+ self.out = Linear(n_state, n_state)
```
-This class is important because it defines how OpenAI Whisper Tutorial: Speech Recognition and Translation implements the patterns covered in this chapter.
-
-### `whisper/model.py`
-
-The `LayerNorm` class in [`whisper/model.py`](https://github.com/openai/whisper/blob/HEAD/whisper/model.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-class LayerNorm(nn.LayerNorm):
- def forward(self, x: Tensor) -> Tensor:
- return super().forward(x.float()).type(x.dtype)
-
-
-class Linear(nn.Linear):
- def forward(self, x: Tensor) -> Tensor:
- return F.linear(
- x,
- self.weight.to(x.dtype),
- None if self.bias is None else self.bias.to(x.dtype),
- )
-
-
-class Conv1d(nn.Conv1d):
- def _conv_forward(
- self, x: Tensor, weight: Tensor, bias: Optional[Tensor]
- ) -> Tensor:
- return super()._conv_forward(
- x, weight.to(x.dtype), None if bias is None else bias.to(x.dtype)
- )
-
-
-def sinusoids(length, channels, max_timescale=10000):
- """Returns sinusoids for positional embedding"""
- assert channels % 2 == 0
- log_timescale_increment = np.log(max_timescale) / (channels // 2 - 1)
- inv_timescales = torch.exp(-log_timescale_increment * torch.arange(channels // 2))
- scaled_time = torch.arange(length)[:, np.newaxis] * inv_timescales[np.newaxis, :]
- return torch.cat([torch.sin(scaled_time), torch.cos(scaled_time)], dim=1)
-```
-
-This class is important because it defines how OpenAI Whisper Tutorial: Speech Recognition and Translation implements the patterns covered in this chapter.
-
+This class implements the multi-head attention layers used in both the audio encoder and text decoder, which is the core of Whisper's transformer architecture.
## How These Components Connect
```mermaid
flowchart TD
- A[add_word_timestamps]
- B[from]
- C[class]
- D[LayerNorm]
- E[Linear]
- A --> B
- B --> C
- C --> D
- D --> E
+ A[Audio Frames 30s] --> B[Log-Mel Spectrogram]
+ B --> C[Audio Encoder]
+ C --> D[Cross-Attention Keys/Values]
+ E[Token Sequence] --> F[Text Decoder]
+ F --> D
+ F --> G[Next Token Logits]
+ G --> H[Output Text]
```
diff --git a/tutorials/openai-whisper-tutorial/03-audio-preprocessing.md b/tutorials/openai-whisper-tutorial/03-audio-preprocessing.md
index c3031a65..f6f6170d 100644
--- a/tutorials/openai-whisper-tutorial/03-audio-preprocessing.md
+++ b/tutorials/openai-whisper-tutorial/03-audio-preprocessing.md
@@ -97,186 +97,36 @@ Suggested trace strategy:
- [Main Catalog](../../README.md#-tutorial-catalog)
- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `whisper/model.py`
+### `whisper/audio.py`
-The `TextDecoder` class in [`whisper/model.py`](https://github.com/openai/whisper/blob/HEAD/whisper/model.py) handles a key part of this chapter's functionality:
+The `log_mel_spectrogram` function in [`whisper/audio.py`](https://github.com/openai/whisper/blob/HEAD/whisper/audio.py) is the core preprocessing step covered in this chapter:
```py
-
-
-class TextDecoder(nn.Module):
- def __init__(
- self, n_vocab: int, n_ctx: int, n_state: int, n_head: int, n_layer: int
- ):
- super().__init__()
-
- self.token_embedding = nn.Embedding(n_vocab, n_state)
- self.positional_embedding = nn.Parameter(torch.empty(n_ctx, n_state))
-
- self.blocks: Iterable[ResidualAttentionBlock] = nn.ModuleList(
- [
- ResidualAttentionBlock(n_state, n_head, cross_attention=True)
- for _ in range(n_layer)
- ]
- )
- self.ln = LayerNorm(n_state)
-
- mask = torch.empty(n_ctx, n_ctx).fill_(-np.inf).triu_(1)
- self.register_buffer("mask", mask, persistent=False)
-
- def forward(self, x: Tensor, xa: Tensor, kv_cache: Optional[dict] = None):
- """
- x : torch.LongTensor, shape = (batch_size, <= n_ctx)
- the text tokens
- xa : torch.Tensor, shape = (batch_size, n_audio_ctx, n_audio_state)
- the encoded audio features to be attended on
- """
- offset = next(iter(kv_cache.values())).shape[1] if kv_cache else 0
- x = (
- self.token_embedding(x)
+def log_mel_spectrogram(
+ audio: Union[str, np.ndarray, torch.Tensor],
+ n_mels: int = N_MELS,
+ padding: int = 0,
+ device: Optional[Union[str, torch.device]] = None,
+):
+ """
+ Compute the log-Mel spectrogram of an audio array.
+ The input audio is expected to be a float array of shape (samples,) in 16kHz sample rate.
+ """
```
-This class is important because it defines how OpenAI Whisper Tutorial: Speech Recognition and Translation implements the patterns covered in this chapter.
-
-### `whisper/model.py`
-
-The `Whisper` class in [`whisper/model.py`](https://github.com/openai/whisper/blob/HEAD/whisper/model.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-class Whisper(nn.Module):
- def __init__(self, dims: ModelDimensions):
- super().__init__()
- self.dims = dims
- self.encoder = AudioEncoder(
- self.dims.n_mels,
- self.dims.n_audio_ctx,
- self.dims.n_audio_state,
- self.dims.n_audio_head,
- self.dims.n_audio_layer,
- )
- self.decoder = TextDecoder(
- self.dims.n_vocab,
- self.dims.n_text_ctx,
- self.dims.n_text_state,
- self.dims.n_text_head,
- self.dims.n_text_layer,
- )
- # use the last half among the decoder layers for time alignment by default;
- # to use a specific set of heads, see `set_alignment_heads()` below.
- all_heads = torch.zeros(
- self.dims.n_text_layer, self.dims.n_text_head, dtype=torch.bool
- )
- all_heads[self.dims.n_text_layer // 2 :] = True
- self.register_buffer("alignment_heads", all_heads.to_sparse(), persistent=False)
-
- def set_alignment_heads(self, dump: bytes):
- array = np.frombuffer(
- gzip.decompress(base64.b85decode(dump)), dtype=bool
- ).copy()
-```
-
-This class is important because it defines how OpenAI Whisper Tutorial: Speech Recognition and Translation implements the patterns covered in this chapter.
-
-### `whisper/model.py`
-
-The `sinusoids` function in [`whisper/model.py`](https://github.com/openai/whisper/blob/HEAD/whisper/model.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def sinusoids(length, channels, max_timescale=10000):
- """Returns sinusoids for positional embedding"""
- assert channels % 2 == 0
- log_timescale_increment = np.log(max_timescale) / (channels // 2 - 1)
- inv_timescales = torch.exp(-log_timescale_increment * torch.arange(channels // 2))
- scaled_time = torch.arange(length)[:, np.newaxis] * inv_timescales[np.newaxis, :]
- return torch.cat([torch.sin(scaled_time), torch.cos(scaled_time)], dim=1)
-
-
-@contextmanager
-def disable_sdpa():
- prev_state = MultiHeadAttention.use_sdpa
- try:
- MultiHeadAttention.use_sdpa = False
- yield
- finally:
- MultiHeadAttention.use_sdpa = prev_state
-
-
-class MultiHeadAttention(nn.Module):
- use_sdpa = True
-
- def __init__(self, n_state: int, n_head: int):
- super().__init__()
- self.n_head = n_head
- self.query = Linear(n_state, n_state)
- self.key = Linear(n_state, n_state, bias=False)
- self.value = Linear(n_state, n_state)
- self.out = Linear(n_state, n_state)
-
-```
-
-This function is important because it defines how OpenAI Whisper Tutorial: Speech Recognition and Translation implements the patterns covered in this chapter.
-
-### `whisper/model.py`
-
-The `disable_sdpa` function in [`whisper/model.py`](https://github.com/openai/whisper/blob/HEAD/whisper/model.py) handles a key part of this chapter's functionality:
-
-```py
-
-@contextmanager
-def disable_sdpa():
- prev_state = MultiHeadAttention.use_sdpa
- try:
- MultiHeadAttention.use_sdpa = False
- yield
- finally:
- MultiHeadAttention.use_sdpa = prev_state
-
-
-class MultiHeadAttention(nn.Module):
- use_sdpa = True
-
- def __init__(self, n_state: int, n_head: int):
- super().__init__()
- self.n_head = n_head
- self.query = Linear(n_state, n_state)
- self.key = Linear(n_state, n_state, bias=False)
- self.value = Linear(n_state, n_state)
- self.out = Linear(n_state, n_state)
-
- def forward(
- self,
- x: Tensor,
- xa: Optional[Tensor] = None,
- mask: Optional[Tensor] = None,
- kv_cache: Optional[dict] = None,
- ):
- q = self.query(x)
-
- if kv_cache is None or xa is None or self.key not in kv_cache:
-```
-
-This function is important because it defines how OpenAI Whisper Tutorial: Speech Recognition and Translation implements the patterns covered in this chapter.
-
+This function converts raw audio waveforms into the 80-channel log-Mel spectrogram that Whisper's encoder processes. It applies the FFT window, mel filterbank, and log compression that are central to audio preprocessing quality.
## How These Components Connect
```mermaid
-flowchart TD
- A[TextDecoder]
- B[Whisper]
- C[sinusoids]
- D[disable_sdpa]
- E[ResultWriter]
- A --> B
- B --> C
- C --> D
- D --> E
+flowchart LR
+ A[Raw Audio File] --> B[load_audio : ffmpeg]
+ B --> C[16kHz Mono PCM]
+ C --> D[Pad to 30s Window]
+ D --> E[STFT]
+ E --> F[Mel Filterbank 80 bins]
+ F --> G[Log Compression]
+ G --> H[Audio Encoder Input]
```
diff --git a/tutorials/openai-whisper-tutorial/04-transcription-translation.md b/tutorials/openai-whisper-tutorial/04-transcription-translation.md
index 42cb5073..a3830304 100644
--- a/tutorials/openai-whisper-tutorial/04-transcription-translation.md
+++ b/tutorials/openai-whisper-tutorial/04-transcription-translation.md
@@ -99,170 +99,168 @@ Suggested trace strategy:
- [Main Catalog](../../README.md#-tutorial-catalog)
- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `whisper/utils.py`
+### `whisper/tokenizer.py`
-The `WriteTSV` class in [`whisper/utils.py`](https://github.com/openai/whisper/blob/HEAD/whisper/utils.py) handles a key part of this chapter's functionality:
+The `get_encoding` function in [`whisper/tokenizer.py`](https://github.com/openai/whisper/blob/HEAD/whisper/tokenizer.py) handles a key part of this chapter's functionality:
```py
-
-class WriteTSV(ResultWriter):
- """
- Write a transcript to a file in TSV (tab-separated values) format containing lines like:
- <start time in integer milliseconds>\t<end time in integer milliseconds>\t<transcript text>
-
- Using integer milliseconds as start and end times means there's no chance of interference from
- an environment setting a language encoding that causes the decimal in a floating point number
- to appear as a comma; also is faster and more efficient to parse & store, e.g., in C++.
- """
-
- extension: str = "tsv"
-
- def write_result(
- self, result: dict, file: TextIO, options: Optional[dict] = None, **kwargs
- ):
- print("start", "end", "text", sep="\t", file=file)
- for segment in result["segments"]:
- print(round(1000 * segment["start"]), file=file, end="\t")
- print(round(1000 * segment["end"]), file=file, end="\t")
- print(segment["text"].strip().replace("\t", " "), file=file, flush=True)
-
-
-class WriteJSON(ResultWriter):
- extension: str = "json"
-
- def write_result(
- self, result: dict, file: TextIO, options: Optional[dict] = None, **kwargs
- ):
- json.dump(result, file)
-
+@lru_cache(maxsize=None)
+def get_encoding(name: str = "gpt2", num_languages: int = 99):
+ vocab_path = os.path.join(os.path.dirname(__file__), "assets", f"{name}.tiktoken")
+ ranks = {
+ base64.b64decode(token): int(rank)
+ for token, rank in (line.split() for line in open(vocab_path) if line)
+ }
+ n_vocab = len(ranks)
+ special_tokens = {}
+
+ specials = [
+ "<|endoftext|>",
+ "<|startoftranscript|>",
+ *[f"<|{lang}|>" for lang in list(LANGUAGES.keys())[:num_languages]],
+ "<|translate|>",
+ "<|transcribe|>",
+ "<|startoflm|>",
+ "<|startofprev|>",
+ "<|nospeech|>",
+ "<|notimestamps|>",
+ *[f"<|{i * 0.02:.2f}|>" for i in range(1501)],
+ ]
+
+ for token in specials:
+ special_tokens[token] = n_vocab
+ n_vocab += 1
+
+ return tiktoken.Encoding(
+ name=os.path.basename(vocab_path),
+ explicit_n_vocab=n_vocab,
+ pat_str=r"""'s|'t|'re|'ve|'m|'ll|'d| ?\p{L}+| ?\p{N}+| ?[^\s\p{L}\p{N}]+|\s+(?!\S)|\s+""",
```
-This class is important because it defines how OpenAI Whisper Tutorial: Speech Recognition and Translation implements the patterns covered in this chapter.
+This function is important because it defines how OpenAI Whisper Tutorial: Speech Recognition and Translation implements the patterns covered in this chapter.
-### `whisper/utils.py`
+### `whisper/tokenizer.py`
-The `WriteJSON` class in [`whisper/utils.py`](https://github.com/openai/whisper/blob/HEAD/whisper/utils.py) handles a key part of this chapter's functionality:
+The `get_tokenizer` function in [`whisper/tokenizer.py`](https://github.com/openai/whisper/blob/HEAD/whisper/tokenizer.py) handles a key part of this chapter's functionality:
```py
+@lru_cache(maxsize=None)
+def get_tokenizer(
+ multilingual: bool,
+ *,
+ num_languages: int = 99,
+ language: Optional[str] = None,
+ task: Optional[str] = None, # Literal["transcribe", "translate", None]
+) -> Tokenizer:
+ if language is not None:
+ language = language.lower()
+ if language not in LANGUAGES:
+ if language in TO_LANGUAGE_CODE:
+ language = TO_LANGUAGE_CODE[language]
+ else:
+ raise ValueError(f"Unsupported language: {language}")
+
+ if multilingual:
+ encoding_name = "multilingual"
+ language = language or "en"
+ task = task or "transcribe"
+ else:
+ encoding_name = "gpt2"
+ language = None
+ task = None
-class WriteJSON(ResultWriter):
- extension: str = "json"
-
- def write_result(
- self, result: dict, file: TextIO, options: Optional[dict] = None, **kwargs
- ):
- json.dump(result, file)
-
-
-def get_writer(
- output_format: str, output_dir: str
-) -> Callable[[dict, TextIO, dict], None]:
- writers = {
- "txt": WriteTXT,
- "vtt": WriteVTT,
- "srt": WriteSRT,
- "tsv": WriteTSV,
- "json": WriteJSON,
- }
-
- if output_format == "all":
- all_writers = [writer(output_dir) for writer in writers.values()]
+ encoding = get_encoding(name=encoding_name, num_languages=num_languages)
- def write_all(
- result: dict, file: TextIO, options: Optional[dict] = None, **kwargs
- ):
- for writer in all_writers:
- writer(result, file, options, **kwargs)
+ return Tokenizer(
+ encoding=encoding, num_languages=num_languages, language=language, task=task
+ )
- return write_all
```
-This class is important because it defines how OpenAI Whisper Tutorial: Speech Recognition and Translation implements the patterns covered in this chapter.
+This function is important because it defines how OpenAI Whisper Tutorial: Speech Recognition and Translation implements the patterns covered in this chapter.
-### `whisper/utils.py`
+### `whisper/transcribe.py`
-The `exact_div` function in [`whisper/utils.py`](https://github.com/openai/whisper/blob/HEAD/whisper/utils.py) handles a key part of this chapter's functionality:
+The `transcribe` function in [`whisper/transcribe.py`](https://github.com/openai/whisper/blob/HEAD/whisper/transcribe.py) handles a key part of this chapter's functionality:
```py
-def exact_div(x, y):
- assert x % y == 0
- return x // y
-
-
-def str2bool(string):
- str2val = {"True": True, "False": False}
- if string in str2val:
- return str2val[string]
- else:
- raise ValueError(f"Expected one of {set(str2val.keys())}, got {string}")
-
-
-def optional_int(string):
- return None if string == "None" else int(string)
-
-
-def optional_float(string):
- return None if string == "None" else float(string)
-
+def transcribe(
+ model: "Whisper",
+ audio: Union[str, np.ndarray, torch.Tensor],
+ *,
+ verbose: Optional[bool] = None,
+ temperature: Union[float, Tuple[float, ...]] = (0.0, 0.2, 0.4, 0.6, 0.8, 1.0),
+ compression_ratio_threshold: Optional[float] = 2.4,
+ logprob_threshold: Optional[float] = -1.0,
+ no_speech_threshold: Optional[float] = 0.6,
+ condition_on_previous_text: bool = True,
+ initial_prompt: Optional[str] = None,
+ carry_initial_prompt: bool = False,
+ word_timestamps: bool = False,
+ prepend_punctuations: str = "\"'“¿([{-",
+ append_punctuations: str = "\"'.。,，!！?？:：”)]}、",
+ clip_timestamps: Union[str, List[float]] = "0",
+ hallucination_silence_threshold: Optional[float] = None,
+ **decode_options,
+):
+ """
+ Transcribe an audio file using Whisper
-def compression_ratio(text) -> float:
- text_bytes = text.encode("utf-8")
- return len(text_bytes) / len(zlib.compress(text_bytes))
+ Parameters
+ ----------
+ model: Whisper
+ The Whisper model instance
+ audio: Union[str, np.ndarray, torch.Tensor]
+ The path to the audio file to open, or the audio waveform
-def format_timestamp(
- seconds: float, always_include_hours: bool = False, decimal_marker: str = "."
-):
- assert seconds >= 0, "non-negative timestamp expected"
```
This function is important because it defines how OpenAI Whisper Tutorial: Speech Recognition and Translation implements the patterns covered in this chapter.
-### `whisper/utils.py`
+### `whisper/transcribe.py`
-The `str2bool` function in [`whisper/utils.py`](https://github.com/openai/whisper/blob/HEAD/whisper/utils.py) handles a key part of this chapter's functionality:
+The `cli` function in [`whisper/transcribe.py`](https://github.com/openai/whisper/blob/HEAD/whisper/transcribe.py) handles a key part of this chapter's functionality:
```py
+ prepend_punctuations: str = "\"'“¿([{-",
+ append_punctuations: str = "\"'.。,，!！?？:：”)]}、",
+ clip_timestamps: Union[str, List[float]] = "0",
+ hallucination_silence_threshold: Optional[float] = None,
+ **decode_options,
+):
+ """
+ Transcribe an audio file using Whisper
+ Parameters
+ ----------
+ model: Whisper
+ The Whisper model instance
-def str2bool(string):
- str2val = {"True": True, "False": False}
- if string in str2val:
- return str2val[string]
- else:
- raise ValueError(f"Expected one of {set(str2val.keys())}, got {string}")
-
-
-def optional_int(string):
- return None if string == "None" else int(string)
-
-
-def optional_float(string):
- return None if string == "None" else float(string)
-
+ audio: Union[str, np.ndarray, torch.Tensor]
+ The path to the audio file to open, or the audio waveform
-def compression_ratio(text) -> float:
- text_bytes = text.encode("utf-8")
- return len(text_bytes) / len(zlib.compress(text_bytes))
+ verbose: bool
+ Whether to display the text being decoded to the console. If True, displays all the details,
+ If False, displays minimal details. If None, does not display anything
+ temperature: Union[float, Tuple[float, ...]]
+ Temperature for sampling. It can be a tuple of temperatures, which will be successively used
+ upon failures according to either `compression_ratio_threshold` or `logprob_threshold`.
-def format_timestamp(
- seconds: float, always_include_hours: bool = False, decimal_marker: str = "."
-):
- assert seconds >= 0, "non-negative timestamp expected"
- milliseconds = round(seconds * 1000.0)
+ compression_ratio_threshold: float
+ If the gzip compression ratio is above this value, treat as failed
- hours = milliseconds // 3_600_000
- milliseconds -= hours * 3_600_000
+ logprob_threshold: float
+ If the average log probability over sampled tokens is below this value, treat as failed
+ no_speech_threshold: float
```
This function is important because it defines how OpenAI Whisper Tutorial: Speech Recognition and Translation implements the patterns covered in this chapter.
@@ -272,11 +270,11 @@ This function is important because it defines how OpenAI Whisper Tutorial: Speec
```mermaid
flowchart TD
- A[WriteTSV]
- B[WriteJSON]
- C[exact_div]
- D[str2bool]
- E[optional_int]
+ A[get_encoding]
+ B[get_tokenizer]
+ C[transcribe]
+ D[cli]
+ E[DecodingOptions]
A --> B
B --> C
C --> D
diff --git a/tutorials/openai-whisper-tutorial/05-fine-tuning.md b/tutorials/openai-whisper-tutorial/05-fine-tuning.md
index ee92608c..d36a72c5 100644
--- a/tutorials/openai-whisper-tutorial/05-fine-tuning.md
+++ b/tutorials/openai-whisper-tutorial/05-fine-tuning.md
@@ -97,180 +97,19 @@ Suggested trace strategy:
- [Main Catalog](../../README.md#-tutorial-catalog)
- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `whisper/utils.py`
-
-The `get_end` function in [`whisper/utils.py`](https://github.com/openai/whisper/blob/HEAD/whisper/utils.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def get_end(segments: List[dict]) -> Optional[float]:
- return next(
- (w["end"] for s in reversed(segments) for w in reversed(s["words"])),
- segments[-1]["end"] if segments else None,
- )
-
-
-class ResultWriter:
- extension: str
-
- def __init__(self, output_dir: str):
- self.output_dir = output_dir
-
- def __call__(
- self, result: dict, audio_path: str, options: Optional[dict] = None, **kwargs
- ):
- audio_basename = os.path.basename(audio_path)
- audio_basename = os.path.splitext(audio_basename)[0]
- output_path = os.path.join(
- self.output_dir, audio_basename + "." + self.extension
- )
-
- with open(output_path, "w", encoding="utf-8") as f:
- self.write_result(result, file=f, options=options, **kwargs)
-
- def write_result(
- self, result: dict, file: TextIO, options: Optional[dict] = None, **kwargs
- ):
- raise NotImplementedError
-
-```
-
-This function is important because it defines how OpenAI Whisper Tutorial: Speech Recognition and Translation implements the patterns covered in this chapter.
-
-### `whisper/utils.py`
-
-The `get_writer` function in [`whisper/utils.py`](https://github.com/openai/whisper/blob/HEAD/whisper/utils.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def get_writer(
- output_format: str, output_dir: str
-) -> Callable[[dict, TextIO, dict], None]:
- writers = {
- "txt": WriteTXT,
- "vtt": WriteVTT,
- "srt": WriteSRT,
- "tsv": WriteTSV,
- "json": WriteJSON,
- }
-
- if output_format == "all":
- all_writers = [writer(output_dir) for writer in writers.values()]
-
- def write_all(
- result: dict, file: TextIO, options: Optional[dict] = None, **kwargs
- ):
- for writer in all_writers:
- writer(result, file, options, **kwargs)
-
- return write_all
-
- return writers[output_format](output_dir)
-
-```
-
-This function is important because it defines how OpenAI Whisper Tutorial: Speech Recognition and Translation implements the patterns covered in this chapter.
-
-### `whisper/tokenizer.py`
-
-The `class` class in [`whisper/tokenizer.py`](https://github.com/openai/whisper/blob/HEAD/whisper/tokenizer.py) handles a key part of this chapter's functionality:
-
-```py
-import os
-import string
-from dataclasses import dataclass, field
-from functools import cached_property, lru_cache
-from typing import Dict, List, Optional, Tuple
-
-import tiktoken
-
-LANGUAGES = {
- "en": "english",
- "zh": "chinese",
- "de": "german",
- "es": "spanish",
- "ru": "russian",
- "ko": "korean",
- "fr": "french",
- "ja": "japanese",
- "pt": "portuguese",
- "tr": "turkish",
- "pl": "polish",
- "ca": "catalan",
- "nl": "dutch",
- "ar": "arabic",
- "sv": "swedish",
- "it": "italian",
- "id": "indonesian",
- "hi": "hindi",
- "fi": "finnish",
- "vi": "vietnamese",
- "he": "hebrew",
- "uk": "ukrainian",
- "el": "greek",
-```
-
-This class is important because it defines how OpenAI Whisper Tutorial: Speech Recognition and Translation implements the patterns covered in this chapter.
-
-### `whisper/tokenizer.py`
-
-The `get_encoding` function in [`whisper/tokenizer.py`](https://github.com/openai/whisper/blob/HEAD/whisper/tokenizer.py) handles a key part of this chapter's functionality:
-
-```py
-
-@lru_cache(maxsize=None)
-def get_encoding(name: str = "gpt2", num_languages: int = 99):
- vocab_path = os.path.join(os.path.dirname(__file__), "assets", f"{name}.tiktoken")
- ranks = {
- base64.b64decode(token): int(rank)
- for token, rank in (line.split() for line in open(vocab_path) if line)
- }
- n_vocab = len(ranks)
- special_tokens = {}
-
- specials = [
- "<|endoftext|>",
- "<|startoftranscript|>",
- *[f"<|{lang}|>" for lang in list(LANGUAGES.keys())[:num_languages]],
- "<|translate|>",
- "<|transcribe|>",
- "<|startoflm|>",
- "<|startofprev|>",
- "<|nospeech|>",
- "<|notimestamps|>",
- *[f"<|{i * 0.02:.2f}|>" for i in range(1501)],
- ]
-
- for token in specials:
- special_tokens[token] = n_vocab
- n_vocab += 1
-
- return tiktoken.Encoding(
- name=os.path.basename(vocab_path),
- explicit_n_vocab=n_vocab,
- pat_str=r"""'s|'t|'re|'ve|'m|'ll|'d| ?\p{L}+| ?\p{N}+| ?[^\s\p{L}\p{N}]+|\s+(?!\S)|\s+""",
-```
-
-This function is important because it defines how OpenAI Whisper Tutorial: Speech Recognition and Translation implements the patterns covered in this chapter.
-
+> **Note**: The official `openai/whisper` repository provides inference code only. Fine-tuning Whisper requires Hugging Face Transformers or custom training loops outside the official repo. The adaptation strategies in this chapter reference the model architecture in [`whisper/model.py`](https://github.com/openai/whisper/blob/HEAD/whisper/model.py) as the starting point for weight loading and layer modification.
## How These Components Connect
```mermaid
-flowchart TD
- A[get_end]
- B[get_writer]
- C[class]
- D[get_encoding]
- E[get_tokenizer]
- A --> B
- B --> C
- C --> D
- D --> E
+flowchart LR
+ A[Pre-trained Whisper Weights] --> B[Load with whisper.load_model]
+ B --> C[Freeze Encoder Layers]
+ C --> D[Fine-tune Decoder on Target Domain Data]
+ D --> E[Evaluate WER on Held-Out Set]
+ E --> F{Acceptable?}
+ F -->|No| D
+ F -->|Yes| G[Export Fine-tuned Checkpoint]
```
diff --git a/tutorials/openai-whisper-tutorial/06-advanced-features.md b/tutorials/openai-whisper-tutorial/06-advanced-features.md
index 42b95a77..616d94ae 100644
--- a/tutorials/openai-whisper-tutorial/06-advanced-features.md
+++ b/tutorials/openai-whisper-tutorial/06-advanced-features.md
@@ -99,186 +99,34 @@ Suggested trace strategy:
- [Main Catalog](../../README.md#-tutorial-catalog)
- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `whisper/decoding.py`
-The `SequenceRanker` class in [`whisper/decoding.py`](https://github.com/openai/whisper/blob/HEAD/whisper/decoding.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-class SequenceRanker:
- def rank(
- self, tokens: List[List[Tensor]], sum_logprobs: List[List[float]]
- ) -> List[int]:
- """
- Given a list of groups of samples and their cumulative log probabilities,
- return the indices of the samples in each group to select as the final result
- """
- raise NotImplementedError
-
-
-class MaximumLikelihoodRanker(SequenceRanker):
- """
- Select the sample with the highest log probabilities, penalized using either
- a simple length normalization or Google NMT paper's length penalty
- """
-
- def __init__(self, length_penalty: Optional[float]):
- self.length_penalty = length_penalty
-
- def rank(self, tokens: List[List[Tensor]], sum_logprobs: List[List[float]]):
- def scores(logprobs, lengths):
- result = []
- for logprob, length in zip(logprobs, lengths):
- if self.length_penalty is None:
- penalty = length
- else:
- # from the Google NMT paper
- penalty = ((5 + length) / 6) ** self.length_penalty
- result.append(logprob / penalty)
-```
-
-This class is important because it defines how OpenAI Whisper Tutorial: Speech Recognition and Translation implements the patterns covered in this chapter.
-
-### `whisper/decoding.py`
-
-The `MaximumLikelihoodRanker` class in [`whisper/decoding.py`](https://github.com/openai/whisper/blob/HEAD/whisper/decoding.py) handles a key part of this chapter's functionality:
+The `detect_language` function in [`whisper/decoding.py`](https://github.com/openai/whisper/blob/HEAD/whisper/decoding.py) is the entry point for language detection, covered in this advanced chapter:
```py
-
-
-class MaximumLikelihoodRanker(SequenceRanker):
+@torch.no_grad()
+def detect_language(
+ model: "Whisper", mel: Tensor, tokenizer: Tokenizer = None
+) -> Tuple[Tensor, List[dict]]:
"""
- Select the sample with the highest log probabilities, penalized using either
- a simple length normalization or Google NMT paper's length penalty
+ Detect the spoken language in the audio, and return them as list of strings, along with the ids
+ of the most probable language tokens and the probability distribution over all language tokens.
+ This is performed outside the main decode loop in order to not interfere with kv-caching.
"""
-
- def __init__(self, length_penalty: Optional[float]):
- self.length_penalty = length_penalty
-
- def rank(self, tokens: List[List[Tensor]], sum_logprobs: List[List[float]]):
- def scores(logprobs, lengths):
- result = []
- for logprob, length in zip(logprobs, lengths):
- if self.length_penalty is None:
- penalty = length
- else:
- # from the Google NMT paper
- penalty = ((5 + length) / 6) ** self.length_penalty
- result.append(logprob / penalty)
- return result
-
- # get the sequence with the highest score
- lengths = [[len(t) for t in s] for s in tokens]
- return [np.argmax(scores(p, l)) for p, l in zip(sum_logprobs, lengths)]
-
-
-class TokenDecoder:
- def reset(self):
- """Initialize any stateful variables for decoding a new sequence"""
-
-```
-
-This class is important because it defines how OpenAI Whisper Tutorial: Speech Recognition and Translation implements the patterns covered in this chapter.
-
-### `whisper/decoding.py`
-
-The `TokenDecoder` class in [`whisper/decoding.py`](https://github.com/openai/whisper/blob/HEAD/whisper/decoding.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-class TokenDecoder:
- def reset(self):
- """Initialize any stateful variables for decoding a new sequence"""
-
- def update(
- self, tokens: Tensor, logits: Tensor, sum_logprobs: Tensor
- ) -> Tuple[Tensor, bool]:
- """Specify how to select the next token, based on the current trace and logits
-
- Parameters
- ----------
- tokens : Tensor, shape = (n_batch, current_sequence_length)
- all tokens in the context so far, including the prefix and sot_sequence tokens
-
- logits : Tensor, shape = (n_batch, vocab_size)
- per-token logits of the probability distribution at the current step
-
- sum_logprobs : Tensor, shape = (n_batch)
- cumulative log probabilities for each sequence
-
- Returns
- -------
- tokens : Tensor, shape = (n_batch, current_sequence_length + 1)
- the tokens, appended with the selected next token
-
- completed : bool
- True if all sequences has reached the end of text
-
- """
- raise NotImplementedError
-```
-
-This class is important because it defines how OpenAI Whisper Tutorial: Speech Recognition and Translation implements the patterns covered in this chapter.
-
-### `whisper/decoding.py`
-
-The `GreedyDecoder` class in [`whisper/decoding.py`](https://github.com/openai/whisper/blob/HEAD/whisper/decoding.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-class GreedyDecoder(TokenDecoder):
- def __init__(self, temperature: float, eot: int):
- self.temperature = temperature
- self.eot = eot
-
- def update(
- self, tokens: Tensor, logits: Tensor, sum_logprobs: Tensor
- ) -> Tuple[Tensor, bool]:
- if self.temperature == 0:
- next_tokens = logits.argmax(dim=-1)
- else:
- next_tokens = Categorical(logits=logits / self.temperature).sample()
-
- logprobs = F.log_softmax(logits.float(), dim=-1)
- current_logprobs = logprobs[torch.arange(logprobs.shape[0]), next_tokens]
- sum_logprobs += current_logprobs * (tokens[:, -1] != self.eot)
-
- next_tokens[tokens[:, -1] == self.eot] = self.eot
- tokens = torch.cat([tokens, next_tokens[:, None]], dim=-1)
-
- completed = (tokens[:, -1] == self.eot).all()
- return tokens, completed
-
- def finalize(self, tokens: Tensor, sum_logprobs: Tensor):
- # make sure each sequence has at least one EOT token at the end
- tokens = F.pad(tokens, (0, 1), value=self.eot)
- return tokens, sum_logprobs.tolist()
-
-
-class BeamSearchDecoder(TokenDecoder):
```
-This class is important because it defines how OpenAI Whisper Tutorial: Speech Recognition and Translation implements the patterns covered in this chapter.
-
+This function is important because it enables multilingual detection and is the basis for advanced word-timestamp and diarization workflows described in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[SequenceRanker]
- B[MaximumLikelihoodRanker]
- C[TokenDecoder]
- D[GreedyDecoder]
- E[BeamSearchDecoder]
- A --> B
- B --> C
- C --> D
- D --> E
+ A[whisper.transcribe with word_timestamps=True] --> B[detect_language]
+ B --> C[decode with timestamps]
+ C --> D[timing.add_word_timestamps]
+ D --> E[DTW Alignment]
+ E --> F[Word-level Timestamps]
+ F --> G[Diarization Integration]
```
diff --git a/tutorials/openai-whisper-tutorial/07-performance-optimization.md b/tutorials/openai-whisper-tutorial/07-performance-optimization.md
index 7828a019..ea3e3a20 100644
--- a/tutorials/openai-whisper-tutorial/07-performance-optimization.md
+++ b/tutorials/openai-whisper-tutorial/07-performance-optimization.md
@@ -90,184 +90,182 @@ Suggested trace strategy:
- [Main Catalog](../../README.md#-tutorial-catalog)
- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `whisper/decoding.py`
+### `whisper/model.py`
-The `DecodingTask` class in [`whisper/decoding.py`](https://github.com/openai/whisper/blob/HEAD/whisper/decoding.py) handles a key part of this chapter's functionality:
+The `MultiHeadAttention` class in [`whisper/model.py`](https://github.com/openai/whisper/blob/HEAD/whisper/model.py) handles a key part of this chapter's functionality:
```py
+@contextmanager
+def disable_sdpa():
+ prev_state = MultiHeadAttention.use_sdpa
+ try:
+ MultiHeadAttention.use_sdpa = False
+ yield
+ finally:
+ MultiHeadAttention.use_sdpa = prev_state
+
+
+class MultiHeadAttention(nn.Module):
+ use_sdpa = True
+
+ def __init__(self, n_state: int, n_head: int):
+ super().__init__()
+ self.n_head = n_head
+ self.query = Linear(n_state, n_state)
+ self.key = Linear(n_state, n_state, bias=False)
+ self.value = Linear(n_state, n_state)
+ self.out = Linear(n_state, n_state)
+
+ def forward(
+ self,
+ x: Tensor,
+ xa: Optional[Tensor] = None,
+ mask: Optional[Tensor] = None,
+ kv_cache: Optional[dict] = None,
+ ):
+ q = self.query(x)
+ if kv_cache is None or xa is None or self.key not in kv_cache:
+ # hooks, if installed (i.e. kv_cache is not None), will prepend the cached kv tensors;
+```
-class DecodingTask:
- inference: Inference
- sequence_ranker: SequenceRanker
- decoder: TokenDecoder
- logit_filters: List[LogitFilter]
+This class is important because it defines how OpenAI Whisper Tutorial: Speech Recognition and Translation implements the patterns covered in this chapter.
- def __init__(self, model: "Whisper", options: DecodingOptions):
- self.model = model
+### `whisper/model.py`
- language = options.language or "en"
- tokenizer = get_tokenizer(
- model.is_multilingual,
- num_languages=model.num_languages,
- language=language,
- task=options.task,
- )
- self.tokenizer: Tokenizer = tokenizer
- self.options: DecodingOptions = self._verify_options(options)
+The `ResidualAttentionBlock` class in [`whisper/model.py`](https://github.com/openai/whisper/blob/HEAD/whisper/model.py) handles a key part of this chapter's functionality:
+
+```py
- self.n_group: int = options.beam_size or options.best_of or 1
- self.n_ctx: int = model.dims.n_text_ctx
- self.sample_len: int = options.sample_len or model.dims.n_text_ctx // 2
- self.sot_sequence: Tuple[int] = tokenizer.sot_sequence
- if self.options.without_timestamps:
- self.sot_sequence = tokenizer.sot_sequence_including_notimestamps
+class ResidualAttentionBlock(nn.Module):
+ def __init__(self, n_state: int, n_head: int, cross_attention: bool = False):
+ super().__init__()
- self.initial_tokens: Tuple[int] = self._get_initial_tokens()
- self.sample_begin: int = len(self.initial_tokens)
- self.sot_index: int = self.initial_tokens.index(tokenizer.sot)
+ self.attn = MultiHeadAttention(n_state, n_head)
+ self.attn_ln = LayerNorm(n_state)
+
+ self.cross_attn = (
+ MultiHeadAttention(n_state, n_head) if cross_attention else None
+ )
+ self.cross_attn_ln = LayerNorm(n_state) if cross_attention else None
+
+ n_mlp = n_state * 4
+ self.mlp = nn.Sequential(
+ Linear(n_state, n_mlp), nn.GELU(), Linear(n_mlp, n_state)
+ )
+ self.mlp_ln = LayerNorm(n_state)
+
+ def forward(
+ self,
+ x: Tensor,
+ xa: Optional[Tensor] = None,
+ mask: Optional[Tensor] = None,
+ kv_cache: Optional[dict] = None,
+ ):
+ x = x + self.attn(self.attn_ln(x), mask=mask, kv_cache=kv_cache)[0]
+ if self.cross_attn:
+ x = x + self.cross_attn(self.cross_attn_ln(x), xa, kv_cache=kv_cache)[0]
+ x = x + self.mlp(self.mlp_ln(x))
+ return x
```
This class is important because it defines how OpenAI Whisper Tutorial: Speech Recognition and Translation implements the patterns covered in this chapter.
-### `whisper/decoding.py`
+### `whisper/model.py`
-The `that` class in [`whisper/decoding.py`](https://github.com/openai/whisper/blob/HEAD/whisper/decoding.py) handles a key part of this chapter's functionality:
+The `AudioEncoder` class in [`whisper/model.py`](https://github.com/openai/whisper/blob/HEAD/whisper/model.py) handles a key part of this chapter's functionality:
```py
- task: str = "transcribe"
-
- # language that the audio is in; uses detected language if None
- language: Optional[str] = None
-
- # sampling-related options
- temperature: float = 0.0
- sample_len: Optional[int] = None # maximum number of tokens to sample
- best_of: Optional[int] = None # number of independent sample trajectories, if t > 0
- beam_size: Optional[int] = None # number of beams in beam search, if t == 0
- patience: Optional[float] = None # patience in beam search (arxiv:2204.05424)
-
- # "alpha" in Google NMT, or None for length norm, when ranking generations
- # to select which to return among the beams or best-of-N samples
- length_penalty: Optional[float] = None
-
- # text or tokens to feed as the prompt or the prefix; for more info:
- # https://github.com/openai/whisper/discussions/117#discussioncomment-3727051
- prompt: Optional[Union[str, List[int]]] = None # for the previous context
- prefix: Optional[Union[str, List[int]]] = None # to prefix the current context
-
- # list of tokens ids (or comma-separated token ids) to suppress
- # "-1" will suppress a set of symbols as defined in `tokenizer.non_speech_tokens()`
- suppress_tokens: Optional[Union[str, Iterable[int]]] = "-1"
- suppress_blank: bool = True # this will suppress blank outputs
-
- # timestamp sampling options
- without_timestamps: bool = False # use <|notimestamps|> to sample text tokens only
- max_initial_timestamp: Optional[float] = 1.0
-
- # implementation details
- fp16: bool = True # use fp16 for most of the calculation
-```
-This class is important because it defines how OpenAI Whisper Tutorial: Speech Recognition and Translation implements the patterns covered in this chapter.
-### `whisper/decoding.py`
+class AudioEncoder(nn.Module):
+ def __init__(
+ self, n_mels: int, n_ctx: int, n_state: int, n_head: int, n_layer: int
+ ):
+ super().__init__()
+ self.conv1 = Conv1d(n_mels, n_state, kernel_size=3, padding=1)
+ self.conv2 = Conv1d(n_state, n_state, kernel_size=3, stride=2, padding=1)
+ self.register_buffer("positional_embedding", sinusoids(n_ctx, n_state))
-The `instance` class in [`whisper/decoding.py`](https://github.com/openai/whisper/blob/HEAD/whisper/decoding.py) handles a key part of this chapter's functionality:
+ self.blocks: Iterable[ResidualAttentionBlock] = nn.ModuleList(
+ [ResidualAttentionBlock(n_state, n_head) for _ in range(n_layer)]
+ )
+ self.ln_post = LayerNorm(n_state)
-```py
- prefix_tokens = (
- self.tokenizer.encode(" " + prefix.strip())
- if isinstance(prefix, str)
- else prefix
- )
- if self.sample_len is not None:
- max_prefix_len = self.n_ctx // 2 - self.sample_len
- prefix_tokens = prefix_tokens[-max_prefix_len:]
- tokens = tokens + prefix_tokens
-
- if prompt := self.options.prompt:
- prompt_tokens = (
- self.tokenizer.encode(" " + prompt.strip())
- if isinstance(prompt, str)
- else prompt
- )
- tokens = (
- [self.tokenizer.sot_prev]
- + prompt_tokens[-(self.n_ctx // 2 - 1) :]
- + tokens
- )
-
- return tuple(tokens)
-
- def _get_suppress_tokens(self) -> Tuple[int]:
- suppress_tokens = self.options.suppress_tokens
-
- if isinstance(suppress_tokens, str):
- suppress_tokens = [int(t) for t in suppress_tokens.split(",")]
-
- if -1 in suppress_tokens:
- suppress_tokens = [t for t in suppress_tokens if t >= 0]
+ def forward(self, x: Tensor):
+ """
+ x : torch.Tensor, shape = (batch_size, n_mels, n_ctx)
+ the mel spectrogram of the audio
+ """
+ x = F.gelu(self.conv1(x))
+ x = F.gelu(self.conv2(x))
+ x = x.permute(0, 2, 1)
+
+ assert x.shape[1:] == self.positional_embedding.shape, "incorrect audio shape"
+ x = (x + self.positional_embedding).to(x.dtype)
+
+ for block in self.blocks:
+ x = block(x)
+
+ x = self.ln_post(x)
```
This class is important because it defines how OpenAI Whisper Tutorial: Speech Recognition and Translation implements the patterns covered in this chapter.
-### `whisper/decoding.py`
+### `whisper/model.py`
-The `detect_language` function in [`whisper/decoding.py`](https://github.com/openai/whisper/blob/HEAD/whisper/decoding.py) handles a key part of this chapter's functionality:
+The `TextDecoder` class in [`whisper/model.py`](https://github.com/openai/whisper/blob/HEAD/whisper/model.py) handles a key part of this chapter's functionality:
```py
-@torch.no_grad()
-def detect_language(
- model: "Whisper", mel: Tensor, tokenizer: Tokenizer = None
-) -> Tuple[Tensor, List[dict]]:
- """
- Detect the spoken language in the audio, and return them as list of strings, along with the ids
- of the most probable language tokens and the probability distribution over all language tokens.
- This is performed outside the main decode loop in order to not interfere with kv-caching.
-
- Returns
- -------
- language_tokens : Tensor, shape = (n_audio,)
- ids of the most probable language tokens, which appears after the startoftranscript token.
- language_probs : List[Dict[str, float]], length = n_audio
- list of dictionaries containing the probability distribution over all languages.
- """
- if tokenizer is None:
- tokenizer = get_tokenizer(
- model.is_multilingual, num_languages=model.num_languages
- )
- if (
- tokenizer.language is None
- or tokenizer.language_token not in tokenizer.sot_sequence
+
+class TextDecoder(nn.Module):
+ def __init__(
+ self, n_vocab: int, n_ctx: int, n_state: int, n_head: int, n_layer: int
):
- raise ValueError(
- "This model doesn't have language tokens so it can't perform lang id"
- )
+ super().__init__()
- single = mel.ndim == 2
- if single:
- mel = mel.unsqueeze(0)
+ self.token_embedding = nn.Embedding(n_vocab, n_state)
+ self.positional_embedding = nn.Parameter(torch.empty(n_ctx, n_state))
+
+ self.blocks: Iterable[ResidualAttentionBlock] = nn.ModuleList(
+ [
+ ResidualAttentionBlock(n_state, n_head, cross_attention=True)
+ for _ in range(n_layer)
+ ]
+ )
+ self.ln = LayerNorm(n_state)
+
+ mask = torch.empty(n_ctx, n_ctx).fill_(-np.inf).triu_(1)
+ self.register_buffer("mask", mask, persistent=False)
+
+ def forward(self, x: Tensor, xa: Tensor, kv_cache: Optional[dict] = None):
+ """
+ x : torch.LongTensor, shape = (batch_size, <= n_ctx)
+ the text tokens
+ xa : torch.Tensor, shape = (batch_size, n_audio_ctx, n_audio_state)
+ the encoded audio features to be attended on
+ """
+ offset = next(iter(kv_cache.values())).shape[1] if kv_cache else 0
+ x = (
+ self.token_embedding(x)
```
-This function is important because it defines how OpenAI Whisper Tutorial: Speech Recognition and Translation implements the patterns covered in this chapter.
+This class is important because it defines how OpenAI Whisper Tutorial: Speech Recognition and Translation implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[DecodingTask]
- B[that]
- C[instance]
- D[detect_language]
- E[decode]
+ A[MultiHeadAttention]
+ B[ResidualAttentionBlock]
+ C[AudioEncoder]
+ D[TextDecoder]
+ E[Whisper]
A --> B
B --> C
C --> D
diff --git a/tutorials/openai-whisper-tutorial/08-production-deployment.md b/tutorials/openai-whisper-tutorial/08-production-deployment.md
index 68fdc4b8..2310e0c4 100644
--- a/tutorials/openai-whisper-tutorial/08-production-deployment.md
+++ b/tutorials/openai-whisper-tutorial/08-production-deployment.md
@@ -98,178 +98,16 @@ Suggested trace strategy:
- [Main Catalog](../../README.md#-tutorial-catalog)
- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
-## Depth Expansion Playbook
-
-## Source Code Walkthrough
-
-### `whisper/audio.py`
-
-The `mel_filters` function in [`whisper/audio.py`](https://github.com/openai/whisper/blob/HEAD/whisper/audio.py) handles a key part of this chapter's functionality:
-
-```py
-
-@lru_cache(maxsize=None)
-def mel_filters(device, n_mels: int) -> torch.Tensor:
- """
- load the mel filterbank matrix for projecting STFT into a Mel spectrogram.
- Allows decoupling librosa dependency; saved using:
-
- np.savez_compressed(
- "mel_filters.npz",
- mel_80=librosa.filters.mel(sr=16000, n_fft=400, n_mels=80),
- mel_128=librosa.filters.mel(sr=16000, n_fft=400, n_mels=128),
- )
- """
- assert n_mels in {80, 128}, f"Unsupported n_mels: {n_mels}"
-
- filters_path = os.path.join(os.path.dirname(__file__), "assets", "mel_filters.npz")
- with np.load(filters_path, allow_pickle=False) as f:
- return torch.from_numpy(f[f"mel_{n_mels}"]).to(device)
-
-
-def log_mel_spectrogram(
- audio: Union[str, np.ndarray, torch.Tensor],
- n_mels: int = 80,
- padding: int = 0,
- device: Optional[Union[str, torch.device]] = None,
-):
- """
- Compute the log-Mel spectrogram of
-
- Parameters
- ----------
- audio: Union[str, np.ndarray, torch.Tensor], shape = (*)
-```
-
-This function is important because it defines how OpenAI Whisper Tutorial: Speech Recognition and Translation implements the patterns covered in this chapter.
-
-### `whisper/audio.py`
-
-The `log_mel_spectrogram` function in [`whisper/audio.py`](https://github.com/openai/whisper/blob/HEAD/whisper/audio.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def log_mel_spectrogram(
- audio: Union[str, np.ndarray, torch.Tensor],
- n_mels: int = 80,
- padding: int = 0,
- device: Optional[Union[str, torch.device]] = None,
-):
- """
- Compute the log-Mel spectrogram of
-
- Parameters
- ----------
- audio: Union[str, np.ndarray, torch.Tensor], shape = (*)
- The path to audio or either a NumPy array or Tensor containing the audio waveform in 16 kHz
-
- n_mels: int
- The number of Mel-frequency filters, only 80 and 128 are supported
-
- padding: int
- Number of zero samples to pad to the right
-
- device: Optional[Union[str, torch.device]]
- If given, the audio tensor is moved to this device before STFT
-
- Returns
- -------
- torch.Tensor, shape = (n_mels, n_frames)
- A Tensor that contains the Mel spectrogram
- """
- if not torch.is_tensor(audio):
- if isinstance(audio, str):
-```
-
-This function is important because it defines how OpenAI Whisper Tutorial: Speech Recognition and Translation implements the patterns covered in this chapter.
-
-### `whisper/normalizers/basic.py`
-
-The `BasicTextNormalizer` class in [`whisper/normalizers/basic.py`](https://github.com/openai/whisper/blob/HEAD/whisper/normalizers/basic.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-class BasicTextNormalizer:
- def __init__(self, remove_diacritics: bool = False, split_letters: bool = False):
- self.clean = (
- remove_symbols_and_diacritics if remove_diacritics else remove_symbols
- )
- self.split_letters = split_letters
-
- def __call__(self, s: str):
- s = s.lower()
- s = re.sub(r"[<\[][^>\]]*[>\]]", "", s) # remove words between brackets
- s = re.sub(r"\(([^)]+?)\)", "", s) # remove words between parenthesis
- s = self.clean(s).lower()
-
- if self.split_letters:
- s = " ".join(regex.findall(r"\X", s, regex.U))
-
- s = re.sub(
- r"\s+", " ", s
- ) # replace any successive whitespace characters with a space
-
- return s
-
-```
-
-This class is important because it defines how OpenAI Whisper Tutorial: Speech Recognition and Translation implements the patterns covered in this chapter.
-
-### `whisper/normalizers/basic.py`
-
-The `remove_symbols_and_diacritics` function in [`whisper/normalizers/basic.py`](https://github.com/openai/whisper/blob/HEAD/whisper/normalizers/basic.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def remove_symbols_and_diacritics(s: str, keep=""):
- """
- Replace any other markers, symbols, and punctuations with a space,
- and drop any diacritics (category 'Mn' and some manual mappings)
- """
- return "".join(
- (
- c
- if c in keep
- else (
- ADDITIONAL_DIACRITICS[c]
- if c in ADDITIONAL_DIACRITICS
- else (
- ""
- if unicodedata.category(c) == "Mn"
- else " " if unicodedata.category(c)[0] in "MSP" else c
- )
- )
- )
- for c in unicodedata.normalize("NFKD", s)
- )
-
-
-def remove_symbols(s: str):
- """
- Replace any other markers, symbols, punctuations with a space, keeping diacritics
- """
- return "".join(
- " " if unicodedata.category(c)[0] in "MSP" else c
- for c in unicodedata.normalize("NFKC", s)
-```
-
-This function is important because it defines how OpenAI Whisper Tutorial: Speech Recognition and Translation implements the patterns covered in this chapter.
-
-
## How These Components Connect
```mermaid
flowchart TD
- A[mel_filters]
- B[log_mel_spectrogram]
- C[BasicTextNormalizer]
- D[remove_symbols_and_diacritics]
- E[remove_symbols]
- A --> B
- B --> C
- C --> D
- D --> E
+ A[Audio Input Stream] --> B[Whisper Service]
+ B --> C[Worker Pool]
+ C --> D[whisper.transcribe]
+ D --> E[Result Cache]
+ E --> F[API Response]
+ B --> G[Health Check Endpoint]
+ B --> H[Metrics / Prometheus]
+ H --> I[Alerting]
```
diff --git a/tutorials/openclaw-tutorial/04-agent-runtime.md b/tutorials/openclaw-tutorial/04-agent-runtime.md
index 43cde36d..8b84ab2e 100644
--- a/tutorials/openclaw-tutorial/04-agent-runtime.md
+++ b/tutorials/openclaw-tutorial/04-agent-runtime.md
@@ -620,6 +620,116 @@ class AgentErrorHandler {
}
```
+## ACP Layer (`extensions/acpx`)
+
+OpenClaw includes an **Agent Communication Protocol (ACP)** extension that lets it communicate with other ACP-compatible agents in a multi-agent network. ACP is an emerging open standard for agent-to-agent messaging; OpenClaw implements it via the `acpx` extension (`extensions/acpx/`).
+
+### What Problem It Solves
+
+A single Pi Agent can handle most tasks alone, but some workflows benefit from specialist agents running in other processes, on other machines, or implemented in other frameworks. ACP provides a standard envelope for cross-agent requests so OpenClaw can delegate to — or be orchestrated by — any ACP-compatible peer without bespoke integrations.
+
+### How It Works
+
+```mermaid
+graph TB
+ subgraph Local["OpenClaw Instance"]
+ AGENT[Pi Agent]
+ ACP_EXT[acpx Extension<br/>extensions/acpx/index.ts]
+ ACP_RT[ACP Runtime<br/>src/runtime.ts]
+ ACP_SVC[ACP Service<br/>src/service.ts]
+ ROUTER[acp-router Skill<br/>skills/acp-router/]
+ end
+
+ subgraph Network["ACP Network"]
+ PEER_A[ACP Agent A<br/>another framework]
+ PEER_B[ACP Agent B<br/>specialist model]
+ ORCHESTRATOR[ACP Orchestrator]
+ end
+
+ AGENT --> ACP_EXT
+ ACP_EXT --> ACP_RT
+ ACP_RT --> ACP_SVC
+ ACP_SVC -->|ACP messages| PEER_A
+ ACP_SVC -->|ACP messages| PEER_B
+ ORCHESTRATOR -->|orchestrate OpenClaw| ACP_SVC
+ ACP_EXT --> ROUTER
+```
+
+### Key Source Files
+
+| File | Role |
+|------|------|
+| `extensions/acpx/index.ts` | Extension entry point; registers with OpenClaw plugin system |
+| `extensions/acpx/src/runtime.ts` | ACP session lifecycle and message dispatch |
+| `extensions/acpx/src/service.ts` | HTTP service that speaks the ACP wire protocol |
+| `extensions/acpx/src/config.ts` | ACP endpoint configuration and peer registry |
+| `extensions/acpx/src/config-schema.ts` | Config schema (validates peer URLs, auth tokens) |
+| `extensions/acpx/skills/acp-router/SKILL.md` | Skill that exposes `acp_call` tool to the Pi Agent |
+| `extensions/acpx/src/runtime-internals/mcp-proxy.mjs` | MCP-over-ACP bridge for MCP-native peers |
+| `extensions/acpx/register.runtime.ts` | Hooks into OpenClaw's extension registration system |
+| `extensions/acpx/runtime-api.ts` | Public API surface used by other extensions |
+| `extensions/acpx/setup-api.ts` | Setup/teardown helpers for integration tests |
+
+### Calling a Peer Agent
+
+When `acpx` is installed, the Pi Agent gains an `acp_call` tool it can invoke during its reasoning loop:
+
+```typescript
+// The agent emits a tool call like this during planning:
+{
+ tool: "acp_call",
+ input: {
+ agent: "research-specialist", // peer alias from config
+ task: "Summarize the latest news about transformer attention",
+ context: { format: "bullets", max_length: 500 },
+ }
+}
+
+// acpx wraps this in an ACP envelope and sends it to the peer:
+// POST https://research-agent.internal/acp/v1/tasks
+// {
+// "task": "Summarize...",
+// "context": { ... },
+// "reply_to": "https://my-openclaw.internal/acp/v1/callbacks/abc123"
+// }
+```
+
+The response flows back through the ACP service into a `tool_result` block, which the agent uses in its next reasoning step — indistinguishable from any other tool result.
+
+### Enabling ACP
+
+```yaml
+# In config.yaml — enable the acpx extension and register peers
+extensions:
+ acpx:
+ enabled: true
+ peers:
+ research-specialist:
+ url: https://research-agent.internal
+ auth_token: ${RESEARCH_AGENT_TOKEN}
+ coding-agent:
+ url: https://coding-agent.internal
+ auth_token: ${CODING_AGENT_TOKEN}
+ # Expose OpenClaw itself as an ACP endpoint
+ server:
+ enabled: true
+ port: 19876
+ auth_token: ${MY_ACP_TOKEN}
+```
+
+### Integration Tests Pattern
+
+The ACP layer has deep integration test coverage. Files like `extensions/discord/src/monitor/acp-bind-here.integration.test.ts` show the canonical pattern for testing ACP bindings: start a mock peer, bind a channel, send a message, assert the ACP envelope was formed correctly.
+
+### When to Use ACP
+
+- You have a specialist model or agent optimized for a narrow task (e.g., code review, legal analysis)
+- You want to orchestrate multiple OpenClaw instances across devices
+- You're building a multi-agent pipeline where OpenClaw is one node
+- You need to connect OpenClaw to an MCP server via the built-in MCP-over-ACP bridge (`mcp-proxy.mjs`)
+
+---
+
## Summary
| Component | Purpose |
diff --git a/tutorials/openclaw-tutorial/05-memory-sessions.md b/tutorials/openclaw-tutorial/05-memory-sessions.md
index 468fc82e..80df8c33 100644
--- a/tutorials/openclaw-tutorial/05-memory-sessions.md
+++ b/tutorials/openclaw-tutorial/05-memory-sessions.md
@@ -608,6 +608,113 @@ class CrossChannelMemory {
}
```
+## Memory Host SDK (`packages/memory-host-sdk`)
+
+The high-level memory system described above is powered under the hood by a dedicated package: `packages/memory-host-sdk`. This SDK is the production-grade semantic memory engine that ships with OpenClaw and handles vector embeddings, provider routing, persistent storage, and a custom query language.
+
+### What Problem It Solves
+
+The built-in `FactMemory` and `EpisodicMemory` classes need a reliable, provider-agnostic way to generate embeddings, store vectors, and run similarity searches. `memory-host-sdk` provides a single engine that abstracts away eight different embedding backends behind a uniform interface, so the rest of the codebase never has to care whether embeddings come from OpenAI, a local Ollama model, or AWS Bedrock.
+
+### Architecture
+
+```mermaid
+graph TB
+ subgraph SDK["memory-host-sdk"]
+ ENGINE[engine.ts<br/>MemoryEngine]
+ EMB[engine-embeddings.ts<br/>EmbeddingRouter]
+ QMD[engine-qmd.ts<br/>QMD Query Parser]
+ STORE[engine-storage.ts<br/>SQLite + sqlite-vec]
+ FOUND[engine-foundation.ts<br/>Schema & Migrations]
+ end
+
+ subgraph Backends["Embedding Backends (packages/memory-host-sdk/src/host/)"]
+ OAI[embeddings-openai.ts]
+ VOY[embeddings-voyage.ts]
+ GEM[embeddings-gemini.ts]
+ OLL[embeddings-ollama.ts]
+ MIS[embeddings-mistral.ts]
+ BED[embeddings-bedrock.ts]
+ REM[embeddings-remote-provider.ts]
+ end
+
+ ENGINE --> EMB
+ ENGINE --> QMD
+ ENGINE --> STORE
+ STORE --> FOUND
+ EMB --> OAI
+ EMB --> VOY
+ EMB --> GEM
+ EMB --> OLL
+ EMB --> MIS
+ EMB --> BED
+ EMB --> REM
+```
+
+### Key Source Files
+
+| File | Role |
+|------|------|
+| `src/engine.ts` | Top-level `MemoryEngine` — entry point for all memory operations |
+| `src/engine-embeddings.ts` | Routes embedding requests to the configured backend |
+| `src/engine-qmd.ts` | Parses and executes QMD queries against the vector store |
+| `src/engine-storage.ts` | SQLite + `sqlite-vec` for vector persistence |
+| `src/engine-foundation.ts` | Schema definitions and migration helpers |
+| `src/host/embeddings-openai.ts` | OpenAI `text-embedding-3-*` backend |
+| `src/host/embeddings-voyage.ts` | Voyage AI backend (best for code/technical content) |
+| `src/host/embeddings-bedrock.ts` | AWS Bedrock Titan/Cohere backends |
+| `src/host/embeddings-ollama.ts` | Local Ollama backend (fully offline) |
+| `src/host/qmd-query-parser.ts` | QMD lexer + parser |
+| `src/host/qmd-process.ts` | QMD execution engine |
+| `src/host/session-files.ts` | Per-session memory file layout on disk |
+
+### QMD: Query Memory Description Language
+
+QMD is a purpose-built query syntax for filtering memories by metadata and running vector similarity searches in one pass. It avoids the impedance mismatch of writing raw SQL against a vector table:
+
+```typescript
+// Example QMD queries
+const results = await engine.query(
+ // Semantic search scoped to a category and recency window
+ "remember my preferences FOR:preference SINCE:30d LIMIT:10"
+);
+
+const codeMemories = await engine.query(
+ // Find memories tagged for a specific project with min similarity
+ "typescript patterns FOR:technical TAG:project-alpha SIM:0.75"
+);
+```
+
+QMD expressions are parsed in `src/host/qmd-query-parser.ts`, compiled to a query plan in `src/host/qmd-scope.ts`, and executed against the SQLite vector store in `src/host/qmd-process.ts`.
+
+### Configuring the Embedding Backend
+
+```typescript
+// In openclaw config (config.yaml)
+memory:
+ embedding_provider: voyage # openai | voyage | gemini | ollama | mistral | bedrock | remote
+ embedding_model: voyage-3-large
+ voyage_api_key: ${VOYAGE_API_KEY}
+
+# For fully local/offline operation:
+memory:
+ embedding_provider: ollama
+ embedding_model: nomic-embed-text
+ ollama_base_url: http://localhost:11434
+```
+
+The `backend-config.ts` module validates provider config at startup and fails fast if required credentials are missing, preventing silent fallback to lower-quality embeddings.
+
+### When to Use This Directly
+
+Most users never touch `memory-host-sdk` directly — OpenClaw wires it automatically. Reach for it directly when:
+- Building a custom memory backend or alternative storage layer
+- Writing integration tests that need to verify embedding quality
+- Extending the QMD language with project-specific filter clauses
+- Migrating to a new embedding provider (swap one backend file, everything else stays the same)
+
+---
+
## Summary
| Concept | Key Takeaway |
diff --git a/tutorials/openclaw-tutorial/06-skills-tools.md b/tutorials/openclaw-tutorial/06-skills-tools.md
index 13a0402a..64d745f0 100644
--- a/tutorials/openclaw-tutorial/06-skills-tools.md
+++ b/tutorials/openclaw-tutorial/06-skills-tools.md
@@ -611,6 +611,145 @@ class DeviceNodeSkill implements SkillDefinition {
}
```
+## Plugin SDK (`packages/plugin-sdk` + `packages/plugin-package-contract`)
+
+Beyond the built-in skills described above, OpenClaw has a full **plugin system** where third parties can publish capabilities as ordinary npm packages. The Plugin SDK provides the runtime scaffolding; the plugin-package-contract defines the interface every plugin must satisfy.
+
+### What Problem It Solves
+
+Built-in skills are compiled into the OpenClaw binary — adding a new integration requires a pull request to the main repo. Plugins solve this by letting anyone publish an `npm` package that follows a standard contract. Users install plugins with a single command; no recompilation required.
+
+### How the Two Packages Fit Together
+
+```mermaid
+graph LR
+ subgraph Contract["packages/plugin-package-contract"]
+ ENTRY[plugin-entry.ts<br/>PluginEntry interface]
+ PAUTH[provider-auth.ts<br/>AuthContract]
+ PTOOLS[provider-tools.ts<br/>ToolsContract]
+ PWEB[provider-web-search.ts<br/>WebSearchContract]
+ PMODEL[provider-model-types.ts<br/>ModelContract]
+ end
+
+ subgraph SDK["packages/plugin-sdk"]
+ RUNTIME[plugin-runtime.ts<br/>PluginRuntime]
+ CONF[config-runtime.ts<br/>ConfigRuntime]
+ SEC[security-runtime.ts<br/>SecurityRuntime]
+ DOC[runtime-doctor.ts<br/>HealthChecker]
+ TEST[testing.ts<br/>TestHarness]
+ end
+
+ subgraph Plugin["Your Plugin (npm package)"]
+ IMPL[index.ts implements PluginEntry]
+ end
+
+ IMPL -->|satisfies| ENTRY
+ SDK --> RUNTIME
+ RUNTIME -->|loads & validates| IMPL
+ Contract --> SDK
+```
+
+### Key Source Files
+
+| Package | File | Role |
+|---------|------|------|
+| `plugin-package-contract` | `src/index.ts` | Exports all interface types a plugin must implement |
+| `plugin-sdk` | `src/plugin-entry.ts` | Plugin entry-point loader and validator |
+| `plugin-sdk` | `src/plugin-runtime.ts` | Lifecycle management (load, configure, unload) |
+| `plugin-sdk` | `src/config-runtime.ts` | Plugin configuration schema validation |
+| `plugin-sdk` | `src/security-runtime.ts` | Sandboxing and permission enforcement |
+| `plugin-sdk` | `src/runtime-doctor.ts` | Health checks and plugin diagnostics |
+| `plugin-sdk` | `src/testing.ts` | Test harness for plugin unit tests |
+| `plugin-sdk` | `src/provider-auth.ts` | OAuth / token provider contract helpers |
+| `plugin-sdk` | `src/provider-http.ts` | Authenticated HTTP client for plugin use |
+
+### Writing a Plugin
+
+A minimal plugin package follows this structure:
+
+```typescript
+// my-openclaw-plugin/src/index.ts
+import type { PluginEntry, ToolsContract } from "@openclaw/plugin-package-contract";
+
+const tools: ToolsContract = {
+ definitions: [
+ {
+ name: "jira_create_issue",
+ description: "Create a Jira issue",
+ parameters: {
+ type: "object",
+ properties: {
+ project: { type: "string" },
+ summary: { type: "string" },
+ description: { type: "string" },
+ },
+ required: ["project", "summary"],
+ },
+ handler: async (params, context) => {
+ // Implementation using context.config for credentials
+ const resp = await context.http.post(
+ `${context.config.base_url}/rest/api/3/issue`,
+ { fields: { project: { key: params.project }, summary: params.summary } }
+ );
+ return { id: resp.id, url: `${context.config.base_url}/browse/${resp.key}` };
+ },
+ },
+ ],
+};
+
+const plugin: PluginEntry = {
+ name: "jira",
+ version: "1.0.0",
+ tools,
+ configSchema: {
+ type: "object",
+ properties: {
+ base_url: { type: "string" },
+ api_token: { type: "string" },
+ },
+ required: ["base_url", "api_token"],
+ },
+};
+
+export default plugin;
+```
+
+The `openclaw.plugin.json` manifest at the package root declares the entry point and required permissions — see `extensions/acpx/openclaw.plugin.json` for a real-world reference.
+
+### Installing and Managing Plugins
+
+```bash
+# Install from npm
+openclaw plugin install @myorg/openclaw-jira-plugin
+
+# Install from local path (development)
+openclaw plugin install ./my-openclaw-plugin
+
+# List installed plugins
+openclaw plugin list
+
+# Configure a plugin
+openclaw plugin config jira --set base_url=https://myorg.atlassian.net --set api_token=$TOKEN
+
+# Run health check
+openclaw plugin doctor jira
+
+# Uninstall
+openclaw plugin remove jira
+```
+
+### When to Build a Plugin vs. a Custom Skill
+
+| Situation | Recommendation |
+|-----------|---------------|
+| Internal tool, not shared | Custom skill in `skills/` directory |
+| Integration to distribute on npm | Plugin via `plugin-sdk` |
+| Need OAuth provider support | Plugin (use `provider-auth.ts`) |
+| Need to add a new AI model provider | Plugin (implement `ModelContract`) |
+| Need to add a custom web search | Plugin (implement `WebSearchContract`) |
+
+---
+
## Summary
| Concept | Key Takeaway |
diff --git a/tutorials/openclaw-tutorial/README.md b/tutorials/openclaw-tutorial/README.md
index 2834bd23..07c9376a 100644
--- a/tutorials/openclaw-tutorial/README.md
+++ b/tutorials/openclaw-tutorial/README.md
@@ -42,8 +42,8 @@ OpenClaw is an open-source, self-hosted personal AI assistant that connects to t
## Current Snapshot (auto-updated)
- repository: [`openclaw/openclaw`](https://github.com/openclaw/openclaw)
-- stars: about **349k**
-- latest release: [`v2026.4.5`](https://github.com/openclaw/openclaw/releases/tag/v2026.4.5) (published 2026-04-06)
+- stars: about **355k**
+- latest release: [`v2026.3.28`](https://github.com/openclaw/openclaw/releases/tag/v2026.3.28) (published 2026-03-29)
## Mental Model
diff --git a/tutorials/opencode-ai-legacy-tutorial/01-getting-started-and-project-status.md b/tutorials/opencode-ai-legacy-tutorial/01-getting-started-and-project-status.md
index 65cd20d5..2a794da1 100644
--- a/tutorials/opencode-ai-legacy-tutorial/01-getting-started-and-project-status.md
+++ b/tutorials/opencode-ai-legacy-tutorial/01-getting-started-and-project-status.md
@@ -35,10 +35,32 @@ You now have the right baseline context for responsible legacy usage.
Next: [Chapter 2: Legacy Architecture and Feature Model](02-legacy-architecture-and-feature-model.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
+### `main.go`
+
+The `main` function in [`main.go`](https://github.com/opencode-ai/opencode/blob/HEAD/main.go) handles a key part of this chapter's functionality:
+
+```go
+package main
+
+import (
+ "github.com/opencode-ai/opencode/cmd"
+ "github.com/opencode-ai/opencode/internal/logging"
+)
+
+func main() {
+ defer logging.RecoverPanic("main", func() {
+ logging.ErrorPersist("Application terminated due to unhandled panic")
+ })
+
+ cmd.Execute()
+}
+
+```
+
+This function is important because it defines how OpenCode AI Legacy Tutorial: Archived Terminal Agent Workflows and Migration to Crush implements the patterns covered in this chapter.
+
### `internal/lsp/methods.go`
The `Implementation` function in [`internal/lsp/methods.go`](https://github.com/opencode-ai/opencode/blob/HEAD/internal/lsp/methods.go) handles a key part of this chapter's functionality:
@@ -162,57 +184,16 @@ func (c *Client) Declaration(ctx context.Context, params protocol.DeclarationPar
This function is important because it defines how OpenCode AI Legacy Tutorial: Archived Terminal Agent Workflows and Migration to Crush implements the patterns covered in this chapter.
-### `internal/lsp/methods.go`
-
-The `ColorPresentation` function in [`internal/lsp/methods.go`](https://github.com/opencode-ai/opencode/blob/HEAD/internal/lsp/methods.go) handles a key part of this chapter's functionality:
-
-```go
-}
-
-// ColorPresentation sends a textDocument/colorPresentation request to the LSP server.
-// A request to list all presentation for a color. The request's parameter is of type ColorPresentationParams the response is of type ColorInformation ColorInformation[] or a Thenable that resolves to such.
-func (c *Client) ColorPresentation(ctx context.Context, params protocol.ColorPresentationParams) ([]protocol.ColorPresentation, error) {
- var result []protocol.ColorPresentation
- err := c.Call(ctx, "textDocument/colorPresentation", params, &result)
- return result, err
-}
-
-// FoldingRange sends a textDocument/foldingRange request to the LSP server.
-// A request to provide folding ranges in a document. The request's parameter is of type FoldingRangeParams, the response is of type FoldingRangeList or a Thenable that resolves to such.
-func (c *Client) FoldingRange(ctx context.Context, params protocol.FoldingRangeParams) ([]protocol.FoldingRange, error) {
- var result []protocol.FoldingRange
- err := c.Call(ctx, "textDocument/foldingRange", params, &result)
- return result, err
-}
-
-// Declaration sends a textDocument/declaration request to the LSP server.
-// A request to resolve the type definition locations of a symbol at a given text document position. The request's parameter is of type TextDocumentPositionParams the response is of type Declaration or a typed array of DeclarationLink or a Thenable that resolves to such.
-func (c *Client) Declaration(ctx context.Context, params protocol.DeclarationParams) (protocol.Or_Result_textDocument_declaration, error) {
- var result protocol.Or_Result_textDocument_declaration
- err := c.Call(ctx, "textDocument/declaration", params, &result)
- return result, err
-}
-
-// SelectionRange sends a textDocument/selectionRange request to the LSP server.
-// A request to provide selection ranges in a document. The request's parameter is of type SelectionRangeParams, the response is of type SelectionRange SelectionRange[] or a Thenable that resolves to such.
-func (c *Client) SelectionRange(ctx context.Context, params protocol.SelectionRangeParams) ([]protocol.SelectionRange, error) {
- var result []protocol.SelectionRange
- err := c.Call(ctx, "textDocument/selectionRange", params, &result)
- return result, err
-```
-
-This function is important because it defines how OpenCode AI Legacy Tutorial: Archived Terminal Agent Workflows and Migration to Crush implements the patterns covered in this chapter.
-
## How These Components Connect
```mermaid
flowchart TD
- A[Implementation]
- B[TypeDefinition]
- C[DocumentColor]
- D[ColorPresentation]
- E[FoldingRange]
+ A[main]
+ B[Implementation]
+ C[TypeDefinition]
+ D[DocumentColor]
+ E[ColorPresentation]
A --> B
B --> C
C --> D
diff --git a/tutorials/opencode-ai-legacy-tutorial/02-legacy-architecture-and-feature-model.md b/tutorials/opencode-ai-legacy-tutorial/02-legacy-architecture-and-feature-model.md
index 5e42c243..1e5f2269 100644
--- a/tutorials/opencode-ai-legacy-tutorial/02-legacy-architecture-and-feature-model.md
+++ b/tutorials/opencode-ai-legacy-tutorial/02-legacy-architecture-and-feature-model.md
@@ -37,17 +37,23 @@ You now understand what parts of the legacy architecture remain worth carrying f
Next: [Chapter 3: Installation and Configuration Baseline](03-installation-and-configuration-baseline.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `internal/lsp/methods.go`
-The `DocumentHighlight` function in [`internal/lsp/methods.go`](https://github.com/opencode-ai/opencode/blob/HEAD/internal/lsp/methods.go) handles a key part of this chapter's functionality:
+The `References` function in [`internal/lsp/methods.go`](https://github.com/opencode-ai/opencode/blob/HEAD/internal/lsp/methods.go) handles a key part of this chapter's functionality:
```go
}
+// References sends a textDocument/references request to the LSP server.
+// A request to resolve project-wide references for the symbol denoted by the given text document position. The request's parameter is of type ReferenceParams the response is of type Location Location[] or a Thenable that resolves to such.
+func (c *Client) References(ctx context.Context, params protocol.ReferenceParams) ([]protocol.Location, error) {
+ var result []protocol.Location
+ err := c.Call(ctx, "textDocument/references", params, &result)
+ return result, err
+}
+
// DocumentHighlight sends a textDocument/documentHighlight request to the LSP server.
// Request to resolve a DocumentHighlight for a given text document position. The request's parameter is of type TextDocumentPosition the request response is an array of type DocumentHighlight or a Thenable that resolves to such.
func (c *Client) DocumentHighlight(ctx context.Context, params protocol.DocumentHighlightParams) ([]protocol.DocumentHighlight, error) {
@@ -70,25 +76,25 @@ func (c *Client) CodeAction(ctx context.Context, params protocol.CodeActionParam
var result []protocol.Or_Result_textDocument_codeAction_Item0_Elem
err := c.Call(ctx, "textDocument/codeAction", params, &result)
return result, err
-}
-
-// ResolveCodeAction sends a codeAction/resolve request to the LSP server.
-// Request to resolve additional information for a given code action.The request's parameter is of type CodeAction the response is of type CodeAction or a Thenable that resolves to such.
-func (c *Client) ResolveCodeAction(ctx context.Context, params protocol.CodeAction) (protocol.CodeAction, error) {
- var result protocol.CodeAction
- err := c.Call(ctx, "codeAction/resolve", params, &result)
- return result, err
```
This function is important because it defines how OpenCode AI Legacy Tutorial: Archived Terminal Agent Workflows and Migration to Crush implements the patterns covered in this chapter.
### `internal/lsp/methods.go`
-The `DocumentSymbol` function in [`internal/lsp/methods.go`](https://github.com/opencode-ai/opencode/blob/HEAD/internal/lsp/methods.go) handles a key part of this chapter's functionality:
+The `DocumentHighlight` function in [`internal/lsp/methods.go`](https://github.com/opencode-ai/opencode/blob/HEAD/internal/lsp/methods.go) handles a key part of this chapter's functionality:
```go
}
+// DocumentHighlight sends a textDocument/documentHighlight request to the LSP server.
+// Request to resolve a DocumentHighlight for a given text document position. The request's parameter is of type TextDocumentPosition the request response is an array of type DocumentHighlight or a Thenable that resolves to such.
+func (c *Client) DocumentHighlight(ctx context.Context, params protocol.DocumentHighlightParams) ([]protocol.DocumentHighlight, error) {
+ var result []protocol.DocumentHighlight
+ err := c.Call(ctx, "textDocument/documentHighlight", params, &result)
+ return result, err
+}
+
// DocumentSymbol sends a textDocument/documentSymbol request to the LSP server.
// A request to list all symbols found in a given text document. The request's parameter is of type TextDocumentIdentifier the response is of type SymbolInformation SymbolInformation[] or a Thenable that resolves to such.
func (c *Client) DocumentSymbol(ctx context.Context, params protocol.DocumentSymbolParams) (protocol.Or_Result_textDocument_documentSymbol, error) {
@@ -111,25 +117,25 @@ func (c *Client) ResolveCodeAction(ctx context.Context, params protocol.CodeActi
var result protocol.CodeAction
err := c.Call(ctx, "codeAction/resolve", params, &result)
return result, err
-}
-
-// Symbol sends a workspace/symbol request to the LSP server.
-// A request to list project-wide symbols matching the query string given by the WorkspaceSymbolParams. The response is of type SymbolInformation SymbolInformation[] or a Thenable that resolves to such. Since 3.17.0 - support for WorkspaceSymbol in the returned data. Clients need to advertise support for WorkspaceSymbols via the client capability workspace.symbol.resolveSupport.
-func (c *Client) Symbol(ctx context.Context, params protocol.WorkspaceSymbolParams) (protocol.Or_Result_workspace_symbol, error) {
- var result protocol.Or_Result_workspace_symbol
- err := c.Call(ctx, "workspace/symbol", params, &result)
- return result, err
```
This function is important because it defines how OpenCode AI Legacy Tutorial: Archived Terminal Agent Workflows and Migration to Crush implements the patterns covered in this chapter.
### `internal/lsp/methods.go`
-The `CodeAction` function in [`internal/lsp/methods.go`](https://github.com/opencode-ai/opencode/blob/HEAD/internal/lsp/methods.go) handles a key part of this chapter's functionality:
+The `DocumentSymbol` function in [`internal/lsp/methods.go`](https://github.com/opencode-ai/opencode/blob/HEAD/internal/lsp/methods.go) handles a key part of this chapter's functionality:
```go
}
+// DocumentSymbol sends a textDocument/documentSymbol request to the LSP server.
+// A request to list all symbols found in a given text document. The request's parameter is of type TextDocumentIdentifier the response is of type SymbolInformation SymbolInformation[] or a Thenable that resolves to such.
+func (c *Client) DocumentSymbol(ctx context.Context, params protocol.DocumentSymbolParams) (protocol.Or_Result_textDocument_documentSymbol, error) {
+ var result protocol.Or_Result_textDocument_documentSymbol
+ err := c.Call(ctx, "textDocument/documentSymbol", params, &result)
+ return result, err
+}
+
// CodeAction sends a textDocument/codeAction request to the LSP server.
// A request to provide commands for the given text document and range.
func (c *Client) CodeAction(ctx context.Context, params protocol.CodeActionParams) ([]protocol.Or_Result_textDocument_codeAction_Item0_Elem, error) {
@@ -152,25 +158,25 @@ func (c *Client) Symbol(ctx context.Context, params protocol.WorkspaceSymbolPara
var result protocol.Or_Result_workspace_symbol
err := c.Call(ctx, "workspace/symbol", params, &result)
return result, err
-}
-
-// ResolveWorkspaceSymbol sends a workspaceSymbol/resolve request to the LSP server.
-// A request to resolve the range inside the workspace symbol's location. Since 3.17.0
-func (c *Client) ResolveWorkspaceSymbol(ctx context.Context, params protocol.WorkspaceSymbol) (protocol.WorkspaceSymbol, error) {
- var result protocol.WorkspaceSymbol
- err := c.Call(ctx, "workspaceSymbol/resolve", params, &result)
- return result, err
```
This function is important because it defines how OpenCode AI Legacy Tutorial: Archived Terminal Agent Workflows and Migration to Crush implements the patterns covered in this chapter.
### `internal/lsp/methods.go`
-The `ResolveCodeAction` function in [`internal/lsp/methods.go`](https://github.com/opencode-ai/opencode/blob/HEAD/internal/lsp/methods.go) handles a key part of this chapter's functionality:
+The `CodeAction` function in [`internal/lsp/methods.go`](https://github.com/opencode-ai/opencode/blob/HEAD/internal/lsp/methods.go) handles a key part of this chapter's functionality:
```go
}
+// CodeAction sends a textDocument/codeAction request to the LSP server.
+// A request to provide commands for the given text document and range.
+func (c *Client) CodeAction(ctx context.Context, params protocol.CodeActionParams) ([]protocol.Or_Result_textDocument_codeAction_Item0_Elem, error) {
+ var result []protocol.Or_Result_textDocument_codeAction_Item0_Elem
+ err := c.Call(ctx, "textDocument/codeAction", params, &result)
+ return result, err
+}
+
// ResolveCodeAction sends a codeAction/resolve request to the LSP server.
// Request to resolve additional information for a given code action.The request's parameter is of type CodeAction the response is of type CodeAction or a Thenable that resolves to such.
func (c *Client) ResolveCodeAction(ctx context.Context, params protocol.CodeAction) (protocol.CodeAction, error) {
@@ -193,14 +199,6 @@ func (c *Client) ResolveWorkspaceSymbol(ctx context.Context, params protocol.Wor
var result protocol.WorkspaceSymbol
err := c.Call(ctx, "workspaceSymbol/resolve", params, &result)
return result, err
-}
-
-// CodeLens sends a textDocument/codeLens request to the LSP server.
-// A request to provide code lens for the given text document.
-func (c *Client) CodeLens(ctx context.Context, params protocol.CodeLensParams) ([]protocol.CodeLens, error) {
- var result []protocol.CodeLens
- err := c.Call(ctx, "textDocument/codeLens", params, &result)
- return result, err
```
This function is important because it defines how OpenCode AI Legacy Tutorial: Archived Terminal Agent Workflows and Migration to Crush implements the patterns covered in this chapter.
@@ -210,11 +208,11 @@ This function is important because it defines how OpenCode AI Legacy Tutorial: A
```mermaid
flowchart TD
- A[DocumentHighlight]
- B[DocumentSymbol]
- C[CodeAction]
- D[ResolveCodeAction]
- E[Symbol]
+ A[References]
+ B[DocumentHighlight]
+ C[DocumentSymbol]
+ D[CodeAction]
+ E[ResolveCodeAction]
A --> B
B --> C
C --> D
diff --git a/tutorials/opencode-ai-legacy-tutorial/03-installation-and-configuration-baseline.md b/tutorials/opencode-ai-legacy-tutorial/03-installation-and-configuration-baseline.md
index ff260efa..e68bb625 100644
--- a/tutorials/opencode-ai-legacy-tutorial/03-installation-and-configuration-baseline.md
+++ b/tutorials/opencode-ai-legacy-tutorial/03-installation-and-configuration-baseline.md
@@ -38,28 +38,43 @@ You now have a reproducible setup baseline for legacy OpenCode operation.
Next: [Chapter 4: Model Providers and Runtime Operations](04-model-providers-and-runtime-operations.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `main.go`
+### `internal/lsp/methods.go`
-The `main` function in [`main.go`](https://github.com/opencode-ai/opencode/blob/HEAD/main.go) handles a key part of this chapter's functionality:
+The `Progress` function in [`internal/lsp/methods.go`](https://github.com/opencode-ai/opencode/blob/HEAD/internal/lsp/methods.go) handles a key part of this chapter's functionality:
```go
-package main
+}
+
+// WorkDoneProgressCancel sends a window/workDoneProgress/cancel notification to the LSP server.
+// The window/workDoneProgress/cancel notification is sent from the client to the server to cancel a progress initiated on the server side.
+func (c *Client) WorkDoneProgressCancel(ctx context.Context, params protocol.WorkDoneProgressCancelParams) error {
+ return c.Notify(ctx, "window/workDoneProgress/cancel", params)
+}
-import (
- "github.com/opencode-ai/opencode/cmd"
- "github.com/opencode-ai/opencode/internal/logging"
-)
+// DidCreateFiles sends a workspace/didCreateFiles notification to the LSP server.
+// The did create files notification is sent from the client to the server when files were created from within the client. Since 3.16.0
+func (c *Client) DidCreateFiles(ctx context.Context, params protocol.CreateFilesParams) error {
+ return c.Notify(ctx, "workspace/didCreateFiles", params)
+}
+
+// DidRenameFiles sends a workspace/didRenameFiles notification to the LSP server.
+// The did rename files notification is sent from the client to the server when files were renamed from within the client. Since 3.16.0
+func (c *Client) DidRenameFiles(ctx context.Context, params protocol.RenameFilesParams) error {
+ return c.Notify(ctx, "workspace/didRenameFiles", params)
+}
-func main() {
- defer logging.RecoverPanic("main", func() {
- logging.ErrorPersist("Application terminated due to unhandled panic")
- })
+// DidDeleteFiles sends a workspace/didDeleteFiles notification to the LSP server.
+// The will delete files request is sent from the client to the server before files are actually deleted as long as the deletion is triggered from within the client. Since 3.16.0
+func (c *Client) DidDeleteFiles(ctx context.Context, params protocol.DeleteFilesParams) error {
+ return c.Notify(ctx, "workspace/didDeleteFiles", params)
+}
- cmd.Execute()
+// DidOpenNotebookDocument sends a notebookDocument/didOpen notification to the LSP server.
+// A notification sent when a notebook opens. Since 3.17.0
+func (c *Client) DidOpenNotebookDocument(ctx context.Context, params protocol.DidOpenNotebookDocumentParams) error {
+ return c.Notify(ctx, "notebookDocument/didOpen", params)
}
```
@@ -194,7 +209,7 @@ This function is important because it defines how OpenCode AI Legacy Tutorial: A
```mermaid
flowchart TD
- A[main]
+ A[Progress]
B[attemptTUIRecovery]
C[initMCPTools]
D[setupSubscriptions]
diff --git a/tutorials/opencode-ai-legacy-tutorial/04-model-providers-and-runtime-operations.md b/tutorials/opencode-ai-legacy-tutorial/04-model-providers-and-runtime-operations.md
index a3d55efe..53e5992c 100644
--- a/tutorials/opencode-ai-legacy-tutorial/04-model-providers-and-runtime-operations.md
+++ b/tutorials/opencode-ai-legacy-tutorial/04-model-providers-and-runtime-operations.md
@@ -37,170 +37,168 @@ You now have a stable runtime configuration model for legacy operations.
Next: [Chapter 5: Interactive and Non-Interactive Workflows](05-interactive-and-non-interactive-workflows.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `internal/diff/diff.go`
+### `internal/lsp/client.go`
-The `WithTotalWidth` function in [`internal/diff/diff.go`](https://github.com/opencode-ai/opencode/blob/HEAD/internal/diff/diff.go) handles a key part of this chapter's functionality:
+The `openKeyConfigFiles` function in [`internal/lsp/client.go`](https://github.com/opencode-ai/opencode/blob/HEAD/internal/lsp/client.go) handles a key part of this chapter's functionality:
```go
-}
-
-// WithTotalWidth sets the total width for side-by-side view
-func WithTotalWidth(width int) SideBySideOption {
- return func(s *SideBySideConfig) {
- if width > 0 {
- s.TotalWidth = width
+ logging.Debug("TypeScript-like server detected, opening key configuration files")
}
+ c.openKeyConfigFiles(ctx)
}
-}
-// -------------------------------------------------------------------------
-// Diff Parsing
-// -------------------------------------------------------------------------
-
-// ParseUnifiedDiff parses a unified diff format string into structured data
-func ParseUnifiedDiff(diff string) (DiffResult, error) {
- var result DiffResult
- var currentHunk *Hunk
-
- hunkHeaderRe := regexp.MustCompile(`^@@ -(\d+),?(\d*) \+(\d+),?(\d*) @@`)
- lines := strings.Split(diff, "\n")
+ for {
+ select {
+ case <-ctx.Done():
+ c.SetServerState(StateError)
+ return fmt.Errorf("timeout waiting for LSP server to be ready")
+ case <-ticker.C:
+ // Try a ping method appropriate for this server type
+ err := c.pingServerByType(ctx, serverType)
+ if err == nil {
+ // Server responded successfully
+ c.SetServerState(StateReady)
+ if cnf.DebugLSP {
+ logging.Debug("LSP server is ready")
+ }
+ return nil
+ } else {
+ logging.Debug("LSP server not ready yet", "error", err, "serverType", serverType)
+ }
- var oldLine, newLine int
- inFileHeader := true
+ if cnf.DebugLSP {
+ logging.Debug("LSP server not ready yet", "error", err, "serverType", serverType)
+ }
+ }
+ }
+}
- for _, line := range lines {
- // Parse file headers
- if inFileHeader {
- if strings.HasPrefix(line, "--- a/") {
- result.OldFile = strings.TrimPrefix(line, "--- a/")
- continue
+// ServerType represents the type of LSP server
```
This function is important because it defines how OpenCode AI Legacy Tutorial: Archived Terminal Agent Workflows and Migration to Crush implements the patterns covered in this chapter.
-### `internal/diff/diff.go`
+### `internal/lsp/client.go`
-The `ParseUnifiedDiff` function in [`internal/diff/diff.go`](https://github.com/opencode-ai/opencode/blob/HEAD/internal/diff/diff.go) handles a key part of this chapter's functionality:
+The `pingServerByType` function in [`internal/lsp/client.go`](https://github.com/opencode-ai/opencode/blob/HEAD/internal/lsp/client.go) handles a key part of this chapter's functionality:
```go
-// -------------------------------------------------------------------------
-
-// ParseUnifiedDiff parses a unified diff format string into structured data
-func ParseUnifiedDiff(diff string) (DiffResult, error) {
- var result DiffResult
- var currentHunk *Hunk
-
- hunkHeaderRe := regexp.MustCompile(`^@@ -(\d+),?(\d*) \+(\d+),?(\d*) @@`)
- lines := strings.Split(diff, "\n")
-
- var oldLine, newLine int
- inFileHeader := true
-
- for _, line := range lines {
- // Parse file headers
- if inFileHeader {
- if strings.HasPrefix(line, "--- a/") {
- result.OldFile = strings.TrimPrefix(line, "--- a/")
- continue
+ case <-ticker.C:
+ // Try a ping method appropriate for this server type
+ err := c.pingServerByType(ctx, serverType)
+ if err == nil {
+ // Server responded successfully
+ c.SetServerState(StateReady)
+ if cnf.DebugLSP {
+ logging.Debug("LSP server is ready")
+ }
+ return nil
+ } else {
+ logging.Debug("LSP server not ready yet", "error", err, "serverType", serverType)
}
- if strings.HasPrefix(line, "+++ b/") {
- result.NewFile = strings.TrimPrefix(line, "+++ b/")
- inFileHeader = false
- continue
+
+ if cnf.DebugLSP {
+ logging.Debug("LSP server not ready yet", "error", err, "serverType", serverType)
}
}
+ }
+}
- // Parse hunk headers
- if matches := hunkHeaderRe.FindStringSubmatch(line); matches != nil {
- if currentHunk != nil {
- result.Hunks = append(result.Hunks, *currentHunk)
- }
+// ServerType represents the type of LSP server
+type ServerType int
+
+const (
+ ServerTypeUnknown ServerType = iota
+ ServerTypeGo
+ ServerTypeTypeScript
+ ServerTypeRust
+ ServerTypePython
+ ServerTypeGeneric
+)
```
This function is important because it defines how OpenCode AI Legacy Tutorial: Archived Terminal Agent Workflows and Migration to Crush implements the patterns covered in this chapter.
-### `internal/diff/diff.go`
+### `internal/lsp/client.go`
-The `HighlightIntralineChanges` function in [`internal/diff/diff.go`](https://github.com/opencode-ai/opencode/blob/HEAD/internal/diff/diff.go) handles a key part of this chapter's functionality:
+The `pingTypeScriptServer` function in [`internal/lsp/client.go`](https://github.com/opencode-ai/opencode/blob/HEAD/internal/lsp/client.go) handles a key part of this chapter's functionality:
```go
+ case ServerTypeTypeScript:
+ // For TypeScript, try a document symbol request on an open file
+ return c.pingTypeScriptServer(ctx)
+ case ServerTypeGo:
+ // For Go, workspace/symbol works well
+ return c.pingWithWorkspaceSymbol(ctx)
+ case ServerTypeRust:
+ // For Rust, workspace/symbol works well
+ return c.pingWithWorkspaceSymbol(ctx)
+ default:
+ // Default ping method
+ return c.pingWithWorkspaceSymbol(ctx)
+ }
}
-// HighlightIntralineChanges updates lines in a hunk to show character-level differences
-func HighlightIntralineChanges(h *Hunk) {
- var updated []DiffLine
- dmp := diffmatchpatch.New()
-
- for i := 0; i < len(h.Lines); i++ {
- // Look for removed line followed by added line
- if i+1 < len(h.Lines) &&
- h.Lines[i].Kind == LineRemoved &&
- h.Lines[i+1].Kind == LineAdded {
-
- oldLine := h.Lines[i]
- newLine := h.Lines[i+1]
-
- // Find character-level differences
- patches := dmp.DiffMain(oldLine.Content, newLine.Content, false)
- patches = dmp.DiffCleanupSemantic(patches)
- patches = dmp.DiffCleanupMerge(patches)
- patches = dmp.DiffCleanupEfficiency(patches)
-
- segments := make([]Segment, 0)
-
- removeStart := 0
- addStart := 0
- for _, patch := range patches {
- switch patch.Type {
- case diffmatchpatch.DiffDelete:
- segments = append(segments, Segment{
- Start: removeStart,
- End: removeStart + len(patch.Text),
+// pingTypeScriptServer tries to ping a TypeScript server with appropriate methods
+func (c *Client) pingTypeScriptServer(ctx context.Context) error {
+ // First try workspace/symbol which works for many servers
+ if err := c.pingWithWorkspaceSymbol(ctx); err == nil {
+ return nil
+ }
+
+ // If that fails, try to find an open file and request document symbols
+ c.openFilesMu.RLock()
+ defer c.openFilesMu.RUnlock()
+
+ // If we have any open files, try to get document symbols for one
+ for uri := range c.openFiles {
+ filePath := strings.TrimPrefix(uri, "file://")
+ if strings.HasSuffix(filePath, ".ts") || strings.HasSuffix(filePath, ".js") ||
+ strings.HasSuffix(filePath, ".tsx") || strings.HasSuffix(filePath, ".jsx") {
+ var symbols []protocol.DocumentSymbol
```
This function is important because it defines how OpenCode AI Legacy Tutorial: Archived Terminal Agent Workflows and Migration to Crush implements the patterns covered in this chapter.
-### `internal/diff/diff.go`
+### `internal/lsp/client.go`
-The `pairLines` function in [`internal/diff/diff.go`](https://github.com/opencode-ai/opencode/blob/HEAD/internal/diff/diff.go) handles a key part of this chapter's functionality:
+The `openTypeScriptFiles` function in [`internal/lsp/client.go`](https://github.com/opencode-ai/opencode/blob/HEAD/internal/lsp/client.go) handles a key part of this chapter's functionality:
```go
-}
-// pairLines converts a flat list of diff lines to pairs for side-by-side display
-func pairLines(lines []DiffLine) []linePair {
- var pairs []linePair
- i := 0
-
- for i < len(lines) {
- switch lines[i].Kind {
- case LineRemoved:
- // Check if the next line is an addition, if so pair them
- if i+1 < len(lines) && lines[i+1].Kind == LineAdded {
- pairs = append(pairs, linePair{left: &lines[i], right: &lines[i+1]})
- i += 2
+ // Also find and open a few TypeScript files to help the server initialize
+ c.openTypeScriptFiles(ctx, workDir)
+ case ServerTypeGo:
+ filesToOpen = []string{
+ filepath.Join(workDir, "go.mod"),
+ filepath.Join(workDir, "go.sum"),
+ }
+ case ServerTypeRust:
+ filesToOpen = []string{
+ filepath.Join(workDir, "Cargo.toml"),
+ filepath.Join(workDir, "Cargo.lock"),
+ }
+ }
+
+ // Try to open each file, ignoring errors if they don't exist
+ for _, file := range filesToOpen {
+ if _, err := os.Stat(file); err == nil {
+ // File exists, try to open it
+ if err := c.OpenFile(ctx, file); err != nil {
+ logging.Debug("Failed to open key config file", "file", file, "error", err)
} else {
- pairs = append(pairs, linePair{left: &lines[i], right: nil})
- i++
+ logging.Debug("Opened key config file for initialization", "file", file)
}
- case LineAdded:
- pairs = append(pairs, linePair{left: nil, right: &lines[i]})
- i++
- case LineContext:
- pairs = append(pairs, linePair{left: &lines[i], right: &lines[i]})
- i++
}
}
-
- return pairs
}
-// -------------------------------------------------------------------------
-// Syntax Highlighting
+// pingServerByType sends a ping request appropriate for the server type
+func (c *Client) pingServerByType(ctx context.Context, serverType ServerType) error {
+ switch serverType {
+ case ServerTypeTypeScript:
```
This function is important because it defines how OpenCode AI Legacy Tutorial: Archived Terminal Agent Workflows and Migration to Crush implements the patterns covered in this chapter.
@@ -210,11 +208,11 @@ This function is important because it defines how OpenCode AI Legacy Tutorial: A
```mermaid
flowchart TD
- A[WithTotalWidth]
- B[ParseUnifiedDiff]
- C[HighlightIntralineChanges]
- D[pairLines]
- E[SyntaxHighlight]
+ A[openKeyConfigFiles]
+ B[pingServerByType]
+ C[pingTypeScriptServer]
+ D[openTypeScriptFiles]
+ E[shouldSkipDir]
A --> B
B --> C
C --> D
diff --git a/tutorials/opencode-ai-legacy-tutorial/05-interactive-and-non-interactive-workflows.md b/tutorials/opencode-ai-legacy-tutorial/05-interactive-and-non-interactive-workflows.md
index 72870b5b..7adec266 100644
--- a/tutorials/opencode-ai-legacy-tutorial/05-interactive-and-non-interactive-workflows.md
+++ b/tutorials/opencode-ai-legacy-tutorial/05-interactive-and-non-interactive-workflows.md
@@ -37,147 +37,168 @@ You now can operate legacy OpenCode in both manual and scripted workflows.
Next: [Chapter 6: Session, Tooling, and Integration Practices](06-session-tooling-and-integration-practices.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `internal/lsp/client.go`
+### `internal/tui/tui.go`
-The `GetDiagnostics` function in [`internal/lsp/client.go`](https://github.com/opencode-ai/opencode/blob/HEAD/internal/lsp/client.go) handles a key part of this chapter's functionality:
+The `findCommand` function in [`internal/tui/tui.go`](https://github.com/opencode-ai/opencode/blob/HEAD/internal/tui/tui.go) handles a key part of this chapter's functionality:
```go
}
-// GetDiagnostics returns all diagnostics for all files
-func (c *Client) GetDiagnostics() map[protocol.DocumentUri][]protocol.Diagnostic {
- return c.diagnostics
-}
-
-// OpenFileOnDemand opens a file only if it's not already open
-// This is used for lazy-loading files when they're actually needed
-func (c *Client) OpenFileOnDemand(ctx context.Context, filepath string) error {
- // Check if the file is already open
- if c.IsFileOpen(filepath) {
- return nil
+func (a *appModel) findCommand(id string) (dialog.Command, bool) {
+ for _, cmd := range a.commands {
+ if cmd.ID == id {
+ return cmd, true
+ }
}
-
- // Open the file
- return c.OpenFile(ctx, filepath)
+ return dialog.Command{}, false
}
-// GetDiagnosticsForFile ensures a file is open and returns its diagnostics
-// This is useful for on-demand diagnostics when using lazy loading
-func (c *Client) GetDiagnosticsForFile(ctx context.Context, filepath string) ([]protocol.Diagnostic, error) {
- uri := fmt.Sprintf("file://%s", filepath)
- documentUri := protocol.DocumentUri(uri)
+func (a *appModel) moveToPage(pageID page.PageID) tea.Cmd {
+ if a.app.CoderAgent.IsBusy() {
+ // For now we don't move to any page if the agent is busy
+ return util.ReportWarn("Agent is busy, please wait...")
+ }
- // Make sure the file is open
- if !c.IsFileOpen(filepath) {
- if err := c.OpenFile(ctx, filepath); err != nil {
- return nil, fmt.Errorf("failed to open file for diagnostics: %w", err)
- }
+ var cmds []tea.Cmd
+ if _, ok := a.loadedPages[pageID]; !ok {
+ cmd := a.pages[pageID].Init()
+ cmds = append(cmds, cmd)
+ a.loadedPages[pageID] = true
+ }
+ a.previousPage = a.currentPage
+ a.currentPage = pageID
+ if sizable, ok := a.pages[a.currentPage].(layout.Sizeable); ok {
+ cmd := sizable.SetSize(a.width, a.height)
+ cmds = append(cmds, cmd)
+ }
- // Give the LSP server a moment to process the file
+ return tea.Batch(cmds...)
+}
```
This function is important because it defines how OpenCode AI Legacy Tutorial: Archived Terminal Agent Workflows and Migration to Crush implements the patterns covered in this chapter.
-### `internal/lsp/client.go`
+### `internal/tui/tui.go`
-The `OpenFileOnDemand` function in [`internal/lsp/client.go`](https://github.com/opencode-ai/opencode/blob/HEAD/internal/lsp/client.go) handles a key part of this chapter's functionality:
+The `moveToPage` function in [`internal/tui/tui.go`](https://github.com/opencode-ai/opencode/blob/HEAD/internal/tui/tui.go) handles a key part of this chapter's functionality:
```go
-}
-// OpenFileOnDemand opens a file only if it's not already open
-// This is used for lazy-loading files when they're actually needed
-func (c *Client) OpenFileOnDemand(ctx context.Context, filepath string) error {
- // Check if the file is already open
- if c.IsFileOpen(filepath) {
- return nil
- }
+ case page.PageChangeMsg:
+ return a, a.moveToPage(msg.ID)
- // Open the file
- return c.OpenFile(ctx, filepath)
-}
+ case dialog.CloseQuitMsg:
+ a.showQuit = false
+ return a, nil
-// GetDiagnosticsForFile ensures a file is open and returns its diagnostics
-// This is useful for on-demand diagnostics when using lazy loading
-func (c *Client) GetDiagnosticsForFile(ctx context.Context, filepath string) ([]protocol.Diagnostic, error) {
- uri := fmt.Sprintf("file://%s", filepath)
- documentUri := protocol.DocumentUri(uri)
+ case dialog.CloseSessionDialogMsg:
+ a.showSessionDialog = false
+ return a, nil
- // Make sure the file is open
- if !c.IsFileOpen(filepath) {
- if err := c.OpenFile(ctx, filepath); err != nil {
- return nil, fmt.Errorf("failed to open file for diagnostics: %w", err)
- }
+ case dialog.CloseCommandDialogMsg:
+ a.showCommandDialog = false
+ return a, nil
- // Give the LSP server a moment to process the file
- time.Sleep(100 * time.Millisecond)
- }
+ case startCompactSessionMsg:
+ // Start compacting the current session
+ a.isCompacting = true
+ a.compactingMessage = "Starting summarization..."
+
+ if a.selectedSession.ID == "" {
+ a.isCompacting = false
+ return a, util.ReportWarn("No active session to summarize")
+ }
- // Get diagnostics
- c.diagnosticsMu.RLock()
+ // Start the summarization process
+ return a, func() tea.Msg {
+ ctx := context.Background()
+ a.app.CoderAgent.Summarize(ctx, a.selectedSession.ID)
+ return nil
+ }
```
This function is important because it defines how OpenCode AI Legacy Tutorial: Archived Terminal Agent Workflows and Migration to Crush implements the patterns covered in this chapter.
-### `internal/lsp/client.go`
+### `internal/tui/tui.go`
-The `GetDiagnosticsForFile` function in [`internal/lsp/client.go`](https://github.com/opencode-ai/opencode/blob/HEAD/internal/lsp/client.go) handles a key part of this chapter's functionality:
+The `View` function in [`internal/tui/tui.go`](https://github.com/opencode-ai/opencode/blob/HEAD/internal/tui/tui.go) handles a key part of this chapter's functionality:
```go
}
-// GetDiagnosticsForFile ensures a file is open and returns its diagnostics
-// This is useful for on-demand diagnostics when using lazy loading
-func (c *Client) GetDiagnosticsForFile(ctx context.Context, filepath string) ([]protocol.Diagnostic, error) {
- uri := fmt.Sprintf("file://%s", filepath)
- documentUri := protocol.DocumentUri(uri)
-
- // Make sure the file is open
- if !c.IsFileOpen(filepath) {
- if err := c.OpenFile(ctx, filepath); err != nil {
- return nil, fmt.Errorf("failed to open file for diagnostics: %w", err)
- }
-
- // Give the LSP server a moment to process the file
- time.Sleep(100 * time.Millisecond)
+func (a appModel) View() string {
+ components := []string{
+ a.pages[a.currentPage].View(),
}
- // Get diagnostics
- c.diagnosticsMu.RLock()
- diagnostics := c.diagnostics[documentUri]
- c.diagnosticsMu.RUnlock()
-
- return diagnostics, nil
-}
+ components = append(components, a.status.View())
+
+ appView := lipgloss.JoinVertical(lipgloss.Top, components...)
+
+ if a.showPermissions {
+ overlay := a.permissions.View()
+ row := lipgloss.Height(appView) / 2
+ row -= lipgloss.Height(overlay) / 2
+ col := lipgloss.Width(appView) / 2
+ col -= lipgloss.Width(overlay) / 2
+ appView = layout.PlaceOverlay(
+ col,
+ row,
+ overlay,
+ appView,
+ true,
+ )
+ }
-// ClearDiagnosticsForURI removes diagnostics for a specific URI from the cache
-func (c *Client) ClearDiagnosticsForURI(uri protocol.DocumentUri) {
- c.diagnosticsMu.Lock()
- defer c.diagnosticsMu.Unlock()
- delete(c.diagnostics, uri)
-}
+ if a.showFilepicker {
+ overlay := a.filepicker.View()
+ row := lipgloss.Height(appView) / 2
+ row -= lipgloss.Height(overlay) / 2
+ col := lipgloss.Width(appView) / 2
+ col -= lipgloss.Width(overlay) / 2
```
This function is important because it defines how OpenCode AI Legacy Tutorial: Archived Terminal Agent Workflows and Migration to Crush implements the patterns covered in this chapter.
-### `internal/lsp/client.go`
+### `internal/tui/tui.go`
-The `ClearDiagnosticsForURI` function in [`internal/lsp/client.go`](https://github.com/opencode-ai/opencode/blob/HEAD/internal/lsp/client.go) handles a key part of this chapter's functionality:
+The `New` function in [`internal/tui/tui.go`](https://github.com/opencode-ai/opencode/blob/HEAD/internal/tui/tui.go) handles a key part of this chapter's functionality:
```go
-}
-
-// ClearDiagnosticsForURI removes diagnostics for a specific URI from the cache
-func (c *Client) ClearDiagnosticsForURI(uri protocol.DocumentUri) {
- c.diagnosticsMu.Lock()
- defer c.diagnosticsMu.Unlock()
- delete(c.diagnostics, uri)
-}
+var keys = keyMap{
+ Logs: key.NewBinding(
+ key.WithKeys("ctrl+l"),
+ key.WithHelp("ctrl+l", "logs"),
+ ),
+
+ Quit: key.NewBinding(
+ key.WithKeys("ctrl+c"),
+ key.WithHelp("ctrl+c", "quit"),
+ ),
+ Help: key.NewBinding(
+ key.WithKeys("ctrl+_", "ctrl+h"),
+ key.WithHelp("ctrl+?", "toggle help"),
+ ),
+
+ SwitchSession: key.NewBinding(
+ key.WithKeys("ctrl+s"),
+ key.WithHelp("ctrl+s", "switch session"),
+ ),
+
+ Commands: key.NewBinding(
+ key.WithKeys("ctrl+k"),
+ key.WithHelp("ctrl+k", "commands"),
+ ),
+ Filepicker: key.NewBinding(
+ key.WithKeys("ctrl+f"),
+ key.WithHelp("ctrl+f", "select files to upload"),
+ ),
+ Models: key.NewBinding(
+ key.WithKeys("ctrl+o"),
+ key.WithHelp("ctrl+o", "model selection"),
```
This function is important because it defines how OpenCode AI Legacy Tutorial: Archived Terminal Agent Workflows and Migration to Crush implements the patterns covered in this chapter.
@@ -187,11 +208,11 @@ This function is important because it defines how OpenCode AI Legacy Tutorial: A
```mermaid
flowchart TD
- A[GetDiagnostics]
- B[OpenFileOnDemand]
- C[GetDiagnosticsForFile]
- D[ClearDiagnosticsForURI]
- E[main]
+ A[findCommand]
+ B[moveToPage]
+ C[View]
+ D[New]
+ E[Error]
A --> B
B --> C
C --> D
diff --git a/tutorials/opencode-ai-legacy-tutorial/06-session-tooling-and-integration-practices.md b/tutorials/opencode-ai-legacy-tutorial/06-session-tooling-and-integration-practices.md
index d1221c03..9799cc95 100644
--- a/tutorials/opencode-ai-legacy-tutorial/06-session-tooling-and-integration-practices.md
+++ b/tutorials/opencode-ai-legacy-tutorial/06-session-tooling-and-integration-practices.md
@@ -37,170 +37,168 @@ You now have stable session and integration practices for controlled legacy oper
Next: [Chapter 7: Migration to Crush and Modern Alternatives](07-migration-to-crush-and-modern-alternatives.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `internal/db/db.go`
+### `internal/message/content.go`
-The `Close` function in [`internal/db/db.go`](https://github.com/opencode-ai/opencode/blob/HEAD/internal/db/db.go) handles a key part of this chapter's functionality:
+The `ReasoningContent` function in [`internal/message/content.go`](https://github.com/opencode-ai/opencode/blob/HEAD/internal/message/content.go) handles a key part of this chapter's functionality:
```go
}
-func (q *Queries) Close() error {
- var err error
- if q.createFileStmt != nil {
- if cerr := q.createFileStmt.Close(); cerr != nil {
- err = fmt.Errorf("error closing createFileStmt: %w", cerr)
- }
- }
- if q.createMessageStmt != nil {
- if cerr := q.createMessageStmt.Close(); cerr != nil {
- err = fmt.Errorf("error closing createMessageStmt: %w", cerr)
- }
- }
- if q.createSessionStmt != nil {
- if cerr := q.createSessionStmt.Close(); cerr != nil {
- err = fmt.Errorf("error closing createSessionStmt: %w", cerr)
- }
- }
- if q.deleteFileStmt != nil {
- if cerr := q.deleteFileStmt.Close(); cerr != nil {
- err = fmt.Errorf("error closing deleteFileStmt: %w", cerr)
- }
- }
- if q.deleteMessageStmt != nil {
- if cerr := q.deleteMessageStmt.Close(); cerr != nil {
- err = fmt.Errorf("error closing deleteMessageStmt: %w", cerr)
- }
- }
- if q.deleteSessionStmt != nil {
- if cerr := q.deleteSessionStmt.Close(); cerr != nil {
- err = fmt.Errorf("error closing deleteSessionStmt: %w", cerr)
+type ReasoningContent struct {
+ Thinking string `json:"thinking"`
+}
+
+func (tc ReasoningContent) String() string {
+ return tc.Thinking
+}
+func (ReasoningContent) isPart() {}
+
+type TextContent struct {
+ Text string `json:"text"`
+}
+
+func (tc TextContent) String() string {
+ return tc.Text
+}
+
+func (TextContent) isPart() {}
+
+type ImageURLContent struct {
+ URL string `json:"url"`
+ Detail string `json:"detail,omitempty"`
+}
+
+func (iuc ImageURLContent) String() string {
+ return iuc.URL
+}
+
+func (ImageURLContent) isPart() {}
+
```
This function is important because it defines how OpenCode AI Legacy Tutorial: Archived Terminal Agent Workflows and Migration to Crush implements the patterns covered in this chapter.
-### `internal/db/db.go`
+### `internal/message/content.go`
-The `exec` function in [`internal/db/db.go`](https://github.com/opencode-ai/opencode/blob/HEAD/internal/db/db.go) handles a key part of this chapter's functionality:
+The `ImageURLContent` function in [`internal/message/content.go`](https://github.com/opencode-ai/opencode/blob/HEAD/internal/message/content.go) handles a key part of this chapter's functionality:
```go
+func (TextContent) isPart() {}
+
+type ImageURLContent struct {
+ URL string `json:"url"`
+ Detail string `json:"detail,omitempty"`
}
-func (q *Queries) exec(ctx context.Context, stmt *sql.Stmt, query string, args ...interface{}) (sql.Result, error) {
- switch {
- case stmt != nil && q.tx != nil:
- return q.tx.StmtContext(ctx, stmt).ExecContext(ctx, args...)
- case stmt != nil:
- return stmt.ExecContext(ctx, args...)
- default:
- return q.db.ExecContext(ctx, query, args...)
- }
+func (iuc ImageURLContent) String() string {
+ return iuc.URL
+}
+
+func (ImageURLContent) isPart() {}
+
+type BinaryContent struct {
+ Path string
+ MIMEType string
+ Data []byte
}
-func (q *Queries) query(ctx context.Context, stmt *sql.Stmt, query string, args ...interface{}) (*sql.Rows, error) {
- switch {
- case stmt != nil && q.tx != nil:
- return q.tx.StmtContext(ctx, stmt).QueryContext(ctx, args...)
- case stmt != nil:
- return stmt.QueryContext(ctx, args...)
- default:
- return q.db.QueryContext(ctx, query, args...)
+func (bc BinaryContent) String(provider models.ModelProvider) string {
+ base64Encoded := base64.StdEncoding.EncodeToString(bc.Data)
+ if provider == models.ProviderOpenAI {
+ return "data:" + bc.MIMEType + ";base64," + base64Encoded
}
+ return base64Encoded
}
-func (q *Queries) queryRow(ctx context.Context, stmt *sql.Stmt, query string, args ...interface{}) *sql.Row {
- switch {
- case stmt != nil && q.tx != nil:
- return q.tx.StmtContext(ctx, stmt).QueryRowContext(ctx, args...)
- case stmt != nil:
- return stmt.QueryRowContext(ctx, args...)
- default:
- return q.db.QueryRowContext(ctx, query, args...)
+func (BinaryContent) isPart() {}
+
+type ToolCall struct {
+ ID string `json:"id"`
+ Name string `json:"name"`
```
This function is important because it defines how OpenCode AI Legacy Tutorial: Archived Terminal Agent Workflows and Migration to Crush implements the patterns covered in this chapter.
-### `internal/db/db.go`
+### `internal/message/content.go`
-The `query` function in [`internal/db/db.go`](https://github.com/opencode-ai/opencode/blob/HEAD/internal/db/db.go) handles a key part of this chapter's functionality:
+The `BinaryContent` function in [`internal/message/content.go`](https://github.com/opencode-ai/opencode/blob/HEAD/internal/message/content.go) handles a key part of this chapter's functionality:
```go
- var err error
- if q.createFileStmt, err = db.PrepareContext(ctx, createFile); err != nil {
- return nil, fmt.Errorf("error preparing query CreateFile: %w", err)
- }
- if q.createMessageStmt, err = db.PrepareContext(ctx, createMessage); err != nil {
- return nil, fmt.Errorf("error preparing query CreateMessage: %w", err)
- }
- if q.createSessionStmt, err = db.PrepareContext(ctx, createSession); err != nil {
- return nil, fmt.Errorf("error preparing query CreateSession: %w", err)
- }
- if q.deleteFileStmt, err = db.PrepareContext(ctx, deleteFile); err != nil {
- return nil, fmt.Errorf("error preparing query DeleteFile: %w", err)
- }
- if q.deleteMessageStmt, err = db.PrepareContext(ctx, deleteMessage); err != nil {
- return nil, fmt.Errorf("error preparing query DeleteMessage: %w", err)
- }
- if q.deleteSessionStmt, err = db.PrepareContext(ctx, deleteSession); err != nil {
- return nil, fmt.Errorf("error preparing query DeleteSession: %w", err)
- }
- if q.deleteSessionFilesStmt, err = db.PrepareContext(ctx, deleteSessionFiles); err != nil {
- return nil, fmt.Errorf("error preparing query DeleteSessionFiles: %w", err)
- }
- if q.deleteSessionMessagesStmt, err = db.PrepareContext(ctx, deleteSessionMessages); err != nil {
- return nil, fmt.Errorf("error preparing query DeleteSessionMessages: %w", err)
- }
- if q.getFileStmt, err = db.PrepareContext(ctx, getFile); err != nil {
- return nil, fmt.Errorf("error preparing query GetFile: %w", err)
- }
- if q.getFileByPathAndSessionStmt, err = db.PrepareContext(ctx, getFileByPathAndSession); err != nil {
- return nil, fmt.Errorf("error preparing query GetFileByPathAndSession: %w", err)
+func (ImageURLContent) isPart() {}
+
+type BinaryContent struct {
+ Path string
+ MIMEType string
+ Data []byte
+}
+
+func (bc BinaryContent) String(provider models.ModelProvider) string {
+ base64Encoded := base64.StdEncoding.EncodeToString(bc.Data)
+ if provider == models.ProviderOpenAI {
+ return "data:" + bc.MIMEType + ";base64," + base64Encoded
}
- if q.getMessageStmt, err = db.PrepareContext(ctx, getMessage); err != nil {
+ return base64Encoded
+}
+
+func (BinaryContent) isPart() {}
+
+type ToolCall struct {
+ ID string `json:"id"`
+ Name string `json:"name"`
+ Input string `json:"input"`
+ Type string `json:"type"`
+ Finished bool `json:"finished"`
+}
+
+func (ToolCall) isPart() {}
+
+type ToolResult struct {
+ ToolCallID string `json:"tool_call_id"`
+ Name string `json:"name"`
+ Content string `json:"content"`
```
This function is important because it defines how OpenCode AI Legacy Tutorial: Archived Terminal Agent Workflows and Migration to Crush implements the patterns covered in this chapter.
-### `internal/db/db.go`
+### `internal/message/content.go`
-The `queryRow` function in [`internal/db/db.go`](https://github.com/opencode-ai/opencode/blob/HEAD/internal/db/db.go) handles a key part of this chapter's functionality:
+The `ToolCalls` function in [`internal/message/content.go`](https://github.com/opencode-ai/opencode/blob/HEAD/internal/message/content.go) handles a key part of this chapter's functionality:
```go
}
-func (q *Queries) queryRow(ctx context.Context, stmt *sql.Stmt, query string, args ...interface{}) *sql.Row {
- switch {
- case stmt != nil && q.tx != nil:
- return q.tx.StmtContext(ctx, stmt).QueryRowContext(ctx, args...)
- case stmt != nil:
- return stmt.QueryRowContext(ctx, args...)
- default:
- return q.db.QueryRowContext(ctx, query, args...)
+func (m *Message) ToolCalls() []ToolCall {
+ toolCalls := make([]ToolCall, 0)
+ for _, part := range m.Parts {
+ if c, ok := part.(ToolCall); ok {
+ toolCalls = append(toolCalls, c)
+ }
+ }
+ return toolCalls
+}
+
+func (m *Message) ToolResults() []ToolResult {
+ toolResults := make([]ToolResult, 0)
+ for _, part := range m.Parts {
+ if c, ok := part.(ToolResult); ok {
+ toolResults = append(toolResults, c)
+ }
+ }
+ return toolResults
+}
+
+func (m *Message) IsFinished() bool {
+ for _, part := range m.Parts {
+ if _, ok := part.(Finish); ok {
+ return true
+ }
}
+ return false
}
-type Queries struct {
- db DBTX
- tx *sql.Tx
- createFileStmt *sql.Stmt
- createMessageStmt *sql.Stmt
- createSessionStmt *sql.Stmt
- deleteFileStmt *sql.Stmt
- deleteMessageStmt *sql.Stmt
- deleteSessionStmt *sql.Stmt
- deleteSessionFilesStmt *sql.Stmt
- deleteSessionMessagesStmt *sql.Stmt
- getFileStmt *sql.Stmt
- getFileByPathAndSessionStmt *sql.Stmt
- getMessageStmt *sql.Stmt
- getSessionByIDStmt *sql.Stmt
- listFilesByPathStmt *sql.Stmt
- listFilesBySessionStmt *sql.Stmt
- listLatestSessionFilesStmt *sql.Stmt
- listMessagesBySessionStmt *sql.Stmt
+func (m *Message) FinishPart() *Finish {
```
This function is important because it defines how OpenCode AI Legacy Tutorial: Archived Terminal Agent Workflows and Migration to Crush implements the patterns covered in this chapter.
@@ -210,11 +208,11 @@ This function is important because it defines how OpenCode AI Legacy Tutorial: A
```mermaid
flowchart TD
- A[Close]
- B[exec]
- C[query]
- D[queryRow]
- E[WithTx]
+ A[ReasoningContent]
+ B[ImageURLContent]
+ C[BinaryContent]
+ D[ToolCalls]
+ E[ToolResults]
A --> B
B --> C
C --> D
diff --git a/tutorials/opencode-ai-legacy-tutorial/07-migration-to-crush-and-modern-alternatives.md b/tutorials/opencode-ai-legacy-tutorial/07-migration-to-crush-and-modern-alternatives.md
index 30b75a24..38842921 100644
--- a/tutorials/opencode-ai-legacy-tutorial/07-migration-to-crush-and-modern-alternatives.md
+++ b/tutorials/opencode-ai-legacy-tutorial/07-migration-to-crush-and-modern-alternatives.md
@@ -39,110 +39,167 @@ You now have a practical migration path away from archived OpenCode AI infrastru
Next: [Chapter 8: Legacy Governance and Controlled Sunset](08-legacy-governance-and-controlled-sunset.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `internal/message/content.go`
+### `internal/history/file.go`
-The `AddFinish` function in [`internal/message/content.go`](https://github.com/opencode-ai/opencode/blob/HEAD/internal/message/content.go) handles a key part of this chapter's functionality:
+The `Get` function in [`internal/history/file.go`](https://github.com/opencode-ai/opencode/blob/HEAD/internal/history/file.go) handles a key part of this chapter's functionality:
```go
+ Create(ctx context.Context, sessionID, path, content string) (File, error)
+ CreateVersion(ctx context.Context, sessionID, path, content string) (File, error)
+ Get(ctx context.Context, id string) (File, error)
+ GetByPathAndSession(ctx context.Context, path, sessionID string) (File, error)
+ ListBySession(ctx context.Context, sessionID string) ([]File, error)
+ ListLatestSessionFiles(ctx context.Context, sessionID string) ([]File, error)
+ Update(ctx context.Context, file File) (File, error)
+ Delete(ctx context.Context, id string) error
+ DeleteSessionFiles(ctx context.Context, sessionID string) error
}
-func (m *Message) AddFinish(reason FinishReason) {
- // remove any existing finish part
- for i, part := range m.Parts {
- if _, ok := part.(Finish); ok {
- m.Parts = slices.Delete(m.Parts, i, i+1)
- break
- }
- }
- m.Parts = append(m.Parts, Finish{Reason: reason, Time: time.Now().Unix()})
+type service struct {
+ *pubsub.Broker[File]
+ db *sql.DB
+ q *db.Queries
}
-func (m *Message) AddImageURL(url, detail string) {
- m.Parts = append(m.Parts, ImageURLContent{URL: url, Detail: detail})
+func NewService(q *db.Queries, db *sql.DB) Service {
+ return &service{
+ Broker: pubsub.NewBroker[File](),
+ q: q,
+ db: db,
+ }
}
-func (m *Message) AddBinary(mimeType string, data []byte) {
- m.Parts = append(m.Parts, BinaryContent{MIMEType: mimeType, Data: data})
+func (s *service) Create(ctx context.Context, sessionID, path, content string) (File, error) {
+ return s.createWithVersion(ctx, sessionID, path, content, InitialVersion)
}
+func (s *service) CreateVersion(ctx context.Context, sessionID, path, content string) (File, error) {
+ // Get the latest version for this path
+ files, err := s.q.ListFilesByPath(ctx, path)
```
This function is important because it defines how OpenCode AI Legacy Tutorial: Archived Terminal Agent Workflows and Migration to Crush implements the patterns covered in this chapter.
-### `internal/message/content.go`
+### `internal/history/file.go`
-The `AddImageURL` function in [`internal/message/content.go`](https://github.com/opencode-ai/opencode/blob/HEAD/internal/message/content.go) handles a key part of this chapter's functionality:
+The `GetByPathAndSession` function in [`internal/history/file.go`](https://github.com/opencode-ai/opencode/blob/HEAD/internal/history/file.go) handles a key part of this chapter's functionality:
```go
+ CreateVersion(ctx context.Context, sessionID, path, content string) (File, error)
+ Get(ctx context.Context, id string) (File, error)
+ GetByPathAndSession(ctx context.Context, path, sessionID string) (File, error)
+ ListBySession(ctx context.Context, sessionID string) ([]File, error)
+ ListLatestSessionFiles(ctx context.Context, sessionID string) ([]File, error)
+ Update(ctx context.Context, file File) (File, error)
+ Delete(ctx context.Context, id string) error
+ DeleteSessionFiles(ctx context.Context, sessionID string) error
}
-func (m *Message) AddImageURL(url, detail string) {
- m.Parts = append(m.Parts, ImageURLContent{URL: url, Detail: detail})
+type service struct {
+ *pubsub.Broker[File]
+ db *sql.DB
+ q *db.Queries
}
-func (m *Message) AddBinary(mimeType string, data []byte) {
- m.Parts = append(m.Parts, BinaryContent{MIMEType: mimeType, Data: data})
+func NewService(q *db.Queries, db *sql.DB) Service {
+ return &service{
+ Broker: pubsub.NewBroker[File](),
+ q: q,
+ db: db,
+ }
+}
+
+func (s *service) Create(ctx context.Context, sessionID, path, content string) (File, error) {
+ return s.createWithVersion(ctx, sessionID, path, content, InitialVersion)
}
+func (s *service) CreateVersion(ctx context.Context, sessionID, path, content string) (File, error) {
+ // Get the latest version for this path
+ files, err := s.q.ListFilesByPath(ctx, path)
+ if err != nil {
```
This function is important because it defines how OpenCode AI Legacy Tutorial: Archived Terminal Agent Workflows and Migration to Crush implements the patterns covered in this chapter.
-### `internal/message/content.go`
+### `internal/history/file.go`
-The `AddBinary` function in [`internal/message/content.go`](https://github.com/opencode-ai/opencode/blob/HEAD/internal/message/content.go) handles a key part of this chapter's functionality:
+The `ListBySession` function in [`internal/history/file.go`](https://github.com/opencode-ai/opencode/blob/HEAD/internal/history/file.go) handles a key part of this chapter's functionality:
```go
+ Get(ctx context.Context, id string) (File, error)
+ GetByPathAndSession(ctx context.Context, path, sessionID string) (File, error)
+ ListBySession(ctx context.Context, sessionID string) ([]File, error)
+ ListLatestSessionFiles(ctx context.Context, sessionID string) ([]File, error)
+ Update(ctx context.Context, file File) (File, error)
+ Delete(ctx context.Context, id string) error
+ DeleteSessionFiles(ctx context.Context, sessionID string) error
+}
+
+type service struct {
+ *pubsub.Broker[File]
+ db *sql.DB
+ q *db.Queries
}
-func (m *Message) AddBinary(mimeType string, data []byte) {
- m.Parts = append(m.Parts, BinaryContent{MIMEType: mimeType, Data: data})
+func NewService(q *db.Queries, db *sql.DB) Service {
+ return &service{
+ Broker: pubsub.NewBroker[File](),
+ q: q,
+ db: db,
+ }
}
+func (s *service) Create(ctx context.Context, sessionID, path, content string) (File, error) {
+ return s.createWithVersion(ctx, sessionID, path, content, InitialVersion)
+}
+
+func (s *service) CreateVersion(ctx context.Context, sessionID, path, content string) (File, error) {
+ // Get the latest version for this path
+ files, err := s.q.ListFilesByPath(ctx, path)
+ if err != nil {
+ return File{}, err
```
This function is important because it defines how OpenCode AI Legacy Tutorial: Archived Terminal Agent Workflows and Migration to Crush implements the patterns covered in this chapter.
-### `internal/message/message.go`
+### `internal/history/file.go`
-The `NewService` function in [`internal/message/message.go`](https://github.com/opencode-ai/opencode/blob/HEAD/internal/message/message.go) handles a key part of this chapter's functionality:
+The `ListLatestSessionFiles` function in [`internal/history/file.go`](https://github.com/opencode-ai/opencode/blob/HEAD/internal/history/file.go) handles a key part of this chapter's functionality:
```go
+ GetByPathAndSession(ctx context.Context, path, sessionID string) (File, error)
+ ListBySession(ctx context.Context, sessionID string) ([]File, error)
+ ListLatestSessionFiles(ctx context.Context, sessionID string) ([]File, error)
+ Update(ctx context.Context, file File) (File, error)
+ Delete(ctx context.Context, id string) error
+ DeleteSessionFiles(ctx context.Context, sessionID string) error
}
-func NewService(q db.Querier) Service {
+type service struct {
+ *pubsub.Broker[File]
+ db *sql.DB
+ q *db.Queries
+}
+
+func NewService(q *db.Queries, db *sql.DB) Service {
return &service{
- Broker: pubsub.NewBroker[Message](),
+ Broker: pubsub.NewBroker[File](),
q: q,
+ db: db,
}
}
-func (s *service) Delete(ctx context.Context, id string) error {
- message, err := s.Get(ctx, id)
- if err != nil {
- return err
- }
- err = s.q.DeleteMessage(ctx, message.ID)
- if err != nil {
- return err
- }
- s.Publish(pubsub.DeletedEvent, message)
- return nil
+func (s *service) Create(ctx context.Context, sessionID, path, content string) (File, error) {
+ return s.createWithVersion(ctx, sessionID, path, content, InitialVersion)
}
-func (s *service) Create(ctx context.Context, sessionID string, params CreateMessageParams) (Message, error) {
- if params.Role != Assistant {
- params.Parts = append(params.Parts, Finish{
- Reason: "stop",
- })
- }
- partsJSON, err := marshallParts(params.Parts)
+func (s *service) CreateVersion(ctx context.Context, sessionID, path, content string) (File, error) {
+ // Get the latest version for this path
+ files, err := s.q.ListFilesByPath(ctx, path)
if err != nil {
- return Message{}, err
+ return File{}, err
}
```
@@ -153,11 +210,11 @@ This function is important because it defines how OpenCode AI Legacy Tutorial: A
```mermaid
flowchart TD
- A[AddFinish]
- B[AddImageURL]
- C[AddBinary]
- D[NewService]
- E[Delete]
+ A[Get]
+ B[GetByPathAndSession]
+ C[ListBySession]
+ D[ListLatestSessionFiles]
+ E[Update]
A --> B
B --> C
C --> D
diff --git a/tutorials/opencode-ai-legacy-tutorial/08-legacy-governance-and-controlled-sunset.md b/tutorials/opencode-ai-legacy-tutorial/08-legacy-governance-and-controlled-sunset.md
index a019937c..4ab9f42f 100644
--- a/tutorials/opencode-ai-legacy-tutorial/08-legacy-governance-and-controlled-sunset.md
+++ b/tutorials/opencode-ai-legacy-tutorial/08-legacy-governance-and-controlled-sunset.md
@@ -39,121 +39,118 @@ You now have a full legacy-to-sunset runbook for archived terminal coding-agent
Next tutorial: [AGENTS.md Tutorial](../agents-md-tutorial/)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `internal/app/app.go`
+### `internal/completions/files-folders.go`
-The `initTheme` function in [`internal/app/app.go`](https://github.com/opencode-ai/opencode/blob/HEAD/internal/app/app.go) handles a key part of this chapter's functionality:
+The `processNullTerminatedOutput` function in [`internal/completions/files-folders.go`](https://github.com/opencode-ai/opencode/blob/HEAD/internal/completions/files-folders.go) handles a key part of this chapter's functionality:
```go
+}
- // Initialize theme based on configuration
- app.initTheme()
-
- // Initialize LSP clients in the background
- go app.initLSPClients(ctx)
-
- var err error
- app.CoderAgent, err = agent.NewAgent(
- config.AgentCoder,
- app.Sessions,
- app.Messages,
- agent.CoderAgentTools(
- app.Permissions,
- app.Sessions,
- app.Messages,
- app.History,
- app.LSPClients,
- ),
- )
- if err != nil {
- logging.Error("Failed to create coder agent", err)
- return nil, err
+func processNullTerminatedOutput(outputBytes []byte) []string {
+ if len(outputBytes) > 0 && outputBytes[len(outputBytes)-1] == 0 {
+ outputBytes = outputBytes[:len(outputBytes)-1]
+ }
+
+ if len(outputBytes) == 0 {
+ return []string{}
+ }
+
+ split := bytes.Split(outputBytes, []byte{0})
+ matches := make([]string, 0, len(split))
+
+ for _, p := range split {
+ if len(p) == 0 {
+ continue
+ }
+
+ path := string(p)
+ path = filepath.Join(".", path)
+
+ if !fileutil.SkipHidden(path) {
+ matches = append(matches, path)
+ }
}
- return app, nil
+ return matches
}
-// initTheme sets the application theme based on the configuration
-func (app *App) initTheme() {
- cfg := config.Get()
- if cfg == nil || cfg.TUI.Theme == "" {
+func (cg *filesAndFoldersContextGroup) getFiles(query string) ([]string, error) {
+ cmdRg := fileutil.GetRgCmd("") // No glob pattern for this use case
```
This function is important because it defines how OpenCode AI Legacy Tutorial: Archived Terminal Agent Workflows and Migration to Crush implements the patterns covered in this chapter.
-### `internal/app/app.go`
+### `internal/completions/files-folders.go`
-The `RunNonInteractive` function in [`internal/app/app.go`](https://github.com/opencode-ai/opencode/blob/HEAD/internal/app/app.go) handles a key part of this chapter's functionality:
+The `getFiles` function in [`internal/completions/files-folders.go`](https://github.com/opencode-ai/opencode/blob/HEAD/internal/completions/files-folders.go) handles a key part of this chapter's functionality:
```go
}
-// RunNonInteractive handles the execution flow when a prompt is provided via CLI flag.
-func (a *App) RunNonInteractive(ctx context.Context, prompt string, outputFormat string, quiet bool) error {
- logging.Info("Running in non-interactive mode")
+func (cg *filesAndFoldersContextGroup) getFiles(query string) ([]string, error) {
+ cmdRg := fileutil.GetRgCmd("") // No glob pattern for this use case
+ cmdFzf := fileutil.GetFzfCmd(query)
- // Start spinner if not in quiet mode
- var spinner *format.Spinner
- if !quiet {
- spinner = format.NewSpinner("Thinking...")
- spinner.Start()
- defer spinner.Stop()
- }
+ var matches []string
+ // Case 1: Both rg and fzf available
+ if cmdRg != nil && cmdFzf != nil {
+ rgPipe, err := cmdRg.StdoutPipe()
+ if err != nil {
+ return nil, fmt.Errorf("failed to get rg stdout pipe: %w", err)
+ }
+ defer rgPipe.Close()
- const maxPromptLengthForTitle = 100
- titlePrefix := "Non-interactive: "
- var titleSuffix string
+ cmdFzf.Stdin = rgPipe
+ var fzfOut bytes.Buffer
+ var fzfErr bytes.Buffer
+ cmdFzf.Stdout = &fzfOut
+ cmdFzf.Stderr = &fzfErr
- if len(prompt) > maxPromptLengthForTitle {
- titleSuffix = prompt[:maxPromptLengthForTitle] + "..."
- } else {
- titleSuffix = prompt
- }
- title := titlePrefix + titleSuffix
+ if err := cmdFzf.Start(); err != nil {
+ return nil, fmt.Errorf("failed to start fzf: %w", err)
+ }
- sess, err := a.Sessions.Create(ctx, title)
- if err != nil {
- return fmt.Errorf("failed to create session for non-interactive mode: %w", err)
- }
- logging.Info("Created session for non-interactive run", "session_id", sess.ID)
+ errRg := cmdRg.Run()
+ errFzf := cmdFzf.Wait()
+
+ if errRg != nil {
+ logging.Warn(fmt.Sprintf("rg command failed during pipe: %v", errRg))
+ }
- // Automatically approve all permission requests for this non-interactive session
```
This function is important because it defines how OpenCode AI Legacy Tutorial: Archived Terminal Agent Workflows and Migration to Crush implements the patterns covered in this chapter.
-### `internal/app/app.go`
+### `internal/completions/files-folders.go`
-The `Shutdown` function in [`internal/app/app.go`](https://github.com/opencode-ai/opencode/blob/HEAD/internal/app/app.go) handles a key part of this chapter's functionality:
+The `GetChildEntries` function in [`internal/completions/files-folders.go`](https://github.com/opencode-ai/opencode/blob/HEAD/internal/completions/files-folders.go) handles a key part of this chapter's functionality:
```go
}
-// Shutdown performs a clean shutdown of the application
-func (app *App) Shutdown() {
- // Cancel all watcher goroutines
- app.cancelFuncsMutex.Lock()
- for _, cancel := range app.watcherCancelFuncs {
- cancel()
+func (cg *filesAndFoldersContextGroup) GetChildEntries(query string) ([]dialog.CompletionItemI, error) {
+ matches, err := cg.getFiles(query)
+ if err != nil {
+ return nil, err
}
- app.cancelFuncsMutex.Unlock()
- app.watcherWG.Wait()
-
- // Perform additional cleanup for LSP clients
- app.clientsMutex.RLock()
- clients := make(map[string]*lsp.Client, len(app.LSPClients))
- maps.Copy(clients, app.LSPClients)
- app.clientsMutex.RUnlock()
-
- for name, client := range clients {
- shutdownCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
- if err := client.Shutdown(shutdownCtx); err != nil {
- logging.Error("Failed to shutdown LSP client", "name", name, "error", err)
- }
- cancel()
+
+ items := make([]dialog.CompletionItemI, 0, len(matches))
+ for _, file := range matches {
+ item := dialog.NewCompletionItem(dialog.CompletionItem{
+ Title: file,
+ Value: file,
+ })
+ items = append(items, item)
+ }
+
+ return items, nil
+}
+
+func NewFileAndFolderContextGroup() dialog.CompletionProvider {
+ return &filesAndFoldersContextGroup{
+ prefix: "file",
}
}
@@ -161,43 +158,19 @@ func (app *App) Shutdown() {
This function is important because it defines how OpenCode AI Legacy Tutorial: Archived Terminal Agent Workflows and Migration to Crush implements the patterns covered in this chapter.
-### `internal/app/lsp.go`
+### `internal/completions/files-folders.go`
-The `initLSPClients` function in [`internal/app/lsp.go`](https://github.com/opencode-ai/opencode/blob/HEAD/internal/app/lsp.go) handles a key part of this chapter's functionality:
+The `NewFileAndFolderContextGroup` function in [`internal/completions/files-folders.go`](https://github.com/opencode-ai/opencode/blob/HEAD/internal/completions/files-folders.go) handles a key part of this chapter's functionality:
```go
-)
-
-func (app *App) initLSPClients(ctx context.Context) {
- cfg := config.Get()
-
- // Initialize LSP clients
- for name, clientConfig := range cfg.LSP {
- // Start each client initialization in its own goroutine
- go app.createAndStartLSPClient(ctx, name, clientConfig.Command, clientConfig.Args...)
- }
- logging.Info("LSP clients initialization started in background")
}
-// createAndStartLSPClient creates a new LSP client, initializes it, and starts its workspace watcher
-func (app *App) createAndStartLSPClient(ctx context.Context, name string, command string, args ...string) {
- // Create a specific context for initialization with a timeout
- logging.Info("Creating LSP client", "name", name, "command", command, "args", args)
-
- // Create the LSP client
- lspClient, err := lsp.NewClient(ctx, command, args...)
- if err != nil {
- logging.Error("Failed to create LSP client for", name, err)
- return
+func NewFileAndFolderContextGroup() dialog.CompletionProvider {
+ return &filesAndFoldersContextGroup{
+ prefix: "file",
}
+}
- // Create a longer timeout for initialization (some servers take time to start)
- initCtx, cancel := context.WithTimeout(ctx, 30*time.Second)
- defer cancel()
-
- // Initialize with the initialization context
- _, err = lspClient.InitializeLSPClient(initCtx, config.WorkingDirectory())
- if err != nil {
```
This function is important because it defines how OpenCode AI Legacy Tutorial: Archived Terminal Agent Workflows and Migration to Crush implements the patterns covered in this chapter.
@@ -207,11 +180,11 @@ This function is important because it defines how OpenCode AI Legacy Tutorial: A
```mermaid
flowchart TD
- A[initTheme]
- B[RunNonInteractive]
- C[Shutdown]
- D[initLSPClients]
- E[createAndStartLSPClient]
+ A[processNullTerminatedOutput]
+ B[getFiles]
+ C[GetChildEntries]
+ D[NewFileAndFolderContextGroup]
+ E[initLSPClients]
A --> B
B --> C
C --> D
diff --git a/tutorials/opencode-tutorial/01-getting-started.md b/tutorials/opencode-tutorial/01-getting-started.md
index e95fc07e..8e7256be 100644
--- a/tutorials/opencode-tutorial/01-getting-started.md
+++ b/tutorials/opencode-tutorial/01-getting-started.md
@@ -55,186 +55,15 @@ You now have OpenCode installed and validated for day-to-day terminal workflows.
Next: [Chapter 2: Architecture and Agent Loop](02-architecture-agent-loop.md)
-## Depth Expansion Playbook
-
-## Source Code Walkthrough
-
-### `sst-env.d.ts`
-
-The `Resource` interface in [`sst-env.d.ts`](https://github.com/anomalyco/opencode/blob/HEAD/sst-env.d.ts) handles a key part of this chapter's functionality:
-
-```ts
-
-declare module "sst" {
- export interface Resource {
- "ADMIN_SECRET": {
- "type": "sst.sst.Secret"
- "value": string
- }
- "AUTH_API_URL": {
- "type": "sst.sst.Linkable"
- "value": string
- }
- "AWS_SES_ACCESS_KEY_ID": {
- "type": "sst.sst.Secret"
- "value": string
- }
- "AWS_SES_SECRET_ACCESS_KEY": {
- "type": "sst.sst.Secret"
- "value": string
- }
- "Api": {
- "type": "sst.cloudflare.Worker"
- "url": string
- }
- "AuthApi": {
- "type": "sst.cloudflare.Worker"
- "url": string
- }
- "AuthStorage": {
- "namespaceId": string
- "type": "sst.cloudflare.Kv"
- }
- "Bucket": {
-```
-
-This interface is important because it defines how OpenCode Tutorial: Open-Source Terminal Coding Agent at Scale implements the patterns covered in this chapter.
-
-### `github/index.ts`
-
-The `createOpencode` function in [`github/index.ts`](https://github.com/anomalyco/opencode/blob/HEAD/github/index.ts) handles a key part of this chapter's functionality:
-
-```ts
-import type { Context as GitHubContext } from "@actions/github/lib/context"
-import type { IssueCommentEvent, PullRequestReviewCommentEvent } from "@octokit/webhooks-types"
-import { createOpencodeClient } from "@opencode-ai/sdk"
-import { spawn } from "node:child_process"
-import { setTimeout as sleep } from "node:timers/promises"
-
-type GitHubAuthor = {
- login: string
- name?: string
-}
-
-type GitHubComment = {
- id: string
- databaseId: string
- body: string
- author: GitHubAuthor
- createdAt: string
-}
-
-type GitHubReviewComment = GitHubComment & {
- path: string
- line: number | null
-}
-
-type GitHubCommit = {
- oid: string
- message: string
- author: {
- name: string
- email: string
- }
-}
-```
-
-This function is important because it defines how OpenCode Tutorial: Open-Source Terminal Coding Agent at Scale implements the patterns covered in this chapter.
-
-### `github/index.ts`
-
-The `assertPayloadKeyword` function in [`github/index.ts`](https://github.com/anomalyco/opencode/blob/HEAD/github/index.ts) handles a key part of this chapter's functionality:
-
-```ts
-try {
- assertContextEvent("issue_comment", "pull_request_review_comment")
- assertPayloadKeyword()
- await assertOpencodeConnected()
-
- accessToken = await getAccessToken()
- octoRest = new Octokit({ auth: accessToken })
- octoGraph = graphql.defaults({
- headers: { authorization: `token ${accessToken}` },
- })
-
- const { userPrompt, promptFiles } = await getUserPrompt()
- await configureGit(accessToken)
- await assertPermissions()
-
- const comment = await createComment()
- commentId = comment.data.id
-
- // Setup opencode session
- const repoData = await fetchRepo()
- session = await client.session.create<true>().then((r) => r.data)
- await subscribeSessionEvents()
- shareId = await (async () => {
- if (useEnvShare() === false) return
- if (!useEnvShare() && repoData.data.private) return
- await client.session.share<true>({ path: session })
- return session.id.slice(-8)
- })()
- console.log("opencode session", session.id)
- if (shareId) {
- console.log("Share link:", `${useShareUrl()}/s/${shareId}`)
- }
-```
-
-This function is important because it defines how OpenCode Tutorial: Open-Source Terminal Coding Agent at Scale implements the patterns covered in this chapter.
-
-### `github/index.ts`
-
-The `getReviewCommentContext` function in [`github/index.ts`](https://github.com/anomalyco/opencode/blob/HEAD/github/index.ts) handles a key part of this chapter's functionality:
-
-```ts
-}
-
-function getReviewCommentContext() {
- const context = useContext()
- if (context.eventName !== "pull_request_review_comment") {
- return null
- }
-
- const payload = context.payload as PullRequestReviewCommentEvent
- return {
- file: payload.comment.path,
- diffHunk: payload.comment.diff_hunk,
- line: payload.comment.line,
- originalLine: payload.comment.original_line,
- position: payload.comment.position,
- commitId: payload.comment.commit_id,
- originalCommitId: payload.comment.original_commit_id,
- }
-}
-
-async function assertOpencodeConnected() {
- let retry = 0
- let connected = false
- do {
- try {
- await client.app.log<true>({
- body: {
- service: "github-workflow",
- level: "info",
- message: "Prepare to react to GitHub Workflow event",
- },
- })
-```
-
-This function is important because it defines how OpenCode Tutorial: Open-Source Terminal Coding Agent at Scale implements the patterns covered in this chapter.
-
-
## How These Components Connect
```mermaid
-flowchart TD
- A[Resource]
- B[createOpencode]
- C[assertPayloadKeyword]
- D[getReviewCommentContext]
- E[assertOpencodeConnected]
- A --> B
- B --> C
- C --> D
- D --> E
+flowchart LR
+ A[opencode CLI] --> B{Mode}
+ B -->|build| C[Agent Loop]
+ B -->|plan| D[Analysis Only]
+ C --> E[File Tools]
+ C --> F[Shell Tools]
+ C --> G[Model Provider]
+ G --> H[Response / Patch]
```
diff --git a/tutorials/opencode-tutorial/02-architecture-agent-loop.md b/tutorials/opencode-tutorial/02-architecture-agent-loop.md
index 49fc39d7..2ece0cf9 100644
--- a/tutorials/opencode-tutorial/02-architecture-agent-loop.md
+++ b/tutorials/opencode-tutorial/02-architecture-agent-loop.md
@@ -48,186 +48,15 @@ You now have the architecture mental model required for safe customization.
Next: [Chapter 3: Model and Provider Routing](03-model-and-provider-routing.md)
-## Depth Expansion Playbook
-
-## Source Code Walkthrough
-
-### `github/index.ts`
-
-The `useEnvAgent` function in [`github/index.ts`](https://github.com/anomalyco/opencode/blob/HEAD/github/index.ts) handles a key part of this chapter's functionality:
-
-```ts
-}
-
-function useEnvAgent() {
- return process.env["AGENT"] || undefined
-}
-
-function useEnvShare() {
- const value = process.env["SHARE"]
- if (!value) return undefined
- if (value === "true") return true
- if (value === "false") return false
- throw new Error(`Invalid share value: ${value}. Share must be a boolean.`)
-}
-
-function useEnvMock() {
- return {
- mockEvent: process.env["MOCK_EVENT"],
- mockToken: process.env["MOCK_TOKEN"],
- }
-}
-
-function useEnvGithubToken() {
- return process.env["TOKEN"]
-}
-
-function isMock() {
- const { mockEvent, mockToken } = useEnvMock()
- return Boolean(mockEvent || mockToken)
-}
-
-function isPullRequest() {
- const context = useContext()
-```
-
-This function is important because it defines how OpenCode Tutorial: Open-Source Terminal Coding Agent at Scale implements the patterns covered in this chapter.
-
-### `github/index.ts`
-
-The `useEnvShare` function in [`github/index.ts`](https://github.com/anomalyco/opencode/blob/HEAD/github/index.ts) handles a key part of this chapter's functionality:
-
-```ts
- await subscribeSessionEvents()
- shareId = await (async () => {
- if (useEnvShare() === false) return
- if (!useEnvShare() && repoData.data.private) return
- await client.session.share<true>({ path: session })
- return session.id.slice(-8)
- })()
- console.log("opencode session", session.id)
- if (shareId) {
- console.log("Share link:", `${useShareUrl()}/s/${shareId}`)
- }
-
- // Handle 3 cases
- // 1. Issue
- // 2. Local PR
- // 3. Fork PR
- if (isPullRequest()) {
- const prData = await fetchPR()
- // Local PR
- if (prData.headRepository.nameWithOwner === prData.baseRepository.nameWithOwner) {
- await checkoutLocalBranch(prData)
- const dataPrompt = buildPromptDataForPR(prData)
- const response = await chat(`${userPrompt}\n\n${dataPrompt}`, promptFiles)
- if (await branchIsDirty()) {
- const summary = await summarize(response)
- await pushToLocalBranch(summary)
- }
- const hasShared = prData.comments.nodes.some((c) => c.body.includes(`${useShareUrl()}/s/${shareId}`))
- await updateComment(`${response}${footer({ image: !hasShared })}`)
- }
- // Fork PR
- else {
-```
-
-This function is important because it defines how OpenCode Tutorial: Open-Source Terminal Coding Agent at Scale implements the patterns covered in this chapter.
-
-### `github/index.ts`
-
-The `useEnvMock` function in [`github/index.ts`](https://github.com/anomalyco/opencode/blob/HEAD/github/index.ts) handles a key part of this chapter's functionality:
-
-```ts
-}
-
-function useEnvMock() {
- return {
- mockEvent: process.env["MOCK_EVENT"],
- mockToken: process.env["MOCK_TOKEN"],
- }
-}
-
-function useEnvGithubToken() {
- return process.env["TOKEN"]
-}
-
-function isMock() {
- const { mockEvent, mockToken } = useEnvMock()
- return Boolean(mockEvent || mockToken)
-}
-
-function isPullRequest() {
- const context = useContext()
- const payload = context.payload as IssueCommentEvent
- return Boolean(payload.issue.pull_request)
-}
-
-function useContext() {
- return isMock() ? (JSON.parse(useEnvMock().mockEvent!) as GitHubContext) : github.context
-}
-
-function useIssueId() {
- const payload = useContext().payload as IssueCommentEvent
- return payload.issue.number
-}
-```
-
-This function is important because it defines how OpenCode Tutorial: Open-Source Terminal Coding Agent at Scale implements the patterns covered in this chapter.
-
-### `github/index.ts`
-
-The `useEnvGithubToken` function in [`github/index.ts`](https://github.com/anomalyco/opencode/blob/HEAD/github/index.ts) handles a key part of this chapter's functionality:
-
-```ts
-}
-
-function useEnvGithubToken() {
- return process.env["TOKEN"]
-}
-
-function isMock() {
- const { mockEvent, mockToken } = useEnvMock()
- return Boolean(mockEvent || mockToken)
-}
-
-function isPullRequest() {
- const context = useContext()
- const payload = context.payload as IssueCommentEvent
- return Boolean(payload.issue.pull_request)
-}
-
-function useContext() {
- return isMock() ? (JSON.parse(useEnvMock().mockEvent!) as GitHubContext) : github.context
-}
-
-function useIssueId() {
- const payload = useContext().payload as IssueCommentEvent
- return payload.issue.number
-}
-
-function useShareUrl() {
- return isMock() ? "https://dev.opencode.ai" : "https://opencode.ai"
-}
-
-async function getAccessToken() {
- const { repo } = useContext()
-```
-
-This function is important because it defines how OpenCode Tutorial: Open-Source Terminal Coding Agent at Scale implements the patterns covered in this chapter.
-
-
## How These Components Connect
```mermaid
flowchart TD
- A[useEnvAgent]
- B[useEnvShare]
- C[useEnvMock]
- D[useEnvGithubToken]
- E[isMock]
- A --> B
- B --> C
- C --> D
- D --> E
+ A[User Input] --> B[OpenCode Client TUI]
+ B --> C[Agent Runtime]
+ C --> D[Planning Phase]
+ D --> E[Tool Execution]
+ E --> F[File Edits / Shell Cmds]
+ F --> G[Result Synthesis]
+ G --> B
```
diff --git a/tutorials/opencode-tutorial/03-model-and-provider-routing.md b/tutorials/opencode-tutorial/03-model-and-provider-routing.md
index cf08dc2a..284c6232 100644
--- a/tutorials/opencode-tutorial/03-model-and-provider-routing.md
+++ b/tutorials/opencode-tutorial/03-model-and-provider-routing.md
@@ -45,186 +45,16 @@ You now know how to build a provider strategy instead of relying on a single def
Next: [Chapter 4: Tools, Permissions, and Execution](04-tools-permissions-and-execution.md)
-## Depth Expansion Playbook
-
-## Source Code Walkthrough
-
-### `github/index.ts`
-
-The `useShareUrl` function in [`github/index.ts`](https://github.com/anomalyco/opencode/blob/HEAD/github/index.ts) handles a key part of this chapter's functionality:
-
-```ts
- console.log("opencode session", session.id)
- if (shareId) {
- console.log("Share link:", `${useShareUrl()}/s/${shareId}`)
- }
-
- // Handle 3 cases
- // 1. Issue
- // 2. Local PR
- // 3. Fork PR
- if (isPullRequest()) {
- const prData = await fetchPR()
- // Local PR
- if (prData.headRepository.nameWithOwner === prData.baseRepository.nameWithOwner) {
- await checkoutLocalBranch(prData)
- const dataPrompt = buildPromptDataForPR(prData)
- const response = await chat(`${userPrompt}\n\n${dataPrompt}`, promptFiles)
- if (await branchIsDirty()) {
- const summary = await summarize(response)
- await pushToLocalBranch(summary)
- }
- const hasShared = prData.comments.nodes.some((c) => c.body.includes(`${useShareUrl()}/s/${shareId}`))
- await updateComment(`${response}${footer({ image: !hasShared })}`)
- }
- // Fork PR
- else {
- await checkoutForkBranch(prData)
- const dataPrompt = buildPromptDataForPR(prData)
- const response = await chat(`${userPrompt}\n\n${dataPrompt}`, promptFiles)
- if (await branchIsDirty()) {
- const summary = await summarize(response)
- await pushToForkBranch(summary, prData)
- }
-```
-
-This function is important because it defines how OpenCode Tutorial: Open-Source Terminal Coding Agent at Scale implements the patterns covered in this chapter.
-
-### `github/index.ts`
-
-The `getAccessToken` function in [`github/index.ts`](https://github.com/anomalyco/opencode/blob/HEAD/github/index.ts) handles a key part of this chapter's functionality:
-
-```ts
- await assertOpencodeConnected()
-
- accessToken = await getAccessToken()
- octoRest = new Octokit({ auth: accessToken })
- octoGraph = graphql.defaults({
- headers: { authorization: `token ${accessToken}` },
- })
-
- const { userPrompt, promptFiles } = await getUserPrompt()
- await configureGit(accessToken)
- await assertPermissions()
-
- const comment = await createComment()
- commentId = comment.data.id
-
- // Setup opencode session
- const repoData = await fetchRepo()
- session = await client.session.create<true>().then((r) => r.data)
- await subscribeSessionEvents()
- shareId = await (async () => {
- if (useEnvShare() === false) return
- if (!useEnvShare() && repoData.data.private) return
- await client.session.share<true>({ path: session })
- return session.id.slice(-8)
- })()
- console.log("opencode session", session.id)
- if (shareId) {
- console.log("Share link:", `${useShareUrl()}/s/${shareId}`)
- }
-
- // Handle 3 cases
- // 1. Issue
-```
-
-This function is important because it defines how OpenCode Tutorial: Open-Source Terminal Coding Agent at Scale implements the patterns covered in this chapter.
-
-### `github/index.ts`
-
-The `createComment` function in [`github/index.ts`](https://github.com/anomalyco/opencode/blob/HEAD/github/index.ts) handles a key part of this chapter's functionality:
-
-```ts
- await assertPermissions()
-
- const comment = await createComment()
- commentId = comment.data.id
-
- // Setup opencode session
- const repoData = await fetchRepo()
- session = await client.session.create<true>().then((r) => r.data)
- await subscribeSessionEvents()
- shareId = await (async () => {
- if (useEnvShare() === false) return
- if (!useEnvShare() && repoData.data.private) return
- await client.session.share<true>({ path: session })
- return session.id.slice(-8)
- })()
- console.log("opencode session", session.id)
- if (shareId) {
- console.log("Share link:", `${useShareUrl()}/s/${shareId}`)
- }
-
- // Handle 3 cases
- // 1. Issue
- // 2. Local PR
- // 3. Fork PR
- if (isPullRequest()) {
- const prData = await fetchPR()
- // Local PR
- if (prData.headRepository.nameWithOwner === prData.baseRepository.nameWithOwner) {
- await checkoutLocalBranch(prData)
- const dataPrompt = buildPromptDataForPR(prData)
- const response = await chat(`${userPrompt}\n\n${dataPrompt}`, promptFiles)
- if (await branchIsDirty()) {
-```
-
-This function is important because it defines how OpenCode Tutorial: Open-Source Terminal Coding Agent at Scale implements the patterns covered in this chapter.
-
-### `github/index.ts`
-
-The `getUserPrompt` function in [`github/index.ts`](https://github.com/anomalyco/opencode/blob/HEAD/github/index.ts) handles a key part of this chapter's functionality:
-
-```ts
-let shareId: string | undefined
-let exitCode = 0
-type PromptFiles = Awaited<ReturnType<typeof getUserPrompt>>["promptFiles"]
-
-try {
- assertContextEvent("issue_comment", "pull_request_review_comment")
- assertPayloadKeyword()
- await assertOpencodeConnected()
-
- accessToken = await getAccessToken()
- octoRest = new Octokit({ auth: accessToken })
- octoGraph = graphql.defaults({
- headers: { authorization: `token ${accessToken}` },
- })
-
- const { userPrompt, promptFiles } = await getUserPrompt()
- await configureGit(accessToken)
- await assertPermissions()
-
- const comment = await createComment()
- commentId = comment.data.id
-
- // Setup opencode session
- const repoData = await fetchRepo()
- session = await client.session.create<true>().then((r) => r.data)
- await subscribeSessionEvents()
- shareId = await (async () => {
- if (useEnvShare() === false) return
- if (!useEnvShare() && repoData.data.private) return
- await client.session.share<true>({ path: session })
- return session.id.slice(-8)
- })()
-```
-
-This function is important because it defines how OpenCode Tutorial: Open-Source Terminal Coding Agent at Scale implements the patterns covered in this chapter.
-
-
## How These Components Connect
```mermaid
-flowchart TD
- A[useShareUrl]
- B[getAccessToken]
- C[createComment]
- D[getUserPrompt]
- E[subscribeSessionEvents]
- A --> B
- B --> C
- C --> D
- D --> E
+flowchart LR
+ A[opencode config] --> B{Provider Router}
+ B --> C[Anthropic Claude]
+ B --> D[OpenAI / Azure]
+ B --> E[Ollama Local]
+ B --> F[Custom Provider]
+ C --> G[Agent Response]
+ D --> G
+ E --> G
```
diff --git a/tutorials/opencode-tutorial/04-tools-permissions-and-execution.md b/tutorials/opencode-tutorial/04-tools-permissions-and-execution.md
index 2ad79406..cf402be9 100644
--- a/tutorials/opencode-tutorial/04-tools-permissions-and-execution.md
+++ b/tutorials/opencode-tutorial/04-tools-permissions-and-execution.md
@@ -47,186 +47,17 @@ You now have a practical safety baseline for running OpenCode against important
Next: [Chapter 5: Agents, Subagents, and Planning](05-agents-subagents-and-planning.md)
-## Depth Expansion Playbook
-
-## Source Code Walkthrough
-
-### `github/index.ts`
-
-The `configureGit` function in [`github/index.ts`](https://github.com/anomalyco/opencode/blob/HEAD/github/index.ts) handles a key part of this chapter's functionality:
-
-```ts
-
- const { userPrompt, promptFiles } = await getUserPrompt()
- await configureGit(accessToken)
- await assertPermissions()
-
- const comment = await createComment()
- commentId = comment.data.id
-
- // Setup opencode session
- const repoData = await fetchRepo()
- session = await client.session.create<true>().then((r) => r.data)
- await subscribeSessionEvents()
- shareId = await (async () => {
- if (useEnvShare() === false) return
- if (!useEnvShare() && repoData.data.private) return
- await client.session.share<true>({ path: session })
- return session.id.slice(-8)
- })()
- console.log("opencode session", session.id)
- if (shareId) {
- console.log("Share link:", `${useShareUrl()}/s/${shareId}`)
- }
-
- // Handle 3 cases
- // 1. Issue
- // 2. Local PR
- // 3. Fork PR
- if (isPullRequest()) {
- const prData = await fetchPR()
- // Local PR
- if (prData.headRepository.nameWithOwner === prData.baseRepository.nameWithOwner) {
- await checkoutLocalBranch(prData)
-```
-
-This function is important because it defines how OpenCode Tutorial: Open-Source Terminal Coding Agent at Scale implements the patterns covered in this chapter.
-
-### `github/index.ts`
-
-The `restoreGitConfig` function in [`github/index.ts`](https://github.com/anomalyco/opencode/blob/HEAD/github/index.ts) handles a key part of this chapter's functionality:
-
-```ts
-} finally {
- server.close()
- await restoreGitConfig()
- await revokeAppToken()
-}
-process.exit(exitCode)
-
-function createOpencode() {
- const host = "127.0.0.1"
- const port = 4096
- const url = `http://${host}:${port}`
- const proc = spawn(`opencode`, [`serve`, `--hostname=${host}`, `--port=${port}`])
- const client = createOpencodeClient({ baseUrl: url })
-
- return {
- server: { url, close: () => proc.kill() },
- client,
- }
-}
-
-function assertPayloadKeyword() {
- const payload = useContext().payload as IssueCommentEvent | PullRequestReviewCommentEvent
- const body = payload.comment.body.trim()
- if (!body.match(/(?:^|\s)(?:\/opencode|\/oc)(?=$|\s)/)) {
- throw new Error("Comments must mention `/opencode` or `/oc`")
- }
-}
-
-function getReviewCommentContext() {
- const context = useContext()
- if (context.eventName !== "pull_request_review_comment") {
- return null
-```
-
-This function is important because it defines how OpenCode Tutorial: Open-Source Terminal Coding Agent at Scale implements the patterns covered in this chapter.
-
-### `github/index.ts`
-
-The `checkoutNewBranch` function in [`github/index.ts`](https://github.com/anomalyco/opencode/blob/HEAD/github/index.ts) handles a key part of this chapter's functionality:
-
-```ts
- // Issue
- else {
- const branch = await checkoutNewBranch()
- const issueData = await fetchIssue()
- const dataPrompt = buildPromptDataForIssue(issueData)
- const response = await chat(`${userPrompt}\n\n${dataPrompt}`, promptFiles)
- if (await branchIsDirty()) {
- const summary = await summarize(response)
- await pushToNewBranch(summary, branch)
- const pr = await createPR(
- repoData.data.default_branch,
- branch,
- summary,
- `${response}\n\nCloses #${useIssueId()}${footer({ image: true })}`,
- )
- await updateComment(`Created PR #${pr}${footer({ image: true })}`)
- } else {
- await updateComment(`${response}${footer({ image: true })}`)
- }
- }
-} catch (e: any) {
- exitCode = 1
- console.error(e)
- let msg = e
- if (e instanceof $.ShellError) {
- msg = e.stderr.toString()
- } else if (e instanceof Error) {
- msg = e.message
- }
- await updateComment(`${msg}${footer()}`)
- core.setFailed(msg)
- // Also output the clean error message for the action to capture
-```
-
-This function is important because it defines how OpenCode Tutorial: Open-Source Terminal Coding Agent at Scale implements the patterns covered in this chapter.
-
-### `github/index.ts`
-
-The `checkoutLocalBranch` function in [`github/index.ts`](https://github.com/anomalyco/opencode/blob/HEAD/github/index.ts) handles a key part of this chapter's functionality:
-
-```ts
- // Local PR
- if (prData.headRepository.nameWithOwner === prData.baseRepository.nameWithOwner) {
- await checkoutLocalBranch(prData)
- const dataPrompt = buildPromptDataForPR(prData)
- const response = await chat(`${userPrompt}\n\n${dataPrompt}`, promptFiles)
- if (await branchIsDirty()) {
- const summary = await summarize(response)
- await pushToLocalBranch(summary)
- }
- const hasShared = prData.comments.nodes.some((c) => c.body.includes(`${useShareUrl()}/s/${shareId}`))
- await updateComment(`${response}${footer({ image: !hasShared })}`)
- }
- // Fork PR
- else {
- await checkoutForkBranch(prData)
- const dataPrompt = buildPromptDataForPR(prData)
- const response = await chat(`${userPrompt}\n\n${dataPrompt}`, promptFiles)
- if (await branchIsDirty()) {
- const summary = await summarize(response)
- await pushToForkBranch(summary, prData)
- }
- const hasShared = prData.comments.nodes.some((c) => c.body.includes(`${useShareUrl()}/s/${shareId}`))
- await updateComment(`${response}${footer({ image: !hasShared })}`)
- }
- }
- // Issue
- else {
- const branch = await checkoutNewBranch()
- const issueData = await fetchIssue()
- const dataPrompt = buildPromptDataForIssue(issueData)
- const response = await chat(`${userPrompt}\n\n${dataPrompt}`, promptFiles)
- if (await branchIsDirty()) {
-```
-
-This function is important because it defines how OpenCode Tutorial: Open-Source Terminal Coding Agent at Scale implements the patterns covered in this chapter.
-
## How These Components Connect
```mermaid
flowchart TD
- A[configureGit]
- B[restoreGitConfig]
- C[checkoutNewBranch]
- D[checkoutLocalBranch]
- E[checkoutForkBranch]
- A --> B
- B --> C
- C --> D
- D --> E
+ A[Task Request] --> B[Permission Check]
+ B -->|Allowed| C[Tool Dispatch]
+ B -->|Denied| D[Prompt for Approval]
+ C --> E[File Operations]
+ C --> F[Shell Commands]
+ C --> G[Search / Read]
+ E --> H[Result]
+ F --> H
```
diff --git a/tutorials/opencode-tutorial/05-agents-subagents-and-planning.md b/tutorials/opencode-tutorial/05-agents-subagents-and-planning.md
index afb5bb6d..9e02a204 100644
--- a/tutorials/opencode-tutorial/05-agents-subagents-and-planning.md
+++ b/tutorials/opencode-tutorial/05-agents-subagents-and-planning.md
@@ -45,186 +45,17 @@ You can now use OpenCode modes as a controlled workflow, not just a toggle.
Next: [Chapter 6: Client/Server and Remote Workflows](06-client-server-and-remote-workflows.md)
-## Depth Expansion Playbook
-
-## Source Code Walkthrough
-
-### `github/index.ts`
-
-The `pushToForkBranch` function in [`github/index.ts`](https://github.com/anomalyco/opencode/blob/HEAD/github/index.ts) handles a key part of this chapter's functionality:
-
-```ts
- if (await branchIsDirty()) {
- const summary = await summarize(response)
- await pushToForkBranch(summary, prData)
- }
- const hasShared = prData.comments.nodes.some((c) => c.body.includes(`${useShareUrl()}/s/${shareId}`))
- await updateComment(`${response}${footer({ image: !hasShared })}`)
- }
- }
- // Issue
- else {
- const branch = await checkoutNewBranch()
- const issueData = await fetchIssue()
- const dataPrompt = buildPromptDataForIssue(issueData)
- const response = await chat(`${userPrompt}\n\n${dataPrompt}`, promptFiles)
- if (await branchIsDirty()) {
- const summary = await summarize(response)
- await pushToNewBranch(summary, branch)
- const pr = await createPR(
- repoData.data.default_branch,
- branch,
- summary,
- `${response}\n\nCloses #${useIssueId()}${footer({ image: true })}`,
- )
- await updateComment(`Created PR #${pr}${footer({ image: true })}`)
- } else {
- await updateComment(`${response}${footer({ image: true })}`)
- }
- }
-} catch (e: any) {
- exitCode = 1
- console.error(e)
- let msg = e
-```
-
-This function is important because it defines how OpenCode Tutorial: Open-Source Terminal Coding Agent at Scale implements the patterns covered in this chapter.
-
-### `github/index.ts`
-
-The `branchIsDirty` function in [`github/index.ts`](https://github.com/anomalyco/opencode/blob/HEAD/github/index.ts) handles a key part of this chapter's functionality:
-
-```ts
- const dataPrompt = buildPromptDataForPR(prData)
- const response = await chat(`${userPrompt}\n\n${dataPrompt}`, promptFiles)
- if (await branchIsDirty()) {
- const summary = await summarize(response)
- await pushToLocalBranch(summary)
- }
- const hasShared = prData.comments.nodes.some((c) => c.body.includes(`${useShareUrl()}/s/${shareId}`))
- await updateComment(`${response}${footer({ image: !hasShared })}`)
- }
- // Fork PR
- else {
- await checkoutForkBranch(prData)
- const dataPrompt = buildPromptDataForPR(prData)
- const response = await chat(`${userPrompt}\n\n${dataPrompt}`, promptFiles)
- if (await branchIsDirty()) {
- const summary = await summarize(response)
- await pushToForkBranch(summary, prData)
- }
- const hasShared = prData.comments.nodes.some((c) => c.body.includes(`${useShareUrl()}/s/${shareId}`))
- await updateComment(`${response}${footer({ image: !hasShared })}`)
- }
- }
- // Issue
- else {
- const branch = await checkoutNewBranch()
- const issueData = await fetchIssue()
- const dataPrompt = buildPromptDataForIssue(issueData)
- const response = await chat(`${userPrompt}\n\n${dataPrompt}`, promptFiles)
- if (await branchIsDirty()) {
- const summary = await summarize(response)
- await pushToNewBranch(summary, branch)
- const pr = await createPR(
-```
-
-This function is important because it defines how OpenCode Tutorial: Open-Source Terminal Coding Agent at Scale implements the patterns covered in this chapter.
-
-### `github/index.ts`
-
-The `assertPermissions` function in [`github/index.ts`](https://github.com/anomalyco/opencode/blob/HEAD/github/index.ts) handles a key part of this chapter's functionality:
-
-```ts
- const { userPrompt, promptFiles } = await getUserPrompt()
- await configureGit(accessToken)
- await assertPermissions()
-
- const comment = await createComment()
- commentId = comment.data.id
-
- // Setup opencode session
- const repoData = await fetchRepo()
- session = await client.session.create<true>().then((r) => r.data)
- await subscribeSessionEvents()
- shareId = await (async () => {
- if (useEnvShare() === false) return
- if (!useEnvShare() && repoData.data.private) return
- await client.session.share<true>({ path: session })
- return session.id.slice(-8)
- })()
- console.log("opencode session", session.id)
- if (shareId) {
- console.log("Share link:", `${useShareUrl()}/s/${shareId}`)
- }
-
- // Handle 3 cases
- // 1. Issue
- // 2. Local PR
- // 3. Fork PR
- if (isPullRequest()) {
- const prData = await fetchPR()
- // Local PR
- if (prData.headRepository.nameWithOwner === prData.baseRepository.nameWithOwner) {
- await checkoutLocalBranch(prData)
- const dataPrompt = buildPromptDataForPR(prData)
-```
-
-This function is important because it defines how OpenCode Tutorial: Open-Source Terminal Coding Agent at Scale implements the patterns covered in this chapter.
-
-### `github/index.ts`
-
-The `updateComment` function in [`github/index.ts`](https://github.com/anomalyco/opencode/blob/HEAD/github/index.ts) handles a key part of this chapter's functionality:
-
-```ts
- }
- const hasShared = prData.comments.nodes.some((c) => c.body.includes(`${useShareUrl()}/s/${shareId}`))
- await updateComment(`${response}${footer({ image: !hasShared })}`)
- }
- // Fork PR
- else {
- await checkoutForkBranch(prData)
- const dataPrompt = buildPromptDataForPR(prData)
- const response = await chat(`${userPrompt}\n\n${dataPrompt}`, promptFiles)
- if (await branchIsDirty()) {
- const summary = await summarize(response)
- await pushToForkBranch(summary, prData)
- }
- const hasShared = prData.comments.nodes.some((c) => c.body.includes(`${useShareUrl()}/s/${shareId}`))
- await updateComment(`${response}${footer({ image: !hasShared })}`)
- }
- }
- // Issue
- else {
- const branch = await checkoutNewBranch()
- const issueData = await fetchIssue()
- const dataPrompt = buildPromptDataForIssue(issueData)
- const response = await chat(`${userPrompt}\n\n${dataPrompt}`, promptFiles)
- if (await branchIsDirty()) {
- const summary = await summarize(response)
- await pushToNewBranch(summary, branch)
- const pr = await createPR(
- repoData.data.default_branch,
- branch,
- summary,
- `${response}\n\nCloses #${useIssueId()}${footer({ image: true })}`,
- )
-```
-
-This function is important because it defines how OpenCode Tutorial: Open-Source Terminal Coding Agent at Scale implements the patterns covered in this chapter.
-
## How These Components Connect
```mermaid
-flowchart TD
- A[pushToForkBranch]
- B[branchIsDirty]
- C[assertPermissions]
- D[updateComment]
- E[createPR]
- A --> B
- B --> C
- C --> D
- D --> E
+flowchart LR
+ A[Task Input] --> B{Agent Mode}
+ B -->|plan| C[Planning Agent]
+ B -->|build| D[Build Agent]
+ C --> E[Step-by-step Plan]
+ D --> F[Subagent Dispatch]
+ F --> G[File Tools]
+ F --> H[Shell Tools]
+ E --> I[Human Review]
```
diff --git a/tutorials/opencode-tutorial/06-client-server-and-remote-workflows.md b/tutorials/opencode-tutorial/06-client-server-and-remote-workflows.md
index 02097216..90795716 100644
--- a/tutorials/opencode-tutorial/06-client-server-and-remote-workflows.md
+++ b/tutorials/opencode-tutorial/06-client-server-and-remote-workflows.md
@@ -42,186 +42,15 @@ You now understand how OpenCode can evolve from local tooling into a remote-capa
Next: [Chapter 7: Integrations: MCP, LSP, and Extensions](07-integrations-mcp-lsp-and-extensions.md)
-## Depth Expansion Playbook
-
-## Source Code Walkthrough
-
-### `github/index.ts`
-
-The `buildPromptDataForIssue` function in [`github/index.ts`](https://github.com/anomalyco/opencode/blob/HEAD/github/index.ts) handles a key part of this chapter's functionality:
-
-```ts
- const branch = await checkoutNewBranch()
- const issueData = await fetchIssue()
- const dataPrompt = buildPromptDataForIssue(issueData)
- const response = await chat(`${userPrompt}\n\n${dataPrompt}`, promptFiles)
- if (await branchIsDirty()) {
- const summary = await summarize(response)
- await pushToNewBranch(summary, branch)
- const pr = await createPR(
- repoData.data.default_branch,
- branch,
- summary,
- `${response}\n\nCloses #${useIssueId()}${footer({ image: true })}`,
- )
- await updateComment(`Created PR #${pr}${footer({ image: true })}`)
- } else {
- await updateComment(`${response}${footer({ image: true })}`)
- }
- }
-} catch (e: any) {
- exitCode = 1
- console.error(e)
- let msg = e
- if (e instanceof $.ShellError) {
- msg = e.stderr.toString()
- } else if (e instanceof Error) {
- msg = e.message
- }
- await updateComment(`${msg}${footer()}`)
- core.setFailed(msg)
- // Also output the clean error message for the action to capture
- //core.setOutput("prepare_error", e.message);
-} finally {
-```
-
-This function is important because it defines how OpenCode Tutorial: Open-Source Terminal Coding Agent at Scale implements the patterns covered in this chapter.
-
-### `github/index.ts`
-
-The `fetchPR` function in [`github/index.ts`](https://github.com/anomalyco/opencode/blob/HEAD/github/index.ts) handles a key part of this chapter's functionality:
-
-```ts
- // 3. Fork PR
- if (isPullRequest()) {
- const prData = await fetchPR()
- // Local PR
- if (prData.headRepository.nameWithOwner === prData.baseRepository.nameWithOwner) {
- await checkoutLocalBranch(prData)
- const dataPrompt = buildPromptDataForPR(prData)
- const response = await chat(`${userPrompt}\n\n${dataPrompt}`, promptFiles)
- if (await branchIsDirty()) {
- const summary = await summarize(response)
- await pushToLocalBranch(summary)
- }
- const hasShared = prData.comments.nodes.some((c) => c.body.includes(`${useShareUrl()}/s/${shareId}`))
- await updateComment(`${response}${footer({ image: !hasShared })}`)
- }
- // Fork PR
- else {
- await checkoutForkBranch(prData)
- const dataPrompt = buildPromptDataForPR(prData)
- const response = await chat(`${userPrompt}\n\n${dataPrompt}`, promptFiles)
- if (await branchIsDirty()) {
- const summary = await summarize(response)
- await pushToForkBranch(summary, prData)
- }
- const hasShared = prData.comments.nodes.some((c) => c.body.includes(`${useShareUrl()}/s/${shareId}`))
- await updateComment(`${response}${footer({ image: !hasShared })}`)
- }
- }
- // Issue
- else {
- const branch = await checkoutNewBranch()
- const issueData = await fetchIssue()
-```
-
-This function is important because it defines how OpenCode Tutorial: Open-Source Terminal Coding Agent at Scale implements the patterns covered in this chapter.
-
-### `github/index.ts`
-
-The `buildPromptDataForPR` function in [`github/index.ts`](https://github.com/anomalyco/opencode/blob/HEAD/github/index.ts) handles a key part of this chapter's functionality:
-
-```ts
- if (prData.headRepository.nameWithOwner === prData.baseRepository.nameWithOwner) {
- await checkoutLocalBranch(prData)
- const dataPrompt = buildPromptDataForPR(prData)
- const response = await chat(`${userPrompt}\n\n${dataPrompt}`, promptFiles)
- if (await branchIsDirty()) {
- const summary = await summarize(response)
- await pushToLocalBranch(summary)
- }
- const hasShared = prData.comments.nodes.some((c) => c.body.includes(`${useShareUrl()}/s/${shareId}`))
- await updateComment(`${response}${footer({ image: !hasShared })}`)
- }
- // Fork PR
- else {
- await checkoutForkBranch(prData)
- const dataPrompt = buildPromptDataForPR(prData)
- const response = await chat(`${userPrompt}\n\n${dataPrompt}`, promptFiles)
- if (await branchIsDirty()) {
- const summary = await summarize(response)
- await pushToForkBranch(summary, prData)
- }
- const hasShared = prData.comments.nodes.some((c) => c.body.includes(`${useShareUrl()}/s/${shareId}`))
- await updateComment(`${response}${footer({ image: !hasShared })}`)
- }
- }
- // Issue
- else {
- const branch = await checkoutNewBranch()
- const issueData = await fetchIssue()
- const dataPrompt = buildPromptDataForIssue(issueData)
- const response = await chat(`${userPrompt}\n\n${dataPrompt}`, promptFiles)
- if (await branchIsDirty()) {
- const summary = await summarize(response)
-```
-
-This function is important because it defines how OpenCode Tutorial: Open-Source Terminal Coding Agent at Scale implements the patterns covered in this chapter.
-
-### `github/index.ts`
-
-The `revokeAppToken` function in [`github/index.ts`](https://github.com/anomalyco/opencode/blob/HEAD/github/index.ts) handles a key part of this chapter's functionality:
-
-```ts
- server.close()
- await restoreGitConfig()
- await revokeAppToken()
-}
-process.exit(exitCode)
-
-function createOpencode() {
- const host = "127.0.0.1"
- const port = 4096
- const url = `http://${host}:${port}`
- const proc = spawn(`opencode`, [`serve`, `--hostname=${host}`, `--port=${port}`])
- const client = createOpencodeClient({ baseUrl: url })
-
- return {
- server: { url, close: () => proc.kill() },
- client,
- }
-}
-
-function assertPayloadKeyword() {
- const payload = useContext().payload as IssueCommentEvent | PullRequestReviewCommentEvent
- const body = payload.comment.body.trim()
- if (!body.match(/(?:^|\s)(?:\/opencode|\/oc)(?=$|\s)/)) {
- throw new Error("Comments must mention `/opencode` or `/oc`")
- }
-}
-
-function getReviewCommentContext() {
- const context = useContext()
- if (context.eventName !== "pull_request_review_comment") {
- return null
- }
-```
-
-This function is important because it defines how OpenCode Tutorial: Open-Source Terminal Coding Agent at Scale implements the patterns covered in this chapter.
-
## How These Components Connect
```mermaid
-flowchart TD
- A[buildPromptDataForIssue]
- B[fetchPR]
- C[buildPromptDataForPR]
- D[revokeAppToken]
- E[getLatestRelease]
- A --> B
- B --> C
- C --> D
- D --> E
+flowchart LR
+ A[Remote Client] --> B[OpenCode Server]
+ B --> C[Session Manager]
+ C --> D[Agent Runtime]
+ D --> E[Shared Workspace]
+ B --> F[Auth Layer]
+ F --> C
```
diff --git a/tutorials/opencode-tutorial/07-integrations-mcp-lsp-and-extensions.md b/tutorials/opencode-tutorial/07-integrations-mcp-lsp-and-extensions.md
index e2aa0100..f2aa7342 100644
--- a/tutorials/opencode-tutorial/07-integrations-mcp-lsp-and-extensions.md
+++ b/tutorials/opencode-tutorial/07-integrations-mcp-lsp-and-extensions.md
@@ -39,186 +39,16 @@ You now have a blueprint for extending OpenCode safely and effectively across yo
Next: [Chapter 8: Production Operations and Security](08-production-operations-security.md)
-## Depth Expansion Playbook
-
-## Source Code Walkthrough
-
-### `script/changelog.ts`
-
-The `summarizeCommit` function in [`script/changelog.ts`](https://github.com/anomalyco/opencode/blob/HEAD/script/changelog.ts) handles a key part of this chapter's functionality:
-
-```ts
-}
-
-async function summarizeCommit(opencode: Awaited<ReturnType<typeof createOpencode>>, message: string): Promise<string> {
- console.log("summarizing commit:", message)
- const session = await opencode.client.session.create()
- const result = await opencode.client.session
- .prompt(
- {
- sessionID: session.data!.id,
- model: { providerID: "opencode", modelID: "claude-sonnet-4-5" },
- tools: {
- "*": false,
- },
- parts: [
- {
- type: "text",
- text: `Summarize this commit message for a changelog entry. Return ONLY a single line summary starting with a capital letter. Be concise but specific. If the commit message is already well-written, just clean it up (capitalize, fix typos, proper grammar). Do not include any prefixes like "fix:" or "feat:".
-
-Commit: ${message}`,
- },
- ],
- },
- {
- signal: AbortSignal.timeout(120_000),
- },
- )
- .then((x) => x.data?.parts?.find((y) => y.type === "text")?.text ?? message)
- return result.trim()
-}
-
-export async function generateChangelog(commits: Commit[], opencode: Awaited<ReturnType<typeof createOpencode>>) {
- // Summarize commits in parallel with max 10 concurrent requests
-```
-
-This function is important because it defines how OpenCode Tutorial: Open-Source Terminal Coding Agent at Scale implements the patterns covered in this chapter.
-
-### `script/changelog.ts`
-
-The `generateChangelog` function in [`script/changelog.ts`](https://github.com/anomalyco/opencode/blob/HEAD/script/changelog.ts) handles a key part of this chapter's functionality:
-
-```ts
-}
-
-export async function generateChangelog(commits: Commit[], opencode: Awaited<ReturnType<typeof createOpencode>>) {
- // Summarize commits in parallel with max 10 concurrent requests
- const BATCH_SIZE = 10
- const summaries: string[] = []
- for (let i = 0; i < commits.length; i += BATCH_SIZE) {
- const batch = commits.slice(i, i + BATCH_SIZE)
- const results = await Promise.all(batch.map((c) => summarizeCommit(opencode, c.message)))
- summaries.push(...results)
- }
-
- const grouped = new Map<string, string[]>()
- for (let i = 0; i < commits.length; i++) {
- const commit = commits[i]!
- const section = getSection(commit.areas)
- const attribution = commit.author && !Script.team.includes(commit.author) ? ` (@${commit.author})` : ""
- const entry = `- ${summaries[i]}${attribution}`
-
- if (!grouped.has(section)) grouped.set(section, [])
- grouped.get(section)!.push(entry)
- }
-
- const sectionOrder = ["Core", "TUI", "Desktop", "SDK", "Extensions"]
- const lines: string[] = []
- for (const section of sectionOrder) {
- const entries = grouped.get(section)
- if (!entries || entries.length === 0) continue
- lines.push(`## ${section}`)
- lines.push(...entries)
- }
-
-```
-
-This function is important because it defines how OpenCode Tutorial: Open-Source Terminal Coding Agent at Scale implements the patterns covered in this chapter.
-
-### `script/changelog.ts`
-
-The `getContributors` function in [`script/changelog.ts`](https://github.com/anomalyco/opencode/blob/HEAD/script/changelog.ts) handles a key part of this chapter's functionality:
-
-```ts
-}
-
-export async function getContributors(from: string, to: string) {
- const fromRef = from.startsWith("v") ? from : `v${from}`
- const toRef = to === "HEAD" ? to : to.startsWith("v") ? to : `v${to}`
- const compare =
- await $`gh api "/repos/anomalyco/opencode/compare/${fromRef}...${toRef}" --jq '.commits[] | {login: .author.login, message: .commit.message}'`.text()
- const contributors = new Map<string, Set<string>>()
-
- for (const line of compare.split("\n").filter(Boolean)) {
- const { login, message } = JSON.parse(line) as { login: string | null; message: string }
- const title = message.split("\n")[0] ?? ""
- if (title.match(/^(ignore:|test:|chore:|ci:|release:)/i)) continue
-
- if (login && !Script.team.includes(login)) {
- if (!contributors.has(login)) contributors.set(login, new Set())
- contributors.get(login)!.add(title)
- }
- }
-
- return contributors
-}
-
-export async function buildNotes(from: string, to: string) {
- const commits = await getCommits(from, to)
-
- if (commits.length === 0) {
- return []
- }
-
- console.log("generating changelog since " + from)
-
-```
-
-This function is important because it defines how OpenCode Tutorial: Open-Source Terminal Coding Agent at Scale implements the patterns covered in this chapter.
-
-### `script/changelog.ts`
-
-The `buildNotes` function in [`script/changelog.ts`](https://github.com/anomalyco/opencode/blob/HEAD/script/changelog.ts) handles a key part of this chapter's functionality:
-
-```ts
-}
-
-export async function buildNotes(from: string, to: string) {
- const commits = await getCommits(from, to)
-
- if (commits.length === 0) {
- return []
- }
-
- console.log("generating changelog since " + from)
-
- const opencode = await createOpencode({ port: 0 })
- const notes: string[] = []
-
- try {
- const lines = await generateChangelog(commits, opencode)
- notes.push(...lines)
- console.log("---- Generated Changelog ----")
- console.log(notes.join("\n"))
- console.log("-----------------------------")
- } catch (error) {
- if (error instanceof Error && error.name === "TimeoutError") {
- console.log("Changelog generation timed out, using raw commits")
- for (const commit of commits) {
- const attribution = commit.author && !team.includes(commit.author) ? ` (@${commit.author})` : ""
- notes.push(`- ${commit.message}${attribution}`)
- }
- } else {
- throw error
- }
- } finally {
- await opencode.server.close()
-```
-
-This function is important because it defines how OpenCode Tutorial: Open-Source Terminal Coding Agent at Scale implements the patterns covered in this chapter.
-
## How These Components Connect
```mermaid
flowchart TD
- A[summarizeCommit]
- B[generateChangelog]
- C[getContributors]
- D[buildNotes]
- E[sendToPostHog]
- A --> B
- B --> C
- C --> D
- D --> E
+ A[OpenCode Agent] --> B[MCP Client]
+ B --> C[MCP Server / Tools]
+ A --> D[LSP Client]
+ D --> E[Language Server]
+ A --> F[Custom Extensions]
+ C --> G[External APIs]
+ E --> H[Code Intelligence]
```
diff --git a/tutorials/opencode-tutorial/08-production-operations-security.md b/tutorials/opencode-tutorial/08-production-operations-security.md
index 0e915749..74580cb7 100644
--- a/tutorials/opencode-tutorial/08-production-operations-security.md
+++ b/tutorials/opencode-tutorial/08-production-operations-security.md
@@ -47,186 +47,16 @@ This chapter turns OpenCode from a local assistant into an operational platform
You now have an operations baseline for running OpenCode in serious development environments.
-## Depth Expansion Playbook
-
-## Source Code Walkthrough
-
-### `script/stats.ts`
-
-The `save` function in [`script/stats.ts`](https://github.com/anomalyco/opencode/blob/HEAD/script/stats.ts) handles a key part of this chapter's functionality:
-
-```ts
-}
-
-async function save(githubTotal: number, npmDownloads: number) {
- const file = "STATS.md"
- const date = new Date().toISOString().split("T")[0]
- const total = githubTotal + npmDownloads
-
- let previousGithub = 0
- let previousNpm = 0
- let previousTotal = 0
- let content = ""
-
- try {
- content = await Bun.file(file).text()
- const lines = content.trim().split("\n")
-
- for (let i = lines.length - 1; i >= 0; i--) {
- const line = lines[i].trim()
- if (line.startsWith("|") && !line.includes("Date") && !line.includes("---")) {
- const match = line.match(
- /\|\s*[\d-]+\s*\|\s*([\d,]+)\s*(?:\([^)]*\))?\s*\|\s*([\d,]+)\s*(?:\([^)]*\))?\s*\|\s*([\d,]+)\s*(?:\([^)]*\))?\s*\|/,
- )
- if (match) {
- previousGithub = parseInt(match[1].replace(/,/g, ""))
- previousNpm = parseInt(match[2].replace(/,/g, ""))
- previousTotal = parseInt(match[3].replace(/,/g, ""))
- break
- }
- }
- }
- } catch {
- content =
-```
-
-This function is important because it defines how OpenCode Tutorial: Open-Source Terminal Coding Agent at Scale implements the patterns covered in this chapter.
-
-### `script/stats.ts`
-
-The `Asset` interface in [`script/stats.ts`](https://github.com/anomalyco/opencode/blob/HEAD/script/stats.ts) handles a key part of this chapter's functionality:
-
-```ts
-}
-
-interface Asset {
- name: string
- download_count: number
-}
-
-interface Release {
- tag_name: string
- name: string
- assets: Asset[]
-}
-
-interface NpmDownloadsRange {
- start: string
- end: string
- package: string
- downloads: Array<{
- downloads: number
- day: string
- }>
-}
-
-async function fetchNpmDownloads(packageName: string): Promise<number> {
- try {
- // Use a range from 2020 to current year + 5 years to ensure it works forever
- const currentYear = new Date().getFullYear()
- const endYear = currentYear + 5
- const response = await fetch(`https://api.npmjs.org/downloads/range/2020-01-01:${endYear}-12-31/${packageName}`)
- if (!response.ok) {
- console.warn(`Failed to fetch npm downloads for ${packageName}: ${response.status}`)
- return 0
-```
-
-This interface is important because it defines how OpenCode Tutorial: Open-Source Terminal Coding Agent at Scale implements the patterns covered in this chapter.
-
-### `script/stats.ts`
-
-The `Release` interface in [`script/stats.ts`](https://github.com/anomalyco/opencode/blob/HEAD/script/stats.ts) handles a key part of this chapter's functionality:
-
-```ts
-}
-
-interface Release {
- tag_name: string
- name: string
- assets: Asset[]
-}
-
-interface NpmDownloadsRange {
- start: string
- end: string
- package: string
- downloads: Array<{
- downloads: number
- day: string
- }>
-}
-
-async function fetchNpmDownloads(packageName: string): Promise<number> {
- try {
- // Use a range from 2020 to current year + 5 years to ensure it works forever
- const currentYear = new Date().getFullYear()
- const endYear = currentYear + 5
- const response = await fetch(`https://api.npmjs.org/downloads/range/2020-01-01:${endYear}-12-31/${packageName}`)
- if (!response.ok) {
- console.warn(`Failed to fetch npm downloads for ${packageName}: ${response.status}`)
- return 0
- }
- const data: NpmDownloadsRange = await response.json()
- return data.downloads.reduce((total, day) => total + day.downloads, 0)
- } catch (error) {
- console.warn(`Error fetching npm downloads for ${packageName}:`, error)
-```
-
-This interface is important because it defines how OpenCode Tutorial: Open-Source Terminal Coding Agent at Scale implements the patterns covered in this chapter.
-
-### `script/stats.ts`
-
-The `NpmDownloadsRange` interface in [`script/stats.ts`](https://github.com/anomalyco/opencode/blob/HEAD/script/stats.ts) handles a key part of this chapter's functionality:
-
-```ts
-}
-
-interface NpmDownloadsRange {
- start: string
- end: string
- package: string
- downloads: Array<{
- downloads: number
- day: string
- }>
-}
-
-async function fetchNpmDownloads(packageName: string): Promise<number> {
- try {
- // Use a range from 2020 to current year + 5 years to ensure it works forever
- const currentYear = new Date().getFullYear()
- const endYear = currentYear + 5
- const response = await fetch(`https://api.npmjs.org/downloads/range/2020-01-01:${endYear}-12-31/${packageName}`)
- if (!response.ok) {
- console.warn(`Failed to fetch npm downloads for ${packageName}: ${response.status}`)
- return 0
- }
- const data: NpmDownloadsRange = await response.json()
- return data.downloads.reduce((total, day) => total + day.downloads, 0)
- } catch (error) {
- console.warn(`Error fetching npm downloads for ${packageName}:`, error)
- return 0
- }
-}
-
-async function fetchReleases(): Promise<Release[]> {
- const releases: Release[] = []
-```
-
-This interface is important because it defines how OpenCode Tutorial: Open-Source Terminal Coding Agent at Scale implements the patterns covered in this chapter.
-
## How These Components Connect
```mermaid
flowchart TD
- A[save]
- B[Asset]
- C[Release]
- D[NpmDownloadsRange]
- E[commentOnPR]
- A --> B
- B --> C
- C --> D
- D --> E
+ A[CI/CD Pipeline] --> B[OpenCode Agent]
+ B --> C[Audit Logging]
+ B --> D[Permission Policies]
+ D --> E[Tool Allowlist]
+ C --> F[Log Store]
+ B --> G[Error Recovery]
+ G --> H[Retry or Abort]
```
diff --git a/tutorials/opencode-tutorial/README.md b/tutorials/opencode-tutorial/README.md
index 451287c7..6114a077 100644
--- a/tutorials/opencode-tutorial/README.md
+++ b/tutorials/opencode-tutorial/README.md
@@ -28,8 +28,8 @@ This track focuses on:
## Current Snapshot (auto-updated)
- repository: [`anomalyco/opencode`](https://github.com/anomalyco/opencode)
-- stars: about **138k**
-- latest release: [`v1.3.17`](https://github.com/anomalyco/opencode/releases/tag/v1.3.17) (published 2026-04-06)
+- stars: about **142k**
+- latest release: [`v1.3.7`](https://github.com/anomalyco/opencode/releases/tag/v1.3.7) (published 2026-03-30)
## Mental Model
diff --git a/tutorials/openhands-tutorial/01-getting-started.md b/tutorials/openhands-tutorial/01-getting-started.md
index 893987e8..7a9e5e14 100644
--- a/tutorials/openhands-tutorial/01-getting-started.md
+++ b/tutorials/openhands-tutorial/01-getting-started.md
@@ -6,6 +6,7 @@ has_children: false
parent: OpenHands Tutorial
---
+
# Chapter 1: Getting Started with OpenHands
Welcome to **Chapter 1: Getting Started with OpenHands**. In this part of **OpenHands Tutorial: Autonomous Software Engineering Workflows**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
@@ -572,148 +573,17 @@ Next, we'll explore **basic operations** - file manipulation, command execution,
## Depth Expansion Playbook
-<!-- depth-expansion-v2 -->
-
-This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
-
-### Strategic Context
-
-- tutorial: **OpenHands Tutorial: Autonomous Software Engineering Workflows**
-- tutorial slug: **openhands-tutorial**
-- chapter focus: **Chapter 1: Getting Started with OpenHands**
-- system context: **Openhands Tutorial**
-- objective: move from surface-level usage to repeatable engineering operation
-
-### Architecture Decomposition
-
-1. Define the runtime boundary for `Chapter 1: Getting Started with OpenHands`.
-2. Separate control-plane decisions from data-plane execution.
-3. Capture input contracts, transformation points, and output contracts.
-4. Trace state transitions across request lifecycle stages.
-5. Identify extension hooks and policy interception points.
-6. Map ownership boundaries for team and automation workflows.
-7. Specify rollback and recovery paths for unsafe changes.
-8. Track observability signals for correctness, latency, and cost.
-
-### Operator Decision Matrix
-
-| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
-|:--------------|:--------------|:------------------|:---------|
-| Runtime mode | managed defaults | explicit policy config | speed vs control |
-| State handling | local ephemeral | durable persisted state | simplicity vs auditability |
-| Tool integration | direct API use | mediated adapter layer | velocity vs governance |
-| Rollout method | manual change | staged + canary rollout | effort vs safety |
-| Incident response | best effort logs | runbooks + SLO alerts | cost vs reliability |
-
-### Failure Modes and Countermeasures
-
-| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
-|:-------------|:-------------|:-------------------|:---------------|
-| stale context | inconsistent outputs | missing refresh window | enforce context TTL and refresh hooks |
-| policy drift | unexpected execution | ad hoc overrides | centralize policy profiles |
-| auth mismatch | 401/403 bursts | credential sprawl | rotation schedule + scope minimization |
-| schema breakage | parser/validation errors | unmanaged upstream changes | contract tests per release |
-| retry storms | queue congestion | no backoff controls | jittered backoff + circuit breakers |
-| silent regressions | quality drop without alerts | weak baseline metrics | eval harness with thresholds |
-
-### Implementation Runbook
-
-1. Establish a reproducible baseline environment.
-2. Capture chapter-specific success criteria before changes.
-3. Implement minimal viable path with explicit interfaces.
-4. Add observability before expanding feature scope.
-5. Run deterministic tests for happy-path behavior.
-6. Inject failure scenarios for negative-path validation.
-7. Compare output quality against baseline snapshots.
-8. Promote through staged environments with rollback gates.
-9. Record operational lessons in release notes.
-
-### Quality Gate Checklist
-
-- [ ] chapter-level assumptions are explicit and testable
-- [ ] API/tool boundaries are documented with input/output examples
-- [ ] failure handling includes retry, timeout, and fallback policy
-- [ ] security controls include auth scopes and secret rotation plans
-- [ ] observability includes logs, metrics, traces, and alert thresholds
-- [ ] deployment guidance includes canary and rollback paths
-- [ ] docs include links to upstream sources and related tracks
-- [ ] post-release verification confirms expected behavior under load
-
-### Source Alignment
-
-- [OpenHands Repository](https://github.com/OpenHands/OpenHands)
-- [OpenHands Docs](https://docs.openhands.dev/)
-- [OpenHands Releases](https://github.com/OpenHands/OpenHands/releases)
-
-### Cross-Tutorial Connection Map
-
-- [OpenClaw Tutorial](../openclaw-tutorial/)
-- [Cline Tutorial](../cline-tutorial/)
-- [Roo Code Tutorial](../roo-code-tutorial/)
-- [Continue Tutorial](../continue-tutorial/)
-- [Chapter 1: Getting Started](01-getting-started.md)
-
-### Advanced Practice Exercises
-
-1. Build a minimal end-to-end implementation for `Chapter 1: Getting Started with OpenHands`.
-2. Add instrumentation and measure baseline latency and error rate.
-3. Introduce one controlled failure and confirm graceful recovery.
-4. Add policy constraints and verify they are enforced consistently.
-5. Run a staged rollout and document rollback decision criteria.
-
-### Review Questions
-
-1. Which execution boundary matters most for this chapter and why?
-2. What signal detects regressions earliest in your environment?
-3. What tradeoff did you make between delivery speed and governance?
-4. How would you recover from the highest-impact failure mode?
-5. What must be automated before scaling to team-wide adoption?
-
-## What Problem Does This Solve?
-
-Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for `print`, `result`, `openhands` so behavior stays predictable as complexity grows.
-
-In practical terms, this chapter helps you avoid three common failures:
-
-- coupling core logic too tightly to one implementation path
-- missing the handoff boundaries between setup, execution, and validation
-- shipping changes without clear rollback or observability strategy
-
-After working through this chapter, you should be able to reason about `Chapter 1: Getting Started with OpenHands` as an operating subsystem inside **OpenHands Tutorial: Autonomous Software Engineering Workflows**, with explicit contracts for inputs, state transitions, and outputs.
-
-Use the implementation notes around `task`, `workspace`, `OpenHands` as your checklist when adapting these patterns to your own repository.
-
-## How it Works Under the Hood
-
-Under the hood, `Chapter 1: Getting Started with OpenHands` usually follows a repeatable control path:
-
-1. **Context bootstrap**: initialize runtime config and prerequisites for `print`.
-2. **Input normalization**: shape incoming data so `result` receives stable contracts.
-3. **Core execution**: run the main logic branch and propagate intermediate state through `openhands`.
-4. **Policy and safety checks**: enforce limits, auth scopes, and failure boundaries.
-5. **Output composition**: return canonical result payloads for downstream consumers.
-6. **Operational telemetry**: emit logs/metrics needed for debugging and performance tuning.
-
-When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
-
-## Source Walkthrough
-
-Use the following upstream sources to verify implementation details while reading this chapter:
-
-- [OpenHands Repository](https://github.com/OpenHands/OpenHands)
- Why it matters: authoritative reference on `OpenHands Repository` (github.com).
-- [OpenHands Docs](https://docs.openhands.dev/)
- Why it matters: authoritative reference on `OpenHands Docs` (docs.openhands.dev).
-- [OpenHands Releases](https://github.com/OpenHands/OpenHands/releases)
- Why it matters: authoritative reference on `OpenHands Releases` (github.com).
-
-Suggested trace strategy:
-- search upstream code for `print` and `result` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
-
-## Chapter Connections
-
-- [Tutorial Index](README.md)
-- [Next Chapter: Chapter 2: Basic Operations - Files, Commands, and Environments](02-basic-operations.md)
-- [Main Catalog](../../README.md#-tutorial-catalog)
-- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
+## How These Components Connect
+
+```mermaid
+flowchart TD
+ A[Docker Container] --> B[OpenHands Runtime]
+ B --> C[Agent Controller]
+ C --> D[LLM Provider]
+ C --> E[Sandbox Executor]
+ E --> F[File Operations]
+ E --> G[Shell Commands]
+ E --> H[Browser Automation]
+ D --> I[Plan and Actions]
+ I --> E
+```
diff --git a/tutorials/openhands-tutorial/02-basic-operations.md b/tutorials/openhands-tutorial/02-basic-operations.md
index 6398cb20..20dd27e8 100644
--- a/tutorials/openhands-tutorial/02-basic-operations.md
+++ b/tutorials/openhands-tutorial/02-basic-operations.md
@@ -633,6 +633,24 @@ Under the hood, `Chapter 2: Basic Operations - Files, Commands, and Environments
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## Architecture Diagram
+
+```mermaid
+flowchart TD
+ A[Task Description] --> B[Agent Controller]
+ B --> C{Action Type}
+ C -->|FileWrite| D[Write File]
+ C -->|FileRead| E[Read File]
+ C -->|CmdRun| F[Execute Shell]
+ C -->|BrowseURL| G[Browser Step]
+ D --> H[Sandbox]
+ E --> H
+ F --> H
+ G --> H
+ H --> I[Observation]
+ I --> B
+```
+
## Source Walkthrough
Use the following upstream sources to verify implementation details while reading this chapter:
diff --git a/tutorials/openhands-tutorial/03-code-generation.md b/tutorials/openhands-tutorial/03-code-generation.md
index b0af235c..897d03d2 100644
--- a/tutorials/openhands-tutorial/03-code-generation.md
+++ b/tutorials/openhands-tutorial/03-code-generation.md
@@ -692,6 +692,19 @@ Under the hood, `Chapter 3: Code Generation - Creating Production-Ready Code` us
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## Architecture Diagram
+
+```mermaid
+flowchart LR
+ A[Feature Request] --> B[LLM Planning]
+ B --> C[Scaffold Files]
+ C --> D[Write Implementation]
+ D --> E[Run Tests]
+ E --> F{Tests Pass?}
+ F -->|No| B
+ F -->|Yes| G[Commit-ready Output]
+```
+
## Source Walkthrough
Use the following upstream sources to verify implementation details while reading this chapter:
diff --git a/tutorials/openhands-tutorial/04-bug-fixing.md b/tutorials/openhands-tutorial/04-bug-fixing.md
index 218d74a6..f03572e1 100644
--- a/tutorials/openhands-tutorial/04-bug-fixing.md
+++ b/tutorials/openhands-tutorial/04-bug-fixing.md
@@ -850,6 +850,20 @@ Under the hood, `Chapter 4: Bug Fixing - Autonomous Debugging and Resolution` us
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## Architecture Diagram
+
+```mermaid
+flowchart TD
+ A[Bug Report / Failing Test] --> B[Reproduce Step]
+ B --> C[Root Cause Analysis]
+ C --> D[Generate Fix]
+ D --> E[Apply Patch]
+ E --> F[Validate Fix]
+ F --> G{Fixed?}
+ G -->|No| C
+ G -->|Yes| H[Summary]
+```
+
## Source Walkthrough
Use the following upstream sources to verify implementation details while reading this chapter:
diff --git a/tutorials/openhands-tutorial/05-testing.md b/tutorials/openhands-tutorial/05-testing.md
index 089f5164..4a9dc343 100644
--- a/tutorials/openhands-tutorial/05-testing.md
+++ b/tutorials/openhands-tutorial/05-testing.md
@@ -687,6 +687,20 @@ Under the hood, `Chapter 5: Testing - Comprehensive Test Suite Generation and Qu
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## Architecture Diagram
+
+```mermaid
+flowchart LR
+ A[Implementation] --> B[Analyze Code Paths]
+ B --> C[Generate Unit Tests]
+ B --> D[Generate Integration Tests]
+ C --> E[Execute Test Suite]
+ D --> E
+ E --> F{Pass Rate}
+ F -->|Failures| G[Diagnose and Retry]
+ F -->|All Pass| H[Test Report]
+```
+
## Source Walkthrough
Use the following upstream sources to verify implementation details while reading this chapter:
diff --git a/tutorials/openhands-tutorial/06-refactoring.md b/tutorials/openhands-tutorial/06-refactoring.md
index 99df1515..7769b5af 100644
--- a/tutorials/openhands-tutorial/06-refactoring.md
+++ b/tutorials/openhands-tutorial/06-refactoring.md
@@ -905,6 +905,21 @@ Under the hood, `Chapter 6: Refactoring - Code Structure Improvement and Moderni
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## Architecture Diagram
+
+```mermaid
+flowchart TD
+ A[Refactor Target] --> B[Static Analysis]
+ B --> C[Identify Patterns]
+ C --> D{Refactor Type}
+ D -->|Extract| E[Extract Function]
+ D -->|Rename| F[Rename Symbols]
+ D -->|Restructure| G[Move / Split Files]
+ E --> H[Verify Tests Still Pass]
+ F --> H
+ G --> H
+```
+
## Source Walkthrough
Use the following upstream sources to verify implementation details while reading this chapter:
diff --git a/tutorials/openhands-tutorial/07-integration.md b/tutorials/openhands-tutorial/07-integration.md
index bf40c841..097e93a7 100644
--- a/tutorials/openhands-tutorial/07-integration.md
+++ b/tutorials/openhands-tutorial/07-integration.md
@@ -712,6 +712,18 @@ Under the hood, `Chapter 7: Integration - Connecting Applications with External
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## Architecture Diagram
+
+```mermaid
+flowchart LR
+ A[Integration Task] --> B[Identify External Service]
+ B --> C[Generate Client Code]
+ C --> D[Add Auth / Config]
+ D --> E[Write Tests]
+ E --> F[Validate Connection]
+ F --> G[Integration Complete]
+```
+
## Source Walkthrough
Use the following upstream sources to verify implementation details while reading this chapter:
diff --git a/tutorials/openhands-tutorial/08-advanced-projects.md b/tutorials/openhands-tutorial/08-advanced-projects.md
index 41bb38fe..a624eb43 100644
--- a/tutorials/openhands-tutorial/08-advanced-projects.md
+++ b/tutorials/openhands-tutorial/08-advanced-projects.md
@@ -736,6 +736,20 @@ Under the hood, `Chapter 8: Advanced Projects - Complete Applications and System
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## Architecture Diagram
+
+```mermaid
+flowchart TD
+ A[Complex Task] --> B[Decompose into Subtasks]
+ B --> C[Execute Subtask 1]
+ B --> D[Execute Subtask 2]
+ C --> E[Validate Output]
+ D --> E
+ E --> F{All Done?}
+ F -->|No| B
+ F -->|Yes| G[Final Deliverable]
+```
+
## Source Walkthrough
Use the following upstream sources to verify implementation details while reading this chapter:
diff --git a/tutorials/openskills-tutorial/01-getting-started.md b/tutorials/openskills-tutorial/01-getting-started.md
index febfc3b4..a13d01bd 100644
--- a/tutorials/openskills-tutorial/01-getting-started.md
+++ b/tutorials/openskills-tutorial/01-getting-started.md
@@ -32,39 +32,85 @@ You now have OpenSkills running with a synced baseline skill set.
Next: [Chapter 2: Skill Format and Loader Architecture](02-skill-format-and-loader-architecture.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/types.ts`
+### `src/commands/sync.ts`
-The `Skill` interface in [`src/types.ts`](https://github.com/numman-ali/openskills/blob/HEAD/src/types.ts) handles a key part of this chapter's functionality:
+The `syncAgentsMd` function in [`src/commands/sync.ts`](https://github.com/numman-ali/openskills/blob/HEAD/src/commands/sync.ts) handles a key part of this chapter's functionality:
```ts
-export interface Skill {
- name: string;
- description: string;
- location: 'project' | 'global';
- path: string;
-}
+ * Sync installed skills to a markdown file
+ */
+export async function syncAgentsMd(options: SyncOptions = {}): Promise<void> {
+ const outputPath = options.output || 'AGENTS.md';
+ const outputName = basename(outputPath);
+
+ // Validate output file is markdown
+ if (!outputPath.endsWith('.md')) {
+ console.error(chalk.red('Error: Output file must be a markdown file (.md)'));
+ process.exit(1);
+ }
+
+ // Create file if it doesn't exist
+ if (!existsSync(outputPath)) {
+ const dir = dirname(outputPath);
+ if (dir && dir !== '.' && !existsSync(dir)) {
+ mkdirSync(dir, { recursive: true });
+ }
+ writeFileSync(outputPath, `# ${outputName.replace('.md', '')}\n\n`);
+ console.log(chalk.dim(`Created ${outputPath}`));
+ }
+
+ let skills = findAllSkills();
+
+ if (skills.length === 0) {
+ console.log('No skills installed. Install skills first:');
+ console.log(` ${chalk.cyan('npx openskills install anthropics/skills --project')}`);
+ return;
+ }
+
+ // Interactive mode by default (unless -y flag)
+ if (!options.yes) {
+```
-export interface SkillLocation {
- path: string;
- baseDir: string;
- source: string;
-}
+This function is important because it defines how OpenSkills Tutorial: Universal Skill Loading for Coding Agents implements the patterns covered in this chapter.
-export interface InstallOptions {
- global?: boolean;
- universal?: boolean;
+### `src/commands/sync.ts`
+
+The `SyncOptions` interface in [`src/commands/sync.ts`](https://github.com/numman-ali/openskills/blob/HEAD/src/commands/sync.ts) handles a key part of this chapter's functionality:
+
+```ts
+import type { Skill } from '../types.js';
+
+export interface SyncOptions {
yes?: boolean;
+ output?: string;
}
-export interface SkillMetadata {
- name: string;
- description: string;
- context?: string;
-}
+/**
+ * Sync installed skills to a markdown file
+ */
+export async function syncAgentsMd(options: SyncOptions = {}): Promise<void> {
+ const outputPath = options.output || 'AGENTS.md';
+ const outputName = basename(outputPath);
+
+ // Validate output file is markdown
+ if (!outputPath.endsWith('.md')) {
+ console.error(chalk.red('Error: Output file must be a markdown file (.md)'));
+ process.exit(1);
+ }
+
+ // Create file if it doesn't exist
+ if (!existsSync(outputPath)) {
+ const dir = dirname(outputPath);
+ if (dir && dir !== '.' && !existsSync(dir)) {
+ mkdirSync(dir, { recursive: true });
+ }
+ writeFileSync(outputPath, `# ${outputName.replace('.md', '')}\n\n`);
+ console.log(chalk.dim(`Created ${outputPath}`));
+ }
+
+ let skills = findAllSkills();
```
@@ -72,9 +118,14 @@ This interface is important because it defines how OpenSkills Tutorial: Universa
### `src/types.ts`
-The `SkillLocation` interface in [`src/types.ts`](https://github.com/numman-ali/openskills/blob/HEAD/src/types.ts) handles a key part of this chapter's functionality:
+The `Skill` interface in [`src/types.ts`](https://github.com/numman-ali/openskills/blob/HEAD/src/types.ts) handles a key part of this chapter's functionality:
```ts
+export interface Skill {
+ name: string;
+ description: string;
+ location: 'project' | 'global';
+ path: string;
}
export interface SkillLocation {
@@ -101,11 +152,17 @@ This interface is important because it defines how OpenSkills Tutorial: Universa
### `src/types.ts`
-The `InstallOptions` interface in [`src/types.ts`](https://github.com/numman-ali/openskills/blob/HEAD/src/types.ts) handles a key part of this chapter's functionality:
+The `SkillLocation` interface in [`src/types.ts`](https://github.com/numman-ali/openskills/blob/HEAD/src/types.ts) handles a key part of this chapter's functionality:
```ts
}
+export interface SkillLocation {
+ path: string;
+ baseDir: string;
+ source: string;
+}
+
export interface InstallOptions {
global?: boolean;
universal?: boolean;
@@ -122,33 +179,16 @@ export interface SkillMetadata {
This interface is important because it defines how OpenSkills Tutorial: Universal Skill Loading for Coding Agents implements the patterns covered in this chapter.
-### `src/types.ts`
-
-The `SkillMetadata` interface in [`src/types.ts`](https://github.com/numman-ali/openskills/blob/HEAD/src/types.ts) handles a key part of this chapter's functionality:
-
-```ts
-}
-
-export interface SkillMetadata {
- name: string;
- description: string;
- context?: string;
-}
-
-```
-
-This interface is important because it defines how OpenSkills Tutorial: Universal Skill Loading for Coding Agents implements the patterns covered in this chapter.
-
## How These Components Connect
```mermaid
flowchart TD
- A[Skill]
- B[SkillLocation]
- C[InstallOptions]
- D[SkillMetadata]
- E[isLocalPath]
+ A[syncAgentsMd]
+ B[SyncOptions]
+ C[Skill]
+ D[SkillLocation]
+ E[InstallOptions]
A --> B
B --> C
C --> D
diff --git a/tutorials/openskills-tutorial/02-skill-format-and-loader-architecture.md b/tutorials/openskills-tutorial/02-skill-format-and-loader-architecture.md
index a4c43ccb..7a81c3ca 100644
--- a/tutorials/openskills-tutorial/02-skill-format-and-loader-architecture.md
+++ b/tutorials/openskills-tutorial/02-skill-format-and-loader-architecture.md
@@ -27,140 +27,123 @@ You now understand how OpenSkills maps skill files into runtime-usable metadata.
Next: [Chapter 3: Installation Sources and Trust Model](03-installation-sources-and-trust-model.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/commands/install.ts`
+### `src/types.ts`
-The `isGitUrl` function in [`src/commands/install.ts`](https://github.com/numman-ali/openskills/blob/HEAD/src/commands/install.ts) handles a key part of this chapter's functionality:
+The `SkillMetadata` interface in [`src/types.ts`](https://github.com/numman-ali/openskills/blob/HEAD/src/types.ts) handles a key part of this chapter's functionality:
```ts
- * Check if source is a git URL (SSH, git://, or HTTPS)
- */
-function isGitUrl(source: string): boolean {
- return (
- source.startsWith('git@') ||
- source.startsWith('git://') ||
- source.startsWith('http://') ||
- source.startsWith('https://') ||
- source.endsWith('.git')
- );
}
-/**
- * Extract repo name from a git URL
- */
-function getRepoName(repoUrl: string): string | null {
- const cleaned = repoUrl.replace(/\.git$/, '');
- const lastPart = cleaned.split('/').pop();
- if (!lastPart) return null;
- const maybeRepo = lastPart.includes(':') ? lastPart.split(':').pop() : lastPart;
- return maybeRepo || null;
+export interface SkillMetadata {
+ name: string;
+ description: string;
+ context?: string;
}
-/**
- * Expand ~ to home directory
- */
-function expandPath(source: string): string {
- if (source.startsWith('~/')) {
- return join(homedir(), source.slice(2));
- }
- return resolve(source);
-}
```
-This function is important because it defines how OpenSkills Tutorial: Universal Skill Loading for Coding Agents implements the patterns covered in this chapter.
+This interface is important because it defines how OpenSkills Tutorial: Universal Skill Loading for Coding Agents implements the patterns covered in this chapter.
-### `src/commands/install.ts`
+### `src/commands/update.ts`
-The `getRepoName` function in [`src/commands/install.ts`](https://github.com/numman-ali/openskills/blob/HEAD/src/commands/install.ts) handles a key part of this chapter's functionality:
+The `updateSkills` function in [`src/commands/update.ts`](https://github.com/numman-ali/openskills/blob/HEAD/src/commands/update.ts) handles a key part of this chapter's functionality:
```ts
- * Extract repo name from a git URL
- */
-function getRepoName(repoUrl: string): string | null {
- const cleaned = repoUrl.replace(/\.git$/, '');
- const lastPart = cleaned.split('/').pop();
- if (!lastPart) return null;
- const maybeRepo = lastPart.includes(':') ? lastPart.split(':').pop() : lastPart;
- return maybeRepo || null;
-}
-
-/**
- * Expand ~ to home directory
+ * Update installed skills from their recorded source metadata.
*/
-function expandPath(source: string): string {
- if (source.startsWith('~/')) {
- return join(homedir(), source.slice(2));
+export async function updateSkills(skillNames: string[] | string | undefined): Promise<void> {
+ const requested = normalizeSkillNames(skillNames);
+ const skills = findAllSkills();
+
+ if (skills.length === 0) {
+ console.log('No skills installed.\n');
+ console.log('Install skills:');
+ console.log(` ${chalk.cyan('npx openskills install anthropics/skills')} ${chalk.dim('# Project (default)')}`);
+ console.log(` ${chalk.cyan('npx openskills install owner/skill --global')} ${chalk.dim('# Global (advanced)')}`);
+ return;
}
- return resolve(source);
-}
-/**
- * Ensure target path stays within target directory
- */
-function isPathInside(targetPath: string, targetDir: string): boolean {
- const resolvedTargetPath = resolve(targetPath);
- const resolvedTargetDir = resolve(targetDir);
- const resolvedTargetDirWithSep = resolvedTargetDir.endsWith(sep)
- ? resolvedTargetDir
- : resolvedTargetDir + sep;
- return resolvedTargetPath.startsWith(resolvedTargetDirWithSep);
-}
+ let targets = skills;
+
+ if (requested.length > 0) {
+ const requestedSet = new Set(requested);
+ targets = skills.filter((skill) => requestedSet.has(skill.name));
+
+ const missing = requested.filter((name) => !skills.some((skill) => skill.name === name));
+ if (missing.length > 0) {
+ console.log(chalk.yellow(`Skipping missing skills: ${missing.join(', ')}`));
+ }
+ } else {
+ // Default to updating all installed skills
+ targets = skills;
+ }
+ if (targets.length === 0) {
+ console.log(chalk.yellow('No matching skills to update.'));
+ return;
```
This function is important because it defines how OpenSkills Tutorial: Universal Skill Loading for Coding Agents implements the patterns covered in this chapter.
-### `src/commands/install.ts`
+### `src/commands/update.ts`
-The `expandPath` function in [`src/commands/install.ts`](https://github.com/numman-ali/openskills/blob/HEAD/src/commands/install.ts) handles a key part of this chapter's functionality:
+The `updateSkillFromDir` function in [`src/commands/update.ts`](https://github.com/numman-ali/openskills/blob/HEAD/src/commands/update.ts) handles a key part of this chapter's functionality:
```ts
- * Expand ~ to home directory
- */
-function expandPath(source: string): string {
- if (source.startsWith('~/')) {
- return join(homedir(), source.slice(2));
- }
- return resolve(source);
-}
-
-/**
- * Ensure target path stays within target directory
- */
-function isPathInside(targetPath: string, targetDir: string): boolean {
- const resolvedTargetPath = resolve(targetPath);
- const resolvedTargetDir = resolve(targetDir);
- const resolvedTargetDirWithSep = resolvedTargetDir.endsWith(sep)
- ? resolvedTargetDir
- : resolvedTargetDir + sep;
- return resolvedTargetPath.startsWith(resolvedTargetDirWithSep);
-}
-
-/**
- * Install skill from local path, GitHub, or Git URL
- */
-export async function installSkill(source: string, options: InstallOptions): Promise<void> {
- const folder = options.universal ? '.agent/skills' : '.claude/skills';
- const isProject = !options.global; // Default to project unless --global specified
- const targetDir = isProject
- ? join(process.cwd(), folder)
- : join(homedir(), folder);
-
- const location = isProject
+ continue;
+ }
+ updateSkillFromDir(skill.path, localPath);
+ writeSkillMetadata(skill.path, { ...metadata, installedAt: new Date().toISOString() });
+ console.log(chalk.green(`✅ Updated: ${skill.name}`));
+ updated++;
+ continue;
+ }
+
+ if (!metadata.repoUrl) {
+ console.log(chalk.yellow(`Skipped: ${skill.name} (missing repo URL metadata)`));
+ missingRepoUrl.push(skill.name);
+ skipped++;
+ continue;
+ }
+
+ const tempDir = join(homedir(), `.openskills-temp-${Date.now()}`);
+ mkdirSync(tempDir, { recursive: true });
+
+ const spinner = ora(`Updating ${skill.name}...`).start();
+ try {
+ execSync(`git clone --depth 1 --quiet "${metadata.repoUrl}" "${tempDir}/repo"`, { stdio: 'pipe' });
+ const repoDir = join(tempDir, 'repo');
+ const subpath = metadata.subpath && metadata.subpath !== '.' ? metadata.subpath : '';
+ const sourceDir = subpath ? join(repoDir, subpath) : repoDir;
+
+ if (!existsSync(join(sourceDir, 'SKILL.md'))) {
+ spinner.fail(`SKILL.md missing for ${skill.name}`);
+ console.log(chalk.yellow(`Skipped: ${skill.name} (SKILL.md not found in repo at ${subpath || '.'})`));
+ missingRepoSkillFile.push({ name: skill.name, subpath: subpath || '.' });
+ skipped++;
+ continue;
```
This function is important because it defines how OpenSkills Tutorial: Universal Skill Loading for Coding Agents implements the patterns covered in this chapter.
-### `src/commands/install.ts`
+### `src/commands/update.ts`
-The `isPathInside` function in [`src/commands/install.ts`](https://github.com/numman-ali/openskills/blob/HEAD/src/commands/install.ts) handles a key part of this chapter's functionality:
+The `isPathInside` function in [`src/commands/update.ts`](https://github.com/numman-ali/openskills/blob/HEAD/src/commands/update.ts) handles a key part of this chapter's functionality:
```ts
- * Ensure target path stays within target directory
- */
+ mkdirSync(targetDir, { recursive: true });
+
+ if (!isPathInside(targetPath, targetDir)) {
+ console.error(chalk.red('Security error: Installation path outside target directory'));
+ process.exit(1);
+ }
+
+ rmSync(targetPath, { recursive: true, force: true });
+ cpSync(sourceDir, targetPath, { recursive: true, dereference: true });
+}
+
function isPathInside(targetPath: string, targetDir: string): boolean {
const resolvedTargetPath = resolve(targetPath);
const resolvedTargetDir = resolve(targetDir);
@@ -170,27 +153,6 @@ function isPathInside(targetPath: string, targetDir: string): boolean {
return resolvedTargetPath.startsWith(resolvedTargetDirWithSep);
}
-/**
- * Install skill from local path, GitHub, or Git URL
- */
-export async function installSkill(source: string, options: InstallOptions): Promise<void> {
- const folder = options.universal ? '.agent/skills' : '.claude/skills';
- const isProject = !options.global; // Default to project unless --global specified
- const targetDir = isProject
- ? join(process.cwd(), folder)
- : join(homedir(), folder);
-
- const location = isProject
- ? chalk.blue(`project (${folder})`)
- : chalk.dim(`global (~/${folder})`);
-
- const projectLocation = `./${folder}`;
- const globalLocation = `~/${folder}`;
-
- console.log(`Installing from: ${chalk.cyan(source)}`);
- console.log(`Location: ${location}`);
- if (isProject) {
- console.log(
```
This function is important because it defines how OpenSkills Tutorial: Universal Skill Loading for Coding Agents implements the patterns covered in this chapter.
@@ -200,11 +162,11 @@ This function is important because it defines how OpenSkills Tutorial: Universal
```mermaid
flowchart TD
- A[isGitUrl]
- B[getRepoName]
- C[expandPath]
+ A[SkillMetadata]
+ B[updateSkills]
+ C[updateSkillFromDir]
D[isPathInside]
- E[installSkill]
+ E[isLocalPath]
A --> B
B --> C
C --> D
diff --git a/tutorials/openskills-tutorial/03-installation-sources-and-trust-model.md b/tutorials/openskills-tutorial/03-installation-sources-and-trust-model.md
index 620169f9..7dcde3b6 100644
--- a/tutorials/openskills-tutorial/03-installation-sources-and-trust-model.md
+++ b/tutorials/openskills-tutorial/03-installation-sources-and-trust-model.md
@@ -27,170 +27,168 @@ You now have a trust model for safe skill installation.
Next: [Chapter 4: Sync and AGENTS.md Integration](04-sync-and-agents-md-integration.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `src/commands/install.ts`
-The `printPostInstallHints` function in [`src/commands/install.ts`](https://github.com/numman-ali/openskills/blob/HEAD/src/commands/install.ts) handles a key part of this chapter's functionality:
+The `isGitUrl` function in [`src/commands/install.ts`](https://github.com/numman-ali/openskills/blob/HEAD/src/commands/install.ts) handles a key part of this chapter's functionality:
```ts
- };
- await installFromLocal(localPath, targetDir, options, sourceInfo);
- printPostInstallHints(isProject);
- return;
- }
+ * Check if source is a git URL (SSH, git://, or HTTPS)
+ */
+function isGitUrl(source: string): boolean {
+ return (
+ source.startsWith('git@') ||
+ source.startsWith('git://') ||
+ source.startsWith('http://') ||
+ source.startsWith('https://') ||
+ source.endsWith('.git')
+ );
+}
- // Parse git source
- let repoUrl: string;
- let skillSubpath: string = '';
-
- if (isGitUrl(source)) {
- // Full git URL (SSH, HTTPS, git://)
- repoUrl = source;
- } else {
- // GitHub shorthand: owner/repo or owner/repo/skill-path
- const parts = source.split('/');
- if (parts.length === 2) {
- repoUrl = `https://github.com/${source}`;
- } else if (parts.length > 2) {
- repoUrl = `https://github.com/${parts[0]}/${parts[1]}`;
- skillSubpath = parts.slice(2).join('/');
- } else {
- console.error(chalk.red('Error: Invalid source format'));
- console.error('Expected: owner/repo, owner/repo/skill-name, git URL, or local path');
- process.exit(1);
- }
- }
+/**
+ * Extract repo name from a git URL
+ */
+function getRepoName(repoUrl: string): string | null {
+ const cleaned = repoUrl.replace(/\.git$/, '');
+ const lastPart = cleaned.split('/').pop();
+ if (!lastPart) return null;
+ const maybeRepo = lastPart.includes(':') ? lastPart.split(':').pop() : lastPart;
+ return maybeRepo || null;
+}
- // Clone and install from git
- const tempDir = join(homedir(), `.openskills-temp-${Date.now()}`);
- mkdirSync(tempDir, { recursive: true });
- const sourceInfo: InstallSourceInfo = {
+/**
+ * Expand ~ to home directory
+ */
+function expandPath(source: string): string {
+ if (source.startsWith('~/')) {
+ return join(homedir(), source.slice(2));
+ }
+ return resolve(source);
+}
```
This function is important because it defines how OpenSkills Tutorial: Universal Skill Loading for Coding Agents implements the patterns covered in this chapter.
### `src/commands/install.ts`
-The `installFromLocal` function in [`src/commands/install.ts`](https://github.com/numman-ali/openskills/blob/HEAD/src/commands/install.ts) handles a key part of this chapter's functionality:
+The `getRepoName` function in [`src/commands/install.ts`](https://github.com/numman-ali/openskills/blob/HEAD/src/commands/install.ts) handles a key part of this chapter's functionality:
```ts
- localRoot: localPath,
- };
- await installFromLocal(localPath, targetDir, options, sourceInfo);
- printPostInstallHints(isProject);
- return;
- }
+ * Extract repo name from a git URL
+ */
+function getRepoName(repoUrl: string): string | null {
+ const cleaned = repoUrl.replace(/\.git$/, '');
+ const lastPart = cleaned.split('/').pop();
+ if (!lastPart) return null;
+ const maybeRepo = lastPart.includes(':') ? lastPart.split(':').pop() : lastPart;
+ return maybeRepo || null;
+}
- // Parse git source
- let repoUrl: string;
- let skillSubpath: string = '';
-
- if (isGitUrl(source)) {
- // Full git URL (SSH, HTTPS, git://)
- repoUrl = source;
- } else {
- // GitHub shorthand: owner/repo or owner/repo/skill-path
- const parts = source.split('/');
- if (parts.length === 2) {
- repoUrl = `https://github.com/${source}`;
- } else if (parts.length > 2) {
- repoUrl = `https://github.com/${parts[0]}/${parts[1]}`;
- skillSubpath = parts.slice(2).join('/');
- } else {
- console.error(chalk.red('Error: Invalid source format'));
- console.error('Expected: owner/repo, owner/repo/skill-name, git URL, or local path');
- process.exit(1);
- }
+/**
+ * Expand ~ to home directory
+ */
+function expandPath(source: string): string {
+ if (source.startsWith('~/')) {
+ return join(homedir(), source.slice(2));
}
+ return resolve(source);
+}
+
+/**
+ * Ensure target path stays within target directory
+ */
+function isPathInside(targetPath: string, targetDir: string): boolean {
+ const resolvedTargetPath = resolve(targetPath);
+ const resolvedTargetDir = resolve(targetDir);
+ const resolvedTargetDirWithSep = resolvedTargetDir.endsWith(sep)
+ ? resolvedTargetDir
+ : resolvedTargetDir + sep;
+ return resolvedTargetPath.startsWith(resolvedTargetDirWithSep);
+}
- // Clone and install from git
- const tempDir = join(homedir(), `.openskills-temp-${Date.now()}`);
- mkdirSync(tempDir, { recursive: true });
```
This function is important because it defines how OpenSkills Tutorial: Universal Skill Loading for Coding Agents implements the patterns covered in this chapter.
### `src/commands/install.ts`
-The `installSingleLocalSkill` function in [`src/commands/install.ts`](https://github.com/numman-ali/openskills/blob/HEAD/src/commands/install.ts) handles a key part of this chapter's functionality:
+The `expandPath` function in [`src/commands/install.ts`](https://github.com/numman-ali/openskills/blob/HEAD/src/commands/install.ts) handles a key part of this chapter's functionality:
```ts
- // Single skill directory
- const isProject = targetDir.includes(process.cwd());
- await installSingleLocalSkill(localPath, targetDir, isProject, options, sourceInfo);
- } else {
- // Directory containing multiple skills
- await installFromRepo(localPath, targetDir, options, undefined, sourceInfo);
+ * Expand ~ to home directory
+ */
+function expandPath(source: string): string {
+ if (source.startsWith('~/')) {
+ return join(homedir(), source.slice(2));
}
+ return resolve(source);
}
/**
- * Install a single local skill directory
+ * Ensure target path stays within target directory
*/
-async function installSingleLocalSkill(
- skillDir: string,
- targetDir: string,
- isProject: boolean,
- options: InstallOptions,
- sourceInfo: InstallSourceInfo
-): Promise<void> {
- const skillMdPath = join(skillDir, 'SKILL.md');
- const content = readFileSync(skillMdPath, 'utf-8');
-
- if (!hasValidFrontmatter(content)) {
- console.error(chalk.red('Error: Invalid SKILL.md (missing YAML frontmatter)'));
- process.exit(1);
- }
-
- const skillName = basename(skillDir);
- const targetPath = join(targetDir, skillName);
+function isPathInside(targetPath: string, targetDir: string): boolean {
+ const resolvedTargetPath = resolve(targetPath);
+ const resolvedTargetDir = resolve(targetDir);
+ const resolvedTargetDirWithSep = resolvedTargetDir.endsWith(sep)
+ ? resolvedTargetDir
+ : resolvedTargetDir + sep;
+ return resolvedTargetPath.startsWith(resolvedTargetDirWithSep);
+}
- const shouldInstall = await warnIfConflict(skillName, targetPath, isProject, options.yes);
- if (!shouldInstall) {
+/**
+ * Install skill from local path, GitHub, or Git URL
+ */
+export async function installSkill(source: string, options: InstallOptions): Promise<void> {
+ const folder = options.universal ? '.agent/skills' : '.claude/skills';
+ const isProject = !options.global; // Default to project unless --global specified
+ const targetDir = isProject
+ ? join(process.cwd(), folder)
+ : join(homedir(), folder);
+
+ const location = isProject
```
This function is important because it defines how OpenSkills Tutorial: Universal Skill Loading for Coding Agents implements the patterns covered in this chapter.
### `src/commands/install.ts`
-The `installSpecificSkill` function in [`src/commands/install.ts`](https://github.com/numman-ali/openskills/blob/HEAD/src/commands/install.ts) handles a key part of this chapter's functionality:
+The `isPathInside` function in [`src/commands/install.ts`](https://github.com/numman-ali/openskills/blob/HEAD/src/commands/install.ts) handles a key part of this chapter's functionality:
```ts
-
- if (skillSubpath) {
- await installSpecificSkill(repoDir, skillSubpath, targetDir, isProject, options, sourceInfo);
- } else {
- const repoName = getRepoName(repoUrl);
- await installFromRepo(repoDir, targetDir, options, repoName || undefined, sourceInfo);
- }
- } finally {
- rmSync(tempDir, { recursive: true, force: true });
- }
-
- printPostInstallHints(isProject);
-}
-
-/**
- * Print post-install hints
+ * Ensure target path stays within target directory
*/
-function printPostInstallHints(isProject: boolean): void {
- console.log(`\n${chalk.dim('Read skill:')} ${chalk.cyan('npx openskills read <skill-name>')}`);
- if (isProject) {
- console.log(`${chalk.dim('Sync to AGENTS.md:')} ${chalk.cyan('npx openskills sync')}`);
- }
+function isPathInside(targetPath: string, targetDir: string): boolean {
+ const resolvedTargetPath = resolve(targetPath);
+ const resolvedTargetDir = resolve(targetDir);
+ const resolvedTargetDirWithSep = resolvedTargetDir.endsWith(sep)
+ ? resolvedTargetDir
+ : resolvedTargetDir + sep;
+ return resolvedTargetPath.startsWith(resolvedTargetDirWithSep);
}
/**
- * Install from local path (directory containing skills or single skill)
+ * Install skill from local path, GitHub, or Git URL
*/
-async function installFromLocal(
- localPath: string,
- targetDir: string,
- options: InstallOptions,
- sourceInfo: InstallSourceInfo
+export async function installSkill(source: string, options: InstallOptions): Promise<void> {
+ const folder = options.universal ? '.agent/skills' : '.claude/skills';
+ const isProject = !options.global; // Default to project unless --global specified
+ const targetDir = isProject
+ ? join(process.cwd(), folder)
+ : join(homedir(), folder);
+
+ const location = isProject
+ ? chalk.blue(`project (${folder})`)
+ : chalk.dim(`global (~/${folder})`);
+
+ const projectLocation = `./${folder}`;
+ const globalLocation = `~/${folder}`;
+
+ console.log(`Installing from: ${chalk.cyan(source)}`);
+ console.log(`Location: ${location}`);
+ if (isProject) {
+ console.log(
```
This function is important because it defines how OpenSkills Tutorial: Universal Skill Loading for Coding Agents implements the patterns covered in this chapter.
@@ -200,11 +198,11 @@ This function is important because it defines how OpenSkills Tutorial: Universal
```mermaid
flowchart TD
- A[printPostInstallHints]
- B[installFromLocal]
- C[installSingleLocalSkill]
- D[installSpecificSkill]
- E[installFromRepo]
+ A[isGitUrl]
+ B[getRepoName]
+ C[expandPath]
+ D[isPathInside]
+ E[installSkill]
A --> B
B --> C
C --> D
diff --git a/tutorials/openskills-tutorial/04-sync-and-agents-md-integration.md b/tutorials/openskills-tutorial/04-sync-and-agents-md-integration.md
index ab107962..db741381 100644
--- a/tutorials/openskills-tutorial/04-sync-and-agents-md-integration.md
+++ b/tutorials/openskills-tutorial/04-sync-and-agents-md-integration.md
@@ -26,168 +26,166 @@ You now know how to keep skill metadata synchronized and discoverable.
Next: [Chapter 5: Universal Mode and Multi-Agent Setups](05-universal-mode-and-multi-agent-setups.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `src/commands/install.ts`
-The `buildMetadataFromSource` function in [`src/commands/install.ts`](https://github.com/numman-ali/openskills/blob/HEAD/src/commands/install.ts) handles a key part of this chapter's functionality:
+The `printPostInstallHints` function in [`src/commands/install.ts`](https://github.com/numman-ali/openskills/blob/HEAD/src/commands/install.ts) handles a key part of this chapter's functionality:
```ts
- }
- cpSync(info.skillDir, info.targetPath, { recursive: true, dereference: true });
- writeSkillMetadata(info.targetPath, buildMetadataFromSource(sourceInfo, info.skillDir, repoDir));
-
- console.log(chalk.green(`✅ Installed: ${info.skillName}`));
- installedCount++;
+ };
+ await installFromLocal(localPath, targetDir, options, sourceInfo);
+ printPostInstallHints(isProject);
+ return;
}
- console.log(chalk.green(`\n✅ Installation complete: ${installedCount} skill(s) installed`));
-}
-
-function buildMetadataFromSource(
- sourceInfo: InstallSourceInfo,
- skillDir: string,
- repoDir: string
-): SkillSourceMetadata {
- if (sourceInfo.sourceType === 'local') {
- return buildLocalMetadata(sourceInfo, skillDir);
+ // Parse git source
+ let repoUrl: string;
+ let skillSubpath: string = '';
+
+ if (isGitUrl(source)) {
+ // Full git URL (SSH, HTTPS, git://)
+ repoUrl = source;
+ } else {
+ // GitHub shorthand: owner/repo or owner/repo/skill-path
+ const parts = source.split('/');
+ if (parts.length === 2) {
+ repoUrl = `https://github.com/${source}`;
+ } else if (parts.length > 2) {
+ repoUrl = `https://github.com/${parts[0]}/${parts[1]}`;
+ skillSubpath = parts.slice(2).join('/');
+ } else {
+ console.error(chalk.red('Error: Invalid source format'));
+ console.error('Expected: owner/repo, owner/repo/skill-name, git URL, or local path');
+ process.exit(1);
+ }
}
- const subpath = relative(repoDir, skillDir);
- const normalizedSubpath = subpath === '' ? '' : subpath;
- return buildGitMetadata(sourceInfo, normalizedSubpath);
-}
-function buildGitMetadata(sourceInfo: InstallSourceInfo, subpath: string): SkillSourceMetadata {
- return {
- source: sourceInfo.source,
- sourceType: 'git',
- repoUrl: sourceInfo.repoUrl,
- subpath,
- installedAt: new Date().toISOString(),
- };
+ // Clone and install from git
+ const tempDir = join(homedir(), `.openskills-temp-${Date.now()}`);
+ mkdirSync(tempDir, { recursive: true });
+ const sourceInfo: InstallSourceInfo = {
```
This function is important because it defines how OpenSkills Tutorial: Universal Skill Loading for Coding Agents implements the patterns covered in this chapter.
### `src/commands/install.ts`
-The `buildGitMetadata` function in [`src/commands/install.ts`](https://github.com/numman-ali/openskills/blob/HEAD/src/commands/install.ts) handles a key part of this chapter's functionality:
+The `installFromLocal` function in [`src/commands/install.ts`](https://github.com/numman-ali/openskills/blob/HEAD/src/commands/install.ts) handles a key part of this chapter's functionality:
```ts
+ localRoot: localPath,
+ };
+ await installFromLocal(localPath, targetDir, options, sourceInfo);
+ printPostInstallHints(isProject);
+ return;
}
- cpSync(skillDir, targetPath, { recursive: true, dereference: true });
- writeSkillMetadata(targetPath, buildGitMetadata(sourceInfo, skillSubpath));
-
- console.log(chalk.green(`✅ Installed: ${skillName}`));
- console.log(` Location: ${targetPath}`);
-}
-/**
- * Install from repository (with interactive selection unless -y flag)
- */
-async function installFromRepo(
- repoDir: string,
- targetDir: string,
- options: InstallOptions,
- repoName: string | undefined,
- sourceInfo: InstallSourceInfo
-): Promise<void> {
- const rootSkillPath = join(repoDir, 'SKILL.md');
- let skillInfos: Array<{
- skillDir: string;
- skillName: string;
- description: string;
- targetPath: string;
- size: number;
- }> = [];
-
- if (existsSync(rootSkillPath)) {
- const content = readFileSync(rootSkillPath, 'utf-8');
- if (!hasValidFrontmatter(content)) {
- console.error(chalk.red('Error: Invalid SKILL.md (missing YAML frontmatter)'));
+ // Parse git source
+ let repoUrl: string;
+ let skillSubpath: string = '';
+
+ if (isGitUrl(source)) {
+ // Full git URL (SSH, HTTPS, git://)
+ repoUrl = source;
+ } else {
+ // GitHub shorthand: owner/repo or owner/repo/skill-path
+ const parts = source.split('/');
+ if (parts.length === 2) {
+ repoUrl = `https://github.com/${source}`;
+ } else if (parts.length > 2) {
+ repoUrl = `https://github.com/${parts[0]}/${parts[1]}`;
+ skillSubpath = parts.slice(2).join('/');
+ } else {
+ console.error(chalk.red('Error: Invalid source format'));
+ console.error('Expected: owner/repo, owner/repo/skill-name, git URL, or local path');
process.exit(1);
+ }
+ }
+
+ // Clone and install from git
+ const tempDir = join(homedir(), `.openskills-temp-${Date.now()}`);
+ mkdirSync(tempDir, { recursive: true });
```
This function is important because it defines how OpenSkills Tutorial: Universal Skill Loading for Coding Agents implements the patterns covered in this chapter.
### `src/commands/install.ts`
-The `buildLocalMetadata` function in [`src/commands/install.ts`](https://github.com/numman-ali/openskills/blob/HEAD/src/commands/install.ts) handles a key part of this chapter's functionality:
+The `installSingleLocalSkill` function in [`src/commands/install.ts`](https://github.com/numman-ali/openskills/blob/HEAD/src/commands/install.ts) handles a key part of this chapter's functionality:
```ts
-
- cpSync(skillDir, targetPath, { recursive: true, dereference: true });
- writeSkillMetadata(targetPath, buildLocalMetadata(sourceInfo, skillDir));
-
- console.log(chalk.green(`✅ Installed: ${skillName}`));
- console.log(` Location: ${targetPath}`);
+ // Single skill directory
+ const isProject = targetDir.includes(process.cwd());
+ await installSingleLocalSkill(localPath, targetDir, isProject, options, sourceInfo);
+ } else {
+ // Directory containing multiple skills
+ await installFromRepo(localPath, targetDir, options, undefined, sourceInfo);
+ }
}
/**
- * Install specific skill from subpath (no interaction needed)
+ * Install a single local skill directory
*/
-async function installSpecificSkill(
- repoDir: string,
- skillSubpath: string,
+async function installSingleLocalSkill(
+ skillDir: string,
targetDir: string,
isProject: boolean,
options: InstallOptions,
sourceInfo: InstallSourceInfo
): Promise<void> {
- const skillDir = join(repoDir, skillSubpath);
const skillMdPath = join(skillDir, 'SKILL.md');
-
- if (!existsSync(skillMdPath)) {
- console.error(chalk.red(`Error: SKILL.md not found at ${skillSubpath}`));
- process.exit(1);
- }
-
- // Validate
const content = readFileSync(skillMdPath, 'utf-8');
+
if (!hasValidFrontmatter(content)) {
console.error(chalk.red('Error: Invalid SKILL.md (missing YAML frontmatter)'));
process.exit(1);
+ }
+
+ const skillName = basename(skillDir);
+ const targetPath = join(targetDir, skillName);
+
+ const shouldInstall = await warnIfConflict(skillName, targetPath, isProject, options.yes);
+ if (!shouldInstall) {
```
This function is important because it defines how OpenSkills Tutorial: Universal Skill Loading for Coding Agents implements the patterns covered in this chapter.
### `src/commands/install.ts`
-The `warnIfConflict` function in [`src/commands/install.ts`](https://github.com/numman-ali/openskills/blob/HEAD/src/commands/install.ts) handles a key part of this chapter's functionality:
+The `installSpecificSkill` function in [`src/commands/install.ts`](https://github.com/numman-ali/openskills/blob/HEAD/src/commands/install.ts) handles a key part of this chapter's functionality:
```ts
- const targetPath = join(targetDir, skillName);
- const shouldInstall = await warnIfConflict(skillName, targetPath, isProject, options.yes);
- if (!shouldInstall) {
- console.log(chalk.yellow(`Skipped: ${skillName}`));
- return;
- }
-
- mkdirSync(targetDir, { recursive: true });
- // Security: ensure target path stays within target directory
- if (!isPathInside(targetPath, targetDir)) {
- console.error(chalk.red(`Security error: Installation path outside target directory`));
- process.exit(1);
+ if (skillSubpath) {
+ await installSpecificSkill(repoDir, skillSubpath, targetDir, isProject, options, sourceInfo);
+ } else {
+ const repoName = getRepoName(repoUrl);
+ await installFromRepo(repoDir, targetDir, options, repoName || undefined, sourceInfo);
+ }
+ } finally {
+ rmSync(tempDir, { recursive: true, force: true });
}
- cpSync(skillDir, targetPath, { recursive: true, dereference: true });
- writeSkillMetadata(targetPath, buildLocalMetadata(sourceInfo, skillDir));
+ printPostInstallHints(isProject);
+}
- console.log(chalk.green(`✅ Installed: ${skillName}`));
- console.log(` Location: ${targetPath}`);
+/**
+ * Print post-install hints
+ */
+function printPostInstallHints(isProject: boolean): void {
+ console.log(`\n${chalk.dim('Read skill:')} ${chalk.cyan('npx openskills read <skill-name>')}`);
+ if (isProject) {
+ console.log(`${chalk.dim('Sync to AGENTS.md:')} ${chalk.cyan('npx openskills sync')}`);
+ }
}
/**
- * Install specific skill from subpath (no interaction needed)
+ * Install from local path (directory containing skills or single skill)
*/
-async function installSpecificSkill(
- repoDir: string,
- skillSubpath: string,
+async function installFromLocal(
+ localPath: string,
targetDir: string,
- isProject: boolean,
options: InstallOptions,
sourceInfo: InstallSourceInfo
```
@@ -199,11 +197,11 @@ This function is important because it defines how OpenSkills Tutorial: Universal
```mermaid
flowchart TD
- A[buildMetadataFromSource]
- B[buildGitMetadata]
- C[buildLocalMetadata]
- D[warnIfConflict]
- E[getDirectorySize]
+ A[printPostInstallHints]
+ B[installFromLocal]
+ C[installSingleLocalSkill]
+ D[installSpecificSkill]
+ E[installFromRepo]
A --> B
B --> C
C --> D
diff --git a/tutorials/openskills-tutorial/05-universal-mode-and-multi-agent-setups.md b/tutorials/openskills-tutorial/05-universal-mode-and-multi-agent-setups.md
index 317bceb5..1cc36db4 100644
--- a/tutorials/openskills-tutorial/05-universal-mode-and-multi-agent-setups.md
+++ b/tutorials/openskills-tutorial/05-universal-mode-and-multi-agent-setups.md
@@ -26,184 +26,182 @@ You now understand multi-agent layout strategy for stable cross-tool skill usage
Next: [Chapter 6: Skill Authoring and Packaging](06-skill-authoring-and-packaging.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `src/commands/install.ts`
-The `formatSize` function in [`src/commands/install.ts`](https://github.com/numman-ali/openskills/blob/HEAD/src/commands/install.ts) handles a key part of this chapter's functionality:
+The `buildMetadataFromSource` function in [`src/commands/install.ts`](https://github.com/numman-ali/openskills/blob/HEAD/src/commands/install.ts) handles a key part of this chapter's functionality:
```ts
- try {
- const choices = skillInfos.map((info) => ({
- name: `${chalk.bold(info.skillName.padEnd(25))} ${chalk.dim(formatSize(info.size))}`,
- value: info.skillName,
- description: info.description.slice(0, 80),
- checked: true, // Check all by default
- }));
-
- const selected = await checkbox({
- message: 'Select skills to install',
- choices,
- pageSize: 15,
- });
-
- if (selected.length === 0) {
- console.log(chalk.yellow('No skills selected. Installation cancelled.'));
- return;
- }
-
- skillsToInstall = skillInfos.filter((info) => selected.includes(info.skillName));
- } catch (error) {
- if (error instanceof ExitPromptError) {
- console.log(chalk.yellow('\n\nCancelled by user'));
- process.exit(0);
- }
- throw error;
}
+ cpSync(info.skillDir, info.targetPath, { recursive: true, dereference: true });
+ writeSkillMetadata(info.targetPath, buildMetadataFromSource(sourceInfo, info.skillDir, repoDir));
+
+ console.log(chalk.green(`✅ Installed: ${info.skillName}`));
+ installedCount++;
+ }
+
+ console.log(chalk.green(`\n✅ Installation complete: ${installedCount} skill(s) installed`));
+}
+
+function buildMetadataFromSource(
+ sourceInfo: InstallSourceInfo,
+ skillDir: string,
+ repoDir: string
+): SkillSourceMetadata {
+ if (sourceInfo.sourceType === 'local') {
+ return buildLocalMetadata(sourceInfo, skillDir);
}
+ const subpath = relative(repoDir, skillDir);
+ const normalizedSubpath = subpath === '' ? '' : subpath;
+ return buildGitMetadata(sourceInfo, normalizedSubpath);
+}
- // Install selected skills
- const isProject = targetDir.startsWith(process.cwd());
- let installedCount = 0;
+function buildGitMetadata(sourceInfo: InstallSourceInfo, subpath: string): SkillSourceMetadata {
+ return {
+ source: sourceInfo.source,
+ sourceType: 'git',
+ repoUrl: sourceInfo.repoUrl,
+ subpath,
+ installedAt: new Date().toISOString(),
+ };
```
This function is important because it defines how OpenSkills Tutorial: Universal Skill Loading for Coding Agents implements the patterns covered in this chapter.
### `src/commands/install.ts`
-The `InstallSourceInfo` interface in [`src/commands/install.ts`](https://github.com/numman-ali/openskills/blob/HEAD/src/commands/install.ts) handles a key part of this chapter's functionality:
+The `buildGitMetadata` function in [`src/commands/install.ts`](https://github.com/numman-ali/openskills/blob/HEAD/src/commands/install.ts) handles a key part of this chapter's functionality:
```ts
-import type { SkillSourceMetadata, SkillSourceType } from '../utils/skill-metadata.js';
-
-interface InstallSourceInfo {
- source: string;
- sourceType: SkillSourceType;
- repoUrl?: string;
- localRoot?: string;
-}
+ }
+ cpSync(skillDir, targetPath, { recursive: true, dereference: true });
+ writeSkillMetadata(targetPath, buildGitMetadata(sourceInfo, skillSubpath));
-/**
- * Check if source is a local path
- */
-function isLocalPath(source: string): boolean {
- return (
- source.startsWith('/') ||
- source.startsWith('./') ||
- source.startsWith('../') ||
- source.startsWith('~/')
- );
+ console.log(chalk.green(`✅ Installed: ${skillName}`));
+ console.log(` Location: ${targetPath}`);
}
/**
- * Check if source is a git URL (SSH, git://, or HTTPS)
+ * Install from repository (with interactive selection unless -y flag)
*/
-function isGitUrl(source: string): boolean {
- return (
- source.startsWith('git@') ||
- source.startsWith('git://') ||
- source.startsWith('http://') ||
- source.startsWith('https://') ||
- source.endsWith('.git')
- );
+async function installFromRepo(
+ repoDir: string,
+ targetDir: string,
+ options: InstallOptions,
+ repoName: string | undefined,
+ sourceInfo: InstallSourceInfo
+): Promise<void> {
+ const rootSkillPath = join(repoDir, 'SKILL.md');
+ let skillInfos: Array<{
+ skillDir: string;
+ skillName: string;
+ description: string;
+ targetPath: string;
+ size: number;
+ }> = [];
+
+ if (existsSync(rootSkillPath)) {
+ const content = readFileSync(rootSkillPath, 'utf-8');
+ if (!hasValidFrontmatter(content)) {
+ console.error(chalk.red('Error: Invalid SKILL.md (missing YAML frontmatter)'));
+ process.exit(1);
```
-This interface is important because it defines how OpenSkills Tutorial: Universal Skill Loading for Coding Agents implements the patterns covered in this chapter.
+This function is important because it defines how OpenSkills Tutorial: Universal Skill Loading for Coding Agents implements the patterns covered in this chapter.
-### `src/commands/sync.ts`
+### `src/commands/install.ts`
-The `syncAgentsMd` function in [`src/commands/sync.ts`](https://github.com/numman-ali/openskills/blob/HEAD/src/commands/sync.ts) handles a key part of this chapter's functionality:
+The `buildLocalMetadata` function in [`src/commands/install.ts`](https://github.com/numman-ali/openskills/blob/HEAD/src/commands/install.ts) handles a key part of this chapter's functionality:
```ts
- * Sync installed skills to a markdown file
- */
-export async function syncAgentsMd(options: SyncOptions = {}): Promise<void> {
- const outputPath = options.output || 'AGENTS.md';
- const outputName = basename(outputPath);
- // Validate output file is markdown
- if (!outputPath.endsWith('.md')) {
- console.error(chalk.red('Error: Output file must be a markdown file (.md)'));
- process.exit(1);
- }
-
- // Create file if it doesn't exist
- if (!existsSync(outputPath)) {
- const dir = dirname(outputPath);
- if (dir && dir !== '.' && !existsSync(dir)) {
- mkdirSync(dir, { recursive: true });
- }
- writeFileSync(outputPath, `# ${outputName.replace('.md', '')}\n\n`);
- console.log(chalk.dim(`Created ${outputPath}`));
- }
+ cpSync(skillDir, targetPath, { recursive: true, dereference: true });
+ writeSkillMetadata(targetPath, buildLocalMetadata(sourceInfo, skillDir));
- let skills = findAllSkills();
+ console.log(chalk.green(`✅ Installed: ${skillName}`));
+ console.log(` Location: ${targetPath}`);
+}
- if (skills.length === 0) {
- console.log('No skills installed. Install skills first:');
- console.log(` ${chalk.cyan('npx openskills install anthropics/skills --project')}`);
- return;
+/**
+ * Install specific skill from subpath (no interaction needed)
+ */
+async function installSpecificSkill(
+ repoDir: string,
+ skillSubpath: string,
+ targetDir: string,
+ isProject: boolean,
+ options: InstallOptions,
+ sourceInfo: InstallSourceInfo
+): Promise<void> {
+ const skillDir = join(repoDir, skillSubpath);
+ const skillMdPath = join(skillDir, 'SKILL.md');
+
+ if (!existsSync(skillMdPath)) {
+ console.error(chalk.red(`Error: SKILL.md not found at ${skillSubpath}`));
+ process.exit(1);
}
- // Interactive mode by default (unless -y flag)
- if (!options.yes) {
+ // Validate
+ const content = readFileSync(skillMdPath, 'utf-8');
+ if (!hasValidFrontmatter(content)) {
+ console.error(chalk.red('Error: Invalid SKILL.md (missing YAML frontmatter)'));
+ process.exit(1);
```
This function is important because it defines how OpenSkills Tutorial: Universal Skill Loading for Coding Agents implements the patterns covered in this chapter.
-### `src/commands/sync.ts`
+### `src/commands/install.ts`
-The `SyncOptions` interface in [`src/commands/sync.ts`](https://github.com/numman-ali/openskills/blob/HEAD/src/commands/sync.ts) handles a key part of this chapter's functionality:
+The `warnIfConflict` function in [`src/commands/install.ts`](https://github.com/numman-ali/openskills/blob/HEAD/src/commands/install.ts) handles a key part of this chapter's functionality:
```ts
-import type { Skill } from '../types.js';
+ const targetPath = join(targetDir, skillName);
-export interface SyncOptions {
- yes?: boolean;
- output?: string;
-}
-
-/**
- * Sync installed skills to a markdown file
- */
-export async function syncAgentsMd(options: SyncOptions = {}): Promise<void> {
- const outputPath = options.output || 'AGENTS.md';
- const outputName = basename(outputPath);
+ const shouldInstall = await warnIfConflict(skillName, targetPath, isProject, options.yes);
+ if (!shouldInstall) {
+ console.log(chalk.yellow(`Skipped: ${skillName}`));
+ return;
+ }
- // Validate output file is markdown
- if (!outputPath.endsWith('.md')) {
- console.error(chalk.red('Error: Output file must be a markdown file (.md)'));
+ mkdirSync(targetDir, { recursive: true });
+ // Security: ensure target path stays within target directory
+ if (!isPathInside(targetPath, targetDir)) {
+ console.error(chalk.red(`Security error: Installation path outside target directory`));
process.exit(1);
}
- // Create file if it doesn't exist
- if (!existsSync(outputPath)) {
- const dir = dirname(outputPath);
- if (dir && dir !== '.' && !existsSync(dir)) {
- mkdirSync(dir, { recursive: true });
- }
- writeFileSync(outputPath, `# ${outputName.replace('.md', '')}\n\n`);
- console.log(chalk.dim(`Created ${outputPath}`));
- }
+ cpSync(skillDir, targetPath, { recursive: true, dereference: true });
+ writeSkillMetadata(targetPath, buildLocalMetadata(sourceInfo, skillDir));
- let skills = findAllSkills();
+ console.log(chalk.green(`✅ Installed: ${skillName}`));
+ console.log(` Location: ${targetPath}`);
+}
+/**
+ * Install specific skill from subpath (no interaction needed)
+ */
+async function installSpecificSkill(
+ repoDir: string,
+ skillSubpath: string,
+ targetDir: string,
+ isProject: boolean,
+ options: InstallOptions,
+ sourceInfo: InstallSourceInfo
```
-This interface is important because it defines how OpenSkills Tutorial: Universal Skill Loading for Coding Agents implements the patterns covered in this chapter.
+This function is important because it defines how OpenSkills Tutorial: Universal Skill Loading for Coding Agents implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[formatSize]
- B[InstallSourceInfo]
- C[syncAgentsMd]
- D[SyncOptions]
- E[updateSkills]
+ A[buildMetadataFromSource]
+ B[buildGitMetadata]
+ C[buildLocalMetadata]
+ D[warnIfConflict]
+ E[getDirectorySize]
A --> B
B --> C
C --> D
diff --git a/tutorials/openskills-tutorial/06-skill-authoring-and-packaging.md b/tutorials/openskills-tutorial/06-skill-authoring-and-packaging.md
index f4aa9ec8..adc37559 100644
--- a/tutorials/openskills-tutorial/06-skill-authoring-and-packaging.md
+++ b/tutorials/openskills-tutorial/06-skill-authoring-and-packaging.md
@@ -26,117 +26,127 @@ You now have a quality baseline for authoring reusable skills.
Next: [Chapter 7: Updates, Versioning, and Governance](07-updates-versioning-and-governance.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/commands/update.ts`
+### `src/commands/install.ts`
-The `updateSkillFromDir` function in [`src/commands/update.ts`](https://github.com/numman-ali/openskills/blob/HEAD/src/commands/update.ts) handles a key part of this chapter's functionality:
+The `formatSize` function in [`src/commands/install.ts`](https://github.com/numman-ali/openskills/blob/HEAD/src/commands/install.ts) handles a key part of this chapter's functionality:
```ts
- continue;
+ try {
+ const choices = skillInfos.map((info) => ({
+ name: `${chalk.bold(info.skillName.padEnd(25))} ${chalk.dim(formatSize(info.size))}`,
+ value: info.skillName,
+ description: info.description.slice(0, 80),
+ checked: true, // Check all by default
+ }));
+
+ const selected = await checkbox({
+ message: 'Select skills to install',
+ choices,
+ pageSize: 15,
+ });
+
+ if (selected.length === 0) {
+ console.log(chalk.yellow('No skills selected. Installation cancelled.'));
+ return;
}
- updateSkillFromDir(skill.path, localPath);
- writeSkillMetadata(skill.path, { ...metadata, installedAt: new Date().toISOString() });
- console.log(chalk.green(`✅ Updated: ${skill.name}`));
- updated++;
- continue;
- }
- if (!metadata.repoUrl) {
- console.log(chalk.yellow(`Skipped: ${skill.name} (missing repo URL metadata)`));
- missingRepoUrl.push(skill.name);
- skipped++;
- continue;
+ skillsToInstall = skillInfos.filter((info) => selected.includes(info.skillName));
+ } catch (error) {
+ if (error instanceof ExitPromptError) {
+ console.log(chalk.yellow('\n\nCancelled by user'));
+ process.exit(0);
+ }
+ throw error;
}
+ }
- const tempDir = join(homedir(), `.openskills-temp-${Date.now()}`);
- mkdirSync(tempDir, { recursive: true });
-
- const spinner = ora(`Updating ${skill.name}...`).start();
- try {
- execSync(`git clone --depth 1 --quiet "${metadata.repoUrl}" "${tempDir}/repo"`, { stdio: 'pipe' });
- const repoDir = join(tempDir, 'repo');
- const subpath = metadata.subpath && metadata.subpath !== '.' ? metadata.subpath : '';
- const sourceDir = subpath ? join(repoDir, subpath) : repoDir;
-
- if (!existsSync(join(sourceDir, 'SKILL.md'))) {
- spinner.fail(`SKILL.md missing for ${skill.name}`);
- console.log(chalk.yellow(`Skipped: ${skill.name} (SKILL.md not found in repo at ${subpath || '.'})`));
- missingRepoSkillFile.push({ name: skill.name, subpath: subpath || '.' });
- skipped++;
- continue;
+ // Install selected skills
+ const isProject = targetDir.startsWith(process.cwd());
+ let installedCount = 0;
```
This function is important because it defines how OpenSkills Tutorial: Universal Skill Loading for Coding Agents implements the patterns covered in this chapter.
-### `src/commands/update.ts`
+### `src/commands/install.ts`
-The `isPathInside` function in [`src/commands/update.ts`](https://github.com/numman-ali/openskills/blob/HEAD/src/commands/update.ts) handles a key part of this chapter's functionality:
+The `InstallSourceInfo` interface in [`src/commands/install.ts`](https://github.com/numman-ali/openskills/blob/HEAD/src/commands/install.ts) handles a key part of this chapter's functionality:
```ts
- mkdirSync(targetDir, { recursive: true });
+import type { SkillSourceMetadata, SkillSourceType } from '../utils/skill-metadata.js';
- if (!isPathInside(targetPath, targetDir)) {
- console.error(chalk.red('Security error: Installation path outside target directory'));
- process.exit(1);
- }
-
- rmSync(targetPath, { recursive: true, force: true });
- cpSync(sourceDir, targetPath, { recursive: true, dereference: true });
+interface InstallSourceInfo {
+ source: string;
+ sourceType: SkillSourceType;
+ repoUrl?: string;
+ localRoot?: string;
}
-function isPathInside(targetPath: string, targetDir: string): boolean {
- const resolvedTargetPath = resolve(targetPath);
- const resolvedTargetDir = resolve(targetDir);
- const resolvedTargetDirWithSep = resolvedTargetDir.endsWith(sep)
- ? resolvedTargetDir
- : resolvedTargetDir + sep;
- return resolvedTargetPath.startsWith(resolvedTargetDirWithSep);
+/**
+ * Check if source is a local path
+ */
+function isLocalPath(source: string): boolean {
+ return (
+ source.startsWith('/') ||
+ source.startsWith('./') ||
+ source.startsWith('../') ||
+ source.startsWith('~/')
+ );
}
+/**
+ * Check if source is a git URL (SSH, git://, or HTTPS)
+ */
+function isGitUrl(source: string): boolean {
+ return (
+ source.startsWith('git@') ||
+ source.startsWith('git://') ||
+ source.startsWith('http://') ||
+ source.startsWith('https://') ||
+ source.endsWith('.git')
+ );
```
-This function is important because it defines how OpenSkills Tutorial: Universal Skill Loading for Coding Agents implements the patterns covered in this chapter.
+This interface is important because it defines how OpenSkills Tutorial: Universal Skill Loading for Coding Agents implements the patterns covered in this chapter.
-### `src/commands/manage.ts`
+### `src/commands/list.ts`
-The `manageSkills` function in [`src/commands/manage.ts`](https://github.com/numman-ali/openskills/blob/HEAD/src/commands/manage.ts) handles a key part of this chapter's functionality:
+The `listSkills` function in [`src/commands/list.ts`](https://github.com/numman-ali/openskills/blob/HEAD/src/commands/list.ts) handles a key part of this chapter's functionality:
```ts
- * Interactively manage (remove) installed skills
+ * List all installed skills
*/
-export async function manageSkills(): Promise<void> {
+export function listSkills(): void {
+ console.log(chalk.bold('Available Skills:\n'));
+
const skills = findAllSkills();
if (skills.length === 0) {
- console.log('No skills installed.');
+ console.log('No skills installed.\n');
+ console.log('Install skills:');
+ console.log(` ${chalk.cyan('npx openskills install anthropics/skills')} ${chalk.dim('# Project (default)')}`);
+ console.log(` ${chalk.cyan('npx openskills install owner/skill --global')} ${chalk.dim('# Global (advanced)')}`);
return;
}
- try {
- // Sort: project first
- const sorted = skills.sort((a, b) => {
- if (a.location !== b.location) {
- return a.location === 'project' ? -1 : 1;
- }
- return a.name.localeCompare(b.name);
- });
-
- const choices = sorted.map((skill) => ({
- name: `${chalk.bold(skill.name.padEnd(25))} ${skill.location === 'project' ? chalk.blue('(project)') : chalk.dim('(global)')}`,
- value: skill.name,
- checked: false, // Nothing checked by default
- }));
-
- const toRemove = await checkbox({
- message: 'Select skills to remove',
- choices,
- pageSize: 15,
- });
-
- if (toRemove.length === 0) {
+ // Sort: project skills first, then global, alphabetically within each
+ const sorted = skills.sort((a, b) => {
+ if (a.location !== b.location) {
+ return a.location === 'project' ? -1 : 1;
+ }
+ return a.name.localeCompare(b.name);
+ });
+
+ // Display with inline location labels
+ for (const skill of sorted) {
+ const locationLabel = skill.location === 'project'
+ ? chalk.blue('(project)')
+ : chalk.dim('(global)');
+
+ console.log(` ${chalk.bold(skill.name.padEnd(25))} ${locationLabel}`);
+ console.log(` ${chalk.dim(skill.description)}\n`);
+ }
```
This function is important because it defines how OpenSkills Tutorial: Universal Skill Loading for Coding Agents implements the patterns covered in this chapter.
@@ -187,9 +197,9 @@ This function is important because it defines how OpenSkills Tutorial: Universal
```mermaid
flowchart TD
- A[updateSkillFromDir]
- B[isPathInside]
- C[manageSkills]
+ A[formatSize]
+ B[InstallSourceInfo]
+ C[listSkills]
D[parseCurrentSkills]
E[generateSkillsXml]
A --> B
diff --git a/tutorials/openskills-tutorial/07-updates-versioning-and-governance.md b/tutorials/openskills-tutorial/07-updates-versioning-and-governance.md
index f8d6b99e..6f9cd494 100644
--- a/tutorials/openskills-tutorial/07-updates-versioning-and-governance.md
+++ b/tutorials/openskills-tutorial/07-updates-versioning-and-governance.md
@@ -27,8 +27,6 @@ You now have a lifecycle process for maintaining shared skill repositories.
Next: [Chapter 8: Production Security and Operations](08-production-security-and-operations.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `src/utils/agents-md.ts`
@@ -109,84 +107,53 @@ export function removeSkillsSection(content: string): string {
This function is important because it defines how OpenSkills Tutorial: Universal Skill Loading for Coding Agents implements the patterns covered in this chapter.
-### `src/utils/skills.ts`
+### `src/utils/dirs.ts`
-The `isDirectoryOrSymlinkToDirectory` function in [`src/utils/skills.ts`](https://github.com/numman-ali/openskills/blob/HEAD/src/utils/skills.ts) handles a key part of this chapter's functionality:
+The `getSkillsDir` function in [`src/utils/dirs.ts`](https://github.com/numman-ali/openskills/blob/HEAD/src/utils/dirs.ts) handles a key part of this chapter's functionality:
```ts
- * Check if a directory entry is a directory or a symlink pointing to a directory
+ * Get skills directory path
*/
-function isDirectoryOrSymlinkToDirectory(entry: Dirent, parentDir: string): boolean {
- if (entry.isDirectory()) {
- return true;
- }
- if (entry.isSymbolicLink()) {
- try {
- const fullPath = join(parentDir, entry.name);
- const stats = statSync(fullPath); // statSync follows symlinks
- return stats.isDirectory();
- } catch {
- // Broken symlink or permission error
- return false;
- }
- }
- return false;
+export function getSkillsDir(projectLocal: boolean = false, universal: boolean = false): string {
+ const folder = universal ? '.agent/skills' : '.claude/skills';
+ return projectLocal
+ ? join(process.cwd(), folder)
+ : join(homedir(), folder);
}
/**
- * Find all installed skills across directories
+ * Get all searchable skill directories in priority order
+ * Priority: project .agent > global .agent > project .claude > global .claude
*/
-export function findAllSkills(): Skill[] {
- const skills: Skill[] = [];
- const seen = new Set<string>();
- const dirs = getSearchDirs();
-
- for (const dir of dirs) {
- if (!existsSync(dir)) continue;
-
- const entries = readdirSync(dir, { withFileTypes: true });
+export function getSearchDirs(): string[] {
+ return [
+ join(process.cwd(), '.agent/skills'), // 1. Project universal (.agent)
+ join(homedir(), '.agent/skills'), // 2. Global universal (.agent)
+ join(process.cwd(), '.claude/skills'), // 3. Project claude
+ join(homedir(), '.claude/skills'), // 4. Global claude
+ ];
+}
```
This function is important because it defines how OpenSkills Tutorial: Universal Skill Loading for Coding Agents implements the patterns covered in this chapter.
-### `src/utils/skills.ts`
+### `src/utils/dirs.ts`
-The `findAllSkills` function in [`src/utils/skills.ts`](https://github.com/numman-ali/openskills/blob/HEAD/src/utils/skills.ts) handles a key part of this chapter's functionality:
+The `getSearchDirs` function in [`src/utils/dirs.ts`](https://github.com/numman-ali/openskills/blob/HEAD/src/utils/dirs.ts) handles a key part of this chapter's functionality:
```ts
- * Find all installed skills across directories
+ * Priority: project .agent > global .agent > project .claude > global .claude
*/
-export function findAllSkills(): Skill[] {
- const skills: Skill[] = [];
- const seen = new Set<string>();
- const dirs = getSearchDirs();
-
- for (const dir of dirs) {
- if (!existsSync(dir)) continue;
-
- const entries = readdirSync(dir, { withFileTypes: true });
-
- for (const entry of entries) {
- if (isDirectoryOrSymlinkToDirectory(entry, dir)) {
- // Deduplicate: only add if we haven't seen this skill name yet
- if (seen.has(entry.name)) continue;
-
- const skillPath = join(dir, entry.name, 'SKILL.md');
- if (existsSync(skillPath)) {
- const content = readFileSync(skillPath, 'utf-8');
- const isProjectLocal = dir.includes(process.cwd());
-
- skills.push({
- name: entry.name,
- description: extractYamlField(content, 'description'),
- location: isProjectLocal ? 'project' : 'global',
- path: join(dir, entry.name),
- });
-
- seen.add(entry.name);
- }
- }
+export function getSearchDirs(): string[] {
+ return [
+ join(process.cwd(), '.agent/skills'), // 1. Project universal (.agent)
+ join(homedir(), '.agent/skills'), // 2. Global universal (.agent)
+ join(process.cwd(), '.claude/skills'), // 3. Project claude
+ join(homedir(), '.claude/skills'), // 4. Global claude
+ ];
+}
+
```
This function is important because it defines how OpenSkills Tutorial: Universal Skill Loading for Coding Agents implements the patterns covered in this chapter.
@@ -198,9 +165,9 @@ This function is important because it defines how OpenSkills Tutorial: Universal
flowchart TD
A[replaceSkillsSection]
B[removeSkillsSection]
- C[isDirectoryOrSymlinkToDirectory]
- D[findAllSkills]
- E[findSkill]
+ C[getSkillsDir]
+ D[getSearchDirs]
+ E[isDirectoryOrSymlinkToDirectory]
A --> B
B --> C
C --> D
diff --git a/tutorials/openskills-tutorial/08-production-security-and-operations.md b/tutorials/openskills-tutorial/08-production-security-and-operations.md
index b5c3f8db..f390756d 100644
--- a/tutorials/openskills-tutorial/08-production-security-and-operations.md
+++ b/tutorials/openskills-tutorial/08-production-security-and-operations.md
@@ -24,102 +24,76 @@ This chapter defines the baseline for operating OpenSkills at team scale.
You now have an operations baseline for enterprise-grade skill distribution.
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/utils/skill-metadata.ts`
+### `src/utils/skills.ts`
-The `readSkillMetadata` function in [`src/utils/skill-metadata.ts`](https://github.com/numman-ali/openskills/blob/HEAD/src/utils/skill-metadata.ts) handles a key part of this chapter's functionality:
+The `findAllSkills` function in [`src/utils/skills.ts`](https://github.com/numman-ali/openskills/blob/HEAD/src/utils/skills.ts) handles a key part of this chapter's functionality:
```ts
-}
-
-export function readSkillMetadata(skillDir: string): SkillSourceMetadata | null {
- const metadataPath = join(skillDir, SKILL_METADATA_FILE);
- if (!existsSync(metadataPath)) return null;
-
- try {
- const raw = readFileSync(metadataPath, 'utf-8');
- return JSON.parse(raw) as SkillSourceMetadata;
- } catch {
- return null;
- }
-}
-
-export function writeSkillMetadata(skillDir: string, metadata: SkillSourceMetadata): void {
- const metadataPath = join(skillDir, SKILL_METADATA_FILE);
- const payload = {
- ...metadata,
- installedAt: metadata.installedAt || new Date().toISOString(),
- };
- writeFileSync(metadataPath, JSON.stringify(payload, null, 2));
-}
-
-```
-
-This function is important because it defines how OpenSkills Tutorial: Universal Skill Loading for Coding Agents implements the patterns covered in this chapter.
-
-### `src/utils/skill-metadata.ts`
-
-The `writeSkillMetadata` function in [`src/utils/skill-metadata.ts`](https://github.com/numman-ali/openskills/blob/HEAD/src/utils/skill-metadata.ts) handles a key part of this chapter's functionality:
-
-```ts
-}
-
-export function writeSkillMetadata(skillDir: string, metadata: SkillSourceMetadata): void {
- const metadataPath = join(skillDir, SKILL_METADATA_FILE);
- const payload = {
- ...metadata,
- installedAt: metadata.installedAt || new Date().toISOString(),
- };
- writeFileSync(metadataPath, JSON.stringify(payload, null, 2));
-}
-
+ * Find all installed skills across directories
+ */
+export function findAllSkills(): Skill[] {
+ const skills: Skill[] = [];
+ const seen = new Set<string>();
+ const dirs = getSearchDirs();
+
+ for (const dir of dirs) {
+ if (!existsSync(dir)) continue;
+
+ const entries = readdirSync(dir, { withFileTypes: true });
+
+ for (const entry of entries) {
+ if (isDirectoryOrSymlinkToDirectory(entry, dir)) {
+ // Deduplicate: only add if we haven't seen this skill name yet
+ if (seen.has(entry.name)) continue;
+
+ const skillPath = join(dir, entry.name, 'SKILL.md');
+ if (existsSync(skillPath)) {
+ const content = readFileSync(skillPath, 'utf-8');
+ const isProjectLocal = dir.includes(process.cwd());
+
+ skills.push({
+ name: entry.name,
+ description: extractYamlField(content, 'description'),
+ location: isProjectLocal ? 'project' : 'global',
+ path: join(dir, entry.name),
+ });
+
+ seen.add(entry.name);
+ }
+ }
```
This function is important because it defines how OpenSkills Tutorial: Universal Skill Loading for Coding Agents implements the patterns covered in this chapter.
-### `src/utils/skill-metadata.ts`
+### `src/utils/skills.ts`
-The `SkillSourceMetadata` interface in [`src/utils/skill-metadata.ts`](https://github.com/numman-ali/openskills/blob/HEAD/src/utils/skill-metadata.ts) handles a key part of this chapter's functionality:
+The `findSkill` function in [`src/utils/skills.ts`](https://github.com/numman-ali/openskills/blob/HEAD/src/utils/skills.ts) handles a key part of this chapter's functionality:
```ts
-export type SkillSourceType = 'git' | 'github' | 'local';
-
-export interface SkillSourceMetadata {
- source: string;
- sourceType: SkillSourceType;
- repoUrl?: string;
- subpath?: string;
- localPath?: string;
- installedAt: string;
-}
-
-export function readSkillMetadata(skillDir: string): SkillSourceMetadata | null {
- const metadataPath = join(skillDir, SKILL_METADATA_FILE);
- if (!existsSync(metadataPath)) return null;
-
- try {
- const raw = readFileSync(metadataPath, 'utf-8');
- return JSON.parse(raw) as SkillSourceMetadata;
- } catch {
- return null;
+ * Find specific skill by name
+ */
+export function findSkill(skillName: string): SkillLocation | null {
+ const dirs = getSearchDirs();
+
+ for (const dir of dirs) {
+ const skillPath = join(dir, skillName, 'SKILL.md');
+ if (existsSync(skillPath)) {
+ return {
+ path: skillPath,
+ baseDir: join(dir, skillName),
+ source: dir,
+ };
+ }
}
-}
-export function writeSkillMetadata(skillDir: string, metadata: SkillSourceMetadata): void {
- const metadataPath = join(skillDir, SKILL_METADATA_FILE);
- const payload = {
- ...metadata,
- installedAt: metadata.installedAt || new Date().toISOString(),
- };
- writeFileSync(metadataPath, JSON.stringify(payload, null, 2));
+ return null;
}
```
-This interface is important because it defines how OpenSkills Tutorial: Universal Skill Loading for Coding Agents implements the patterns covered in this chapter.
+This function is important because it defines how OpenSkills Tutorial: Universal Skill Loading for Coding Agents implements the patterns covered in this chapter.
### `src/commands/read.ts`
@@ -162,16 +136,57 @@ export function readSkill(skillNames: string[] | string): void {
This function is important because it defines how OpenSkills Tutorial: Universal Skill Loading for Coding Agents implements the patterns covered in this chapter.
+### `src/commands/manage.ts`
+
+The `manageSkills` function in [`src/commands/manage.ts`](https://github.com/numman-ali/openskills/blob/HEAD/src/commands/manage.ts) handles a key part of this chapter's functionality:
+
+```ts
+ * Interactively manage (remove) installed skills
+ */
+export async function manageSkills(): Promise<void> {
+ const skills = findAllSkills();
+
+ if (skills.length === 0) {
+ console.log('No skills installed.');
+ return;
+ }
+
+ try {
+ // Sort: project first
+ const sorted = skills.sort((a, b) => {
+ if (a.location !== b.location) {
+ return a.location === 'project' ? -1 : 1;
+ }
+ return a.name.localeCompare(b.name);
+ });
+
+ const choices = sorted.map((skill) => ({
+ name: `${chalk.bold(skill.name.padEnd(25))} ${skill.location === 'project' ? chalk.blue('(project)') : chalk.dim('(global)')}`,
+ value: skill.name,
+ checked: false, // Nothing checked by default
+ }));
+
+ const toRemove = await checkbox({
+ message: 'Select skills to remove',
+ choices,
+ pageSize: 15,
+ });
+
+ if (toRemove.length === 0) {
+```
+
+This function is important because it defines how OpenSkills Tutorial: Universal Skill Loading for Coding Agents implements the patterns covered in this chapter.
+
## How These Components Connect
```mermaid
flowchart TD
- A[readSkillMetadata]
- B[writeSkillMetadata]
- C[SkillSourceMetadata]
- D[readSkill]
- E[getSkillsDir]
+ A[findAllSkills]
+ B[findSkill]
+ C[readSkill]
+ D[manageSkills]
+ E[readSkillMetadata]
A --> B
B --> C
C --> D
diff --git a/tutorials/openspec-tutorial/01-getting-started-and-opsx-basics.md b/tutorials/openspec-tutorial/01-getting-started-and-opsx-basics.md
index 9537d66a..e0b80380 100644
--- a/tutorials/openspec-tutorial/01-getting-started-and-opsx-basics.md
+++ b/tutorials/openspec-tutorial/01-getting-started-and-opsx-basics.md
@@ -64,8 +64,6 @@ You now have a working OpenSpec environment with the core workflow entry points.
Next: [Chapter 2: Artifact Graph and Change Lifecycle](02-artifact-graph-and-change-lifecycle.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `scripts/postinstall.js`
diff --git a/tutorials/openspec-tutorial/02-artifact-graph-and-change-lifecycle.md b/tutorials/openspec-tutorial/02-artifact-graph-and-change-lifecycle.md
index ced03766..19557414 100644
--- a/tutorials/openspec-tutorial/02-artifact-graph-and-change-lifecycle.md
+++ b/tutorials/openspec-tutorial/02-artifact-graph-and-change-lifecycle.md
@@ -60,170 +60,168 @@ You now have a working model for how artifacts evolve from intent to archived be
Next: [Chapter 3: Command Surface and Agent Workflows](03-command-surface-and-agent-workflows.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/commands/schema.ts`
+### `src/commands/config.ts`
-The `registerSchemaCommand` function in [`src/commands/schema.ts`](https://github.com/Fission-AI/OpenSpec/blob/HEAD/src/commands/schema.ts) handles a key part of this chapter's functionality:
+The `registerConfigCommand` function in [`src/commands/config.ts`](https://github.com/Fission-AI/OpenSpec/blob/HEAD/src/commands/config.ts) handles a key part of this chapter's functionality:
```ts
- * Register the schema command and all its subcommands.
+ * @param program - The Commander program instance
*/
-export function registerSchemaCommand(program: Command): void {
- const schemaCmd = program
- .command('schema')
- .description('Manage workflow schemas [experimental]');
-
- // Experimental warning
- schemaCmd.hook('preAction', () => {
- console.error('Note: Schema commands are experimental and may change.');
- });
-
- // schema which
- schemaCmd
- .command('which [name]')
- .description('Show where a schema resolves from')
+export function registerConfigCommand(program: Command): void {
+ const configCmd = program
+ .command('config')
+ .description('View and modify global OpenSpec configuration')
+ .option('--scope <scope>', 'Config scope (only "global" supported currently)')
+ .hook('preAction', (thisCommand) => {
+ const opts = thisCommand.opts();
+ if (opts.scope && opts.scope !== 'global') {
+ console.error('Error: Project-local config is not yet implemented');
+ process.exit(1);
+ }
+ });
+
+ // config path
+ configCmd
+ .command('path')
+ .description('Show config file location')
+ .action(() => {
+ console.log(getGlobalConfigPath());
+ });
+
+ // config list
+ configCmd
+ .command('list')
+ .description('Show all current settings')
.option('--json', 'Output as JSON')
- .option('--all', 'List all schemas with their resolution sources')
- .action(async (name?: string, options?: { json?: boolean; all?: boolean }) => {
- try {
- const projectRoot = process.cwd();
-
- if (options?.all) {
- // List all schemas
- const schemas = getAllSchemasWithResolution(projectRoot);
-
- if (options?.json) {
- console.log(JSON.stringify(schemas, null, 2));
- } else {
- if (schemas.length === 0) {
- console.log('No schemas found.');
- return;
+ .action((options: { json?: boolean }) => {
+ const config = getGlobalConfig();
+
+ if (options.json) {
```
This function is important because it defines how OpenSpec Tutorial: Spec-Driven Workflows for AI Coding Agents implements the patterns covered in this chapter.
-### `src/commands/schema.ts`
+### `src/commands/config.ts`
-The `createDefaultTemplate` function in [`src/commands/schema.ts`](https://github.com/Fission-AI/OpenSpec/blob/HEAD/src/commands/schema.ts) handles a key part of this chapter's functionality:
+The `ProfileState` interface in [`src/commands/config.ts`](https://github.com/Fission-AI/OpenSpec/blob/HEAD/src/commands/config.ts) handles a key part of this chapter's functionality:
```ts
+type ProfileAction = 'both' | 'delivery' | 'workflows' | 'keep';
+
+interface ProfileState {
+ profile: Profile;
+ delivery: Delivery;
+ workflows: string[];
+}
+
+interface ProfileStateDiff {
+ hasChanges: boolean;
+ lines: string[];
+}
- // Create default template content
- const templateContent = createDefaultTemplate(artifact.id);
- fs.writeFileSync(templatePath, templateContent);
- }
-
- // Update config if --default
- if (options?.default) {
- const configPath = path.join(projectRoot, 'openspec', 'config.yaml');
-
- if (fs.existsSync(configPath)) {
- const { parse: parseYaml, stringify: stringifyYaml2 } = await import('yaml');
- const configContent = fs.readFileSync(configPath, 'utf-8');
- const config = parseYaml(configContent) || {};
- config.defaultSchema = name;
- fs.writeFileSync(configPath, stringifyYaml2(config));
- } else {
- // Create config file
- const configDir = path.dirname(configPath);
- if (!fs.existsSync(configDir)) {
- fs.mkdirSync(configDir, { recursive: true });
- }
- fs.writeFileSync(configPath, stringifyYaml({ defaultSchema: name }));
- }
- }
-
- if (spinner) spinner.succeed(`Created schema '${name}'`);
-
- if (options?.json) {
- console.log(JSON.stringify({
- created: true,
- path: schemaDir,
+interface WorkflowPromptMeta {
+ name: string;
+ description: string;
+}
+
+const WORKFLOW_PROMPT_META: Record<string, WorkflowPromptMeta> = {
+ propose: {
+ name: 'Propose change',
+ description: 'Create proposal, design, and tasks from a request',
+ },
+ explore: {
+ name: 'Explore ideas',
+ description: 'Investigate a problem before implementation',
+ },
+ new: {
+ name: 'New change',
+ description: 'Create a new change scaffold quickly',
+ },
+ continue: {
```
-This function is important because it defines how OpenSpec Tutorial: Spec-Driven Workflows for AI Coding Agents implements the patterns covered in this chapter.
+This interface is important because it defines how OpenSpec Tutorial: Spec-Driven Workflows for AI Coding Agents implements the patterns covered in this chapter.
-### `src/commands/schema.ts`
+### `src/commands/config.ts`
-The `SchemaLocation` interface in [`src/commands/schema.ts`](https://github.com/Fission-AI/OpenSpec/blob/HEAD/src/commands/schema.ts) handles a key part of this chapter's functionality:
+The `ProfileStateDiff` interface in [`src/commands/config.ts`](https://github.com/Fission-AI/OpenSpec/blob/HEAD/src/commands/config.ts) handles a key part of this chapter's functionality:
```ts
- * Result of checking a schema location
- */
-interface SchemaLocation {
- source: SchemaSource;
- path: string;
- exists: boolean;
}
-/**
- * Schema resolution info with shadowing details
- */
-interface SchemaResolution {
- name: string;
- source: SchemaSource;
- path: string;
- shadows: Array<{ source: SchemaSource; path: string }>;
+interface ProfileStateDiff {
+ hasChanges: boolean;
+ lines: string[];
}
-/**
- * Validation issue structure
- */
-interface ValidationIssue {
- level: 'error' | 'warning';
- path: string;
- message: string;
+interface WorkflowPromptMeta {
+ name: string;
+ description: string;
}
-/**
- * Check all three locations for a schema and return which ones exist.
- */
-function checkAllLocations(
- name: string,
+const WORKFLOW_PROMPT_META: Record<string, WorkflowPromptMeta> = {
+ propose: {
+ name: 'Propose change',
+ description: 'Create proposal, design, and tasks from a request',
+ },
+ explore: {
+ name: 'Explore ideas',
+ description: 'Investigate a problem before implementation',
+ },
+ new: {
+ name: 'New change',
+ description: 'Create a new change scaffold quickly',
+ },
+ continue: {
+ name: 'Continue change',
+ description: 'Resume work on an existing change',
+ },
+ apply: {
+ name: 'Apply tasks',
+ description: 'Implement tasks from the current change',
```
This interface is important because it defines how OpenSpec Tutorial: Spec-Driven Workflows for AI Coding Agents implements the patterns covered in this chapter.
-### `src/commands/schema.ts`
+### `src/commands/config.ts`
-The `SchemaResolution` interface in [`src/commands/schema.ts`](https://github.com/Fission-AI/OpenSpec/blob/HEAD/src/commands/schema.ts) handles a key part of this chapter's functionality:
+The `WorkflowPromptMeta` interface in [`src/commands/config.ts`](https://github.com/Fission-AI/OpenSpec/blob/HEAD/src/commands/config.ts) handles a key part of this chapter's functionality:
```ts
- * Schema resolution info with shadowing details
- */
-interface SchemaResolution {
- name: string;
- source: SchemaSource;
- path: string;
- shadows: Array<{ source: SchemaSource; path: string }>;
}
-/**
- * Validation issue structure
- */
-interface ValidationIssue {
- level: 'error' | 'warning';
- path: string;
- message: string;
+interface WorkflowPromptMeta {
+ name: string;
+ description: string;
}
-/**
- * Check all three locations for a schema and return which ones exist.
- */
-function checkAllLocations(
- name: string,
- projectRoot: string
-): SchemaLocation[] {
- const locations: SchemaLocation[] = [];
-
- // Project location
- const projectDir = path.join(getProjectSchemasDir(projectRoot), name);
- const projectSchemaPath = path.join(projectDir, 'schema.yaml');
- locations.push({
- source: 'project',
+const WORKFLOW_PROMPT_META: Record<string, WorkflowPromptMeta> = {
+ propose: {
+ name: 'Propose change',
+ description: 'Create proposal, design, and tasks from a request',
+ },
+ explore: {
+ name: 'Explore ideas',
+ description: 'Investigate a problem before implementation',
+ },
+ new: {
+ name: 'New change',
+ description: 'Create a new change scaffold quickly',
+ },
+ continue: {
+ name: 'Continue change',
+ description: 'Resume work on an existing change',
+ },
+ apply: {
+ name: 'Apply tasks',
+ description: 'Implement tasks from the current change',
+ },
+ ff: {
+ name: 'Fast-forward',
+ description: 'Run a faster implementation workflow',
+ },
```
This interface is important because it defines how OpenSpec Tutorial: Spec-Driven Workflows for AI Coding Agents implements the patterns covered in this chapter.
@@ -233,11 +231,11 @@ This interface is important because it defines how OpenSpec Tutorial: Spec-Drive
```mermaid
flowchart TD
- A[registerSchemaCommand]
- B[createDefaultTemplate]
- C[SchemaLocation]
- D[SchemaResolution]
- E[ValidationIssue]
+ A[registerConfigCommand]
+ B[ProfileState]
+ C[ProfileStateDiff]
+ D[WorkflowPromptMeta]
+ E[getCommandPath]
A --> B
B --> C
C --> D
diff --git a/tutorials/openspec-tutorial/03-command-surface-and-agent-workflows.md b/tutorials/openspec-tutorial/03-command-surface-and-agent-workflows.md
index e78799bc..94541850 100644
--- a/tutorials/openspec-tutorial/03-command-surface-and-agent-workflows.md
+++ b/tutorials/openspec-tutorial/03-command-surface-and-agent-workflows.md
@@ -55,170 +55,168 @@ You now know how to coordinate human and agent command usage without workflow co
Next: [Chapter 4: Spec Authoring, Delta Patterns, and Quality](04-spec-authoring-delta-patterns-and-quality.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/commands/validate.ts`
+### `src/core/legacy-cleanup.ts`
-The `ValidateCommand` class in [`src/commands/validate.ts`](https://github.com/Fission-AI/OpenSpec/blob/HEAD/src/commands/validate.ts) handles a key part of this chapter's functionality:
+The `removeMarkerBlock` function in [`src/core/legacy-cleanup.ts`](https://github.com/Fission-AI/OpenSpec/blob/HEAD/src/core/legacy-cleanup.ts) handles a key part of this chapter's functionality:
```ts
-}
+import { promises as fs } from 'fs';
+import chalk from 'chalk';
+import { FileSystemUtils, removeMarkerBlock as removeMarkerBlockUtil } from '../utils/file-system.js';
+import { OPENSPEC_MARKERS } from './config.js';
+
+/**
+ * Legacy config file names from the old ToolRegistry.
+ * These were config files created at project root with OpenSpec markers.
+ */
+export const LEGACY_CONFIG_FILES = [
+ 'CLAUDE.md',
+ 'CLINE.md',
+ 'CODEBUDDY.md',
+ 'COSTRICT.md',
+ 'QODER.md',
+ 'IFLOW.md',
+ 'AGENTS.md', // root AGENTS.md (not openspec/AGENTS.md)
+ 'QWEN.md',
+] as const;
+
+/**
+ * Legacy slash command patterns from the old SlashCommandRegistry.
+ * These map toolId to the path pattern where legacy commands were created.
+ * Some tools used a directory structure, others used individual files.
+ */
+export const LEGACY_SLASH_COMMAND_PATHS: Record<string, LegacySlashCommandPattern> = {
+ // Directory-based: .tooldir/commands/openspec/ or .tooldir/commands/openspec/*.md
+ 'claude': { type: 'directory', path: '.claude/commands/openspec' },
+ 'codebuddy': { type: 'directory', path: '.codebuddy/commands/openspec' },
+ 'qoder': { type: 'directory', path: '.qoder/commands/openspec' },
+ 'crush': { type: 'directory', path: '.crush/commands/openspec' },
+ 'gemini': { type: 'directory', path: '.gemini/commands/openspec' },
+```
-export class ValidateCommand {
- async execute(itemName: string | undefined, options: ExecuteOptions = {}): Promise<void> {
- const interactive = isInteractive(options);
-
- // Handle bulk flags first
- if (options.all || options.changes || options.specs) {
- await this.runBulkValidation({
- changes: !!options.all || !!options.changes,
- specs: !!options.all || !!options.specs,
- }, { strict: !!options.strict, json: !!options.json, concurrency: options.concurrency, noInteractive: resolveNoInteractive(options) });
- return;
- }
+This function is important because it defines how OpenSpec Tutorial: Spec-Driven Workflows for AI Coding Agents implements the patterns covered in this chapter.
- // No item and no flags
- if (!itemName) {
- if (interactive) {
- await this.runInteractiveSelector({ strict: !!options.strict, json: !!options.json, concurrency: options.concurrency });
- return;
- }
- this.printNonInteractiveHint();
- process.exitCode = 1;
- return;
- }
+### `src/core/legacy-cleanup.ts`
- // Direct item validation with type detection or override
- const typeOverride = this.normalizeType(options.type);
- await this.validateDirectItem(itemName, { typeOverride, strict: !!options.strict, json: !!options.json });
+The `cleanupLegacyArtifacts` function in [`src/core/legacy-cleanup.ts`](https://github.com/Fission-AI/OpenSpec/blob/HEAD/src/core/legacy-cleanup.ts) handles a key part of this chapter's functionality:
+
+```ts
+ * @returns Cleanup result with summary of actions taken
+ */
+export async function cleanupLegacyArtifacts(
+ projectPath: string,
+ detection: LegacyDetectionResult
+): Promise<CleanupResult> {
+ const result: CleanupResult = {
+ deletedFiles: [],
+ modifiedFiles: [],
+ deletedDirs: [],
+ projectMdNeedsMigration: detection.hasProjectMd,
+ errors: [],
+ };
+
+ // Remove marker blocks from config files (NEVER delete config files)
+ // Config files like CLAUDE.md, AGENTS.md belong to the user's project root
+ for (const fileName of detection.configFilesToUpdate) {
+ const filePath = FileSystemUtils.joinPath(projectPath, fileName);
+ try {
+ const content = await FileSystemUtils.readFile(filePath);
+ const newContent = removeMarkerBlock(content);
+ // Always write the file, even if empty - never delete user config files
+ await FileSystemUtils.writeFile(filePath, newContent);
+ result.modifiedFiles.push(fileName);
+ } catch (error: any) {
+ result.errors.push(`Failed to modify ${fileName}: ${error.message}`);
+ }
}
- private normalizeType(value?: string): ItemType | undefined {
+ // Delete legacy slash command directories (these are 100% OpenSpec-managed)
+ for (const dirPath of detection.slashCommandDirs) {
+ const fullPath = FileSystemUtils.joinPath(projectPath, dirPath);
```
-This class is important because it defines how OpenSpec Tutorial: Spec-Driven Workflows for AI Coding Agents implements the patterns covered in this chapter.
+This function is important because it defines how OpenSpec Tutorial: Spec-Driven Workflows for AI Coding Agents implements the patterns covered in this chapter.
-### `src/commands/validate.ts`
+### `src/core/legacy-cleanup.ts`
-The `summarizeType` function in [`src/commands/validate.ts`](https://github.com/Fission-AI/OpenSpec/blob/HEAD/src/commands/validate.ts) handles a key part of this chapter's functionality:
+The `formatCleanupSummary` function in [`src/core/legacy-cleanup.ts`](https://github.com/Fission-AI/OpenSpec/blob/HEAD/src/core/legacy-cleanup.ts) handles a key part of this chapter's functionality:
```ts
- totals: { items: results.length, passed, failed },
- byType: {
- ...(scope.changes ? { change: summarizeType(results, 'change') } : {}),
- ...(scope.specs ? { spec: summarizeType(results, 'spec') } : {}),
- },
- } as const;
-
- if (opts.json) {
- const out = { items: results, summary, version: '1.0' };
- console.log(JSON.stringify(out, null, 2));
- } else {
- for (const res of results) {
- if (res.valid) console.log(`✓ ${res.type}/${res.id}`);
- else console.error(`✗ ${res.type}/${res.id}`);
- }
- console.log(`Totals: ${summary.totals.passed} passed, ${summary.totals.failed} failed (${summary.totals.items} items)`);
+ * @returns Formatted summary string for console output
+ */
+export function formatCleanupSummary(result: CleanupResult): string {
+ const lines: string[] = [];
+
+ if (result.deletedFiles.length > 0 || result.deletedDirs.length > 0 || result.modifiedFiles.length > 0) {
+ lines.push('Cleaned up legacy files:');
+
+ for (const file of result.deletedFiles) {
+ lines.push(` ✓ Removed ${file}`);
}
- process.exitCode = failed > 0 ? 1 : 0;
+ for (const dir of result.deletedDirs) {
+ lines.push(` ✓ Removed ${dir}/ (replaced by /opsx:*)`);
+ }
+
+ for (const file of result.modifiedFiles) {
+ lines.push(` ✓ Removed OpenSpec markers from ${file}`);
+ }
}
-}
-function summarizeType(results: BulkItemResult[], type: ItemType) {
- const filtered = results.filter(r => r.type === type);
- const items = filtered.length;
- const passed = filtered.filter(r => r.valid).length;
- const failed = items - passed;
- return { items, passed, failed };
-}
+ if (result.projectMdNeedsMigration) {
+ if (lines.length > 0) {
+ lines.push('');
+ }
+ lines.push(formatProjectMdMigrationHint());
+ }
-function normalizeConcurrency(value?: string): number | undefined {
- if (!value) return undefined;
+ if (result.errors.length > 0) {
+ if (lines.length > 0) {
+ lines.push('');
+ }
```
This function is important because it defines how OpenSpec Tutorial: Spec-Driven Workflows for AI Coding Agents implements the patterns covered in this chapter.
-### `src/commands/validate.ts`
+### `src/core/legacy-cleanup.ts`
-The `normalizeConcurrency` function in [`src/commands/validate.ts`](https://github.com/Fission-AI/OpenSpec/blob/HEAD/src/commands/validate.ts) handles a key part of this chapter's functionality:
+The `buildRemovalsList` function in [`src/core/legacy-cleanup.ts`](https://github.com/Fission-AI/OpenSpec/blob/HEAD/src/core/legacy-cleanup.ts) handles a key part of this chapter's functionality:
```ts
- const DEFAULT_CONCURRENCY = 6;
- const maxSuggestions = 5; // used by nearestMatches
- const concurrency = normalizeConcurrency(opts.concurrency) ?? normalizeConcurrency(process.env.OPENSPEC_CONCURRENCY) ?? DEFAULT_CONCURRENCY;
- const validator = new Validator(opts.strict);
- const queue: Array<() => Promise<BulkItemResult>> = [];
-
- for (const id of changeIds) {
- queue.push(async () => {
- const start = Date.now();
- const changeDir = path.join(process.cwd(), 'openspec', 'changes', id);
- const report = await validator.validateChangeDeltaSpecs(changeDir);
- const durationMs = Date.now() - start;
- return { id, type: 'change' as const, valid: report.valid, issues: report.issues, durationMs };
- });
- }
- for (const id of specIds) {
- queue.push(async () => {
- const start = Date.now();
- const file = path.join(process.cwd(), 'openspec', 'specs', id, 'spec.md');
- const report = await validator.validateSpec(file);
- const durationMs = Date.now() - start;
- return { id, type: 'spec' as const, valid: report.valid, issues: report.issues, durationMs };
- });
- }
-
- if (queue.length === 0) {
- spinner?.stop();
+ * @returns Array of objects with path and explanation
+ */
+function buildRemovalsList(detection: LegacyDetectionResult): Array<{ path: string; explanation: string }> {
+ const removals: Array<{ path: string; explanation: string }> = [];
+
+ // Slash command directories (these are 100% OpenSpec-managed)
+ for (const dir of detection.slashCommandDirs) {
+ // Split on both forward and backward slashes for Windows compatibility
+ const toolDir = dir.split(/[\/\\]/)[0];
+ removals.push({ path: dir + '/', explanation: `replaced by ${toolDir}/skills/` });
+ }
- const summary = {
- totals: { items: 0, passed: 0, failed: 0 },
- byType: {
- ...(scope.changes ? { change: { items: 0, passed: 0, failed: 0 } } : {}),
-```
+ // Slash command files (these are 100% OpenSpec-managed)
+ for (const file of detection.slashCommandFiles) {
+ removals.push({ path: file, explanation: 'replaced by skills/' });
+ }
-This function is important because it defines how OpenSpec Tutorial: Spec-Driven Workflows for AI Coding Agents implements the patterns covered in this chapter.
+ // openspec/AGENTS.md (inside openspec/, it's OpenSpec-managed)
+ if (detection.hasOpenspecAgents) {
+ removals.push({ path: 'openspec/AGENTS.md', explanation: 'obsolete workflow file' });
+ }
-### `src/commands/validate.ts`
+ // Note: Config files (CLAUDE.md, AGENTS.md, etc.) are NEVER in the removals list
+ // They always go to the updates list where only markers are removed
-The `getPlannedId` function in [`src/commands/validate.ts`](https://github.com/Fission-AI/OpenSpec/blob/HEAD/src/commands/validate.ts) handles a key part of this chapter's functionality:
+ return removals;
+}
-```ts
- .catch((error: any) => {
- const message = error?.message || 'Unknown error';
- const res: BulkItemResult = { id: getPlannedId(currentIndex, changeIds, specIds) ?? 'unknown', type: getPlannedType(currentIndex, changeIds, specIds) ?? 'change', valid: false, issues: [{ level: 'ERROR', path: 'file', message }], durationMs: 0 };
- results.push(res);
- failed++;
- })
- .finally(() => {
- running--;
- if (index >= queue.length && running === 0) resolve();
- else next();
- });
- }
- };
- next();
- });
-
- spinner?.stop();
-
- results.sort((a, b) => a.id.localeCompare(b.id));
- const summary = {
- totals: { items: results.length, passed, failed },
- byType: {
- ...(scope.changes ? { change: summarizeType(results, 'change') } : {}),
- ...(scope.specs ? { spec: summarizeType(results, 'spec') } : {}),
- },
- } as const;
-
- if (opts.json) {
- const out = { items: results, summary, version: '1.0' };
- console.log(JSON.stringify(out, null, 2));
- } else {
- for (const res of results) {
+/**
+ * Build list of files to be updated with explanations.
+ * Includes ALL config files with markers - markers are removed, file is never deleted.
+ *
```
This function is important because it defines how OpenSpec Tutorial: Spec-Driven Workflows for AI Coding Agents implements the patterns covered in this chapter.
@@ -228,11 +226,11 @@ This function is important because it defines how OpenSpec Tutorial: Spec-Driven
```mermaid
flowchart TD
- A[ValidateCommand]
- B[summarizeType]
- C[normalizeConcurrency]
- D[getPlannedId]
- E[getPlannedType]
+ A[removeMarkerBlock]
+ B[cleanupLegacyArtifacts]
+ C[formatCleanupSummary]
+ D[buildRemovalsList]
+ E[buildUpdatesList]
A --> B
B --> C
C --> D
diff --git a/tutorials/openspec-tutorial/04-spec-authoring-delta-patterns-and-quality.md b/tutorials/openspec-tutorial/04-spec-authoring-delta-patterns-and-quality.md
index 8b5663b2..1f81d589 100644
--- a/tutorials/openspec-tutorial/04-spec-authoring-delta-patterns-and-quality.md
+++ b/tutorials/openspec-tutorial/04-spec-authoring-delta-patterns-and-quality.md
@@ -59,170 +59,168 @@ You now have concrete rules for writing high-signal artifacts that agents and hu
Next: [Chapter 5: Customization, Schemas, and Project Rules](05-customization-schemas-and-project-rules.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/core/legacy-cleanup.ts`
+### `src/commands/schema.ts`
-The `hasOpenSpecMarkers` function in [`src/core/legacy-cleanup.ts`](https://github.com/Fission-AI/OpenSpec/blob/HEAD/src/core/legacy-cleanup.ts) handles a key part of this chapter's functionality:
+The `getSchemaResolution` function in [`src/commands/schema.ts`](https://github.com/Fission-AI/OpenSpec/blob/HEAD/src/commands/schema.ts) handles a key part of this chapter's functionality:
```ts
- const content = await FileSystemUtils.readFile(filePath);
-
- if (hasOpenSpecMarkers(content)) {
- allFiles.push(fileName);
- filesToUpdate.push(fileName); // Always update, never delete config files
- }
- }
+ * Get resolution info for a schema including shadow detection.
+ */
+function getSchemaResolution(
+ name: string,
+ projectRoot: string
+): SchemaResolution | null {
+ const locations = checkAllLocations(name, projectRoot);
+ const existingLocations = locations.filter((loc) => loc.exists);
+
+ if (existingLocations.length === 0) {
+ return null;
}
- return { allFiles, filesToUpdate };
+ const active = existingLocations[0];
+ const shadows = existingLocations.slice(1).map((loc) => ({
+ source: loc.source,
+ path: loc.path,
+ }));
+
+ return {
+ name,
+ source: active.source,
+ path: active.path,
+ shadows,
+ };
}
/**
- * Detects legacy slash command directories and files.
- *
- * @param projectPath - The root path of the project
- * @returns Object with directories and individual files found
+ * Get all schemas with resolution info.
*/
-export async function detectLegacySlashCommands(
- projectPath: string
-): Promise<{
- directories: string[];
- files: string[];
-}> {
- const directories: string[] = [];
- const files: string[] = [];
-
- for (const [toolId, pattern] of Object.entries(LEGACY_SLASH_COMMAND_PATHS)) {
- if (pattern.type === 'directory' && pattern.path) {
- const dirPath = FileSystemUtils.joinPath(projectPath, pattern.path);
- if (await FileSystemUtils.directoryExists(dirPath)) {
- directories.push(pattern.path);
+function getAllSchemasWithResolution(
+ projectRoot: string
```
This function is important because it defines how OpenSpec Tutorial: Spec-Driven Workflows for AI Coding Agents implements the patterns covered in this chapter.
-### `src/core/legacy-cleanup.ts`
+### `src/commands/schema.ts`
-The `isOnlyOpenSpecContent` function in [`src/core/legacy-cleanup.ts`](https://github.com/Fission-AI/OpenSpec/blob/HEAD/src/core/legacy-cleanup.ts) handles a key part of this chapter's functionality:
+The `getAllSchemasWithResolution` function in [`src/commands/schema.ts`](https://github.com/Fission-AI/OpenSpec/blob/HEAD/src/commands/schema.ts) handles a key part of this chapter's functionality:
```ts
- * @returns True if content outside markers is only whitespace
+ * Get all schemas with resolution info.
*/
-export function isOnlyOpenSpecContent(content: string): boolean {
- const startIndex = content.indexOf(OPENSPEC_MARKERS.start);
- const endIndex = content.indexOf(OPENSPEC_MARKERS.end);
-
- if (startIndex === -1 || endIndex === -1 || endIndex <= startIndex) {
- return false;
+function getAllSchemasWithResolution(
+ projectRoot: string
+): SchemaResolution[] {
+ const schemaNames = listSchemas(projectRoot);
+ const results: SchemaResolution[] = [];
+
+ for (const name of schemaNames) {
+ const resolution = getSchemaResolution(name, projectRoot);
+ if (resolution) {
+ results.push(resolution);
+ }
}
- const before = content.substring(0, startIndex);
- const after = content.substring(endIndex + OPENSPEC_MARKERS.end.length);
-
- return before.trim() === '' && after.trim() === '';
+ return results;
}
/**
- * Removes the OpenSpec marker block from file content.
- * Only removes markers that are on their own lines (ignores inline mentions).
- * Cleans up double blank lines that may result from removal.
- *
- * @param content - File content with OpenSpec markers
- * @returns Content with marker block removed
+ * Validate a schema and return issues.
*/
-export function removeMarkerBlock(content: string): string {
- return removeMarkerBlockUtil(content, OPENSPEC_MARKERS.start, OPENSPEC_MARKERS.end);
-}
-
-/**
- * Result of cleanup operation
- */
-export interface CleanupResult {
+function validateSchema(
+ schemaDir: string,
+ verbose: boolean = false
+): { valid: boolean; issues: ValidationIssue[] } {
+ const issues: ValidationIssue[] = [];
+ const schemaPath = path.join(schemaDir, 'schema.yaml');
+
+ // Check schema.yaml exists
+ if (verbose) {
+ console.log(' Checking schema.yaml exists...');
+ }
```
This function is important because it defines how OpenSpec Tutorial: Spec-Driven Workflows for AI Coding Agents implements the patterns covered in this chapter.
-### `src/core/legacy-cleanup.ts`
+### `src/commands/schema.ts`
-The `removeMarkerBlock` function in [`src/core/legacy-cleanup.ts`](https://github.com/Fission-AI/OpenSpec/blob/HEAD/src/core/legacy-cleanup.ts) handles a key part of this chapter's functionality:
+The `validateSchema` function in [`src/commands/schema.ts`](https://github.com/Fission-AI/OpenSpec/blob/HEAD/src/commands/schema.ts) handles a key part of this chapter's functionality:
```ts
-import { promises as fs } from 'fs';
-import chalk from 'chalk';
-import { FileSystemUtils, removeMarkerBlock as removeMarkerBlockUtil } from '../utils/file-system.js';
-import { OPENSPEC_MARKERS } from './config.js';
-
-/**
- * Legacy config file names from the old ToolRegistry.
- * These were config files created at project root with OpenSpec markers.
+ * Validate a schema and return issues.
*/
-export const LEGACY_CONFIG_FILES = [
- 'CLAUDE.md',
- 'CLINE.md',
- 'CODEBUDDY.md',
- 'COSTRICT.md',
- 'QODER.md',
- 'IFLOW.md',
- 'AGENTS.md', // root AGENTS.md (not openspec/AGENTS.md)
- 'QWEN.md',
-] as const;
+function validateSchema(
+ schemaDir: string,
+ verbose: boolean = false
+): { valid: boolean; issues: ValidationIssue[] } {
+ const issues: ValidationIssue[] = [];
+ const schemaPath = path.join(schemaDir, 'schema.yaml');
+
+ // Check schema.yaml exists
+ if (verbose) {
+ console.log(' Checking schema.yaml exists...');
+ }
+ if (!fs.existsSync(schemaPath)) {
+ issues.push({
+ level: 'error',
+ path: 'schema.yaml',
+ message: 'schema.yaml not found',
+ });
+ return { valid: false, issues };
+ }
-/**
- * Legacy slash command patterns from the old SlashCommandRegistry.
- * These map toolId to the path pattern where legacy commands were created.
- * Some tools used a directory structure, others used individual files.
- */
-export const LEGACY_SLASH_COMMAND_PATHS: Record<string, LegacySlashCommandPattern> = {
- // Directory-based: .tooldir/commands/openspec/ or .tooldir/commands/openspec/*.md
- 'claude': { type: 'directory', path: '.claude/commands/openspec' },
- 'codebuddy': { type: 'directory', path: '.codebuddy/commands/openspec' },
- 'qoder': { type: 'directory', path: '.qoder/commands/openspec' },
- 'crush': { type: 'directory', path: '.crush/commands/openspec' },
- 'gemini': { type: 'directory', path: '.gemini/commands/openspec' },
+ // Parse YAML
+ if (verbose) {
+ console.log(' Parsing YAML...');
+ }
+ let content: string;
+ try {
+ content = fs.readFileSync(schemaPath, 'utf-8');
+ } catch (err) {
+ issues.push({
+ level: 'error',
```
This function is important because it defines how OpenSpec Tutorial: Spec-Driven Workflows for AI Coding Agents implements the patterns covered in this chapter.
-### `src/core/legacy-cleanup.ts`
+### `src/commands/schema.ts`
-The `cleanupLegacyArtifacts` function in [`src/core/legacy-cleanup.ts`](https://github.com/Fission-AI/OpenSpec/blob/HEAD/src/core/legacy-cleanup.ts) handles a key part of this chapter's functionality:
+The `isValidSchemaName` function in [`src/commands/schema.ts`](https://github.com/Fission-AI/OpenSpec/blob/HEAD/src/commands/schema.ts) handles a key part of this chapter's functionality:
```ts
- * @returns Cleanup result with summary of actions taken
+ * Validate schema name format (kebab-case).
*/
-export async function cleanupLegacyArtifacts(
- projectPath: string,
- detection: LegacyDetectionResult
-): Promise<CleanupResult> {
- const result: CleanupResult = {
- deletedFiles: [],
- modifiedFiles: [],
- deletedDirs: [],
- projectMdNeedsMigration: detection.hasProjectMd,
- errors: [],
- };
+function isValidSchemaName(name: string): boolean {
+ return /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/.test(name);
+}
- // Remove marker blocks from config files (NEVER delete config files)
- // Config files like CLAUDE.md, AGENTS.md belong to the user's project root
- for (const fileName of detection.configFilesToUpdate) {
- const filePath = FileSystemUtils.joinPath(projectPath, fileName);
- try {
- const content = await FileSystemUtils.readFile(filePath);
- const newContent = removeMarkerBlock(content);
- // Always write the file, even if empty - never delete user config files
- await FileSystemUtils.writeFile(filePath, newContent);
- result.modifiedFiles.push(fileName);
- } catch (error: any) {
- result.errors.push(`Failed to modify ${fileName}: ${error.message}`);
+/**
+ * Copy a directory recursively.
+ */
+function copyDirRecursive(src: string, dest: string): void {
+ fs.mkdirSync(dest, { recursive: true });
+
+ const entries = fs.readdirSync(src, { withFileTypes: true });
+ for (const entry of entries) {
+ const srcPath = path.join(src, entry.name);
+ const destPath = path.join(dest, entry.name);
+
+ if (entry.isDirectory()) {
+ copyDirRecursive(srcPath, destPath);
+ } else {
+ fs.copyFileSync(srcPath, destPath);
}
}
+}
- // Delete legacy slash command directories (these are 100% OpenSpec-managed)
- for (const dirPath of detection.slashCommandDirs) {
- const fullPath = FileSystemUtils.joinPath(projectPath, dirPath);
+/**
+ * Default artifacts with descriptions for schema init.
+ */
+const DEFAULT_ARTIFACTS: Array<{
+ id: string;
+ description: string;
+ generates: string;
```
This function is important because it defines how OpenSpec Tutorial: Spec-Driven Workflows for AI Coding Agents implements the patterns covered in this chapter.
@@ -232,11 +230,11 @@ This function is important because it defines how OpenSpec Tutorial: Spec-Driven
```mermaid
flowchart TD
- A[hasOpenSpecMarkers]
- B[isOnlyOpenSpecContent]
- C[removeMarkerBlock]
- D[cleanupLegacyArtifacts]
- E[formatCleanupSummary]
+ A[getSchemaResolution]
+ B[getAllSchemasWithResolution]
+ C[validateSchema]
+ D[isValidSchemaName]
+ E[copyDirRecursive]
A --> B
B --> C
C --> D
diff --git a/tutorials/openspec-tutorial/05-customization-schemas-and-project-rules.md b/tutorials/openspec-tutorial/05-customization-schemas-and-project-rules.md
index 5296b226..9a132a13 100644
--- a/tutorials/openspec-tutorial/05-customization-schemas-and-project-rules.md
+++ b/tutorials/openspec-tutorial/05-customization-schemas-and-project-rules.md
@@ -62,184 +62,182 @@ You now know how to shape OpenSpec behavior while keeping workflows maintainable
Next: [Chapter 6: Tool Integrations and Multi-Agent Portability](06-tool-integrations-and-multi-agent-portability.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/core/legacy-cleanup.ts`
+### `src/commands/validate.ts`
-The `CleanupResult` interface in [`src/core/legacy-cleanup.ts`](https://github.com/Fission-AI/OpenSpec/blob/HEAD/src/core/legacy-cleanup.ts) handles a key part of this chapter's functionality:
+The `normalizeConcurrency` function in [`src/commands/validate.ts`](https://github.com/Fission-AI/OpenSpec/blob/HEAD/src/commands/validate.ts) handles a key part of this chapter's functionality:
```ts
- * Result of cleanup operation
- */
-export interface CleanupResult {
- /** Files that were deleted entirely */
- deletedFiles: string[];
- /** Files that had marker blocks removed */
- modifiedFiles: string[];
- /** Directories that were deleted */
- deletedDirs: string[];
- /** Whether project.md exists and needs manual migration */
- projectMdNeedsMigration: boolean;
- /** Error messages if any operations failed */
- errors: string[];
-}
+ const DEFAULT_CONCURRENCY = 6;
+ const maxSuggestions = 5; // used by nearestMatches
+ const concurrency = normalizeConcurrency(opts.concurrency) ?? normalizeConcurrency(process.env.OPENSPEC_CONCURRENCY) ?? DEFAULT_CONCURRENCY;
+ const validator = new Validator(opts.strict);
+ const queue: Array<() => Promise<BulkItemResult>> = [];
+
+ for (const id of changeIds) {
+ queue.push(async () => {
+ const start = Date.now();
+ const changeDir = path.join(process.cwd(), 'openspec', 'changes', id);
+ const report = await validator.validateChangeDeltaSpecs(changeDir);
+ const durationMs = Date.now() - start;
+ return { id, type: 'change' as const, valid: report.valid, issues: report.issues, durationMs };
+ });
+ }
+ for (const id of specIds) {
+ queue.push(async () => {
+ const start = Date.now();
+ const file = path.join(process.cwd(), 'openspec', 'specs', id, 'spec.md');
+ const report = await validator.validateSpec(file);
+ const durationMs = Date.now() - start;
+ return { id, type: 'spec' as const, valid: report.valid, issues: report.issues, durationMs };
+ });
+ }
-/**
- * Cleans up legacy OpenSpec artifacts from a project.
- * Preserves openspec/project.md (shows migration hint instead of deleting).
- *
- * @param projectPath - The root path of the project
- * @param detection - Detection result from detectLegacyArtifacts
- * @returns Cleanup result with summary of actions taken
- */
-export async function cleanupLegacyArtifacts(
- projectPath: string,
- detection: LegacyDetectionResult
-): Promise<CleanupResult> {
- const result: CleanupResult = {
- deletedFiles: [],
- modifiedFiles: [],
- deletedDirs: [],
- projectMdNeedsMigration: detection.hasProjectMd,
+ if (queue.length === 0) {
+ spinner?.stop();
+
+ const summary = {
+ totals: { items: 0, passed: 0, failed: 0 },
+ byType: {
+ ...(scope.changes ? { change: { items: 0, passed: 0, failed: 0 } } : {}),
```
-This interface is important because it defines how OpenSpec Tutorial: Spec-Driven Workflows for AI Coding Agents implements the patterns covered in this chapter.
+This function is important because it defines how OpenSpec Tutorial: Spec-Driven Workflows for AI Coding Agents implements the patterns covered in this chapter.
-### `src/commands/config.ts`
+### `src/commands/validate.ts`
-The `isPromptCancellationError` function in [`src/commands/config.ts`](https://github.com/Fission-AI/OpenSpec/blob/HEAD/src/commands/config.ts) handles a key part of this chapter's functionality:
+The `getPlannedId` function in [`src/commands/validate.ts`](https://github.com/Fission-AI/OpenSpec/blob/HEAD/src/commands/validate.ts) handles a key part of this chapter's functionality:
```ts
-};
-
-function isPromptCancellationError(error: unknown): boolean {
- return (
- error instanceof Error &&
- (error.name === 'ExitPromptError' || error.message.includes('force closed the prompt with SIGINT'))
- );
-}
-
-/**
- * Resolve the effective current profile state from global config defaults.
- */
-export function resolveCurrentProfileState(config: GlobalConfig): ProfileState {
- const profile = config.profile || 'core';
- const delivery = config.delivery || 'both';
- const workflows = [
- ...getProfileWorkflows(profile, config.workflows ? [...config.workflows] : undefined),
- ];
- return { profile, delivery, workflows };
-}
-
-/**
- * Derive profile type from selected workflows.
- */
-export function deriveProfileFromWorkflowSelection(selectedWorkflows: string[]): Profile {
- const isCoreMatch =
- selectedWorkflows.length === CORE_WORKFLOWS.length &&
- CORE_WORKFLOWS.every((w) => selectedWorkflows.includes(w));
- return isCoreMatch ? 'core' : 'custom';
-}
-
-/**
+ .catch((error: any) => {
+ const message = error?.message || 'Unknown error';
+ const res: BulkItemResult = { id: getPlannedId(currentIndex, changeIds, specIds) ?? 'unknown', type: getPlannedType(currentIndex, changeIds, specIds) ?? 'change', valid: false, issues: [{ level: 'ERROR', path: 'file', message }], durationMs: 0 };
+ results.push(res);
+ failed++;
+ })
+ .finally(() => {
+ running--;
+ if (index >= queue.length && running === 0) resolve();
+ else next();
+ });
+ }
+ };
+ next();
+ });
+
+ spinner?.stop();
+
+ results.sort((a, b) => a.id.localeCompare(b.id));
+ const summary = {
+ totals: { items: results.length, passed, failed },
+ byType: {
+ ...(scope.changes ? { change: summarizeType(results, 'change') } : {}),
+ ...(scope.specs ? { spec: summarizeType(results, 'spec') } : {}),
+ },
+ } as const;
+
+ if (opts.json) {
+ const out = { items: results, summary, version: '1.0' };
+ console.log(JSON.stringify(out, null, 2));
+ } else {
+ for (const res of results) {
```
This function is important because it defines how OpenSpec Tutorial: Spec-Driven Workflows for AI Coding Agents implements the patterns covered in this chapter.
-### `src/commands/config.ts`
+### `src/commands/validate.ts`
-The `resolveCurrentProfileState` function in [`src/commands/config.ts`](https://github.com/Fission-AI/OpenSpec/blob/HEAD/src/commands/config.ts) handles a key part of this chapter's functionality:
+The `getPlannedType` function in [`src/commands/validate.ts`](https://github.com/Fission-AI/OpenSpec/blob/HEAD/src/commands/validate.ts) handles a key part of this chapter's functionality:
```ts
- * Resolve the effective current profile state from global config defaults.
- */
-export function resolveCurrentProfileState(config: GlobalConfig): ProfileState {
- const profile = config.profile || 'core';
- const delivery = config.delivery || 'both';
- const workflows = [
- ...getProfileWorkflows(profile, config.workflows ? [...config.workflows] : undefined),
- ];
- return { profile, delivery, workflows };
-}
-
-/**
- * Derive profile type from selected workflows.
- */
-export function deriveProfileFromWorkflowSelection(selectedWorkflows: string[]): Profile {
- const isCoreMatch =
- selectedWorkflows.length === CORE_WORKFLOWS.length &&
- CORE_WORKFLOWS.every((w) => selectedWorkflows.includes(w));
- return isCoreMatch ? 'core' : 'custom';
-}
-
-/**
- * Format a compact workflow summary for the profile header.
- */
-export function formatWorkflowSummary(workflows: readonly string[], profile: Profile): string {
- return `${workflows.length} selected (${profile})`;
-}
-
-function stableWorkflowOrder(workflows: readonly string[]): string[] {
- const seen = new Set<string>();
- const ordered: string[] = [];
-
+ .catch((error: any) => {
+ const message = error?.message || 'Unknown error';
+ const res: BulkItemResult = { id: getPlannedId(currentIndex, changeIds, specIds) ?? 'unknown', type: getPlannedType(currentIndex, changeIds, specIds) ?? 'change', valid: false, issues: [{ level: 'ERROR', path: 'file', message }], durationMs: 0 };
+ results.push(res);
+ failed++;
+ })
+ .finally(() => {
+ running--;
+ if (index >= queue.length && running === 0) resolve();
+ else next();
+ });
+ }
+ };
+ next();
+ });
+
+ spinner?.stop();
+
+ results.sort((a, b) => a.id.localeCompare(b.id));
+ const summary = {
+ totals: { items: results.length, passed, failed },
+ byType: {
+ ...(scope.changes ? { change: summarizeType(results, 'change') } : {}),
+ ...(scope.specs ? { spec: summarizeType(results, 'spec') } : {}),
+ },
+ } as const;
+
+ if (opts.json) {
+ const out = { items: results, summary, version: '1.0' };
+ console.log(JSON.stringify(out, null, 2));
+ } else {
+ for (const res of results) {
```
This function is important because it defines how OpenSpec Tutorial: Spec-Driven Workflows for AI Coding Agents implements the patterns covered in this chapter.
-### `src/commands/config.ts`
+### `src/commands/validate.ts`
-The `deriveProfileFromWorkflowSelection` function in [`src/commands/config.ts`](https://github.com/Fission-AI/OpenSpec/blob/HEAD/src/commands/config.ts) handles a key part of this chapter's functionality:
+The `ExecuteOptions` interface in [`src/commands/validate.ts`](https://github.com/Fission-AI/OpenSpec/blob/HEAD/src/commands/validate.ts) handles a key part of this chapter's functionality:
```ts
- * Derive profile type from selected workflows.
- */
-export function deriveProfileFromWorkflowSelection(selectedWorkflows: string[]): Profile {
- const isCoreMatch =
- selectedWorkflows.length === CORE_WORKFLOWS.length &&
- CORE_WORKFLOWS.every((w) => selectedWorkflows.includes(w));
- return isCoreMatch ? 'core' : 'custom';
+type ItemType = 'change' | 'spec';
+
+interface ExecuteOptions {
+ all?: boolean;
+ changes?: boolean;
+ specs?: boolean;
+ type?: string;
+ strict?: boolean;
+ json?: boolean;
+ noInteractive?: boolean;
+ interactive?: boolean; // Commander sets this to false when --no-interactive is used
+ concurrency?: string;
}
-/**
- * Format a compact workflow summary for the profile header.
- */
-export function formatWorkflowSummary(workflows: readonly string[], profile: Profile): string {
- return `${workflows.length} selected (${profile})`;
+interface BulkItemResult {
+ id: string;
+ type: ItemType;
+ valid: boolean;
+ issues: { level: 'ERROR' | 'WARNING' | 'INFO'; path: string; message: string }[];
+ durationMs: number;
}
-function stableWorkflowOrder(workflows: readonly string[]): string[] {
- const seen = new Set<string>();
- const ordered: string[] = [];
-
- for (const workflow of ALL_WORKFLOWS) {
- if (workflows.includes(workflow) && !seen.has(workflow)) {
- ordered.push(workflow);
- seen.add(workflow);
- }
- }
+export class ValidateCommand {
+ async execute(itemName: string | undefined, options: ExecuteOptions = {}): Promise<void> {
+ const interactive = isInteractive(options);
- const extras = workflows.filter((w) => !ALL_WORKFLOWS.includes(w as (typeof ALL_WORKFLOWS)[number]));
- extras.sort();
- for (const extra of extras) {
- if (!seen.has(extra)) {
- ordered.push(extra);
+ // Handle bulk flags first
+ if (options.all || options.changes || options.specs) {
+ await this.runBulkValidation({
+ changes: !!options.all || !!options.changes,
+ specs: !!options.all || !!options.specs,
+ }, { strict: !!options.strict, json: !!options.json, concurrency: options.concurrency, noInteractive: resolveNoInteractive(options) });
```
-This function is important because it defines how OpenSpec Tutorial: Spec-Driven Workflows for AI Coding Agents implements the patterns covered in this chapter.
+This interface is important because it defines how OpenSpec Tutorial: Spec-Driven Workflows for AI Coding Agents implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[CleanupResult]
- B[isPromptCancellationError]
- C[resolveCurrentProfileState]
- D[deriveProfileFromWorkflowSelection]
- E[formatWorkflowSummary]
+ A[normalizeConcurrency]
+ B[getPlannedId]
+ C[getPlannedType]
+ D[ExecuteOptions]
+ E[BulkItemResult]
A --> B
B --> C
C --> D
diff --git a/tutorials/openspec-tutorial/06-tool-integrations-and-multi-agent-portability.md b/tutorials/openspec-tutorial/06-tool-integrations-and-multi-agent-portability.md
index 529d8f34..a68e9749 100644
--- a/tutorials/openspec-tutorial/06-tool-integrations-and-multi-agent-portability.md
+++ b/tutorials/openspec-tutorial/06-tool-integrations-and-multi-agent-portability.md
@@ -57,8 +57,6 @@ You now understand how OpenSpec reduces migration friction across coding-agent c
Next: [Chapter 7: Validation, Automation, and CI Operations](07-validation-automation-and-ci-operations.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `src/utils/file-system.ts`
@@ -234,7 +232,7 @@ flowchart TD
B[isMarkerOnOwnLine]
C[findMarkerIndex]
D[removeMarkerBlock]
- E[validateConfigKeyPath]
+ E[ChangeCommand]
A --> B
B --> C
C --> D
diff --git a/tutorials/openspec-tutorial/07-validation-automation-and-ci-operations.md b/tutorials/openspec-tutorial/07-validation-automation-and-ci-operations.md
index d810d3b6..78ba20c7 100644
--- a/tutorials/openspec-tutorial/07-validation-automation-and-ci-operations.md
+++ b/tutorials/openspec-tutorial/07-validation-automation-and-ci-operations.md
@@ -60,184 +60,182 @@ You now have an actionable quality-gate model for integrating OpenSpec into CI/C
Next: [Chapter 8: Migration, Governance, and Team Adoption](08-migration-governance-and-team-adoption.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/commands/completion.ts`
+### `src/core/project-config.ts`
-The `GenerateOptions` interface in [`src/commands/completion.ts`](https://github.com/Fission-AI/OpenSpec/blob/HEAD/src/commands/completion.ts) handles a key part of this chapter's functionality:
+The `suggestSchemas` function in [`src/core/project-config.ts`](https://github.com/Fission-AI/OpenSpec/blob/HEAD/src/core/project-config.ts) handles a key part of this chapter's functionality:
```ts
-import { getArchivedChangeIds } from '../utils/item-discovery.js';
-
-interface GenerateOptions {
- shell?: string;
-}
-
-interface InstallOptions {
- shell?: string;
- verbose?: boolean;
-}
-
-interface UninstallOptions {
- shell?: string;
- yes?: boolean;
-}
-
-interface CompleteOptions {
- type: string;
-}
-
-/**
- * Command for managing shell completions for OpenSpec CLI
+ * @returns Error message with suggestions and available schemas
*/
-export class CompletionCommand {
- private completionProvider: CompletionProvider;
-
- constructor() {
- this.completionProvider = new CompletionProvider();
+export function suggestSchemas(
+ invalidSchemaName: string,
+ availableSchemas: { name: string; isBuiltIn: boolean }[]
+): string {
+ // Simple fuzzy match: Levenshtein distance
+ function levenshtein(a: string, b: string): number {
+ const matrix: number[][] = [];
+ for (let i = 0; i <= b.length; i++) {
+ matrix[i] = [i];
+ }
+ for (let j = 0; j <= a.length; j++) {
+ matrix[0][j] = j;
+ }
+ for (let i = 1; i <= b.length; i++) {
+ for (let j = 1; j <= a.length; j++) {
+ if (b.charAt(i - 1) === a.charAt(j - 1)) {
+ matrix[i][j] = matrix[i - 1][j - 1];
+ } else {
+ matrix[i][j] = Math.min(
+ matrix[i - 1][j - 1] + 1,
+ matrix[i][j - 1] + 1,
+ matrix[i - 1][j] + 1
+ );
+ }
+ }
+ }
+ return matrix[b.length][a.length];
}
- /**
- * Resolve shell parameter or exit with error
- *
+
+ // Find closest matches (distance <= 3)
```
-This interface is important because it defines how OpenSpec Tutorial: Spec-Driven Workflows for AI Coding Agents implements the patterns covered in this chapter.
+This function is important because it defines how OpenSpec Tutorial: Spec-Driven Workflows for AI Coding Agents implements the patterns covered in this chapter.
-### `src/commands/completion.ts`
+### `src/core/project-config.ts`
-The `InstallOptions` interface in [`src/commands/completion.ts`](https://github.com/Fission-AI/OpenSpec/blob/HEAD/src/commands/completion.ts) handles a key part of this chapter's functionality:
+The `levenshtein` function in [`src/core/project-config.ts`](https://github.com/Fission-AI/OpenSpec/blob/HEAD/src/core/project-config.ts) handles a key part of this chapter's functionality:
```ts
-}
+): string {
+ // Simple fuzzy match: Levenshtein distance
+ function levenshtein(a: string, b: string): number {
+ const matrix: number[][] = [];
+ for (let i = 0; i <= b.length; i++) {
+ matrix[i] = [i];
+ }
+ for (let j = 0; j <= a.length; j++) {
+ matrix[0][j] = j;
+ }
+ for (let i = 1; i <= b.length; i++) {
+ for (let j = 1; j <= a.length; j++) {
+ if (b.charAt(i - 1) === a.charAt(j - 1)) {
+ matrix[i][j] = matrix[i - 1][j - 1];
+ } else {
+ matrix[i][j] = Math.min(
+ matrix[i - 1][j - 1] + 1,
+ matrix[i][j - 1] + 1,
+ matrix[i - 1][j] + 1
+ );
+ }
+ }
+ }
+ return matrix[b.length][a.length];
+ }
-interface InstallOptions {
- shell?: string;
- verbose?: boolean;
-}
+ // Find closest matches (distance <= 3)
+ const suggestions = availableSchemas
+ .map((s) => ({ ...s, distance: levenshtein(invalidSchemaName, s.name) }))
+ .filter((s) => s.distance <= 3)
+ .sort((a, b) => a.distance - b.distance)
+ .slice(0, 3);
+```
-interface UninstallOptions {
- shell?: string;
- yes?: boolean;
-}
+This function is important because it defines how OpenSpec Tutorial: Spec-Driven Workflows for AI Coding Agents implements the patterns covered in this chapter.
-interface CompleteOptions {
- type: string;
-}
+### `src/core/view.ts`
-/**
- * Command for managing shell completions for OpenSpec CLI
- */
-export class CompletionCommand {
- private completionProvider: CompletionProvider;
+The `ViewCommand` class in [`src/core/view.ts`](https://github.com/Fission-AI/OpenSpec/blob/HEAD/src/core/view.ts) handles a key part of this chapter's functionality:
- constructor() {
- this.completionProvider = new CompletionProvider();
- }
- /**
- * Resolve shell parameter or exit with error
- *
- * @param shell - The shell parameter (may be undefined)
- * @param operationName - Name of the operation (for error messages)
- * @returns Resolved shell or null if should exit
- */
+```ts
+import { MarkdownParser } from './parsers/markdown-parser.js';
+
+export class ViewCommand {
+ async execute(targetPath: string = '.'): Promise<void> {
+ const openspecDir = path.join(targetPath, 'openspec');
+
+ if (!fs.existsSync(openspecDir)) {
+ console.error(chalk.red('No openspec directory found'));
+ process.exit(1);
+ }
+
+ console.log(chalk.bold('\nOpenSpec Dashboard\n'));
+ console.log('═'.repeat(60));
+
+ // Get changes and specs data
+ const changesData = await this.getChangesData(openspecDir);
+ const specsData = await this.getSpecsData(openspecDir);
+
+ // Display summary metrics
+ this.displaySummary(changesData, specsData);
+
+ // Display draft changes
+ if (changesData.draft.length > 0) {
+ console.log(chalk.bold.gray('\nDraft Changes'));
+ console.log('─'.repeat(60));
+ changesData.draft.forEach((change) => {
+ console.log(` ${chalk.gray('○')} ${change.name}`);
+ });
+ }
+
+ // Display active changes
+ if (changesData.active.length > 0) {
```
-This interface is important because it defines how OpenSpec Tutorial: Spec-Driven Workflows for AI Coding Agents implements the patterns covered in this chapter.
+This class is important because it defines how OpenSpec Tutorial: Spec-Driven Workflows for AI Coding Agents implements the patterns covered in this chapter.
-### `src/commands/completion.ts`
+### `src/core/profile-sync-drift.ts`
-The `UninstallOptions` interface in [`src/commands/completion.ts`](https://github.com/Fission-AI/OpenSpec/blob/HEAD/src/commands/completion.ts) handles a key part of this chapter's functionality:
+The `toKnownWorkflows` function in [`src/core/profile-sync-drift.ts`](https://github.com/Fission-AI/OpenSpec/blob/HEAD/src/core/profile-sync-drift.ts) handles a key part of this chapter's functionality:
```ts
-}
-
-interface UninstallOptions {
- shell?: string;
- yes?: boolean;
-}
+};
-interface CompleteOptions {
- type: string;
+function toKnownWorkflows(workflows: readonly string[]): WorkflowId[] {
+ return workflows.filter(
+ (workflow): workflow is WorkflowId =>
+ (ALL_WORKFLOWS as readonly string[]).includes(workflow)
+ );
}
/**
- * Command for managing shell completions for OpenSpec CLI
+ * Checks whether a tool has at least one generated OpenSpec command file.
*/
-export class CompletionCommand {
- private completionProvider: CompletionProvider;
-
- constructor() {
- this.completionProvider = new CompletionProvider();
+export function toolHasAnyConfiguredCommand(projectPath: string, toolId: string): boolean {
+ const adapter = CommandAdapterRegistry.get(toolId);
+ if (!adapter) return false;
+
+ for (const commandId of COMMAND_IDS) {
+ const cmdPath = adapter.getFilePath(commandId);
+ const fullPath = path.isAbsolute(cmdPath) ? cmdPath : path.join(projectPath, cmdPath);
+ if (fs.existsSync(fullPath)) {
+ return true;
+ }
}
- /**
- * Resolve shell parameter or exit with error
- *
- * @param shell - The shell parameter (may be undefined)
- * @param operationName - Name of the operation (for error messages)
- * @returns Resolved shell or null if should exit
- */
- private resolveShellOrExit(shell: string | undefined, operationName: string): SupportedShell | null {
- const normalizedShell = this.normalizeShell(shell);
-
- if (!normalizedShell) {
- const detectionResult = detectShell();
-```
-This interface is important because it defines how OpenSpec Tutorial: Spec-Driven Workflows for AI Coding Agents implements the patterns covered in this chapter.
-
-### `src/commands/completion.ts`
-
-The `CompleteOptions` interface in [`src/commands/completion.ts`](https://github.com/Fission-AI/OpenSpec/blob/HEAD/src/commands/completion.ts) handles a key part of this chapter's functionality:
-
-```ts
-}
-
-interface CompleteOptions {
- type: string;
+ return false;
}
/**
- * Command for managing shell completions for OpenSpec CLI
+ * Returns tools with at least one generated command file on disk.
*/
-export class CompletionCommand {
- private completionProvider: CompletionProvider;
-
- constructor() {
- this.completionProvider = new CompletionProvider();
- }
- /**
- * Resolve shell parameter or exit with error
- *
- * @param shell - The shell parameter (may be undefined)
- * @param operationName - Name of the operation (for error messages)
- * @returns Resolved shell or null if should exit
- */
- private resolveShellOrExit(shell: string | undefined, operationName: string): SupportedShell | null {
- const normalizedShell = this.normalizeShell(shell);
-
- if (!normalizedShell) {
- const detectionResult = detectShell();
-
- if (detectionResult.shell && CompletionFactory.isSupported(detectionResult.shell)) {
- return detectionResult.shell;
- }
-
+export function getCommandConfiguredTools(projectPath: string): string[] {
+ return AI_TOOLS
```
-This interface is important because it defines how OpenSpec Tutorial: Spec-Driven Workflows for AI Coding Agents implements the patterns covered in this chapter.
+This function is important because it defines how OpenSpec Tutorial: Spec-Driven Workflows for AI Coding Agents implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[GenerateOptions]
- B[InstallOptions]
- C[UninstallOptions]
- D[CompleteOptions]
- E[readProjectConfig]
+ A[suggestSchemas]
+ B[levenshtein]
+ C[ViewCommand]
+ D[toKnownWorkflows]
+ E[toolHasAnyConfiguredCommand]
A --> B
B --> C
C --> D
diff --git a/tutorials/openspec-tutorial/08-migration-governance-and-team-adoption.md b/tutorials/openspec-tutorial/08-migration-governance-and-team-adoption.md
index 4bfa6831..e2f660a0 100644
--- a/tutorials/openspec-tutorial/08-migration-governance-and-team-adoption.md
+++ b/tutorials/openspec-tutorial/08-migration-governance-and-team-adoption.md
@@ -54,164 +54,168 @@ You now have an end-to-end model for running OpenSpec as part of a production en
Next: compare execution patterns with [Claude Task Master](../claude-task-master-tutorial/) and [Codex CLI](../codex-cli-tutorial/).
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/core/profile-sync-drift.ts`
+### `src/core/config-schema.ts`
-The `hasToolProfileOrDeliveryDrift` function in [`src/core/profile-sync-drift.ts`](https://github.com/Fission-AI/OpenSpec/blob/HEAD/src/core/profile-sync-drift.ts) handles a key part of this chapter's functionality:
+The `getNestedValue` function in [`src/core/config-schema.ts`](https://github.com/Fission-AI/OpenSpec/blob/HEAD/src/core/config-schema.ts) handles a key part of this chapter's functionality:
```ts
- * - artifacts for workflows that were deselected from the current profile
+ * @returns The value at the path, or undefined if not found
*/
-export function hasToolProfileOrDeliveryDrift(
- projectPath: string,
- toolId: string,
- desiredWorkflows: readonly string[],
- delivery: Delivery
-): boolean {
- const tool = AI_TOOLS.find((t) => t.value === toolId);
- if (!tool?.skillsDir) return false;
-
- const knownDesiredWorkflows = toKnownWorkflows(desiredWorkflows);
- const desiredWorkflowSet = new Set<WorkflowId>(knownDesiredWorkflows);
- const skillsDir = path.join(projectPath, tool.skillsDir, 'skills');
- const adapter = CommandAdapterRegistry.get(toolId);
- const shouldGenerateSkills = delivery !== 'commands';
- const shouldGenerateCommands = delivery !== 'skills';
-
- if (shouldGenerateSkills) {
- for (const workflow of knownDesiredWorkflows) {
- const dirName = WORKFLOW_TO_SKILL_DIR[workflow];
- const skillFile = path.join(skillsDir, dirName, 'SKILL.md');
- if (!fs.existsSync(skillFile)) {
- return true;
- }
+export function getNestedValue(obj: Record<string, unknown>, path: string): unknown {
+ const keys = path.split('.');
+ let current: unknown = obj;
+
+ for (const key of keys) {
+ if (current === null || current === undefined) {
+ return undefined;
}
+ if (typeof current !== 'object') {
+ return undefined;
+ }
+ current = (current as Record<string, unknown>)[key];
+ }
+
+ return current;
+}
+
+/**
+ * Set a nested value in an object using dot notation.
+ * Creates intermediate objects as needed.
+ *
+ * @param obj - The object to modify (mutated in place)
+ * @param path - Dot-separated path (e.g., "featureFlags.someFlag")
+ * @param value - The value to set
+ */
+export function setNestedValue(obj: Record<string, unknown>, path: string, value: unknown): void {
+ const keys = path.split('.');
+ let current: Record<string, unknown> = obj;
- // Deselecting workflows in a profile should trigger sync.
- for (const workflow of ALL_WORKFLOWS) {
- if (desiredWorkflowSet.has(workflow)) continue;
- const dirName = WORKFLOW_TO_SKILL_DIR[workflow];
- const skillDir = path.join(skillsDir, dirName);
+ for (let i = 0; i < keys.length - 1; i++) {
```
This function is important because it defines how OpenSpec Tutorial: Spec-Driven Workflows for AI Coding Agents implements the patterns covered in this chapter.
-### `src/core/profile-sync-drift.ts`
+### `src/core/config-schema.ts`
-The `getToolsNeedingProfileSync` function in [`src/core/profile-sync-drift.ts`](https://github.com/Fission-AI/OpenSpec/blob/HEAD/src/core/profile-sync-drift.ts) handles a key part of this chapter's functionality:
+The `setNestedValue` function in [`src/core/config-schema.ts`](https://github.com/Fission-AI/OpenSpec/blob/HEAD/src/core/config-schema.ts) handles a key part of this chapter's functionality:
```ts
- * Returns configured tools that currently need a profile/delivery sync.
+ * @param value - The value to set
*/
-export function getToolsNeedingProfileSync(
- projectPath: string,
- desiredWorkflows: readonly string[],
- delivery: Delivery,
- configuredTools?: readonly string[]
-): string[] {
- const tools = configuredTools ? [...new Set(configuredTools)] : getConfiguredToolsForProfileSync(projectPath);
- return tools.filter((toolId) =>
- hasToolProfileOrDeliveryDrift(projectPath, toolId, desiredWorkflows, delivery)
- );
+export function setNestedValue(obj: Record<string, unknown>, path: string, value: unknown): void {
+ const keys = path.split('.');
+ let current: Record<string, unknown> = obj;
+
+ for (let i = 0; i < keys.length - 1; i++) {
+ const key = keys[i];
+ if (current[key] === undefined || current[key] === null || typeof current[key] !== 'object') {
+ current[key] = {};
+ }
+ current = current[key] as Record<string, unknown>;
+ }
+
+ const lastKey = keys[keys.length - 1];
+ current[lastKey] = value;
}
-function getInstalledWorkflowsForTool(
- projectPath: string,
- toolId: string,
- options: { includeSkills: boolean; includeCommands: boolean }
-): WorkflowId[] {
- const tool = AI_TOOLS.find((t) => t.value === toolId);
- if (!tool?.skillsDir) return [];
-
- const installed = new Set<WorkflowId>();
- const skillsDir = path.join(projectPath, tool.skillsDir, 'skills');
-
- if (options.includeSkills) {
- for (const workflow of ALL_WORKFLOWS) {
- const dirName = WORKFLOW_TO_SKILL_DIR[workflow];
- const skillFile = path.join(skillsDir, dirName, 'SKILL.md');
- if (fs.existsSync(skillFile)) {
- installed.add(workflow);
- }
+/**
+ * Delete a nested value from an object using dot notation.
+ *
+ * @param obj - The object to modify (mutated in place)
+ * @param path - Dot-separated path (e.g., "featureFlags.someFlag")
+ * @returns true if the key existed and was deleted, false otherwise
+ */
+export function deleteNestedValue(obj: Record<string, unknown>, path: string): boolean {
+ const keys = path.split('.');
+ let current: Record<string, unknown> = obj;
+
+ for (let i = 0; i < keys.length - 1; i++) {
+ const key = keys[i];
+ if (current[key] === undefined || current[key] === null || typeof current[key] !== 'object') {
```
This function is important because it defines how OpenSpec Tutorial: Spec-Driven Workflows for AI Coding Agents implements the patterns covered in this chapter.
-### `src/core/profile-sync-drift.ts`
+### `src/core/config-schema.ts`
-The `getInstalledWorkflowsForTool` function in [`src/core/profile-sync-drift.ts`](https://github.com/Fission-AI/OpenSpec/blob/HEAD/src/core/profile-sync-drift.ts) handles a key part of this chapter's functionality:
+The `deleteNestedValue` function in [`src/core/config-schema.ts`](https://github.com/Fission-AI/OpenSpec/blob/HEAD/src/core/config-schema.ts) handles a key part of this chapter's functionality:
```ts
-}
-
-function getInstalledWorkflowsForTool(
- projectPath: string,
- toolId: string,
- options: { includeSkills: boolean; includeCommands: boolean }
-): WorkflowId[] {
- const tool = AI_TOOLS.find((t) => t.value === toolId);
- if (!tool?.skillsDir) return [];
-
- const installed = new Set<WorkflowId>();
- const skillsDir = path.join(projectPath, tool.skillsDir, 'skills');
-
- if (options.includeSkills) {
- for (const workflow of ALL_WORKFLOWS) {
- const dirName = WORKFLOW_TO_SKILL_DIR[workflow];
- const skillFile = path.join(skillsDir, dirName, 'SKILL.md');
- if (fs.existsSync(skillFile)) {
- installed.add(workflow);
- }
+ * @returns true if the key existed and was deleted, false otherwise
+ */
+export function deleteNestedValue(obj: Record<string, unknown>, path: string): boolean {
+ const keys = path.split('.');
+ let current: Record<string, unknown> = obj;
+
+ for (let i = 0; i < keys.length - 1; i++) {
+ const key = keys[i];
+ if (current[key] === undefined || current[key] === null || typeof current[key] !== 'object') {
+ return false;
}
+ current = current[key] as Record<string, unknown>;
}
- if (options.includeCommands) {
- const adapter = CommandAdapterRegistry.get(toolId);
- if (adapter) {
- for (const workflow of ALL_WORKFLOWS) {
- const cmdPath = adapter.getFilePath(workflow);
- const fullPath = path.isAbsolute(cmdPath) ? cmdPath : path.join(projectPath, cmdPath);
- if (fs.existsSync(fullPath)) {
- installed.add(workflow);
- }
+ const lastKey = keys[keys.length - 1];
+ if (lastKey in current) {
+ delete current[lastKey];
+ return true;
+ }
+ return false;
+}
+
+/**
+ * Coerce a string value to its appropriate type.
+ * - "true" / "false" -> boolean
+ * - Numeric strings -> number
+ * - Everything else -> string
+ *
+ * @param value - The string value to coerce
+ * @param forceString - If true, always return the value as a string
+ * @returns The coerced value
+ */
```
This function is important because it defines how OpenSpec Tutorial: Spec-Driven Workflows for AI Coding Agents implements the patterns covered in this chapter.
-### `src/core/profile-sync-drift.ts`
+### `src/core/config-schema.ts`
-The `hasProjectConfigDrift` function in [`src/core/profile-sync-drift.ts`](https://github.com/Fission-AI/OpenSpec/blob/HEAD/src/core/profile-sync-drift.ts) handles a key part of this chapter's functionality:
+The `coerceValue` function in [`src/core/config-schema.ts`](https://github.com/Fission-AI/OpenSpec/blob/HEAD/src/core/config-schema.ts) handles a key part of this chapter's functionality:
```ts
- * Detects whether the current project has any profile/delivery drift.
+ * @returns The coerced value
*/
-export function hasProjectConfigDrift(
- projectPath: string,
- desiredWorkflows: readonly string[],
- delivery: Delivery
-): boolean {
- const configuredTools = getConfiguredToolsForProfileSync(projectPath);
- if (getToolsNeedingProfileSync(projectPath, desiredWorkflows, delivery, configuredTools).length > 0) {
- return true;
+export function coerceValue(value: string, forceString: boolean = false): string | number | boolean {
+ if (forceString) {
+ return value;
}
- const desiredSet = new Set(toKnownWorkflows(desiredWorkflows));
- const includeSkills = delivery !== 'commands';
- const includeCommands = delivery !== 'skills';
+ // Boolean coercion
+ if (value === 'true') {
+ return true;
+ }
+ if (value === 'false') {
+ return false;
+ }
- for (const toolId of configuredTools) {
- const installed = getInstalledWorkflowsForTool(projectPath, toolId, { includeSkills, includeCommands });
- if (installed.some((workflow) => !desiredSet.has(workflow))) {
- return true;
- }
+ // Number coercion - must be a valid finite number
+ const num = Number(value);
+ if (!isNaN(num) && isFinite(num) && value.trim() !== '') {
+ return num;
}
- return false;
+ return value;
}
+/**
+ * Format a value for YAML-like display.
+ *
+ * @param value - The value to format
+ * @param indent - Current indentation level
+ * @returns Formatted string
+ */
+export function formatValueYaml(value: unknown, indent: number = 0): string {
```
This function is important because it defines how OpenSpec Tutorial: Spec-Driven Workflows for AI Coding Agents implements the patterns covered in this chapter.
@@ -221,11 +225,11 @@ This function is important because it defines how OpenSpec Tutorial: Spec-Driven
```mermaid
flowchart TD
- A[hasToolProfileOrDeliveryDrift]
- B[getToolsNeedingProfileSync]
- C[getInstalledWorkflowsForTool]
- D[hasProjectConfigDrift]
- E[ChangeCommand]
+ A[getNestedValue]
+ B[setNestedValue]
+ C[deleteNestedValue]
+ D[coerceValue]
+ E[formatValueYaml]
A --> B
B --> C
C --> D
diff --git a/tutorials/openspec-tutorial/README.md b/tutorials/openspec-tutorial/README.md
index b95e80cc..2d3af5b7 100644
--- a/tutorials/openspec-tutorial/README.md
+++ b/tutorials/openspec-tutorial/README.md
@@ -29,7 +29,7 @@ This track focuses on:
## Current Snapshot (auto-updated)
- repository: [`Fission-AI/OpenSpec`](https://github.com/Fission-AI/OpenSpec)
-- stars: about **37.5k**
+- stars: about **39.3k**
- latest release: [`v1.2.0`](https://github.com/Fission-AI/OpenSpec/releases/tag/v1.2.0) (published 2026-02-23)
## Mental Model
diff --git a/tutorials/opensrc-tutorial/01-getting-started.md b/tutorials/opensrc-tutorial/01-getting-started.md
index 55fd69a8..131229ea 100644
--- a/tutorials/opensrc-tutorial/01-getting-started.md
+++ b/tutorials/opensrc-tutorial/01-getting-started.md
@@ -43,170 +43,168 @@ You now have OpenSrc running with an initial source import and index file.
Next: [Chapter 2: Input Parsing and Resolution Pipeline](02-input-parsing-and-resolution-pipeline.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/lib/git.ts`
+### `src/index.ts`
-The `getOpensrcDir` function in [`src/lib/git.ts`](https://github.com/vercel-labs/opensrc/blob/HEAD/src/lib/git.ts) handles a key part of this chapter's functionality:
+The `createProgram` function in [`src/index.ts`](https://github.com/vercel-labs/opensrc/blob/HEAD/src/index.ts) handles a key part of this chapter's functionality:
```ts
- * Get the opensrc directory path
- */
-export function getOpensrcDir(cwd: string = process.cwd()): string {
- return join(cwd, OPENSRC_DIR);
-}
-
-/**
- * Get the repos directory path
- */
-export function getReposDir(cwd: string = process.cwd()): string {
- return join(getOpensrcDir(cwd), REPOS_DIR);
-}
-
-/**
- * Extract host/owner/repo from a git URL
- */
-export function parseRepoUrl(
- url: string,
-): { host: string; owner: string; repo: string } | null {
- // Handle HTTPS URLs: https://github.com/owner/repo
- const httpsMatch = url.match(/https?:\/\/([^/]+)\/([^/]+)\/([^/]+)/);
- if (httpsMatch) {
- return {
- host: httpsMatch[1],
- owner: httpsMatch[2],
- repo: httpsMatch[3].replace(/\.git$/, ""),
- };
- }
-
- // Handle SSH URLs: git@github.com:owner/repo.git
- const sshMatch = url.match(/git@([^:]+):([^/]+)\/(.+)/);
- if (sshMatch) {
+const pkg = require("../package.json") as { version: string };
+
+export function createProgram(): Command {
+ const program = new Command();
+
+ program
+ .name("opensrc")
+ .description(
+ "Fetch source code for packages to give coding agents deeper context",
+ )
+ .version(pkg.version)
+ .enablePositionalOptions();
+
+ // Default command: fetch packages
+ program
+ .argument(
+ "[packages...]",
+ "packages or repos to fetch (e.g., zod, pypi:requests, crates:serde, owner/repo)",
+ )
+ .option("--cwd <path>", "working directory (default: current directory)")
+ .option(
+ "--modify [value]",
+ "allow/deny modifying .gitignore, tsconfig.json, AGENTS.md",
+ (val) => {
+ if (val === undefined || val === "" || val === "true") return true;
+ if (val === "false") return false;
+ return true;
+ },
+ )
+ .action(
+ async (
+ packages: string[],
```
This function is important because it defines how OpenSrc Tutorial: Deep Source Context for Coding Agents implements the patterns covered in this chapter.
-### `src/lib/git.ts`
+### `src/commands/fetch.ts`
-The `getReposDir` function in [`src/lib/git.ts`](https://github.com/vercel-labs/opensrc/blob/HEAD/src/lib/git.ts) handles a key part of this chapter's functionality:
+The `checkFileModificationPermission` function in [`src/commands/fetch.ts`](https://github.com/vercel-labs/opensrc/blob/HEAD/src/commands/fetch.ts) handles a key part of this chapter's functionality:
```ts
- * Get the repos directory path
- */
-export function getReposDir(cwd: string = process.cwd()): string {
- return join(getOpensrcDir(cwd), REPOS_DIR);
-}
-
-/**
- * Extract host/owner/repo from a git URL
+ * Check if file modifications are allowed
*/
-export function parseRepoUrl(
- url: string,
-): { host: string; owner: string; repo: string } | null {
- // Handle HTTPS URLs: https://github.com/owner/repo
- const httpsMatch = url.match(/https?:\/\/([^/]+)\/([^/]+)\/([^/]+)/);
- if (httpsMatch) {
- return {
- host: httpsMatch[1],
- owner: httpsMatch[2],
- repo: httpsMatch[3].replace(/\.git$/, ""),
- };
+async function checkFileModificationPermission(
+ cwd: string,
+ cliOverride?: boolean,
+): Promise<boolean> {
+ if (cliOverride !== undefined) {
+ await setFileModificationPermission(cliOverride, cwd);
+ if (cliOverride) {
+ console.log("✓ File modifications enabled (--modify)");
+ } else {
+ console.log("✗ File modifications disabled (--modify=false)");
+ }
+ return cliOverride;
}
- // Handle SSH URLs: git@github.com:owner/repo.git
- const sshMatch = url.match(/git@([^:]+):([^/]+)\/(.+)/);
- if (sshMatch) {
- return {
- host: sshMatch[1],
- owner: sshMatch[2],
- repo: sshMatch[3].replace(/\.git$/, ""),
- };
+ const storedPermission = await getFileModificationPermission(cwd);
+ if (storedPermission !== undefined) {
+ return storedPermission;
}
+ console.log(
+ "\nopensrc can update the following files for better integration:",
+ );
+ console.log(" • .gitignore - add opensrc/ to ignore list");
+ console.log(" • tsconfig.json - exclude opensrc/ from compilation");
+ console.log(" • AGENTS.md - add source code reference section\n");
+
+ const allowed = await confirm("Allow opensrc to modify these files?");
+
+ await setFileModificationPermission(allowed, cwd);
+
```
This function is important because it defines how OpenSrc Tutorial: Deep Source Context for Coding Agents implements the patterns covered in this chapter.
-### `src/lib/git.ts`
+### `src/commands/fetch.ts`
-The `parseRepoUrl` function in [`src/lib/git.ts`](https://github.com/vercel-labs/opensrc/blob/HEAD/src/lib/git.ts) handles a key part of this chapter's functionality:
+The `getRegistryLabel` function in [`src/commands/fetch.ts`](https://github.com/vercel-labs/opensrc/blob/HEAD/src/commands/fetch.ts) handles a key part of this chapter's functionality:
```ts
- * Extract host/owner/repo from a git URL
+ * Get registry display name
*/
-export function parseRepoUrl(
- url: string,
-): { host: string; owner: string; repo: string } | null {
- // Handle HTTPS URLs: https://github.com/owner/repo
- const httpsMatch = url.match(/https?:\/\/([^/]+)\/([^/]+)\/([^/]+)/);
- if (httpsMatch) {
- return {
- host: httpsMatch[1],
- owner: httpsMatch[2],
- repo: httpsMatch[3].replace(/\.git$/, ""),
- };
+function getRegistryLabel(registry: Registry): string {
+ switch (registry) {
+ case "npm":
+ return "npm";
+ case "pypi":
+ return "PyPI";
+ case "crates":
+ return "crates.io";
}
+}
+
+/**
+ * Fetch a git repository
+ */
+async function fetchRepoInput(spec: string, cwd: string): Promise<FetchResult> {
+ const repoSpec = parseRepoSpec(spec);
- // Handle SSH URLs: git@github.com:owner/repo.git
- const sshMatch = url.match(/git@([^:]+):([^/]+)\/(.+)/);
- if (sshMatch) {
+ if (!repoSpec) {
return {
- host: sshMatch[1],
- owner: sshMatch[2],
- repo: sshMatch[3].replace(/\.git$/, ""),
+ package: spec,
+ version: "",
+ path: "",
+ success: false,
+ error: `Invalid repository format: ${spec}`,
};
}
- return null;
-}
-
-/**
- * Get the path where a repo's source will be stored
- */
-export function getRepoPath(
+ const displayName = `${repoSpec.host}/${repoSpec.owner}/${repoSpec.repo}`;
+ console.log(
+ `\nFetching ${repoSpec.owner}/${repoSpec.repo} from ${repoSpec.host}...`,
```
This function is important because it defines how OpenSrc Tutorial: Deep Source Context for Coding Agents implements the patterns covered in this chapter.
-### `src/lib/git.ts`
+### `src/commands/fetch.ts`
-The `getRepoPath` function in [`src/lib/git.ts`](https://github.com/vercel-labs/opensrc/blob/HEAD/src/lib/git.ts) handles a key part of this chapter's functionality:
+The `fetchRepoInput` function in [`src/commands/fetch.ts`](https://github.com/vercel-labs/opensrc/blob/HEAD/src/commands/fetch.ts) handles a key part of this chapter's functionality:
```ts
- * Get the path where a repo's source will be stored
+ * Fetch a git repository
*/
-export function getRepoPath(
- displayName: string,
- cwd: string = process.cwd(),
-): string {
- return join(getReposDir(cwd), displayName);
-}
+async function fetchRepoInput(spec: string, cwd: string): Promise<FetchResult> {
+ const repoSpec = parseRepoSpec(spec);
-/**
- * Get the relative path for a repo (for sources.json)
- */
-export function getRepoRelativePath(displayName: string): string {
- return `${REPOS_DIR}/${displayName}`;
-}
-
-/**
- * Get repo display name from URL
- */
-export function getRepoDisplayName(repoUrl: string): string | null {
- const parsed = parseRepoUrl(repoUrl);
- if (!parsed) return null;
- return `${parsed.host}/${parsed.owner}/${parsed.repo}`;
-}
+ if (!repoSpec) {
+ return {
+ package: spec,
+ version: "",
+ path: "",
+ success: false,
+ error: `Invalid repository format: ${spec}`,
+ };
+ }
-interface PackageEntry {
- name: string;
- version: string;
- registry: Registry;
- path: string;
- fetchedAt: string;
-}
+ const displayName = `${repoSpec.host}/${repoSpec.owner}/${repoSpec.repo}`;
+ console.log(
+ `\nFetching ${repoSpec.owner}/${repoSpec.repo} from ${repoSpec.host}...`,
+ );
+
+ try {
+ // Check if already exists with the same ref
+ if (repoExists(displayName, cwd)) {
+ const existing = await getRepoInfo(displayName, cwd);
+ if (existing && repoSpec.ref && existing.version === repoSpec.ref) {
+ console.log(` ✓ Already up to date (${repoSpec.ref})`);
+ return {
+ package: displayName,
+ version: existing.version,
+ path: getRepoRelativePath(displayName),
+ success: true,
+ };
```
This function is important because it defines how OpenSrc Tutorial: Deep Source Context for Coding Agents implements the patterns covered in this chapter.
@@ -216,11 +214,11 @@ This function is important because it defines how OpenSrc Tutorial: Deep Source
```mermaid
flowchart TD
- A[getOpensrcDir]
- B[getReposDir]
- C[parseRepoUrl]
- D[getRepoPath]
- E[getRepoRelativePath]
+ A[createProgram]
+ B[checkFileModificationPermission]
+ C[getRegistryLabel]
+ D[fetchRepoInput]
+ E[fetchPackageInput]
A --> B
B --> C
C --> D
diff --git a/tutorials/opensrc-tutorial/02-input-parsing-and-resolution-pipeline.md b/tutorials/opensrc-tutorial/02-input-parsing-and-resolution-pipeline.md
index b89f7776..d0d533f8 100644
--- a/tutorials/opensrc-tutorial/02-input-parsing-and-resolution-pipeline.md
+++ b/tutorials/opensrc-tutorial/02-input-parsing-and-resolution-pipeline.md
@@ -40,170 +40,135 @@ You now understand how OpenSrc classifies and routes each input before fetching.
Next: [Chapter 3: Multi-Registry Package Fetching](03-multi-registry-package-fetching.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/lib/git.ts`
+### `src/types.ts`
-The `fetchRepoSource` function in [`src/lib/git.ts`](https://github.com/vercel-labs/opensrc/blob/HEAD/src/lib/git.ts) handles a key part of this chapter's functionality:
+The `PackageSpec` interface in [`src/types.ts`](https://github.com/vercel-labs/opensrc/blob/HEAD/src/types.ts) handles a key part of this chapter's functionality:
```ts
- * Fetch source code for a resolved repository
+ * Parsed package specification with registry
*/
-export async function fetchRepoSource(
- resolved: ResolvedRepo,
- cwd: string = process.cwd(),
-): Promise<FetchResult> {
- const git = simpleGit();
- const repoPath = getRepoPath(resolved.displayName, cwd);
- const reposDir = getReposDir(cwd);
-
- // Ensure repos directory exists
- if (!existsSync(reposDir)) {
- await mkdir(reposDir, { recursive: true });
- }
-
- // Remove existing if present
- if (existsSync(repoPath)) {
- await rm(repoPath, { recursive: true, force: true });
- }
+export interface PackageSpec {
+ registry: Registry;
+ name: string;
+ version?: string;
+}
- // Ensure parent directories exist (for host/owner structure)
- const parentDir = join(repoPath, "..");
- if (!existsSync(parentDir)) {
- await mkdir(parentDir, { recursive: true });
- }
+/**
+ * Resolved repository information (for git repos)
+ */
+export interface ResolvedRepo {
+ host: string; // e.g., "github.com", "gitlab.com"
+ owner: string;
+ repo: string;
+ ref: string; // branch, tag, or commit (resolved)
+ repoUrl: string;
+ displayName: string; // e.g., "github.com/owner/repo"
+}
- // Clone the repository
- const cloneResult = await cloneAtRef(
- git,
- resolved.repoUrl,
- repoPath,
- resolved.ref,
```
-This function is important because it defines how OpenSrc Tutorial: Deep Source Context for Coding Agents implements the patterns covered in this chapter.
+This interface is important because it defines how OpenSrc Tutorial: Deep Source Context for Coding Agents implements the patterns covered in this chapter.
-### `src/lib/git.ts`
+### `src/types.ts`
-The `extractRepoPath` function in [`src/lib/git.ts`](https://github.com/vercel-labs/opensrc/blob/HEAD/src/lib/git.ts) handles a key part of this chapter's functionality:
+The `ResolvedRepo` interface in [`src/types.ts`](https://github.com/vercel-labs/opensrc/blob/HEAD/src/types.ts) handles a key part of this chapter's functionality:
```ts
- * e.g., "repos/github.com/owner/repo/packages/sub" -> "repos/github.com/owner/repo"
+ * Resolved repository information (for git repos)
*/
-function extractRepoPath(fullPath: string): string {
- const parts = fullPath.split("/");
- // repos/host/owner/repo = 4 parts minimum
- if (parts.length >= 4 && parts[0] === "repos") {
- return parts.slice(0, 4).join("/");
- }
- return fullPath;
+export interface ResolvedRepo {
+ host: string; // e.g., "github.com", "gitlab.com"
+ owner: string;
+ repo: string;
+ ref: string; // branch, tag, or commit (resolved)
+ repoUrl: string;
+ displayName: string; // e.g., "github.com/owner/repo"
}
-/**
- * Remove source code for a package (removes its repo if no other packages use it)
- */
-export async function removePackageSource(
- packageName: string,
- cwd: string = process.cwd(),
- registry: Registry = "npm",
-): Promise<{ removed: boolean; repoRemoved: boolean }> {
- const sources = await readSourcesJson(cwd);
- if (!sources?.packages) {
- return { removed: false, repoRemoved: false };
- }
-
- const pkg = sources.packages.find(
- (p) => p.name === packageName && p.registry === registry,
- );
- if (!pkg) {
- return { removed: false, repoRemoved: false };
- }
-
- const pkgRepoPath = extractRepoPath(pkg.path);
```
-This function is important because it defines how OpenSrc Tutorial: Deep Source Context for Coding Agents implements the patterns covered in this chapter.
+This interface is important because it defines how OpenSrc Tutorial: Deep Source Context for Coding Agents implements the patterns covered in this chapter.
### `src/lib/git.ts`
-The `removePackageSource` function in [`src/lib/git.ts`](https://github.com/vercel-labs/opensrc/blob/HEAD/src/lib/git.ts) handles a key part of this chapter's functionality:
+The `getOpensrcDir` function in [`src/lib/git.ts`](https://github.com/vercel-labs/opensrc/blob/HEAD/src/lib/git.ts) handles a key part of this chapter's functionality:
```ts
- * Remove source code for a package (removes its repo if no other packages use it)
+ * Get the opensrc directory path
*/
-export async function removePackageSource(
- packageName: string,
- cwd: string = process.cwd(),
- registry: Registry = "npm",
-): Promise<{ removed: boolean; repoRemoved: boolean }> {
- const sources = await readSourcesJson(cwd);
- if (!sources?.packages) {
- return { removed: false, repoRemoved: false };
- }
-
- const pkg = sources.packages.find(
- (p) => p.name === packageName && p.registry === registry,
- );
- if (!pkg) {
- return { removed: false, repoRemoved: false };
- }
-
- const pkgRepoPath = extractRepoPath(pkg.path);
+export function getOpensrcDir(cwd: string = process.cwd()): string {
+ return join(cwd, OPENSRC_DIR);
+}
- // Check if other packages use the same repo
- const otherPackagesUsingSameRepo = sources.packages.filter(
- (p) =>
- extractRepoPath(p.path) === pkgRepoPath &&
- !(p.name === packageName && p.registry === registry),
- );
+/**
+ * Get the repos directory path
+ */
+export function getReposDir(cwd: string = process.cwd()): string {
+ return join(getOpensrcDir(cwd), REPOS_DIR);
+}
- let repoRemoved = false;
+/**
+ * Extract host/owner/repo from a git URL
+ */
+export function parseRepoUrl(
+ url: string,
+): { host: string; owner: string; repo: string } | null {
+ // Handle HTTPS URLs: https://github.com/owner/repo
+ const httpsMatch = url.match(/https?:\/\/([^/]+)\/([^/]+)\/([^/]+)/);
+ if (httpsMatch) {
+ return {
+ host: httpsMatch[1],
+ owner: httpsMatch[2],
+ repo: httpsMatch[3].replace(/\.git$/, ""),
+ };
+ }
- // Only remove the repo if no other packages use it
- if (otherPackagesUsingSameRepo.length === 0) {
+ // Handle SSH URLs: git@github.com:owner/repo.git
+ const sshMatch = url.match(/git@([^:]+):([^/]+)\/(.+)/);
+ if (sshMatch) {
```
This function is important because it defines how OpenSrc Tutorial: Deep Source Context for Coding Agents implements the patterns covered in this chapter.
### `src/lib/git.ts`
-The `removeRepoSource` function in [`src/lib/git.ts`](https://github.com/vercel-labs/opensrc/blob/HEAD/src/lib/git.ts) handles a key part of this chapter's functionality:
+The `getReposDir` function in [`src/lib/git.ts`](https://github.com/vercel-labs/opensrc/blob/HEAD/src/lib/git.ts) handles a key part of this chapter's functionality:
```ts
- * Remove source code for a repo
+ * Get the repos directory path
*/
-export async function removeRepoSource(
- displayName: string,
- cwd: string = process.cwd(),
-): Promise<boolean> {
- const repoPath = getRepoPath(displayName, cwd);
-
- if (!existsSync(repoPath)) {
- return false;
- }
-
- await rm(repoPath, { recursive: true, force: true });
-
- // Clean up empty parent directories
- await cleanupEmptyParentDirs(getRepoRelativePath(displayName), cwd);
-
- return true;
+export function getReposDir(cwd: string = process.cwd()): string {
+ return join(getOpensrcDir(cwd), REPOS_DIR);
}
/**
- * Clean up empty parent directories after removing a repo
+ * Extract host/owner/repo from a git URL
*/
-async function cleanupEmptyParentDirs(
- relativePath: string,
- cwd: string,
-): Promise<void> {
- const parts = relativePath.split("/");
- if (parts.length < 4) return; // repos/host/owner/repo - need at least 4 parts
-
- const { readdir } = await import("fs/promises");
- const opensrcDir = getOpensrcDir(cwd);
+export function parseRepoUrl(
+ url: string,
+): { host: string; owner: string; repo: string } | null {
+ // Handle HTTPS URLs: https://github.com/owner/repo
+ const httpsMatch = url.match(/https?:\/\/([^/]+)\/([^/]+)\/([^/]+)/);
+ if (httpsMatch) {
+ return {
+ host: httpsMatch[1],
+ owner: httpsMatch[2],
+ repo: httpsMatch[3].replace(/\.git$/, ""),
+ };
+ }
+
+ // Handle SSH URLs: git@github.com:owner/repo.git
+ const sshMatch = url.match(/git@([^:]+):([^/]+)\/(.+)/);
+ if (sshMatch) {
+ return {
+ host: sshMatch[1],
+ owner: sshMatch[2],
+ repo: sshMatch[3].replace(/\.git$/, ""),
+ };
+ }
+
```
This function is important because it defines how OpenSrc Tutorial: Deep Source Context for Coding Agents implements the patterns covered in this chapter.
@@ -213,11 +178,11 @@ This function is important because it defines how OpenSrc Tutorial: Deep Source
```mermaid
flowchart TD
- A[fetchRepoSource]
- B[extractRepoPath]
- C[removePackageSource]
- D[removeRepoSource]
- E[cleanupEmptyParentDirs]
+ A[PackageSpec]
+ B[ResolvedRepo]
+ C[getOpensrcDir]
+ D[getReposDir]
+ E[parseRepoUrl]
A --> B
B --> C
C --> D
diff --git a/tutorials/opensrc-tutorial/03-multi-registry-package-fetching.md b/tutorials/opensrc-tutorial/03-multi-registry-package-fetching.md
index c37050d7..70889adc 100644
--- a/tutorials/opensrc-tutorial/03-multi-registry-package-fetching.md
+++ b/tutorials/opensrc-tutorial/03-multi-registry-package-fetching.md
@@ -47,175 +47,182 @@ You now have a model for how OpenSrc maps package ecosystems to repository sourc
Next: [Chapter 4: Git Repository Source Imports](04-git-repository-source-imports.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/lib/repo.ts`
+### `src/lib/git.ts`
-The `displayNameToSpec` function in [`src/lib/repo.ts`](https://github.com/vercel-labs/opensrc/blob/HEAD/src/lib/repo.ts) handles a key part of this chapter's functionality:
+The `cloneAtRef` function in [`src/lib/git.ts`](https://github.com/vercel-labs/opensrc/blob/HEAD/src/lib/git.ts) handles a key part of this chapter's functionality:
```ts
- * Convert a repo display name back to host/owner/repo format
+ * Clone a repository at a specific ref (branch, tag, or commit)
*/
-export function displayNameToSpec(displayName: string): {
- host: string;
- owner: string;
- repo: string;
-} | null {
- const parts = displayName.split("/");
- if (parts.length !== 3) {
- return null;
+async function cloneAtRef(
+ git: SimpleGit,
+ repoUrl: string,
+ targetPath: string,
+ ref: string,
+): Promise<{ success: boolean; ref?: string; error?: string }> {
+ try {
+ await git.clone(repoUrl, targetPath, [
+ "--depth",
+ "1",
+ "--branch",
+ ref,
+ "--single-branch",
+ ]);
+ return { success: true, ref };
+ } catch {
+ // Ref might be a commit or doesn't exist as a branch/tag
}
- return { host: parts[0], owner: parts[1], repo: parts[2] };
-}
-/**
- * @deprecated Use displayNameToSpec instead
- */
-export function displayNameToOwnerRepo(displayName: string): {
- owner: string;
- repo: string;
-} | null {
- // Handle old format: owner--repo
- if (displayName.includes("--") && !displayName.includes("/")) {
- const parts = displayName.split("--");
- if (parts.length !== 2) {
- return null;
- }
- return { owner: parts[0], repo: parts[1] };
- }
-
- // Handle new format: host/owner/repo
- const spec = displayNameToSpec(displayName);
+ // Clone default branch
+ try {
+ await git.clone(repoUrl, targetPath, ["--depth", "1"]);
+ return {
+ success: true,
+ ref: "HEAD",
+ error: `Could not find ref "${ref}", cloned default branch instead`,
+ };
+ } catch (err) {
+ return {
+ success: false,
```
This function is important because it defines how OpenSrc Tutorial: Deep Source Context for Coding Agents implements the patterns covered in this chapter.
-### `src/lib/repo.ts`
+### `src/lib/git.ts`
-The `displayNameToOwnerRepo` function in [`src/lib/repo.ts`](https://github.com/vercel-labs/opensrc/blob/HEAD/src/lib/repo.ts) handles a key part of this chapter's functionality:
+The `fetchSource` function in [`src/lib/git.ts`](https://github.com/vercel-labs/opensrc/blob/HEAD/src/lib/git.ts) handles a key part of this chapter's functionality:
```ts
- * @deprecated Use displayNameToSpec instead
+ * Fetch source code for a resolved package
*/
-export function displayNameToOwnerRepo(displayName: string): {
- owner: string;
- repo: string;
-} | null {
- // Handle old format: owner--repo
- if (displayName.includes("--") && !displayName.includes("/")) {
- const parts = displayName.split("--");
- if (parts.length !== 2) {
- return null;
- }
- return { owner: parts[0], repo: parts[1] };
+export async function fetchSource(
+ resolved: ResolvedPackage,
+ cwd: string = process.cwd(),
+): Promise<FetchResult> {
+ const git = simpleGit();
+
+ // Get repo display name from URL
+ const repoDisplayName = getRepoDisplayName(resolved.repoUrl);
+ if (!repoDisplayName) {
+ return {
+ package: resolved.name,
+ version: resolved.version,
+ path: "",
+ success: false,
+ error: `Could not parse repository URL: ${resolved.repoUrl}`,
+ registry: resolved.registry,
+ };
}
- // Handle new format: host/owner/repo
- const spec = displayNameToSpec(displayName);
- if (!spec) {
- return null;
+ const repoPath = getRepoPath(repoDisplayName, cwd);
+ const reposDir = getReposDir(cwd);
+
+ // Ensure repos directory exists
+ if (!existsSync(reposDir)) {
+ await mkdir(reposDir, { recursive: true });
}
- return { owner: spec.owner, repo: spec.repo };
-}
+ // Remove existing if present (re-fetch at potentially different version)
+ if (existsSync(repoPath)) {
+ await rm(repoPath, { recursive: true, force: true });
```
This function is important because it defines how OpenSrc Tutorial: Deep Source Context for Coding Agents implements the patterns covered in this chapter.
-### `src/lib/repo.ts`
+### `src/lib/git.ts`
-The `GitHubApiResponse` interface in [`src/lib/repo.ts`](https://github.com/vercel-labs/opensrc/blob/HEAD/src/lib/repo.ts) handles a key part of this chapter's functionality:
+The `fetchRepoSource` function in [`src/lib/git.ts`](https://github.com/vercel-labs/opensrc/blob/HEAD/src/lib/git.ts) handles a key part of this chapter's functionality:
```ts
-}
+ * Fetch source code for a resolved repository
+ */
+export async function fetchRepoSource(
+ resolved: ResolvedRepo,
+ cwd: string = process.cwd(),
+): Promise<FetchResult> {
+ const git = simpleGit();
+ const repoPath = getRepoPath(resolved.displayName, cwd);
+ const reposDir = getReposDir(cwd);
+
+ // Ensure repos directory exists
+ if (!existsSync(reposDir)) {
+ await mkdir(reposDir, { recursive: true });
+ }
-interface GitHubApiResponse {
- default_branch: string;
- clone_url: string;
- html_url: string;
-}
+ // Remove existing if present
+ if (existsSync(repoPath)) {
+ await rm(repoPath, { recursive: true, force: true });
+ }
-interface GitLabApiResponse {
- default_branch: string;
- http_url_to_repo: string;
- web_url: string;
-}
+ // Ensure parent directories exist (for host/owner structure)
+ const parentDir = join(repoPath, "..");
+ if (!existsSync(parentDir)) {
+ await mkdir(parentDir, { recursive: true });
+ }
-/**
- * Resolve a repo spec to full repository information using the appropriate API
- */
-export async function resolveRepo(spec: RepoSpec): Promise<ResolvedRepo> {
- const { host, owner, repo, ref } = spec;
-
- if (host === "github.com") {
- return resolveGitHubRepo(host, owner, repo, ref);
- } else if (host === "gitlab.com") {
- return resolveGitLabRepo(host, owner, repo, ref);
- } else {
- // For unsupported hosts, assume default branch is "main"
- return {
- host,
- owner,
- repo,
- ref: ref || "main",
- repoUrl: `https://${host}/${owner}/${repo}`,
+ // Clone the repository
+ const cloneResult = await cloneAtRef(
+ git,
+ resolved.repoUrl,
+ repoPath,
+ resolved.ref,
```
-This interface is important because it defines how OpenSrc Tutorial: Deep Source Context for Coding Agents implements the patterns covered in this chapter.
+This function is important because it defines how OpenSrc Tutorial: Deep Source Context for Coding Agents implements the patterns covered in this chapter.
-### `src/lib/repo.ts`
+### `src/lib/git.ts`
-The `GitLabApiResponse` interface in [`src/lib/repo.ts`](https://github.com/vercel-labs/opensrc/blob/HEAD/src/lib/repo.ts) handles a key part of this chapter's functionality:
+The `extractRepoPath` function in [`src/lib/git.ts`](https://github.com/vercel-labs/opensrc/blob/HEAD/src/lib/git.ts) handles a key part of this chapter's functionality:
```ts
-}
-
-interface GitLabApiResponse {
- default_branch: string;
- http_url_to_repo: string;
- web_url: string;
+ * e.g., "repos/github.com/owner/repo/packages/sub" -> "repos/github.com/owner/repo"
+ */
+function extractRepoPath(fullPath: string): string {
+ const parts = fullPath.split("/");
+ // repos/host/owner/repo = 4 parts minimum
+ if (parts.length >= 4 && parts[0] === "repos") {
+ return parts.slice(0, 4).join("/");
+ }
+ return fullPath;
}
/**
- * Resolve a repo spec to full repository information using the appropriate API
+ * Remove source code for a package (removes its repo if no other packages use it)
*/
-export async function resolveRepo(spec: RepoSpec): Promise<ResolvedRepo> {
- const { host, owner, repo, ref } = spec;
-
- if (host === "github.com") {
- return resolveGitHubRepo(host, owner, repo, ref);
- } else if (host === "gitlab.com") {
- return resolveGitLabRepo(host, owner, repo, ref);
- } else {
- // For unsupported hosts, assume default branch is "main"
- return {
- host,
- owner,
- repo,
- ref: ref || "main",
- repoUrl: `https://${host}/${owner}/${repo}`,
- displayName: `${host}/${owner}/${repo}`,
- };
+export async function removePackageSource(
+ packageName: string,
+ cwd: string = process.cwd(),
+ registry: Registry = "npm",
+): Promise<{ removed: boolean; repoRemoved: boolean }> {
+ const sources = await readSourcesJson(cwd);
+ if (!sources?.packages) {
+ return { removed: false, repoRemoved: false };
+ }
+
+ const pkg = sources.packages.find(
+ (p) => p.name === packageName && p.registry === registry,
+ );
+ if (!pkg) {
+ return { removed: false, repoRemoved: false };
}
-}
-async function resolveGitHubRepo(
+ const pkgRepoPath = extractRepoPath(pkg.path);
```
-This interface is important because it defines how OpenSrc Tutorial: Deep Source Context for Coding Agents implements the patterns covered in this chapter.
+This function is important because it defines how OpenSrc Tutorial: Deep Source Context for Coding Agents implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[displayNameToSpec]
- B[displayNameToOwnerRepo]
- C[GitHubApiResponse]
- D[GitLabApiResponse]
- E[createProgram]
+ A[cloneAtRef]
+ B[fetchSource]
+ C[fetchRepoSource]
+ D[extractRepoPath]
+ E[removePackageSource]
A --> B
B --> C
C --> D
diff --git a/tutorials/opensrc-tutorial/04-git-repository-source-imports.md b/tutorials/opensrc-tutorial/04-git-repository-source-imports.md
index f7ff2b21..c2b82973 100644
--- a/tutorials/opensrc-tutorial/04-git-repository-source-imports.md
+++ b/tutorials/opensrc-tutorial/04-git-repository-source-imports.md
@@ -44,184 +44,173 @@ You now understand how OpenSrc imports repository source directly and normalizes
Next: [Chapter 5: AGENTS.md and sources.json Integration](05-agents-md-and-sources-json-integration.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/types.ts`
+### `src/lib/repo.ts`
-The `ResolvedPackage` interface in [`src/types.ts`](https://github.com/vercel-labs/opensrc/blob/HEAD/src/types.ts) handles a key part of this chapter's functionality:
+The `resolveGitHubRepo` function in [`src/lib/repo.ts`](https://github.com/vercel-labs/opensrc/blob/HEAD/src/lib/repo.ts) handles a key part of this chapter's functionality:
```ts
-}
-
-export interface ResolvedPackage {
- registry: Registry;
- name: string;
- version: string;
- repoUrl: string;
- repoDirectory?: string;
- gitTag: string;
-}
-
-export interface FetchResult {
- package: string;
- version: string;
- path: string;
- success: boolean;
- error?: string;
- registry?: Registry;
-}
-export interface InstalledPackage {
- name: string;
- version: string;
+ if (host === "github.com") {
+ return resolveGitHubRepo(host, owner, repo, ref);
+ } else if (host === "gitlab.com") {
+ return resolveGitLabRepo(host, owner, repo, ref);
+ } else {
+ // For unsupported hosts, assume default branch is "main"
+ return {
+ host,
+ owner,
+ repo,
+ ref: ref || "main",
+ repoUrl: `https://${host}/${owner}/${repo}`,
+ displayName: `${host}/${owner}/${repo}`,
+ };
+ }
}
-/**
- * Parsed repository specification
- */
-export interface RepoSpec {
- host: string; // e.g., "github.com", "gitlab.com"
- owner: string;
- repo: string;
+async function resolveGitHubRepo(
+ host: string,
+ owner: string,
+ repo: string,
+ ref?: string,
+): Promise<ResolvedRepo> {
+ const apiUrl = `https://api.github.com/repos/${owner}/${repo}`;
+
+ const response = await fetch(apiUrl, {
+ headers: {
+ Accept: "application/vnd.github.v3+json",
+ "User-Agent": "opensrc-cli",
+ },
+ });
```
-This interface is important because it defines how OpenSrc Tutorial: Deep Source Context for Coding Agents implements the patterns covered in this chapter.
+This function is important because it defines how OpenSrc Tutorial: Deep Source Context for Coding Agents implements the patterns covered in this chapter.
-### `src/types.ts`
+### `src/lib/repo.ts`
-The `FetchResult` interface in [`src/types.ts`](https://github.com/vercel-labs/opensrc/blob/HEAD/src/types.ts) handles a key part of this chapter's functionality:
+The `resolveGitLabRepo` function in [`src/lib/repo.ts`](https://github.com/vercel-labs/opensrc/blob/HEAD/src/lib/repo.ts) handles a key part of this chapter's functionality:
```ts
+ return resolveGitHubRepo(host, owner, repo, ref);
+ } else if (host === "gitlab.com") {
+ return resolveGitLabRepo(host, owner, repo, ref);
+ } else {
+ // For unsupported hosts, assume default branch is "main"
+ return {
+ host,
+ owner,
+ repo,
+ ref: ref || "main",
+ repoUrl: `https://${host}/${owner}/${repo}`,
+ displayName: `${host}/${owner}/${repo}`,
+ };
+ }
}
-export interface FetchResult {
- package: string;
- version: string;
- path: string;
- success: boolean;
- error?: string;
- registry?: Registry;
-}
-
-export interface InstalledPackage {
- name: string;
- version: string;
-}
-
-/**
- * Parsed repository specification
- */
-export interface RepoSpec {
- host: string; // e.g., "github.com", "gitlab.com"
- owner: string;
- repo: string;
- ref?: string; // branch, tag, or commit
-}
-
-/**
- * Type of input: package (with ecosystem) or git repo
- */
-export type InputType = "package" | "repo";
-
-/**
+async function resolveGitHubRepo(
+ host: string,
+ owner: string,
+ repo: string,
+ ref?: string,
+): Promise<ResolvedRepo> {
+ const apiUrl = `https://api.github.com/repos/${owner}/${repo}`;
+
+ const response = await fetch(apiUrl, {
+ headers: {
+ Accept: "application/vnd.github.v3+json",
+ "User-Agent": "opensrc-cli",
+ },
+ });
+
+ if (!response.ok) {
```
-This interface is important because it defines how OpenSrc Tutorial: Deep Source Context for Coding Agents implements the patterns covered in this chapter.
+This function is important because it defines how OpenSrc Tutorial: Deep Source Context for Coding Agents implements the patterns covered in this chapter.
-### `src/types.ts`
+### `src/lib/repo.ts`
-The `InstalledPackage` interface in [`src/types.ts`](https://github.com/vercel-labs/opensrc/blob/HEAD/src/types.ts) handles a key part of this chapter's functionality:
+The `displayNameToSpec` function in [`src/lib/repo.ts`](https://github.com/vercel-labs/opensrc/blob/HEAD/src/lib/repo.ts) handles a key part of this chapter's functionality:
```ts
-}
-
-export interface InstalledPackage {
- name: string;
- version: string;
-}
-
-/**
- * Parsed repository specification
+ * Convert a repo display name back to host/owner/repo format
*/
-export interface RepoSpec {
- host: string; // e.g., "github.com", "gitlab.com"
+export function displayNameToSpec(displayName: string): {
+ host: string;
owner: string;
repo: string;
- ref?: string; // branch, tag, or commit
+} | null {
+ const parts = displayName.split("/");
+ if (parts.length !== 3) {
+ return null;
+ }
+ return { host: parts[0], owner: parts[1], repo: parts[2] };
}
/**
- * Type of input: package (with ecosystem) or git repo
- */
-export type InputType = "package" | "repo";
-
-/**
- * Parsed package specification with registry
+ * @deprecated Use displayNameToSpec instead
*/
-export interface PackageSpec {
- registry: Registry;
- name: string;
- version?: string;
-}
-
-/**
+export function displayNameToOwnerRepo(displayName: string): {
+ owner: string;
+ repo: string;
+} | null {
+ // Handle old format: owner--repo
+ if (displayName.includes("--") && !displayName.includes("/")) {
+ const parts = displayName.split("--");
+ if (parts.length !== 2) {
+ return null;
+ }
+ return { owner: parts[0], repo: parts[1] };
+ }
+
+ // Handle new format: host/owner/repo
+ const spec = displayNameToSpec(displayName);
```
-This interface is important because it defines how OpenSrc Tutorial: Deep Source Context for Coding Agents implements the patterns covered in this chapter.
+This function is important because it defines how OpenSrc Tutorial: Deep Source Context for Coding Agents implements the patterns covered in this chapter.
-### `src/types.ts`
+### `src/lib/repo.ts`
-The `RepoSpec` interface in [`src/types.ts`](https://github.com/vercel-labs/opensrc/blob/HEAD/src/types.ts) handles a key part of this chapter's functionality:
+The `displayNameToOwnerRepo` function in [`src/lib/repo.ts`](https://github.com/vercel-labs/opensrc/blob/HEAD/src/lib/repo.ts) handles a key part of this chapter's functionality:
```ts
- * Parsed repository specification
+ * @deprecated Use displayNameToSpec instead
*/
-export interface RepoSpec {
- host: string; // e.g., "github.com", "gitlab.com"
+export function displayNameToOwnerRepo(displayName: string): {
owner: string;
repo: string;
- ref?: string; // branch, tag, or commit
-}
-
-/**
- * Type of input: package (with ecosystem) or git repo
- */
-export type InputType = "package" | "repo";
-
-/**
- * Parsed package specification with registry
- */
-export interface PackageSpec {
- registry: Registry;
- name: string;
- version?: string;
+} | null {
+ // Handle old format: owner--repo
+ if (displayName.includes("--") && !displayName.includes("/")) {
+ const parts = displayName.split("--");
+ if (parts.length !== 2) {
+ return null;
+ }
+ return { owner: parts[0], repo: parts[1] };
+ }
+
+ // Handle new format: host/owner/repo
+ const spec = displayNameToSpec(displayName);
+ if (!spec) {
+ return null;
+ }
+ return { owner: spec.owner, repo: spec.repo };
}
-/**
- * Resolved repository information (for git repos)
- */
-export interface ResolvedRepo {
- host: string; // e.g., "github.com", "gitlab.com"
- owner: string;
- repo: string;
- ref: string; // branch, tag, or commit (resolved)
- repoUrl: string;
```
-This interface is important because it defines how OpenSrc Tutorial: Deep Source Context for Coding Agents implements the patterns covered in this chapter.
+This function is important because it defines how OpenSrc Tutorial: Deep Source Context for Coding Agents implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[ResolvedPackage]
- B[FetchResult]
- C[InstalledPackage]
- D[RepoSpec]
- E[PackageSpec]
+ A[resolveGitHubRepo]
+ B[resolveGitLabRepo]
+ C[displayNameToSpec]
+ D[displayNameToOwnerRepo]
+ E[GitHubApiResponse]
A --> B
B --> C
C --> D
diff --git a/tutorials/opensrc-tutorial/05-agents-md-and-sources-json-integration.md b/tutorials/opensrc-tutorial/05-agents-md-and-sources-json-integration.md
index eb44a7f1..2d29dc62 100644
--- a/tutorials/opensrc-tutorial/05-agents-md-and-sources-json-integration.md
+++ b/tutorials/opensrc-tutorial/05-agents-md-and-sources-json-integration.md
@@ -37,184 +37,182 @@ You now know how OpenSrc surfaces fetched sources to agent workflows without man
Next: [Chapter 6: Update, Remove, and Clean Lifecycle](06-update-remove-and-clean-lifecycle.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/lib/tsconfig.ts`
+### `src/lib/version.ts`
-The `hasOpensrcExclude` function in [`src/lib/tsconfig.ts`](https://github.com/vercel-labs/opensrc/blob/HEAD/src/lib/tsconfig.ts) handles a key part of this chapter's functionality:
+The `PackageJson` interface in [`src/lib/version.ts`](https://github.com/vercel-labs/opensrc/blob/HEAD/src/lib/version.ts) handles a key part of this chapter's functionality:
```ts
- * Check if tsconfig.json already excludes opensrc/
- */
-export async function hasOpensrcExclude(
- cwd: string = process.cwd(),
-): Promise<boolean> {
- const tsconfigPath = join(cwd, "tsconfig.json");
+import type { InstalledPackage } from "../types.js";
- if (!existsSync(tsconfigPath)) {
- return false;
- }
+interface PackageJson {
+ dependencies?: Record<string, string>;
+ devDependencies?: Record<string, string>;
+ peerDependencies?: Record<string, string>;
+}
- try {
- const content = await readFile(tsconfigPath, "utf-8");
- const config = JSON.parse(content) as TsConfig;
-
- if (!config.exclude) {
- return false;
- }
-
- return config.exclude.some(
- (entry) =>
- entry === OPENSRC_DIR ||
- entry === `${OPENSRC_DIR}/` ||
- entry === `./${OPENSRC_DIR}`,
- );
- } catch {
- return false;
- }
+interface PackageLockJson {
+ packages?: Record<string, { version?: string }>;
+ dependencies?: Record<string, { version: string }>;
}
/**
- * Add opensrc/ to tsconfig.json exclude array
-```
-
-This function is important because it defines how OpenSrc Tutorial: Deep Source Context for Coding Agents implements the patterns covered in this chapter.
-
-### `src/lib/tsconfig.ts`
-
-The `ensureTsconfigExclude` function in [`src/lib/tsconfig.ts`](https://github.com/vercel-labs/opensrc/blob/HEAD/src/lib/tsconfig.ts) handles a key part of this chapter's functionality:
-
-```ts
- * Add opensrc/ to tsconfig.json exclude array
+ * Strip version range prefixes like ^, ~, >=, etc.
*/
-export async function ensureTsconfigExclude(
- cwd: string = process.cwd(),
-): Promise<boolean> {
- const tsconfigPath = join(cwd, "tsconfig.json");
-
- if (!existsSync(tsconfigPath)) {
- return false;
- }
-
- // Already excluded
- if (await hasOpensrcExclude(cwd)) {
- return false;
- }
-
- try {
- const content = await readFile(tsconfigPath, "utf-8");
- const config = JSON.parse(content) as TsConfig;
-
- if (!config.exclude) {
- config.exclude = [];
- }
-
- config.exclude.push(OPENSRC_DIR);
+function stripVersionPrefix(version: string): string {
+ return version.replace(/^[\^~>=<]+/, "");
+}
- // Preserve formatting by using 2-space indent (most common for tsconfig)
- await writeFile(
- tsconfigPath,
- JSON.stringify(config, null, 2) + "\n",
- "utf-8",
- );
+/**
+ * Try to get installed version from node_modules
+ */
+async function getVersionFromNodeModules(
+ packageName: string,
+ cwd: string,
+): Promise<string | null> {
+ const packageJsonPath = join(
+ cwd,
+ "node_modules",
+ packageName,
+ "package.json",
```
-This function is important because it defines how OpenSrc Tutorial: Deep Source Context for Coding Agents implements the patterns covered in this chapter.
+This interface is important because it defines how OpenSrc Tutorial: Deep Source Context for Coding Agents implements the patterns covered in this chapter.
-### `src/lib/tsconfig.ts`
+### `src/lib/version.ts`
-The `TsConfig` interface in [`src/lib/tsconfig.ts`](https://github.com/vercel-labs/opensrc/blob/HEAD/src/lib/tsconfig.ts) handles a key part of this chapter's functionality:
+The `PackageLockJson` interface in [`src/lib/version.ts`](https://github.com/vercel-labs/opensrc/blob/HEAD/src/lib/version.ts) handles a key part of this chapter's functionality:
```ts
-const OPENSRC_DIR = "opensrc";
+}
-interface TsConfig {
- exclude?: string[];
- [key: string]: unknown;
+interface PackageLockJson {
+ packages?: Record<string, { version?: string }>;
+ dependencies?: Record<string, { version: string }>;
}
/**
- * Check if tsconfig.json exists
+ * Strip version range prefixes like ^, ~, >=, etc.
*/
-export function hasTsConfig(cwd: string = process.cwd()): boolean {
- return existsSync(join(cwd, "tsconfig.json"));
+function stripVersionPrefix(version: string): string {
+ return version.replace(/^[\^~>=<]+/, "");
}
/**
- * Check if tsconfig.json already excludes opensrc/
+ * Try to get installed version from node_modules
*/
-export async function hasOpensrcExclude(
- cwd: string = process.cwd(),
-): Promise<boolean> {
- const tsconfigPath = join(cwd, "tsconfig.json");
-
- if (!existsSync(tsconfigPath)) {
- return false;
+async function getVersionFromNodeModules(
+ packageName: string,
+ cwd: string,
+): Promise<string | null> {
+ const packageJsonPath = join(
+ cwd,
+ "node_modules",
+ packageName,
+ "package.json",
+ );
+
+ if (!existsSync(packageJsonPath)) {
+ return null;
}
- try {
- const content = await readFile(tsconfigPath, "utf-8");
- const config = JSON.parse(content) as TsConfig;
-
- if (!config.exclude) {
- return false;
```
This interface is important because it defines how OpenSrc Tutorial: Deep Source Context for Coding Agents implements the patterns covered in this chapter.
-### `src/commands/clean.ts`
+### `src/commands/remove.ts`
-The `cleanCommand` function in [`src/commands/clean.ts`](https://github.com/vercel-labs/opensrc/blob/HEAD/src/commands/clean.ts) handles a key part of this chapter's functionality:
+The `removeCommand` function in [`src/commands/remove.ts`](https://github.com/vercel-labs/opensrc/blob/HEAD/src/commands/remove.ts) handles a key part of this chapter's functionality:
```ts
- * Remove all fetched packages and/or repositories
+ * Remove source code for one or more packages or repositories
*/
-export async function cleanCommand(options: CleanOptions = {}): Promise<void> {
+export async function removeCommand(
+ items: string[],
+ options: RemoveOptions = {},
+): Promise<void> {
const cwd = options.cwd || process.cwd();
- const cleanPackages =
- options.packages || (!options.packages && !options.repos);
- const cleanRepos =
- options.repos || (!options.packages && !options.repos && !options.registry);
-
- let packagesRemoved = 0;
- let reposRemoved = 0;
-
- // Get current sources
- const sources = await listSources(cwd);
-
- // Remaining after clean
- let remainingPackages: PackageEntry[] = [...sources.packages];
- let remainingRepos: RepoEntry[] = [...sources.repos];
-
- // Determine which packages to remove
- let packagesToRemove: PackageEntry[] = [];
- if (cleanPackages) {
- if (options.registry) {
- packagesToRemove = sources.packages.filter(
- (p) => p.registry === options.registry,
- );
- remainingPackages = sources.packages.filter(
- (p) => p.registry !== options.registry,
- );
- } else {
- packagesToRemove = sources.packages;
- remainingPackages = [];
+ let removed = 0;
+ let notFound = 0;
+
+ // Track packages and repos to update in sources.json
+ const removedPackages: Array<{ name: string; registry: Registry }> = [];
+ const removedRepos: string[] = [];
+
+ for (const item of items) {
+ // Check if it's a repo or package based on format
+ const isRepo =
+ isRepoSpec(item) || (item.includes("/") && !item.includes(":"));
+
+ if (isRepo) {
+ // Try to remove as repo
+ // Convert formats like "vercel/vercel" to "github.com/vercel/vercel" if needed
+ let displayName = item;
+ if (item.split("/").length === 2 && !item.startsWith("http")) {
+ displayName = `github.com/${item}`;
+ }
+
+ if (!repoExists(displayName, cwd)) {
+ // Try the item as-is (might already be full path like github.com/owner/repo)
+ if (repoExists(item, cwd)) {
+ displayName = item;
+ } else {
```
This function is important because it defines how OpenSrc Tutorial: Deep Source Context for Coding Agents implements the patterns covered in this chapter.
+### `src/commands/remove.ts`
+
+The `RemoveOptions` interface in [`src/commands/remove.ts`](https://github.com/vercel-labs/opensrc/blob/HEAD/src/commands/remove.ts) handles a key part of this chapter's functionality:
+
+```ts
+import type { Registry } from "../types.js";
+
+export interface RemoveOptions {
+ cwd?: string;
+}
+
+/**
+ * Remove source code for one or more packages or repositories
+ */
+export async function removeCommand(
+ items: string[],
+ options: RemoveOptions = {},
+): Promise<void> {
+ const cwd = options.cwd || process.cwd();
+ let removed = 0;
+ let notFound = 0;
+
+ // Track packages and repos to update in sources.json
+ const removedPackages: Array<{ name: string; registry: Registry }> = [];
+ const removedRepos: string[] = [];
+
+ for (const item of items) {
+ // Check if it's a repo or package based on format
+ const isRepo =
+ isRepoSpec(item) || (item.includes("/") && !item.includes(":"));
+
+ if (isRepo) {
+ // Try to remove as repo
+ // Convert formats like "vercel/vercel" to "github.com/vercel/vercel" if needed
+ let displayName = item;
+ if (item.split("/").length === 2 && !item.startsWith("http")) {
+ displayName = `github.com/${item}`;
+```
+
+This interface is important because it defines how OpenSrc Tutorial: Deep Source Context for Coding Agents implements the patterns covered in this chapter.
+
## How These Components Connect
```mermaid
flowchart TD
- A[hasOpensrcExclude]
- B[ensureTsconfigExclude]
- C[TsConfig]
- D[cleanCommand]
- E[cleanupEmptyDirs]
+ A[PackageJson]
+ B[PackageLockJson]
+ C[removeCommand]
+ D[RemoveOptions]
+ E[getSettingsPath]
A --> B
B --> C
C --> D
diff --git a/tutorials/opensrc-tutorial/06-update-remove-and-clean-lifecycle.md b/tutorials/opensrc-tutorial/06-update-remove-and-clean-lifecycle.md
index f9aa2ec1..b9f4c461 100644
--- a/tutorials/opensrc-tutorial/06-update-remove-and-clean-lifecycle.md
+++ b/tutorials/opensrc-tutorial/06-update-remove-and-clean-lifecycle.md
@@ -41,170 +41,168 @@ You now have operational control over source import lifecycle and cache hygiene.
Next: [Chapter 7: Reliability, Rate Limits, and Version Fallbacks](07-reliability-rate-limits-and-version-fallbacks.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/lib/version.ts`
+### `src/commands/list.ts`
-The `getVersionFromNodeModules` function in [`src/lib/version.ts`](https://github.com/vercel-labs/opensrc/blob/HEAD/src/lib/version.ts) handles a key part of this chapter's functionality:
+The `listCommand` function in [`src/commands/list.ts`](https://github.com/vercel-labs/opensrc/blob/HEAD/src/commands/list.ts) handles a key part of this chapter's functionality:
```ts
- * Try to get installed version from node_modules
+ * List all fetched package sources
*/
-async function getVersionFromNodeModules(
- packageName: string,
- cwd: string,
-): Promise<string | null> {
- const packageJsonPath = join(
- cwd,
- "node_modules",
- packageName,
- "package.json",
- );
-
- if (!existsSync(packageJsonPath)) {
- return null;
+export async function listCommand(options: ListOptions = {}): Promise<void> {
+ const cwd = options.cwd || process.cwd();
+ const sources = await listSources(cwd);
+
+ const totalCount = sources.packages.length + sources.repos.length;
+
+ if (totalCount === 0) {
+ console.log("No sources fetched yet.");
+ console.log(
+ "\nUse `opensrc <package>` to fetch source code for a package.",
+ );
+ console.log("Use `opensrc <owner>/<repo>` to fetch a GitHub repository.");
+ console.log("\nSupported registries:");
+ console.log(" • npm: opensrc zod, opensrc npm:react");
+ console.log(" • PyPI: opensrc pypi:requests");
+ console.log(" • crates: opensrc crates:serde");
+ return;
}
- try {
- const content = await readFile(packageJsonPath, "utf-8");
- const pkg = JSON.parse(content) as { version?: string };
- return pkg.version || null;
- } catch {
- return null;
+ if (options.json) {
+ console.log(JSON.stringify(sources, null, 2));
+ return;
}
-}
-/**
- * Try to get installed version from package-lock.json
- */
-async function getVersionFromPackageLock(
- packageName: string,
- cwd: string,
+ // Group packages by registry for display
+ const packagesByRegistry: Record<Registry, typeof sources.packages> = {
+ npm: [],
+ pypi: [],
+ crates: [],
+ };
```
This function is important because it defines how OpenSrc Tutorial: Deep Source Context for Coding Agents implements the patterns covered in this chapter.
-### `src/lib/version.ts`
+### `src/commands/list.ts`
-The `getVersionFromPackageLock` function in [`src/lib/version.ts`](https://github.com/vercel-labs/opensrc/blob/HEAD/src/lib/version.ts) handles a key part of this chapter's functionality:
+The `ListOptions` interface in [`src/commands/list.ts`](https://github.com/vercel-labs/opensrc/blob/HEAD/src/commands/list.ts) handles a key part of this chapter's functionality:
```ts
- * Try to get installed version from package-lock.json
- */
-async function getVersionFromPackageLock(
- packageName: string,
- cwd: string,
-): Promise<string | null> {
- const lockPath = join(cwd, "package-lock.json");
-
- if (!existsSync(lockPath)) {
- return null;
- }
+import type { Registry } from "../types.js";
- try {
- const content = await readFile(lockPath, "utf-8");
- const lock = JSON.parse(content) as PackageLockJson;
+export interface ListOptions {
+ cwd?: string;
+ json?: boolean;
+}
- // npm v7+ format uses "packages"
- if (lock.packages) {
- const key = `node_modules/${packageName}`;
- if (lock.packages[key]?.version) {
- return lock.packages[key].version;
- }
- }
+const REGISTRY_LABELS: Record<Registry, string> = {
+ npm: "npm",
+ pypi: "PyPI",
+ crates: "crates.io",
+};
- // npm v6 and earlier format uses "dependencies"
- if (lock.dependencies?.[packageName]?.version) {
- return lock.dependencies[packageName].version;
- }
+/**
+ * List all fetched package sources
+ */
+export async function listCommand(options: ListOptions = {}): Promise<void> {
+ const cwd = options.cwd || process.cwd();
+ const sources = await listSources(cwd);
- return null;
- } catch {
- return null;
+ const totalCount = sources.packages.length + sources.repos.length;
+
+ if (totalCount === 0) {
+ console.log("No sources fetched yet.");
+ console.log(
+ "\nUse `opensrc <package>` to fetch source code for a package.",
+ );
+ console.log("Use `opensrc <owner>/<repo>` to fetch a GitHub repository.");
+ console.log("\nSupported registries:");
+ console.log(" • npm: opensrc zod, opensrc npm:react");
+ console.log(" • PyPI: opensrc pypi:requests");
+ console.log(" • crates: opensrc crates:serde");
```
-This function is important because it defines how OpenSrc Tutorial: Deep Source Context for Coding Agents implements the patterns covered in this chapter.
+This interface is important because it defines how OpenSrc Tutorial: Deep Source Context for Coding Agents implements the patterns covered in this chapter.
-### `src/lib/version.ts`
+### `src/lib/agents.ts`
-The `getVersionFromPnpmLock` function in [`src/lib/version.ts`](https://github.com/vercel-labs/opensrc/blob/HEAD/src/lib/version.ts) handles a key part of this chapter's functionality:
+The `getSectionContent` function in [`src/lib/agents.ts`](https://github.com/vercel-labs/opensrc/blob/HEAD/src/lib/agents.ts) handles a key part of this chapter's functionality:
```ts
- * This is a simplified parser - pnpm lockfiles are complex
+ * Get the section content (without leading newline for comparison)
*/
-async function getVersionFromPnpmLock(
- packageName: string,
- cwd: string,
-): Promise<string | null> {
- const lockPath = join(cwd, "pnpm-lock.yaml");
-
- if (!existsSync(lockPath)) {
- return null;
- }
+function getSectionContent(): string {
+ return `${SECTION_MARKER}
- try {
- const content = await readFile(lockPath, "utf-8");
+${SECTION_START}
- // Look for the package in the lockfile
- // pnpm format: 'packageName@version(peer-deps):' or 'packageName@version:'
- // We need to stop at '(' or ')' (peer deps), ':' (end of key), or quotes
- // The ')' case handles matching inside another package's peer deps like ai@6.0.6(zod@4.3.4)
- const escapedName = packageName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
- const regex = new RegExp(`['"]?${escapedName}@([^(':"\\s)]+)`, "g");
- const matches = [...content.matchAll(regex)];
+Source code for dependencies is available in \`opensrc/\` for deeper understanding of implementation details.
- if (matches.length > 0) {
- // Return the first match's version
- return matches[0][1];
- }
+See \`opensrc/sources.json\` for the list of available packages and their versions.
- return null;
- } catch {
- return null;
- }
+Use this source code when you need to understand how a package works internally, not just its types/interface.
+
+### Fetching Additional Source Code
+
+To fetch source code for a package or repository you need to understand, run:
+
+\`\`\`bash
+npx opensrc <package> # npm package (e.g., npx opensrc zod)
+npx opensrc pypi:<package> # Python package (e.g., npx opensrc pypi:requests)
+npx opensrc crates:<package> # Rust crate (e.g., npx opensrc crates:serde)
+npx opensrc <owner>/<repo> # GitHub repo (e.g., npx opensrc vercel/ai)
+\`\`\`
+
+${SECTION_END_MARKER}`;
+}
+
+export interface PackageEntry {
+ name: string;
+ version: string;
+ registry: Registry;
+ path: string;
```
This function is important because it defines how OpenSrc Tutorial: Deep Source Context for Coding Agents implements the patterns covered in this chapter.
-### `src/lib/version.ts`
+### `src/lib/agents.ts`
-The `getVersionFromYarnLock` function in [`src/lib/version.ts`](https://github.com/vercel-labs/opensrc/blob/HEAD/src/lib/version.ts) handles a key part of this chapter's functionality:
+The `updatePackageIndex` function in [`src/lib/agents.ts`](https://github.com/vercel-labs/opensrc/blob/HEAD/src/lib/agents.ts) handles a key part of this chapter's functionality:
```ts
- * Try to get version from yarn.lock
+ * Update the sources.json file in opensrc/
*/
-async function getVersionFromYarnLock(
- packageName: string,
- cwd: string,
-): Promise<string | null> {
- const lockPath = join(cwd, "yarn.lock");
-
- if (!existsSync(lockPath)) {
- return null;
- }
-
- try {
- const content = await readFile(lockPath, "utf-8");
-
- // Yarn lockfile format:
- // "packageName@^version":
- // version "actual-version"
- const escapedName = packageName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
- const regex = new RegExp(
- `"?${escapedName}@[^":\\n]+[":]?\\s*\\n\\s*version\\s+["']?([^"'\\n]+)`,
- "g",
- );
- const matches = [...content.matchAll(regex)];
-
- if (matches.length > 0) {
- return matches[0][1];
+export async function updatePackageIndex(
+ sources: {
+ packages: PackageEntry[];
+ repos: RepoEntry[];
+ },
+ cwd: string = process.cwd(),
+): Promise<void> {
+ const opensrcDir = join(cwd, OPENSRC_DIR);
+ const sourcesPath = join(opensrcDir, SOURCES_FILE);
+
+ if (sources.packages.length === 0 && sources.repos.length === 0) {
+ // Remove index file if no sources
+ if (existsSync(sourcesPath)) {
+ const { rm } = await import("fs/promises");
+ await rm(sourcesPath, { force: true });
}
+ return;
+ }
- return null;
- } catch {
- return null;
+ const index: SourcesIndex = {
+ updatedAt: new Date().toISOString(),
+ };
+
+ if (sources.packages.length > 0) {
+ index.packages = sources.packages.map((p) => ({
+ name: p.name,
+ version: p.version,
+ registry: p.registry,
+ path: p.path,
+ fetchedAt: p.fetchedAt,
```
This function is important because it defines how OpenSrc Tutorial: Deep Source Context for Coding Agents implements the patterns covered in this chapter.
@@ -214,11 +212,11 @@ This function is important because it defines how OpenSrc Tutorial: Deep Source
```mermaid
flowchart TD
- A[getVersionFromNodeModules]
- B[getVersionFromPackageLock]
- C[getVersionFromPnpmLock]
- D[getVersionFromYarnLock]
- E[getVersionFromPackageJson]
+ A[listCommand]
+ B[ListOptions]
+ C[getSectionContent]
+ D[updatePackageIndex]
+ E[hasOpensrcSection]
A --> B
B --> C
C --> D
diff --git a/tutorials/opensrc-tutorial/07-reliability-rate-limits-and-version-fallbacks.md b/tutorials/opensrc-tutorial/07-reliability-rate-limits-and-version-fallbacks.md
index f80a159e..9850aa05 100644
--- a/tutorials/opensrc-tutorial/07-reliability-rate-limits-and-version-fallbacks.md
+++ b/tutorials/opensrc-tutorial/07-reliability-rate-limits-and-version-fallbacks.md
@@ -36,184 +36,182 @@ You now understand how OpenSrc behaves under common failure modes and how to des
Next: [Chapter 8: Team Operations and Governance](08-team-operations-and-governance.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/lib/agents.ts`
+### `src/commands/clean.ts`
-The `updateAgentsMd` function in [`src/lib/agents.ts`](https://github.com/vercel-labs/opensrc/blob/HEAD/src/lib/agents.ts) handles a key part of this chapter's functionality:
+The `CleanOptions` interface in [`src/commands/clean.ts`](https://github.com/vercel-labs/opensrc/blob/HEAD/src/commands/clean.ts) handles a key part of this chapter's functionality:
```ts
- * Update AGENTS.md and the package index
- */
-export async function updateAgentsMd(
- sources: {
- packages: PackageEntry[];
- repos: RepoEntry[];
- },
- cwd: string = process.cwd(),
-): Promise<boolean> {
- // Always update the index file
- await updatePackageIndex(sources, cwd);
-
- if (sources.packages.length > 0 || sources.repos.length > 0) {
- return ensureAgentsMd(cwd);
- }
-
- return removeOpensrcSection(cwd);
+import type { Registry } from "../types.js";
+
+export interface CleanOptions {
+ cwd?: string;
+ /** Only clean packages (all registries) */
+ packages?: boolean;
+ /** Only clean repos */
+ repos?: boolean;
+ /** Only clean specific registry */
+ registry?: Registry;
}
/**
- * Remove the opensrc section from AGENTS.md
+ * Remove all fetched packages and/or repositories
*/
-export async function removeOpensrcSection(
- cwd: string = process.cwd(),
-): Promise<boolean> {
- const agentsPath = join(cwd, AGENTS_FILE);
+export async function cleanCommand(options: CleanOptions = {}): Promise<void> {
+ const cwd = options.cwd || process.cwd();
+ const cleanPackages =
+ options.packages || (!options.packages && !options.repos);
+ const cleanRepos =
+ options.repos || (!options.packages && !options.repos && !options.registry);
- if (!existsSync(agentsPath)) {
- return false;
- }
+ let packagesRemoved = 0;
+ let reposRemoved = 0;
+
+ // Get current sources
+ const sources = await listSources(cwd);
+
+ // Remaining after clean
+ let remainingPackages: PackageEntry[] = [...sources.packages];
+ let remainingRepos: RepoEntry[] = [...sources.repos];
- try {
```
-This function is important because it defines how OpenSrc Tutorial: Deep Source Context for Coding Agents implements the patterns covered in this chapter.
+This interface is important because it defines how OpenSrc Tutorial: Deep Source Context for Coding Agents implements the patterns covered in this chapter.
-### `src/lib/agents.ts`
+### `src/lib/tsconfig.ts`
-The `removeOpensrcSection` function in [`src/lib/agents.ts`](https://github.com/vercel-labs/opensrc/blob/HEAD/src/lib/agents.ts) handles a key part of this chapter's functionality:
+The `hasTsConfig` function in [`src/lib/tsconfig.ts`](https://github.com/vercel-labs/opensrc/blob/HEAD/src/lib/tsconfig.ts) handles a key part of this chapter's functionality:
```ts
- }
-
- return removeOpensrcSection(cwd);
+ * Check if tsconfig.json exists
+ */
+export function hasTsConfig(cwd: string = process.cwd()): boolean {
+ return existsSync(join(cwd, "tsconfig.json"));
}
/**
- * Remove the opensrc section from AGENTS.md
+ * Check if tsconfig.json already excludes opensrc/
*/
-export async function removeOpensrcSection(
+export async function hasOpensrcExclude(
cwd: string = process.cwd(),
): Promise<boolean> {
- const agentsPath = join(cwd, AGENTS_FILE);
+ const tsconfigPath = join(cwd, "tsconfig.json");
- if (!existsSync(agentsPath)) {
+ if (!existsSync(tsconfigPath)) {
return false;
}
try {
- const content = await readFile(agentsPath, "utf-8");
-
- if (!content.includes(SECTION_MARKER)) {
- return false;
- }
+ const content = await readFile(tsconfigPath, "utf-8");
+ const config = JSON.parse(content) as TsConfig;
- const startIdx = content.indexOf(SECTION_MARKER);
- const endIdx = content.indexOf(SECTION_END_MARKER);
-
- if (startIdx === -1 || endIdx === -1) {
+ if (!config.exclude) {
return false;
}
- const before = content.slice(0, startIdx).trimEnd();
+ return config.exclude.some(
+ (entry) =>
+ entry === OPENSRC_DIR ||
+ entry === `${OPENSRC_DIR}/` ||
+ entry === `./${OPENSRC_DIR}`,
+ );
```
This function is important because it defines how OpenSrc Tutorial: Deep Source Context for Coding Agents implements the patterns covered in this chapter.
-### `src/lib/agents.ts`
+### `src/lib/tsconfig.ts`
-The `PackageEntry` interface in [`src/lib/agents.ts`](https://github.com/vercel-labs/opensrc/blob/HEAD/src/lib/agents.ts) handles a key part of this chapter's functionality:
+The `hasOpensrcExclude` function in [`src/lib/tsconfig.ts`](https://github.com/vercel-labs/opensrc/blob/HEAD/src/lib/tsconfig.ts) handles a key part of this chapter's functionality:
```ts
-}
+ * Check if tsconfig.json already excludes opensrc/
+ */
+export async function hasOpensrcExclude(
+ cwd: string = process.cwd(),
+): Promise<boolean> {
+ const tsconfigPath = join(cwd, "tsconfig.json");
-export interface PackageEntry {
- name: string;
- version: string;
- registry: Registry;
- path: string;
- fetchedAt: string;
-}
+ if (!existsSync(tsconfigPath)) {
+ return false;
+ }
-export interface RepoEntry {
- name: string;
- version: string;
- path: string;
- fetchedAt: string;
-}
+ try {
+ const content = await readFile(tsconfigPath, "utf-8");
+ const config = JSON.parse(content) as TsConfig;
+
+ if (!config.exclude) {
+ return false;
+ }
-export interface SourcesIndex {
- packages?: PackageEntry[];
- repos?: RepoEntry[];
- updatedAt: string;
+ return config.exclude.some(
+ (entry) =>
+ entry === OPENSRC_DIR ||
+ entry === `${OPENSRC_DIR}/` ||
+ entry === `./${OPENSRC_DIR}`,
+ );
+ } catch {
+ return false;
+ }
}
/**
- * Update the sources.json file in opensrc/
- */
-export async function updatePackageIndex(
- sources: {
- packages: PackageEntry[];
- repos: RepoEntry[];
- },
- cwd: string = process.cwd(),
+ * Add opensrc/ to tsconfig.json exclude array
```
-This interface is important because it defines how OpenSrc Tutorial: Deep Source Context for Coding Agents implements the patterns covered in this chapter.
+This function is important because it defines how OpenSrc Tutorial: Deep Source Context for Coding Agents implements the patterns covered in this chapter.
-### `src/lib/agents.ts`
+### `src/lib/tsconfig.ts`
-The `RepoEntry` interface in [`src/lib/agents.ts`](https://github.com/vercel-labs/opensrc/blob/HEAD/src/lib/agents.ts) handles a key part of this chapter's functionality:
+The `ensureTsconfigExclude` function in [`src/lib/tsconfig.ts`](https://github.com/vercel-labs/opensrc/blob/HEAD/src/lib/tsconfig.ts) handles a key part of this chapter's functionality:
```ts
-}
+ * Add opensrc/ to tsconfig.json exclude array
+ */
+export async function ensureTsconfigExclude(
+ cwd: string = process.cwd(),
+): Promise<boolean> {
+ const tsconfigPath = join(cwd, "tsconfig.json");
-export interface RepoEntry {
- name: string;
- version: string;
- path: string;
- fetchedAt: string;
-}
+ if (!existsSync(tsconfigPath)) {
+ return false;
+ }
-export interface SourcesIndex {
- packages?: PackageEntry[];
- repos?: RepoEntry[];
- updatedAt: string;
-}
+ // Already excluded
+ if (await hasOpensrcExclude(cwd)) {
+ return false;
+ }
-/**
- * Update the sources.json file in opensrc/
- */
-export async function updatePackageIndex(
- sources: {
- packages: PackageEntry[];
- repos: RepoEntry[];
- },
- cwd: string = process.cwd(),
-): Promise<void> {
- const opensrcDir = join(cwd, OPENSRC_DIR);
- const sourcesPath = join(opensrcDir, SOURCES_FILE);
-
- if (sources.packages.length === 0 && sources.repos.length === 0) {
- // Remove index file if no sources
- if (existsSync(sourcesPath)) {
- const { rm } = await import("fs/promises");
+ try {
+ const content = await readFile(tsconfigPath, "utf-8");
+ const config = JSON.parse(content) as TsConfig;
+
+ if (!config.exclude) {
+ config.exclude = [];
+ }
+
+ config.exclude.push(OPENSRC_DIR);
+
+ // Preserve formatting by using 2-space indent (most common for tsconfig)
+ await writeFile(
+ tsconfigPath,
+ JSON.stringify(config, null, 2) + "\n",
+ "utf-8",
+ );
```
-This interface is important because it defines how OpenSrc Tutorial: Deep Source Context for Coding Agents implements the patterns covered in this chapter.
+This function is important because it defines how OpenSrc Tutorial: Deep Source Context for Coding Agents implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[updateAgentsMd]
- B[removeOpensrcSection]
- C[PackageEntry]
- D[RepoEntry]
- E[SourcesIndex]
+ A[CleanOptions]
+ B[hasTsConfig]
+ C[hasOpensrcExclude]
+ D[ensureTsconfigExclude]
+ E[TsConfig]
A --> B
B --> C
C --> D
diff --git a/tutorials/opensrc-tutorial/08-team-operations-and-governance.md b/tutorials/opensrc-tutorial/08-team-operations-and-governance.md
index e9f21c6c..0ad4c5b2 100644
--- a/tutorials/opensrc-tutorial/08-team-operations-and-governance.md
+++ b/tutorials/opensrc-tutorial/08-team-operations-and-governance.md
@@ -35,170 +35,168 @@ For team usage, OpenSrc works best with explicit policy on what to fetch, where
You now have a governance baseline for scaling OpenSrc usage across repositories and teams.
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/lib/registries/pypi.ts`
+### `src/lib/registries/crates.ts`
-The `PyPIResponse` interface in [`src/lib/registries/pypi.ts`](https://github.com/vercel-labs/opensrc/blob/HEAD/src/lib/registries/pypi.ts) handles a key part of this chapter's functionality:
+The `isGitRepoUrl` function in [`src/lib/registries/crates.ts`](https://github.com/vercel-labs/opensrc/blob/HEAD/src/lib/registries/crates.ts) handles a key part of this chapter's functionality:
```ts
+function extractRepoUrl(crate: CrateResponse["crate"]): string | null {
+ // Check repository field first
+ if (crate.repository && isGitRepoUrl(crate.repository)) {
+ return normalizeRepoUrl(crate.repository);
+ }
+
+ // Fall back to homepage if it's a git repo
+ if (crate.homepage && isGitRepoUrl(crate.homepage)) {
+ return normalizeRepoUrl(crate.homepage);
+ }
+
+ return null;
}
-interface PyPIResponse {
- info: {
- name: string;
- version: string;
- home_page?: string;
- project_urls?: Record<string, string>;
- project_url?: string;
- };
- releases: Record<string, PyPIRelease[]>;
+function isGitRepoUrl(url: string): boolean {
+ return (
+ url.includes("github.com") ||
+ url.includes("gitlab.com") ||
+ url.includes("bitbucket.org")
+ );
}
-/**
- * Parse a PyPI package specifier like "requests==2.31.0" into name and version
- */
-export function parsePyPISpec(spec: string): {
- name: string;
- version?: string;
-} {
- // Handle version specifiers: requests==2.31.0 or requests>=2.31.0
- const eqMatch = spec.match(/^([^=<>!~]+)==(.+)$/);
- if (eqMatch) {
- return { name: eqMatch[1].trim(), version: eqMatch[2].trim() };
- }
+function normalizeRepoUrl(url: string): string {
+ // Remove trailing slashes and common suffixes
+ return url
+ .replace(/\/+$/, "")
+ .replace(/\.git$/, "")
+ .replace(/\/tree\/.*$/, "")
+ .replace(/\/blob\/.*$/, "");
+}
- // Handle @ version specifier: requests@2.31.0
- const atIndex = spec.lastIndexOf("@");
- if (atIndex > 0) {
- return {
- name: spec.slice(0, atIndex).trim(),
- version: spec.slice(atIndex + 1).trim(),
+/**
```
-This interface is important because it defines how OpenSrc Tutorial: Deep Source Context for Coding Agents implements the patterns covered in this chapter.
+This function is important because it defines how OpenSrc Tutorial: Deep Source Context for Coding Agents implements the patterns covered in this chapter.
### `src/lib/registries/crates.ts`
-The `parseCratesSpec` function in [`src/lib/registries/crates.ts`](https://github.com/vercel-labs/opensrc/blob/HEAD/src/lib/registries/crates.ts) handles a key part of this chapter's functionality:
+The `normalizeRepoUrl` function in [`src/lib/registries/crates.ts`](https://github.com/vercel-labs/opensrc/blob/HEAD/src/lib/registries/crates.ts) handles a key part of this chapter's functionality:
```ts
- * Parse a crates.io package specifier like "serde@1.0.0" into name and version
- */
-export function parseCratesSpec(spec: string): {
- name: string;
- version?: string;
-} {
- // Handle @ version specifier: serde@1.0.0
- const atIndex = spec.lastIndexOf("@");
- if (atIndex > 0) {
- return {
- name: spec.slice(0, atIndex).trim(),
- version: spec.slice(atIndex + 1).trim(),
- };
+ // Check repository field first
+ if (crate.repository && isGitRepoUrl(crate.repository)) {
+ return normalizeRepoUrl(crate.repository);
+ }
+
+ // Fall back to homepage if it's a git repo
+ if (crate.homepage && isGitRepoUrl(crate.homepage)) {
+ return normalizeRepoUrl(crate.homepage);
}
- return { name: spec.trim() };
+ return null;
}
-/**
- * Fetch crate metadata from crates.io
- */
-async function fetchCrateInfo(crateName: string): Promise<CrateResponse> {
- const url = `${CRATES_API}/crates/${crateName}`;
+function isGitRepoUrl(url: string): boolean {
+ return (
+ url.includes("github.com") ||
+ url.includes("gitlab.com") ||
+ url.includes("bitbucket.org")
+ );
+}
- const response = await fetch(url, {
- headers: {
- Accept: "application/json",
- "User-Agent": "opensrc-cli (https://github.com/vercel-labs/opensrc)",
- },
- });
+function normalizeRepoUrl(url: string): string {
+ // Remove trailing slashes and common suffixes
+ return url
+ .replace(/\/+$/, "")
+ .replace(/\.git$/, "")
+ .replace(/\/tree\/.*$/, "")
+ .replace(/\/blob\/.*$/, "");
+}
- if (!response.ok) {
+/**
+ * Get available versions sorted by release date (newest first)
```
This function is important because it defines how OpenSrc Tutorial: Deep Source Context for Coding Agents implements the patterns covered in this chapter.
### `src/lib/registries/crates.ts`
-The `fetchCrateInfo` function in [`src/lib/registries/crates.ts`](https://github.com/vercel-labs/opensrc/blob/HEAD/src/lib/registries/crates.ts) handles a key part of this chapter's functionality:
+The `getAvailableVersions` function in [`src/lib/registries/crates.ts`](https://github.com/vercel-labs/opensrc/blob/HEAD/src/lib/registries/crates.ts) handles a key part of this chapter's functionality:
```ts
- * Fetch crate metadata from crates.io
+ * Get available versions sorted by release date (newest first)
*/
-async function fetchCrateInfo(crateName: string): Promise<CrateResponse> {
- const url = `${CRATES_API}/crates/${crateName}`;
-
- const response = await fetch(url, {
- headers: {
- Accept: "application/json",
- "User-Agent": "opensrc-cli (https://github.com/vercel-labs/opensrc)",
- },
- });
-
- if (!response.ok) {
- if (response.status === 404) {
- throw new Error(`Crate "${crateName}" not found on crates.io`);
- }
- throw new Error(
- `Failed to fetch crate info: ${response.status} ${response.statusText}`,
- );
- }
-
- return response.json() as Promise<CrateResponse>;
+function getAvailableVersions(versions: CrateVersion[]): string[] {
+ return versions
+ .filter((v) => !v.yanked)
+ .sort(
+ (a, b) =>
+ new Date(b.created_at).getTime() - new Date(a.created_at).getTime(),
+ )
+ .map((v) => v.num);
}
/**
- * Fetch specific version info from crates.io
+ * Resolve a crate to its repository information
*/
-async function fetchCrateVersionInfo(
+export async function resolveCrate(
crateName: string,
- version: string,
-): Promise<CrateVersionResponse> {
- const url = `${CRATES_API}/crates/${crateName}/${version}`;
+ version?: string,
+): Promise<ResolvedPackage> {
+ const info = await fetchCrateInfo(crateName);
+
+ // If version specified, verify it exists
+ let resolvedVersion = version || info.crate.max_version;
+
+ if (version) {
+ await fetchCrateVersionInfo(crateName, version);
+ resolvedVersion = version;
+ }
+
+ const repoUrl = extractRepoUrl(info.crate);
+
+ if (!repoUrl) {
```
This function is important because it defines how OpenSrc Tutorial: Deep Source Context for Coding Agents implements the patterns covered in this chapter.
### `src/lib/registries/crates.ts`
-The `fetchCrateVersionInfo` function in [`src/lib/registries/crates.ts`](https://github.com/vercel-labs/opensrc/blob/HEAD/src/lib/registries/crates.ts) handles a key part of this chapter's functionality:
+The `resolveCrate` function in [`src/lib/registries/crates.ts`](https://github.com/vercel-labs/opensrc/blob/HEAD/src/lib/registries/crates.ts) handles a key part of this chapter's functionality:
```ts
- * Fetch specific version info from crates.io
+ * Resolve a crate to its repository information
*/
-async function fetchCrateVersionInfo(
+export async function resolveCrate(
crateName: string,
- version: string,
-): Promise<CrateVersionResponse> {
- const url = `${CRATES_API}/crates/${crateName}/${version}`;
-
- const response = await fetch(url, {
- headers: {
- Accept: "application/json",
- "User-Agent": "opensrc-cli (https://github.com/vercel-labs/opensrc)",
- },
- });
-
- if (!response.ok) {
- if (response.status === 404) {
- throw new Error(
- `Version "${version}" not found for crate "${crateName}"`,
- );
- }
+ version?: string,
+): Promise<ResolvedPackage> {
+ const info = await fetchCrateInfo(crateName);
+
+ // If version specified, verify it exists
+ let resolvedVersion = version || info.crate.max_version;
+
+ if (version) {
+ await fetchCrateVersionInfo(crateName, version);
+ resolvedVersion = version;
+ }
+
+ const repoUrl = extractRepoUrl(info.crate);
+
+ if (!repoUrl) {
+ const availableVersions = getAvailableVersions(info.versions)
+ .slice(0, 5)
+ .join(", ");
throw new Error(
- `Failed to fetch crate version info: ${response.status} ${response.statusText}`,
+ `No repository URL found for "${crateName}@${resolvedVersion}". ` +
+ `This crate may not have its source published. ` +
+ `Recent versions: ${availableVersions}`,
);
}
- return response.json() as Promise<CrateVersionResponse>;
-}
+ // Rust crates commonly use v1.2.3 as tags
+ const gitTag = `v${resolvedVersion}`;
-/**
- * Extract repository URL from crate metadata
- */
```
This function is important because it defines how OpenSrc Tutorial: Deep Source Context for Coding Agents implements the patterns covered in this chapter.
@@ -208,11 +206,11 @@ This function is important because it defines how OpenSrc Tutorial: Deep Source
```mermaid
flowchart TD
- A[PyPIResponse]
- B[parseCratesSpec]
- C[fetchCrateInfo]
- D[fetchCrateVersionInfo]
- E[extractRepoUrl]
+ A[isGitRepoUrl]
+ B[normalizeRepoUrl]
+ C[getAvailableVersions]
+ D[resolveCrate]
+ E[CrateVersion]
A --> B
B --> C
C --> D
diff --git a/tutorials/outlines-tutorial/01-getting-started.md b/tutorials/outlines-tutorial/01-getting-started.md
index 124286e4..66c2d3ec 100644
--- a/tutorials/outlines-tutorial/01-getting-started.md
+++ b/tutorials/outlines-tutorial/01-getting-started.md
@@ -22,7 +22,7 @@ Welcome to **Chapter 1: Getting Started with Outlines**. In this part of **Outli
pip install outlines
# For development with latest features
-pip install git+https://github.com/outlines-dev/outlines.git
+pip install git+https://github.com/dottxt-ai/outlines.git
# Optional: Install with specific backends
pip install outlines[transformers] # For Hugging Face models
@@ -459,11 +459,26 @@ Under the hood, `Chapter 1: Getting Started with Outlines` usually follows a rep
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## Architecture Overview
+
+```mermaid
+flowchart TD
+ A[LLM Model] --> B[Outlines Processor]
+ B --> C{Constraint Type}
+ C -->|regex| D[Token Mask: Regex]
+ C -->|json_schema| E[Token Mask: JSON]
+ C -->|grammar| F[Token Mask: CFG]
+ D --> G[Constrained Sampling]
+ E --> G
+ F --> G
+ G --> H[Guaranteed Structured Output]
+```
+
## Source Walkthrough
Use the following upstream sources to verify implementation details while reading this chapter:
-- [View Repo](https://github.com/outlines-dev/outlines)
+- [View Repo](https://github.com/dottxt-ai/outlines)
Why it matters: authoritative reference on `View Repo` (github.com).
Suggested trace strategy:
diff --git a/tutorials/outlines-tutorial/02-text-patterns.md b/tutorials/outlines-tutorial/02-text-patterns.md
index 10c297e0..51139d18 100644
--- a/tutorials/outlines-tutorial/02-text-patterns.md
+++ b/tutorials/outlines-tutorial/02-text-patterns.md
@@ -581,11 +581,24 @@ Under the hood, `Chapter 2: Text Patterns & Regular Expressions` usually follows
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## Regex Constraint Flow
+
+```mermaid
+flowchart LR
+ A[Pattern String] --> B[Compile Regex]
+ B --> C[Build FSM]
+ C --> D[Mask Allowed Tokens per State]
+ D --> E[LLM Sampling]
+ E --> F[Next State Transition]
+ F --> D
+ F --> G[End State: Output]
+```
+
## Source Walkthrough
Use the following upstream sources to verify implementation details while reading this chapter:
-- [View Repo](https://github.com/outlines-dev/outlines)
+- [View Repo](https://github.com/dottxt-ai/outlines)
Why it matters: authoritative reference on `View Repo` (github.com).
Suggested trace strategy:
diff --git a/tutorials/outlines-tutorial/03-json-schema.md b/tutorials/outlines-tutorial/03-json-schema.md
index 2a5ac457..63d49a19 100644
--- a/tutorials/outlines-tutorial/03-json-schema.md
+++ b/tutorials/outlines-tutorial/03-json-schema.md
@@ -663,11 +663,23 @@ Under the hood, `Chapter 3: JSON Schema & Structured Data Generation` usually fo
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## JSON Schema Generation Flow
+
+```mermaid
+flowchart TD
+ A[JSON Schema] --> B[Schema Parser]
+ B --> C[Build JSON FSM]
+ C --> D[Token Masks for Each Key/Value Position]
+ D --> E[LLM Sampling]
+ E --> F[Valid JSON Object]
+ F --> G[Schema Validation Check]
+```
+
## Source Walkthrough
Use the following upstream sources to verify implementation details while reading this chapter:
-- [View Repo](https://github.com/outlines-dev/outlines)
+- [View Repo](https://github.com/dottxt-ai/outlines)
Why it matters: authoritative reference on `View Repo` (github.com).
Suggested trace strategy:
diff --git a/tutorials/outlines-tutorial/04-type-safety.md b/tutorials/outlines-tutorial/04-type-safety.md
index 5d6a3bc5..d7295634 100644
--- a/tutorials/outlines-tutorial/04-type-safety.md
+++ b/tutorials/outlines-tutorial/04-type-safety.md
@@ -723,11 +723,23 @@ Under the hood, `Chapter 4: Type Safety & Pydantic Integration` usually follows
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## Pydantic Integration Flow
+
+```mermaid
+flowchart LR
+ A[Pydantic Model Class] --> B[JSON Schema Extraction]
+ B --> C[Outlines json Generator]
+ C --> D[LLM with Constrained Sampling]
+ D --> E[Raw JSON String]
+ E --> F[Pydantic parse_raw / model_validate]
+ F --> G[Type-Safe Python Object]
+```
+
## Source Walkthrough
Use the following upstream sources to verify implementation details while reading this chapter:
-- [View Repo](https://github.com/outlines-dev/outlines)
+- [View Repo](https://github.com/dottxt-ai/outlines)
Why it matters: authoritative reference on `View Repo` (github.com).
Suggested trace strategy:
diff --git a/tutorials/outlines-tutorial/05-grammar-based.md b/tutorials/outlines-tutorial/05-grammar-based.md
index 6431b6e0..7b29e8f8 100644
--- a/tutorials/outlines-tutorial/05-grammar-based.md
+++ b/tutorials/outlines-tutorial/05-grammar-based.md
@@ -693,11 +693,24 @@ Under the hood, `Chapter 5: Grammar-Based Generation & Context-Free Grammars` us
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## Grammar-Based Generation Flow
+
+```mermaid
+flowchart TD
+ A[EBNF Grammar Definition] --> B[Parse Grammar Rules]
+ B --> C[Build Earley / LL Parser]
+ C --> D[Compute Allowed Tokens at Each Position]
+ D --> E[LLM Sampling]
+ E --> F[Grammar Check]
+ F -->|Valid Continuation| D
+ F -->|Complete| G[Parsed Output]
+```
+
## Source Walkthrough
Use the following upstream sources to verify implementation details while reading this chapter:
-- [View Repo](https://github.com/outlines-dev/outlines)
+- [View Repo](https://github.com/dottxt-ai/outlines)
Why it matters: authoritative reference on `View Repo` (github.com).
Suggested trace strategy:
diff --git a/tutorials/outlines-tutorial/06-advanced-features.md b/tutorials/outlines-tutorial/06-advanced-features.md
index 80d488c2..09b077dd 100644
--- a/tutorials/outlines-tutorial/06-advanced-features.md
+++ b/tutorials/outlines-tutorial/06-advanced-features.md
@@ -860,11 +860,23 @@ Under the hood, `Chapter 6: Advanced Features & Performance Optimization` usuall
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## Advanced Sampling Architecture
+
+```mermaid
+flowchart LR
+ A[Outlines Generator] --> B[Temperature / Top-p Config]
+ B --> C[Beam Search or Greedy]
+ C --> D[Constraint Intersection]
+ D --> E[Batched Requests]
+ E --> F[Cached FSM States]
+ F --> G[Outputs]
+```
+
## Source Walkthrough
Use the following upstream sources to verify implementation details while reading this chapter:
-- [View Repo](https://github.com/outlines-dev/outlines)
+- [View Repo](https://github.com/dottxt-ai/outlines)
Why it matters: authoritative reference on `View Repo` (github.com).
Suggested trace strategy:
diff --git a/tutorials/outlines-tutorial/07-integration.md b/tutorials/outlines-tutorial/07-integration.md
index 0a7248fb..9b68ce03 100644
--- a/tutorials/outlines-tutorial/07-integration.md
+++ b/tutorials/outlines-tutorial/07-integration.md
@@ -885,11 +885,24 @@ Under the hood, `Chapter 7: Integration with AI Frameworks` usually follows a re
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## Framework Integration Points
+
+```mermaid
+flowchart TD
+ A[Application Code] --> B{Integration Layer}
+ B --> C[LangChain LLM Wrapper]
+ B --> D[vLLM Guided Decoding]
+ B --> E[Direct Outlines API]
+ C --> F[Constrained Output]
+ D --> F
+ E --> F
+```
+
## Source Walkthrough
Use the following upstream sources to verify implementation details while reading this chapter:
-- [View Repo](https://github.com/outlines-dev/outlines)
+- [View Repo](https://github.com/dottxt-ai/outlines)
Why it matters: authoritative reference on `View Repo` (github.com).
Suggested trace strategy:
diff --git a/tutorials/outlines-tutorial/08-production.md b/tutorials/outlines-tutorial/08-production.md
index 56e5620b..027c5cd8 100644
--- a/tutorials/outlines-tutorial/08-production.md
+++ b/tutorials/outlines-tutorial/08-production.md
@@ -1350,11 +1350,23 @@ Under the hood, `Chapter 8: Production Deployment & Scaling` usually follows a r
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## Production Deployment Architecture
+
+```mermaid
+flowchart LR
+ A[Client Request] --> B[FastAPI / API Server]
+ B --> C[Outlines Generator Pool]
+ C --> D[Cached FSM per Schema]
+ D --> E[LLM Backend]
+ E --> F[Response]
+ B --> G[Metrics / Logging]
+```
+
## Source Walkthrough
Use the following upstream sources to verify implementation details while reading this chapter:
-- [View Repo](https://github.com/outlines-dev/outlines)
+- [View Repo](https://github.com/dottxt-ai/outlines)
Why it matters: authoritative reference on `View Repo` (github.com).
Suggested trace strategy:
diff --git a/tutorials/outlines-tutorial/README.md b/tutorials/outlines-tutorial/README.md
index 55a65ef2..41b17a2f 100644
--- a/tutorials/outlines-tutorial/README.md
+++ b/tutorials/outlines-tutorial/README.md
@@ -15,7 +15,7 @@ format_version: v2
[](https://github.com/dottxt-ai/outlines)
-Outlines<sup>[View Repo](https://github.com/outlines-dev/outlines)</sup> is a Python library that allows you to control Large Language Model outputs with structural constraints. Use JSON Schema, regular expressions, context-free grammars, and more to guide model generation.
+Outlines<sup>[View Repo](https://github.com/dottxt-ai/outlines)</sup> is a Python library that allows you to control Large Language Model outputs with structural constraints. Use JSON Schema, regular expressions, context-free grammars, and more to guide model generation.
## Why This Track Matters
@@ -147,6 +147,6 @@ Ready to add structure to your LLM outputs? Let's begin with [Chapter 1: Getting
## Source References
-- [View Repo](https://github.com/outlines-dev/outlines)
+- [View Repo](https://github.com/dottxt-ai/outlines)
*Generated by [AI Codebase Knowledge Builder](https://github.com/The-Pocket/Tutorial-Codebase-Knowledge)*
diff --git a/tutorials/perplexica-tutorial/01-getting-started.md b/tutorials/perplexica-tutorial/01-getting-started.md
index dfa07c74..fa1c1f5b 100644
--- a/tutorials/perplexica-tutorial/01-getting-started.md
+++ b/tutorials/perplexica-tutorial/01-getting-started.md
@@ -161,6 +161,21 @@ Under the hood, `Chapter 1: Getting Started with Perplexica` usually follows a r
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## System Overview
+
+```mermaid
+flowchart TD
+ A[User Query] --> B[Perplexica Next.js Frontend]
+ B --> C[Backend Express Server]
+ C --> D[AI Search Pipeline]
+ D --> E[SearXNG Web Search]
+ D --> F[LLM Provider]
+ E --> G[Web Results]
+ F --> H[Answer Synthesis]
+ G --> H
+ H --> I[Response with Sources]
+```
+
## Source Walkthrough
Use the following upstream sources to verify implementation details while reading this chapter:
diff --git a/tutorials/phidata-tutorial/01-getting-started.md b/tutorials/phidata-tutorial/01-getting-started.md
index 39baab37..5aaa2d15 100644
--- a/tutorials/phidata-tutorial/01-getting-started.md
+++ b/tutorials/phidata-tutorial/01-getting-started.md
@@ -531,6 +531,20 @@ Under the hood, `Chapter 1: Getting Started with Phidata Agents` usually follows
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## Architecture Overview
+
+```mermaid
+flowchart TD
+ A[User Input] --> B[Phidata Agent]
+ B --> C[Reasoning Engine]
+ C --> D{Action}
+ D -->|Use Tool| E[Tool Execution]
+ D -->|Respond| F[Response Generation]
+ E --> G[Result]
+ G --> C
+ F --> H[Final Output]
+```
+
## Source Walkthrough
Use the following upstream sources to verify implementation details while reading this chapter:
diff --git a/tutorials/phidata-tutorial/02-agent-architecture.md b/tutorials/phidata-tutorial/02-agent-architecture.md
index 0e2a2fd8..855a19b9 100644
--- a/tutorials/phidata-tutorial/02-agent-architecture.md
+++ b/tutorials/phidata-tutorial/02-agent-architecture.md
@@ -901,6 +901,21 @@ Under the hood, `Chapter 2: Understanding Phidata Agent Architecture` usually fo
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## Agent Component Architecture
+
+```mermaid
+flowchart LR
+ A[Agent Definition] --> B[Model Provider]
+ A --> C[Tool Registry]
+ A --> D[Memory Store]
+ A --> E[Instructions / System Prompt]
+ B --> F[LLM Calls]
+ C --> G[Tool Calls]
+ D --> H[Context Retrieval]
+ F --> I[Agent Response]
+ G --> I
+```
+
## Source Walkthrough
Use the following upstream sources to verify implementation details while reading this chapter:
diff --git a/tutorials/phidata-tutorial/03-tools-functions.md b/tutorials/phidata-tutorial/03-tools-functions.md
index 0eb8a87b..eb40922a 100644
--- a/tutorials/phidata-tutorial/03-tools-functions.md
+++ b/tutorials/phidata-tutorial/03-tools-functions.md
@@ -853,6 +853,18 @@ Under the hood, `Chapter 3: Tools & Functions - Extending Agent Capabilities` us
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## Tool Integration Flow
+
+```mermaid
+flowchart TD
+ A[Tool Definition] --> B[Function Signature]
+ B --> C[JSON Schema Generation]
+ C --> D[LLM Function Calling]
+ D --> E[Tool Invocation]
+ E --> F[Result]
+ F --> G[Back to Agent Context]
+```
+
## Source Walkthrough
Use the following upstream sources to verify implementation details while reading this chapter:
diff --git a/tutorials/phidata-tutorial/04-memory-systems.md b/tutorials/phidata-tutorial/04-memory-systems.md
index e3b33f4e..0a1630c0 100644
--- a/tutorials/phidata-tutorial/04-memory-systems.md
+++ b/tutorials/phidata-tutorial/04-memory-systems.md
@@ -922,6 +922,23 @@ Under the hood, `Chapter 4: Memory Systems - Building Context-Aware Agents` usua
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## Memory System Architecture
+
+```mermaid
+flowchart LR
+ A[User Message] --> B[Agent]
+ B --> C{Memory Type}
+ C --> D[Short-term: Session Context]
+ C --> E[Long-term: Vector Store]
+ C --> F[Structured: Database]
+ D --> G[In-context]
+ E --> H[Similarity Search]
+ F --> I[SQL / Key-value Lookup]
+ G --> B
+ H --> B
+ I --> B
+```
+
## Source Walkthrough
Use the following upstream sources to verify implementation details while reading this chapter:
diff --git a/tutorials/phidata-tutorial/05-multi-agent-systems.md b/tutorials/phidata-tutorial/05-multi-agent-systems.md
index 16b88dc9..bf19ebce 100644
--- a/tutorials/phidata-tutorial/05-multi-agent-systems.md
+++ b/tutorials/phidata-tutorial/05-multi-agent-systems.md
@@ -881,6 +881,23 @@ Under the hood, `Chapter 5: Multi-Agent Systems - Coordinating Teams of AI Agent
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## Multi-Agent Coordination
+
+```mermaid
+flowchart TD
+ A[Task] --> B[Orchestrator Agent]
+ B --> C[Specialist Agent 1]
+ B --> D[Specialist Agent 2]
+ B --> E[Specialist Agent 3]
+ C --> F[Sub-result 1]
+ D --> G[Sub-result 2]
+ E --> H[Sub-result 3]
+ F --> I[Aggregator]
+ G --> I
+ H --> I
+ I --> J[Final Response]
+```
+
## Source Walkthrough
Use the following upstream sources to verify implementation details while reading this chapter:
diff --git a/tutorials/phidata-tutorial/06-advanced-reasoning.md b/tutorials/phidata-tutorial/06-advanced-reasoning.md
index 269d45f3..4b71488d 100644
--- a/tutorials/phidata-tutorial/06-advanced-reasoning.md
+++ b/tutorials/phidata-tutorial/06-advanced-reasoning.md
@@ -1035,6 +1035,19 @@ Under the hood, `Chapter 6: Advanced Reasoning - Complex Decision Making and Pro
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## Reasoning Flow
+
+```mermaid
+flowchart LR
+ A[Complex Task] --> B[Decompose]
+ B --> C[Chain of Thought]
+ C --> D[Tool Use]
+ D --> E[Verify Step]
+ E --> F{Complete?}
+ F -->|No| C
+ F -->|Yes| G[Synthesize Answer]
+```
+
## Source Walkthrough
Use the following upstream sources to verify implementation details while reading this chapter:
diff --git a/tutorials/phidata-tutorial/07-integrations.md b/tutorials/phidata-tutorial/07-integrations.md
index f237959c..0c4a2b9c 100644
--- a/tutorials/phidata-tutorial/07-integrations.md
+++ b/tutorials/phidata-tutorial/07-integrations.md
@@ -1066,6 +1066,19 @@ Under the hood, `Chapter 7: Integrations - Connecting Phidata Agents to External
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## Integration Architecture
+
+```mermaid
+flowchart TD
+ A[Phidata Agent] --> B[External APIs]
+ A --> C[Databases]
+ A --> D[Vector Stores]
+ A --> E[Webhooks]
+ B --> F[REST / GraphQL]
+ C --> G[PostgreSQL / SQLite]
+ D --> H[PgVector / Pinecone]
+```
+
## Source Walkthrough
Use the following upstream sources to verify implementation details while reading this chapter:
diff --git a/tutorials/phidata-tutorial/08-production-deployment.md b/tutorials/phidata-tutorial/08-production-deployment.md
index 70c15ffd..074beb84 100644
--- a/tutorials/phidata-tutorial/08-production-deployment.md
+++ b/tutorials/phidata-tutorial/08-production-deployment.md
@@ -1746,6 +1746,19 @@ Under the hood, `Chapter 8: Production Deployment & Scaling Phidata Agents` usua
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## Production Architecture
+
+```mermaid
+flowchart LR
+ A[Client] --> B[API Gateway]
+ B --> C[Phidata Agent Service]
+ C --> D[LLM Provider]
+ C --> E[Memory / Vector DB]
+ C --> F[Tool Services]
+ B --> G[Auth / Rate Limiting]
+ C --> H[Observability]
+```
+
## Source Walkthrough
Use the following upstream sources to verify implementation details while reading this chapter:
diff --git a/tutorials/phidata-tutorial/README.md b/tutorials/phidata-tutorial/README.md
index 8780fc25..2ecb03cc 100644
--- a/tutorials/phidata-tutorial/README.md
+++ b/tutorials/phidata-tutorial/README.md
@@ -15,11 +15,13 @@ format_version: v2
[](https://github.com/phidatahq/phidata)
-Phidata<sup>[View Repo](https://github.com/phidatahq/phidata)</sup> is a framework for building autonomous AI agents with memory, reasoning, and tool integration capabilities. Create intelligent agents that can perform complex tasks, maintain conversation context, and use various tools to accomplish goals.
+Phidata<sup>[View Repo](https://github.com/agno-agi/agno)</sup> is a framework for building autonomous AI agents with memory, reasoning, and tool integration capabilities. Create intelligent agents that can perform complex tasks, maintain conversation context, and use various tools to accomplish goals.
+
+> **Note**: The Phidata project was rebranded to **Agno** (repo: [`agno-agi/agno`](https://github.com/agno-agi/agno), docs: [docs.agno.com](https://docs.agno.com)). The `phidatahq/phidata` GitHub URL redirects to the new location. For the current Agno framework, see the [Agno Tutorial](../agno-tutorial/).
## Why This Track Matters
-Phidata is increasingly relevant for developers working with modern AI/ML infrastructure. A deep technical walkthrough of Phidata covering Building Autonomous AI Agents, and this track helps you understand the architecture, key patterns, and production considerations.
+Phidata (now Agno) is increasingly relevant for developers working with modern AI/ML infrastructure. A deep technical walkthrough of Phidata covering Building Autonomous AI Agents, and this track helps you understand the architecture, key patterns, and production considerations.
This track focuses on:
@@ -41,9 +43,9 @@ This track focuses on:
## Current Snapshot (auto-updated)
-- repository: [`phidatahq/phidata`](https://github.com/phidatahq/phidata)
-- stars: about **39.2k**
-- latest release: [`v2.5.14`](https://github.com/phidatahq/phidata/releases/tag/v2.5.14) (published 2026-04-02)
+- repository: [`agno-agi/agno`](https://github.com/agno-agi/agno) (formerly `phidatahq/phidata`)
+- stars: about **39.4k**
+- latest release: see [agno-agi/agno releases](https://github.com/agno-agi/agno/releases)
## What You Will Learn
diff --git a/tutorials/plandex-tutorial/01-getting-started.md b/tutorials/plandex-tutorial/01-getting-started.md
index fa2909d3..94a2d6de 100644
--- a/tutorials/plandex-tutorial/01-getting-started.md
+++ b/tutorials/plandex-tutorial/01-getting-started.md
@@ -36,75 +36,8 @@ You now have a functioning Plandex baseline.
Next: [Chapter 2: Architecture and Workflow](02-architecture-and-workflow.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `app/shared/ai_models_available.go`
-
-The `init` function in [`app/shared/ai_models_available.go`](https://github.com/plandex-ai/plandex/blob/HEAD/app/shared/ai_models_available.go) handles a key part of this chapter's functionality:
-
-```go
-var AvailableModelsByComposite = map[string]*AvailableModel{}
-
-func init() {
- for _, model := range BuiltInModels {
- // if the model has an anthropic provider, insert claude max provider before it
- var usesAnthropicProvider *BaseModelUsesProvider
- for _, provider := range model.Providers {
- if provider.Provider == ModelProviderAnthropic {
- copy := provider
- latestModelName, ok := AnthropicLatestModelNameMap[provider.ModelName]
- if ok {
- copy.ModelName = latestModelName
- }
- usesAnthropicProvider = ©
- break
- }
- }
- if usesAnthropicProvider != nil {
- usesAnthropicProvider.Provider = ModelProviderAnthropicClaudeMax
- model.Providers = append([]BaseModelUsesProvider{*usesAnthropicProvider}, model.Providers...)
- }
-
- AvailableModels = append(AvailableModels, model.ToAvailableModels()...)
-
- var addVariants func(variants []BaseModelConfigVariant, baseId ModelId)
- addVariants = func(variants []BaseModelConfigVariant, baseId ModelId) {
- for _, variant := range variants {
- var modelId ModelId
- if variant.IsBaseVariant || variant.IsDefaultVariant {
- modelId = baseId
- } else {
- modelId = ModelId(strings.Join([]string{string(baseId), string(variant.VariantTag)}, "-"))
-```
-
-This function is important because it defines how Plandex Tutorial: Large-Task AI Coding Agent Workflows implements the patterns covered in this chapter.
-
-### `app/shared/ai_models_available.go`
-
-The `GetAvailableModel` function in [`app/shared/ai_models_available.go`](https://github.com/plandex-ai/plandex/blob/HEAD/app/shared/ai_models_available.go) handles a key part of this chapter's functionality:
-
-```go
-}
-
-func GetAvailableModel(provider ModelProvider, modelId ModelId) *AvailableModel {
- compositeKey := string(provider) + "/" + string(modelId)
- return AvailableModelsByComposite[compositeKey]
-}
-
-var AnthropicLatestModelNameMap = map[ModelName]ModelName{
- "anthropic/claude-sonnet-4-0": "anthropic/claude-sonnet-4-20250514",
- "anthropic/claude-opus-4-0": "anthropic/claude-opus-4-20250514",
- "anthropic/claude-3-7-sonnet-latest": "anthropic/claude-3-7-sonnet-20250219",
- "anthropic/claude-3-5-haiku-latest": "anthropic/claude-3-5-haiku-20241022",
- "anthropic/claude-3-5-sonnet-latest": "anthropic/claude-3-5-sonnet-20241022",
-}
-
-```
-
-This function is important because it defines how Plandex Tutorial: Large-Task AI Coding Agent Workflows implements the patterns covered in this chapter.
-
### `app/shared/ai_models_data_models.go`
The `ToComposite` function in [`app/shared/ai_models_data_models.go`](https://github.com/plandex-ai/plandex/blob/HEAD/app/shared/ai_models_data_models.go) handles a key part of this chapter's functionality:
@@ -187,16 +120,98 @@ func (b *BaseModelConfigSchema) ToAvailableModels() []*AvailableModel {
This function is important because it defines how Plandex Tutorial: Large-Task AI Coding Agent Workflows implements the patterns covered in this chapter.
+### `app/shared/ai_models_data_models.go`
+
+The `ToAvailableModels` function in [`app/shared/ai_models_data_models.go`](https://github.com/plandex-ai/plandex/blob/HEAD/app/shared/ai_models_data_models.go) handles a key part of this chapter's functionality:
+
+```go
+}
+
+func (b *BaseModelConfigSchema) ToAvailableModels() []*AvailableModel {
+ avail := []*AvailableModel{}
+ for _, provider := range b.Providers {
+
+ providerConfig, ok := BuiltInModelProviderConfigs[provider.Provider]
+ if !ok {
+ panic(fmt.Sprintf("provider %s not found", provider.Provider))
+ }
+
+ addBase := func() {
+ avail = append(avail, &AvailableModel{
+ Description: b.Description,
+ DefaultMaxConvoTokens: b.DefaultMaxConvoTokens,
+ BaseModelConfig: BaseModelConfig{
+ ModelTag: b.ModelTag,
+ ModelId: ModelId(string(b.ModelTag)),
+ BaseModelShared: b.BaseModelShared,
+ BaseModelProviderConfig: BaseModelProviderConfig{
+ ModelProviderConfigSchema: providerConfig,
+ ModelName: provider.ModelName,
+ },
+ },
+ })
+ }
+
+ type variantParams struct {
+ BaseVariant *BaseModelConfigVariant
+ BaseId ModelId
+ BaseDescription string
+ CumulativeOverrides BaseModelShared
+```
+
+This function is important because it defines how Plandex Tutorial: Large-Task AI Coding Agent Workflows implements the patterns covered in this chapter.
+
+### `app/shared/ai_models_data_models.go`
+
+The `ModelString` function in [`app/shared/ai_models_data_models.go`](https://github.com/plandex-ai/plandex/blob/HEAD/app/shared/ai_models_data_models.go) handles a key part of this chapter's functionality:
+
+```go
+}
+
+func (m *AvailableModel) ModelString() string {
+ s := ""
+ if m.Provider != "" && m.Provider != ModelProviderOpenAI {
+ s += string(m.Provider) + "/"
+ }
+ s += string(m.ModelId)
+ return s
+}
+
+type PlannerModelConfig struct {
+ MaxConvoTokens int `json:"maxConvoTokens"`
+}
+
+type ReasoningEffort string
+
+const (
+ ReasoningEffortLow ReasoningEffort = "low"
+ ReasoningEffortMedium ReasoningEffort = "medium"
+ ReasoningEffortHigh ReasoningEffort = "high"
+)
+
+type ModelRoleConfig struct {
+ Role ModelRole `json:"role"`
+
+ ModelId ModelId `json:"modelId"` // new in 2.2.0 refactor — uses provider lookup instead of BaseModelConfig and MissingKeyFallback
+
+ BaseModelConfig *BaseModelConfig `json:"baseModelConfig,omitempty"`
+ Temperature float32 `json:"temperature"`
+ TopP float32 `json:"topP"`
+ ReservedOutputTokens int `json:"reservedOutputTokens"`
+```
+
+This function is important because it defines how Plandex Tutorial: Large-Task AI Coding Agent Workflows implements the patterns covered in this chapter.
+
## How These Components Connect
```mermaid
flowchart TD
- A[init]
- B[GetAvailableModel]
- C[ToComposite]
- D[IsLocalOnly]
- E[ToAvailableModels]
+ A[ToComposite]
+ B[IsLocalOnly]
+ C[ToAvailableModels]
+ D[ModelString]
+ E[ToClientVal]
A --> B
B --> C
C --> D
diff --git a/tutorials/plandex-tutorial/02-architecture-and-workflow.md b/tutorials/plandex-tutorial/02-architecture-and-workflow.md
index c64a860a..39b15103 100644
--- a/tutorials/plandex-tutorial/02-architecture-and-workflow.md
+++ b/tutorials/plandex-tutorial/02-architecture-and-workflow.md
@@ -26,88 +26,86 @@ You now understand Plandex's large-task lifecycle.
Next: [Chapter 3: Context Management at Scale](03-context-management-at-scale.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `app/shared/ai_models_data_models.go`
-The `GetSharedBaseConfig` function in [`app/shared/ai_models_data_models.go`](https://github.com/plandex-ai/plandex/blob/HEAD/app/shared/ai_models_data_models.go) handles a key part of this chapter's functionality:
+The `Scan` function in [`app/shared/ai_models_data_models.go`](https://github.com/plandex-ai/plandex/blob/HEAD/app/shared/ai_models_data_models.go) handles a key part of this chapter's functionality:
```go
- }
-
- sharedBaseConfig := m.GetSharedBaseConfigWithCustomModels(customModelsById)
- return sharedBaseConfig.ReservedOutputTokens
}
-func (m ModelRoleConfig) GetSharedBaseConfig(settings *PlanSettings) *BaseModelShared {
- return m.GetSharedBaseConfigWithCustomModels(settings.CustomModelsById)
-}
-
-func (m ModelRoleConfig) GetSharedBaseConfigWithCustomModels(customModels map[ModelId]*CustomModel) *BaseModelShared {
- if m.BaseModelConfig != nil {
- return &m.BaseModelConfig.BaseModelShared
+func (m *ModelRoleConfig) Scan(src interface{}) error {
+ if src == nil {
+ return nil
}
-
- builtInModel := BuiltInBaseModelsById[m.ModelId]
- if builtInModel != nil {
- return &builtInModel.BaseModelShared
+ switch s := src.(type) {
+ case []byte:
+ return json.Unmarshal(s, m)
+ case string:
+ return json.Unmarshal([]byte(s), m)
+ default:
+ return fmt.Errorf("unsupported data type: %T", src)
}
+}
- customModel := customModels[m.ModelId]
- if customModel != nil {
- return &customModel.BaseModelShared
- }
+func (m ModelRoleConfig) Value() (driver.Value, error) {
+ return json.Marshal(m)
+}
- return nil
+type PlannerRoleConfig struct {
+ ModelRoleConfig
+ PlannerModelConfig
}
-func (m *ModelRoleConfig) Scan(src interface{}) error {
+func (p *PlannerRoleConfig) Scan(src interface{}) error {
if src == nil {
return nil
}
+ switch s := src.(type) {
+ case []byte:
+ return json.Unmarshal(s, p)
```
This function is important because it defines how Plandex Tutorial: Large-Task AI Coding Agent Workflows implements the patterns covered in this chapter.
### `app/shared/ai_models_data_models.go`
-The `GetSharedBaseConfigWithCustomModels` function in [`app/shared/ai_models_data_models.go`](https://github.com/plandex-ai/plandex/blob/HEAD/app/shared/ai_models_data_models.go) handles a key part of this chapter's functionality:
+The `Value` function in [`app/shared/ai_models_data_models.go`](https://github.com/plandex-ai/plandex/blob/HEAD/app/shared/ai_models_data_models.go) handles a key part of this chapter's functionality:
```go
}
- sharedBaseConfig := m.GetSharedBaseConfigWithCustomModels(customModelsById)
- return sharedBaseConfig.ReservedOutputTokens
-}
-
-func (m ModelRoleConfig) GetSharedBaseConfig(settings *PlanSettings) *BaseModelShared {
- return m.GetSharedBaseConfigWithCustomModels(settings.CustomModelsById)
-}
+ v := reflect.ValueOf(*m)
+ t := v.Type()
-func (m ModelRoleConfig) GetSharedBaseConfigWithCustomModels(customModels map[ModelId]*CustomModel) *BaseModelShared {
- if m.BaseModelConfig != nil {
- return &m.BaseModelConfig.BaseModelShared
- }
+ for i := 0; i < v.NumField(); i++ {
+ f := t.Field(i)
+ if f.Name == "ModelId" { // skip the sentinel field
+ continue
+ }
- builtInModel := BuiltInBaseModelsById[m.ModelId]
- if builtInModel != nil {
- return &builtInModel.BaseModelShared
- }
+ fv := v.Field(i)
- customModel := customModels[m.ModelId]
- if customModel != nil {
- return &customModel.BaseModelShared
+ switch fv.Kind() {
+ case reflect.Pointer, reflect.Interface, reflect.Map, reflect.Slice:
+ if !fv.IsNil() {
+ return false
+ }
+ default:
+ if !fv.IsZero() {
+ return false
+ }
+ }
}
-
- return nil
+ return true
}
-func (m *ModelRoleConfig) Scan(src interface{}) error {
- if src == nil {
- return nil
- }
+func (m *ModelRoleConfigSchema) AllModelIds() []ModelId {
+ ids := []ModelId{}
+
+ if m.ModelId != "" {
+ ids = append(ids, m.ModelId)
```
This function is important because it defines how Plandex Tutorial: Large-Task AI Coding Agent Workflows implements the patterns covered in this chapter.
@@ -199,11 +197,11 @@ This function is important because it defines how Plandex Tutorial: Large-Task A
```mermaid
flowchart TD
- A[GetSharedBaseConfig]
- B[GetSharedBaseConfigWithCustomModels]
+ A[Scan]
+ B[Value]
C[Scan]
D[Value]
- E[Scan]
+ E[GetMaxConvoTokens]
A --> B
B --> C
C --> D
diff --git a/tutorials/plandex-tutorial/03-context-management-at-scale.md b/tutorials/plandex-tutorial/03-context-management-at-scale.md
index 621f6ec8..b7f242ac 100644
--- a/tutorials/plandex-tutorial/03-context-management-at-scale.md
+++ b/tutorials/plandex-tutorial/03-context-management-at-scale.md
@@ -27,170 +27,168 @@ You now have a context strategy for large-scale tasks in Plandex.
Next: [Chapter 4: Planning, Execution, and Diff Sandbox](04-planning-execution-and-diff-sandbox.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `app/shared/ai_models_packs.go`
+### `app/shared/plan_config.go`
-The `getStrongModelFallback` function in [`app/shared/ai_models_packs.go`](https://github.com/plandex-ai/plandex/blob/HEAD/app/shared/ai_models_packs.go) handles a key part of this chapter's functionality:
+The `Value` function in [`app/shared/plan_config.go`](https://github.com/plandex-ai/plandex/blob/HEAD/app/shared/plan_config.go) handles a key part of this chapter's functionality:
```go
}
-func getStrongModelFallback(role ModelRole, modelId ModelId, fns ...func(*ModelRoleConfigSchema)) func(*ModelRoleConfigSchema) {
- return func(c *ModelRoleConfigSchema) {
- n := getModelRoleConfig(role, modelId)
- for _, f := range fns {
- f(&n)
- }
- c.StrongModel = &n
- }
+func (p PlanConfig) Value() (driver.Value, error) {
+ return json.Marshal(p)
}
-var (
- DailyDriverSchema ModelPackSchema
- ReasoningSchema ModelPackSchema
- StrongSchema ModelPackSchema
- OssSchema ModelPackSchema
- CheapSchema ModelPackSchema
- OllamaExperimentalSchema ModelPackSchema
- OllamaAdaptiveOssSchema ModelPackSchema
- OllamaAdaptiveDailySchema ModelPackSchema
- AnthropicSchema ModelPackSchema
- OpenAISchema ModelPackSchema
- GoogleSchema ModelPackSchema
- GeminiPlannerSchema ModelPackSchema
- OpusPlannerSchema ModelPackSchema
- R1PlannerSchema ModelPackSchema
- PerplexityPlannerSchema ModelPackSchema
- O3PlannerSchema ModelPackSchema
-)
-
-var BuiltInModelPackSchemas = []*ModelPackSchema{
+func (p *PlanConfig) SetAutoMode(mode AutoModeType) {
+ p.AutoMode = mode
+
+ switch p.AutoMode {
+ case AutoModeFull:
+ p.AutoContinue = true
+ p.AutoBuild = true
+ p.AutoUpdateContext = true
+ p.AutoLoadContext = true
+ p.SmartContext = true
+ p.AutoApply = true
+ p.AutoCommit = true
+ p.CanExec = true
+ p.AutoExec = true
+ p.AutoDebug = true
+ p.AutoDebugTries = defaultAutoDebugTries
+ p.AutoRevertOnRewind = true
+ p.SkipChangesMenu = false
+
+ case AutoModeSemi:
+ p.AutoContinue = true
+ p.AutoBuild = true
+ p.AutoUpdateContext = true
+ p.AutoLoadContext = true
+ p.SmartContext = true
+ p.AutoApply = false
```
This function is important because it defines how Plandex Tutorial: Large-Task AI Coding Agent Workflows implements the patterns covered in this chapter.
-### `app/shared/ai_models_packs.go`
+### `app/shared/plan_config.go`
-The `init` function in [`app/shared/ai_models_packs.go`](https://github.com/plandex-ai/plandex/blob/HEAD/app/shared/ai_models_packs.go) handles a key part of this chapter's functionality:
+The `SetAutoMode` function in [`app/shared/plan_config.go`](https://github.com/plandex-ai/plandex/blob/HEAD/app/shared/plan_config.go) handles a key part of this chapter's functionality:
```go
}
-func init() {
- defaultBuilder := getModelRoleConfig(ModelRoleBuilder, "openai/o4-mini-medium",
- getStrongModelFallback(ModelRoleBuilder, "openai/o4-mini-high"),
- )
-
- DailyDriverSchema = ModelPackSchema{
- Name: "daily-driver",
- Description: "A mix of models from Anthropic, OpenAI, and Google that balances speed, quality, and cost. Supports up to 2M context.",
- ModelPackSchemaRoles: ModelPackSchemaRoles{
- Planner: getModelRoleConfig(ModelRolePlanner, "anthropic/claude-sonnet-4",
- getLargeContextFallback(ModelRolePlanner, "google/gemini-2.5-pro",
- getLargeContextFallback(ModelRolePlanner, "google/gemini-pro-1.5"),
- ),
- ),
- Architect: Pointer(getModelRoleConfig(ModelRoleArchitect, "anthropic/claude-sonnet-4",
- getLargeContextFallback(ModelRoleArchitect, "google/gemini-2.5-pro",
- getLargeContextFallback(ModelRoleArchitect, "google/gemini-pro-1.5"),
- ),
- )),
- Coder: Pointer(getModelRoleConfig(ModelRoleCoder, "anthropic/claude-sonnet-4",
- getLargeContextFallback(ModelRoleCoder, "openai/gpt-4.1"),
- )),
- PlanSummary: getModelRoleConfig(ModelRolePlanSummary, "openai/o4-mini-low"),
- Builder: defaultBuilder,
- WholeFileBuilder: Pointer(getModelRoleConfig(ModelRoleWholeFileBuilder, "openai/o4-mini-medium")),
- Namer: getModelRoleConfig(ModelRoleName, "openai/gpt-4.1-mini"),
- CommitMsg: getModelRoleConfig(ModelRoleCommitMsg, "openai/gpt-4.1-mini"),
- ExecStatus: getModelRoleConfig(ModelRoleExecStatus, "openai/o4-mini-low"),
- },
- }
+func (p *PlanConfig) SetAutoMode(mode AutoModeType) {
+ p.AutoMode = mode
+
+ switch p.AutoMode {
+ case AutoModeFull:
+ p.AutoContinue = true
+ p.AutoBuild = true
+ p.AutoUpdateContext = true
+ p.AutoLoadContext = true
+ p.SmartContext = true
+ p.AutoApply = true
+ p.AutoCommit = true
+ p.CanExec = true
+ p.AutoExec = true
+ p.AutoDebug = true
+ p.AutoDebugTries = defaultAutoDebugTries
+ p.AutoRevertOnRewind = true
+ p.SkipChangesMenu = false
+
+ case AutoModeSemi:
+ p.AutoContinue = true
+ p.AutoBuild = true
+ p.AutoUpdateContext = true
+ p.AutoLoadContext = true
+ p.SmartContext = true
+ p.AutoApply = false
+ p.AutoCommit = true
+ p.CanExec = true
+ p.AutoExec = false
+ p.AutoDebug = false
```
This function is important because it defines how Plandex Tutorial: Large-Task AI Coding Agent Workflows implements the patterns covered in this chapter.
-### `app/shared/ai_models_packs.go`
+### `app/shared/plan_config.go`
-The `cloneSchema` function in [`app/shared/ai_models_packs.go`](https://github.com/plandex-ai/plandex/blob/HEAD/app/shared/ai_models_packs.go) handles a key part of this chapter's functionality:
+The `init` function in [`app/shared/plan_config.go`](https://github.com/plandex-ai/plandex/blob/HEAD/app/shared/plan_config.go) handles a key part of this chapter's functionality:
```go
+var AutoModeLabels = map[AutoModeType]string{}
+
+// populated in init()
+var AutoModeChoices []string
+
+type PlanConfig struct {
+ AutoMode AutoModeType `json:"autoMode"`
+ // QuietMode bool `json:"quietMode"`
+
+ Editor string `json:"editor"`
+ EditorCommand string `json:"editorCommand"`
+ EditorArgs []string `json:"editorArgs"`
+ EditorOpenManually bool `json:"editorOpenManually"`
+
+ AutoContinue bool `json:"autoContinue"`
+ AutoBuild bool `json:"autoBuild"`
+
+ AutoUpdateContext bool `json:"autoUpdateContext"`
+ AutoLoadContext bool `json:"autoContext"`
+ SmartContext bool `json:"smartContext"`
+
+ // AutoApproveContext bool `json:"autoApproveContext"`
+ // QuietContext bool `json:"quietContext"`
- // Copy daily driver schema and modify it to use ollama for lighter tasks
- OllamaAdaptiveDailySchema = cloneSchema(DailyDriverSchema)
- OllamaAdaptiveDailySchema.Name = "ollama-daily"
- OllamaAdaptiveDailySchema.Description = "Ollama adaptive/daily-driver blend. Uses 'daily-driver' for heavy lifting, local models for lighter tasks."
- OllamaAdaptiveDailySchema.LocalProvider = ModelProviderOllama
- OllamaAdaptiveDailySchema.PlanSummary = getModelRoleConfig(ModelRolePlanSummary, "mistral/devstral-small")
- OllamaAdaptiveDailySchema.CommitMsg = getModelRoleConfig(ModelRoleCommitMsg, "qwen/qwen3-8b-local")
- OllamaAdaptiveDailySchema.Namer = getModelRoleConfig(ModelRoleName, "qwen/qwen3-8b-local")
-
- // Copy oss schema and modify it to use ollama for lighter tasks
- OllamaAdaptiveOssSchema = cloneSchema(OssSchema)
- OllamaAdaptiveOssSchema.Name = "ollama-oss"
- OllamaAdaptiveOssSchema.Description = "Ollama adaptive/oss blend. Uses local models for planning and context selection, open source cloud models for implementation and file edits. Supports up to 110k context."
- OllamaAdaptiveOssSchema.LocalProvider = ModelProviderOllama
- OllamaAdaptiveOssSchema.PlanSummary = getModelRoleConfig(ModelRolePlanSummary, "mistral/devstral-small")
- OllamaAdaptiveOssSchema.CommitMsg = getModelRoleConfig(ModelRoleCommitMsg, "qwen/qwen3-8b-local")
- OllamaAdaptiveOssSchema.Namer = getModelRoleConfig(ModelRoleName, "qwen/qwen3-8b-local")
-
- OpenAISchema = ModelPackSchema{
- Name: "openai",
- Description: "OpenAI blend. Supports up to 1M context. Uses OpenAI's GPT-4.1 model for heavy lifting, GPT-4.1 Mini for lighter tasks.",
- ModelPackSchemaRoles: ModelPackSchemaRoles{
- Planner: getModelRoleConfig(ModelRolePlanner, "openai/gpt-4.1"),
- PlanSummary: getModelRoleConfig(ModelRolePlanSummary, "openai/o4-mini-low"),
- Builder: defaultBuilder,
- WholeFileBuilder: Pointer(getModelRoleConfig(ModelRoleWholeFileBuilder,
- "openai/o4-mini-medium")),
- Namer: getModelRoleConfig(ModelRoleName, "openai/gpt-4.1-mini"),
- CommitMsg: getModelRoleConfig(ModelRoleCommitMsg, "openai/gpt-4.1-mini"),
- ExecStatus: getModelRoleConfig(ModelRoleExecStatus, "openai/o4-mini-low"),
- },
+ // AutoApprovePlan bool `json:"autoApprovePlan"`
+
+ // QuietCoding bool `json:"quietCoding"`
+ // ParallelCoding bool `json:"parallelCoding"`
+
+ AutoApply bool `json:"autoApply"`
+ AutoCommit bool `json:"autoCommit"`
+ SkipCommit bool `json:"skipCommit"`
```
This function is important because it defines how Plandex Tutorial: Large-Task AI Coding Agent Workflows implements the patterns covered in this chapter.
-### `app/shared/ai_models_providers.go`
+### `app/shared/data_models.go`
-The `ToComposite` function in [`app/shared/ai_models_providers.go`](https://github.com/plandex-ai/plandex/blob/HEAD/app/shared/ai_models_providers.go) handles a key part of this chapter's functionality:
+The `Name` function in [`app/shared/data_models.go`](https://github.com/plandex-ai/plandex/blob/HEAD/app/shared/data_models.go) handles a key part of this chapter's functionality:
```go
+type Org struct {
+ Id string `json:"id"`
+ Name string `json:"name"`
+ IsTrial bool `json:"isTrial"`
+ AutoAddDomainUsers bool `json:"autoAddDomainUsers"`
+
+ // optional cloud attributes
+ IntegratedModelsMode bool `json:"integratedModelsMode,omitempty"`
+ CloudBillingFields *CloudBillingFields `json:"cloudBillingFields,omitempty"`
+}
+
+type User struct {
+ Id string `json:"id"`
+ Name string `json:"name"`
+ Email string `json:"email"`
+ IsTrial bool `json:"isTrial"`
+ NumNonDraftPlans int `json:"numNonDraftPlans"`
+
+ DefaultPlanConfig *PlanConfig `json:"defaultPlanConfig,omitempty"`
}
-func (m *ModelProviderConfigSchema) ToComposite() string {
- if m.CustomProvider != nil {
- return fmt.Sprintf("%s|%s", m.Provider, *m.CustomProvider)
- }
- return string(m.Provider)
+type OrgUser struct {
+ OrgId string `json:"orgId"`
+ UserId string `json:"userId"`
+ OrgRoleId string `json:"orgRoleId"`
+
+ Config *OrgUserConfig `json:"config,omitempty"`
}
-const DefaultAzureApiVersion = "2025-04-01-preview"
-const AnthropicMaxReasoningBudget = 32000
-const GoogleMaxReasoningBudget = 32000
-
-var BuiltInModelProviderConfigs = map[ModelProvider]ModelProviderConfigSchema{
- ModelProviderOpenAI: {
- Provider: ModelProviderOpenAI,
- BaseUrl: OpenAIV1BaseUrl,
- ApiKeyEnvVar: OpenAIEnvVar,
- ExtraAuthVars: []ModelProviderExtraAuthVars{
- {
- Var: "OPENAI_ORG_ID",
- Required: false,
- },
- },
- },
- ModelProviderOpenRouter: {
- Provider: ModelProviderOpenRouter,
- BaseUrl: OpenRouterBaseUrl,
- ApiKeyEnvVar: OpenRouterApiKeyEnvVar,
- },
- ModelProviderAnthropic: {
- Provider: ModelProviderAnthropic,
+type Invite struct {
+ Id string `json:"id"`
+ OrgId string `json:"orgId"`
```
This function is important because it defines how Plandex Tutorial: Large-Task AI Coding Agent Workflows implements the patterns covered in this chapter.
@@ -200,11 +198,11 @@ This function is important because it defines how Plandex Tutorial: Large-Task A
```mermaid
flowchart TD
- A[getStrongModelFallback]
- B[init]
- C[cloneSchema]
- D[ToComposite]
- E[init]
+ A[Value]
+ B[SetAutoMode]
+ C[init]
+ D[Name]
+ E[ModelString]
A --> B
B --> C
C --> D
diff --git a/tutorials/plandex-tutorial/04-planning-execution-and-diff-sandbox.md b/tutorials/plandex-tutorial/04-planning-execution-and-diff-sandbox.md
index 09891590..fc201e55 100644
--- a/tutorials/plandex-tutorial/04-planning-execution-and-diff-sandbox.md
+++ b/tutorials/plandex-tutorial/04-planning-execution-and-diff-sandbox.md
@@ -26,170 +26,168 @@ You now know how to use Plandex's review sandbox for safer high-impact changes.
Next: [Chapter 5: Model Packs and Provider Strategy](05-model-packs-and-provider-strategy.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `app/shared/ai_models_custom.go`
+### `app/shared/plan_result_pending_summary.go`
-The `Hash` function in [`app/shared/ai_models_custom.go`](https://github.com/plandex-ai/plandex/blob/HEAD/app/shared/ai_models_custom.go) handles a key part of this chapter's functionality:
+The `pendingChangesSummary` function in [`app/shared/plan_result_pending_summary.go`](https://github.com/plandex-ai/plandex/blob/HEAD/app/shared/plan_result_pending_summary.go) handles a key part of this chapter's functionality:
```go
-}
-// Hash returns a deterministic hash of the ModelsInput.
-// WARNING: This relies on json.Marshal being deterministic for our struct types.
-// Do not add map fields to these structs or the hash will become non-deterministic.
-func (input ModelsInput) Hash() (string, error) {
- data, err := json.Marshal(input)
- if err != nil {
- return "", err
- }
+func (state *CurrentPlanState) PendingChangesSummaryForBuild() string {
+ return state.pendingChangesSummary(false, "")
+}
- hash := sha256.Sum256(data)
- return hex.EncodeToString(hash[:]), nil
+func (state *CurrentPlanState) PendingChangesSummaryForApply(commitSummary string) string {
+ return state.pendingChangesSummary(true, commitSummary)
}
-type ClientModelPackSchema struct {
- Name string `json:"name"`
- Description string `json:"description"`
+func (state *CurrentPlanState) pendingChangesSummary(forApply bool, commitSummary string) string {
+ var msgs []string
- ClientModelPackSchemaRoles
-}
+ descByConvoMessageId := make(map[string]*ConvoMessageDescription)
+
+ for _, desc := range state.ConvoMessageDescriptions {
+ if desc.ConvoMessageId == "" {
+ log.Println("Warning: ConvoMessageId is empty for description:", desc)
+ continue
+ }
-func (input *ClientModelPackSchema) ToModelPackSchema() *ModelPackSchema {
- return &ModelPackSchema{
- Name: input.Name,
- Description: input.Description,
- ModelPackSchemaRoles: input.ClientModelPackSchemaRoles.ToModelPackSchemaRoles(),
+ descByConvoMessageId[desc.ConvoMessageId] = desc
}
-}
-func (input *ModelPackSchema) ToClientModelPackSchema() *ClientModelPackSchema {
- return &ClientModelPackSchema{
+ type changeset struct {
+ descsSet map[string]bool
+ descs []*ConvoMessageDescription
+ results []*PlanFileResult
+ }
+ byDescs := map[string]*changeset{}
+
+ for _, result := range state.PlanResult.Results {
+ // log.Println("result:")
```
This function is important because it defines how Plandex Tutorial: Large-Task AI Coding Agent Workflows implements the patterns covered in this chapter.
-### `app/shared/ai_models_custom.go`
+### `app/cli/upgrade.go`
-The `ToModelPackSchema` function in [`app/shared/ai_models_custom.go`](https://github.com/plandex-ai/plandex/blob/HEAD/app/shared/ai_models_custom.go) handles a key part of this chapter's functionality:
+The `checkForUpgrade` function in [`app/cli/upgrade.go`](https://github.com/plandex-ai/plandex/blob/HEAD/app/cli/upgrade.go) handles a key part of this chapter's functionality:
```go
+)
-func (mp *ModelPack) Equals(other *ModelPack) bool {
- return mp.ToModelPackSchema().Equals(other.ToModelPackSchema())
-}
-
-// Hash returns a deterministic hash of the ModelsInput.
-// WARNING: This relies on json.Marshal being deterministic for our struct types.
-// Do not add map fields to these structs or the hash will become non-deterministic.
-func (input ModelsInput) Hash() (string, error) {
- data, err := json.Marshal(input)
- if err != nil {
- return "", err
+func checkForUpgrade() {
+ if os.Getenv("PLANDEX_SKIP_UPGRADE") != "" {
+ return
}
- hash := sha256.Sum256(data)
- return hex.EncodeToString(hash[:]), nil
-}
-
-type ClientModelPackSchema struct {
- Name string `json:"name"`
- Description string `json:"description"`
-
- ClientModelPackSchemaRoles
-}
+ if version.Version == "development" {
+ return
+ }
-func (input *ClientModelPackSchema) ToModelPackSchema() *ModelPackSchema {
- return &ModelPackSchema{
- Name: input.Name,
- Description: input.Description,
- ModelPackSchemaRoles: input.ClientModelPackSchemaRoles.ToModelPackSchemaRoles(),
+ term.StartSpinner("")
+ defer term.StopSpinner()
+ ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+ defer cancel()
+ latestVersionURL := "https://plandex.ai/v2/cli-version.txt"
+ req, err := http.NewRequestWithContext(ctx, http.MethodGet, latestVersionURL, nil)
+ if err != nil {
+ log.Println("Error creating request:", err)
+ return
}
-}
+ resp, err := http.DefaultClient.Do(req)
+ if err != nil {
+ log.Println("Error checking latest version:", err)
+ return
+ }
+ defer resp.Body.Close()
+
+ body, err := io.ReadAll(resp.Body)
+ if err != nil {
+ log.Println("Error reading response body:", err)
+ return
```
This function is important because it defines how Plandex Tutorial: Large-Task AI Coding Agent Workflows implements the patterns covered in this chapter.
-### `app/shared/ai_models_custom.go`
+### `app/cli/upgrade.go`
-The `ToClientModelPackSchema` function in [`app/shared/ai_models_custom.go`](https://github.com/plandex-ai/plandex/blob/HEAD/app/shared/ai_models_custom.go) handles a key part of this chapter's functionality:
+The `doUpgrade` function in [`app/cli/upgrade.go`](https://github.com/plandex-ai/plandex/blob/HEAD/app/cli/upgrade.go) handles a key part of this chapter's functionality:
```go
-}
-
-func (input *ModelPackSchema) ToClientModelPackSchema() *ClientModelPackSchema {
- return &ClientModelPackSchema{
- Name: input.Name,
- Description: input.Description,
- ClientModelPackSchemaRoles: input.ToClientModelPackSchemaRoles(),
+ if confirmed {
+ term.ResumeSpinner()
+ err := doUpgrade(latestVersion.String())
+ if err != nil {
+ term.OutputErrorAndExit("Failed to upgrade: %v", err)
+ return
+ }
+ term.StopSpinner()
+ restartPlandex()
+ } else {
+ fmt.Println("Note: set PLANDEX_SKIP_UPGRADE=1 to stop upgrade prompts")
+ }
}
}
-type ClientModelsInput struct {
- SchemaUrl SchemaUrl `json:"$schema"`
-
- CustomModels []*CustomModel `json:"models,omitempty"`
- CustomProviders []*CustomProvider `json:"providers,omitempty"`
- CustomModelPacks []*ClientModelPackSchema `json:"modelPacks,omitempty"`
-}
+func doUpgrade(version string) error {
+ tag := fmt.Sprintf("cli/v%s", version)
+ escapedTag := url.QueryEscape(tag)
-func (input ClientModelsInput) ToModelsInput() ModelsInput {
- modelPacks := []*ModelPackSchema{}
- for _, pack := range input.CustomModelPacks {
- modelPacks = append(modelPacks, pack.ToModelPackSchema())
+ downloadURL := fmt.Sprintf("https://github.com/plandex-ai/plandex/releases/download/%s/plandex_%s_%s_%s.tar.gz", escapedTag, version, runtime.GOOS, runtime.GOARCH)
+ resp, err := http.Get(downloadURL)
+ if err != nil {
+ return fmt.Errorf("failed to download the update: %w", err)
}
+ defer resp.Body.Close()
- return ModelsInput{
- CustomModels: input.CustomModels,
- CustomProviders: input.CustomProviders,
- CustomModelPacks: modelPacks,
+ // Create a temporary file to save the downloaded archive
+ tempFile, err := os.CreateTemp("", "*.tar.gz")
+ if err != nil {
+ return fmt.Errorf("failed to create temporary file: %w", err)
}
-}
-
-func (input *ClientModelsInput) PrepareUpdate() {
+ defer os.Remove(tempFile.Name()) // Clean up file afterwards
```
This function is important because it defines how Plandex Tutorial: Large-Task AI Coding Agent Workflows implements the patterns covered in this chapter.
-### `app/shared/ai_models_custom.go`
+### `app/cli/upgrade.go`
-The `ToModelsInput` function in [`app/shared/ai_models_custom.go`](https://github.com/plandex-ai/plandex/blob/HEAD/app/shared/ai_models_custom.go) handles a key part of this chapter's functionality:
+The `restartPlandex` function in [`app/cli/upgrade.go`](https://github.com/plandex-ai/plandex/blob/HEAD/app/cli/upgrade.go) handles a key part of this chapter's functionality:
```go
+ }
+ term.StopSpinner()
+ restartPlandex()
+ } else {
+ fmt.Println("Note: set PLANDEX_SKIP_UPGRADE=1 to stop upgrade prompts")
+ }
+ }
}
-func (input ClientModelsInput) ToModelsInput() ModelsInput {
- modelPacks := []*ModelPackSchema{}
- for _, pack := range input.CustomModelPacks {
- modelPacks = append(modelPacks, pack.ToModelPackSchema())
- }
+func doUpgrade(version string) error {
+ tag := fmt.Sprintf("cli/v%s", version)
+ escapedTag := url.QueryEscape(tag)
- return ModelsInput{
- CustomModels: input.CustomModels,
- CustomProviders: input.CustomProviders,
- CustomModelPacks: modelPacks,
+ downloadURL := fmt.Sprintf("https://github.com/plandex-ai/plandex/releases/download/%s/plandex_%s_%s_%s.tar.gz", escapedTag, version, runtime.GOOS, runtime.GOARCH)
+ resp, err := http.Get(downloadURL)
+ if err != nil {
+ return fmt.Errorf("failed to download the update: %w", err)
}
-}
+ defer resp.Body.Close()
-func (input *ClientModelsInput) PrepareUpdate() {
- for _, model := range input.CustomModels {
- model.Id = ""
- model.CreatedAt = nil
- model.UpdatedAt = nil
+ // Create a temporary file to save the downloaded archive
+ tempFile, err := os.CreateTemp("", "*.tar.gz")
+ if err != nil {
+ return fmt.Errorf("failed to create temporary file: %w", err)
}
+ defer os.Remove(tempFile.Name()) // Clean up file afterwards
- for _, provider := range input.CustomProviders {
- provider.Id = ""
- provider.CreatedAt = nil
- provider.UpdatedAt = nil
+ // Copy the response body to the temporary file
+ _, err = io.Copy(tempFile, resp.Body)
+ if err != nil {
+ return fmt.Errorf("failed to save the downloaded archive: %w", err)
}
-}
-
-func (input ModelsInput) ToClientModelsInput() ClientModelsInput {
- clientModelPacks := []*ClientModelPackSchema{}
- for _, pack := range input.CustomModelPacks {
```
This function is important because it defines how Plandex Tutorial: Large-Task AI Coding Agent Workflows implements the patterns covered in this chapter.
@@ -199,11 +197,11 @@ This function is important because it defines how Plandex Tutorial: Large-Task A
```mermaid
flowchart TD
- A[Hash]
- B[ToModelPackSchema]
- C[ToClientModelPackSchema]
- D[ToModelsInput]
- E[PrepareUpdate]
+ A[pendingChangesSummary]
+ B[checkForUpgrade]
+ C[doUpgrade]
+ D[restartPlandex]
+ E[init]
A --> B
B --> C
C --> D
diff --git a/tutorials/plandex-tutorial/05-model-packs-and-provider-strategy.md b/tutorials/plandex-tutorial/05-model-packs-and-provider-strategy.md
index 411cf674..dc434e05 100644
--- a/tutorials/plandex-tutorial/05-model-packs-and-provider-strategy.md
+++ b/tutorials/plandex-tutorial/05-model-packs-and-provider-strategy.md
@@ -25,65 +25,15 @@ You now have a model strategy framework for production Plandex usage.
Next: [Chapter 6: Autonomy, Control, and Debugging](06-autonomy-control-and-debugging.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `app/shared/plan_model_settings.go`
-The `GetCoderMaxTokens` function in [`app/shared/plan_model_settings.go`](https://github.com/plandex-ai/plandex/blob/HEAD/app/shared/plan_model_settings.go) handles a key part of this chapter's functionality:
-
-```go
-}
-
-func (ps PlanSettings) GetCoderMaxTokens() int {
- modelPack := ps.GetModelPack()
- coder := modelPack.GetCoder()
- fallback := coder.GetFinalLargeContextFallback()
- return fallback.GetSharedBaseConfig(&ps).MaxTokens
-}
-
-func (ps PlanSettings) GetCoderMaxReservedOutputTokens() int {
- modelPack := ps.GetModelPack()
- coder := modelPack.GetCoder()
- fallback := coder.GetFinalLargeContextFallback()
- return fallback.GetReservedOutputTokens(ps.CustomModelsById)
-}
-
-func (ps PlanSettings) GetWholeFileBuilderMaxTokens() int {
- modelPack := ps.GetModelPack()
- builder := modelPack.GetWholeFileBuilder()
- fallback := builder.GetFinalLargeContextFallback()
- return fallback.GetSharedBaseConfig(&ps).MaxTokens
-}
-
-func (ps PlanSettings) GetWholeFileBuilderMaxReservedOutputTokens() int {
- modelPack := ps.GetModelPack()
- builder := modelPack.GetWholeFileBuilder()
- fallback := builder.GetFinalLargeOutputFallback()
- return fallback.GetReservedOutputTokens(ps.CustomModelsById)
-}
-
-func (ps PlanSettings) GetPlannerMaxConvoTokens() int {
- modelPack := ps.GetModelPack()
-```
-
-This function is important because it defines how Plandex Tutorial: Large-Task AI Coding Agent Workflows implements the patterns covered in this chapter.
-
-### `app/shared/plan_model_settings.go`
-
-The `GetCoderMaxReservedOutputTokens` function in [`app/shared/plan_model_settings.go`](https://github.com/plandex-ai/plandex/blob/HEAD/app/shared/plan_model_settings.go) handles a key part of this chapter's functionality:
+The `GetWholeFileBuilderMaxTokens` function in [`app/shared/plan_model_settings.go`](https://github.com/plandex-ai/plandex/blob/HEAD/app/shared/plan_model_settings.go) handles a key part of this chapter's functionality:
```go
}
-func (ps PlanSettings) GetCoderMaxReservedOutputTokens() int {
- modelPack := ps.GetModelPack()
- coder := modelPack.GetCoder()
- fallback := coder.GetFinalLargeContextFallback()
- return fallback.GetReservedOutputTokens(ps.CustomModelsById)
-}
-
func (ps PlanSettings) GetWholeFileBuilderMaxTokens() int {
modelPack := ps.GetModelPack()
builder := modelPack.GetWholeFileBuilder()
@@ -107,24 +57,24 @@ func (ps PlanSettings) GetPlannerMaxConvoTokens() int {
return planner.MaxConvoTokens
}
+ return planner.GetSharedBaseConfig(&ps).DefaultMaxConvoTokens
+}
+
+func (ps PlanSettings) GetPlannerEffectiveMaxTokens() int {
+ maxPlannerTokens := ps.GetPlannerMaxTokens()
+ maxReservedOutputTokens := ps.GetPlannerMaxReservedOutputTokens()
+
```
This function is important because it defines how Plandex Tutorial: Large-Task AI Coding Agent Workflows implements the patterns covered in this chapter.
### `app/shared/plan_model_settings.go`
-The `GetWholeFileBuilderMaxTokens` function in [`app/shared/plan_model_settings.go`](https://github.com/plandex-ai/plandex/blob/HEAD/app/shared/plan_model_settings.go) handles a key part of this chapter's functionality:
+The `GetWholeFileBuilderMaxReservedOutputTokens` function in [`app/shared/plan_model_settings.go`](https://github.com/plandex-ai/plandex/blob/HEAD/app/shared/plan_model_settings.go) handles a key part of this chapter's functionality:
```go
}
-func (ps PlanSettings) GetWholeFileBuilderMaxTokens() int {
- modelPack := ps.GetModelPack()
- builder := modelPack.GetWholeFileBuilder()
- fallback := builder.GetFinalLargeContextFallback()
- return fallback.GetSharedBaseConfig(&ps).MaxTokens
-}
-
func (ps PlanSettings) GetWholeFileBuilderMaxReservedOutputTokens() int {
modelPack := ps.GetModelPack()
builder := modelPack.GetWholeFileBuilder()
@@ -148,24 +98,24 @@ func (ps PlanSettings) GetPlannerEffectiveMaxTokens() int {
maxPlannerTokens := ps.GetPlannerMaxTokens()
maxReservedOutputTokens := ps.GetPlannerMaxReservedOutputTokens()
+ return maxPlannerTokens - maxReservedOutputTokens
+}
+
+func (ps PlanSettings) GetArchitectEffectiveMaxTokens() int {
+ maxArchitectTokens := ps.GetArchitectMaxTokens()
+ maxReservedOutputTokens := ps.GetArchitectMaxReservedOutputTokens()
+
```
This function is important because it defines how Plandex Tutorial: Large-Task AI Coding Agent Workflows implements the patterns covered in this chapter.
### `app/shared/plan_model_settings.go`
-The `GetWholeFileBuilderMaxReservedOutputTokens` function in [`app/shared/plan_model_settings.go`](https://github.com/plandex-ai/plandex/blob/HEAD/app/shared/plan_model_settings.go) handles a key part of this chapter's functionality:
+The `GetPlannerMaxConvoTokens` function in [`app/shared/plan_model_settings.go`](https://github.com/plandex-ai/plandex/blob/HEAD/app/shared/plan_model_settings.go) handles a key part of this chapter's functionality:
```go
}
-func (ps PlanSettings) GetWholeFileBuilderMaxReservedOutputTokens() int {
- modelPack := ps.GetModelPack()
- builder := modelPack.GetWholeFileBuilder()
- fallback := builder.GetFinalLargeOutputFallback()
- return fallback.GetReservedOutputTokens(ps.CustomModelsById)
-}
-
func (ps PlanSettings) GetPlannerMaxConvoTokens() int {
modelPack := ps.GetModelPack()
@@ -189,6 +139,54 @@ func (ps PlanSettings) GetArchitectEffectiveMaxTokens() int {
maxArchitectTokens := ps.GetArchitectMaxTokens()
maxReservedOutputTokens := ps.GetArchitectMaxReservedOutputTokens()
+ return maxArchitectTokens - maxReservedOutputTokens
+}
+
+func (ps PlanSettings) GetCoderEffectiveMaxTokens() int {
+ maxCoderTokens := ps.GetCoderMaxTokens()
+ maxReservedOutputTokens := ps.GetCoderMaxReservedOutputTokens()
+
+```
+
+This function is important because it defines how Plandex Tutorial: Large-Task AI Coding Agent Workflows implements the patterns covered in this chapter.
+
+### `app/shared/plan_model_settings.go`
+
+The `GetPlannerEffectiveMaxTokens` function in [`app/shared/plan_model_settings.go`](https://github.com/plandex-ai/plandex/blob/HEAD/app/shared/plan_model_settings.go) handles a key part of this chapter's functionality:
+
+```go
+}
+
+func (ps PlanSettings) GetPlannerEffectiveMaxTokens() int {
+ maxPlannerTokens := ps.GetPlannerMaxTokens()
+ maxReservedOutputTokens := ps.GetPlannerMaxReservedOutputTokens()
+
+ return maxPlannerTokens - maxReservedOutputTokens
+}
+
+func (ps PlanSettings) GetArchitectEffectiveMaxTokens() int {
+ maxArchitectTokens := ps.GetArchitectMaxTokens()
+ maxReservedOutputTokens := ps.GetArchitectMaxReservedOutputTokens()
+
+ return maxArchitectTokens - maxReservedOutputTokens
+}
+
+func (ps PlanSettings) GetCoderEffectiveMaxTokens() int {
+ maxCoderTokens := ps.GetCoderMaxTokens()
+ maxReservedOutputTokens := ps.GetCoderMaxReservedOutputTokens()
+
+ return maxCoderTokens - maxReservedOutputTokens
+}
+
+func (ps PlanSettings) GetWholeFileBuilderEffectiveMaxTokens() int {
+ maxWholeFileBuilderTokens := ps.GetWholeFileBuilderMaxTokens()
+ maxReservedOutputTokens := ps.GetWholeFileBuilderMaxReservedOutputTokens()
+
+ return maxWholeFileBuilderTokens - maxReservedOutputTokens
+}
+
+func (ps PlanSettings) GetModelProviderOptions() ModelProviderOptions {
+ opts := ModelProviderOptions{}
```
This function is important because it defines how Plandex Tutorial: Large-Task AI Coding Agent Workflows implements the patterns covered in this chapter.
@@ -198,11 +196,11 @@ This function is important because it defines how Plandex Tutorial: Large-Task A
```mermaid
flowchart TD
- A[GetCoderMaxTokens]
- B[GetCoderMaxReservedOutputTokens]
- C[GetWholeFileBuilderMaxTokens]
- D[GetWholeFileBuilderMaxReservedOutputTokens]
- E[GetPlannerMaxConvoTokens]
+ A[GetWholeFileBuilderMaxTokens]
+ B[GetWholeFileBuilderMaxReservedOutputTokens]
+ C[GetPlannerMaxConvoTokens]
+ D[GetPlannerEffectiveMaxTokens]
+ E[GetArchitectEffectiveMaxTokens]
A --> B
B --> C
C --> D
diff --git a/tutorials/plandex-tutorial/06-autonomy-control-and-debugging.md b/tutorials/plandex-tutorial/06-autonomy-control-and-debugging.md
index fd761dde..7c1128b5 100644
--- a/tutorials/plandex-tutorial/06-autonomy-control-and-debugging.md
+++ b/tutorials/plandex-tutorial/06-autonomy-control-and-debugging.md
@@ -26,170 +26,168 @@ You now know how to choose the right autonomy level and debugging posture per ta
Next: [Chapter 7: Git, Branching, and Review Workflows](07-git-branching-and-review-workflows.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `app/shared/context.go`
+### `app/shared/ai_models_custom.go`
-The `TypeAndIcon` function in [`app/shared/context.go`](https://github.com/plandex-ai/plandex/blob/HEAD/app/shared/context.go) handles a key part of this chapter's functionality:
+The `Equals` function in [`app/shared/ai_models_custom.go`](https://github.com/plandex-ai/plandex/blob/HEAD/app/shared/ai_models_custom.go) handles a key part of this chapter's functionality:
```go
}
-func (c *Context) TypeAndIcon() (string, string) {
- var icon string
- var t string
- switch c.ContextType {
- case ContextFileType:
- icon = "📄"
- t = "file"
- case ContextURLType:
- icon = "🌎"
- t = "url"
- case ContextDirectoryTreeType:
- icon = "🗂 "
- t = "tree"
- case ContextNoteType:
- icon = "✏️ "
- t = "note"
- case ContextPipedDataType:
- icon = "↔️ "
- t = "piped"
- case ContextImageType:
- icon = "🖼️ "
- t = "image"
- case ContextMapType:
- icon = "🗺️ "
- t = "map"
- }
+func (input ModelsInput) Equals(other ModelsInput) bool {
+ left := input.FilterUnchanged(&other)
+ right := other.FilterUnchanged(&input)
- return t, icon
+ return left.IsEmpty() && right.IsEmpty()
}
+func (input ModelsInput) CheckNoDuplicates() (bool, string) {
+ sawModelIds := map[ModelId]bool{}
+ sawProviderNames := map[string]bool{}
+ sawPackNames := map[string]bool{}
+
+ builder := strings.Builder{}
+
+ for _, provider := range input.CustomProviders {
+ if _, ok := sawProviderNames[provider.Name]; ok {
+ builder.WriteString(fmt.Sprintf("• Provider %s is duplicated\n", provider.Name))
+ }
+ sawProviderNames[provider.Name] = true
+ }
+
+ for _, model := range input.CustomModels {
+ if _, ok := sawModelIds[model.ModelId]; ok {
+ builder.WriteString(fmt.Sprintf("• Model %s is duplicated\n", model.ModelId))
+ }
+ sawModelIds[model.ModelId] = true
+ }
+
+ for _, pack := range input.CustomModelPacks {
+ if _, ok := sawPackNames[pack.Name]; ok {
```
This function is important because it defines how Plandex Tutorial: Large-Task AI Coding Agent Workflows implements the patterns covered in this chapter.
-### `app/shared/context.go`
+### `app/shared/ai_models_custom.go`
-The `TableForLoadContext` function in [`app/shared/context.go`](https://github.com/plandex-ai/plandex/blob/HEAD/app/shared/context.go) handles a key part of this chapter's functionality:
+The `Hash` function in [`app/shared/ai_models_custom.go`](https://github.com/plandex-ai/plandex/blob/HEAD/app/shared/ai_models_custom.go) handles a key part of this chapter's functionality:
```go
}
-func TableForLoadContext(contexts []*Context, plaintext bool) string {
- tableString := &strings.Builder{}
- table := tablewriter.NewWriter(tableString)
- table.SetHeader([]string{"Name", "Type", "🪙"})
- table.SetAutoWrapText(false)
-
- for _, context := range contexts {
- t, icon := context.TypeAndIcon()
- row := []string{
- " " + icon + " " + context.Name,
- t,
- "+" + strconv.Itoa(context.NumTokens),
- }
-
- if !plaintext {
- table.Rich(row, []tablewriter.Colors{
- {tablewriter.FgHiGreenColor, tablewriter.Bold},
- {tablewriter.FgHiGreenColor},
- {tablewriter.FgHiGreenColor},
- })
- } else {
- table.Append(row)
- }
+// Hash returns a deterministic hash of the ModelsInput.
+// WARNING: This relies on json.Marshal being deterministic for our struct types.
+// Do not add map fields to these structs or the hash will become non-deterministic.
+func (input ModelsInput) Hash() (string, error) {
+ data, err := json.Marshal(input)
+ if err != nil {
+ return "", err
}
- table.Render()
+ hash := sha256.Sum256(data)
+ return hex.EncodeToString(hash[:]), nil
+}
+
+type ClientModelPackSchema struct {
+ Name string `json:"name"`
+ Description string `json:"description"`
- return strings.TrimSpace(tableString.String())
+ ClientModelPackSchemaRoles
}
+func (input *ClientModelPackSchema) ToModelPackSchema() *ModelPackSchema {
+ return &ModelPackSchema{
+ Name: input.Name,
+ Description: input.Description,
+ ModelPackSchemaRoles: input.ClientModelPackSchemaRoles.ToModelPackSchemaRoles(),
+ }
+}
+
+func (input *ModelPackSchema) ToClientModelPackSchema() *ClientModelPackSchema {
+ return &ClientModelPackSchema{
```
This function is important because it defines how Plandex Tutorial: Large-Task AI Coding Agent Workflows implements the patterns covered in this chapter.
-### `app/shared/context.go`
+### `app/shared/ai_models_custom.go`
-The `MarkdownTableForLoadContext` function in [`app/shared/context.go`](https://github.com/plandex-ai/plandex/blob/HEAD/app/shared/context.go) handles a key part of this chapter's functionality:
+The `ToModelPackSchema` function in [`app/shared/ai_models_custom.go`](https://github.com/plandex-ai/plandex/blob/HEAD/app/shared/ai_models_custom.go) handles a key part of this chapter's functionality:
```go
-}
-func MarkdownTableForLoadContext(contexts []*Context) string {
- var sb strings.Builder
- sb.WriteString("| Name | Type | 🪙 |\n")
- sb.WriteString("|------|------|----|\n")
+func (mp *ModelPack) Equals(other *ModelPack) bool {
+ return mp.ToModelPackSchema().Equals(other.ToModelPackSchema())
+}
- for _, context := range contexts {
- t, icon := context.TypeAndIcon()
- sb.WriteString(fmt.Sprintf("| %s %s | %s | +%d |\n",
- icon, context.Name, t, context.NumTokens))
+// Hash returns a deterministic hash of the ModelsInput.
+// WARNING: This relies on json.Marshal being deterministic for our struct types.
+// Do not add map fields to these structs or the hash will become non-deterministic.
+func (input ModelsInput) Hash() (string, error) {
+ data, err := json.Marshal(input)
+ if err != nil {
+ return "", err
}
- return sb.String()
+ hash := sha256.Sum256(data)
+ return hex.EncodeToString(hash[:]), nil
}
-func SummaryForLoadContext(contexts []*Context, tokensAdded, totalTokens int) string {
-
- var hasNote bool
- var hasPiped bool
+type ClientModelPackSchema struct {
+ Name string `json:"name"`
+ Description string `json:"description"`
- var numFiles int
- var numTrees int
- var numUrls int
- var numMaps int
+ ClientModelPackSchemaRoles
+}
- for _, context := range contexts {
- switch context.ContextType {
- case ContextFileType:
- numFiles++
- case ContextURLType:
- numUrls++
+func (input *ClientModelPackSchema) ToModelPackSchema() *ModelPackSchema {
+ return &ModelPackSchema{
+ Name: input.Name,
+ Description: input.Description,
+ ModelPackSchemaRoles: input.ClientModelPackSchemaRoles.ToModelPackSchemaRoles(),
+ }
+}
```
This function is important because it defines how Plandex Tutorial: Large-Task AI Coding Agent Workflows implements the patterns covered in this chapter.
-### `app/shared/context.go`
+### `app/shared/ai_models_custom.go`
-The `SummaryForLoadContext` function in [`app/shared/context.go`](https://github.com/plandex-ai/plandex/blob/HEAD/app/shared/context.go) handles a key part of this chapter's functionality:
+The `ToClientModelPackSchema` function in [`app/shared/ai_models_custom.go`](https://github.com/plandex-ai/plandex/blob/HEAD/app/shared/ai_models_custom.go) handles a key part of this chapter's functionality:
```go
}
-func SummaryForLoadContext(contexts []*Context, tokensAdded, totalTokens int) string {
-
- var hasNote bool
- var hasPiped bool
-
- var numFiles int
- var numTrees int
- var numUrls int
- var numMaps int
-
- for _, context := range contexts {
- switch context.ContextType {
- case ContextFileType:
- numFiles++
- case ContextURLType:
- numUrls++
- case ContextDirectoryTreeType:
- numTrees++
- case ContextNoteType:
- hasNote = true
- case ContextPipedDataType:
- hasPiped = true
- case ContextMapType:
- numMaps++
- }
+func (input *ModelPackSchema) ToClientModelPackSchema() *ClientModelPackSchema {
+ return &ClientModelPackSchema{
+ Name: input.Name,
+ Description: input.Description,
+ ClientModelPackSchemaRoles: input.ToClientModelPackSchemaRoles(),
}
+}
+
+type ClientModelsInput struct {
+ SchemaUrl SchemaUrl `json:"$schema"`
+
+ CustomModels []*CustomModel `json:"models,omitempty"`
+ CustomProviders []*CustomProvider `json:"providers,omitempty"`
+ CustomModelPacks []*ClientModelPackSchema `json:"modelPacks,omitempty"`
+}
- var added []string
+func (input ClientModelsInput) ToModelsInput() ModelsInput {
+ modelPacks := []*ModelPackSchema{}
+ for _, pack := range input.CustomModelPacks {
+ modelPacks = append(modelPacks, pack.ToModelPackSchema())
+ }
+
+ return ModelsInput{
+ CustomModels: input.CustomModels,
+ CustomProviders: input.CustomProviders,
+ CustomModelPacks: modelPacks,
+ }
+}
- if hasNote {
+func (input *ClientModelsInput) PrepareUpdate() {
```
This function is important because it defines how Plandex Tutorial: Large-Task AI Coding Agent Workflows implements the patterns covered in this chapter.
@@ -199,11 +197,11 @@ This function is important because it defines how Plandex Tutorial: Large-Task A
```mermaid
flowchart TD
- A[TypeAndIcon]
- B[TableForLoadContext]
- C[MarkdownTableForLoadContext]
- D[SummaryForLoadContext]
- E[TableForRemoveContext]
+ A[Equals]
+ B[Hash]
+ C[ToModelPackSchema]
+ D[ToClientModelPackSchema]
+ E[ToModelsInput]
A --> B
B --> C
C --> D
diff --git a/tutorials/plandex-tutorial/07-git-branching-and-review-workflows.md b/tutorials/plandex-tutorial/07-git-branching-and-review-workflows.md
index 8827f13e..c5ae929b 100644
--- a/tutorials/plandex-tutorial/07-git-branching-and-review-workflows.md
+++ b/tutorials/plandex-tutorial/07-git-branching-and-review-workflows.md
@@ -26,186 +26,16 @@ You now have a repeatable review workflow for team-scale Plandex adoption.
Next: [Chapter 8: Self-Hosting and Production Operations](08-self-hosting-and-production-operations.md)
-## Depth Expansion Playbook
-
-## Source Code Walkthrough
-
-### `app/shared/utils.go`
-
-The `AddLineNums` function in [`app/shared/utils.go`](https://github.com/plandex-ai/plandex/blob/HEAD/app/shared/utils.go) handles a key part of this chapter's functionality:
-
-```go
-type LineNumberedTextType string
-
-func AddLineNums(s string) LineNumberedTextType {
- return LineNumberedTextType(AddLineNumsWithPrefix(s, "pdx-"))
-}
-
-func AddLineNumsWithPrefix(s, prefix string) LineNumberedTextType {
- var res string
- for i, line := range strings.Split(s, "\n") {
- res += fmt.Sprintf("%s%d: %s\n", prefix, i+1, line)
- }
- return LineNumberedTextType(res)
-}
-
-func RemoveLineNums(s LineNumberedTextType) string {
- return RemoveLineNumsWithPrefix(s, "pdx-")
-}
-
-func RemoveLineNumsWithPrefix(s LineNumberedTextType, prefix string) string {
- return regexp.MustCompile(fmt.Sprintf(`(?m)^%s\d+: `, prefix)).ReplaceAllString(string(s), "")
-}
-
-// indexRunes searches for the slice of runes `needle` in the slice of runes `haystack`
-// and returns the index of the first rune of `needle` in `haystack`, or -1 if `needle` is not present.
-func IndexRunes(haystack []rune, needle []rune) int {
- if len(needle) == 0 {
- return 0
- }
- if len(haystack) == 0 {
- return -1
- }
-
-```
-
-This function is important because it defines how Plandex Tutorial: Large-Task AI Coding Agent Workflows implements the patterns covered in this chapter.
-
-### `app/shared/utils.go`
-
-The `AddLineNumsWithPrefix` function in [`app/shared/utils.go`](https://github.com/plandex-ai/plandex/blob/HEAD/app/shared/utils.go) handles a key part of this chapter's functionality:
-
-```go
-
-func AddLineNums(s string) LineNumberedTextType {
- return LineNumberedTextType(AddLineNumsWithPrefix(s, "pdx-"))
-}
-
-func AddLineNumsWithPrefix(s, prefix string) LineNumberedTextType {
- var res string
- for i, line := range strings.Split(s, "\n") {
- res += fmt.Sprintf("%s%d: %s\n", prefix, i+1, line)
- }
- return LineNumberedTextType(res)
-}
-
-func RemoveLineNums(s LineNumberedTextType) string {
- return RemoveLineNumsWithPrefix(s, "pdx-")
-}
-
-func RemoveLineNumsWithPrefix(s LineNumberedTextType, prefix string) string {
- return regexp.MustCompile(fmt.Sprintf(`(?m)^%s\d+: `, prefix)).ReplaceAllString(string(s), "")
-}
-
-// indexRunes searches for the slice of runes `needle` in the slice of runes `haystack`
-// and returns the index of the first rune of `needle` in `haystack`, or -1 if `needle` is not present.
-func IndexRunes(haystack []rune, needle []rune) int {
- if len(needle) == 0 {
- return 0
- }
- if len(haystack) == 0 {
- return -1
- }
-
- // Search for the needle
-```
-
-This function is important because it defines how Plandex Tutorial: Large-Task AI Coding Agent Workflows implements the patterns covered in this chapter.
-
-### `app/shared/utils.go`
-
-The `RemoveLineNums` function in [`app/shared/utils.go`](https://github.com/plandex-ai/plandex/blob/HEAD/app/shared/utils.go) handles a key part of this chapter's functionality:
-
-```go
-}
-
-func RemoveLineNums(s LineNumberedTextType) string {
- return RemoveLineNumsWithPrefix(s, "pdx-")
-}
-
-func RemoveLineNumsWithPrefix(s LineNumberedTextType, prefix string) string {
- return regexp.MustCompile(fmt.Sprintf(`(?m)^%s\d+: `, prefix)).ReplaceAllString(string(s), "")
-}
-
-// indexRunes searches for the slice of runes `needle` in the slice of runes `haystack`
-// and returns the index of the first rune of `needle` in `haystack`, or -1 if `needle` is not present.
-func IndexRunes(haystack []rune, needle []rune) int {
- if len(needle) == 0 {
- return 0
- }
- if len(haystack) == 0 {
- return -1
- }
-
- // Search for the needle
- for i := 0; i <= len(haystack)-len(needle); i++ {
- found := true
- for j := 0; j < len(needle); j++ {
- if haystack[i+j] != needle[j] {
- found = false
- break
- }
- }
- if found {
- return i
- }
-```
-
-This function is important because it defines how Plandex Tutorial: Large-Task AI Coding Agent Workflows implements the patterns covered in this chapter.
-
-### `app/shared/utils.go`
-
-The `RemoveLineNumsWithPrefix` function in [`app/shared/utils.go`](https://github.com/plandex-ai/plandex/blob/HEAD/app/shared/utils.go) handles a key part of this chapter's functionality:
-
-```go
-
-func RemoveLineNums(s LineNumberedTextType) string {
- return RemoveLineNumsWithPrefix(s, "pdx-")
-}
-
-func RemoveLineNumsWithPrefix(s LineNumberedTextType, prefix string) string {
- return regexp.MustCompile(fmt.Sprintf(`(?m)^%s\d+: `, prefix)).ReplaceAllString(string(s), "")
-}
-
-// indexRunes searches for the slice of runes `needle` in the slice of runes `haystack`
-// and returns the index of the first rune of `needle` in `haystack`, or -1 if `needle` is not present.
-func IndexRunes(haystack []rune, needle []rune) int {
- if len(needle) == 0 {
- return 0
- }
- if len(haystack) == 0 {
- return -1
- }
-
- // Search for the needle
- for i := 0; i <= len(haystack)-len(needle); i++ {
- found := true
- for j := 0; j < len(needle); j++ {
- if haystack[i+j] != needle[j] {
- found = false
- break
- }
- }
- if found {
- return i
- }
- }
-```
-
-This function is important because it defines how Plandex Tutorial: Large-Task AI Coding Agent Workflows implements the patterns covered in this chapter.
-
## How These Components Connect
```mermaid
-flowchart TD
- A[AddLineNums]
- B[AddLineNumsWithPrefix]
- C[RemoveLineNums]
- D[RemoveLineNumsWithPrefix]
- E[IndexRunes]
- A --> B
- B --> C
- C --> D
- D --> E
+flowchart LR
+ A[plandex changes] --> B[Diff Sandbox Branch]
+ B --> C[Human Review]
+ C -->|Approve| D[plandex apply]
+ C -->|Reject| E[plandex reject]
+ D --> F[Main Working Branch]
+ F --> G[git commit / push]
+ G --> H[Team PR / Review]
```
diff --git a/tutorials/plandex-tutorial/08-self-hosting-and-production-operations.md b/tutorials/plandex-tutorial/08-self-hosting-and-production-operations.md
index d3c0faf5..08a5bdc2 100644
--- a/tutorials/plandex-tutorial/08-self-hosting-and-production-operations.md
+++ b/tutorials/plandex-tutorial/08-self-hosting-and-production-operations.md
@@ -28,170 +28,168 @@ This chapter covers local/self-hosted operation patterns for production-grade Pl
You now have an operations baseline for running Plandex as a serious engineering tool.
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `app/server/litellm_proxy.py`
-
-The `passthrough` function in [`app/server/litellm_proxy.py`](https://github.com/plandex-ai/plandex/blob/HEAD/app/server/litellm_proxy.py) handles a key part of this chapter's functionality:
-
-```py
-
-@app.post("/v1/chat/completions")
-async def passthrough(request: Request):
- payload = await request.json()
-
- if LOGGING_ENABLED:
- # Log the request data for debugging
- try:
- # Get headers (excluding authorization to avoid logging credentials)
- headers = dict(request.headers)
- if "Authorization" in headers:
- headers["Authorization"] = "Bearer [REDACTED]"
- if "api-key" in headers:
- headers["api-key"] = "[REDACTED]"
-
- # Create a log-friendly representation
- request_data = {
- "method": request.method,
- "url": str(request.url),
- "headers": headers,
- "body": payload
- }
-
- # Log the request data
- print("Incoming request to /v1/chat/completions:")
- print(json.dumps(request_data, indent=2))
- except Exception as e:
- print(f"Error logging request: {str(e)}")
-
- model = payload.get("model", None)
- print(f"Litellm proxy: calling model: {model}")
+### `app/shared/utils.go`
-```
+The `ReplaceReverse` function in [`app/shared/utils.go`](https://github.com/plandex-ai/plandex/blob/HEAD/app/shared/utils.go) handles a key part of this chapter's functionality:
-This function is important because it defines how Plandex Tutorial: Large-Task AI Coding Agent Workflows implements the patterns covered in this chapter.
+```go
+}
+
+func ReplaceReverse(s, old, new string, n int) string {
+ // If n is negative, there is no limit to the number of replacements
+ if n == 0 {
+ return s
+ }
+
+ if n < 0 {
+ return strings.Replace(s, old, new, -1)
+ }
+
+ // If n is positive, replace the last n occurrences of old with new
+ var res string
+ for i := 0; i < n; i++ {
+ idx := strings.LastIndex(s, old)
+ if idx == -1 {
+ break
+ }
+ res = s[:idx] + new + s[idx+len(old):]
+ s = res
+ }
+ return res
+}
-### `app/server/litellm_proxy.py`
-
-The `error_response` function in [`app/server/litellm_proxy.py`](https://github.com/plandex-ai/plandex/blob/HEAD/app/server/litellm_proxy.py) handles a key part of this chapter's functionality:
-
-```py
- response_stream = completion(api_key=api_key, **payload)
- except Exception as e:
- return error_response(e)
- def stream_generator():
- try:
- for chunk in response_stream:
- yield f"data: {json.dumps(chunk.to_dict())}\n\n"
- yield "data: [DONE]\n\n"
- except Exception as e:
- # surface the problem to the client _inside_ the SSE stream
- yield f"data: {json.dumps({'error': str(e)})}\n\n"
- return
-
- finally:
- try:
- response_stream.close()
- except AttributeError:
- pass
-
- print(f"Litellm proxy: Initiating streaming response for model: {payload.get('model', 'unknown')}")
- return StreamingResponse(stream_generator(), media_type="text/event-stream")
-
- else:
- print(f"Litellm proxy: Non-streaming response requested for model: {payload.get('model', 'unknown')}")
- try:
- result = completion(api_key=api_key, **payload)
- except Exception as e:
- return error_response(e)
- return JSONResponse(content=result)
-
- except Exception as e:
- err_msg = str(e)
+func NormalizeEOL(data []byte) []byte {
+ if !looksTextish(data) {
+ return data
+ }
+
+ // CRLF -> LF
+ n := bytes.ReplaceAll(data, []byte{'\r', '\n'}, []byte{'\n'})
```
This function is important because it defines how Plandex Tutorial: Large-Task AI Coding Agent Workflows implements the patterns covered in this chapter.
-### `app/server/litellm_proxy.py`
-
-The `normalise_for_ollama` function in [`app/server/litellm_proxy.py`](https://github.com/plandex-ai/plandex/blob/HEAD/app/server/litellm_proxy.py) handles a key part of this chapter's functionality:
-
-```py
-
- # clean up for ollama if needed
- payload = normalise_for_ollama(payload)
-
- try:
- if payload.get("stream"):
-
- try:
- response_stream = completion(api_key=api_key, **payload)
- except Exception as e:
- return error_response(e)
- def stream_generator():
- try:
- for chunk in response_stream:
- yield f"data: {json.dumps(chunk.to_dict())}\n\n"
- yield "data: [DONE]\n\n"
- except Exception as e:
- # surface the problem to the client _inside_ the SSE stream
- yield f"data: {json.dumps({'error': str(e)})}\n\n"
- return
-
- finally:
- try:
- response_stream.close()
- except AttributeError:
- pass
-
- print(f"Litellm proxy: Initiating streaming response for model: {payload.get('model', 'unknown')}")
- return StreamingResponse(stream_generator(), media_type="text/event-stream")
-
- else:
- print(f"Litellm proxy: Non-streaming response requested for model: {payload.get('model', 'unknown')}")
+### `app/shared/utils.go`
+
+The `NormalizeEOL` function in [`app/shared/utils.go`](https://github.com/plandex-ai/plandex/blob/HEAD/app/shared/utils.go) handles a key part of this chapter's functionality:
+
+```go
+}
+
+func NormalizeEOL(data []byte) []byte {
+ if !looksTextish(data) {
+ return data
+ }
+
+ // CRLF -> LF
+ n := bytes.ReplaceAll(data, []byte{'\r', '\n'}, []byte{'\n'})
+
+ // treat stray CR as newline as well
+ n = bytes.ReplaceAll(n, []byte{'\r'}, []byte{'\n'})
+ return n
+}
+
+// looksTextish checks some very cheap heuristics:
+// 1. no NUL bytes → probably not binary
+// 2. valid UTF-8 → BOMs are OK
+// 3. printable ratio → ≥ 90 % of runes are >= 0x20 or common whitespace
+func looksTextish(b []byte) bool {
+ if bytes.IndexByte(b, 0x00) != -1 { // 1
+ return false
+ }
+ if !utf8.Valid(b) { // 2
+ return false
+ }
+
+ printable := 0
+ for len(b) > 0 {
+ r, size := utf8.DecodeRune(b)
+ b = b[size:]
+ switch {
```
This function is important because it defines how Plandex Tutorial: Large-Task AI Coding Agent Workflows implements the patterns covered in this chapter.
-### `app/shared/images.go`
+### `app/shared/utils.go`
-The `GetImageTokens` function in [`app/shared/images.go`](https://github.com/plandex-ai/plandex/blob/HEAD/app/shared/images.go) handles a key part of this chapter's functionality:
+The `looksTextish` function in [`app/shared/utils.go`](https://github.com/plandex-ai/plandex/blob/HEAD/app/shared/utils.go) handles a key part of this chapter's functionality:
```go
-)
-func GetImageTokens(base64Image string, detail openai.ImageURLDetail) (int, error) {
- imageData, err := base64.StdEncoding.DecodeString(base64Image)
- if err != nil {
- log.Println("failed to decode base64 image data:", err)
- return 0, fmt.Errorf("failed to decode base64 image data: %w", err)
+func NormalizeEOL(data []byte) []byte {
+ if !looksTextish(data) {
+ return data
}
- return GetImageTokensFromHeader(bytes.NewReader(imageData), detail, int64(len(imageData)))
+ // CRLF -> LF
+ n := bytes.ReplaceAll(data, []byte{'\r', '\n'}, []byte{'\n'})
+
+ // treat stray CR as newline as well
+ n = bytes.ReplaceAll(n, []byte{'\r'}, []byte{'\n'})
+ return n
}
-func GetImageTokensFromHeader(reader io.Reader, detail openai.ImageURLDetail, maxBytes int64) (int, error) {
- reader = io.LimitReader(reader, maxBytes)
- img, _, err := image.DecodeConfig(reader)
- if err != nil {
- log.Println("failed to decode image config:", err)
- return 0, fmt.Errorf("failed to decode image config: %w", err)
+// looksTextish checks some very cheap heuristics:
+// 1. no NUL bytes → probably not binary
+// 2. valid UTF-8 → BOMs are OK
+// 3. printable ratio → ≥ 90 % of runes are >= 0x20 or common whitespace
+func looksTextish(b []byte) bool {
+ if bytes.IndexByte(b, 0x00) != -1 { // 1
+ return false
}
+ if !utf8.Valid(b) { // 2
+ return false
+ }
+
+ printable := 0
+ for len(b) > 0 {
+ r, size := utf8.DecodeRune(b)
+ b = b[size:]
+ switch {
+ case r == '\n', r == '\r', r == '\t':
+```
+
+This function is important because it defines how Plandex Tutorial: Large-Task AI Coding Agent Workflows implements the patterns covered in this chapter.
- width, height := img.Width, img.Height
+### `app/shared/plan_result.go`
- anthropicTokens := getAnthropicImageTokens(width, height)
- googleTokens := getGoogleImageTokens(width, height)
- openaiTokens := getOpenAIImageTokens(width, height, detail)
+The `IsPending` function in [`app/shared/plan_result.go`](https://github.com/plandex-ai/plandex/blob/HEAD/app/shared/plan_result.go) handles a key part of this chapter's functionality:
- // log.Printf("GetImageTokens - width: %d, height: %d\n", width, height)
- // log.Printf("GetImageTokens - anthropicTokens: %d\n", anthropicTokens)
- // log.Printf("GetImageTokens - googleTokens: %d\n", googleTokens)
- // log.Printf("GetImageTokens - openaiTokens: %d\n", openaiTokens)
+```go
+)
+
+func (rep *Replacement) IsPending() bool {
+ return !rep.Failed && rep.RejectedAt == nil
+}
+
+func (rep *Replacement) SetRejected(t time.Time) {
+ rep.RejectedAt = &t
+}
+
+func (res *PlanFileResult) NumPendingReplacements() int {
+ numPending := 0
+ for _, rep := range res.Replacements {
+ if rep.IsPending() {
+ numPending++
+ }
+ }
+ return numPending
+}
+
+func (res *PlanFileResult) IsPending() bool {
+ return res.AppliedAt == nil && res.RejectedAt == nil && (res.Content != "" || res.NumPendingReplacements() > 0 || res.RemovedFile)
+}
- // get max of the three
+func (p PlanFileResultsByPath) SetApplied(t time.Time) {
+ for _, planResults := range p {
+ for _, planResult := range planResults {
+ if !planResult.IsPending() {
+ continue
+ }
+ planResult.AppliedAt = &t
+ }
```
This function is important because it defines how Plandex Tutorial: Large-Task AI Coding Agent Workflows implements the patterns covered in this chapter.
@@ -201,11 +199,11 @@ This function is important because it defines how Plandex Tutorial: Large-Task A
```mermaid
flowchart TD
- A[passthrough]
- B[error_response]
- C[normalise_for_ollama]
- D[GetImageTokens]
- E[GetImageTokensFromHeader]
+ A[ReplaceReverse]
+ B[NormalizeEOL]
+ C[looksTextish]
+ D[IsPending]
+ E[SetRejected]
A --> B
B --> C
C --> D
diff --git a/tutorials/planning-with-files-tutorial/01-getting-started.md b/tutorials/planning-with-files-tutorial/01-getting-started.md
index 8b43a49d..7b7c1bfa 100644
--- a/tutorials/planning-with-files-tutorial/01-getting-started.md
+++ b/tutorials/planning-with-files-tutorial/01-getting-started.md
@@ -53,8 +53,6 @@ You now have the baseline workflow installed and active.
Next: [Chapter 2: Core Philosophy and the 3-File Pattern](02-core-philosophy-and-the-3-file-pattern.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `scripts/session-catchup.py`
@@ -180,47 +178,6 @@ def get_sessions_sorted_opencode(storage_dir: Path) -> List[Path]:
This function is important because it defines how Planning with Files Tutorial: Persistent Markdown Workflow Memory for AI Coding Agents implements the patterns covered in this chapter.
-### `scripts/session-catchup.py`
-
-The `get_sessions_sorted` function in [`scripts/session-catchup.py`](https://github.com/OthmanAdi/planning-with-files/blob/HEAD/scripts/session-catchup.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def get_sessions_sorted(project_dir: Path) -> List[Path]:
- """Get all session files sorted by modification time (newest first)."""
- sessions = list(project_dir.glob('*.jsonl'))
- main_sessions = [s for s in sessions if not s.name.startswith('agent-')]
- return sorted(main_sessions, key=lambda p: p.stat().st_mtime, reverse=True)
-
-
-def get_sessions_sorted_opencode(storage_dir: Path) -> List[Path]:
- """
- Get all OpenCode session files sorted by modification time.
- OpenCode stores sessions at: storage/session/{projectHash}/{sessionID}.json
- """
- session_dir = storage_dir / 'session'
- if not session_dir.exists():
- return []
-
- sessions = []
- for project_hash_dir in session_dir.iterdir():
- if project_hash_dir.is_dir():
- for session_file in project_hash_dir.glob('*.json'):
- sessions.append(session_file)
-
- return sorted(sessions, key=lambda p: p.stat().st_mtime, reverse=True)
-
-
-def get_session_first_timestamp(session_file: Path) -> Optional[str]:
- """Get the timestamp of the first message in a session."""
- try:
- with open(session_file, 'r') as f:
- for line in f:
-```
-
-This function is important because it defines how Planning with Files Tutorial: Persistent Markdown Workflow Memory for AI Coding Agents implements the patterns covered in this chapter.
-
## How These Components Connect
@@ -229,10 +186,6 @@ flowchart TD
A[detect_ide]
B[get_project_dir_claude]
C[get_project_dir_opencode]
- D[get_sessions_sorted]
- E[get_sessions_sorted_opencode]
A --> B
B --> C
- C --> D
- D --> E
```
diff --git a/tutorials/planning-with-files-tutorial/02-core-philosophy-and-the-3-file-pattern.md b/tutorials/planning-with-files-tutorial/02-core-philosophy-and-the-3-file-pattern.md
index 4a802027..7e12f88c 100644
--- a/tutorials/planning-with-files-tutorial/02-core-philosophy-and-the-3-file-pattern.md
+++ b/tutorials/planning-with-files-tutorial/02-core-philosophy-and-the-3-file-pattern.md
@@ -42,170 +42,127 @@ You now understand the planning model that keeps long-running tasks stable.
Next: [Chapter 3: Installation Paths Across IDEs and Agents](03-installation-paths-across-ides-and-agents.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `scripts/sync-ide-folders.py`
+### `scripts/session-catchup.py`
-The `sync_file` function in [`scripts/sync-ide-folders.py`](https://github.com/OthmanAdi/planning-with-files/blob/HEAD/scripts/sync-ide-folders.py) handles a key part of this chapter's functionality:
+The `get_sessions_sorted` function in [`scripts/session-catchup.py`](https://github.com/OthmanAdi/planning-with-files/blob/HEAD/scripts/session-catchup.py) handles a key part of this chapter's functionality:
```py
-def sync_file(src, dst, *, dry_run=False):
- """Copy src to dst. Returns (action, detail) tuple.
-
- Actions: "updated", "created", "skipped" (already identical), "missing_src"
- """
- if not src.exists():
- return "missing_src", f"Canonical file not found: {src}"
-
- src_hash = file_hash(src)
- dst_hash = file_hash(dst)
+def get_sessions_sorted(project_dir: Path) -> List[Path]:
+ """Get all session files sorted by modification time (newest first)."""
+ sessions = list(project_dir.glob('*.jsonl'))
+ main_sessions = [s for s in sessions if not s.name.startswith('agent-')]
+ return sorted(main_sessions, key=lambda p: p.stat().st_mtime, reverse=True)
- if src_hash == dst_hash:
- return "skipped", "Already up to date"
- action = "created" if dst_hash is None else "updated"
-
- if not dry_run:
- dst.parent.mkdir(parents=True, exist_ok=True)
- shutil.copy2(src, dst)
+def get_sessions_sorted_opencode(storage_dir: Path) -> List[Path]:
+ """
+ Get all OpenCode session files sorted by modification time.
+ OpenCode stores sessions at: storage/session/{projectHash}/{sessionID}.json
+ """
+ session_dir = storage_dir / 'session'
+ if not session_dir.exists():
+ return []
- return action, f"{'Would ' if dry_run else ''}{action}: {dst}"
+ sessions = []
+ for project_hash_dir in session_dir.iterdir():
+ if project_hash_dir.is_dir():
+ for session_file in project_hash_dir.glob('*.json'):
+ sessions.append(session_file)
+ return sorted(sessions, key=lambda p: p.stat().st_mtime, reverse=True)
-# ─── Main ──────────────────────────────────────────────────────────
-def parse_args(argv=None):
- """Parse CLI arguments for sync behavior."""
- parser = argparse.ArgumentParser(
- description=(
- "Sync shared planning-with-files assets from canonical source "
+def get_session_first_timestamp(session_file: Path) -> Optional[str]:
+ """Get the timestamp of the first message in a session."""
+ try:
+ with open(session_file, 'r') as f:
+ for line in f:
```
This function is important because it defines how Planning with Files Tutorial: Persistent Markdown Workflow Memory for AI Coding Agents implements the patterns covered in this chapter.
-### `scripts/sync-ide-folders.py`
+### `scripts/session-catchup.py`
-The `parse_args` function in [`scripts/sync-ide-folders.py`](https://github.com/OthmanAdi/planning-with-files/blob/HEAD/scripts/sync-ide-folders.py) handles a key part of this chapter's functionality:
+The `get_sessions_sorted_opencode` function in [`scripts/session-catchup.py`](https://github.com/OthmanAdi/planning-with-files/blob/HEAD/scripts/session-catchup.py) handles a key part of this chapter's functionality:
```py
-# ─── Main ──────────────────────────────────────────────────────────
-
-def parse_args(argv=None):
- """Parse CLI arguments for sync behavior."""
- parser = argparse.ArgumentParser(
- description=(
- "Sync shared planning-with-files assets from canonical source "
- "to IDE-specific folders."
- )
- )
- parser.add_argument(
- "--dry-run",
- action="store_true",
- help="Preview changes without writing files.",
- )
- parser.add_argument(
- "--verify",
- action="store_true",
- help="Check for drift only; exit with code 1 if drift is found.",
- )
- return parser.parse_args(argv)
-
-
-def main(argv=None):
- args = parse_args(argv)
- dry_run = args.dry_run
- verify = args.verify
-
- # Must run from repo root
- if not CANONICAL.exists():
- print(f"Error: Canonical source not found at {CANONICAL}/")
- print("Run this script from the repo root.")
-```
-
-This function is important because it defines how Planning with Files Tutorial: Persistent Markdown Workflow Memory for AI Coding Agents implements the patterns covered in this chapter.
-### `scripts/sync-ide-folders.py`
-The `main` function in [`scripts/sync-ide-folders.py`](https://github.com/OthmanAdi/planning-with-files/blob/HEAD/scripts/sync-ide-folders.py) handles a key part of this chapter's functionality:
-
-```py
- ),
+def get_sessions_sorted_opencode(storage_dir: Path) -> List[Path]:
+ """
+ Get all OpenCode session files sorted by modification time.
+ OpenCode stores sessions at: storage/session/{projectHash}/{sessionID}.json
+ """
+ session_dir = storage_dir / 'session'
+ if not session_dir.exists():
+ return []
- # Kiro: maintained under .kiro/ (skill + wrappers); not synced from canonical scripts/.
- ".kiro": {},
-}
+ sessions = []
+ for project_hash_dir in session_dir.iterdir():
+ if project_hash_dir.is_dir():
+ for session_file in project_hash_dir.glob('*.json'):
+ sessions.append(session_file)
+ return sorted(sessions, key=lambda p: p.stat().st_mtime, reverse=True)
-# ─── Utility functions ─────────────────────────────────────────────
-def file_hash(path):
- """Return SHA-256 hash of a file, or None if it doesn't exist."""
+def get_session_first_timestamp(session_file: Path) -> Optional[str]:
+ """Get the timestamp of the first message in a session."""
try:
- return hashlib.sha256(Path(path).read_bytes()).hexdigest()
- except FileNotFoundError:
- return None
-
-
-def sync_file(src, dst, *, dry_run=False):
- """Copy src to dst. Returns (action, detail) tuple.
-
- Actions: "updated", "created", "skipped" (already identical), "missing_src"
- """
- if not src.exists():
- return "missing_src", f"Canonical file not found: {src}"
-
- src_hash = file_hash(src)
- dst_hash = file_hash(dst)
-
- if src_hash == dst_hash:
- return "skipped", "Already up to date"
-
- action = "created" if dst_hash is None else "updated"
+ with open(session_file, 'r') as f:
+ for line in f:
+ try:
+ data = json.loads(line)
+ ts = data.get('timestamp')
+ if ts:
+ return ts
+ except:
+ continue
```
This function is important because it defines how Planning with Files Tutorial: Persistent Markdown Workflow Memory for AI Coding Agents implements the patterns covered in this chapter.
-### `.opencode/skills/planning-with-files/scripts/session-catchup.py`
+### `scripts/session-catchup.py`
-The `get_project_dir` function in [`.opencode/skills/planning-with-files/scripts/session-catchup.py`](https://github.com/OthmanAdi/planning-with-files/blob/HEAD/.opencode/skills/planning-with-files/scripts/session-catchup.py) handles a key part of this chapter's functionality:
+The `get_session_first_timestamp` function in [`scripts/session-catchup.py`](https://github.com/OthmanAdi/planning-with-files/blob/HEAD/scripts/session-catchup.py) handles a key part of this chapter's functionality:
```py
-def get_project_dir(project_path: str) -> Path:
- """Convert project path to OpenCode's storage path format."""
- # Normalize to an absolute path to ensure a stable representation
- # .as_posix() handles '\' -> '/' conversion on Windows automatically
- resolved_str = Path(project_path).resolve().as_posix()
-
- # Sanitize path: replace separators with '-', remove ':' (Windows drives)
- sanitized = resolved_str.replace('/', '-').replace(':', '')
-
- # Apply legacy naming convention: leading '-' and '_' -> '-'
- if not sanitized.startswith('-'):
- sanitized = '-' + sanitized
- sanitized_name = sanitized.replace('_', '-')
-
- # 1. Check Legacy Location first (~/.opencode/sessions/...)
- legacy_dir = Path.home() / '.opencode' / 'sessions' / sanitized_name
- if legacy_dir.is_dir():
- return legacy_dir
-
- # 2. Standard Layout
- data_root_env = os.getenv('OPENCODE_DATA_DIR')
- if data_root_env:
- data_root = Path(data_root_env)
- else:
- # Respect XDG_DATA_HOME if set, otherwise use default
- xdg_root = os.getenv('XDG_DATA_HOME')
- if xdg_root:
- data_root = Path(xdg_root) / 'opencode' / 'storage'
- else:
- data_root = Path.home() / '.local' / 'share' / 'opencode' / 'storage'
+def get_session_first_timestamp(session_file: Path) -> Optional[str]:
+ """Get the timestamp of the first message in a session."""
+ try:
+ with open(session_file, 'r') as f:
+ for line in f:
+ try:
+ data = json.loads(line)
+ ts = data.get('timestamp')
+ if ts:
+ return ts
+ except:
+ continue
+ except:
+ pass
+ return None
+
+
+def scan_for_planning_update(session_file: Path) -> Tuple[int, Optional[str]]:
+ """
+ Quickly scan a session file for planning file updates.
+ Returns (line_number, filename) of last update, or (-1, None) if none found.
+ """
+ last_update_line = -1
+ last_update_file = None
+
+ try:
+ with open(session_file, 'r') as f:
+ for line_num, line in enumerate(f):
+ if '"Write"' not in line and '"Edit"' not in line:
+ continue
```
This function is important because it defines how Planning with Files Tutorial: Persistent Markdown Workflow Memory for AI Coding Agents implements the patterns covered in this chapter.
@@ -215,13 +172,9 @@ This function is important because it defines how Planning with Files Tutorial:
```mermaid
flowchart TD
- A[sync_file]
- B[parse_args]
- C[main]
- D[get_project_dir]
- E[get_sessions_sorted]
+ A[get_sessions_sorted]
+ B[get_sessions_sorted_opencode]
+ C[get_session_first_timestamp]
A --> B
B --> C
- C --> D
- D --> E
```
diff --git a/tutorials/planning-with-files-tutorial/03-installation-paths-across-ides-and-agents.md b/tutorials/planning-with-files-tutorial/03-installation-paths-across-ides-and-agents.md
index 5d9b533a..440e2508 100644
--- a/tutorials/planning-with-files-tutorial/03-installation-paths-across-ides-and-agents.md
+++ b/tutorials/planning-with-files-tutorial/03-installation-paths-across-ides-and-agents.md
@@ -43,170 +43,127 @@ You now have a clear multi-environment installation model.
Next: [Chapter 4: Commands, Hooks, and Workflow Orchestration](04-commands-hooks-and-workflow-orchestration.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `.codex/skills/planning-with-files/scripts/session-catchup.py`
+### `scripts/session-catchup.py`
-The `get_project_dir` function in [`.codex/skills/planning-with-files/scripts/session-catchup.py`](https://github.com/OthmanAdi/planning-with-files/blob/HEAD/.codex/skills/planning-with-files/scripts/session-catchup.py) handles a key part of this chapter's functionality:
+The `scan_for_planning_update` function in [`scripts/session-catchup.py`](https://github.com/OthmanAdi/planning-with-files/blob/HEAD/scripts/session-catchup.py) handles a key part of this chapter's functionality:
```py
-def get_project_dir(project_path: str) -> Tuple[Optional[Path], Optional[str]]:
- """Resolve session storage path for the current runtime variant."""
- normalized = normalize_path(project_path)
-
- # Claude Code's sanitization: replace path separators and : with -
- sanitized = normalized.replace('\\', '-').replace('/', '-').replace(':', '-')
- sanitized = sanitized.replace('_', '-')
- # Strip leading dash if present (Unix absolute paths start with /)
- if sanitized.startswith('-'):
- sanitized = sanitized[1:]
-
- claude_path = Path.home() / '.claude' / 'projects' / sanitized
-
- # Codex stores sessions in ~/.codex/sessions with a different format.
- # Avoid silently scanning Claude paths when running from Codex skill folder.
- script_path = Path(__file__).as_posix().lower()
- is_codex_variant = '/.codex/' in script_path
- codex_sessions_dir = Path.home() / '.codex' / 'sessions'
- if is_codex_variant and codex_sessions_dir.exists() and not claude_path.exists():
- return None, (
- "[planning-with-files] Session catchup skipped: Codex stores sessions "
- "in ~/.codex/sessions and native Codex parsing is not implemented yet."
- )
-
- return claude_path, None
-
-
-def get_sessions_sorted(project_dir: Path) -> List[Path]:
- """Get all session files sorted by modification time (newest first)."""
- sessions = list(project_dir.glob('*.jsonl'))
-```
-
-This function is important because it defines how Planning with Files Tutorial: Persistent Markdown Workflow Memory for AI Coding Agents implements the patterns covered in this chapter.
-
-### `.codex/skills/planning-with-files/scripts/session-catchup.py`
-
-The `get_sessions_sorted` function in [`.codex/skills/planning-with-files/scripts/session-catchup.py`](https://github.com/OthmanAdi/planning-with-files/blob/HEAD/.codex/skills/planning-with-files/scripts/session-catchup.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def get_sessions_sorted(project_dir: Path) -> List[Path]:
- """Get all session files sorted by modification time (newest first)."""
- sessions = list(project_dir.glob('*.jsonl'))
- main_sessions = [s for s in sessions if not s.name.startswith('agent-')]
- return sorted(main_sessions, key=lambda p: p.stat().st_mtime, reverse=True)
-
-
-def parse_session_messages(session_file: Path) -> List[Dict]:
- """Parse all messages from a session file, preserving order."""
- messages = []
- with open(session_file, 'r', encoding='utf-8', errors='replace') as f:
- for line_num, line in enumerate(f):
- try:
- data = json.loads(line)
- data['_line_num'] = line_num
- messages.append(data)
- except json.JSONDecodeError:
- pass
- return messages
-
-
-def find_last_planning_update(messages: List[Dict]) -> Tuple[int, Optional[str]]:
+def scan_for_planning_update(session_file: Path) -> Tuple[int, Optional[str]]:
"""
- Find the last time a planning file was written/edited.
- Returns (line_number, filename) or (-1, None) if not found.
+ Quickly scan a session file for planning file updates.
+ Returns (line_number, filename) of last update, or (-1, None) if none found.
"""
last_update_line = -1
last_update_file = None
- for msg in messages:
+ try:
+ with open(session_file, 'r') as f:
+ for line_num, line in enumerate(f):
+ if '"Write"' not in line and '"Edit"' not in line:
+ continue
+
+ try:
+ data = json.loads(line)
+ if data.get('type') != 'assistant':
+ continue
+
+ content = data.get('message', {}).get('content', [])
+ if not isinstance(content, list):
+ continue
+
+ for item in content:
+ if item.get('type') != 'tool_use':
+ continue
+ tool_name = item.get('name', '')
+ if tool_name not in ('Write', 'Edit'):
+ continue
+
```
This function is important because it defines how Planning with Files Tutorial: Persistent Markdown Workflow Memory for AI Coding Agents implements the patterns covered in this chapter.
-### `.codex/skills/planning-with-files/scripts/session-catchup.py`
+### `scripts/session-catchup.py`
-The `parse_session_messages` function in [`.codex/skills/planning-with-files/scripts/session-catchup.py`](https://github.com/OthmanAdi/planning-with-files/blob/HEAD/.codex/skills/planning-with-files/scripts/session-catchup.py) handles a key part of this chapter's functionality:
+The `extract_messages_from_session` function in [`scripts/session-catchup.py`](https://github.com/OthmanAdi/planning-with-files/blob/HEAD/scripts/session-catchup.py) handles a key part of this chapter's functionality:
```py
-def parse_session_messages(session_file: Path) -> List[Dict]:
- """Parse all messages from a session file, preserving order."""
- messages = []
- with open(session_file, 'r', encoding='utf-8', errors='replace') as f:
- for line_num, line in enumerate(f):
- try:
- data = json.loads(line)
- data['_line_num'] = line_num
- messages.append(data)
- except json.JSONDecodeError:
- pass
- return messages
-
-
-def find_last_planning_update(messages: List[Dict]) -> Tuple[int, Optional[str]]:
+def extract_messages_from_session(session_file: Path, after_line: int = -1) -> List[Dict]:
"""
- Find the last time a planning file was written/edited.
- Returns (line_number, filename) or (-1, None) if not found.
+ Extract conversation messages from a session file.
+ If after_line >= 0, only extract messages after that line.
+ If after_line < 0, extract all messages.
"""
- last_update_line = -1
- last_update_file = None
-
- for msg in messages:
- msg_type = msg.get('type')
-
- if msg_type == 'assistant':
- content = msg.get('message', {}).get('content', [])
- if isinstance(content, list):
- for item in content:
- if item.get('type') == 'tool_use':
+ result = []
+
+ try:
+ with open(session_file, 'r') as f:
+ for line_num, line in enumerate(f):
+ if after_line >= 0 and line_num <= after_line:
+ continue
+
+ try:
+ msg = json.loads(line)
+ except json.JSONDecodeError:
+ continue
+
+ msg_type = msg.get('type')
+ is_meta = msg.get('isMeta', False)
+
+ if msg_type == 'user' and not is_meta:
+ content = msg.get('message', {}).get('content', '')
+ if isinstance(content, list):
+ for item in content:
+ if isinstance(item, dict) and item.get('type') == 'text':
+ content = item.get('text', '')
+ break
+ else:
```
This function is important because it defines how Planning with Files Tutorial: Persistent Markdown Workflow Memory for AI Coding Agents implements the patterns covered in this chapter.
-### `.codex/skills/planning-with-files/scripts/session-catchup.py`
+### `scripts/session-catchup.py`
-The `find_last_planning_update` function in [`.codex/skills/planning-with-files/scripts/session-catchup.py`](https://github.com/OthmanAdi/planning-with-files/blob/HEAD/.codex/skills/planning-with-files/scripts/session-catchup.py) handles a key part of this chapter's functionality:
+The `main` function in [`scripts/session-catchup.py`](https://github.com/OthmanAdi/planning-with-files/blob/HEAD/scripts/session-catchup.py) handles a key part of this chapter's functionality:
```py
+ """Get all session files sorted by modification time (newest first)."""
+ sessions = list(project_dir.glob('*.jsonl'))
+ main_sessions = [s for s in sessions if not s.name.startswith('agent-')]
+ return sorted(main_sessions, key=lambda p: p.stat().st_mtime, reverse=True)
-def find_last_planning_update(messages: List[Dict]) -> Tuple[int, Optional[str]]:
+def get_sessions_sorted_opencode(storage_dir: Path) -> List[Path]:
"""
- Find the last time a planning file was written/edited.
- Returns (line_number, filename) or (-1, None) if not found.
+ Get all OpenCode session files sorted by modification time.
+ OpenCode stores sessions at: storage/session/{projectHash}/{sessionID}.json
"""
- last_update_line = -1
- last_update_file = None
-
- for msg in messages:
- msg_type = msg.get('type')
-
- if msg_type == 'assistant':
- content = msg.get('message', {}).get('content', [])
- if isinstance(content, list):
- for item in content:
- if item.get('type') == 'tool_use':
- tool_name = item.get('name', '')
- tool_input = item.get('input', {})
-
- if tool_name in ('Write', 'Edit'):
- file_path = tool_input.get('file_path', '')
- for pf in PLANNING_FILES:
- if file_path.endswith(pf):
- last_update_line = msg['_line_num']
- last_update_file = pf
-
- return last_update_line, last_update_file
-
-
-def extract_messages_after(messages: List[Dict], after_line: int) -> List[Dict]:
+ session_dir = storage_dir / 'session'
+ if not session_dir.exists():
+ return []
+
+ sessions = []
+ for project_hash_dir in session_dir.iterdir():
+ if project_hash_dir.is_dir():
+ for session_file in project_hash_dir.glob('*.json'):
+ sessions.append(session_file)
+
+ return sorted(sessions, key=lambda p: p.stat().st_mtime, reverse=True)
+
+
+def get_session_first_timestamp(session_file: Path) -> Optional[str]:
+ """Get the timestamp of the first message in a session."""
+ try:
+ with open(session_file, 'r') as f:
+ for line in f:
+ try:
+ data = json.loads(line)
+ ts = data.get('timestamp')
```
This function is important because it defines how Planning with Files Tutorial: Persistent Markdown Workflow Memory for AI Coding Agents implements the patterns covered in this chapter.
@@ -216,13 +173,9 @@ This function is important because it defines how Planning with Files Tutorial:
```mermaid
flowchart TD
- A[get_project_dir]
- B[get_sessions_sorted]
- C[parse_session_messages]
- D[find_last_planning_update]
- E[extract_messages_after]
+ A[scan_for_planning_update]
+ B[extract_messages_from_session]
+ C[main]
A --> B
B --> C
- C --> D
- D --> E
```
diff --git a/tutorials/planning-with-files-tutorial/04-commands-hooks-and-workflow-orchestration.md b/tutorials/planning-with-files-tutorial/04-commands-hooks-and-workflow-orchestration.md
index 00c05104..2c2eb6c2 100644
--- a/tutorials/planning-with-files-tutorial/04-commands-hooks-and-workflow-orchestration.md
+++ b/tutorials/planning-with-files-tutorial/04-commands-hooks-and-workflow-orchestration.md
@@ -44,170 +44,127 @@ You now know how orchestration components enforce workflow consistency.
Next: [Chapter 5: Templates, Scripts, and Session Recovery](05-templates-scripts-and-session-recovery.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `skills/planning-with-files/scripts/session-catchup.py`
+### `examples/boxlite/quickstart.py`
-The `get_project_dir` function in [`skills/planning-with-files/scripts/session-catchup.py`](https://github.com/OthmanAdi/planning-with-files/blob/HEAD/skills/planning-with-files/scripts/session-catchup.py) handles a key part of this chapter's functionality:
+The `load_skill` function in [`examples/boxlite/quickstart.py`](https://github.com/OthmanAdi/planning-with-files/blob/HEAD/examples/boxlite/quickstart.py) handles a key part of this chapter's functionality:
```py
-def get_project_dir(project_path: str) -> Tuple[Optional[Path], Optional[str]]:
- """Resolve session storage path for the current runtime variant."""
- normalized = normalize_path(project_path)
-
- # Claude Code's sanitization: replace path separators and : with -
- sanitized = normalized.replace('\\', '-').replace('/', '-').replace(':', '-')
- sanitized = sanitized.replace('_', '-')
- # Strip leading dash if present (Unix absolute paths start with /)
- if sanitized.startswith('-'):
- sanitized = sanitized[1:]
-
- claude_path = Path.home() / '.claude' / 'projects' / sanitized
-
- # Codex stores sessions in ~/.codex/sessions with a different format.
- # Avoid silently scanning Claude paths when running from Codex skill folder.
- script_path = Path(__file__).as_posix().lower()
- is_codex_variant = '/.codex/' in script_path
- codex_sessions_dir = Path.home() / '.codex' / 'sessions'
- if is_codex_variant and codex_sessions_dir.exists() and not claude_path.exists():
- return None, (
- "[planning-with-files] Session catchup skipped: Codex stores sessions "
- "in ~/.codex/sessions and native Codex parsing is not implemented yet."
+def load_skill() -> Skill:
+ """
+ Build a ClaudeBox Skill from the planning-with-files SKILL.md.
+
+ Reads the SKILL.md from your local Claude Code skills directory.
+ If not installed locally, falls back to fetching from the repo.
+ """
+ skill_base = Path.home() / ".claude" / "skills" / "planning-with-files"
+ skill_md_path = skill_base / "SKILL.md"
+ check_complete_path = skill_base / "scripts" / "check-complete.sh"
+
+ if not skill_md_path.exists():
+ raise FileNotFoundError(
+ "planning-with-files is not installed locally.\n"
+ "Install it first:\n"
+ " /plugin marketplace add OthmanAdi/planning-with-files\n"
+ " /plugin install planning-with-files@planning-with-files"
)
- return claude_path, None
+ files = {
+ "/root/.claude/skills/planning-with-files/SKILL.md": skill_md_path.read_text(),
+ }
+ # Include the stop hook script if available
+ if check_complete_path.exists():
+ files["/root/.claude/skills/planning-with-files/scripts/check-complete.sh"] = (
+ check_complete_path.read_text()
+ )
-def get_sessions_sorted(project_dir: Path) -> List[Path]:
- """Get all session files sorted by modification time (newest first)."""
- sessions = list(project_dir.glob('*.jsonl'))
+ return Skill(
```
This function is important because it defines how Planning with Files Tutorial: Persistent Markdown Workflow Memory for AI Coding Agents implements the patterns covered in this chapter.
-### `skills/planning-with-files/scripts/session-catchup.py`
+### `examples/boxlite/quickstart.py`
-The `get_sessions_sorted` function in [`skills/planning-with-files/scripts/session-catchup.py`](https://github.com/OthmanAdi/planning-with-files/blob/HEAD/skills/planning-with-files/scripts/session-catchup.py) handles a key part of this chapter's functionality:
+The `main` function in [`examples/boxlite/quickstart.py`](https://github.com/OthmanAdi/planning-with-files/blob/HEAD/examples/boxlite/quickstart.py) handles a key part of this chapter's functionality:
```py
-def get_sessions_sorted(project_dir: Path) -> List[Path]:
- """Get all session files sorted by modification time (newest first)."""
- sessions = list(project_dir.glob('*.jsonl'))
- main_sessions = [s for s in sessions if not s.name.startswith('agent-')]
- return sorted(main_sessions, key=lambda p: p.stat().st_mtime, reverse=True)
-
-
-def parse_session_messages(session_file: Path) -> List[Dict]:
- """Parse all messages from a session file, preserving order."""
- messages = []
- with open(session_file, 'r', encoding='utf-8', errors='replace') as f:
- for line_num, line in enumerate(f):
- try:
- data = json.loads(line)
- data['_line_num'] = line_num
- messages.append(data)
- except json.JSONDecodeError:
- pass
- return messages
+async def main():
+ skill = load_skill()
+ print("Starting BoxLite VM with planning-with-files skill...")
-def find_last_planning_update(messages: List[Dict]) -> Tuple[int, Optional[str]]:
- """
- Find the last time a planning file was written/edited.
- Returns (line_number, filename) or (-1, None) if not found.
- """
- last_update_line = -1
- last_update_file = None
-
- for msg in messages:
-```
-
-This function is important because it defines how Planning with Files Tutorial: Persistent Markdown Workflow Memory for AI Coding Agents implements the patterns covered in this chapter.
-
-### `skills/planning-with-files/scripts/session-catchup.py`
-
-The `parse_session_messages` function in [`skills/planning-with-files/scripts/session-catchup.py`](https://github.com/OthmanAdi/planning-with-files/blob/HEAD/skills/planning-with-files/scripts/session-catchup.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def parse_session_messages(session_file: Path) -> List[Dict]:
- """Parse all messages from a session file, preserving order."""
- messages = []
- with open(session_file, 'r', encoding='utf-8', errors='replace') as f:
- for line_num, line in enumerate(f):
- try:
- data = json.loads(line)
- data['_line_num'] = line_num
- messages.append(data)
- except json.JSONDecodeError:
- pass
- return messages
+ async with ClaudeBox(
+ session_id="planning-demo",
+ skills=[skill],
+ ) as box:
+ print("VM running. Invoking planning session...\n")
+ result = await box.code(
+ "/planning-with-files:plan\n\n"
+ "Task: Build a REST API endpoint for user authentication with JWT tokens. "
+ "Plan the implementation phases, identify the key files to create, "
+ "and list the dependencies needed."
+ )
-def find_last_planning_update(messages: List[Dict]) -> Tuple[int, Optional[str]]:
- """
- Find the last time a planning file was written/edited.
- Returns (line_number, filename) or (-1, None) if not found.
- """
- last_update_line = -1
- last_update_file = None
+ print("=== Claude Code Output ===")
+ print(result.response)
+ print("==========================")
- for msg in messages:
- msg_type = msg.get('type')
+ # Show what planning files were created inside the VM
+ files_result = await box.code(
+ "ls -la task_plan.md findings.md progress.md 2>/dev/null && "
+ "echo '---' && head -20 task_plan.md 2>/dev/null"
+ )
+ print("\n=== Planning Files in VM ===")
+ print(files_result.response)
- if msg_type == 'assistant':
- content = msg.get('message', {}).get('content', [])
- if isinstance(content, list):
- for item in content:
- if item.get('type') == 'tool_use':
```
This function is important because it defines how Planning with Files Tutorial: Persistent Markdown Workflow Memory for AI Coding Agents implements the patterns covered in this chapter.
-### `skills/planning-with-files/scripts/session-catchup.py`
+### `examples/boxlite/quickstart.py`
-The `find_last_planning_update` function in [`skills/planning-with-files/scripts/session-catchup.py`](https://github.com/OthmanAdi/planning-with-files/blob/HEAD/skills/planning-with-files/scripts/session-catchup.py) handles a key part of this chapter's functionality:
+The `persistent_session_example` function in [`examples/boxlite/quickstart.py`](https://github.com/OthmanAdi/planning-with-files/blob/HEAD/examples/boxlite/quickstart.py) handles a key part of this chapter's functionality:
```py
-def find_last_planning_update(messages: List[Dict]) -> Tuple[int, Optional[str]]:
+async def persistent_session_example():
"""
- Find the last time a planning file was written/edited.
- Returns (line_number, filename) or (-1, None) if not found.
+ Example of a multi-session workflow.
+ Session 1 creates the plan. Session 2 continues from it.
"""
- last_update_line = -1
- last_update_file = None
+ skill = load_skill()
- for msg in messages:
- msg_type = msg.get('type')
+ # Session 1
+ async with ClaudeBox(session_id="multi-session-demo", skills=[skill]) as box:
+ await box.code(
+ "/planning-with-files:plan\n\n"
+ "Task: Refactor the user service to support multi-tenancy."
+ )
+ print("Session 1 complete. Plan created inside VM.")
- if msg_type == 'assistant':
- content = msg.get('message', {}).get('content', [])
- if isinstance(content, list):
- for item in content:
- if item.get('type') == 'tool_use':
- tool_name = item.get('name', '')
- tool_input = item.get('input', {})
+ # Session 2 — same workspace, plan files intact
+ async with ClaudeBox.reconnect("multi-session-demo") as box:
+ result = await box.code(
+ "Read task_plan.md and continue with the next incomplete phase."
+ )
+ print("Session 2:", result.response[:200])
- if tool_name in ('Write', 'Edit'):
- file_path = tool_input.get('file_path', '')
- for pf in PLANNING_FILES:
- if file_path.endswith(pf):
- last_update_line = msg['_line_num']
- last_update_file = pf
+ # Clean up
+ await ClaudeBox.cleanup_session("multi-session-demo", remove_workspace=True)
+ print("Workspace cleaned up.")
- return last_update_line, last_update_file
+if __name__ == "__main__":
+ asyncio.run(main())
-def extract_messages_after(messages: List[Dict], after_line: int) -> List[Dict]:
```
This function is important because it defines how Planning with Files Tutorial: Persistent Markdown Workflow Memory for AI Coding Agents implements the patterns covered in this chapter.
@@ -217,13 +174,9 @@ This function is important because it defines how Planning with Files Tutorial:
```mermaid
flowchart TD
- A[get_project_dir]
- B[get_sessions_sorted]
- C[parse_session_messages]
- D[find_last_planning_update]
- E[extract_messages_after]
+ A[load_skill]
+ B[main]
+ C[persistent_session_example]
A --> B
B --> C
- C --> D
- D --> E
```
diff --git a/tutorials/planning-with-files-tutorial/05-templates-scripts-and-session-recovery.md b/tutorials/planning-with-files-tutorial/05-templates-scripts-and-session-recovery.md
index b8042528..99e09018 100644
--- a/tutorials/planning-with-files-tutorial/05-templates-scripts-and-session-recovery.md
+++ b/tutorials/planning-with-files-tutorial/05-templates-scripts-and-session-recovery.md
@@ -42,107 +42,67 @@ You now have a resilience toolkit for context resets and interrupted sessions.
Next: [Chapter 6: Multi-IDE Adaptation (Codex, Gemini, OpenCode, Cursor)](06-multi-ide-adaptation-codex-gemini-opencode-cursor.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `.codebuddy/skills/planning-with-files/scripts/session-catchup.py`
+### `skills/planning-with-files-zht/scripts/session-catchup.py`
-The `find_last_planning_update` function in [`.codebuddy/skills/planning-with-files/scripts/session-catchup.py`](https://github.com/OthmanAdi/planning-with-files/blob/HEAD/.codebuddy/skills/planning-with-files/scripts/session-catchup.py) handles a key part of this chapter's functionality:
+The `get_project_dir` function in [`skills/planning-with-files-zht/scripts/session-catchup.py`](https://github.com/OthmanAdi/planning-with-files/blob/HEAD/skills/planning-with-files-zht/scripts/session-catchup.py) handles a key part of this chapter's functionality:
```py
-def find_last_planning_update(messages: List[Dict]) -> Tuple[int, Optional[str]]:
- """
- Find the last time a planning file was written/edited.
- Returns (line_number, filename) or (-1, None) if not found.
- """
- last_update_line = -1
- last_update_file = None
+def get_project_dir(project_path: str) -> Tuple[Optional[Path], Optional[str]]:
+ """解析目前執行環境的會話儲存路徑。"""
+ sanitized = project_path.replace('/', '-')
+ if not sanitized.startswith('-'):
+ sanitized = '-' + sanitized
+ sanitized = sanitized.replace('_', '-')
- for msg in messages:
- msg_type = msg.get('type')
+ claude_path = Path.home() / '.claude' / 'projects' / sanitized
- if msg_type == 'assistant':
- content = msg.get('message', {}).get('content', [])
- if isinstance(content, list):
- for item in content:
- if item.get('type') == 'tool_use':
- tool_name = item.get('name', '')
- tool_input = item.get('input', {})
+ # Codex 將會話存放在 ~/.codex/sessions，格式不同。
+ # 從 Codex 技能資料夾執行時，避免靜默掃描 Claude 路徑。
+ script_path = Path(__file__).as_posix().lower()
+ is_codex_variant = '/.codex/' in script_path
+ codex_sessions_dir = Path.home() / '.codex' / 'sessions'
+ if is_codex_variant and codex_sessions_dir.exists() and not claude_path.exists():
+ return None, (
+ "[planning-with-files] 會話恢復已跳過：Codex 將會話存放在 "
+ "~/.codex/sessions，原生 Codex 解析尚未實作。"
+ )
- if tool_name in ('Write', 'Edit'):
- file_path = tool_input.get('file_path', '')
- for pf in PLANNING_FILES:
- if file_path.endswith(pf):
- last_update_line = msg['_line_num']
- last_update_file = pf
+ return claude_path, None
- return last_update_line, last_update_file
+
+def get_sessions_sorted(project_dir: Path) -> List[Path]:
+ """取得所有會話檔案，按修改時間排序（最新優先）。"""
+ sessions = list(project_dir.glob('*.jsonl'))
+ main_sessions = [s for s in sessions if not s.name.startswith('agent-')]
+ return sorted(main_sessions, key=lambda p: p.stat().st_mtime, reverse=True)
-def extract_messages_after(messages: List[Dict], after_line: int) -> List[Dict]:
```
This function is important because it defines how Planning with Files Tutorial: Persistent Markdown Workflow Memory for AI Coding Agents implements the patterns covered in this chapter.
-### `.codebuddy/skills/planning-with-files/scripts/session-catchup.py`
+### `skills/planning-with-files-zht/scripts/session-catchup.py`
-The `extract_messages_after` function in [`.codebuddy/skills/planning-with-files/scripts/session-catchup.py`](https://github.com/OthmanAdi/planning-with-files/blob/HEAD/.codebuddy/skills/planning-with-files/scripts/session-catchup.py) handles a key part of this chapter's functionality:
+The `get_sessions_sorted` function in [`skills/planning-with-files-zht/scripts/session-catchup.py`](https://github.com/OthmanAdi/planning-with-files/blob/HEAD/skills/planning-with-files-zht/scripts/session-catchup.py) handles a key part of this chapter's functionality:
```py
-def extract_messages_after(messages: List[Dict], after_line: int) -> List[Dict]:
- """Extract conversation messages after a certain line number."""
- result = []
- for msg in messages:
- if msg['_line_num'] <= after_line:
- continue
-
- msg_type = msg.get('type')
- is_meta = msg.get('isMeta', False)
-
- if msg_type == 'user' and not is_meta:
- content = msg.get('message', {}).get('content', '')
- if isinstance(content, list):
- for item in content:
- if isinstance(item, dict) and item.get('type') == 'text':
- content = item.get('text', '')
- break
- else:
- content = ''
-
- if content and isinstance(content, str):
- if content.startswith(('<local-command', '<command-', '<task-notification')):
- continue
- if len(content) > 20:
- result.append({'role': 'user', 'content': content, 'line': msg['_line_num']})
-
- elif msg_type == 'assistant':
- msg_content = msg.get('message', {}).get('content', '')
- text_content = ''
- tool_uses = []
-```
-
-This function is important because it defines how Planning with Files Tutorial: Persistent Markdown Workflow Memory for AI Coding Agents implements the patterns covered in this chapter.
-
-### `.codebuddy/skills/planning-with-files/scripts/session-catchup.py`
-
-The `main` function in [`.codebuddy/skills/planning-with-files/scripts/session-catchup.py`](https://github.com/OthmanAdi/planning-with-files/blob/HEAD/.codebuddy/skills/planning-with-files/scripts/session-catchup.py) handles a key part of this chapter's functionality:
-
-```py
- """Get all session files sorted by modification time (newest first)."""
+def get_sessions_sorted(project_dir: Path) -> List[Path]:
+ """取得所有會話檔案，按修改時間排序（最新優先）。"""
sessions = list(project_dir.glob('*.jsonl'))
main_sessions = [s for s in sessions if not s.name.startswith('agent-')]
return sorted(main_sessions, key=lambda p: p.stat().st_mtime, reverse=True)
def parse_session_messages(session_file: Path) -> List[Dict]:
- """Parse all messages from a session file, preserving order."""
+ """解析會話檔案中的所有訊息，保持順序。"""
messages = []
- with open(session_file, 'r', encoding='utf-8', errors='replace') as f:
+ with open(session_file, 'r') as f:
for line_num, line in enumerate(f):
try:
data = json.loads(line)
@@ -155,57 +115,54 @@ def parse_session_messages(session_file: Path) -> List[Dict]:
def find_last_planning_update(messages: List[Dict]) -> Tuple[int, Optional[str]]:
"""
- Find the last time a planning file was written/edited.
- Returns (line_number, filename) or (-1, None) if not found.
+ 找出最後一次寫入/編輯規劃檔案的時間點。
+ 回傳 (行號, 檔案名稱) 或 (-1, None)（如果未找到）。
"""
last_update_line = -1
last_update_file = None
for msg in messages:
- msg_type = msg.get('type')
-
- if msg_type == 'assistant':
```
This function is important because it defines how Planning with Files Tutorial: Persistent Markdown Workflow Memory for AI Coding Agents implements the patterns covered in this chapter.
-### `skills/planning-with-files-zh/scripts/session-catchup.py`
+### `skills/planning-with-files-zht/scripts/session-catchup.py`
-The `get_project_dir` function in [`skills/planning-with-files-zh/scripts/session-catchup.py`](https://github.com/OthmanAdi/planning-with-files/blob/HEAD/skills/planning-with-files-zh/scripts/session-catchup.py) handles a key part of this chapter's functionality:
+The `parse_session_messages` function in [`skills/planning-with-files-zht/scripts/session-catchup.py`](https://github.com/OthmanAdi/planning-with-files/blob/HEAD/skills/planning-with-files-zht/scripts/session-catchup.py) handles a key part of this chapter's functionality:
```py
-def get_project_dir(project_path: str) -> Tuple[Optional[Path], Optional[str]]:
- """Resolve session storage path for the current runtime variant."""
- sanitized = project_path.replace('/', '-')
- if not sanitized.startswith('-'):
- sanitized = '-' + sanitized
- sanitized = sanitized.replace('_', '-')
-
- claude_path = Path.home() / '.claude' / 'projects' / sanitized
-
- # Codex stores sessions in ~/.codex/sessions with a different format.
- # Avoid silently scanning Claude paths when running from Codex skill folder.
- script_path = Path(__file__).as_posix().lower()
- is_codex_variant = '/.codex/' in script_path
- codex_sessions_dir = Path.home() / '.codex' / 'sessions'
- if is_codex_variant and codex_sessions_dir.exists() and not claude_path.exists():
- return None, (
- "[planning-with-files] Session catchup skipped: Codex stores sessions "
- "in ~/.codex/sessions and native Codex parsing is not implemented yet."
- )
-
- return claude_path, None
+def parse_session_messages(session_file: Path) -> List[Dict]:
+ """解析會話檔案中的所有訊息，保持順序。"""
+ messages = []
+ with open(session_file, 'r') as f:
+ for line_num, line in enumerate(f):
+ try:
+ data = json.loads(line)
+ data['_line_num'] = line_num
+ messages.append(data)
+ except json.JSONDecodeError:
+ pass
+ return messages
-def get_sessions_sorted(project_dir: Path) -> List[Path]:
- """Get all session files sorted by modification time (newest first)."""
- sessions = list(project_dir.glob('*.jsonl'))
- main_sessions = [s for s in sessions if not s.name.startswith('agent-')]
- return sorted(main_sessions, key=lambda p: p.stat().st_mtime, reverse=True)
+def find_last_planning_update(messages: List[Dict]) -> Tuple[int, Optional[str]]:
+ """
+ 找出最後一次寫入/編輯規劃檔案的時間點。
+ 回傳 (行號, 檔案名稱) 或 (-1, None)（如果未找到）。
+ """
+ last_update_line = -1
+ last_update_file = None
+ for msg in messages:
+ msg_type = msg.get('type')
+ if msg_type == 'assistant':
+ content = msg.get('message', {}).get('content', [])
+ if isinstance(content, list):
+ for item in content:
+ if item.get('type') == 'tool_use':
```
This function is important because it defines how Planning with Files Tutorial: Persistent Markdown Workflow Memory for AI Coding Agents implements the patterns covered in this chapter.
@@ -215,13 +172,9 @@ This function is important because it defines how Planning with Files Tutorial:
```mermaid
flowchart TD
- A[find_last_planning_update]
- B[extract_messages_after]
- C[main]
- D[get_project_dir]
- E[get_sessions_sorted]
+ A[get_project_dir]
+ B[get_sessions_sorted]
+ C[parse_session_messages]
A --> B
B --> C
- C --> D
- D --> E
```
diff --git a/tutorials/planning-with-files-tutorial/06-multi-ide-adaptation-codex-gemini-opencode-cursor.md b/tutorials/planning-with-files-tutorial/06-multi-ide-adaptation-codex-gemini-opencode-cursor.md
index 838a6cc4..d04cf0e7 100644
--- a/tutorials/planning-with-files-tutorial/06-multi-ide-adaptation-codex-gemini-opencode-cursor.md
+++ b/tutorials/planning-with-files-tutorial/06-multi-ide-adaptation-codex-gemini-opencode-cursor.md
@@ -39,103 +39,105 @@ You now have a practical strategy for multi-IDE workflow consistency.
Next: [Chapter 7: Troubleshooting, Anti-Patterns, and Safety Checks](07-troubleshooting-anti-patterns-and-safety-checks.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `.continue/skills/planning-with-files/scripts/session-catchup.py`
+### `skills/planning-with-files-zht/scripts/session-catchup.py`
-The `get_project_dir` function in [`.continue/skills/planning-with-files/scripts/session-catchup.py`](https://github.com/OthmanAdi/planning-with-files/blob/HEAD/.continue/skills/planning-with-files/scripts/session-catchup.py) handles a key part of this chapter's functionality:
+The `find_last_planning_update` function in [`skills/planning-with-files-zht/scripts/session-catchup.py`](https://github.com/OthmanAdi/planning-with-files/blob/HEAD/skills/planning-with-files-zht/scripts/session-catchup.py) handles a key part of this chapter's functionality:
```py
-def get_project_dir(project_path: str) -> Tuple[Optional[Path], Optional[str]]:
- """Resolve session storage path for the current runtime variant."""
- normalized = normalize_path(project_path)
+def find_last_planning_update(messages: List[Dict]) -> Tuple[int, Optional[str]]:
+ """
+ 找出最後一次寫入/編輯規劃檔案的時間點。
+ 回傳 (行號, 檔案名稱) 或 (-1, None)（如果未找到）。
+ """
+ last_update_line = -1
+ last_update_file = None
- # Claude Code's sanitization: replace path separators and : with -
- sanitized = normalized.replace('\\', '-').replace('/', '-').replace(':', '-')
- sanitized = sanitized.replace('_', '-')
- # Strip leading dash if present (Unix absolute paths start with /)
- if sanitized.startswith('-'):
- sanitized = sanitized[1:]
+ for msg in messages:
+ msg_type = msg.get('type')
- claude_path = Path.home() / '.claude' / 'projects' / sanitized
+ if msg_type == 'assistant':
+ content = msg.get('message', {}).get('content', [])
+ if isinstance(content, list):
+ for item in content:
+ if item.get('type') == 'tool_use':
+ tool_name = item.get('name', '')
+ tool_input = item.get('input', {})
- # Codex stores sessions in ~/.codex/sessions with a different format.
- # Avoid silently scanning Claude paths when running from Codex skill folder.
- script_path = Path(__file__).as_posix().lower()
- is_codex_variant = '/.codex/' in script_path
- codex_sessions_dir = Path.home() / '.codex' / 'sessions'
- if is_codex_variant and codex_sessions_dir.exists() and not claude_path.exists():
- return None, (
- "[planning-with-files] Session catchup skipped: Codex stores sessions "
- "in ~/.codex/sessions and native Codex parsing is not implemented yet."
- )
+ if tool_name in ('Write', 'Edit'):
+ file_path = tool_input.get('file_path', '')
+ for pf in PLANNING_FILES:
+ if file_path.endswith(pf):
+ last_update_line = msg['_line_num']
+ last_update_file = pf
- return claude_path, None
+ return last_update_line, last_update_file
-def get_sessions_sorted(project_dir: Path) -> List[Path]:
- """Get all session files sorted by modification time (newest first)."""
- sessions = list(project_dir.glob('*.jsonl'))
+def extract_messages_after(messages: List[Dict], after_line: int) -> List[Dict]:
```
This function is important because it defines how Planning with Files Tutorial: Persistent Markdown Workflow Memory for AI Coding Agents implements the patterns covered in this chapter.
-### `.continue/skills/planning-with-files/scripts/session-catchup.py`
+### `skills/planning-with-files-zht/scripts/session-catchup.py`
-The `get_sessions_sorted` function in [`.continue/skills/planning-with-files/scripts/session-catchup.py`](https://github.com/OthmanAdi/planning-with-files/blob/HEAD/.continue/skills/planning-with-files/scripts/session-catchup.py) handles a key part of this chapter's functionality:
+The `extract_messages_after` function in [`skills/planning-with-files-zht/scripts/session-catchup.py`](https://github.com/OthmanAdi/planning-with-files/blob/HEAD/skills/planning-with-files-zht/scripts/session-catchup.py) handles a key part of this chapter's functionality:
```py
-def get_sessions_sorted(project_dir: Path) -> List[Path]:
- """Get all session files sorted by modification time (newest first)."""
- sessions = list(project_dir.glob('*.jsonl'))
- main_sessions = [s for s in sessions if not s.name.startswith('agent-')]
- return sorted(main_sessions, key=lambda p: p.stat().st_mtime, reverse=True)
-
-
-def parse_session_messages(session_file: Path) -> List[Dict]:
- """Parse all messages from a session file, preserving order."""
- messages = []
- with open(session_file, 'r', encoding='utf-8', errors='replace') as f:
- for line_num, line in enumerate(f):
- try:
- data = json.loads(line)
- data['_line_num'] = line_num
- messages.append(data)
- except json.JSONDecodeError:
- pass
- return messages
-
+def extract_messages_after(messages: List[Dict], after_line: int) -> List[Dict]:
+ """擷取特定行號之後的對話訊息。"""
+ result = []
+ for msg in messages:
+ if msg['_line_num'] <= after_line:
+ continue
-def find_last_planning_update(messages: List[Dict]) -> Tuple[int, Optional[str]]:
- """
- Find the last time a planning file was written/edited.
- Returns (line_number, filename) or (-1, None) if not found.
- """
- last_update_line = -1
- last_update_file = None
+ msg_type = msg.get('type')
+ is_meta = msg.get('isMeta', False)
- for msg in messages:
+ if msg_type == 'user' and not is_meta:
+ content = msg.get('message', {}).get('content', '')
+ if isinstance(content, list):
+ for item in content:
+ if isinstance(item, dict) and item.get('type') == 'text':
+ content = item.get('text', '')
+ break
+ else:
+ content = ''
+
+ if content and isinstance(content, str):
+ if content.startswith(('<local-command', '<command-', '<task-notification')):
+ continue
+ if len(content) > 20:
+ result.append({'role': 'user', 'content': content, 'line': msg['_line_num']})
+
+ elif msg_type == 'assistant':
+ msg_content = msg.get('message', {}).get('content', '')
+ text_content = ''
+ tool_uses = []
```
This function is important because it defines how Planning with Files Tutorial: Persistent Markdown Workflow Memory for AI Coding Agents implements the patterns covered in this chapter.
-### `.continue/skills/planning-with-files/scripts/session-catchup.py`
+### `skills/planning-with-files-zht/scripts/session-catchup.py`
-The `parse_session_messages` function in [`.continue/skills/planning-with-files/scripts/session-catchup.py`](https://github.com/OthmanAdi/planning-with-files/blob/HEAD/.continue/skills/planning-with-files/scripts/session-catchup.py) handles a key part of this chapter's functionality:
+The `main` function in [`skills/planning-with-files-zht/scripts/session-catchup.py`](https://github.com/OthmanAdi/planning-with-files/blob/HEAD/skills/planning-with-files-zht/scripts/session-catchup.py) handles a key part of this chapter's functionality:
```py
+ """取得所有會話檔案，按修改時間排序（最新優先）。"""
+ sessions = list(project_dir.glob('*.jsonl'))
+ main_sessions = [s for s in sessions if not s.name.startswith('agent-')]
+ return sorted(main_sessions, key=lambda p: p.stat().st_mtime, reverse=True)
def parse_session_messages(session_file: Path) -> List[Dict]:
- """Parse all messages from a session file, preserving order."""
+ """解析會話檔案中的所有訊息，保持順序。"""
messages = []
- with open(session_file, 'r', encoding='utf-8', errors='replace') as f:
+ with open(session_file, 'r') as f:
for line_num, line in enumerate(f):
try:
data = json.loads(line)
@@ -148,8 +150,8 @@ def parse_session_messages(session_file: Path) -> List[Dict]:
def find_last_planning_update(messages: List[Dict]) -> Tuple[int, Optional[str]]:
"""
- Find the last time a planning file was written/edited.
- Returns (line_number, filename) or (-1, None) if not found.
+ 找出最後一次寫入/編輯規劃檔案的時間點。
+ 回傳 (行號, 檔案名稱) 或 (-1, None)（如果未找到）。
"""
last_update_line = -1
last_update_file = None
@@ -158,51 +160,6 @@ def find_last_planning_update(messages: List[Dict]) -> Tuple[int, Optional[str]]
msg_type = msg.get('type')
if msg_type == 'assistant':
- content = msg.get('message', {}).get('content', [])
- if isinstance(content, list):
- for item in content:
- if item.get('type') == 'tool_use':
-```
-
-This function is important because it defines how Planning with Files Tutorial: Persistent Markdown Workflow Memory for AI Coding Agents implements the patterns covered in this chapter.
-
-### `.continue/skills/planning-with-files/scripts/session-catchup.py`
-
-The `find_last_planning_update` function in [`.continue/skills/planning-with-files/scripts/session-catchup.py`](https://github.com/OthmanAdi/planning-with-files/blob/HEAD/.continue/skills/planning-with-files/scripts/session-catchup.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def find_last_planning_update(messages: List[Dict]) -> Tuple[int, Optional[str]]:
- """
- Find the last time a planning file was written/edited.
- Returns (line_number, filename) or (-1, None) if not found.
- """
- last_update_line = -1
- last_update_file = None
-
- for msg in messages:
- msg_type = msg.get('type')
-
- if msg_type == 'assistant':
- content = msg.get('message', {}).get('content', [])
- if isinstance(content, list):
- for item in content:
- if item.get('type') == 'tool_use':
- tool_name = item.get('name', '')
- tool_input = item.get('input', {})
-
- if tool_name in ('Write', 'Edit'):
- file_path = tool_input.get('file_path', '')
- for pf in PLANNING_FILES:
- if file_path.endswith(pf):
- last_update_line = msg['_line_num']
- last_update_file = pf
-
- return last_update_line, last_update_file
-
-
-def extract_messages_after(messages: List[Dict], after_line: int) -> List[Dict]:
```
This function is important because it defines how Planning with Files Tutorial: Persistent Markdown Workflow Memory for AI Coding Agents implements the patterns covered in this chapter.
@@ -212,13 +169,9 @@ This function is important because it defines how Planning with Files Tutorial:
```mermaid
flowchart TD
- A[get_project_dir]
- B[get_sessions_sorted]
- C[parse_session_messages]
- D[find_last_planning_update]
- E[extract_messages_after]
+ A[find_last_planning_update]
+ B[extract_messages_after]
+ C[main]
A --> B
B --> C
- C --> D
- D --> E
```
diff --git a/tutorials/planning-with-files-tutorial/07-troubleshooting-anti-patterns-and-safety-checks.md b/tutorials/planning-with-files-tutorial/07-troubleshooting-anti-patterns-and-safety-checks.md
index ea9a9e25..1b3d193b 100644
--- a/tutorials/planning-with-files-tutorial/07-troubleshooting-anti-patterns-and-safety-checks.md
+++ b/tutorials/planning-with-files-tutorial/07-troubleshooting-anti-patterns-and-safety-checks.md
@@ -45,97 +45,57 @@ You now have a robust troubleshooting and safety playbook.
Next: [Chapter 8: Contribution Workflow and Team Adoption](08-contribution-workflow-and-team-adoption.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `.factory/skills/planning-with-files/scripts/session-catchup.py`
+### `skills/planning-with-files-zh/scripts/session-catchup.py`
-The `find_last_planning_update` function in [`.factory/skills/planning-with-files/scripts/session-catchup.py`](https://github.com/OthmanAdi/planning-with-files/blob/HEAD/.factory/skills/planning-with-files/scripts/session-catchup.py) handles a key part of this chapter's functionality:
+The `get_project_dir` function in [`skills/planning-with-files-zh/scripts/session-catchup.py`](https://github.com/OthmanAdi/planning-with-files/blob/HEAD/skills/planning-with-files-zh/scripts/session-catchup.py) handles a key part of this chapter's functionality:
```py
-def find_last_planning_update(messages: List[Dict]) -> Tuple[int, Optional[str]]:
- """
- Find the last time a planning file was written/edited.
- Returns (line_number, filename) or (-1, None) if not found.
- """
- last_update_line = -1
- last_update_file = None
+def get_project_dir(project_path: str) -> Tuple[Optional[Path], Optional[str]]:
+ """Resolve session storage path for the current runtime variant."""
+ sanitized = project_path.replace('/', '-')
+ if not sanitized.startswith('-'):
+ sanitized = '-' + sanitized
+ sanitized = sanitized.replace('_', '-')
- for msg in messages:
- msg_type = msg.get('type')
+ claude_path = Path.home() / '.claude' / 'projects' / sanitized
- if msg_type == 'assistant':
- content = msg.get('message', {}).get('content', [])
- if isinstance(content, list):
- for item in content:
- if item.get('type') == 'tool_use':
- tool_name = item.get('name', '')
- tool_input = item.get('input', {})
+ # Codex stores sessions in ~/.codex/sessions with a different format.
+ # Avoid silently scanning Claude paths when running from Codex skill folder.
+ script_path = Path(__file__).as_posix().lower()
+ is_codex_variant = '/.codex/' in script_path
+ codex_sessions_dir = Path.home() / '.codex' / 'sessions'
+ if is_codex_variant and codex_sessions_dir.exists() and not claude_path.exists():
+ return None, (
+ "[planning-with-files] Session catchup skipped: Codex stores sessions "
+ "in ~/.codex/sessions and native Codex parsing is not implemented yet."
+ )
- if tool_name in ('Write', 'Edit'):
- file_path = tool_input.get('file_path', '')
- for pf in PLANNING_FILES:
- if file_path.endswith(pf):
- last_update_line = msg['_line_num']
- last_update_file = pf
+ return claude_path, None
- return last_update_line, last_update_file
+
+def get_sessions_sorted(project_dir: Path) -> List[Path]:
+ """Get all session files sorted by modification time (newest first)."""
+ sessions = list(project_dir.glob('*.jsonl'))
+ main_sessions = [s for s in sessions if not s.name.startswith('agent-')]
+ return sorted(main_sessions, key=lambda p: p.stat().st_mtime, reverse=True)
-def extract_messages_after(messages: List[Dict], after_line: int) -> List[Dict]:
```
This function is important because it defines how Planning with Files Tutorial: Persistent Markdown Workflow Memory for AI Coding Agents implements the patterns covered in this chapter.
-### `.factory/skills/planning-with-files/scripts/session-catchup.py`
+### `skills/planning-with-files-zh/scripts/session-catchup.py`
-The `extract_messages_after` function in [`.factory/skills/planning-with-files/scripts/session-catchup.py`](https://github.com/OthmanAdi/planning-with-files/blob/HEAD/.factory/skills/planning-with-files/scripts/session-catchup.py) handles a key part of this chapter's functionality:
+The `get_sessions_sorted` function in [`skills/planning-with-files-zh/scripts/session-catchup.py`](https://github.com/OthmanAdi/planning-with-files/blob/HEAD/skills/planning-with-files-zh/scripts/session-catchup.py) handles a key part of this chapter's functionality:
```py
-def extract_messages_after(messages: List[Dict], after_line: int) -> List[Dict]:
- """Extract conversation messages after a certain line number."""
- result = []
- for msg in messages:
- if msg['_line_num'] <= after_line:
- continue
-
- msg_type = msg.get('type')
- is_meta = msg.get('isMeta', False)
-
- if msg_type == 'user' and not is_meta:
- content = msg.get('message', {}).get('content', '')
- if isinstance(content, list):
- for item in content:
- if isinstance(item, dict) and item.get('type') == 'text':
- content = item.get('text', '')
- break
- else:
- content = ''
-
- if content and isinstance(content, str):
- if content.startswith(('<local-command', '<command-', '<task-notification')):
- continue
- if len(content) > 20:
- result.append({'role': 'user', 'content': content, 'line': msg['_line_num']})
-
- elif msg_type == 'assistant':
- msg_content = msg.get('message', {}).get('content', '')
- text_content = ''
- tool_uses = []
-```
-
-This function is important because it defines how Planning with Files Tutorial: Persistent Markdown Workflow Memory for AI Coding Agents implements the patterns covered in this chapter.
-
-### `.factory/skills/planning-with-files/scripts/session-catchup.py`
-
-The `main` function in [`.factory/skills/planning-with-files/scripts/session-catchup.py`](https://github.com/OthmanAdi/planning-with-files/blob/HEAD/.factory/skills/planning-with-files/scripts/session-catchup.py) handles a key part of this chapter's functionality:
-
-```py
+def get_sessions_sorted(project_dir: Path) -> List[Path]:
"""Get all session files sorted by modification time (newest first)."""
sessions = list(project_dir.glob('*.jsonl'))
main_sessions = [s for s in sessions if not s.name.startswith('agent-')]
@@ -145,7 +105,7 @@ The `main` function in [`.factory/skills/planning-with-files/scripts/session-cat
def parse_session_messages(session_file: Path) -> List[Dict]:
"""Parse all messages from a session file, preserving order."""
messages = []
- with open(session_file, 'r', encoding='utf-8', errors='replace') as f:
+ with open(session_file, 'r') as f:
for line_num, line in enumerate(f):
try:
data = json.loads(line)
@@ -165,50 +125,47 @@ def find_last_planning_update(messages: List[Dict]) -> Tuple[int, Optional[str]]
last_update_file = None
for msg in messages:
- msg_type = msg.get('type')
-
- if msg_type == 'assistant':
```
This function is important because it defines how Planning with Files Tutorial: Persistent Markdown Workflow Memory for AI Coding Agents implements the patterns covered in this chapter.
-### `.pi/skills/planning-with-files/scripts/session-catchup.py`
+### `skills/planning-with-files-zh/scripts/session-catchup.py`
-The `normalize_path` function in [`.pi/skills/planning-with-files/scripts/session-catchup.py`](https://github.com/OthmanAdi/planning-with-files/blob/HEAD/.pi/skills/planning-with-files/scripts/session-catchup.py) handles a key part of this chapter's functionality:
+The `parse_session_messages` function in [`skills/planning-with-files-zh/scripts/session-catchup.py`](https://github.com/OthmanAdi/planning-with-files/blob/HEAD/skills/planning-with-files-zh/scripts/session-catchup.py) handles a key part of this chapter's functionality:
```py
-def normalize_path(project_path: str) -> str:
- """Normalize project path to match Claude Code's internal representation.
-
- Claude Code stores session directories using the Windows-native path
- (e.g., C:\\Users\\...) sanitized with separators replaced by dashes.
- Git Bash passes /c/Users/... which produces a DIFFERENT sanitized
- string. This function converts Git Bash paths to Windows paths first.
- """
- p = project_path
-
- # Git Bash / MSYS2: /c/Users/... -> C:/Users/...
- if len(p) >= 3 and p[0] == '/' and p[2] == '/':
- p = p[1].upper() + ':' + p[2:]
-
- # Resolve to absolute path to handle relative paths and symlinks
- try:
- resolved = str(Path(p).resolve())
- # On Windows, resolve() returns C:\Users\... which is what we want
- if os.name == 'nt' or '\\' in resolved:
- p = resolved
- except (OSError, ValueError):
- pass
+def parse_session_messages(session_file: Path) -> List[Dict]:
+ """Parse all messages from a session file, preserving order."""
+ messages = []
+ with open(session_file, 'r') as f:
+ for line_num, line in enumerate(f):
+ try:
+ data = json.loads(line)
+ data['_line_num'] = line_num
+ messages.append(data)
+ except json.JSONDecodeError:
+ pass
+ return messages
- return p
+def find_last_planning_update(messages: List[Dict]) -> Tuple[int, Optional[str]]:
+ """
+ Find the last time a planning file was written/edited.
+ Returns (line_number, filename) or (-1, None) if not found.
+ """
+ last_update_line = -1
+ last_update_file = None
-def get_project_dir(project_path: str) -> Tuple[Optional[Path], Optional[str]]:
- """Resolve session storage path for the current runtime variant."""
- normalized = normalize_path(project_path)
+ for msg in messages:
+ msg_type = msg.get('type')
+ if msg_type == 'assistant':
+ content = msg.get('message', {}).get('content', [])
+ if isinstance(content, list):
+ for item in content:
+ if item.get('type') == 'tool_use':
```
This function is important because it defines how Planning with Files Tutorial: Persistent Markdown Workflow Memory for AI Coding Agents implements the patterns covered in this chapter.
@@ -218,13 +175,9 @@ This function is important because it defines how Planning with Files Tutorial:
```mermaid
flowchart TD
- A[find_last_planning_update]
- B[extract_messages_after]
- C[main]
- D[normalize_path]
- E[get_project_dir]
+ A[get_project_dir]
+ B[get_sessions_sorted]
+ C[parse_session_messages]
A --> B
B --> C
- C --> D
- D --> E
```
diff --git a/tutorials/planning-with-files-tutorial/08-contribution-workflow-and-team-adoption.md b/tutorials/planning-with-files-tutorial/08-contribution-workflow-and-team-adoption.md
index e5105dfb..a63a20c6 100644
--- a/tutorials/planning-with-files-tutorial/08-contribution-workflow-and-team-adoption.md
+++ b/tutorials/planning-with-files-tutorial/08-contribution-workflow-and-team-adoption.md
@@ -49,100 +49,95 @@ Next steps:
- run pilot adoption on one active project
- contribute one improvement with docs and compatibility notes
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `.gemini/skills/planning-with-files/scripts/session-catchup.py`
+### `skills/planning-with-files-zh/scripts/session-catchup.py`
-The `normalize_path` function in [`.gemini/skills/planning-with-files/scripts/session-catchup.py`](https://github.com/OthmanAdi/planning-with-files/blob/HEAD/.gemini/skills/planning-with-files/scripts/session-catchup.py) handles a key part of this chapter's functionality:
+The `find_last_planning_update` function in [`skills/planning-with-files-zh/scripts/session-catchup.py`](https://github.com/OthmanAdi/planning-with-files/blob/HEAD/skills/planning-with-files-zh/scripts/session-catchup.py) handles a key part of this chapter's functionality:
```py
-def normalize_path(project_path: str) -> str:
- """Normalize project path to match Claude Code's internal representation.
-
- Claude Code stores session directories using the Windows-native path
- (e.g., C:\\Users\\...) sanitized with separators replaced by dashes.
- Git Bash passes /c/Users/... which produces a DIFFERENT sanitized
- string. This function converts Git Bash paths to Windows paths first.
+def find_last_planning_update(messages: List[Dict]) -> Tuple[int, Optional[str]]:
+ """
+ Find the last time a planning file was written/edited.
+ Returns (line_number, filename) or (-1, None) if not found.
"""
- p = project_path
+ last_update_line = -1
+ last_update_file = None
- # Git Bash / MSYS2: /c/Users/... -> C:/Users/...
- if len(p) >= 3 and p[0] == '/' and p[2] == '/':
- p = p[1].upper() + ':' + p[2:]
+ for msg in messages:
+ msg_type = msg.get('type')
- # Resolve to absolute path to handle relative paths and symlinks
- try:
- resolved = str(Path(p).resolve())
- # On Windows, resolve() returns C:\Users\... which is what we want
- if os.name == 'nt' or '\\' in resolved:
- p = resolved
- except (OSError, ValueError):
- pass
+ if msg_type == 'assistant':
+ content = msg.get('message', {}).get('content', [])
+ if isinstance(content, list):
+ for item in content:
+ if item.get('type') == 'tool_use':
+ tool_name = item.get('name', '')
+ tool_input = item.get('input', {})
- return p
+ if tool_name in ('Write', 'Edit'):
+ file_path = tool_input.get('file_path', '')
+ for pf in PLANNING_FILES:
+ if file_path.endswith(pf):
+ last_update_line = msg['_line_num']
+ last_update_file = pf
+ return last_update_line, last_update_file
-def get_project_dir(project_path: str) -> Tuple[Optional[Path], Optional[str]]:
- """Resolve session storage path for the current runtime variant."""
- normalized = normalize_path(project_path)
+def extract_messages_after(messages: List[Dict], after_line: int) -> List[Dict]:
```
This function is important because it defines how Planning with Files Tutorial: Persistent Markdown Workflow Memory for AI Coding Agents implements the patterns covered in this chapter.
-### `.gemini/skills/planning-with-files/scripts/session-catchup.py`
+### `skills/planning-with-files-zh/scripts/session-catchup.py`
-The `get_project_dir` function in [`.gemini/skills/planning-with-files/scripts/session-catchup.py`](https://github.com/OthmanAdi/planning-with-files/blob/HEAD/.gemini/skills/planning-with-files/scripts/session-catchup.py) handles a key part of this chapter's functionality:
+The `extract_messages_after` function in [`skills/planning-with-files-zh/scripts/session-catchup.py`](https://github.com/OthmanAdi/planning-with-files/blob/HEAD/skills/planning-with-files-zh/scripts/session-catchup.py) handles a key part of this chapter's functionality:
```py
-def get_project_dir(project_path: str) -> Tuple[Optional[Path], Optional[str]]:
- """Resolve session storage path for the current runtime variant."""
- normalized = normalize_path(project_path)
-
- # Claude Code's sanitization: replace path separators and : with -
- sanitized = normalized.replace('\\', '-').replace('/', '-').replace(':', '-')
- sanitized = sanitized.replace('_', '-')
- # Strip leading dash if present (Unix absolute paths start with /)
- if sanitized.startswith('-'):
- sanitized = sanitized[1:]
-
- claude_path = Path.home() / '.claude' / 'projects' / sanitized
-
- # Codex stores sessions in ~/.codex/sessions with a different format.
- # Avoid silently scanning Claude paths when running from Codex skill folder.
- script_path = Path(__file__).as_posix().lower()
- is_codex_variant = '/.codex/' in script_path
- codex_sessions_dir = Path.home() / '.codex' / 'sessions'
- if is_codex_variant and codex_sessions_dir.exists() and not claude_path.exists():
- return None, (
- "[planning-with-files] Session catchup skipped: Codex stores sessions "
- "in ~/.codex/sessions and native Codex parsing is not implemented yet."
- )
-
- return claude_path, None
+def extract_messages_after(messages: List[Dict], after_line: int) -> List[Dict]:
+ """Extract conversation messages after a certain line number."""
+ result = []
+ for msg in messages:
+ if msg['_line_num'] <= after_line:
+ continue
+ msg_type = msg.get('type')
+ is_meta = msg.get('isMeta', False)
-def get_sessions_sorted(project_dir: Path) -> List[Path]:
- """Get all session files sorted by modification time (newest first)."""
- sessions = list(project_dir.glob('*.jsonl'))
+ if msg_type == 'user' and not is_meta:
+ content = msg.get('message', {}).get('content', '')
+ if isinstance(content, list):
+ for item in content:
+ if isinstance(item, dict) and item.get('type') == 'text':
+ content = item.get('text', '')
+ break
+ else:
+ content = ''
+
+ if content and isinstance(content, str):
+ if content.startswith(('<local-command', '<command-', '<task-notification')):
+ continue
+ if len(content) > 20:
+ result.append({'role': 'user', 'content': content, 'line': msg['_line_num']})
+
+ elif msg_type == 'assistant':
+ msg_content = msg.get('message', {}).get('content', '')
+ text_content = ''
+ tool_uses = []
```
This function is important because it defines how Planning with Files Tutorial: Persistent Markdown Workflow Memory for AI Coding Agents implements the patterns covered in this chapter.
-### `.gemini/skills/planning-with-files/scripts/session-catchup.py`
+### `skills/planning-with-files-zh/scripts/session-catchup.py`
-The `get_sessions_sorted` function in [`.gemini/skills/planning-with-files/scripts/session-catchup.py`](https://github.com/OthmanAdi/planning-with-files/blob/HEAD/.gemini/skills/planning-with-files/scripts/session-catchup.py) handles a key part of this chapter's functionality:
+The `main` function in [`skills/planning-with-files-zh/scripts/session-catchup.py`](https://github.com/OthmanAdi/planning-with-files/blob/HEAD/skills/planning-with-files-zh/scripts/session-catchup.py) handles a key part of this chapter's functionality:
```py
-
-
-def get_sessions_sorted(project_dir: Path) -> List[Path]:
"""Get all session files sorted by modification time (newest first)."""
sessions = list(project_dir.glob('*.jsonl'))
main_sessions = [s for s in sessions if not s.name.startswith('agent-')]
@@ -152,41 +147,7 @@ def get_sessions_sorted(project_dir: Path) -> List[Path]:
def parse_session_messages(session_file: Path) -> List[Dict]:
"""Parse all messages from a session file, preserving order."""
messages = []
- with open(session_file, 'r', encoding='utf-8', errors='replace') as f:
- for line_num, line in enumerate(f):
- try:
- data = json.loads(line)
- data['_line_num'] = line_num
- messages.append(data)
- except json.JSONDecodeError:
- pass
- return messages
-
-
-def find_last_planning_update(messages: List[Dict]) -> Tuple[int, Optional[str]]:
- """
- Find the last time a planning file was written/edited.
- Returns (line_number, filename) or (-1, None) if not found.
- """
- last_update_line = -1
- last_update_file = None
-
- for msg in messages:
-```
-
-This function is important because it defines how Planning with Files Tutorial: Persistent Markdown Workflow Memory for AI Coding Agents implements the patterns covered in this chapter.
-
-### `.gemini/skills/planning-with-files/scripts/session-catchup.py`
-
-The `parse_session_messages` function in [`.gemini/skills/planning-with-files/scripts/session-catchup.py`](https://github.com/OthmanAdi/planning-with-files/blob/HEAD/.gemini/skills/planning-with-files/scripts/session-catchup.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def parse_session_messages(session_file: Path) -> List[Dict]:
- """Parse all messages from a session file, preserving order."""
- messages = []
- with open(session_file, 'r', encoding='utf-8', errors='replace') as f:
+ with open(session_file, 'r') as f:
for line_num, line in enumerate(f):
try:
data = json.loads(line)
@@ -209,10 +170,6 @@ def find_last_planning_update(messages: List[Dict]) -> Tuple[int, Optional[str]]
msg_type = msg.get('type')
if msg_type == 'assistant':
- content = msg.get('message', {}).get('content', [])
- if isinstance(content, list):
- for item in content:
- if item.get('type') == 'tool_use':
```
This function is important because it defines how Planning with Files Tutorial: Persistent Markdown Workflow Memory for AI Coding Agents implements the patterns covered in this chapter.
@@ -222,13 +179,9 @@ This function is important because it defines how Planning with Files Tutorial:
```mermaid
flowchart TD
- A[normalize_path]
- B[get_project_dir]
- C[get_sessions_sorted]
- D[parse_session_messages]
- E[find_last_planning_update]
+ A[find_last_planning_update]
+ B[extract_messages_after]
+ C[main]
A --> B
B --> C
- C --> D
- D --> E
```
diff --git a/tutorials/pocketflow-tutorial/01-getting-started.md b/tutorials/pocketflow-tutorial/01-getting-started.md
index f077ed88..b2c19a61 100644
--- a/tutorials/pocketflow-tutorial/01-getting-started.md
+++ b/tutorials/pocketflow-tutorial/01-getting-started.md
@@ -37,8 +37,6 @@ You now have a runnable PocketFlow setup and know where to find core patterns.
Next: [Chapter 2: Core Graph Abstraction](02-core-graph-abstraction.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `pocketflow/__init__.py`
diff --git a/tutorials/pocketflow-tutorial/02-core-graph-abstraction.md b/tutorials/pocketflow-tutorial/02-core-graph-abstraction.md
index 88af0fd5..22e6602f 100644
--- a/tutorials/pocketflow-tutorial/02-core-graph-abstraction.md
+++ b/tutorials/pocketflow-tutorial/02-core-graph-abstraction.md
@@ -25,8 +25,6 @@ You now understand how the graph abstraction underpins all PocketFlow capabiliti
Next: [Chapter 3: Agent and Workflow Patterns](03-agent-and-workflow-patterns.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `cookbook/pocketflow-code-generator/nodes.py`
diff --git a/tutorials/pocketflow-tutorial/03-agent-and-workflow-patterns.md b/tutorials/pocketflow-tutorial/03-agent-and-workflow-patterns.md
index 31b6929a..bf7dde87 100644
--- a/tutorials/pocketflow-tutorial/03-agent-and-workflow-patterns.md
+++ b/tutorials/pocketflow-tutorial/03-agent-and-workflow-patterns.md
@@ -27,170 +27,168 @@ You now have composition patterns for turning simple nodes into full agent workf
Next: [Chapter 4: RAG and Knowledge Patterns](04-rag-and-knowledge-patterns.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `cookbook/pocketflow-thinking/nodes.py`
+### `cookbook/pocketflow-fastapi-hitl/server.py`
-The `format_plan` function in [`cookbook/pocketflow-thinking/nodes.py`](https://github.com/The-Pocket/PocketFlow/blob/HEAD/cookbook/pocketflow-thinking/nodes.py) handles a key part of this chapter's functionality:
+The `SubmitResponse` class in [`cookbook/pocketflow-fastapi-hitl/server.py`](https://github.com/The-Pocket/PocketFlow/blob/HEAD/cookbook/pocketflow-fastapi-hitl/server.py) handles a key part of this chapter's functionality:
```py
-
-# Helper function to format structured plan for printing
-def format_plan(plan_items, indent_level=0):
- indent = " " * indent_level
- output = []
- if isinstance(plan_items, list):
- for item in plan_items:
- if isinstance(item, dict):
- status = item.get('status', 'Unknown')
- desc = item.get('description', 'No description')
- result = item.get('result', '')
- mark = item.get('mark', '') # For verification etc.
-
- # Format the main step line
- line = f"{indent}- [{status}] {desc}"
- if result:
- line += f": {result}"
- if mark:
- line += f" ({mark})"
- output.append(line)
-
- # Recursively format sub-steps if they exist
- sub_steps = item.get('sub_steps')
- if sub_steps:
- output.append(format_plan(sub_steps, indent_level + 1))
- elif isinstance(item, str): # Basic fallback for string items
- output.append(f"{indent}- {item}")
- else: # Fallback for unexpected types
- output.append(f"{indent}- {str(item)}")
-
- elif isinstance(plan_items, str): # Handle case where plan is just an error string
- output.append(f"{indent}{plan_items}")
+ data: str = Field(..., min_length=1, description="Input data for the task")
+
+class SubmitResponse(BaseModel):
+ message: str = "Task submitted"
+ task_id: str
+
+class FeedbackRequest(BaseModel):
+ feedback: Literal["approved", "rejected"] # Use Literal for specific choices
+
+class FeedbackResponse(BaseModel):
+ message: str
+
+# --- FastAPI Routes ---
+@app.get("/", response_class=HTMLResponse, include_in_schema=False)
+async def get_index(request: Request):
+ """Serves the main HTML frontend."""
+ if templates is None:
+ raise HTTPException(status_code=500, detail="Templates directory not configured.")
+ return templates.TemplateResponse("index.html", {"request": request})
+
+@app.post("/submit", response_model=SubmitResponse, status_code=status.HTTP_202_ACCEPTED)
+async def submit_task(
+ submit_request: SubmitRequest, # Use Pydantic model for validation
+ background_tasks: BackgroundTasks # Inject BackgroundTasks instance
+):
+ """
+ Submits a new task. The actual processing runs in the background.
+ Returns immediately with the task ID.
+ """
+ task_id = str(uuid.uuid4())
+ feedback_event = asyncio.Event()
+ status_queue = asyncio.Queue()
```
-This function is important because it defines how PocketFlow Tutorial: Minimal LLM Framework with Graph-Based Power implements the patterns covered in this chapter.
+This class is important because it defines how PocketFlow Tutorial: Minimal LLM Framework with Graph-Based Power implements the patterns covered in this chapter.
-### `cookbook/pocketflow-thinking/nodes.py`
+### `cookbook/pocketflow-fastapi-hitl/server.py`
-The `format_plan_for_prompt` function in [`cookbook/pocketflow-thinking/nodes.py`](https://github.com/The-Pocket/PocketFlow/blob/HEAD/cookbook/pocketflow-thinking/nodes.py) handles a key part of this chapter's functionality:
+The `FeedbackRequest` class in [`cookbook/pocketflow-fastapi-hitl/server.py`](https://github.com/The-Pocket/PocketFlow/blob/HEAD/cookbook/pocketflow-fastapi-hitl/server.py) handles a key part of this chapter's functionality:
```py
-
-# Helper function to format structured plan for the prompt (simplified view)
-def format_plan_for_prompt(plan_items, indent_level=0):
- indent = " " * indent_level
- output = []
- # Simplified formatting for prompt clarity
- if isinstance(plan_items, list):
- for item in plan_items:
- if isinstance(item, dict):
- status = item.get('status', 'Unknown')
- desc = item.get('description', 'No description')
- line = f"{indent}- [{status}] {desc}"
- output.append(line)
- sub_steps = item.get('sub_steps')
- if sub_steps:
- # Indicate nesting without full recursive display in prompt
- output.append(format_plan_for_prompt(sub_steps, indent_level + 1))
- else: # Fallback
- output.append(f"{indent}- {str(item)}")
- else:
- output.append(f"{indent}{str(plan_items)}")
- return "\n".join(output)
-
-
-class ChainOfThoughtNode(Node):
- def prep(self, shared):
- problem = shared.get("problem", "")
- thoughts = shared.get("thoughts", [])
- current_thought_number = shared.get("current_thought_number", 0)
-
- shared["current_thought_number"] = current_thought_number + 1
-
+ task_id: str
+
+class FeedbackRequest(BaseModel):
+ feedback: Literal["approved", "rejected"] # Use Literal for specific choices
+
+class FeedbackResponse(BaseModel):
+ message: str
+
+# --- FastAPI Routes ---
+@app.get("/", response_class=HTMLResponse, include_in_schema=False)
+async def get_index(request: Request):
+ """Serves the main HTML frontend."""
+ if templates is None:
+ raise HTTPException(status_code=500, detail="Templates directory not configured.")
+ return templates.TemplateResponse("index.html", {"request": request})
+
+@app.post("/submit", response_model=SubmitResponse, status_code=status.HTTP_202_ACCEPTED)
+async def submit_task(
+ submit_request: SubmitRequest, # Use Pydantic model for validation
+ background_tasks: BackgroundTasks # Inject BackgroundTasks instance
+):
+ """
+ Submits a new task. The actual processing runs in the background.
+ Returns immediately with the task ID.
+ """
+ task_id = str(uuid.uuid4())
+ feedback_event = asyncio.Event()
+ status_queue = asyncio.Queue()
+
+ shared = {
+ "task_input": submit_request.data,
+ "processed_output": None,
```
-This function is important because it defines how PocketFlow Tutorial: Minimal LLM Framework with Graph-Based Power implements the patterns covered in this chapter.
+This class is important because it defines how PocketFlow Tutorial: Minimal LLM Framework with Graph-Based Power implements the patterns covered in this chapter.
-### `cookbook/pocketflow-thinking/nodes.py`
+### `cookbook/pocketflow-fastapi-hitl/server.py`
-The `Prompt` interface in [`cookbook/pocketflow-thinking/nodes.py`](https://github.com/The-Pocket/PocketFlow/blob/HEAD/cookbook/pocketflow-thinking/nodes.py) handles a key part of this chapter's functionality:
+The `FeedbackResponse` class in [`cookbook/pocketflow-fastapi-hitl/server.py`](https://github.com/The-Pocket/PocketFlow/blob/HEAD/cookbook/pocketflow-fastapi-hitl/server.py) handles a key part of this chapter's functionality:
```py
- is_first_thought = prep_res["is_first_thought"]
-
- # --- Construct Prompt ---
- # Instructions updated for dictionary structure
- instruction_base = textwrap.dedent(f"""
- Your task is to generate the next thought (Thought {current_thought_number}).
-
- Instructions:
- 1. **Evaluate Previous Thought:** If not the first thought, start `current_thinking` by evaluating Thought {current_thought_number - 1}. State: "Evaluation of Thought {current_thought_number - 1}: [Correct/Minor Issues/Major Error - explain]". Address errors first.
- 2. **Execute Step:** Execute the first step in the plan with `status: Pending`.
- 3. **Maintain Plan (Structure):** Generate an updated `planning` list. Each item should be a dictionary with keys: `description` (string), `status` (string: "Pending", "Done", "Verification Needed"), and optionally `result` (string, concise summary when Done) or `mark` (string, reason for Verification Needed). Sub-steps are represented by a `sub_steps` key containing a *list* of these dictionaries.
- 4. **Update Current Step Status:** In the updated plan, change the `status` of the executed step to "Done" and add a `result` key with a concise summary. If verification is needed based on evaluation, change status to "Verification Needed" and add a `mark`.
- 5. **Refine Plan (Sub-steps):** If a "Pending" step is complex, add a `sub_steps` key to its dictionary containing a list of new step dictionaries (status: "Pending") breaking it down. Keep the parent step's status "Pending" until all sub-steps are "Done".
- 6. **Refine Plan (Errors):** Modify the plan logically based on evaluation findings (e.g., change status, add correction steps).
- 7. **Final Step:** Ensure the plan progresses towards a final step dictionary like `{{'description': "Conclusion", 'status': "Pending"}}`.
- 8. **Termination:** Set `next_thought_needed` to `false` ONLY when executing the step with `description: "Conclusion"`.
- """)
-
- # Context remains largely the same
- if is_first_thought:
- instruction_context = textwrap.dedent("""
- **This is the first thought:** Create an initial plan as a list of dictionaries (keys: description, status). Include sub-steps via the `sub_steps` key if needed. Then, execute the first step in `current_thinking` and provide the updated plan (marking step 1 `status: Done` with a `result`).
- """)
- else:
- instruction_context = textwrap.dedent(f"""
- **Previous Plan (Simplified View):**
- {last_plan_text}
-
- Start `current_thinking` by evaluating Thought {current_thought_number - 1}. Then, proceed with the first step where `status: Pending`. Update the plan structure (list of dictionaries) reflecting evaluation, execution, and refinements.
- """)
-
- # Output format example updated for dictionary structure
+ feedback: Literal["approved", "rejected"] # Use Literal for specific choices
+
+class FeedbackResponse(BaseModel):
+ message: str
+
+# --- FastAPI Routes ---
+@app.get("/", response_class=HTMLResponse, include_in_schema=False)
+async def get_index(request: Request):
+ """Serves the main HTML frontend."""
+ if templates is None:
+ raise HTTPException(status_code=500, detail="Templates directory not configured.")
+ return templates.TemplateResponse("index.html", {"request": request})
+
+@app.post("/submit", response_model=SubmitResponse, status_code=status.HTTP_202_ACCEPTED)
+async def submit_task(
+ submit_request: SubmitRequest, # Use Pydantic model for validation
+ background_tasks: BackgroundTasks # Inject BackgroundTasks instance
+):
+ """
+ Submits a new task. The actual processing runs in the background.
+ Returns immediately with the task ID.
+ """
+ task_id = str(uuid.uuid4())
+ feedback_event = asyncio.Event()
+ status_queue = asyncio.Queue()
+
+ shared = {
+ "task_input": submit_request.data,
+ "processed_output": None,
+ "feedback": None,
+ "review_event": feedback_event,
+ "sse_queue": status_queue,
```
-This interface is important because it defines how PocketFlow Tutorial: Minimal LLM Framework with Graph-Based Power implements the patterns covered in this chapter.
+This class is important because it defines how PocketFlow Tutorial: Minimal LLM Framework with Graph-Based Power implements the patterns covered in this chapter.
-### `cookbook/pocketflow-visualization/visualize.py`
+### `cookbook/pocketflow-fastapi-hitl/server.py`
-The `build_mermaid` function in [`cookbook/pocketflow-visualization/visualize.py`](https://github.com/The-Pocket/PocketFlow/blob/HEAD/cookbook/pocketflow-visualization/visualize.py) handles a key part of this chapter's functionality:
+The `run_flow_background` function in [`cookbook/pocketflow-fastapi-hitl/server.py`](https://github.com/The-Pocket/PocketFlow/blob/HEAD/cookbook/pocketflow-fastapi-hitl/server.py) handles a key part of this chapter's functionality:
```py
-
-
-def build_mermaid(start):
- ids, visited, lines = {}, set(), ["graph LR"]
- ctr = 1
-
- def get_id(n):
- nonlocal ctr
- return (
- ids[n] if n in ids else (ids.setdefault(n, f"N{ctr}"), (ctr := ctr + 1))[0]
- )
-
- def link(a, b, action=None):
- if action:
- lines.append(f" {a} -->|{action}| {b}")
+# This function remains mostly the same, as it defines the work to be done.
+# It will be scheduled by FastAPI's BackgroundTasks now.
+async def run_flow_background(task_id: str, flow, shared: Dict[str, Any]):
+ """Runs the flow in background, uses queue in shared for SSE."""
+ # Check if task exists (might have been cancelled/deleted)
+ if task_id not in tasks:
+ print(f"Background task {task_id}: Task not found, aborting.")
+ return
+ queue = shared.get("sse_queue")
+ if not queue:
+ print(f"ERROR: Task {task_id} missing sse_queue in shared store!")
+ tasks[task_id]["status"] = "failed"
+ # Cannot report failure via SSE if queue is missing
+ return
+
+ tasks[task_id]["status"] = "running"
+ await queue.put({"status": "running"})
+ print(f"Task {task_id}: Background flow starting.")
+
+ final_status = "unknown"
+ error_message = None
+ try:
+ # Execute the potentially long-running PocketFlow
+ await flow.run_async(shared)
+
+ # Determine final status based on shared state after flow completion
+ if shared.get("final_result") is not None:
+ final_status = "completed"
else:
- lines.append(f" {a} --> {b}")
-
- def walk(node, parent=None, action=None):
- if node in visited:
- return parent and link(parent, get_id(node), action)
- visited.add(node)
- if isinstance(node, Flow):
- node.start_node and parent and link(parent, get_id(node.start_node), action)
- lines.append(
- f"\n subgraph sub_flow_{get_id(node)}[{type(node).__name__}]"
- )
- node.start_node and walk(node.start_node)
- for act, nxt in node.successors.items():
- node.start_node and walk(nxt, get_id(node.start_node), act) or (
- parent and link(parent, get_id(nxt), action)
- ) or walk(nxt, None, act)
+ # If flow ends without setting final_result
+ final_status = "finished_incomplete"
+ print(f"Task {task_id}: Flow finished with status: {final_status}")
```
This function is important because it defines how PocketFlow Tutorial: Minimal LLM Framework with Graph-Based Power implements the patterns covered in this chapter.
@@ -200,11 +198,11 @@ This function is important because it defines how PocketFlow Tutorial: Minimal L
```mermaid
flowchart TD
- A[format_plan]
- B[format_plan_for_prompt]
- C[Prompt]
- D[build_mermaid]
- E[flow_to_json]
+ A[SubmitResponse]
+ B[FeedbackRequest]
+ C[FeedbackResponse]
+ D[run_flow_background]
+ E[get_index]
A --> B
B --> C
C --> D
diff --git a/tutorials/pocketflow-tutorial/04-rag-and-knowledge-patterns.md b/tutorials/pocketflow-tutorial/04-rag-and-knowledge-patterns.md
index b3d527ae..30fd0b03 100644
--- a/tutorials/pocketflow-tutorial/04-rag-and-knowledge-patterns.md
+++ b/tutorials/pocketflow-tutorial/04-rag-and-knowledge-patterns.md
@@ -26,169 +26,167 @@ You now know how to model retrieval workflows with clear graph boundaries.
Next: [Chapter 5: Multi-Agent and Supervision](05-multi-agent-and-supervision.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `cookbook/pocketflow-fastapi-hitl/server.py`
+### `cookbook/pocketflow-visualization/visualize.py`
-The `run_flow_background` function in [`cookbook/pocketflow-fastapi-hitl/server.py`](https://github.com/The-Pocket/PocketFlow/blob/HEAD/cookbook/pocketflow-fastapi-hitl/server.py) handles a key part of this chapter's functionality:
+The `find_free_port` function in [`cookbook/pocketflow-visualization/visualize.py`](https://github.com/The-Pocket/PocketFlow/blob/HEAD/cookbook/pocketflow-visualization/visualize.py) handles a key part of this chapter's functionality:
```py
-# This function remains mostly the same, as it defines the work to be done.
-# It will be scheduled by FastAPI's BackgroundTasks now.
-async def run_flow_background(task_id: str, flow, shared: Dict[str, Any]):
- """Runs the flow in background, uses queue in shared for SSE."""
- # Check if task exists (might have been cancelled/deleted)
- if task_id not in tasks:
- print(f"Background task {task_id}: Task not found, aborting.")
- return
- queue = shared.get("sse_queue")
- if not queue:
- print(f"ERROR: Task {task_id} missing sse_queue in shared store!")
- tasks[task_id]["status"] = "failed"
- # Cannot report failure via SSE if queue is missing
- return
-
- tasks[task_id]["status"] = "running"
- await queue.put({"status": "running"})
- print(f"Task {task_id}: Background flow starting.")
-
- final_status = "unknown"
- error_message = None
- try:
- # Execute the potentially long-running PocketFlow
- await flow.run_async(shared)
-
- # Determine final status based on shared state after flow completion
- if shared.get("final_result") is not None:
- final_status = "completed"
- else:
- # If flow ends without setting final_result
- final_status = "finished_incomplete"
- print(f"Task {task_id}: Flow finished with status: {final_status}")
+
+
+def find_free_port():
+ """Find a free port on localhost."""
+ with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+ s.bind(("", 0))
+ s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+ return s.getsockname()[1]
+
+
+def start_http_server(directory, port=None):
+ """Start an HTTP server in the given directory.
+
+ Args:
+ directory: Directory to serve files from
+ port: Port to use (finds a free port if None)
+
+ Returns:
+ tuple: (server_thread, port)
+ """
+ if port is None:
+ port = find_free_port()
+
+ # Get the absolute path of the directory
+ directory = str(Path(directory).absolute())
+
+ # Change to the directory to serve files
+ os.chdir(directory)
+
+ # Create HTTP server
+ handler = http.server.SimpleHTTPRequestHandler
+ httpd = socketserver.TCPServer(("", port), handler)
```
This function is important because it defines how PocketFlow Tutorial: Minimal LLM Framework with Graph-Based Power implements the patterns covered in this chapter.
-### `cookbook/pocketflow-fastapi-hitl/server.py`
+### `cookbook/pocketflow-visualization/visualize.py`
-The `get_index` function in [`cookbook/pocketflow-fastapi-hitl/server.py`](https://github.com/The-Pocket/PocketFlow/blob/HEAD/cookbook/pocketflow-fastapi-hitl/server.py) handles a key part of this chapter's functionality:
+The `start_http_server` function in [`cookbook/pocketflow-visualization/visualize.py`](https://github.com/The-Pocket/PocketFlow/blob/HEAD/cookbook/pocketflow-visualization/visualize.py) handles a key part of this chapter's functionality:
```py
-# --- FastAPI Routes ---
-@app.get("/", response_class=HTMLResponse, include_in_schema=False)
-async def get_index(request: Request):
- """Serves the main HTML frontend."""
- if templates is None:
- raise HTTPException(status_code=500, detail="Templates directory not configured.")
- return templates.TemplateResponse("index.html", {"request": request})
-
-@app.post("/submit", response_model=SubmitResponse, status_code=status.HTTP_202_ACCEPTED)
-async def submit_task(
- submit_request: SubmitRequest, # Use Pydantic model for validation
- background_tasks: BackgroundTasks # Inject BackgroundTasks instance
-):
- """
- Submits a new task. The actual processing runs in the background.
- Returns immediately with the task ID.
+
+
+def start_http_server(directory, port=None):
+ """Start an HTTP server in the given directory.
+
+ Args:
+ directory: Directory to serve files from
+ port: Port to use (finds a free port if None)
+
+ Returns:
+ tuple: (server_thread, port)
"""
- task_id = str(uuid.uuid4())
- feedback_event = asyncio.Event()
- status_queue = asyncio.Queue()
-
- shared = {
- "task_input": submit_request.data,
- "processed_output": None,
- "feedback": None,
- "review_event": feedback_event,
- "sse_queue": status_queue,
- "final_result": None,
- "task_id": task_id
- }
-
- flow = create_feedback_flow()
+ if port is None:
+ port = find_free_port()
+
+ # Get the absolute path of the directory
+ directory = str(Path(directory).absolute())
+
+ # Change to the directory to serve files
+ os.chdir(directory)
+
+ # Create HTTP server
+ handler = http.server.SimpleHTTPRequestHandler
+ httpd = socketserver.TCPServer(("", port), handler)
+
+ # Start server in a separate thread
+ server_thread = threading.Thread(target=httpd.serve_forever)
+ server_thread.daemon = (
+ True # This makes the thread exit when the main program exits
+ )
+ server_thread.start()
+
```
This function is important because it defines how PocketFlow Tutorial: Minimal LLM Framework with Graph-Based Power implements the patterns covered in this chapter.
-### `cookbook/pocketflow-fastapi-hitl/server.py`
+### `cookbook/pocketflow-visualization/visualize.py`
-The `submit_task` function in [`cookbook/pocketflow-fastapi-hitl/server.py`](https://github.com/The-Pocket/PocketFlow/blob/HEAD/cookbook/pocketflow-fastapi-hitl/server.py) handles a key part of this chapter's functionality:
+The `serve_and_open_visualization` function in [`cookbook/pocketflow-visualization/visualize.py`](https://github.com/The-Pocket/PocketFlow/blob/HEAD/cookbook/pocketflow-visualization/visualize.py) handles a key part of this chapter's functionality:
```py
-@app.post("/submit", response_model=SubmitResponse, status_code=status.HTTP_202_ACCEPTED)
-async def submit_task(
- submit_request: SubmitRequest, # Use Pydantic model for validation
- background_tasks: BackgroundTasks # Inject BackgroundTasks instance
-):
- """
- Submits a new task. The actual processing runs in the background.
- Returns immediately with the task ID.
+
+def serve_and_open_visualization(html_path, auto_open=True):
+ """Serve the HTML file and open it in a browser.
+
+ Args:
+ html_path: Path to the HTML file
+ auto_open: Whether to automatically open the browser
+
+ Returns:
+ tuple: (server_thread, url)
"""
- task_id = str(uuid.uuid4())
- feedback_event = asyncio.Event()
- status_queue = asyncio.Queue()
-
- shared = {
- "task_input": submit_request.data,
- "processed_output": None,
- "feedback": None,
- "review_event": feedback_event,
- "sse_queue": status_queue,
- "final_result": None,
- "task_id": task_id
- }
-
- flow = create_feedback_flow()
-
- # Store task state BEFORE scheduling background task
- tasks[task_id] = {
- "shared": shared,
- "status": "pending",
- "task_obj": None # Placeholder for the asyncio Task created by BackgroundTasks
- }
+ # Get the directory and filename
+ directory = os.path.dirname(os.path.abspath(html_path))
+ filename = os.path.basename(html_path)
+
+ # Start the server
+ server_thread, port = start_http_server(directory)
+
+ # Build the URL
+ url = f"http://localhost:{port}/{filename}"
+
+ # Open the URL in a browser
+ if auto_open:
+ print(f"Opening {url} in your browser...")
+ webbrowser.open(url)
+ else:
+ print(f"Visualization available at {url}")
+
+ return server_thread, url
+
+
```
This function is important because it defines how PocketFlow Tutorial: Minimal LLM Framework with Graph-Based Power implements the patterns covered in this chapter.
-### `cookbook/pocketflow-fastapi-hitl/server.py`
+### `cookbook/pocketflow-visualization/visualize.py`
-The `provide_feedback` function in [`cookbook/pocketflow-fastapi-hitl/server.py`](https://github.com/The-Pocket/PocketFlow/blob/HEAD/cookbook/pocketflow-fastapi-hitl/server.py) handles a key part of this chapter's functionality:
+The `visualize_flow` function in [`cookbook/pocketflow-visualization/visualize.py`](https://github.com/The-Pocket/PocketFlow/blob/HEAD/cookbook/pocketflow-visualization/visualize.py) handles a key part of this chapter's functionality:
```py
-@app.post("/feedback/{task_id}", response_model=FeedbackResponse)
-async def provide_feedback(task_id: str, feedback_request: FeedbackRequest):
- """Provides feedback (approved/rejected) to potentially unblock a waiting task."""
- if task_id not in tasks:
- raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Task not found")
-
- task_info = tasks[task_id]
- shared = task_info["shared"]
- queue = shared.get("sse_queue")
- review_event = shared.get("review_event")
-
- async def report_error(message, status_code=status.HTTP_400_BAD_REQUEST):
- # Helper to log, put status on queue, and raise HTTP exception
- print(f"Task {task_id}: Feedback error - {message}")
- if queue: await queue.put({"status": "feedback_error", "error": message})
- raise HTTPException(status_code=status_code, detail=message)
-
- if not review_event:
- # This indicates an internal setup error if the task exists but has no event
- await report_error("Task not configured for feedback", status.HTTP_500_INTERNAL_SERVER_ERROR)
- if review_event.is_set():
- # Prevent processing feedback multiple times or if the task isn't waiting
- await report_error("Task not awaiting feedback or feedback already sent", status.HTTP_409_CONFLICT)
-
- feedback = feedback_request.feedback # Already validated by Pydantic
- print(f"Task {task_id}: Received feedback via POST: {feedback}")
-
- # Update status *before* setting the event, so client sees 'processing' first
- if queue: await queue.put({"status": "processing_feedback", "feedback_value": feedback})
- tasks[task_id]["status"] = "processing_feedback" # Update central status tracker
+
+def visualize_flow(
+ flow: Flow,
+ flow_name: str,
+ serve: bool = True,
+ auto_open: bool = True,
+ output_dir: str = "./viz",
+ html_title: Optional[str] = None,
+) -> Union[str, Tuple[str, Any, str]]:
+ """Helper function to visualize a flow with both mermaid and D3.js
+
+ Args:
+ flow: Flow object to visualize
+ flow_name: Name of the flow (used for filename and display)
+ serve: Whether to start a server for the visualization
+ auto_open: Whether to automatically open in browser
+ output_dir: Directory to save visualization files
+ html_title: Custom title for the HTML page (defaults to flow_name if None)
+
+ Returns:
+ str or tuple: Path to HTML file, or (path, server_thread, url) if serve=True
+ """
+ print(f"\n--- {flow_name} Mermaid Diagram ---")
+ print(build_mermaid(start=flow))
+
+ print(f"\n--- {flow_name} D3.js Visualization ---")
+ json_data = flow_to_json(flow)
+
+ # Create the visualization
+ output_filename = f"{flow_name.lower().replace(' ', '_')}"
```
@@ -199,11 +197,11 @@ This function is important because it defines how PocketFlow Tutorial: Minimal L
```mermaid
flowchart TD
- A[run_flow_background]
- B[get_index]
- C[submit_task]
- D[provide_feedback]
- E[stream_status]
+ A[find_free_port]
+ B[start_http_server]
+ C[serve_and_open_visualization]
+ D[visualize_flow]
+ E[load_flow_from_module]
A --> B
B --> C
C --> D
diff --git a/tutorials/pocketflow-tutorial/05-multi-agent-and-supervision.md b/tutorials/pocketflow-tutorial/05-multi-agent-and-supervision.md
index d4fd7c2c..e71e213c 100644
--- a/tutorials/pocketflow-tutorial/05-multi-agent-and-supervision.md
+++ b/tutorials/pocketflow-tutorial/05-multi-agent-and-supervision.md
@@ -25,184 +25,182 @@ You now have a baseline for orchestrating multiple agents with supervision loops
Next: [Chapter 6: Streaming, HITL, and Interrupts](06-streaming-hitl-and-interrupts.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `cookbook/pocketflow-agent/nodes.py`
+### `cookbook/pocketflow-mcp/utils.py`
-The `SearchWeb` class in [`cookbook/pocketflow-agent/nodes.py`](https://github.com/The-Pocket/PocketFlow/blob/HEAD/cookbook/pocketflow-agent/nodes.py) handles a key part of this chapter's functionality:
+The `that` class in [`cookbook/pocketflow-mcp/utils.py`](https://github.com/The-Pocket/PocketFlow/blob/HEAD/cookbook/pocketflow-mcp/utils.py) handles a key part of this chapter's functionality:
```py
- return exec_res["action"]
-class SearchWeb(Node):
- def prep(self, shared):
- """Get the search query from the shared store."""
- return shared["search_query"]
+ class DictObject(dict):
+ """A simple class that behaves both as a dictionary and as an object with attributes."""
+ def __init__(self, data):
+ super().__init__(data)
+ for key, value in data.items():
+ if isinstance(value, dict):
+ self[key] = DictObject(value)
+ elif isinstance(value, list) and value and isinstance(value[0], dict):
+ self[key] = [DictObject(item) for item in value]
- def exec(self, search_query):
- """Search the web for the given query."""
- # Call the search utility function
- print(f"🌐 Searching the web for: {search_query}")
- results = search_web_duckduckgo(search_query)
- return results
+ def __getattr__(self, key):
+ try:
+ return self[key]
+ except KeyError:
+ raise AttributeError(f"'DictObject' object has no attribute '{key}'")
+
+ return [DictObject(tool) for tool in tools]
+
+def call_tool(server_script_path=None, tool_name=None, arguments=None):
+ """Call a tool, either from MCP server or locally based on MCP global setting."""
+ if MCP:
+ return mcp_call_tool(server_script_path, tool_name, arguments)
+ else:
+ return local_call_tool(server_script_path, tool_name, arguments)
- def post(self, shared, prep_res, exec_res):
- """Save the search results and go back to the decision node."""
- # Add the search results to the context in the shared store
- previous = shared.get("context", "")
- shared["context"] = previous + "\n\nSEARCH: " + shared["search_query"] + "\nRESULTS: " + exec_res
-
- print(f"📚 Found information, analyzing results...")
-
- # Always go back to the decision node after searching
- return "decide"
-
-class AnswerQuestion(Node):
- def prep(self, shared):
- """Get the question and context for answering."""
- return shared["question"], shared.get("context", "")
-
- def exec(self, inputs):
- """Call the LLM to generate a final answer."""
+def mcp_call_tool(server_script_path=None, tool_name=None, arguments=None):
+ """Call a tool on an MCP server.
+ """
+ async def _call_tool():
+ server_params = StdioServerParameters(
+ command="python",
```
This class is important because it defines how PocketFlow Tutorial: Minimal LLM Framework with Graph-Based Power implements the patterns covered in this chapter.
-### `cookbook/pocketflow-agent/nodes.py`
+### `cookbook/pocketflow-mcp/utils.py`
-The `AnswerQuestion` class in [`cookbook/pocketflow-agent/nodes.py`](https://github.com/The-Pocket/PocketFlow/blob/HEAD/cookbook/pocketflow-agent/nodes.py) handles a key part of this chapter's functionality:
+The `call_llm` function in [`cookbook/pocketflow-mcp/utils.py`](https://github.com/The-Pocket/PocketFlow/blob/HEAD/cookbook/pocketflow-mcp/utils.py) handles a key part of this chapter's functionality:
```py
- return "decide"
-
-class AnswerQuestion(Node):
- def prep(self, shared):
- """Get the question and context for answering."""
- return shared["question"], shared.get("context", "")
-
- def exec(self, inputs):
- """Call the LLM to generate a final answer."""
- question, context = inputs
-
- print(f"✍️ Crafting final answer...")
-
- # Create a prompt for the LLM to answer the question
- prompt = f"""
-### CONTEXT
-Based on the following information, answer the question.
-Question: {question}
-Research: {context}
-
-## YOUR ANSWER:
-Provide a comprehensive answer using the research results.
-"""
- # Call the LLM to generate an answer
- answer = call_llm(prompt)
- return answer
+MCP = False
+
+def call_llm(prompt):
+ client = OpenAI(api_key=os.environ.get("OPENAI_API_KEY", "your-api-key"))
+ r = client.chat.completions.create(
+ model="gpt-4o",
+ messages=[{"role": "user", "content": prompt}]
+ )
+ return r.choices[0].message.content
+
+def get_tools(server_script_path=None):
+ """Get available tools, either from MCP server or locally based on MCP global setting."""
+ if MCP:
+ return mcp_get_tools(server_script_path)
+ else:
+ return local_get_tools(server_script_path)
- def post(self, shared, prep_res, exec_res):
- """Save the final answer and complete the flow."""
- # Save the answer in the shared store
- shared["answer"] = exec_res
+def mcp_get_tools(server_script_path):
+ """Get available tools from an MCP server.
+ """
+ async def _get_tools():
+ server_params = StdioServerParameters(
+ command="python",
+ args=[server_script_path]
+ )
+ async with stdio_client(server_params) as (read, write):
+ async with ClientSession(read, write) as session:
+ await session.initialize()
+ tools_response = await session.list_tools()
+ return tools_response.tools
+
```
-This class is important because it defines how PocketFlow Tutorial: Minimal LLM Framework with Graph-Based Power implements the patterns covered in this chapter.
+This function is important because it defines how PocketFlow Tutorial: Minimal LLM Framework with Graph-Based Power implements the patterns covered in this chapter.
-### `cookbook/pocketflow-tao/nodes.py`
+### `cookbook/pocketflow-mcp/utils.py`
-The `ThinkNode` class in [`cookbook/pocketflow-tao/nodes.py`](https://github.com/The-Pocket/PocketFlow/blob/HEAD/cookbook/pocketflow-tao/nodes.py) handles a key part of this chapter's functionality:
+The `get_tools` function in [`cookbook/pocketflow-mcp/utils.py`](https://github.com/The-Pocket/PocketFlow/blob/HEAD/cookbook/pocketflow-mcp/utils.py) handles a key part of this chapter's functionality:
```py
-from utils import call_llm
-
-class ThinkNode(Node):
- def prep(self, shared):
- """Prepare the context needed for thinking"""
- query = shared.get("query", "")
- observations = shared.get("observations", [])
- thoughts = shared.get("thoughts", [])
- current_thought_number = shared.get("current_thought_number", 0)
-
- # Update thought count
- shared["current_thought_number"] = current_thought_number + 1
-
- # Format previous observations
- observations_text = "\n".join([f"Observation {i+1}: {obs}" for i, obs in enumerate(observations)])
- if not observations_text:
- observations_text = "No observations yet."
-
- return {
- "query": query,
- "observations_text": observations_text,
- "thoughts": thoughts,
- "current_thought_number": current_thought_number + 1
- }
+ return r.choices[0].message.content
+
+def get_tools(server_script_path=None):
+ """Get available tools, either from MCP server or locally based on MCP global setting."""
+ if MCP:
+ return mcp_get_tools(server_script_path)
+ else:
+ return local_get_tools(server_script_path)
- def exec(self, prep_res):
- """Execute the thinking process, decide the next action"""
- query = prep_res["query"]
- observations_text = prep_res["observations_text"]
- current_thought_number = prep_res["current_thought_number"]
+def mcp_get_tools(server_script_path):
+ """Get available tools from an MCP server.
+ """
+ async def _get_tools():
+ server_params = StdioServerParameters(
+ command="python",
+ args=[server_script_path]
+ )
- # Build the prompt
+ async with stdio_client(server_params) as (read, write):
+ async with ClientSession(read, write) as session:
+ await session.initialize()
+ tools_response = await session.list_tools()
+ return tools_response.tools
+
+ return asyncio.run(_get_tools())
+
+def local_get_tools(server_script_path=None):
+ """A simple dummy implementation of get_tools without MCP."""
+ tools = [
+ {
+ "name": "add",
+ "description": "Add two numbers together",
```
-This class is important because it defines how PocketFlow Tutorial: Minimal LLM Framework with Graph-Based Power implements the patterns covered in this chapter.
+This function is important because it defines how PocketFlow Tutorial: Minimal LLM Framework with Graph-Based Power implements the patterns covered in this chapter.
-### `cookbook/pocketflow-tao/nodes.py`
+### `cookbook/pocketflow-mcp/utils.py`
-The `ActionNode` class in [`cookbook/pocketflow-tao/nodes.py`](https://github.com/The-Pocket/PocketFlow/blob/HEAD/cookbook/pocketflow-tao/nodes.py) handles a key part of this chapter's functionality:
+The `mcp_get_tools` function in [`cookbook/pocketflow-mcp/utils.py`](https://github.com/The-Pocket/PocketFlow/blob/HEAD/cookbook/pocketflow-mcp/utils.py) handles a key part of this chapter's functionality:
```py
- return "action"
-
-class ActionNode(Node):
- def prep(self, shared):
- """Prepare to execute action"""
- action = shared["current_action"]
- action_input = shared["current_action_input"]
- return action, action_input
+ """Get available tools, either from MCP server or locally based on MCP global setting."""
+ if MCP:
+ return mcp_get_tools(server_script_path)
+ else:
+ return local_get_tools(server_script_path)
- def exec(self, inputs):
- """Execute action and return result"""
- action, action_input = inputs
-
- print(f"🚀 Executing action: {action}, input: {action_input}")
+def mcp_get_tools(server_script_path):
+ """Get available tools from an MCP server.
+ """
+ async def _get_tools():
+ server_params = StdioServerParameters(
+ command="python",
+ args=[server_script_path]
+ )
- # Execute different operations based on action type
- if action == "search":
- # Simulate search operation
- result = self.search_web(action_input)
- elif action == "calculate":
- # Simulate calculation operation
- result = self.calculate(action_input)
- elif action == "answer":
- # Direct return answer
- result = action_input
- else:
- # Unknown action type
- result = f"Unknown action type: {action}"
-
- return result
+ async with stdio_client(server_params) as (read, write):
+ async with ClientSession(read, write) as session:
+ await session.initialize()
+ tools_response = await session.list_tools()
+ return tools_response.tools
- def post(self, shared, prep_res, exec_res):
+ return asyncio.run(_get_tools())
+
+def local_get_tools(server_script_path=None):
+ """A simple dummy implementation of get_tools without MCP."""
+ tools = [
+ {
+ "name": "add",
+ "description": "Add two numbers together",
+ "inputSchema": {
+ "properties": {
+ "a": {"type": "integer"},
```
-This class is important because it defines how PocketFlow Tutorial: Minimal LLM Framework with Graph-Based Power implements the patterns covered in this chapter.
+This function is important because it defines how PocketFlow Tutorial: Minimal LLM Framework with Graph-Based Power implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[SearchWeb]
- B[AnswerQuestion]
- C[ThinkNode]
- D[ActionNode]
- E[ObserveNode]
+ A[that]
+ B[call_llm]
+ C[get_tools]
+ D[mcp_get_tools]
+ E[local_get_tools]
A --> B
B --> C
C --> D
diff --git a/tutorials/pocketflow-tutorial/06-streaming-hitl-and-interrupts.md b/tutorials/pocketflow-tutorial/06-streaming-hitl-and-interrupts.md
index abeebb2f..e8c4bc0d 100644
--- a/tutorials/pocketflow-tutorial/06-streaming-hitl-and-interrupts.md
+++ b/tutorials/pocketflow-tutorial/06-streaming-hitl-and-interrupts.md
@@ -27,184 +27,182 @@ You now know how to add interactive controls to PocketFlow applications.
Next: [Chapter 7: Multi-Language Ecosystem](07-multi-language-ecosystem.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `cookbook/pocketflow-mcp/utils.py`
+### `cookbook/pocketflow-coding-agent/nodes.py`
-The `DictObject` class in [`cookbook/pocketflow-mcp/utils.py`](https://github.com/The-Pocket/PocketFlow/blob/HEAD/cookbook/pocketflow-mcp/utils.py) handles a key part of this chapter's functionality:
+The `ListFiles` class in [`cookbook/pocketflow-coding-agent/nodes.py`](https://github.com/The-Pocket/PocketFlow/blob/HEAD/cookbook/pocketflow-coding-agent/nodes.py) handles a key part of this chapter's functionality:
```py
- ]
-
- class DictObject(dict):
- """A simple class that behaves both as a dictionary and as an object with attributes."""
- def __init__(self, data):
- super().__init__(data)
- for key, value in data.items():
- if isinstance(value, dict):
- self[key] = DictObject(value)
- elif isinstance(value, list) and value and isinstance(value[0], dict):
- self[key] = [DictObject(item) for item in value]
-
- def __getattr__(self, key):
- try:
- return self[key]
- except KeyError:
- raise AttributeError(f"'DictObject' object has no attribute '{key}'")
-
- return [DictObject(tool) for tool in tools]
-
-def call_tool(server_script_path=None, tool_name=None, arguments=None):
- """Call a tool, either from MCP server or locally based on MCP global setting."""
- if MCP:
- return mcp_call_tool(server_script_path, tool_name, arguments)
- else:
- return local_call_tool(server_script_path, tool_name, arguments)
-
-def mcp_call_tool(server_script_path=None, tool_name=None, arguments=None):
- """Call a tool on an MCP server.
- """
- async def _call_tool():
- server_params = StdioServerParameters(
+ print(f" ✅ {str(exec_res)[:200]}")
+
+class ListFiles(ToolNode):
+ def exec(self, inputs):
+ args, workdir = inputs
+ result = []
+ for root, _, files in os.walk(_path(workdir, args.get("directory", "."))):
+ for f in files:
+ if not f.startswith("."): result.append(os.path.relpath(os.path.join(root, f), workdir))
+ return "\n".join(result)
+
+class GrepSearch(ToolNode):
+ def exec(self, inputs):
+ args, workdir = inputs
+ pattern, path = args.get("pattern", ""), args.get("path", ".")
+ results = []
+ for root, _, files in os.walk(_path(workdir, path)):
+ for fname in files:
+ if not fname.endswith(".py"): continue
+ fpath = os.path.join(root, fname)
+ with open(fpath) as f:
+ for i, line in enumerate(f, 1):
+ if re.search(pattern, line):
+ results.append(f"{os.path.relpath(fpath, workdir)}:{i}: {line.rstrip()}")
+ return "\n".join(results) or "No matches"
+
+class ReadFile(ToolNode):
+ def exec(self, inputs):
+ args, workdir = inputs
+ with open(_path(workdir, args["path"])) as f: lines = f.readlines()
+ end = args.get("end") or len(lines)
+ start = args.get("start", 1)
```
This class is important because it defines how PocketFlow Tutorial: Minimal LLM Framework with Graph-Based Power implements the patterns covered in this chapter.
-### `cookbook/pocketflow-mcp/utils.py`
+### `cookbook/pocketflow-coding-agent/nodes.py`
-The `that` class in [`cookbook/pocketflow-mcp/utils.py`](https://github.com/The-Pocket/PocketFlow/blob/HEAD/cookbook/pocketflow-mcp/utils.py) handles a key part of this chapter's functionality:
+The `GrepSearch` class in [`cookbook/pocketflow-coding-agent/nodes.py`](https://github.com/The-Pocket/PocketFlow/blob/HEAD/cookbook/pocketflow-coding-agent/nodes.py) handles a key part of this chapter's functionality:
```py
-
- class DictObject(dict):
- """A simple class that behaves both as a dictionary and as an object with attributes."""
- def __init__(self, data):
- super().__init__(data)
- for key, value in data.items():
- if isinstance(value, dict):
- self[key] = DictObject(value)
- elif isinstance(value, list) and value and isinstance(value[0], dict):
- self[key] = [DictObject(item) for item in value]
-
- def __getattr__(self, key):
- try:
- return self[key]
- except KeyError:
- raise AttributeError(f"'DictObject' object has no attribute '{key}'")
-
- return [DictObject(tool) for tool in tools]
-
-def call_tool(server_script_path=None, tool_name=None, arguments=None):
- """Call a tool, either from MCP server or locally based on MCP global setting."""
- if MCP:
- return mcp_call_tool(server_script_path, tool_name, arguments)
- else:
- return local_call_tool(server_script_path, tool_name, arguments)
-
-def mcp_call_tool(server_script_path=None, tool_name=None, arguments=None):
- """Call a tool on an MCP server.
- """
- async def _call_tool():
- server_params = StdioServerParameters(
- command="python",
+ return "\n".join(result)
+
+class GrepSearch(ToolNode):
+ def exec(self, inputs):
+ args, workdir = inputs
+ pattern, path = args.get("pattern", ""), args.get("path", ".")
+ results = []
+ for root, _, files in os.walk(_path(workdir, path)):
+ for fname in files:
+ if not fname.endswith(".py"): continue
+ fpath = os.path.join(root, fname)
+ with open(fpath) as f:
+ for i, line in enumerate(f, 1):
+ if re.search(pattern, line):
+ results.append(f"{os.path.relpath(fpath, workdir)}:{i}: {line.rstrip()}")
+ return "\n".join(results) or "No matches"
+
+class ReadFile(ToolNode):
+ def exec(self, inputs):
+ args, workdir = inputs
+ with open(_path(workdir, args["path"])) as f: lines = f.readlines()
+ end = args.get("end") or len(lines)
+ start = args.get("start", 1)
+ return "".join(f"{i}: {l}" for i, l in enumerate(lines[start-1:end], start))
+
+class RunCommand(ToolNode):
+ def exec(self, inputs):
+ args, workdir = inputs
+ r = subprocess.run(args["cmd"], shell=True, capture_output=True, text=True, cwd=workdir, timeout=30)
+ return (r.stdout + r.stderr) or "(no output)"
+
+# patch_file as SubFlow
```
This class is important because it defines how PocketFlow Tutorial: Minimal LLM Framework with Graph-Based Power implements the patterns covered in this chapter.
-### `cookbook/pocketflow-mcp/utils.py`
+### `cookbook/pocketflow-coding-agent/nodes.py`
-The `call_llm` function in [`cookbook/pocketflow-mcp/utils.py`](https://github.com/The-Pocket/PocketFlow/blob/HEAD/cookbook/pocketflow-mcp/utils.py) handles a key part of this chapter's functionality:
+The `ReadFile` class in [`cookbook/pocketflow-coding-agent/nodes.py`](https://github.com/The-Pocket/PocketFlow/blob/HEAD/cookbook/pocketflow-coding-agent/nodes.py) handles a key part of this chapter's functionality:
```py
-MCP = False
-
-def call_llm(prompt):
- client = OpenAI(api_key=os.environ.get("OPENAI_API_KEY", "your-api-key"))
- r = client.chat.completions.create(
- model="gpt-4o",
- messages=[{"role": "user", "content": prompt}]
- )
- return r.choices[0].message.content
-
-def get_tools(server_script_path=None):
- """Get available tools, either from MCP server or locally based on MCP global setting."""
- if MCP:
- return mcp_get_tools(server_script_path)
- else:
- return local_get_tools(server_script_path)
-
-def mcp_get_tools(server_script_path):
- """Get available tools from an MCP server.
- """
- async def _get_tools():
- server_params = StdioServerParameters(
- command="python",
- args=[server_script_path]
- )
-
- async with stdio_client(server_params) as (read, write):
- async with ClientSession(read, write) as session:
- await session.initialize()
- tools_response = await session.list_tools()
- return tools_response.tools
-
+ return "\n".join(results) or "No matches"
+
+class ReadFile(ToolNode):
+ def exec(self, inputs):
+ args, workdir = inputs
+ with open(_path(workdir, args["path"])) as f: lines = f.readlines()
+ end = args.get("end") or len(lines)
+ start = args.get("start", 1)
+ return "".join(f"{i}: {l}" for i, l in enumerate(lines[start-1:end], start))
+
+class RunCommand(ToolNode):
+ def exec(self, inputs):
+ args, workdir = inputs
+ r = subprocess.run(args["cmd"], shell=True, capture_output=True, text=True, cwd=workdir, timeout=30)
+ return (r.stdout + r.stderr) or "(no output)"
+
+# patch_file as SubFlow
+class PatchRead(Node):
+ def prep(self, shared):
+ return shared["tool_call"]["args"]["path"], shared["workdir"]
+ def exec(self, inputs):
+ path, workdir = inputs
+ with open(_path(workdir, path)) as f: return f.read()
+ def post(self, shared, prep_res, exec_res):
+ shared["_patch_content"] = exec_res
+
+class PatchValidate(Node):
+ def prep(self, shared):
+ args = shared["tool_call"]["args"]
+ return shared["_patch_content"], args["old_str"], args["path"]
+ def exec(self, inputs):
+ content, old_str, path = inputs
```
-This function is important because it defines how PocketFlow Tutorial: Minimal LLM Framework with Graph-Based Power implements the patterns covered in this chapter.
+This class is important because it defines how PocketFlow Tutorial: Minimal LLM Framework with Graph-Based Power implements the patterns covered in this chapter.
-### `cookbook/pocketflow-mcp/utils.py`
+### `cookbook/pocketflow-coding-agent/nodes.py`
-The `get_tools` function in [`cookbook/pocketflow-mcp/utils.py`](https://github.com/The-Pocket/PocketFlow/blob/HEAD/cookbook/pocketflow-mcp/utils.py) handles a key part of this chapter's functionality:
+The `RunCommand` class in [`cookbook/pocketflow-coding-agent/nodes.py`](https://github.com/The-Pocket/PocketFlow/blob/HEAD/cookbook/pocketflow-coding-agent/nodes.py) handles a key part of this chapter's functionality:
```py
- return r.choices[0].message.content
-
-def get_tools(server_script_path=None):
- """Get available tools, either from MCP server or locally based on MCP global setting."""
- if MCP:
- return mcp_get_tools(server_script_path)
- else:
- return local_get_tools(server_script_path)
-
-def mcp_get_tools(server_script_path):
- """Get available tools from an MCP server.
- """
- async def _get_tools():
- server_params = StdioServerParameters(
- command="python",
- args=[server_script_path]
- )
-
- async with stdio_client(server_params) as (read, write):
- async with ClientSession(read, write) as session:
- await session.initialize()
- tools_response = await session.list_tools()
- return tools_response.tools
-
- return asyncio.run(_get_tools())
-
-def local_get_tools(server_script_path=None):
- """A simple dummy implementation of get_tools without MCP."""
- tools = [
- {
- "name": "add",
- "description": "Add two numbers together",
+ return "".join(f"{i}: {l}" for i, l in enumerate(lines[start-1:end], start))
+
+class RunCommand(ToolNode):
+ def exec(self, inputs):
+ args, workdir = inputs
+ r = subprocess.run(args["cmd"], shell=True, capture_output=True, text=True, cwd=workdir, timeout=30)
+ return (r.stdout + r.stderr) or "(no output)"
+
+# patch_file as SubFlow
+class PatchRead(Node):
+ def prep(self, shared):
+ return shared["tool_call"]["args"]["path"], shared["workdir"]
+ def exec(self, inputs):
+ path, workdir = inputs
+ with open(_path(workdir, path)) as f: return f.read()
+ def post(self, shared, prep_res, exec_res):
+ shared["_patch_content"] = exec_res
+
+class PatchValidate(Node):
+ def prep(self, shared):
+ args = shared["tool_call"]["args"]
+ return shared["_patch_content"], args["old_str"], args["path"]
+ def exec(self, inputs):
+ content, old_str, path = inputs
+ if old_str not in content:
+ lines = content.split('\n')
+ n = old_str.count('\n') + 1
+ chunks = ['\n'.join(lines[i:i+n]) for i in range(len(lines))]
+ best = difflib.get_close_matches(old_str, chunks, n=1, cutoff=0.4)
+ if best: return f"ERROR: old_str not found in {path}. Did you mean:\n{best[0]}"
+ return f"ERROR: old_str not found in {path}"
+ if content.count(old_str) > 1:
```
-This function is important because it defines how PocketFlow Tutorial: Minimal LLM Framework with Graph-Based Power implements the patterns covered in this chapter.
+This class is important because it defines how PocketFlow Tutorial: Minimal LLM Framework with Graph-Based Power implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[DictObject]
- B[that]
- C[call_llm]
- D[get_tools]
- E[mcp_get_tools]
+ A[ListFiles]
+ B[GrepSearch]
+ C[ReadFile]
+ D[RunCommand]
+ E[PatchRead]
A --> B
B --> C
C --> D
diff --git a/tutorials/pocketflow-tutorial/07-multi-language-ecosystem.md b/tutorials/pocketflow-tutorial/07-multi-language-ecosystem.md
index 6de97b20..e9ce863b 100644
--- a/tutorials/pocketflow-tutorial/07-multi-language-ecosystem.md
+++ b/tutorials/pocketflow-tutorial/07-multi-language-ecosystem.md
@@ -25,170 +25,168 @@ You now understand how PocketFlow patterns can transfer across language stacks.
Next: [Chapter 8: Production Usage and Scaling](08-production-usage-and-scaling.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `cookbook/pocketflow-chat-guardrail/main.py`
+### `cookbook/pocketflow-supervisor/nodes.py`
-The `GuardrailNode` class in [`cookbook/pocketflow-chat-guardrail/main.py`](https://github.com/The-Pocket/PocketFlow/blob/HEAD/cookbook/pocketflow-chat-guardrail/main.py) handles a key part of this chapter's functionality:
+The `DecideAction` class in [`cookbook/pocketflow-supervisor/nodes.py`](https://github.com/The-Pocket/PocketFlow/blob/HEAD/cookbook/pocketflow-supervisor/nodes.py) handles a key part of this chapter's functionality:
```py
- return "validate"
+import random
-class GuardrailNode(Node):
+class DecideAction(Node):
def prep(self, shared):
- # Get the user input from shared data
- user_input = shared.get("user_input", "")
- return user_input
-
- def exec(self, user_input):
- # Basic validation checks
- if not user_input or user_input.strip() == "":
- return False, "Your query is empty. Please provide a travel-related question."
-
- if len(user_input.strip()) < 3:
- return False, "Your query is too short. Please provide more details about your travel question."
+ """Prepare the context and question for the decision-making process."""
+ # Get the current context (default to "No previous search" if none exists)
+ context = shared.get("context", "No previous search")
+ # Get the question from the shared store
+ question = shared["question"]
+ # Return both for the exec step
+ return question, context
- # LLM-based validation for travel topics
- prompt = f"""
-Evaluate if the following user query is related to travel advice, destinations, planning, or other travel topics.
-The chat should ONLY answer travel-related questions and reject any off-topic, harmful, or inappropriate queries.
-User query: {user_input}
-Return your evaluation in YAML format:
-```yaml
-valid: true/false
-reason: [Explain why the query is valid or invalid]
-```"""
+ def exec(self, inputs):
+ """Call the LLM to decide whether to search or answer."""
+ question, context = inputs
- # Call LLM with the validation prompt
- messages = [{"role": "user", "content": prompt}]
- response = call_llm(messages)
+ print(f"🤔 Agent deciding what to do next...")
- # Extract YAML content
+ # Create a prompt to help the LLM decide what to do next
+ prompt = f"""
+### CONTEXT
+You are a research assistant that can search the web.
+Question: {question}
+Previous Research: {context}
+
+### ACTION SPACE
+[1] search
+ Description: Look up more information on the web
+ Parameters:
+ - query (str): What to search for
+
+[2] answer
```
This class is important because it defines how PocketFlow Tutorial: Minimal LLM Framework with Graph-Based Power implements the patterns covered in this chapter.
-### `cookbook/pocketflow-chat-guardrail/main.py`
+### `cookbook/pocketflow-supervisor/nodes.py`
-The `LLMNode` class in [`cookbook/pocketflow-chat-guardrail/main.py`](https://github.com/The-Pocket/PocketFlow/blob/HEAD/cookbook/pocketflow-chat-guardrail/main.py) handles a key part of this chapter's functionality:
+The `SearchWeb` class in [`cookbook/pocketflow-supervisor/nodes.py`](https://github.com/The-Pocket/PocketFlow/blob/HEAD/cookbook/pocketflow-supervisor/nodes.py) handles a key part of this chapter's functionality:
```py
- return "process"
+ return exec_res["action"]
-class LLMNode(Node):
+class SearchWeb(Node):
def prep(self, shared):
- # Add system message if not present
- if not any(msg.get("role") == "system" for msg in shared["messages"]):
- shared["messages"].insert(0, {
- "role": "system",
- "content": "You are a helpful travel advisor that provides information about destinations, travel planning, accommodations, transportation, activities, and other travel-related topics. Only respond to travel-related queries and keep responses informative and friendly. Your response are concise in 100 words."
- })
+ """Get the search query from the shared store."""
+ return shared["search_query"]
- # Return all messages for the LLM
- return shared["messages"]
-
- def exec(self, messages):
- # Call LLM with the entire conversation history
- response = call_llm(messages)
- return response
-
+ def exec(self, search_query):
+ """Search the web for the given query."""
+ # Call the search utility function
+ print(f"🌐 Searching the web for: {search_query}")
+ results = search_web(search_query)
+ return results
+
def post(self, shared, prep_res, exec_res):
- # Print the assistant's response
- print(f"\nTravel Advisor: {exec_res}")
+ """Save the search results and go back to the decision node."""
+ # Add the search results to the context in the shared store
+ previous = shared.get("context", "")
+ shared["context"] = previous + "\n\nSEARCH: " + shared["search_query"] + "\nRESULTS: " + exec_res
- # Add assistant message to history
- shared["messages"].append({"role": "assistant", "content": exec_res})
+ print(f"📚 Found information, analyzing results...")
- # Loop back to continue the conversation
- return "continue"
+ # Always go back to the decision node after searching
+ return "decide"
-# Create the flow with nodes and connections
-user_input_node = UserInputNode()
-guardrail_node = GuardrailNode()
+class UnreliableAnswerNode(Node):
+ def prep(self, shared):
+ """Get the question and context for answering."""
+ return shared["question"], shared.get("context", "")
+
+ def exec(self, inputs):
+ """Call the LLM to generate a final answer with 50% chance of returning a dummy answer."""
```
This class is important because it defines how PocketFlow Tutorial: Minimal LLM Framework with Graph-Based Power implements the patterns covered in this chapter.
-### `cookbook/pocketflow-mcp/main.py`
+### `cookbook/pocketflow-supervisor/nodes.py`
-The `GetToolsNode` class in [`cookbook/pocketflow-mcp/main.py`](https://github.com/The-Pocket/PocketFlow/blob/HEAD/cookbook/pocketflow-mcp/main.py) handles a key part of this chapter's functionality:
+The `UnreliableAnswerNode` class in [`cookbook/pocketflow-supervisor/nodes.py`](https://github.com/The-Pocket/PocketFlow/blob/HEAD/cookbook/pocketflow-supervisor/nodes.py) handles a key part of this chapter's functionality:
```py
-import sys
+ return "decide"
-class GetToolsNode(Node):
+class UnreliableAnswerNode(Node):
def prep(self, shared):
- """Initialize and get tools"""
- # The question is now passed from main via shared
- print("🔍 Getting available tools...")
- return "simple_server.py"
-
- def exec(self, server_path):
- """Retrieve tools from the MCP server"""
- tools = get_tools(server_path)
- return tools
-
- def post(self, shared, prep_res, exec_res):
- """Store tools and process to decision node"""
- tools = exec_res
- shared["tools"] = tools
+ """Get the question and context for answering."""
+ return shared["question"], shared.get("context", "")
+
+ def exec(self, inputs):
+ """Call the LLM to generate a final answer with 50% chance of returning a dummy answer."""
+ question, context = inputs
+
+ # 50% chance to return a dummy answer
+ if random.random() < 0.5:
+ print(f"🤪 Generating unreliable dummy answer...")
+ return "Sorry, I'm on a coffee break right now. All information I provide is completely made up anyway. The answer to your question is 42, or maybe purple unicorns. Who knows? Certainly not me!"
- # Format tool information for later use
- tool_info = []
- for i, tool in enumerate(tools, 1):
- properties = tool.inputSchema.get('properties', {})
- required = tool.inputSchema.get('required', [])
-
- params = []
- for param_name, param_info in properties.items():
- param_type = param_info.get('type', 'unknown')
- req_status = "(Required)" if param_name in required else "(Optional)"
- params.append(f" - {param_name} ({param_type}): {req_status}")
-
- tool_info.append(f"[{i}] {tool.name}\n Description: {tool.description}\n Parameters:\n" + "\n".join(params))
+ print(f"✍️ Crafting final answer...")
+
+ # Create a prompt for the LLM to answer the question
+ prompt = f"""
+### CONTEXT
+Based on the following information, answer the question.
+Question: {question}
+Research: {context}
+
+## YOUR ANSWER:
+Provide a comprehensive answer using the research results.
+"""
+ # Call the LLM to generate an answer
+ answer = call_llm(prompt)
+ return answer
+
```
This class is important because it defines how PocketFlow Tutorial: Minimal LLM Framework with Graph-Based Power implements the patterns covered in this chapter.
-### `cookbook/pocketflow-mcp/main.py`
+### `cookbook/pocketflow-supervisor/nodes.py`
-The `DecideToolNode` class in [`cookbook/pocketflow-mcp/main.py`](https://github.com/The-Pocket/PocketFlow/blob/HEAD/cookbook/pocketflow-mcp/main.py) handles a key part of this chapter's functionality:
+The `SupervisorNode` class in [`cookbook/pocketflow-supervisor/nodes.py`](https://github.com/The-Pocket/PocketFlow/blob/HEAD/cookbook/pocketflow-supervisor/nodes.py) handles a key part of this chapter's functionality:
```py
- return "decide"
+ print(f"✅ Answer generated successfully")
-class DecideToolNode(Node):
+class SupervisorNode(Node):
def prep(self, shared):
- """Prepare the prompt for LLM to process the question"""
- tool_info = shared["tool_info"]
- question = shared["question"]
+ """Get the current answer for evaluation."""
+ return shared["answer"]
+
+ def exec(self, answer):
+ """Check if the answer is valid or nonsensical."""
+ print(f" 🔍 Supervisor checking answer quality...")
- prompt = f"""
-### CONTEXT
-You are an assistant that can use tools via Model Context Protocol (MCP).
-
-### ACTION SPACE
-{tool_info}
-
-### TASK
-Answer this question: "{question}"
-
-## NEXT ACTION
-Analyze the question, extract any numbers or parameters, and decide which tool to use.
-Return your response in this format:
-
-```yaml
-thinking: |
- <your step-by-step reasoning about what the question is asking and what numbers to extract>
-tool: <name of the tool to use>
-reason: <why you chose this tool>
-parameters:
- <parameter_name>: <parameter_value>
- <parameter_name>: <parameter_value>
-```
-IMPORTANT:
+ # Check for obvious markers of the nonsense answers
+ nonsense_markers = [
+ "coffee break",
+ "purple unicorns",
+ "made up",
+ "42",
+ "Who knows?"
+ ]
+
+ # Check if the answer contains any nonsense markers
+ is_nonsense = any(marker in answer for marker in nonsense_markers)
+
+ if is_nonsense:
+ return {"valid": False, "reason": "Answer appears to be nonsensical or unhelpful"}
+ else:
+ return {"valid": True, "reason": "Answer appears to be legitimate"}
+
+ def post(self, shared, prep_res, exec_res):
+ """Decide whether to accept the answer or restart the process."""
+ if exec_res["valid"]:
+ print(f" ✅ Supervisor approved answer: {exec_res['reason']}")
```
This class is important because it defines how PocketFlow Tutorial: Minimal LLM Framework with Graph-Based Power implements the patterns covered in this chapter.
@@ -198,11 +196,11 @@ This class is important because it defines how PocketFlow Tutorial: Minimal LLM
```mermaid
flowchart TD
- A[GuardrailNode]
- B[LLMNode]
- C[GetToolsNode]
- D[DecideToolNode]
- E[ExecuteToolNode]
+ A[DecideAction]
+ B[SearchWeb]
+ C[UnreliableAnswerNode]
+ D[SupervisorNode]
+ E[colorize]
A --> B
B --> C
C --> D
diff --git a/tutorials/pocketflow-tutorial/08-production-usage-and-scaling.md b/tutorials/pocketflow-tutorial/08-production-usage-and-scaling.md
index b9df7bbb..8e2b5ec4 100644
--- a/tutorials/pocketflow-tutorial/08-production-usage-and-scaling.md
+++ b/tutorials/pocketflow-tutorial/08-production-usage-and-scaling.md
@@ -24,170 +24,164 @@ This chapter outlines how to run PocketFlow systems reliably in production conte
You now have an operations baseline for production PocketFlow workloads.
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `cookbook/pocketflow-structured-output/main.py`
+### `cookbook/pocketflow-rag/nodes.py`
-The `ResumeParserNode` class in [`cookbook/pocketflow-structured-output/main.py`](https://github.com/The-Pocket/PocketFlow/blob/HEAD/cookbook/pocketflow-structured-output/main.py) handles a key part of this chapter's functionality:
+The `EmbedQueryNode` class in [`cookbook/pocketflow-rag/nodes.py`](https://github.com/The-Pocket/PocketFlow/blob/HEAD/cookbook/pocketflow-rag/nodes.py) handles a key part of this chapter's functionality:
```py
-from utils import call_llm # Assumes utils.py with call_llm exists
-class ResumeParserNode(Node):
+# Nodes for the online flow
+class EmbedQueryNode(Node):
def prep(self, shared):
- """Return resume text and target skills from shared state."""
- return {
- "resume_text": shared["resume_text"],
- "target_skills": shared.get("target_skills", [])
- }
-
- def exec(self, prep_res):
- """Extract structured data from resume using prompt engineering.
- Requests YAML output with comments and skill indexes as a list.
- """
- resume_text = prep_res["resume_text"]
- target_skills = prep_res["target_skills"]
-
- # Format skills with indexes for the prompt
- skill_list_for_prompt = "\n".join([f"{i}: {skill}" for i, skill in enumerate(target_skills)])
-
- # Simplified Prompt focusing on key instructions and format
- prompt = f"""
-Analyze the resume below. Output ONLY the requested information in YAML format.
-
-**Resume:**
-```
-{resume_text}
-```
+ """Get query from shared store"""
+ return shared["query"]
+
+ def exec(self, query):
+ """Embed the query"""
+ print(f"🔍 Embedding query: {query}")
+ query_embedding = get_embedding(query)
+ return np.array([query_embedding], dtype=np.float32)
+
+ def post(self, shared, prep_res, exec_res):
+ """Store query embedding in shared store"""
+ shared["query_embedding"] = exec_res
+ return "default"
-**Target Skills (use these indexes):**
-```
-{skill_list_for_prompt}
+class RetrieveDocumentNode(Node):
+ def prep(self, shared):
+ """Get query embedding, index, and texts from shared store"""
+ return shared["query_embedding"], shared["index"], shared["texts"]
+
+ def exec(self, inputs):
+ """Search the index for similar documents"""
+ print("🔎 Searching for relevant documents...")
+ query_embedding, index, texts = inputs
+
+ # Search for the most similar document
+ distances, indices = index.search(query_embedding, k=1)
+
+ # Get the index of the most similar document
```
This class is important because it defines how PocketFlow Tutorial: Minimal LLM Framework with Graph-Based Power implements the patterns covered in this chapter.
-### `cookbook/pocketflow-a2a/nodes.py`
+### `cookbook/pocketflow-rag/nodes.py`
-The `DecideAction` class in [`cookbook/pocketflow-a2a/nodes.py`](https://github.com/The-Pocket/PocketFlow/blob/HEAD/cookbook/pocketflow-a2a/nodes.py) handles a key part of this chapter's functionality:
+The `RetrieveDocumentNode` class in [`cookbook/pocketflow-rag/nodes.py`](https://github.com/The-Pocket/PocketFlow/blob/HEAD/cookbook/pocketflow-rag/nodes.py) handles a key part of this chapter's functionality:
```py
-import yaml
+ return "default"
-class DecideAction(Node):
+class RetrieveDocumentNode(Node):
def prep(self, shared):
- """Prepare the context and question for the decision-making process."""
- # Get the current context (default to "No previous search" if none exists)
- context = shared.get("context", "No previous search")
- # Get the question from the shared store
- question = shared["question"]
- # Return both for the exec step
- return question, context
-
+ """Get query embedding, index, and texts from shared store"""
+ return shared["query_embedding"], shared["index"], shared["texts"]
+
def exec(self, inputs):
- """Call the LLM to decide whether to search or answer."""
- question, context = inputs
+ """Search the index for similar documents"""
+ print("🔎 Searching for relevant documents...")
+ query_embedding, index, texts = inputs
- print(f"🤔 Agent deciding what to do next...")
+ # Search for the most similar document
+ distances, indices = index.search(query_embedding, k=1)
- # Create a prompt to help the LLM decide what to do next with proper yaml formatting
- prompt = f"""
-### CONTEXT
-You are a research assistant that can search the web.
-Question: {question}
-Previous Research: {context}
-
-### ACTION SPACE
-[1] search
- Description: Look up more information on the web
- Parameters:
- - query (str): What to search for
-
-[2] answer
+ # Get the index of the most similar document
+ best_idx = indices[0][0]
+ distance = distances[0][0]
+
+ # Get the corresponding text
+ most_relevant_text = texts[best_idx]
+
+ return {
+ "text": most_relevant_text,
+ "index": best_idx,
+ "distance": distance
+ }
+
+ def post(self, shared, prep_res, exec_res):
+ """Store retrieved document in shared store"""
+ shared["retrieved_document"] = exec_res
+ print(f"📄 Retrieved document (index: {exec_res['index']}, distance: {exec_res['distance']:.4f})")
```
This class is important because it defines how PocketFlow Tutorial: Minimal LLM Framework with Graph-Based Power implements the patterns covered in this chapter.
-### `cookbook/pocketflow-a2a/nodes.py`
+### `cookbook/pocketflow-rag/nodes.py`
-The `SearchWeb` class in [`cookbook/pocketflow-a2a/nodes.py`](https://github.com/The-Pocket/PocketFlow/blob/HEAD/cookbook/pocketflow-a2a/nodes.py) handles a key part of this chapter's functionality:
+The `GenerateAnswerNode` class in [`cookbook/pocketflow-rag/nodes.py`](https://github.com/The-Pocket/PocketFlow/blob/HEAD/cookbook/pocketflow-rag/nodes.py) handles a key part of this chapter's functionality:
```py
- return exec_res["action"]
-
-class SearchWeb(Node):
+ return "default"
+
+class GenerateAnswerNode(Node):
def prep(self, shared):
- """Get the search query from the shared store."""
- return shared["search_query"]
-
- def exec(self, search_query):
- """Search the web for the given query."""
- # Call the search utility function
- print(f"🌐 Searching the web for: {search_query}")
- results = search_web(search_query)
- return results
+ """Get query, retrieved document, and any other context needed"""
+ return shared["query"], shared["retrieved_document"]
- def post(self, shared, prep_res, exec_res):
- """Save the search results and go back to the decision node."""
- # Add the search results to the context in the shared store
- previous = shared.get("context", "")
- shared["context"] = previous + "\n\nSEARCH: " + shared["search_query"] + "\nRESULTS: " + exec_res
+ def exec(self, inputs):
+ """Generate an answer using the LLM"""
+ query, retrieved_doc = inputs
- print(f"📚 Found information, analyzing results...")
+ prompt = f"""
+Briefly answer the following question based on the context provided:
+Question: {query}
+Context: {retrieved_doc['text']}
+Answer:
+"""
- # Always go back to the decision node after searching
- return "decide"
+ answer = call_llm(prompt)
+ return answer
+
+ def post(self, shared, prep_res, exec_res):
+ """Store generated answer in shared store"""
+ shared["generated_answer"] = exec_res
+ print("\n🤖 Generated Answer:")
+ print(exec_res)
+ return "default"
-class AnswerQuestion(Node):
- def prep(self, shared):
- """Get the question and context for answering."""
- return shared["question"], shared.get("context", "")
-
- def exec(self, inputs):
- """Call the LLM to generate a final answer."""
```
This class is important because it defines how PocketFlow Tutorial: Minimal LLM Framework with Graph-Based Power implements the patterns covered in this chapter.
-### `cookbook/pocketflow-a2a/nodes.py`
+### `cookbook/pocketflow-voice-chat/nodes.py`
-The `AnswerQuestion` class in [`cookbook/pocketflow-a2a/nodes.py`](https://github.com/The-Pocket/PocketFlow/blob/HEAD/cookbook/pocketflow-a2a/nodes.py) handles a key part of this chapter's functionality:
+The `CaptureAudioNode` class in [`cookbook/pocketflow-voice-chat/nodes.py`](https://github.com/The-Pocket/PocketFlow/blob/HEAD/cookbook/pocketflow-voice-chat/nodes.py) handles a key part of this chapter's functionality:
```py
- return "decide"
+from utils.text_to_speech import text_to_speech_api
-class AnswerQuestion(Node):
- def prep(self, shared):
- """Get the question and context for answering."""
- return shared["question"], shared.get("context", "")
-
- def exec(self, inputs):
- """Call the LLM to generate a final answer."""
- question, context = inputs
-
- print(f"✍️ Crafting final answer...")
-
- # Create a prompt for the LLM to answer the question
- prompt = f"""
-### CONTEXT
-Based on the following information, answer the question.
-Question: {question}
-Research: {context}
+class CaptureAudioNode(Node):
+ """Records audio input from the user using VAD."""
+ def exec(self, _): # prep_res is not used as per design
+ print("\nListening for your query...")
+ audio_data, sample_rate = record_audio()
+ if audio_data is None:
+ return None, None
+ return audio_data, sample_rate
-## YOUR ANSWER:
-Provide a comprehensive answer using the research results.
-"""
- # Call the LLM to generate an answer
- answer = call_llm(prompt)
- return answer
-
def post(self, shared, prep_res, exec_res):
- """Save the final answer and complete the flow."""
- # Save the answer in the shared store
- shared["answer"] = exec_res
-
+ audio_numpy_array, sample_rate = exec_res
+ if audio_numpy_array is None:
+ shared["user_audio_data"] = None
+ shared["user_audio_sample_rate"] = None
+ print("CaptureAudioNode: Failed to capture audio.")
+ return "end_conversation"
+
+ shared["user_audio_data"] = audio_numpy_array
+ shared["user_audio_sample_rate"] = sample_rate
+ print(f"Audio captured ({len(audio_numpy_array)/sample_rate:.2f}s), proceeding to STT.")
+
+class SpeechToTextNode(Node):
+ """Converts the recorded in-memory audio to text."""
+ def prep(self, shared):
+ user_audio_data = shared.get("user_audio_data")
+ user_audio_sample_rate = shared.get("user_audio_sample_rate")
+ if user_audio_data is None or user_audio_sample_rate is None:
+ print("SpeechToTextNode: No audio data to process.")
+ return None # Signal to skip exec
+ return user_audio_data, user_audio_sample_rate
```
This class is important because it defines how PocketFlow Tutorial: Minimal LLM Framework with Graph-Based Power implements the patterns covered in this chapter.
@@ -197,11 +191,11 @@ This class is important because it defines how PocketFlow Tutorial: Minimal LLM
```mermaid
flowchart TD
- A[ResumeParserNode]
- B[DecideAction]
- C[SearchWeb]
- D[AnswerQuestion]
- E[ValidatePayment]
+ A[EmbedQueryNode]
+ B[RetrieveDocumentNode]
+ C[GenerateAnswerNode]
+ D[CaptureAudioNode]
+ E[SpeechToTextNode]
A --> B
B --> C
C --> D
diff --git a/tutorials/pydantic-ai-tutorial/01-getting-started.md b/tutorials/pydantic-ai-tutorial/01-getting-started.md
index bfbbb538..f873695e 100644
--- a/tutorials/pydantic-ai-tutorial/01-getting-started.md
+++ b/tutorials/pydantic-ai-tutorial/01-getting-started.md
@@ -584,6 +584,19 @@ Under the hood, `Chapter 1: Getting Started with Pydantic AI` usually follows a
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## Architecture Overview
+
+```mermaid
+flowchart TD
+ A[User Input] --> B[PydanticAI Agent]
+ B --> C[LLM Provider]
+ C --> D[Raw Response]
+ D --> E[Pydantic Validation]
+ E --> F[Typed Result Object]
+ F --> G[Application Code]
+ E -->|Validation Error| H[Retry / Raise]
+```
+
## Source Walkthrough
Use the following upstream sources to verify implementation details while reading this chapter:
diff --git a/tutorials/pydantic-ai-tutorial/02-model-configuration.md b/tutorials/pydantic-ai-tutorial/02-model-configuration.md
index 83a8d708..78641be0 100644
--- a/tutorials/pydantic-ai-tutorial/02-model-configuration.md
+++ b/tutorials/pydantic-ai-tutorial/02-model-configuration.md
@@ -956,6 +956,20 @@ Under the hood, `Chapter 2: Advanced Model Configuration & Provider Setup` usual
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## Model Configuration Flow
+
+```mermaid
+flowchart LR
+ A[Provider String] --> B{Provider Router}
+ B --> C[openai:gpt-4o]
+ B --> D[anthropic:claude-3-5-sonnet]
+ B --> E[google:gemini-2.0-flash]
+ C --> F[HTTP Client]
+ D --> F
+ E --> F
+ F --> G[Model Response]
+```
+
## Source Walkthrough
Use the following upstream sources to verify implementation details while reading this chapter:
diff --git a/tutorials/pydantic-ai-tutorial/03-structured-outputs.md b/tutorials/pydantic-ai-tutorial/03-structured-outputs.md
index d8d553da..9bc9d679 100644
--- a/tutorials/pydantic-ai-tutorial/03-structured-outputs.md
+++ b/tutorials/pydantic-ai-tutorial/03-structured-outputs.md
@@ -734,6 +734,19 @@ Under the hood, `Chapter 3: Structured Outputs & Pydantic Models` usually follow
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## Structured Output Pipeline
+
+```mermaid
+flowchart TD
+ A[Pydantic Model Class] --> B[Agent result_type]
+ B --> C[LLM with Tool/JSON Mode]
+ C --> D[Raw JSON]
+ D --> E[model_validate]
+ E --> F{Valid?}
+ F -->|Yes| G[Typed Python Object]
+ F -->|No| H[ValidationError / Retry]
+```
+
## Source Walkthrough
Use the following upstream sources to verify implementation details while reading this chapter:
diff --git a/tutorials/pydantic-ai-tutorial/04-dependencies-tools.md b/tutorials/pydantic-ai-tutorial/04-dependencies-tools.md
index 962d6a80..04efba6e 100644
--- a/tutorials/pydantic-ai-tutorial/04-dependencies-tools.md
+++ b/tutorials/pydantic-ai-tutorial/04-dependencies-tools.md
@@ -1014,6 +1014,18 @@ Under the hood, `Chapter 4: Dependencies, Tools & External Integrations` usually
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## Dependency Injection and Tools
+
+```mermaid
+flowchart LR
+ A[Agent.run] --> B[Deps Context]
+ B --> C[@tool Functions]
+ C --> D[External Service Call]
+ D --> E[Tool Result]
+ E --> F[Back to LLM]
+ F --> G[Final Answer]
+```
+
## Source Walkthrough
Use the following upstream sources to verify implementation details while reading this chapter:
diff --git a/tutorials/pydantic-ai-tutorial/05-streaming-async.md b/tutorials/pydantic-ai-tutorial/05-streaming-async.md
index 1d4aa8ba..bcfd7182 100644
--- a/tutorials/pydantic-ai-tutorial/05-streaming-async.md
+++ b/tutorials/pydantic-ai-tutorial/05-streaming-async.md
@@ -789,6 +789,18 @@ Under the hood, `Chapter 5: Streaming Responses & Async Operations` usually foll
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## Streaming Architecture
+
+```mermaid
+flowchart TD
+ A[agent.run_stream] --> B[LLM Streaming Response]
+ B --> C[Partial Token Events]
+ C --> D[StreamedRunResult]
+ D --> E[stream_text Iterator]
+ E --> F[UI / Consumer]
+ D --> G[Final Validated Result]
+```
+
## Source Walkthrough
Use the following upstream sources to verify implementation details while reading this chapter:
diff --git a/tutorials/pydantic-ai-tutorial/06-error-handling.md b/tutorials/pydantic-ai-tutorial/06-error-handling.md
index ce0336c5..fbf0e63d 100644
--- a/tutorials/pydantic-ai-tutorial/06-error-handling.md
+++ b/tutorials/pydantic-ai-tutorial/06-error-handling.md
@@ -1093,6 +1093,21 @@ Under the hood, `Chapter 6: Error Handling, Retry Mechanisms & Recovery` usually
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## Error Handling Flow
+
+```mermaid
+flowchart LR
+ A[Agent Run] --> B{Error Type}
+ B --> C[ModelRetry]
+ B --> D[ValidationError]
+ B --> E[UnexpectedModelBehavior]
+ C --> F[Retry Loop]
+ D --> G[Re-prompt with Error Context]
+ E --> H[Raise to Caller]
+ F --> A
+ G --> A
+```
+
## Source Walkthrough
Use the following upstream sources to verify implementation details while reading this chapter:
diff --git a/tutorials/pydantic-ai-tutorial/07-advanced-patterns.md b/tutorials/pydantic-ai-tutorial/07-advanced-patterns.md
index bf51531b..a76c55d4 100644
--- a/tutorials/pydantic-ai-tutorial/07-advanced-patterns.md
+++ b/tutorials/pydantic-ai-tutorial/07-advanced-patterns.md
@@ -1007,6 +1007,20 @@ Under the hood, `Chapter 7: Advanced Patterns & Multi-Step Workflows` usually fo
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## Advanced Agent Patterns
+
+```mermaid
+flowchart TD
+ A[Complex Query] --> B[Orchestrator Agent]
+ B --> C[Sub-agent 1]
+ B --> D[Sub-agent 2]
+ C --> E[Structured Result 1]
+ D --> F[Structured Result 2]
+ E --> G[Final Agent]
+ F --> G
+ G --> H[Combined Typed Output]
+```
+
## Source Walkthrough
Use the following upstream sources to verify implementation details while reading this chapter:
diff --git a/tutorials/pydantic-ai-tutorial/08-production.md b/tutorials/pydantic-ai-tutorial/08-production.md
index 64501c0e..6eac99a0 100644
--- a/tutorials/pydantic-ai-tutorial/08-production.md
+++ b/tutorials/pydantic-ai-tutorial/08-production.md
@@ -1579,6 +1579,18 @@ Under the hood, `Chapter 8: Production Deployment & Scaling Pydantic AI Systems`
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## Production Deployment
+
+```mermaid
+flowchart LR
+ A[FastAPI App] --> B[PydanticAI Agent]
+ B --> C[LLM Provider]
+ B --> D[Logfire / Telemetry]
+ D --> E[Traces / Metrics]
+ A --> F[Structured API Response]
+ F --> G[Client]
+```
+
## Source Walkthrough
Use the following upstream sources to verify implementation details while reading this chapter:
diff --git a/tutorials/qwen-agent-tutorial/01-getting-started.md b/tutorials/qwen-agent-tutorial/01-getting-started.md
index 9f993b66..64c0f644 100644
--- a/tutorials/qwen-agent-tutorial/01-getting-started.md
+++ b/tutorials/qwen-agent-tutorial/01-getting-started.md
@@ -38,92 +38,8 @@ You now have a working Qwen-Agent baseline.
Next: [Chapter 2: Framework Architecture and Core Modules](02-framework-architecture-and-core-modules.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `examples/function_calling.py`
-
-The `get_current_weather` function in [`examples/function_calling.py`](https://github.com/QwenLM/Qwen-Agent/blob/HEAD/examples/function_calling.py) handles a key part of this chapter's functionality:
-
-```py
-# Example dummy function hard coded to return the same weather
-# In production, this could be your backend API or an external API
-def get_current_weather(location, unit='fahrenheit'):
- """Get the current weather in a given location"""
- if 'tokyo' in location.lower():
- return json.dumps({'location': 'Tokyo', 'temperature': '10', 'unit': 'celsius'})
- elif 'san francisco' in location.lower():
- return json.dumps({'location': 'San Francisco', 'temperature': '72', 'unit': 'fahrenheit'})
- elif 'paris' in location.lower():
- return json.dumps({'location': 'Paris', 'temperature': '22', 'unit': 'celsius'})
- else:
- return json.dumps({'location': location, 'temperature': 'unknown'})
-
-
-def test(fncall_prompt_type: str = 'qwen'):
- llm = get_chat_model({
- # Use the model service provided by DashScope:
- 'model': 'qwen-plus-latest',
- 'model_server': 'dashscope',
- 'api_key': os.getenv('DASHSCOPE_API_KEY'),
- 'generate_cfg': {
- 'fncall_prompt_type': fncall_prompt_type
- },
-
- # Use the OpenAI-compatible model service provided by DashScope:
- # 'model': 'qwen2.5-72b-instruct',
- # 'model_server': 'https://dashscope.aliyuncs.com/compatible-mode/v1',
- # 'api_key': os.getenv('DASHSCOPE_API_KEY'),
-
- # Use the model service provided by Together.AI:
- # 'model': 'Qwen/qwen2.5-7b-instruct',
- # 'model_server': 'https://api.together.xyz', # api_base
-```
-
-This function is important because it defines how Qwen-Agent Tutorial: Tool-Enabled Agent Framework with MCP, RAG, and Multi-Modal Workflows implements the patterns covered in this chapter.
-
-### `examples/function_calling.py`
-
-The `test` function in [`examples/function_calling.py`](https://github.com/QwenLM/Qwen-Agent/blob/HEAD/examples/function_calling.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def test(fncall_prompt_type: str = 'qwen'):
- llm = get_chat_model({
- # Use the model service provided by DashScope:
- 'model': 'qwen-plus-latest',
- 'model_server': 'dashscope',
- 'api_key': os.getenv('DASHSCOPE_API_KEY'),
- 'generate_cfg': {
- 'fncall_prompt_type': fncall_prompt_type
- },
-
- # Use the OpenAI-compatible model service provided by DashScope:
- # 'model': 'qwen2.5-72b-instruct',
- # 'model_server': 'https://dashscope.aliyuncs.com/compatible-mode/v1',
- # 'api_key': os.getenv('DASHSCOPE_API_KEY'),
-
- # Use the model service provided by Together.AI:
- # 'model': 'Qwen/qwen2.5-7b-instruct',
- # 'model_server': 'https://api.together.xyz', # api_base
- # 'api_key': os.getenv('TOGETHER_API_KEY'),
-
- # Use your own model service compatible with OpenAI API:
- # 'model': 'Qwen/qwen2.5-7b-instruct',
- # 'model_server': 'http://localhost:8000/v1', # api_base
- # 'api_key': 'EMPTY',
- })
-
- # Step 1: send the conversation and available functions to the model
- messages = [{'role': 'user', 'content': "What's the weather like in San Francisco?"}]
- functions = [{
- 'name': 'get_current_weather',
-```
-
-This function is important because it defines how Qwen-Agent Tutorial: Tool-Enabled Agent Framework with MCP, RAG, and Multi-Modal Workflows implements the patterns covered in this chapter.
-
### `setup.py`
The `get_version` function in [`setup.py`](https://github.com/QwenLM/Qwen-Agent/blob/HEAD/setup.py) handles a key part of this chapter's functionality:
@@ -206,16 +122,98 @@ setup(
This function is important because it defines how Qwen-Agent Tutorial: Tool-Enabled Agent Framework with MCP, RAG, and Multi-Modal Workflows implements the patterns covered in this chapter.
+### `qwen_agent/agent.py`
+
+The `Agent` class in [`qwen_agent/agent.py`](https://github.com/QwenLM/Qwen-Agent/blob/HEAD/qwen_agent/agent.py) handles a key part of this chapter's functionality:
+
+```py
+
+
+class Agent(ABC):
+ """A base class for Agent.
+
+ An agent can receive messages and provide response by LLM or Tools.
+ Different agents have distinct workflows for processing messages and generating responses in the `_run` method.
+ """
+
+ def __init__(self,
+ function_list: Optional[List[Union[str, Dict, BaseTool]]] = None,
+ llm: Optional[Union[dict, BaseChatModel]] = None,
+ system_message: Optional[str] = DEFAULT_SYSTEM_MESSAGE,
+ name: Optional[str] = None,
+ description: Optional[str] = None,
+ **kwargs):
+ """Initialization the agent.
+
+ Args:
+ function_list: One list of tool name, tool configuration or Tool object,
+ such as 'code_interpreter', {'name': 'code_interpreter', 'timeout': 10}, or CodeInterpreter().
+ llm: The LLM model configuration or LLM model object.
+ Set the configuration as {'model': '', 'api_key': '', 'model_server': ''}.
+ system_message: The specified system message for LLM chat.
+ name: The name of this agent.
+ description: The description of this agent, which will be used for multi_agent.
+ """
+ if isinstance(llm, dict):
+ self.llm = get_chat_model(llm)
+ else:
+ self.llm = llm
+ self.extra_generate_cfg: dict = {}
+```
+
+This class is important because it defines how Qwen-Agent Tutorial: Tool-Enabled Agent Framework with MCP, RAG, and Multi-Modal Workflows implements the patterns covered in this chapter.
+
+### `qwen_agent/agent.py`
+
+The `for` class in [`qwen_agent/agent.py`](https://github.com/QwenLM/Qwen-Agent/blob/HEAD/qwen_agent/agent.py) handles a key part of this chapter's functionality:
+
+```py
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import copy
+import json
+import traceback
+from abc import ABC, abstractmethod
+from typing import Dict, Iterator, List, Optional, Tuple, Union
+
+from qwen_agent.llm import get_chat_model
+from qwen_agent.llm.base import BaseChatModel
+from qwen_agent.llm.schema import CONTENT, DEFAULT_SYSTEM_MESSAGE, ROLE, SYSTEM, ContentItem, Message
+from qwen_agent.log import logger
+from qwen_agent.tools import TOOL_REGISTRY, BaseTool, MCPManager
+from qwen_agent.tools.base import ToolServiceError
+from qwen_agent.tools.simple_doc_parser import DocParserError
+from qwen_agent.utils.utils import has_chinese_messages, merge_generate_cfgs
+
+
+class Agent(ABC):
+ """A base class for Agent.
+
+ An agent can receive messages and provide response by LLM or Tools.
+ Different agents have distinct workflows for processing messages and generating responses in the `_run` method.
+ """
+
+ def __init__(self,
+ function_list: Optional[List[Union[str, Dict, BaseTool]]] = None,
+ llm: Optional[Union[dict, BaseChatModel]] = None,
+ system_message: Optional[str] = DEFAULT_SYSTEM_MESSAGE,
+```
+
+This class is important because it defines how Qwen-Agent Tutorial: Tool-Enabled Agent Framework with MCP, RAG, and Multi-Modal Workflows implements the patterns covered in this chapter.
+
## How These Components Connect
```mermaid
flowchart TD
- A[get_current_weather]
- B[test]
- C[get_version]
- D[read_description]
- E[Agent]
+ A[get_version]
+ B[read_description]
+ C[Agent]
+ D[for]
+ E[needs]
A --> B
B --> C
C --> D
diff --git a/tutorials/qwen-agent-tutorial/02-framework-architecture-and-core-modules.md b/tutorials/qwen-agent-tutorial/02-framework-architecture-and-core-modules.md
index 7a8d8d64..3a646c6d 100644
--- a/tutorials/qwen-agent-tutorial/02-framework-architecture-and-core-modules.md
+++ b/tutorials/qwen-agent-tutorial/02-framework-architecture-and-core-modules.md
@@ -39,94 +39,10 @@ You now have a reliable mental model for Qwen-Agent framework internals.
Next: [Chapter 3: Model Service and Runtime Strategy](03-model-service-and-runtime-strategy.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `examples/group_chat_demo.py`
-The `init_agent_service_create` function in [`examples/group_chat_demo.py`](https://github.com/QwenLM/Qwen-Agent/blob/HEAD/examples/group_chat_demo.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def init_agent_service_create():
- llm_cfg = {'model': 'qwen-max'}
- bot = GroupChatCreator(llm=llm_cfg)
- return bot
-
-
-# =========================================================
-# Below is the gradio service: front-end and back-end logic
-# =========================================================
-
-app_global_para = {
- 'messages': [],
- 'messages_create': [],
- 'is_first_upload': False,
- 'uploaded_file': '',
- 'user_interrupt': True
-}
-
-# Initialized group chat configuration
-CFGS = {
- 'background':
- '一个陌生人互帮互助群聊',
- 'agents': [
- {
- 'name': '小塘',
- 'description': '一个勤劳的打工人，每天沉迷工作，日渐消瘦。（这是一个真实用户）',
- 'is_human': True # mark this as a real person
- },
- {
- 'name': '甄嬛',
-```
-
-This function is important because it defines how Qwen-Agent Tutorial: Tool-Enabled Agent Framework with MCP, RAG, and Multi-Modal Workflows implements the patterns covered in this chapter.
-
-### `examples/group_chat_demo.py`
-
-The `app` function in [`examples/group_chat_demo.py`](https://github.com/QwenLM/Qwen-Agent/blob/HEAD/examples/group_chat_demo.py) handles a key part of this chapter's functionality:
-
-```py
-# http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-
-"""A group chat gradio demo"""
-import json
-
-import json5
-
-from qwen_agent.agents import GroupChat, GroupChatCreator
-from qwen_agent.agents.user_agent import PENDING_USER_INPUT
-from qwen_agent.gui.gradio_dep import gr, mgr, ms
-from qwen_agent.llm.schema import ContentItem, Message
-
-
-def init_agent_service(cfgs):
- llm_cfg = {'model': 'qwen-max'}
- bot = GroupChat(agents=cfgs, llm=llm_cfg)
- return bot
-
-
-def init_agent_service_create():
- llm_cfg = {'model': 'qwen-max'}
- bot = GroupChatCreator(llm=llm_cfg)
- return bot
-
-
-# =========================================================
-```
-
-This function is important because it defines how Qwen-Agent Tutorial: Tool-Enabled Agent Framework with MCP, RAG, and Multi-Modal Workflows implements the patterns covered in this chapter.
-
-### `examples/group_chat_demo.py`
-
The `test` function in [`examples/group_chat_demo.py`](https://github.com/QwenLM/Qwen-Agent/blob/HEAD/examples/group_chat_demo.py) handles a key part of this chapter's functionality:
```py
@@ -207,16 +123,98 @@ def app_create(history, now_cfgs):
This function is important because it defines how Qwen-Agent Tutorial: Tool-Enabled Agent Framework with MCP, RAG, and Multi-Modal Workflows implements the patterns covered in this chapter.
+### `examples/group_chat_demo.py`
+
+The `get_name_of_current_user` function in [`examples/group_chat_demo.py`](https://github.com/QwenLM/Qwen-Agent/blob/HEAD/examples/group_chat_demo.py) handles a key part of this chapter's functionality:
+
+```py
+
+
+def get_name_of_current_user(cfgs):
+ for agent in cfgs['agents']:
+ if 'is_human' in agent and agent['is_human']:
+ return agent['name']
+ return 'user'
+
+
+def add_text(text, cfgs):
+ app_global_para['user_interrupt'] = True
+ content = [ContentItem(text=text)]
+ if app_global_para['uploaded_file'] and app_global_para['is_first_upload']:
+ app_global_para['is_first_upload'] = False # only send file when first upload
+ content.append(ContentItem(file=app_global_para['uploaded_file']))
+ app_global_para['messages'].append(
+ Message('user', content=content, name=get_name_of_current_user(json5.loads(cfgs))))
+
+ return _get_display_history_from_message(), None
+
+
+def chat_clear():
+ app_global_para['messages'] = []
+ return None
+
+
+def chat_clear_create():
+ app_global_para['messages_create'] = []
+ return None, None
+
+
+def add_file(file):
+```
+
+This function is important because it defines how Qwen-Agent Tutorial: Tool-Enabled Agent Framework with MCP, RAG, and Multi-Modal Workflows implements the patterns covered in this chapter.
+
+### `examples/group_chat_demo.py`
+
+The `add_text` function in [`examples/group_chat_demo.py`](https://github.com/QwenLM/Qwen-Agent/blob/HEAD/examples/group_chat_demo.py) handles a key part of this chapter's functionality:
+
+```py
+
+
+def add_text(text, cfgs):
+ app_global_para['user_interrupt'] = True
+ content = [ContentItem(text=text)]
+ if app_global_para['uploaded_file'] and app_global_para['is_first_upload']:
+ app_global_para['is_first_upload'] = False # only send file when first upload
+ content.append(ContentItem(file=app_global_para['uploaded_file']))
+ app_global_para['messages'].append(
+ Message('user', content=content, name=get_name_of_current_user(json5.loads(cfgs))))
+
+ return _get_display_history_from_message(), None
+
+
+def chat_clear():
+ app_global_para['messages'] = []
+ return None
+
+
+def chat_clear_create():
+ app_global_para['messages_create'] = []
+ return None, None
+
+
+def add_file(file):
+ app_global_para['uploaded_file'] = file.name
+ app_global_para['is_first_upload'] = True
+ return file.name
+
+
+def add_text_create(history, text):
+ history = history + [(text, None)]
+```
+
+This function is important because it defines how Qwen-Agent Tutorial: Tool-Enabled Agent Framework with MCP, RAG, and Multi-Modal Workflows implements the patterns covered in this chapter.
+
## How These Components Connect
```mermaid
flowchart TD
- A[init_agent_service_create]
- B[app]
- C[test]
- D[app_create]
- E[get_name_of_current_user]
+ A[test]
+ B[app_create]
+ C[get_name_of_current_user]
+ D[add_text]
+ E[chat_clear]
A --> B
B --> C
C --> D
diff --git a/tutorials/qwen-agent-tutorial/03-model-service-and-runtime-strategy.md b/tutorials/qwen-agent-tutorial/03-model-service-and-runtime-strategy.md
index 487ffae2..ac59f36b 100644
--- a/tutorials/qwen-agent-tutorial/03-model-service-and-runtime-strategy.md
+++ b/tutorials/qwen-agent-tutorial/03-model-service-and-runtime-strategy.md
@@ -38,8 +38,6 @@ You now can pick model service and parser strategies with fewer integration surp
Next: [Chapter 4: Tool Calling and MCP Integration](04-tool-calling-and-mcp-integration.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `examples/qwen2vl_assistant_tooluse.py`
diff --git a/tutorials/qwen-agent-tutorial/04-tool-calling-and-mcp-integration.md b/tutorials/qwen-agent-tutorial/04-tool-calling-and-mcp-integration.md
index b8c86726..f7c36d52 100644
--- a/tutorials/qwen-agent-tutorial/04-tool-calling-and-mcp-integration.md
+++ b/tutorials/qwen-agent-tutorial/04-tool-calling-and-mcp-integration.md
@@ -38,8 +38,6 @@ You now have a practical model for tool + MCP integration in Qwen-Agent.
Next: [Chapter 5: Memory, RAG, and Long-Context Workflows](05-memory-rag-and-long-context-workflows.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `qwen_server/workstation_server.py`
diff --git a/tutorials/qwen-agent-tutorial/05-memory-rag-and-long-context-workflows.md b/tutorials/qwen-agent-tutorial/05-memory-rag-and-long-context-workflows.md
index 5df050dd..b2e37464 100644
--- a/tutorials/qwen-agent-tutorial/05-memory-rag-and-long-context-workflows.md
+++ b/tutorials/qwen-agent-tutorial/05-memory-rag-and-long-context-workflows.md
@@ -38,160 +38,163 @@ You now can design Qwen-Agent workflows for high-context and document-heavy work
Next: [Chapter 6: Application Patterns and Safety Boundaries](06-application-patterns-and-safety-boundaries.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `examples/assistant_qwen3.5.py`
+### `qwen_server/database_server.py`
-The `test` function in [`examples/assistant_qwen3.5.py`](https://github.com/QwenLM/Qwen-Agent/blob/HEAD/examples/assistant_qwen3.5.py) handles a key part of this chapter's functionality:
+The `web_listening` function in [`qwen_server/database_server.py`](https://github.com/QwenLM/Qwen-Agent/blob/HEAD/qwen_server/database_server.py) handles a key part of this chapter's functionality:
```py
+@app.post('/endpoint')
+async def web_listening(request: Request):
+ data = await request.json()
+ msg_type = data['task']
-def test(query: str = 'What time is it?'):
- # Define the agent
- bot = init_agent_service()
-
- # Chat
- messages = [{'role': 'user', 'content': query}]
- response_plain_text = ''
- for response in bot.run(messages=messages):
- response_plain_text = typewriter_print(response, response_plain_text)
+ if msg_type == 'change_checkbox':
+ rsp = change_checkbox_state(data['ckid'])
+ elif msg_type == 'cache':
+ cache_obj = multiprocessing.Process(target=cache_page, kwargs=data)
+ cache_obj.start()
+ # rsp = cache_data(data, cache_file)
+ rsp = 'caching'
+ elif msg_type == 'pop_url':
+ # What a misleading name! pop_url actually means add_url. pop is referring to the pop_up ui.
+ rsp = update_pop_url(data['url'])
+ else:
+ raise NotImplementedError
+ return JSONResponse(content=rsp)
-def app_tui():
- # Define the agent
- bot = init_agent_service()
-
- # Chat
- messages = []
- while True:
- query = input('user question: ')
- messages.append({'role': 'user', 'content': query})
- response = []
- response_plain_text = ''
- for response in bot.run(messages=messages):
- response_plain_text = typewriter_print(response, response_plain_text)
- messages.extend(response)
+if __name__ == '__main__':
+ uvicorn.run(app='database_server:app',
+ host=server_config.server.server_host,
+ port=server_config.server.fast_api_port)
-def app_gui():
- # Define the agent
- bot = init_agent_service()
```
This function is important because it defines how Qwen-Agent Tutorial: Tool-Enabled Agent Framework with MCP, RAG, and Multi-Modal Workflows implements the patterns covered in this chapter.
-### `examples/assistant_qwen3.5.py`
+### `qwen_server/assistant_server.py`
-The `app_tui` function in [`examples/assistant_qwen3.5.py`](https://github.com/QwenLM/Qwen-Agent/blob/HEAD/examples/assistant_qwen3.5.py) handles a key part of this chapter's functionality:
+The `add_text` function in [`qwen_server/assistant_server.py`](https://github.com/QwenLM/Qwen-Agent/blob/HEAD/qwen_server/assistant_server.py) handles a key part of this chapter's functionality:
```py
-def app_tui():
- # Define the agent
- bot = init_agent_service()
-
- # Chat
- messages = []
- while True:
- query = input('user question: ')
- messages.append({'role': 'user', 'content': query})
- response = []
- response_plain_text = ''
- for response in bot.run(messages=messages):
- response_plain_text = typewriter_print(response, response_plain_text)
- messages.extend(response)
-
-
-def app_gui():
- # Define the agent
- bot = init_agent_service()
- chatbot_config = {
- 'prompt.suggestions': [
- 'Help me organize my desktop.',
- 'Develop a dog website and save it on the desktop',
- ]
- }
- WebUI(
- bot,
- chatbot_config=chatbot_config,
- ).run()
+def add_text(history, text):
+ history = history + [(text, None)]
+ return history, gr.update(value='', interactive=False)
-```
-This function is important because it defines how Qwen-Agent Tutorial: Tool-Enabled Agent Framework with MCP, RAG, and Multi-Modal Workflows implements the patterns covered in this chapter.
+def rm_text(history):
+ if not history:
+ gr.Warning('No input content!')
+ elif not history[-1][1]:
+ return history, gr.update(value='', interactive=False)
+ else:
+ history = history[:-1] + [(history[-1][0], None)]
+ return history, gr.update(value='', interactive=False)
-### `examples/assistant_qwen3.5.py`
-The `app_gui` function in [`examples/assistant_qwen3.5.py`](https://github.com/QwenLM/Qwen-Agent/blob/HEAD/examples/assistant_qwen3.5.py) handles a key part of this chapter's functionality:
+def set_url():
+ lines = []
+ if not os.path.exists(cache_file_popup_url):
+ # Only able to remind the situation of first browsing failure
+ gr.Error('Oops, it seems that the page cannot be opened due to network issues.')
-```py
+ for line in jsonlines.open(cache_file_popup_url):
+ lines.append(line)
+ logger.info('The current access page is: ' + lines[-1]['url'])
+ return lines[-1]['url']
-def app_gui():
- # Define the agent
- bot = init_agent_service()
- chatbot_config = {
- 'prompt.suggestions': [
- 'Help me organize my desktop.',
- 'Develop a dog website and save it on the desktop',
- ]
- }
- WebUI(
- bot,
- chatbot_config=chatbot_config,
- ).run()
+def bot(history):
+ page_url = set_url()
+ if not history:
+```
+
+This function is important because it defines how Qwen-Agent Tutorial: Tool-Enabled Agent Framework with MCP, RAG, and Multi-Modal Workflows implements the patterns covered in this chapter.
+### `qwen_server/assistant_server.py`
+
+The `rm_text` function in [`qwen_server/assistant_server.py`](https://github.com/QwenLM/Qwen-Agent/blob/HEAD/qwen_server/assistant_server.py) handles a key part of this chapter's functionality:
+
+```py
-if __name__ == '__main__':
- # test()
- # app_tui()
- app_gui()
+def rm_text(history):
+ if not history:
+ gr.Warning('No input content!')
+ elif not history[-1][1]:
+ return history, gr.update(value='', interactive=False)
+ else:
+ history = history[:-1] + [(history[-1][0], None)]
+ return history, gr.update(value='', interactive=False)
+
+
+def set_url():
+ lines = []
+ if not os.path.exists(cache_file_popup_url):
+ # Only able to remind the situation of first browsing failure
+ gr.Error('Oops, it seems that the page cannot be opened due to network issues.')
+
+ for line in jsonlines.open(cache_file_popup_url):
+ lines.append(line)
+ logger.info('The current access page is: ' + lines[-1]['url'])
+ return lines[-1]['url']
+
+
+def bot(history):
+ page_url = set_url()
+ if not history:
+ yield history
+ else:
+ messages = [{'role': 'user', 'content': [{'text': history[-1][0]}, {'file': page_url}]}]
+ history[-1][1] = ''
+ try:
```
This function is important because it defines how Qwen-Agent Tutorial: Tool-Enabled Agent Framework with MCP, RAG, and Multi-Modal Workflows implements the patterns covered in this chapter.
-### `examples/assistant_qwen3_coder.py`
+### `qwen_server/assistant_server.py`
-The `init_agent_service` function in [`examples/assistant_qwen3_coder.py`](https://github.com/QwenLM/Qwen-Agent/blob/HEAD/examples/assistant_qwen3_coder.py) handles a key part of this chapter's functionality:
+The `set_url` function in [`qwen_server/assistant_server.py`](https://github.com/QwenLM/Qwen-Agent/blob/HEAD/qwen_server/assistant_server.py) handles a key part of this chapter's functionality:
```py
-def init_agent_service():
- llm_cfg = {
- # Use the model service provided by DashScope:
- 'model': 'qwen3-coder-480b-a35b-instruct',
- 'model_type': 'qwen_dashscope',
- 'generate_cfg': {
- # Using the API's native tool call interface
- 'use_raw_api': True,
- 'max_input_tokens': 200000
- },
- }
- # llm_cfg = {
- # # Use the OpenAI-compatible model service provided by DashScope:
- # 'model': 'qwen3-coder-480b-a35b-instruct',
- # 'model_server': 'https://dashscope.aliyuncs.com/compatible-mode/v1',
- # 'api_key': os.getenv('DASHSCOPE_API_KEY'),
- # 'generate_cfg': {
- # # Using the API's native tool call interface
- # 'use_raw_api': True,
- # 'max_input_tokens': 200000
- # },
- # }
-
- tools = [
- {
- 'mcpServers': { # You can specify the MCP configuration file
- 'time': {
- 'command': 'uvx',
- 'args': ['mcp-server-time', '--local-timezone=Asia/Shanghai']
- },
+def set_url():
+ lines = []
+ if not os.path.exists(cache_file_popup_url):
+ # Only able to remind the situation of first browsing failure
+ gr.Error('Oops, it seems that the page cannot be opened due to network issues.')
+
+ for line in jsonlines.open(cache_file_popup_url):
+ lines.append(line)
+ logger.info('The current access page is: ' + lines[-1]['url'])
+ return lines[-1]['url']
+
+
+def bot(history):
+ page_url = set_url()
+ if not history:
+ yield history
+ else:
+ messages = [{'role': 'user', 'content': [{'text': history[-1][0]}, {'file': page_url}]}]
+ history[-1][1] = ''
+ try:
+ response = assistant.run(messages=messages, max_ref_token=server_config.server.max_ref_token)
+ for rsp in response:
+ if rsp:
+ history[-1][1] = rsp[-1]['content']
+ yield history
+ except ModelServiceError as ex:
+ history[-1][1] = str(ex)
+ yield history
+ except Exception as ex:
+ raise ValueError(ex)
```
This function is important because it defines how Qwen-Agent Tutorial: Tool-Enabled Agent Framework with MCP, RAG, and Multi-Modal Workflows implements the patterns covered in this chapter.
@@ -201,11 +204,11 @@ This function is important because it defines how Qwen-Agent Tutorial: Tool-Enab
```mermaid
flowchart TD
- A[test]
- B[app_tui]
- C[app_gui]
- D[init_agent_service]
- E[test]
+ A[web_listening]
+ B[add_text]
+ C[rm_text]
+ D[set_url]
+ E[bot]
A --> B
B --> C
C --> D
diff --git a/tutorials/qwen-agent-tutorial/06-application-patterns-and-safety-boundaries.md b/tutorials/qwen-agent-tutorial/06-application-patterns-and-safety-boundaries.md
index 9662fc0e..982a7038 100644
--- a/tutorials/qwen-agent-tutorial/06-application-patterns-and-safety-boundaries.md
+++ b/tutorials/qwen-agent-tutorial/06-application-patterns-and-safety-boundaries.md
@@ -38,173 +38,161 @@ You now have a safer application-design lens for Qwen-Agent deployments.
Next: [Chapter 7: Benchmarking and DeepPlanning Evaluation](07-benchmarking-and-deepplanning-evaluation.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `examples/qwen2vl_function_calling.py`
+### `examples/assistant_qwen3.5.py`
-The `test` function in [`examples/qwen2vl_function_calling.py`](https://github.com/QwenLM/Qwen-Agent/blob/HEAD/examples/qwen2vl_function_calling.py) handles a key part of this chapter's functionality:
+The `test` function in [`examples/assistant_qwen3.5.py`](https://github.com/QwenLM/Qwen-Agent/blob/HEAD/examples/assistant_qwen3.5.py) handles a key part of this chapter's functionality:
```py
-def test():
- # Config for the model
- llm_cfg_oai = {
- # Using Qwen2-VL deployed at any openai-compatible service such as vLLM:
- # 'model_type': 'qwenvl_oai',
- # 'model': 'Qwen2-VL-7B-Instruct',
- # 'model_server': 'http://localhost:8000/v1', # api_base
- # 'api_key': 'EMPTY',
-
- # Using Qwen2-VL provided by Alibaba Cloud DashScope's openai-compatible service:
- # 'model_type': 'qwenvl_oai',
- # 'model': 'qwen-vl-max-0809',
- # 'model_server': 'https://dashscope.aliyuncs.com/compatible-mode/v1',
- # 'api_key': os.getenv('DASHSCOPE_API_KEY'),
-
- # Using Qwen2-VL provided by Alibaba Cloud DashScope:
- 'model_type': 'qwenvl_dashscope',
- 'model': 'qwen-vl-max-0809',
- 'api_key': os.getenv('DASHSCOPE_API_KEY'),
- 'generate_cfg': {
- 'max_retries': 10,
- 'fncall_prompt_type': 'qwen'
- }
- }
- llm = get_chat_model(llm_cfg_oai)
+def test(query: str = 'What time is it?'):
+ # Define the agent
+ bot = init_agent_service()
+
+ # Chat
+ messages = [{'role': 'user', 'content': query}]
+ response_plain_text = ''
+ for response in bot.run(messages=messages):
+ response_plain_text = typewriter_print(response, response_plain_text)
+
+
+def app_tui():
+ # Define the agent
+ bot = init_agent_service()
- # Initial conversation
- messages = [{
- 'role':
- 'user',
+ # Chat
+ messages = []
+ while True:
+ query = input('user question: ')
+ messages.append({'role': 'user', 'content': query})
+ response = []
+ response_plain_text = ''
+ for response in bot.run(messages=messages):
+ response_plain_text = typewriter_print(response, response_plain_text)
+ messages.extend(response)
+
+
+def app_gui():
+ # Define the agent
+ bot = init_agent_service()
```
This function is important because it defines how Qwen-Agent Tutorial: Tool-Enabled Agent Framework with MCP, RAG, and Multi-Modal Workflows implements the patterns covered in this chapter.
-### `qwen_server/assistant_server.py`
+### `examples/assistant_qwen3.5.py`
-The `add_text` function in [`qwen_server/assistant_server.py`](https://github.com/QwenLM/Qwen-Agent/blob/HEAD/qwen_server/assistant_server.py) handles a key part of this chapter's functionality:
+The `app_tui` function in [`examples/assistant_qwen3.5.py`](https://github.com/QwenLM/Qwen-Agent/blob/HEAD/examples/assistant_qwen3.5.py) handles a key part of this chapter's functionality:
```py
-def add_text(history, text):
- history = history + [(text, None)]
- return history, gr.update(value='', interactive=False)
+def app_tui():
+ # Define the agent
+ bot = init_agent_service()
+
+ # Chat
+ messages = []
+ while True:
+ query = input('user question: ')
+ messages.append({'role': 'user', 'content': query})
+ response = []
+ response_plain_text = ''
+ for response in bot.run(messages=messages):
+ response_plain_text = typewriter_print(response, response_plain_text)
+ messages.extend(response)
+
+
+def app_gui():
+ # Define the agent
+ bot = init_agent_service()
+ chatbot_config = {
+ 'prompt.suggestions': [
+ 'Help me organize my desktop.',
+ 'Develop a dog website and save it on the desktop',
+ ]
+ }
+ WebUI(
+ bot,
+ chatbot_config=chatbot_config,
+ ).run()
+```
-def rm_text(history):
- if not history:
- gr.Warning('No input content!')
- elif not history[-1][1]:
- return history, gr.update(value='', interactive=False)
- else:
- history = history[:-1] + [(history[-1][0], None)]
- return history, gr.update(value='', interactive=False)
+This function is important because it defines how Qwen-Agent Tutorial: Tool-Enabled Agent Framework with MCP, RAG, and Multi-Modal Workflows implements the patterns covered in this chapter.
+### `examples/assistant_qwen3.5.py`
-def set_url():
- lines = []
- if not os.path.exists(cache_file_popup_url):
- # Only able to remind the situation of first browsing failure
- gr.Error('Oops, it seems that the page cannot be opened due to network issues.')
+The `app_gui` function in [`examples/assistant_qwen3.5.py`](https://github.com/QwenLM/Qwen-Agent/blob/HEAD/examples/assistant_qwen3.5.py) handles a key part of this chapter's functionality:
+
+```py
+
+
+def app_gui():
+ # Define the agent
+ bot = init_agent_service()
+ chatbot_config = {
+ 'prompt.suggestions': [
+ 'Help me organize my desktop.',
+ 'Develop a dog website and save it on the desktop',
+ ]
+ }
+ WebUI(
+ bot,
+ chatbot_config=chatbot_config,
+ ).run()
- for line in jsonlines.open(cache_file_popup_url):
- lines.append(line)
- logger.info('The current access page is: ' + lines[-1]['url'])
- return lines[-1]['url']
+if __name__ == '__main__':
+ # test()
+ # app_tui()
+ app_gui()
-def bot(history):
- page_url = set_url()
- if not history:
```
This function is important because it defines how Qwen-Agent Tutorial: Tool-Enabled Agent Framework with MCP, RAG, and Multi-Modal Workflows implements the patterns covered in this chapter.
-### `qwen_server/assistant_server.py`
+### `examples/visual_storytelling.py`
-The `rm_text` function in [`qwen_server/assistant_server.py`](https://github.com/QwenLM/Qwen-Agent/blob/HEAD/qwen_server/assistant_server.py) handles a key part of this chapter's functionality:
+The `VisualStorytelling` class in [`examples/visual_storytelling.py`](https://github.com/QwenLM/Qwen-Agent/blob/HEAD/examples/visual_storytelling.py) handles a key part of this chapter's functionality:
```py
-def rm_text(history):
- if not history:
- gr.Warning('No input content!')
- elif not history[-1][1]:
- return history, gr.update(value='', interactive=False)
- else:
- history = history[:-1] + [(history[-1][0], None)]
- return history, gr.update(value='', interactive=False)
-
-
-def set_url():
- lines = []
- if not os.path.exists(cache_file_popup_url):
- # Only able to remind the situation of first browsing failure
- gr.Error('Oops, it seems that the page cannot be opened due to network issues.')
-
- for line in jsonlines.open(cache_file_popup_url):
- lines.append(line)
- logger.info('The current access page is: ' + lines[-1]['url'])
- return lines[-1]['url']
-
-
-def bot(history):
- page_url = set_url()
- if not history:
- yield history
- else:
- messages = [{'role': 'user', 'content': [{'text': history[-1][0]}, {'file': page_url}]}]
- history[-1][1] = ''
- try:
-```
+class VisualStorytelling(Agent):
+ """Customize an agent for writing story from pictures"""
-This function is important because it defines how Qwen-Agent Tutorial: Tool-Enabled Agent Framework with MCP, RAG, and Multi-Modal Workflows implements the patterns covered in this chapter.
+ def __init__(self,
+ function_list: Optional[List[Union[str, Dict, BaseTool]]] = None,
+ llm: Optional[Union[Dict, BaseChatModel]] = None):
+ super().__init__(llm=llm)
-### `qwen_server/assistant_server.py`
+ # Nest one vl assistant for image understanding
+ self.image_agent = Assistant(llm={'model': 'qwen-vl-max'})
-The `set_url` function in [`qwen_server/assistant_server.py`](https://github.com/QwenLM/Qwen-Agent/blob/HEAD/qwen_server/assistant_server.py) handles a key part of this chapter's functionality:
+ # Nest one assistant for article writing
+ self.writing_agent = Assistant(llm=self.llm,
+ function_list=function_list,
+ system_message='你扮演一个想象力丰富的学生，你需要先理解图片内容，根据描述图片信息以后，' +
+ '参考知识库中教你的写作技巧，发挥你的想象力，写一篇800字的记叙文',
+ files=['https://www.jianshu.com/p/cdf82ff33ef8'])
-```py
+ def _run(self, messages: List[Message], lang: str = 'zh', **kwargs) -> Iterator[List[Message]]:
+ """Define the workflow"""
+ assert isinstance(messages[-1]['content'], list)
+ assert any([item.image for item in messages[-1]['content']]), 'This agent requires input of images'
-def set_url():
- lines = []
- if not os.path.exists(cache_file_popup_url):
- # Only able to remind the situation of first browsing failure
- gr.Error('Oops, it seems that the page cannot be opened due to network issues.')
-
- for line in jsonlines.open(cache_file_popup_url):
- lines.append(line)
- logger.info('The current access page is: ' + lines[-1]['url'])
- return lines[-1]['url']
-
-
-def bot(history):
- page_url = set_url()
- if not history:
- yield history
- else:
- messages = [{'role': 'user', 'content': [{'text': history[-1][0]}, {'file': page_url}]}]
- history[-1][1] = ''
- try:
- response = assistant.run(messages=messages, max_ref_token=server_config.server.max_ref_token)
- for rsp in response:
- if rsp:
- history[-1][1] = rsp[-1]['content']
- yield history
- except ModelServiceError as ex:
- history[-1][1] = str(ex)
- yield history
- except Exception as ex:
- raise ValueError(ex)
+ # Image understanding
+ new_messages = copy.deepcopy(messages)
+ new_messages[-1]['content'].append(ContentItem(text='请详细描述这张图片的所有细节内容'))
+ response = []
+ for rsp in self.image_agent.run(new_messages):
+ yield response + rsp
```
-This function is important because it defines how Qwen-Agent Tutorial: Tool-Enabled Agent Framework with MCP, RAG, and Multi-Modal Workflows implements the patterns covered in this chapter.
+This class is important because it defines how Qwen-Agent Tutorial: Tool-Enabled Agent Framework with MCP, RAG, and Multi-Modal Workflows implements the patterns covered in this chapter.
## How These Components Connect
@@ -212,10 +200,10 @@ This function is important because it defines how Qwen-Agent Tutorial: Tool-Enab
```mermaid
flowchart TD
A[test]
- B[add_text]
- C[rm_text]
- D[set_url]
- E[bot]
+ B[app_tui]
+ C[app_gui]
+ D[VisualStorytelling]
+ E[test]
A --> B
B --> C
C --> D
diff --git a/tutorials/qwen-agent-tutorial/07-benchmarking-and-deepplanning-evaluation.md b/tutorials/qwen-agent-tutorial/07-benchmarking-and-deepplanning-evaluation.md
index c002b7b4..8a154d43 100644
--- a/tutorials/qwen-agent-tutorial/07-benchmarking-and-deepplanning-evaluation.md
+++ b/tutorials/qwen-agent-tutorial/07-benchmarking-and-deepplanning-evaluation.md
@@ -38,106 +38,77 @@ You now have a benchmark-driven evaluation model for long-horizon Qwen-Agent tas
Next: [Chapter 8: Contribution Workflow and Production Governance](08-contribution-workflow-and-production-governance.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `examples/assistant_add_custom_tool.py`
+### `examples/multi_agent_router.py`
-The `MyImageGen` class in [`examples/assistant_add_custom_tool.py`](https://github.com/QwenLM/Qwen-Agent/blob/HEAD/examples/assistant_add_custom_tool.py) handles a key part of this chapter's functionality:
+The `init_agent_service` function in [`examples/multi_agent_router.py`](https://github.com/QwenLM/Qwen-Agent/blob/HEAD/examples/multi_agent_router.py) handles a key part of this chapter's functionality:
```py
-# Add a custom tool named my_image_gen：
-@register_tool('my_image_gen')
-class MyImageGen(BaseTool):
- description = 'AI painting (image generation) service, input text description, and return the image URL drawn based on text information.'
- parameters = [{
- 'name': 'prompt',
- 'type': 'string',
- 'description': 'Detailed description of the desired image content, in English',
- 'required': True,
- }]
-
- def call(self, params: str, **kwargs) -> str:
- prompt = json5.loads(params)['prompt']
- prompt = urllib.parse.quote(prompt)
- return json.dumps(
- {'image_url': f'https://image.pollinations.ai/prompt/{prompt}'},
- ensure_ascii=False,
- )
def init_agent_service():
+ # settings
llm_cfg = {'model': 'qwen-max'}
- system = ("According to the user's request, you first draw a picture and then automatically "
- 'run code to download the picture and select an image operation from the given document '
- 'to process the image')
-
- tools = [
- 'my_image_gen',
- 'code_interpreter',
- ] # code_interpreter is a built-in tool in Qwen-Agent
- bot = Assistant(
- llm=llm_cfg,
-```
-
-This class is important because it defines how Qwen-Agent Tutorial: Tool-Enabled Agent Framework with MCP, RAG, and Multi-Modal Workflows implements the patterns covered in this chapter.
-
-### `examples/assistant_add_custom_tool.py`
-
-The `init_agent_service` function in [`examples/assistant_add_custom_tool.py`](https://github.com/QwenLM/Qwen-Agent/blob/HEAD/examples/assistant_add_custom_tool.py) handles a key part of this chapter's functionality:
-
-```py
+ llm_cfg_vl = {'model': 'qwen-vl-max'}
+ tools = ['image_gen', 'code_interpreter']
+ # Define a vl agent
+ bot_vl = Assistant(llm=llm_cfg_vl, name='多模态助手', description='可以理解图像内容。')
-def init_agent_service():
- llm_cfg = {'model': 'qwen-max'}
- system = ("According to the user's request, you first draw a picture and then automatically "
- 'run code to download the picture and select an image operation from the given document '
- 'to process the image')
-
- tools = [
- 'my_image_gen',
- 'code_interpreter',
- ] # code_interpreter is a built-in tool in Qwen-Agent
- bot = Assistant(
+ # Define a tool agent
+ bot_tool = ReActChat(
llm=llm_cfg,
- name='AI painting',
- description='AI painting service',
- system_message=system,
+ name='工具助手',
+ description='可以使用画图工具和运行代码来解决问题',
function_list=tools,
- files=[os.path.join(ROOT_RESOURCE, 'doc.pdf')],
)
+ # Define a router (simultaneously serving as a text agent)
+ bot = Router(
+ llm=llm_cfg,
+ agents=[bot_vl, bot_tool],
+ )
return bot
-def test(query: str = 'draw a dog'):
- # Define the agent
- bot = init_agent_service()
-
- # Chat
- messages = [{'role': 'user', 'content': query}]
- for response in bot.run(messages=messages):
- print('bot response:', response)
+def test(
+ query: str = 'hello',
+ image: str = 'https://dashscope.oss-cn-beijing.aliyuncs.com/images/dog_and_girl.jpeg',
+ file: Optional[str] = os.path.join(ROOT_RESOURCE, 'poem.pdf'),
+):
```
This function is important because it defines how Qwen-Agent Tutorial: Tool-Enabled Agent Framework with MCP, RAG, and Multi-Modal Workflows implements the patterns covered in this chapter.
-### `examples/assistant_add_custom_tool.py`
+### `examples/multi_agent_router.py`
-The `test` function in [`examples/assistant_add_custom_tool.py`](https://github.com/QwenLM/Qwen-Agent/blob/HEAD/examples/assistant_add_custom_tool.py) handles a key part of this chapter's functionality:
+The `test` function in [`examples/multi_agent_router.py`](https://github.com/QwenLM/Qwen-Agent/blob/HEAD/examples/multi_agent_router.py) handles a key part of this chapter's functionality:
```py
-def test(query: str = 'draw a dog'):
+def test(
+ query: str = 'hello',
+ image: str = 'https://dashscope.oss-cn-beijing.aliyuncs.com/images/dog_and_girl.jpeg',
+ file: Optional[str] = os.path.join(ROOT_RESOURCE, 'poem.pdf'),
+):
# Define the agent
bot = init_agent_service()
# Chat
- messages = [{'role': 'user', 'content': query}]
- for response in bot.run(messages=messages):
+ messages = []
+
+ if not image and not file:
+ messages.append({'role': 'user', 'content': query})
+ else:
+ messages.append({'role': 'user', 'content': [{'text': query}]})
+ if image:
+ messages[-1]['content'].append({'image': image})
+ if file:
+ messages[-1]['content'].append({'file': file})
+
+ for response in bot.run(messages):
print('bot response:', response)
@@ -147,27 +118,13 @@ def app_tui():
# Chat
messages = []
- while True:
- query = input('user question: ')
- messages.append({'role': 'user', 'content': query})
- response = []
- for response in bot.run(messages=messages):
- print('bot response:', response)
- messages.extend(response)
-
-
-def app_gui():
- # Define the agent
- bot = init_agent_service()
- chatbot_config = {
- 'prompt.suggestions': [
```
This function is important because it defines how Qwen-Agent Tutorial: Tool-Enabled Agent Framework with MCP, RAG, and Multi-Modal Workflows implements the patterns covered in this chapter.
-### `examples/assistant_add_custom_tool.py`
+### `examples/multi_agent_router.py`
-The `app_tui` function in [`examples/assistant_add_custom_tool.py`](https://github.com/QwenLM/Qwen-Agent/blob/HEAD/examples/assistant_add_custom_tool.py) handles a key part of this chapter's functionality:
+The `app_tui` function in [`examples/multi_agent_router.py`](https://github.com/QwenLM/Qwen-Agent/blob/HEAD/examples/multi_agent_router.py) handles a key part of this chapter's functionality:
```py
@@ -180,27 +137,51 @@ def app_tui():
messages = []
while True:
query = input('user question: ')
- messages.append({'role': 'user', 'content': query})
+ # Image example: https://dashscope.oss-cn-beijing.aliyuncs.com/images/dog_and_girl.jpeg
+ image = input('image url (press enter if no image): ')
+ # File example: resource/poem.pdf
+ file = input('file url (press enter if no file): ').strip()
+ if not query:
+ print('user question cannot be empty！')
+ continue
+ if not image and not file:
+ messages.append({'role': 'user', 'content': query})
+ else:
+ messages.append({'role': 'user', 'content': [{'text': query}]})
+ if image:
+ messages[-1]['content'].append({'image': image})
+ if file:
+ messages[-1]['content'].append({'file': file})
+
response = []
- for response in bot.run(messages=messages):
+ for response in bot.run(messages):
print('bot response:', response)
messages.extend(response)
+```
+
+This function is important because it defines how Qwen-Agent Tutorial: Tool-Enabled Agent Framework with MCP, RAG, and Multi-Modal Workflows implements the patterns covered in this chapter.
+
+### `examples/multi_agent_router.py`
+
+The `app_gui` function in [`examples/multi_agent_router.py`](https://github.com/QwenLM/Qwen-Agent/blob/HEAD/examples/multi_agent_router.py) handles a key part of this chapter's functionality:
+
+```py
+
+
def app_gui():
- # Define the agent
bot = init_agent_service()
chatbot_config = {
- 'prompt.suggestions': [
- '画一只猫的图片',
- '画一只可爱的小腊肠狗',
- '画一幅风景画，有湖有山有树',
- ]
+ 'verbose': True,
}
- WebUI(
- bot,
- chatbot_config=chatbot_config,
- ).run()
+ WebUI(bot, chatbot_config=chatbot_config).run()
+
+
+if __name__ == '__main__':
+ # test()
+ # app_tui()
+ app_gui()
```
@@ -211,11 +192,11 @@ This function is important because it defines how Qwen-Agent Tutorial: Tool-Enab
```mermaid
flowchart TD
- A[MyImageGen]
- B[init_agent_service]
- C[test]
- D[app_tui]
- E[app_gui]
+ A[init_agent_service]
+ B[test]
+ C[app_tui]
+ D[app_gui]
+ E[test]
A --> B
B --> C
C --> D
diff --git a/tutorials/qwen-agent-tutorial/08-contribution-workflow-and-production-governance.md b/tutorials/qwen-agent-tutorial/08-contribution-workflow-and-production-governance.md
index f77960af..1ced2eff 100644
--- a/tutorials/qwen-agent-tutorial/08-contribution-workflow-and-production-governance.md
+++ b/tutorials/qwen-agent-tutorial/08-contribution-workflow-and-production-governance.md
@@ -40,166 +40,152 @@ You now have a complete Qwen-Agent path from first setup to production governanc
Next tutorial: [Mini-SWE-Agent Tutorial](../mini-swe-agent-tutorial/)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `examples/multi_agent_router.py`
+### `qwen_server/utils.py`
-The `init_agent_service` function in [`examples/multi_agent_router.py`](https://github.com/QwenLM/Qwen-Agent/blob/HEAD/examples/multi_agent_router.py) handles a key part of this chapter's functionality:
+The `read_meta_data_by_condition` function in [`qwen_server/utils.py`](https://github.com/QwenLM/Qwen-Agent/blob/HEAD/qwen_server/utils.py) handles a key part of this chapter's functionality:
```py
-def init_agent_service():
- # settings
- llm_cfg = {'model': 'qwen-max'}
- llm_cfg_vl = {'model': 'qwen-vl-max'}
- tools = ['image_gen', 'code_interpreter']
-
- # Define a vl agent
- bot_vl = Assistant(llm=llm_cfg_vl, name='多模态助手', description='可以理解图像内容。')
-
- # Define a tool agent
- bot_tool = ReActChat(
- llm=llm_cfg,
- name='工具助手',
- description='可以使用画图工具和运行代码来解决问题',
- function_list=tools,
- )
-
- # Define a router (simultaneously serving as a text agent)
- bot = Router(
- llm=llm_cfg,
- agents=[bot_vl, bot_tool],
- )
- return bot
-
+def read_meta_data_by_condition(meta_file: str, **kwargs):
+ if os.path.exists(meta_file):
+ with open(meta_file, 'r', encoding='utf-8') as file:
+ meta_info = json.load(file)
+ else:
+ meta_info = {}
+ return []
-def test(
- query: str = 'hello',
- image: str = 'https://dashscope.oss-cn-beijing.aliyuncs.com/images/dog_and_girl.jpeg',
- file: Optional[str] = os.path.join(ROOT_RESOURCE, 'poem.pdf'),
-):
+ if 'url' in kwargs:
+ if kwargs['url'] in meta_info:
+ return meta_info[kwargs['url']]
+ else:
+ return ''
+
+ records = meta_info.values()
+
+ if 'time_limit' in kwargs:
+ filter_records = []
+ for x in records:
+ if kwargs['time_limit'][0] <= x['time'] <= kwargs['time_limit'][1]:
+ filter_records.append(x)
+ records = filter_records
+ if 'checked' in kwargs:
+ filter_records = []
+ for x in records:
+ if x['checked']:
+ filter_records.append(x)
+ records = filter_records
+
+ return records
```
This function is important because it defines how Qwen-Agent Tutorial: Tool-Enabled Agent Framework with MCP, RAG, and Multi-Modal Workflows implements the patterns covered in this chapter.
-### `examples/multi_agent_router.py`
+### `qwen_server/utils.py`
-The `test` function in [`examples/multi_agent_router.py`](https://github.com/QwenLM/Qwen-Agent/blob/HEAD/examples/multi_agent_router.py) handles a key part of this chapter's functionality:
+The `save_history` function in [`qwen_server/utils.py`](https://github.com/QwenLM/Qwen-Agent/blob/HEAD/qwen_server/utils.py) handles a key part of this chapter's functionality:
```py
-def test(
- query: str = 'hello',
- image: str = 'https://dashscope.oss-cn-beijing.aliyuncs.com/images/dog_and_girl.jpeg',
- file: Optional[str] = os.path.join(ROOT_RESOURCE, 'poem.pdf'),
-):
- # Define the agent
- bot = init_agent_service()
-
- # Chat
- messages = []
+def save_history(history, url, history_dir):
+ history = history or []
+ history_file = os.path.join(history_dir, get_basename_from_url(url) + '.json')
+ if not os.path.exists(history_dir):
+ os.makedirs(history_dir)
+ with open(history_file, 'w', encoding='utf-8') as file:
+ json.dump(history, file, indent=4)
- if not image and not file:
- messages.append({'role': 'user', 'content': query})
- else:
- messages.append({'role': 'user', 'content': [{'text': query}]})
- if image:
- messages[-1]['content'].append({'image': image})
- if file:
- messages[-1]['content'].append({'file': file})
- for response in bot.run(messages):
- print('bot response:', response)
+def read_history(url, history_dir):
+ history_file = os.path.join(history_dir, get_basename_from_url(url) + '.json')
+ if os.path.exists(history_file):
+ with open(history_file, 'r', encoding='utf-8') as file:
+ data = json.load(file)
+ if data:
+ return data
+ else:
+ return []
+ return []
-
-def app_tui():
- # Define the agent
- bot = init_agent_service()
-
- # Chat
- messages = []
```
This function is important because it defines how Qwen-Agent Tutorial: Tool-Enabled Agent Framework with MCP, RAG, and Multi-Modal Workflows implements the patterns covered in this chapter.
-### `examples/multi_agent_router.py`
+### `qwen_server/utils.py`
-The `app_tui` function in [`examples/multi_agent_router.py`](https://github.com/QwenLM/Qwen-Agent/blob/HEAD/examples/multi_agent_router.py) handles a key part of this chapter's functionality:
+The `read_history` function in [`qwen_server/utils.py`](https://github.com/QwenLM/Qwen-Agent/blob/HEAD/qwen_server/utils.py) handles a key part of this chapter's functionality:
```py
-def app_tui():
- # Define the agent
- bot = init_agent_service()
-
- # Chat
- messages = []
- while True:
- query = input('user question: ')
- # Image example: https://dashscope.oss-cn-beijing.aliyuncs.com/images/dog_and_girl.jpeg
- image = input('image url (press enter if no image): ')
- # File example: resource/poem.pdf
- file = input('file url (press enter if no file): ').strip()
- if not query:
- print('user question cannot be empty！')
- continue
- if not image and not file:
- messages.append({'role': 'user', 'content': query})
- else:
- messages.append({'role': 'user', 'content': [{'text': query}]})
- if image:
- messages[-1]['content'].append({'image': image})
- if file:
- messages[-1]['content'].append({'file': file})
-
- response = []
- for response in bot.run(messages):
- print('bot response:', response)
- messages.extend(response)
-
+def read_history(url, history_dir):
+ history_file = os.path.join(history_dir, get_basename_from_url(url) + '.json')
+ if os.path.exists(history_file):
+ with open(history_file, 'r', encoding='utf-8') as file:
+ data = json.load(file)
+ if data:
+ return data
+ else:
+ return []
+ return []
```
This function is important because it defines how Qwen-Agent Tutorial: Tool-Enabled Agent Framework with MCP, RAG, and Multi-Modal Workflows implements the patterns covered in this chapter.
-### `examples/multi_agent_router.py`
+### `examples/assistant_add_custom_tool.py`
-The `app_gui` function in [`examples/multi_agent_router.py`](https://github.com/QwenLM/Qwen-Agent/blob/HEAD/examples/multi_agent_router.py) handles a key part of this chapter's functionality:
+The `MyImageGen` class in [`examples/assistant_add_custom_tool.py`](https://github.com/QwenLM/Qwen-Agent/blob/HEAD/examples/assistant_add_custom_tool.py) handles a key part of this chapter's functionality:
```py
+# Add a custom tool named my_image_gen：
+@register_tool('my_image_gen')
+class MyImageGen(BaseTool):
+ description = 'AI painting (image generation) service, input text description, and return the image URL drawn based on text information.'
+ parameters = [{
+ 'name': 'prompt',
+ 'type': 'string',
+ 'description': 'Detailed description of the desired image content, in English',
+ 'required': True,
+ }]
+
+ def call(self, params: str, **kwargs) -> str:
+ prompt = json5.loads(params)['prompt']
+ prompt = urllib.parse.quote(prompt)
+ return json.dumps(
+ {'image_url': f'https://image.pollinations.ai/prompt/{prompt}'},
+ ensure_ascii=False,
+ )
-def app_gui():
- bot = init_agent_service()
- chatbot_config = {
- 'verbose': True,
- }
- WebUI(bot, chatbot_config=chatbot_config).run()
-
-
-if __name__ == '__main__':
- # test()
- # app_tui()
- app_gui()
-
+def init_agent_service():
+ llm_cfg = {'model': 'qwen-max'}
+ system = ("According to the user's request, you first draw a picture and then automatically "
+ 'run code to download the picture and select an image operation from the given document '
+ 'to process the image')
+
+ tools = [
+ 'my_image_gen',
+ 'code_interpreter',
+ ] # code_interpreter is a built-in tool in Qwen-Agent
+ bot = Assistant(
+ llm=llm_cfg,
```
-This function is important because it defines how Qwen-Agent Tutorial: Tool-Enabled Agent Framework with MCP, RAG, and Multi-Modal Workflows implements the patterns covered in this chapter.
+This class is important because it defines how Qwen-Agent Tutorial: Tool-Enabled Agent Framework with MCP, RAG, and Multi-Modal Workflows implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[init_agent_service]
- B[test]
- C[app_tui]
- D[app_gui]
+ A[read_meta_data_by_condition]
+ B[save_history]
+ C[read_history]
+ D[MyImageGen]
E[init_agent_service]
A --> B
B --> C
diff --git a/tutorials/ragflow-tutorial/02-document-processing.md b/tutorials/ragflow-tutorial/02-document-processing.md
index 5306e4f6..28ec9c35 100644
--- a/tutorials/ragflow-tutorial/02-document-processing.md
+++ b/tutorials/ragflow-tutorial/02-document-processing.md
@@ -755,6 +755,24 @@ Under the hood, `Chapter 2: Document Processing` usually follows a repeatable co
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## Document Processing Pipeline
+
+```mermaid
+flowchart TD
+ A[Document Upload] --> B{File Type}
+ B --> C[PDF Parser]
+ B --> D[Word / DOCX]
+ B --> E[HTML / Web]
+ B --> F[Excel / CSV]
+ C --> G[Text Extraction]
+ D --> G
+ E --> G
+ F --> G
+ G --> H[Layout Analysis]
+ H --> I[Chunking]
+ I --> J[Embedding Queue]
+```
+
## Source Walkthrough
Use the following upstream sources to verify implementation details while reading this chapter:
diff --git a/tutorials/ragflow-tutorial/03-knowledge-base-setup.md b/tutorials/ragflow-tutorial/03-knowledge-base-setup.md
index c197bf27..3b288459 100644
--- a/tutorials/ragflow-tutorial/03-knowledge-base-setup.md
+++ b/tutorials/ragflow-tutorial/03-knowledge-base-setup.md
@@ -678,6 +678,20 @@ Under the hood, `Chapter 3: Knowledge Base Setup` usually follows a repeatable c
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## Knowledge Base Architecture
+
+```mermaid
+flowchart LR
+ A[Documents] --> B[RAGFlow Knowledge Base]
+ B --> C[Chunk Strategy Config]
+ C --> D[Embedding Model]
+ D --> E[Vector Index]
+ B --> F[Full-text Index]
+ E --> G[Hybrid Search]
+ F --> G
+ G --> H[Ranked Chunks]
+```
+
## Source Walkthrough
Use the following upstream sources to verify implementation details while reading this chapter:
diff --git a/tutorials/ragflow-tutorial/04-retrieval-system.md b/tutorials/ragflow-tutorial/04-retrieval-system.md
index d967b5df..0381ffd1 100644
--- a/tutorials/ragflow-tutorial/04-retrieval-system.md
+++ b/tutorials/ragflow-tutorial/04-retrieval-system.md
@@ -795,6 +795,21 @@ Under the hood, `Chapter 4: Retrieval System` usually follows a repeatable contr
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## Retrieval System Flow
+
+```mermaid
+flowchart TD
+ A[User Query] --> B[Query Embedding]
+ B --> C[Vector Search]
+ A --> D[Keyword Extraction]
+ D --> E[Full-text Search]
+ C --> F[Score Fusion]
+ E --> F
+ F --> G[Reranking Model]
+ G --> H[Top-K Chunks]
+ H --> I[LLM Context]
+```
+
## Source Walkthrough
Use the following upstream sources to verify implementation details while reading this chapter:
diff --git a/tutorials/ragflow-tutorial/05-llm-integration.md b/tutorials/ragflow-tutorial/05-llm-integration.md
index e9adf0a7..2492eac2 100644
--- a/tutorials/ragflow-tutorial/05-llm-integration.md
+++ b/tutorials/ragflow-tutorial/05-llm-integration.md
@@ -426,6 +426,22 @@ Under the hood, `Chapter 5: LLM Integration & Configuration` usually follows a r
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## LLM Integration Architecture
+
+```mermaid
+flowchart LR
+ A[RAGFlow Backend] --> B{LLM Provider}
+ B --> C[OpenAI GPT-4o]
+ B --> D[Anthropic Claude]
+ B --> E[Ollama Local]
+ B --> F[Azure OpenAI]
+ C --> G[Answer Generation]
+ D --> G
+ E --> G
+ F --> G
+ G --> H[RAG Response with Citations]
+```
+
## Source Walkthrough
Use the following upstream sources to verify implementation details while reading this chapter:
diff --git a/tutorials/ragflow-tutorial/07-advanced-features.md b/tutorials/ragflow-tutorial/07-advanced-features.md
index f9e2d448..93f599cb 100644
--- a/tutorials/ragflow-tutorial/07-advanced-features.md
+++ b/tutorials/ragflow-tutorial/07-advanced-features.md
@@ -767,6 +767,19 @@ Under the hood, `Chapter 7: Advanced Features` usually follows a repeatable cont
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## Advanced Feature Architecture
+
+```mermaid
+flowchart TD
+ A[RAGFlow Core] --> B[Knowledge Graph]
+ A --> C[Multi-modal Processing]
+ A --> D[Agent Workflows]
+ B --> E[Entity Linking]
+ B --> F[Relationship Queries]
+ C --> G[Image Understanding]
+ D --> H[Tool Use in RAG]
+```
+
## Source Walkthrough
Use the following upstream sources to verify implementation details while reading this chapter:
diff --git a/tutorials/ragflow-tutorial/08-production-deployment.md b/tutorials/ragflow-tutorial/08-production-deployment.md
index 1796bba8..6ce8a332 100644
--- a/tutorials/ragflow-tutorial/08-production-deployment.md
+++ b/tutorials/ragflow-tutorial/08-production-deployment.md
@@ -1270,6 +1270,19 @@ Under the hood, `Chapter 8: Production Deployment` usually follows a repeatable
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## Production Deployment Architecture
+
+```mermaid
+flowchart LR
+ A[Load Balancer] --> B[RAGFlow API Nodes]
+ B --> C[Elasticsearch / Vector DB]
+ B --> D[MinIO Object Store]
+ B --> E[LLM Backend Pool]
+ B --> F[Redis Cache]
+ G[Monitoring] --> B
+ H[CI/CD] --> B
+```
+
## Source Walkthrough
Use the following upstream sources to verify implementation details while reading this chapter:
diff --git a/tutorials/refly-tutorial/01-getting-started.md b/tutorials/refly-tutorial/01-getting-started.md
index dbfe8a9d..16de6c77 100644
--- a/tutorials/refly-tutorial/01-getting-started.md
+++ b/tutorials/refly-tutorial/01-getting-started.md
@@ -49,8 +49,6 @@ You now have a baseline local environment for running Refly workflows.
Next: [Chapter 2: Architecture and Component Topology](02-architecture-and-component-topology.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `scripts/check-i18n-consistency.js`
@@ -94,46 +92,46 @@ class I18nConsistencyChecker {
This class is important because it defines how Refly Tutorial: Build Deterministic Agent Skills and Ship Them Across APIs and Claude Code implements the patterns covered in this chapter.
-### `scripts/cleanup-node-modules.js`
-
-The `findNodeModules` function in [`scripts/cleanup-node-modules.js`](https://github.com/refly-ai/refly/blob/HEAD/scripts/cleanup-node-modules.js) handles a key part of this chapter's functionality:
-
-```js
- * @param {string[]} nodeModulesPaths - Array to collect found paths
- */
-function findNodeModules(dir, nodeModulesPaths = []) {
- try {
- const items = fs.readdirSync(dir, { withFileTypes: true });
-
- for (const item of items) {
- if (item.isDirectory()) {
- const fullPath = path.join(dir, item.name);
-
- if (item.name === 'node_modules') {
- nodeModulesPaths.push(fullPath);
- console.log(`Found: ${fullPath}`);
- } else {
- // Skip common directories that shouldn't contain node_modules we want to delete
- const skipDirs = ['.git', '.turbo', 'dist', 'build', 'coverage', '.next', '.nuxt'];
- if (!skipDirs.includes(item.name)) {
- findNodeModules(fullPath, nodeModulesPaths);
- }
- }
- }
- }
- } catch (error) {
- // Skip directories we can't read (permission issues, etc.)
- console.warn(`Warning: Could not read directory ${dir}: ${error.message}`);
- }
-
- return nodeModulesPaths;
-}
-
-/**
- * Delete a directory recursively
+### `config/provider-catalog.json`
+
+The `for` interface in [`config/provider-catalog.json`](https://github.com/refly-ai/refly/blob/HEAD/config/provider-catalog.json) handles a key part of this chapter's functionality:
+
+```json
+ "baseUrl": "https://api.siliconflow.cn/v1",
+ "description": {
+ "en": "SiliconFlow provides a one-stop cloud service platform with high-performance inference for top-tier large language and embedding models.",
+ "zh-CN": "SiliconFlow 提供一站式云服务平台，为顶级大语言模型和嵌入模型提供高性能推理服务。"
+ },
+ "categories": ["llm", "embedding"],
+ "documentation": "https://docs.siliconflow.cn/",
+ "icon": "https://static.refly.ai/icons/providers/siliconflow.png"
+ },
+ {
+ "name": "litellm",
+ "providerKey": "openai",
+ "baseUrl": "https://litellm.powerformer.net/v1",
+ "description": {
+ "en": "LiteLLM is a lightweight library to simplify LLM completion and embedding calls, providing a consistent interface for over 100 LLMs.",
+ "zh-CN": "LiteLLM 是一个轻量级库，用于简化 LLM 的补全和嵌入调用，为 100 多个 LLM 提供一致的接口。"
+ },
+ "categories": ["llm", "embedding"],
+ "documentation": "https://docs.litellm.ai/",
+ "icon": "https://static.refly.ai/icons/providers/litellm.png"
+ },
+ {
+ "name": "七牛云AI",
+ "providerKey": "openai",
+ "baseUrl": "https://api.qnaigc.com/v1",
+ "description": {
+ "en": "Qiniu AI provides efficient, stable, and secure model inference services, supporting mainstream open-source large models.",
+ "zh-CN": "七牛云AI 提供高效、稳定、安全的模型推理服务，支持主流开源大模型。"
+ },
+ "categories": ["llm"],
+ "documentation": "https://developer.qiniu.com/aitokenapi",
+ "icon": "https://static.refly.ai/icons/providers/qiniu.png"
```
-This function is important because it defines how Refly Tutorial: Build Deterministic Agent Skills and Ship Them Across APIs and Claude Code implements the patterns covered in this chapter.
+This interface is important because it defines how Refly Tutorial: Build Deterministic Agent Skills and Ship Them Across APIs and Claude Code implements the patterns covered in this chapter.
## How These Components Connect
@@ -141,6 +139,6 @@ This function is important because it defines how Refly Tutorial: Build Determin
```mermaid
flowchart TD
A[I18nConsistencyChecker]
- B[findNodeModules]
+ B[for]
A --> B
```
diff --git a/tutorials/refly-tutorial/02-architecture-and-component-topology.md b/tutorials/refly-tutorial/02-architecture-and-component-topology.md
index 75fb4ac1..cef76e36 100644
--- a/tutorials/refly-tutorial/02-architecture-and-component-topology.md
+++ b/tutorials/refly-tutorial/02-architecture-and-component-topology.md
@@ -41,88 +41,80 @@ You now understand the architectural boundaries and extension points in Refly.
Next: [Chapter 3: Workflow Construction and Deterministic Runtime](03-workflow-construction-and-deterministic-runtime.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `scripts/cleanup-node-modules.js`
-
-The `deleteDirectory` function in [`scripts/cleanup-node-modules.js`](https://github.com/refly-ai/refly/blob/HEAD/scripts/cleanup-node-modules.js) handles a key part of this chapter's functionality:
-
-```js
- * @param {string} dirPath - Path to directory to delete
- */
-function deleteDirectory(dirPath) {
- try {
- fs.rmSync(dirPath, { recursive: true, force: true });
- console.log(`✅ Deleted: ${dirPath}`);
- return true;
- } catch (error) {
- console.error(`❌ Failed to delete ${dirPath}: ${error.message}`);
- return false;
- }
-}
-
-/**
- * Get human-readable file size
- * @param {number} bytes - Size in bytes
- */
-function formatBytes(bytes) {
- if (bytes === 0) return '0 Bytes';
- const k = 1024;
- const sizes = ['Bytes', 'KB', 'MB', 'GB'];
- const i = Math.floor(Math.log(bytes) / Math.log(k));
- return `${Number.parseFloat((bytes / k ** i).toFixed(2))} ${sizes[i]}`;
-}
-
-/**
- * Calculate directory size
- * @param {string} dirPath - Path to directory
- */
-function getDirectorySize(dirPath) {
- let totalSize = 0;
-
+### `config/provider-catalog.json`
+
+The `for` interface in [`config/provider-catalog.json`](https://github.com/refly-ai/refly/blob/HEAD/config/provider-catalog.json) handles a key part of this chapter's functionality:
+
+```json
+ "baseUrl": "https://api.siliconflow.cn/v1",
+ "description": {
+ "en": "SiliconFlow provides a one-stop cloud service platform with high-performance inference for top-tier large language and embedding models.",
+ "zh-CN": "SiliconFlow 提供一站式云服务平台，为顶级大语言模型和嵌入模型提供高性能推理服务。"
+ },
+ "categories": ["llm", "embedding"],
+ "documentation": "https://docs.siliconflow.cn/",
+ "icon": "https://static.refly.ai/icons/providers/siliconflow.png"
+ },
+ {
+ "name": "litellm",
+ "providerKey": "openai",
+ "baseUrl": "https://litellm.powerformer.net/v1",
+ "description": {
+ "en": "LiteLLM is a lightweight library to simplify LLM completion and embedding calls, providing a consistent interface for over 100 LLMs.",
+ "zh-CN": "LiteLLM 是一个轻量级库，用于简化 LLM 的补全和嵌入调用，为 100 多个 LLM 提供一致的接口。"
+ },
+ "categories": ["llm", "embedding"],
+ "documentation": "https://docs.litellm.ai/",
+ "icon": "https://static.refly.ai/icons/providers/litellm.png"
+ },
+ {
+ "name": "七牛云AI",
+ "providerKey": "openai",
+ "baseUrl": "https://api.qnaigc.com/v1",
+ "description": {
+ "en": "Qiniu AI provides efficient, stable, and secure model inference services, supporting mainstream open-source large models.",
+ "zh-CN": "七牛云AI 提供高效、稳定、安全的模型推理服务，支持主流开源大模型。"
+ },
+ "categories": ["llm"],
+ "documentation": "https://developer.qiniu.com/aitokenapi",
+ "icon": "https://static.refly.ai/icons/providers/qiniu.png"
```
-This function is important because it defines how Refly Tutorial: Build Deterministic Agent Skills and Ship Them Across APIs and Claude Code implements the patterns covered in this chapter.
+This interface is important because it defines how Refly Tutorial: Build Deterministic Agent Skills and Ship Them Across APIs and Claude Code implements the patterns covered in this chapter.
-### `scripts/cleanup-node-modules.js`
+### `scripts/upload-config.js`
-The `formatBytes` function in [`scripts/cleanup-node-modules.js`](https://github.com/refly-ai/refly/blob/HEAD/scripts/cleanup-node-modules.js) handles a key part of this chapter's functionality:
+The `uploadState` function in [`scripts/upload-config.js`](https://github.com/refly-ai/refly/blob/HEAD/scripts/upload-config.js) handles a key part of this chapter's functionality:
```js
- * @param {number} bytes - Size in bytes
- */
-function formatBytes(bytes) {
- if (bytes === 0) return '0 Bytes';
- const k = 1024;
- const sizes = ['Bytes', 'KB', 'MB', 'GB'];
- const i = Math.floor(Math.log(bytes) / Math.log(k));
- return `${Number.parseFloat((bytes / k ** i).toFixed(2))} ${sizes[i]}`;
+import { Client as MinioClient } from 'minio';
+
+async function uploadState(sourceFile, targetPath) {
+ const minioClient = new MinioClient({
+ endPoint: process.env.MINIO_EXTERNAL_ENDPOINT,
+ port: Number.parseInt(process.env.MINIO_EXTERNAL_PORT || '443'),
+ useSSL: process.env.MINIO_EXTERNAL_USE_SSL === 'true',
+ accessKey: process.env.MINIO_EXTERNAL_ACCESS_KEY,
+ secretKey: process.env.MINIO_EXTERNAL_SECRET_KEY,
+ });
+
+ const metaData = {
+ 'Content-Type': 'application/json',
+ };
+ await minioClient.fPutObject(process.env.MINIO_EXTERNAL_BUCKET, targetPath, sourceFile, metaData);
}
-/**
- * Calculate directory size
- * @param {string} dirPath - Path to directory
- */
-function getDirectorySize(dirPath) {
- let totalSize = 0;
-
- try {
- const items = fs.readdirSync(dirPath, { withFileTypes: true });
-
- for (const item of items) {
- const fullPath = path.join(dirPath, item.name);
-
- if (item.isDirectory()) {
- totalSize += getDirectorySize(fullPath);
- } else {
- try {
- const stats = fs.statSync(fullPath);
- totalSize += stats.size;
- } catch (_error) {
- // Skip files we can't stat
- }
+async function main() {
+ // upload mcp catalog
+ await uploadState('config/mcp-catalog.json', 'mcp-config/mcp-catalog.json');
+
+ await uploadState('config/provider-catalog.json', 'mcp-config/provider-catalog.json');
+}
+
+main();
+
```
This function is important because it defines how Refly Tutorial: Build Deterministic Agent Skills and Ship Them Across APIs and Claude Code implements the patterns covered in this chapter.
@@ -132,7 +124,7 @@ This function is important because it defines how Refly Tutorial: Build Determin
```mermaid
flowchart TD
- A[deleteDirectory]
- B[formatBytes]
+ A[for]
+ B[uploadState]
A --> B
```
diff --git a/tutorials/refly-tutorial/03-workflow-construction-and-deterministic-runtime.md b/tutorials/refly-tutorial/03-workflow-construction-and-deterministic-runtime.md
index 37e3a93e..03be7eba 100644
--- a/tutorials/refly-tutorial/03-workflow-construction-and-deterministic-runtime.md
+++ b/tutorials/refly-tutorial/03-workflow-construction-and-deterministic-runtime.md
@@ -49,88 +49,65 @@ You now have a practical pattern for building stable workflows and iterating saf
Next: [Chapter 4: API and Webhook Integrations](04-api-and-webhook-integrations.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `scripts/cleanup-node-modules.js`
+### `scripts/upload-config.js`
-The `getDirectorySize` function in [`scripts/cleanup-node-modules.js`](https://github.com/refly-ai/refly/blob/HEAD/scripts/cleanup-node-modules.js) handles a key part of this chapter's functionality:
+The `main` function in [`scripts/upload-config.js`](https://github.com/refly-ai/refly/blob/HEAD/scripts/upload-config.js) handles a key part of this chapter's functionality:
```js
- * @param {string} dirPath - Path to directory
- */
-function getDirectorySize(dirPath) {
- let totalSize = 0;
-
- try {
- const items = fs.readdirSync(dirPath, { withFileTypes: true });
-
- for (const item of items) {
- const fullPath = path.join(dirPath, item.name);
-
- if (item.isDirectory()) {
- totalSize += getDirectorySize(fullPath);
- } else {
- try {
- const stats = fs.statSync(fullPath);
- totalSize += stats.size;
- } catch (_error) {
- // Skip files we can't stat
- }
- }
- }
- } catch (_error) {
- // Skip directories we can't read
- }
-
- return totalSize;
}
async function main() {
- console.log('🔍 Searching for node_modules directories...\n');
-
-```
-
-This function is important because it defines how Refly Tutorial: Build Deterministic Agent Skills and Ship Them Across APIs and Claude Code implements the patterns covered in this chapter.
-
-### `scripts/cleanup-node-modules.js`
+ // upload mcp catalog
+ await uploadState('config/mcp-catalog.json', 'mcp-config/mcp-catalog.json');
-The `main` function in [`scripts/cleanup-node-modules.js`](https://github.com/refly-ai/refly/blob/HEAD/scripts/cleanup-node-modules.js) handles a key part of this chapter's functionality:
-
-```js
+ await uploadState('config/provider-catalog.json', 'mcp-config/provider-catalog.json');
}
-async function main() {
- console.log('🔍 Searching for node_modules directories...\n');
-
- const startTime = Date.now();
- const rootDir = process.cwd();
-
- // Find all node_modules directories
- const nodeModulesPaths = findNodeModules(rootDir);
-
- if (nodeModulesPaths.length === 0) {
- console.log('✨ No node_modules directories found!');
- return;
- }
+main();
- console.log(`\n📊 Found ${nodeModulesPaths.length} node_modules directories`);
-
- // Calculate total size before deletion
- let totalSize = 0;
- console.log('\n📏 Calculating sizes...');
- for (const dirPath of nodeModulesPaths) {
- const size = getDirectorySize(dirPath);
- totalSize += size;
- console.log(` ${path.relative(rootDir, dirPath)}: ${formatBytes(size)}`);
- }
+```
- console.log(`\n💾 Total size to be freed: ${formatBytes(totalSize)}`);
- console.log('\n🗑️ Starting deletion...\n');
+This function is important because it defines how Refly Tutorial: Build Deterministic Agent Skills and Ship Them Across APIs and Claude Code implements the patterns covered in this chapter.
- // Delete all found node_modules directories
- let deletedCount = 0;
+### `docs/.vitepress/config.ts`
+
+The `gtag` function in [`docs/.vitepress/config.ts`](https://github.com/refly-ai/refly/blob/HEAD/docs/.vitepress/config.ts) handles a key part of this chapter's functionality:
+
+```ts
+ {
+ async: '',
+ src: 'https://www.googletagmanager.com/gtag/js?id=G-RS0SJYDFJF',
+ },
+ ],
+ [
+ 'script',
+ {},
+ `window.dataLayer = window.dataLayer || [];
+ function gtag(){dataLayer.push(arguments);}
+ gtag('js', new Date());
+ gtag('config', 'G-RS0SJYDFJF');`,
+ ],
+ ],
+
+ // File path rewrites to map /en/* files to root URLs
+ rewrites: {
+ 'en/index.md': 'index.md',
+ 'en/:path*': ':path*',
+ },
+
+ // i18n configuration
+ locales: {
+ root: {
+ label: 'English',
+ lang: 'en',
+ title: 'Refly Docs',
+ description: 'Refly Documentation',
+ themeConfig: {
+ nav: enNav,
+ sidebar: sidebar.en,
+ siteTitle: 'Refly Docs',
```
This function is important because it defines how Refly Tutorial: Build Deterministic Agent Skills and Ship Them Across APIs and Claude Code implements the patterns covered in this chapter.
@@ -140,7 +117,7 @@ This function is important because it defines how Refly Tutorial: Build Determin
```mermaid
flowchart TD
- A[getDirectorySize]
- B[main]
+ A[main]
+ B[gtag]
A --> B
```
diff --git a/tutorials/refly-tutorial/04-api-and-webhook-integrations.md b/tutorials/refly-tutorial/04-api-and-webhook-integrations.md
index f56c366c..89aaaeeb 100644
--- a/tutorials/refly-tutorial/04-api-and-webhook-integrations.md
+++ b/tutorials/refly-tutorial/04-api-and-webhook-integrations.md
@@ -48,88 +48,86 @@ You now have a production-style pattern for calling and monitoring Refly workflo
Next: [Chapter 5: Refly CLI and Claude Code Skill Export](05-refly-cli-and-claude-code-skill-export.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `config/provider-catalog.json`
-
-The `for` interface in [`config/provider-catalog.json`](https://github.com/refly-ai/refly/blob/HEAD/config/provider-catalog.json) handles a key part of this chapter's functionality:
-
-```json
- "baseUrl": "https://api.siliconflow.cn/v1",
- "description": {
- "en": "SiliconFlow provides a one-stop cloud service platform with high-performance inference for top-tier large language and embedding models.",
- "zh-CN": "SiliconFlow 提供一站式云服务平台，为顶级大语言模型和嵌入模型提供高性能推理服务。"
- },
- "categories": ["llm", "embedding"],
- "documentation": "https://docs.siliconflow.cn/",
- "icon": "https://static.refly.ai/icons/providers/siliconflow.png"
- },
- {
- "name": "litellm",
- "providerKey": "openai",
- "baseUrl": "https://litellm.powerformer.net/v1",
- "description": {
- "en": "LiteLLM is a lightweight library to simplify LLM completion and embedding calls, providing a consistent interface for over 100 LLMs.",
- "zh-CN": "LiteLLM 是一个轻量级库，用于简化 LLM 的补全和嵌入调用，为 100 多个 LLM 提供一致的接口。"
- },
- "categories": ["llm", "embedding"],
- "documentation": "https://docs.litellm.ai/",
- "icon": "https://static.refly.ai/icons/providers/litellm.png"
- },
- {
- "name": "七牛云AI",
- "providerKey": "openai",
- "baseUrl": "https://api.qnaigc.com/v1",
- "description": {
- "en": "Qiniu AI provides efficient, stable, and secure model inference services, supporting mainstream open-source large models.",
- "zh-CN": "七牛云AI 提供高效、稳定、安全的模型推理服务，支持主流开源大模型。"
- },
- "categories": ["llm"],
- "documentation": "https://developer.qiniu.com/aitokenapi",
- "icon": "https://static.refly.ai/icons/providers/qiniu.png"
+### `cypress/support/commands.ts`
+
+The `Chainable` interface in [`cypress/support/commands.ts`](https://github.com/refly-ai/refly/blob/HEAD/cypress/support/commands.ts) handles a key part of this chapter's functionality:
+
+```ts
+// declare global {
+// namespace Cypress {
+// interface Chainable {
+// login(email: string, password: string): Chainable<void>
+// drag(subject: string, options?: Partial<TypeOptions>): Chainable<Element>
+// dismiss(subject: string, options?: Partial<TypeOptions>): Chainable<Element>
+// visit(originalFn: CommandOriginalFn, url: string, options: Partial<VisitOptions>): Chainable<Element>
+// }
+// }
+// }
+
+declare namespace Cypress {
+ interface Chainable {
+ /**
+ * Execute SQL query through Docker container
+ * @param query - SQL query to execute
+ * @example
+ * cy.execSQL('SELECT * FROM users')
+ */
+ execSQL(query: string): Chainable<string>;
+ /**
+ * Login to the app
+ * @param email - Email to login with
+ * @param password - Password to login with
+ * @example
+ * cy.login('test@example.com', 'testPassword123')
+ */
+ login(email: string, password: string): Chainable<void>;
+ }
+}
+
+Cypress.Commands.add('execSQL', (query: string) => {
```
This interface is important because it defines how Refly Tutorial: Build Deterministic Agent Skills and Ship Them Across APIs and Claude Code implements the patterns covered in this chapter.
-### `config/provider-catalog.json`
-
-The `for` interface in [`config/provider-catalog.json`](https://github.com/refly-ai/refly/blob/HEAD/config/provider-catalog.json) handles a key part of this chapter's functionality:
-
-```json
- "baseUrl": "https://api.siliconflow.cn/v1",
- "description": {
- "en": "SiliconFlow provides a one-stop cloud service platform with high-performance inference for top-tier large language and embedding models.",
- "zh-CN": "SiliconFlow 提供一站式云服务平台，为顶级大语言模型和嵌入模型提供高性能推理服务。"
- },
- "categories": ["llm", "embedding"],
- "documentation": "https://docs.siliconflow.cn/",
- "icon": "https://static.refly.ai/icons/providers/siliconflow.png"
- },
- {
- "name": "litellm",
- "providerKey": "openai",
- "baseUrl": "https://litellm.powerformer.net/v1",
- "description": {
- "en": "LiteLLM is a lightweight library to simplify LLM completion and embedding calls, providing a consistent interface for over 100 LLMs.",
- "zh-CN": "LiteLLM 是一个轻量级库，用于简化 LLM 的补全和嵌入调用，为 100 多个 LLM 提供一致的接口。"
- },
- "categories": ["llm", "embedding"],
- "documentation": "https://docs.litellm.ai/",
- "icon": "https://static.refly.ai/icons/providers/litellm.png"
- },
- {
- "name": "七牛云AI",
- "providerKey": "openai",
- "baseUrl": "https://api.qnaigc.com/v1",
- "description": {
- "en": "Qiniu AI provides efficient, stable, and secure model inference services, supporting mainstream open-source large models.",
- "zh-CN": "七牛云AI 提供高效、稳定、安全的模型推理服务，支持主流开源大模型。"
- },
- "categories": ["llm"],
- "documentation": "https://developer.qiniu.com/aitokenapi",
- "icon": "https://static.refly.ai/icons/providers/qiniu.png"
+### `cypress/support/commands.ts`
+
+The `Chainable` interface in [`cypress/support/commands.ts`](https://github.com/refly-ai/refly/blob/HEAD/cypress/support/commands.ts) handles a key part of this chapter's functionality:
+
+```ts
+// declare global {
+// namespace Cypress {
+// interface Chainable {
+// login(email: string, password: string): Chainable<void>
+// drag(subject: string, options?: Partial<TypeOptions>): Chainable<Element>
+// dismiss(subject: string, options?: Partial<TypeOptions>): Chainable<Element>
+// visit(originalFn: CommandOriginalFn, url: string, options: Partial<VisitOptions>): Chainable<Element>
+// }
+// }
+// }
+
+declare namespace Cypress {
+ interface Chainable {
+ /**
+ * Execute SQL query through Docker container
+ * @param query - SQL query to execute
+ * @example
+ * cy.execSQL('SELECT * FROM users')
+ */
+ execSQL(query: string): Chainable<string>;
+ /**
+ * Login to the app
+ * @param email - Email to login with
+ * @param password - Password to login with
+ * @example
+ * cy.login('test@example.com', 'testPassword123')
+ */
+ login(email: string, password: string): Chainable<void>;
+ }
+}
+
+Cypress.Commands.add('execSQL', (query: string) => {
```
This interface is important because it defines how Refly Tutorial: Build Deterministic Agent Skills and Ship Them Across APIs and Claude Code implements the patterns covered in this chapter.
@@ -139,7 +137,7 @@ This interface is important because it defines how Refly Tutorial: Build Determi
```mermaid
flowchart TD
- A[for]
- B[for]
+ A[Chainable]
+ B[Chainable]
A --> B
```
diff --git a/tutorials/refly-tutorial/05-refly-cli-and-claude-code-skill-export.md b/tutorials/refly-tutorial/05-refly-cli-and-claude-code-skill-export.md
index 3d2ebc09..713c2062 100644
--- a/tutorials/refly-tutorial/05-refly-cli-and-claude-code-skill-export.md
+++ b/tutorials/refly-tutorial/05-refly-cli-and-claude-code-skill-export.md
@@ -50,60 +50,85 @@ You now have a deterministic CLI path for building, validating, and exporting wo
Next: [Chapter 6: Observability, Deployment, and Operations](06-observability-deployment-and-operations.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `scripts/upload-config.js`
+### `docs/scripts/convert-webp.js`
-The `uploadState` function in [`scripts/upload-config.js`](https://github.com/refly-ai/refly/blob/HEAD/scripts/upload-config.js) handles a key part of this chapter's functionality:
+The `convertImagesToWebp` function in [`docs/scripts/convert-webp.js`](https://github.com/refly-ai/refly/blob/HEAD/docs/scripts/convert-webp.js) handles a key part of this chapter's functionality:
```js
-import { Client as MinioClient } from 'minio';
-
-async function uploadState(sourceFile, targetPath) {
- const minioClient = new MinioClient({
- endPoint: process.env.MINIO_EXTERNAL_ENDPOINT,
- port: Number.parseInt(process.env.MINIO_EXTERNAL_PORT || '443'),
- useSSL: process.env.MINIO_EXTERNAL_USE_SSL === 'true',
- accessKey: process.env.MINIO_EXTERNAL_ACCESS_KEY,
- secretKey: process.env.MINIO_EXTERNAL_SECRET_KEY,
- });
-
- const metaData = {
- 'Content-Type': 'application/json',
- };
- await minioClient.fPutObject(process.env.MINIO_EXTERNAL_BUCKET, targetPath, sourceFile, metaData);
-}
-
-async function main() {
- // upload mcp catalog
- await uploadState('config/mcp-catalog.json', 'mcp-config/mcp-catalog.json');
-
- await uploadState('config/provider-catalog.json', 'mcp-config/provider-catalog.json');
-}
-
-main();
-
+const imageMap = new Map();
+
+async function convertImagesToWebp() {
+ try {
+ const files = await fs.readdir(imagesDir);
+ const imageFiles = files.filter((file) => {
+ const ext = path.extname(file).toLowerCase();
+ return ['.png', '.jpg', '.jpeg', '.gif'].includes(ext);
+ });
+
+ console.log(`Found ${imageFiles.length} images to convert`);
+
+ for (const file of imageFiles) {
+ const inputPath = path.join(imagesDir, file);
+ const fileInfo = path.parse(file);
+ const outputPath = path.join(imagesDir, `${fileInfo.name}.webp`);
+
+ try {
+ // Convert to WebP
+ await sharp(inputPath).webp({ quality: 80 }).toFile(outputPath);
+
+ // Store the mapping from original path to WebP path (for use in Markdown replacements)
+ const originalRelativePath = path.join('/images', file);
+ const webpRelativePath = path.join('/images', `${fileInfo.name}.webp`);
+ imageMap.set(originalRelativePath, webpRelativePath);
+
+ // Remove the original file
+ await fs.unlink(inputPath);
+
+ console.log(`Converted and replaced: ${file} -> ${fileInfo.name}.webp`);
+ } catch (error) {
+ console.error(`Error converting ${file}: ${error.message}`);
```
This function is important because it defines how Refly Tutorial: Build Deterministic Agent Skills and Ship Them Across APIs and Claude Code implements the patterns covered in this chapter.
-### `scripts/upload-config.js`
+### `docs/scripts/convert-webp.js`
-The `main` function in [`scripts/upload-config.js`](https://github.com/refly-ai/refly/blob/HEAD/scripts/upload-config.js) handles a key part of this chapter's functionality:
+The `findMarkdownFiles` function in [`docs/scripts/convert-webp.js`](https://github.com/refly-ai/refly/blob/HEAD/docs/scripts/convert-webp.js) handles a key part of this chapter's functionality:
```js
}
-async function main() {
- // upload mcp catalog
- await uploadState('config/mcp-catalog.json', 'mcp-config/mcp-catalog.json');
-
- await uploadState('config/provider-catalog.json', 'mcp-config/provider-catalog.json');
+async function findMarkdownFiles(dir) {
+ const result = [];
+ const entries = await fs.readdir(dir, { withFileTypes: true });
+
+ for (const entry of entries) {
+ const fullPath = path.join(dir, entry.name);
+
+ if (entry.isDirectory()) {
+ // Skip node_modules and .git directories
+ if (entry.name !== 'node_modules' && entry.name !== '.git') {
+ const nestedFiles = await findMarkdownFiles(fullPath);
+ result.push(...nestedFiles);
+ }
+ } else if (entry.name.endsWith('.md')) {
+ result.push(fullPath);
+ }
+ }
+
+ return result;
}
-main();
+async function updateMarkdownFiles() {
+ try {
+ const markdownFiles = await findMarkdownFiles(rootDir);
+ console.log(`Found ${markdownFiles.length} Markdown files to update`);
+
+ for (const file of markdownFiles) {
+ let content = await fs.readFile(file, 'utf-8');
+ let modified = false;
```
@@ -114,7 +139,7 @@ This function is important because it defines how Refly Tutorial: Build Determin
```mermaid
flowchart TD
- A[uploadState]
- B[main]
+ A[convertImagesToWebp]
+ B[findMarkdownFiles]
A --> B
```
diff --git a/tutorials/refly-tutorial/06-observability-deployment-and-operations.md b/tutorials/refly-tutorial/06-observability-deployment-and-operations.md
index 1f393d1e..99ed1158 100644
--- a/tutorials/refly-tutorial/06-observability-deployment-and-operations.md
+++ b/tutorials/refly-tutorial/06-observability-deployment-and-operations.md
@@ -50,98 +50,80 @@ You now have a baseline operational model for running Refly beyond local experim
Next: [Chapter 7: Troubleshooting, Safety, and Cost Controls](07-troubleshooting-safety-and-cost-controls.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `cypress/support/commands.ts`
-
-The `Chainable` interface in [`cypress/support/commands.ts`](https://github.com/refly-ai/refly/blob/HEAD/cypress/support/commands.ts) handles a key part of this chapter's functionality:
-
-```ts
-// declare global {
-// namespace Cypress {
-// interface Chainable {
-// login(email: string, password: string): Chainable<void>
-// drag(subject: string, options?: Partial<TypeOptions>): Chainable<Element>
-// dismiss(subject: string, options?: Partial<TypeOptions>): Chainable<Element>
-// visit(originalFn: CommandOriginalFn, url: string, options: Partial<VisitOptions>): Chainable<Element>
-// }
-// }
-// }
-
-declare namespace Cypress {
- interface Chainable {
- /**
- * Execute SQL query through Docker container
- * @param query - SQL query to execute
- * @example
- * cy.execSQL('SELECT * FROM users')
- */
- execSQL(query: string): Chainable<string>;
- /**
- * Login to the app
- * @param email - Email to login with
- * @param password - Password to login with
- * @example
- * cy.login('test@example.com', 'testPassword123')
- */
- login(email: string, password: string): Chainable<void>;
- }
+### `docs/scripts/convert-webp.js`
+
+The `updateMarkdownFiles` function in [`docs/scripts/convert-webp.js`](https://github.com/refly-ai/refly/blob/HEAD/docs/scripts/convert-webp.js) handles a key part of this chapter's functionality:
+
+```js
}
-Cypress.Commands.add('execSQL', (query: string) => {
+async function updateMarkdownFiles() {
+ try {
+ const markdownFiles = await findMarkdownFiles(rootDir);
+ console.log(`Found ${markdownFiles.length} Markdown files to update`);
+
+ for (const file of markdownFiles) {
+ let content = await fs.readFile(file, 'utf-8');
+ let modified = false;
+
+ // Replace image links in Markdown
+ // This regex matches Markdown image syntax: 
+ const regex = /!\[([^\]]*)\]\(([^)]+)\)/g;
+
+ content = content.replace(regex, (match, alt, imagePath) => {
+ // Normalize the path to handle different formats
+ const normalizedPath = imagePath.trim();
+
+ // Check if this image is in our map
+ for (const [originalPath, webpPath] of imageMap.entries()) {
+ if (normalizedPath.includes(originalPath)) {
+ modified = true;
+ return ``;
+ }
+ }
+
+ // If no match found, return the original
+ return match;
+ });
+
+ // Also handle HTML img tags
```
-This interface is important because it defines how Refly Tutorial: Build Deterministic Agent Skills and Ship Them Across APIs and Claude Code implements the patterns covered in this chapter.
-
-### `cypress/support/commands.ts`
-
-The `Chainable` interface in [`cypress/support/commands.ts`](https://github.com/refly-ai/refly/blob/HEAD/cypress/support/commands.ts) handles a key part of this chapter's functionality:
-
-```ts
-// declare global {
-// namespace Cypress {
-// interface Chainable {
-// login(email: string, password: string): Chainable<void>
-// drag(subject: string, options?: Partial<TypeOptions>): Chainable<Element>
-// dismiss(subject: string, options?: Partial<TypeOptions>): Chainable<Element>
-// visit(originalFn: CommandOriginalFn, url: string, options: Partial<VisitOptions>): Chainable<Element>
-// }
-// }
-// }
-
-declare namespace Cypress {
- interface Chainable {
- /**
- * Execute SQL query through Docker container
- * @param query - SQL query to execute
- * @example
- * cy.execSQL('SELECT * FROM users')
- */
- execSQL(query: string): Chainable<string>;
- /**
- * Login to the app
- * @param email - Email to login with
- * @param password - Password to login with
- * @example
- * cy.login('test@example.com', 'testPassword123')
- */
- login(email: string, password: string): Chainable<void>;
- }
+This function is important because it defines how Refly Tutorial: Build Deterministic Agent Skills and Ship Them Across APIs and Claude Code implements the patterns covered in this chapter.
+
+### `docs/scripts/convert-webp.js`
+
+The `main` function in [`docs/scripts/convert-webp.js`](https://github.com/refly-ai/refly/blob/HEAD/docs/scripts/convert-webp.js) handles a key part of this chapter's functionality:
+
+```js
+}
+
+async function main() {
+ console.log('Starting image conversion and Markdown update process...');
+
+ await convertImagesToWebp();
+ await updateMarkdownFiles();
+
+ console.log('Process completed successfully!');
}
-Cypress.Commands.add('execSQL', (query: string) => {
+main().catch((error) => {
+ console.error('An error occurred:', error);
+ process.exit(1);
+});
+
```
-This interface is important because it defines how Refly Tutorial: Build Deterministic Agent Skills and Ship Them Across APIs and Claude Code implements the patterns covered in this chapter.
+This function is important because it defines how Refly Tutorial: Build Deterministic Agent Skills and Ship Them Across APIs and Claude Code implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[Chainable]
- B[Chainable]
+ A[updateMarkdownFiles]
+ B[main]
A --> B
```
diff --git a/tutorials/refly-tutorial/07-troubleshooting-safety-and-cost-controls.md b/tutorials/refly-tutorial/07-troubleshooting-safety-and-cost-controls.md
index 972cf4d1..5b38377f 100644
--- a/tutorials/refly-tutorial/07-troubleshooting-safety-and-cost-controls.md
+++ b/tutorials/refly-tutorial/07-troubleshooting-safety-and-cost-controls.md
@@ -48,51 +48,8 @@ You now have a practical troubleshooting and safety playbook for Refly operation
Next: [Chapter 8: Contribution Workflow and Governance](08-contribution-workflow-and-governance.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `apps/web/tailwind.config.ts`
-
-The `defineConfig` function in [`apps/web/tailwind.config.ts`](https://github.com/refly-ai/refly/blob/HEAD/apps/web/tailwind.config.ts) handles a key part of this chapter's functionality:
-
-```ts
-});
-
-export function defineConfig(): Config {
- return {
- darkMode: 'class',
- plugins: [AntdOverwritePlugin],
- corePlugins: {
- preflight: false,
- },
- content,
- theme: {
- extend: {
- gridTemplateColumns: {
- // Custom grid columns for avatar wall
- '13': 'repeat(13, minmax(0, 1fr))',
- '14': 'repeat(14, minmax(0, 1fr))',
- '15': 'repeat(15, minmax(0, 1fr))',
- '16': 'repeat(16, minmax(0, 1fr))',
- },
- fontFamily: {
- inter: ['Inter', 'sans-serif'],
- 'architects-daughter': ['"Architects Daughter"', 'sans-serif'],
- },
- fontSize: {
- xs: ['12px', '20px'],
- sm: ['14px', '22px'],
- base: ['16px', '24px'],
- lg: ['18px', '28px'],
- xl: ['20px', '30px'],
- '2xl': ['24px', '36px'],
- },
- animation: {
-```
-
-This function is important because it defines how Refly Tutorial: Build Deterministic Agent Skills and Ship Them Across APIs and Claude Code implements the patterns covered in this chapter.
-
### `packages/cli/tsup.config.ts`
The `getDefaultEndpoint` function in [`packages/cli/tsup.config.ts`](https://github.com/refly-ai/refly/blob/HEAD/packages/cli/tsup.config.ts) handles a key part of this chapter's functionality:
@@ -134,12 +91,53 @@ export default defineConfig({
This function is important because it defines how Refly Tutorial: Build Deterministic Agent Skills and Ship Them Across APIs and Claude Code implements the patterns covered in this chapter.
+### `packages/cli/tsup.config.ts`
+
+The `getDefaultWebUrl` function in [`packages/cli/tsup.config.ts`](https://github.com/refly-ai/refly/blob/HEAD/packages/cli/tsup.config.ts) handles a key part of this chapter's functionality:
+
+```ts
+
+// Determine the default Web URL based on build environment
+function getDefaultWebUrl(): string {
+ if (customWebUrl) return customWebUrl;
+ if (customEndpoint) return customEndpoint; // Assume same domain if only endpoint specified
+ return ENV_CONFIG[buildEnv]?.webUrl ?? ENV_CONFIG.production.webUrl;
+}
+
+// Determine the npm tag based on build environment
+function getNpmTag(): string {
+ return ENV_CONFIG[buildEnv]?.npmTag ?? 'latest';
+}
+
+const defaultEndpoint = getDefaultEndpoint();
+const defaultWebUrl = getDefaultWebUrl();
+const npmTag = getNpmTag();
+
+console.log(`[tsup] Building CLI for environment: ${buildEnv}`);
+console.log(`[tsup] CLI version: ${cliVersion}`);
+console.log(`[tsup] NPM tag: ${npmTag}`);
+console.log(`[tsup] Default API endpoint: ${defaultEndpoint}`);
+console.log(`[tsup] Default Web URL: ${defaultWebUrl}`);
+
+export default defineConfig({
+ entry: {
+ 'bin/refly': 'src/bin/refly.ts',
+ index: 'src/index.ts',
+ },
+ format: ['cjs'],
+ target: 'node18',
+ clean: true,
+ dts: true,
+```
+
+This function is important because it defines how Refly Tutorial: Build Deterministic Agent Skills and Ship Them Across APIs and Claude Code implements the patterns covered in this chapter.
+
## How These Components Connect
```mermaid
flowchart TD
- A[defineConfig]
- B[getDefaultEndpoint]
+ A[getDefaultEndpoint]
+ B[getDefaultWebUrl]
A --> B
```
diff --git a/tutorials/refly-tutorial/08-contribution-workflow-and-governance.md b/tutorials/refly-tutorial/08-contribution-workflow-and-governance.md
index f78bdcff..eb13a7db 100644
--- a/tutorials/refly-tutorial/08-contribution-workflow-and-governance.md
+++ b/tutorials/refly-tutorial/08-contribution-workflow-and-governance.md
@@ -50,53 +50,10 @@ Next steps:
- export and test one skill in your Claude Code environment
- contribute one focused improvement with docs and validation notes
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `packages/cli/tsup.config.ts`
-The `getDefaultWebUrl` function in [`packages/cli/tsup.config.ts`](https://github.com/refly-ai/refly/blob/HEAD/packages/cli/tsup.config.ts) handles a key part of this chapter's functionality:
-
-```ts
-
-// Determine the default Web URL based on build environment
-function getDefaultWebUrl(): string {
- if (customWebUrl) return customWebUrl;
- if (customEndpoint) return customEndpoint; // Assume same domain if only endpoint specified
- return ENV_CONFIG[buildEnv]?.webUrl ?? ENV_CONFIG.production.webUrl;
-}
-
-// Determine the npm tag based on build environment
-function getNpmTag(): string {
- return ENV_CONFIG[buildEnv]?.npmTag ?? 'latest';
-}
-
-const defaultEndpoint = getDefaultEndpoint();
-const defaultWebUrl = getDefaultWebUrl();
-const npmTag = getNpmTag();
-
-console.log(`[tsup] Building CLI for environment: ${buildEnv}`);
-console.log(`[tsup] CLI version: ${cliVersion}`);
-console.log(`[tsup] NPM tag: ${npmTag}`);
-console.log(`[tsup] Default API endpoint: ${defaultEndpoint}`);
-console.log(`[tsup] Default Web URL: ${defaultWebUrl}`);
-
-export default defineConfig({
- entry: {
- 'bin/refly': 'src/bin/refly.ts',
- index: 'src/index.ts',
- },
- format: ['cjs'],
- target: 'node18',
- clean: true,
- dts: true,
-```
-
-This function is important because it defines how Refly Tutorial: Build Deterministic Agent Skills and Ship Them Across APIs and Claude Code implements the patterns covered in this chapter.
-
-### `packages/cli/tsup.config.ts`
-
The `getNpmTag` function in [`packages/cli/tsup.config.ts`](https://github.com/refly-ai/refly/blob/HEAD/packages/cli/tsup.config.ts) handles a key part of this chapter's functionality:
```ts
@@ -136,12 +93,53 @@ export default defineConfig({
This function is important because it defines how Refly Tutorial: Build Deterministic Agent Skills and Ship Them Across APIs and Claude Code implements the patterns covered in this chapter.
+### `scripts/cleanup-node-modules.js`
+
+The `findNodeModules` function in [`scripts/cleanup-node-modules.js`](https://github.com/refly-ai/refly/blob/HEAD/scripts/cleanup-node-modules.js) handles a key part of this chapter's functionality:
+
+```js
+ * @param {string[]} nodeModulesPaths - Array to collect found paths
+ */
+function findNodeModules(dir, nodeModulesPaths = []) {
+ try {
+ const items = fs.readdirSync(dir, { withFileTypes: true });
+
+ for (const item of items) {
+ if (item.isDirectory()) {
+ const fullPath = path.join(dir, item.name);
+
+ if (item.name === 'node_modules') {
+ nodeModulesPaths.push(fullPath);
+ console.log(`Found: ${fullPath}`);
+ } else {
+ // Skip common directories that shouldn't contain node_modules we want to delete
+ const skipDirs = ['.git', '.turbo', 'dist', 'build', 'coverage', '.next', '.nuxt'];
+ if (!skipDirs.includes(item.name)) {
+ findNodeModules(fullPath, nodeModulesPaths);
+ }
+ }
+ }
+ }
+ } catch (error) {
+ // Skip directories we can't read (permission issues, etc.)
+ console.warn(`Warning: Could not read directory ${dir}: ${error.message}`);
+ }
+
+ return nodeModulesPaths;
+}
+
+/**
+ * Delete a directory recursively
+```
+
+This function is important because it defines how Refly Tutorial: Build Deterministic Agent Skills and Ship Them Across APIs and Claude Code implements the patterns covered in this chapter.
+
## How These Components Connect
```mermaid
flowchart TD
- A[getDefaultWebUrl]
- B[getNpmTag]
+ A[getNpmTag]
+ B[findNodeModules]
A --> B
```
diff --git a/tutorials/roo-code-tutorial/01-getting-started.md b/tutorials/roo-code-tutorial/01-getting-started.md
index 096474a2..454ca877 100644
--- a/tutorials/roo-code-tutorial/01-getting-started.md
+++ b/tutorials/roo-code-tutorial/01-getting-started.md
@@ -131,98 +131,24 @@ You now have Roo Code running with:
Next: [Chapter 2: Modes and Task Design](02-modes-and-task-design.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `scripts/find-missing-i18n-key.js`
-
-The `getLocaleDirs` function in [`scripts/find-missing-i18n-key.js`](https://github.com/RooCodeInc/Roo-Code/blob/HEAD/scripts/find-missing-i18n-key.js) handles a key part of this chapter's functionality:
-
-```js
-
-// Get all language directories for a specific locales directory
-function getLocaleDirs(localesDir) {
- try {
- const allLocales = fs.readdirSync(localesDir).filter((file) => {
- const stats = fs.statSync(path.join(localesDir, file))
- return stats.isDirectory() // Do not exclude any language directories
- })
-
- // Filter to a specific language if specified
- return args.locale ? allLocales.filter((locale) => locale === args.locale) : allLocales
- } catch (error) {
- if (error.code === "ENOENT") {
- console.warn(`Warning: Locales directory not found: ${localesDir}`)
- return []
- }
- throw error
- }
-}
-
-// Get the value from JSON by path
-function getValueByPath(obj, path) {
- const parts = path.split(".")
- let current = obj
-
- for (const part of parts) {
- if (current === undefined || current === null) {
- return undefined
- }
- current = current[part]
- }
-
-```
-
-This function is important because it defines how Roo Code Tutorial: Run an AI Dev Team in Your Editor implements the patterns covered in this chapter.
-
-### `scripts/find-missing-i18n-key.js`
-
-The `getValueByPath` function in [`scripts/find-missing-i18n-key.js`](https://github.com/RooCodeInc/Roo-Code/blob/HEAD/scripts/find-missing-i18n-key.js) handles a key part of this chapter's functionality:
-
-```js
-
-// Get the value from JSON by path
-function getValueByPath(obj, path) {
- const parts = path.split(".")
- let current = obj
-
- for (const part of parts) {
- if (current === undefined || current === null) {
- return undefined
- }
- current = current[part]
- }
-
- return current
-}
-
-// Check if the key exists in all language files, return a list of missing language files
-function checkKeyInLocales(key, localeDirs, localesDir) {
- const [file, ...pathParts] = key.split(":")
- const jsonPath = pathParts.join(".")
-
- const missingLocales = []
-
- localeDirs.forEach((locale) => {
- const filePath = path.join(localesDir, locale, `${file}.json`)
- if (!fs.existsSync(filePath)) {
- missingLocales.push(`${locale}/${file}.json`)
- return
- }
-
- const json = JSON.parse(fs.readFileSync(filePath, "utf8"))
- if (getValueByPath(json, jsonPath) === undefined) {
-```
+Use the following upstream sources to verify getting started and initial setup details while reading this chapter:
-This function is important because it defines how Roo Code Tutorial: Run an AI Dev Team in Your Editor implements the patterns covered in this chapter.
+- [`src/extension.ts`](https://github.com/RooCodeInc/Roo-Code/blob/HEAD/src/extension.ts) — the VS Code extension entry point that registers commands, activates the Roo Code sidebar, initializes the task manager, and sets up MCP server connections on first load.
+- [`src/core/task/index.ts`](https://github.com/RooCodeInc/Roo-Code/blob/HEAD/src/core/task/index.ts) — the task manager that drives Roo Code's core loop: receiving user messages, dispatching to the model, handling tool approvals, and managing the conversation lifecycle.
+Suggested trace strategy:
+- read `src/extension.ts` `activate()` function to understand the full initialization sequence when Roo Code first loads
+- trace `src/core/task/index.ts` constructor and `initiateTaskLoop` to understand how a first task invocation is structured
+- check `src/shared/ExtensionMessage.ts` for the message types exchanged between the extension and webview during setup
## How These Components Connect
```mermaid
-flowchart TD
- A[getLocaleDirs]
- B[getValueByPath]
- A --> B
+flowchart LR
+ A[VS Code activates extension] --> B[extension.ts activate]
+ B --> C[Sidebar and commands registered]
+ B --> D[Task manager initialized in task/index.ts]
+ D --> E[First user message triggers task loop]
```
diff --git a/tutorials/roo-code-tutorial/02-modes-and-task-design.md b/tutorials/roo-code-tutorial/02-modes-and-task-design.md
index b5db889e..2067d73f 100644
--- a/tutorials/roo-code-tutorial/02-modes-and-task-design.md
+++ b/tutorials/roo-code-tutorial/02-modes-and-task-design.md
@@ -110,98 +110,23 @@ You now have a mode-driven execution framework that supports:
Next: [Chapter 3: File and Command Operations](03-file-and-command-operations.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `scripts/find-missing-i18n-key.js`
-
-The `checkKeyInLocales` function in [`scripts/find-missing-i18n-key.js`](https://github.com/RooCodeInc/Roo-Code/blob/HEAD/scripts/find-missing-i18n-key.js) handles a key part of this chapter's functionality:
-
-```js
-
-// Check if the key exists in all language files, return a list of missing language files
-function checkKeyInLocales(key, localeDirs, localesDir) {
- const [file, ...pathParts] = key.split(":")
- const jsonPath = pathParts.join(".")
-
- const missingLocales = []
-
- localeDirs.forEach((locale) => {
- const filePath = path.join(localesDir, locale, `${file}.json`)
- if (!fs.existsSync(filePath)) {
- missingLocales.push(`${locale}/${file}.json`)
- return
- }
-
- const json = JSON.parse(fs.readFileSync(filePath, "utf8"))
- if (getValueByPath(json, jsonPath) === undefined) {
- missingLocales.push(`${locale}/${file}.json`)
- }
- })
-
- return missingLocales
-}
-
-// Recursively traverse the directory
-function findMissingI18nKeys() {
- const results = []
-
- function walk(dir, baseDir, localeDirs, localesDir) {
- const files = fs.readdirSync(dir)
-
- for (const file of files) {
-```
-
-This function is important because it defines how Roo Code Tutorial: Run an AI Dev Team in Your Editor implements the patterns covered in this chapter.
-
-### `scripts/find-missing-i18n-key.js`
-
-The `findMissingI18nKeys` function in [`scripts/find-missing-i18n-key.js`](https://github.com/RooCodeInc/Roo-Code/blob/HEAD/scripts/find-missing-i18n-key.js) handles a key part of this chapter's functionality:
-
-```js
-
-// Recursively traverse the directory
-function findMissingI18nKeys() {
- const results = []
-
- function walk(dir, baseDir, localeDirs, localesDir) {
- const files = fs.readdirSync(dir)
+Use the following upstream sources to verify mode-related implementation details while reading this chapter:
- for (const file of files) {
- const filePath = path.join(dir, file)
- const stat = fs.statSync(filePath)
-
- // Exclude test files and __mocks__ directory
- if (filePath.includes(".test.") || filePath.includes("__mocks__")) continue
-
- if (stat.isDirectory()) {
- walk(filePath, baseDir, localeDirs, localesDir) // Recursively traverse subdirectories
- } else if (stat.isFile() && [".ts", ".tsx", ".js", ".jsx"].includes(path.extname(filePath))) {
- const content = fs.readFileSync(filePath, "utf8")
-
- // Match all i18n keys
- for (const pattern of i18nPatterns) {
- let match
- while ((match = pattern.exec(content)) !== null) {
- const key = match[1]
- const missingLocales = checkKeyInLocales(key, localeDirs, localesDir)
- if (missingLocales.length > 0) {
- results.push({
- key,
- missingLocales,
- file: path.relative(baseDir, filePath),
- })
-```
-
-This function is important because it defines how Roo Code Tutorial: Run an AI Dev Team in Your Editor implements the patterns covered in this chapter.
+- [`src/shared/modes.ts`](https://github.com/RooCodeInc/Roo-Code/blob/HEAD/src/shared/modes.ts) — defines mode identifiers, slug constants, and the mode registry that drives mode selection behavior in Roo Code.
+- [`src/core/prompts/system.ts`](https://github.com/RooCodeInc/Roo-Code/blob/HEAD/src/core/prompts/system.ts) — contains the system prompt construction logic used for each mode, showing how mode context shapes agent behavior.
+Suggested trace strategy:
+- search the `src/shared/modes.ts` file for mode slug definitions and the `ModeConfig` type to understand mode attributes
+- compare system prompt differences across modes in `system.ts` to understand capability boundaries
+- check `src/extension.ts` for mode-switching entry points triggered from the VS Code UI
## How These Components Connect
```mermaid
-flowchart TD
- A[checkKeyInLocales]
- B[findMissingI18nKeys]
- A --> B
+flowchart LR
+ A[User selects mode] --> B[modes.ts registry]
+ B --> C[system.ts prompt builder]
+ C --> D[Agent receives mode-scoped context]
```
diff --git a/tutorials/roo-code-tutorial/03-file-and-command-operations.md b/tutorials/roo-code-tutorial/03-file-and-command-operations.md
index 9319a8c1..3396182b 100644
--- a/tutorials/roo-code-tutorial/03-file-and-command-operations.md
+++ b/tutorials/roo-code-tutorial/03-file-and-command-operations.md
@@ -100,98 +100,24 @@ You now have a governance model for Roo edit/command loops:
Next: [Chapter 4: Context and Indexing](04-context-and-indexing.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `scripts/find-missing-i18n-key.js`
-
-The `walk` function in [`scripts/find-missing-i18n-key.js`](https://github.com/RooCodeInc/Roo-Code/blob/HEAD/scripts/find-missing-i18n-key.js) handles a key part of this chapter's functionality:
-
-```js
- const results = []
-
- function walk(dir, baseDir, localeDirs, localesDir) {
- const files = fs.readdirSync(dir)
-
- for (const file of files) {
- const filePath = path.join(dir, file)
- const stat = fs.statSync(filePath)
-
- // Exclude test files and __mocks__ directory
- if (filePath.includes(".test.") || filePath.includes("__mocks__")) continue
-
- if (stat.isDirectory()) {
- walk(filePath, baseDir, localeDirs, localesDir) // Recursively traverse subdirectories
- } else if (stat.isFile() && [".ts", ".tsx", ".js", ".jsx"].includes(path.extname(filePath))) {
- const content = fs.readFileSync(filePath, "utf8")
-
- // Match all i18n keys
- for (const pattern of i18nPatterns) {
- let match
- while ((match = pattern.exec(content)) !== null) {
- const key = match[1]
- const missingLocales = checkKeyInLocales(key, localeDirs, localesDir)
- if (missingLocales.length > 0) {
- results.push({
- key,
- missingLocales,
- file: path.relative(baseDir, filePath),
- })
- }
- }
- }
-```
-
-This function is important because it defines how Roo Code Tutorial: Run an AI Dev Team in Your Editor implements the patterns covered in this chapter.
-
-### `scripts/find-missing-i18n-key.js`
-
-The `main` function in [`scripts/find-missing-i18n-key.js`](https://github.com/RooCodeInc/Roo-Code/blob/HEAD/scripts/find-missing-i18n-key.js) handles a key part of this chapter's functionality:
-
-```js
-
-// Execute and output the results
-function main() {
- try {
- if (args.locale) {
- // Check if the specified locale exists in any of the locales directories
- const localeExists = Object.values(DIRS).some((config) => {
- const localeDirs = getLocaleDirs(config.localesDir)
- return localeDirs.includes(args.locale)
- })
-
- if (!localeExists) {
- console.error(`Error: Language '${args.locale}' not found in any locales directory`)
- process.exit(1)
- }
- }
-
- const missingKeys = findMissingI18nKeys()
-
- if (missingKeys.length === 0) {
- console.log("\n✅ All i18n keys are present!")
- return
- }
-
- console.log("\nMissing i18n keys:\n")
- missingKeys.forEach(({ key, missingLocales, file }) => {
- console.log(`File: ${file}`)
- console.log(`Key: ${key}`)
- console.log("Missing in:")
- missingLocales.forEach((file) => console.log(` - ${file}`))
- console.log("-------------------")
- })
-```
+Use the following upstream sources to verify file and command operation implementation details while reading this chapter:
-This function is important because it defines how Roo Code Tutorial: Run an AI Dev Team in Your Editor implements the patterns covered in this chapter.
+- [`src/core/tools/`](https://github.com/RooCodeInc/Roo-Code/blob/HEAD/src/core/tools/) — contains the tool handler implementations for file read/write, command execution, diff application, and search operations that drive Roo Code's file and terminal interaction model.
+- [`src/core/task/index.ts`](https://github.com/RooCodeInc/Roo-Code/blob/HEAD/src/core/task/index.ts) — manages the task execution lifecycle including approval checkpoints before file writes and terminal commands are executed.
+Suggested trace strategy:
+- browse `src/core/tools/` to find handlers like `write_to_file`, `execute_command`, and `apply_diff`
+- trace approval flow in `src/core/task/index.ts` to see where human confirmation is requested before destructive operations
+- check `src/shared/tool-groups.ts` for tool grouping that controls which tools are available in each mode
## How These Components Connect
```mermaid
-flowchart TD
- A[walk]
- B[main]
- A --> B
+flowchart LR
+ A[Agent plan] --> B[Tool call: write or execute]
+ B --> C[Approval checkpoint in task/index.ts]
+ C --> D[Tool handler in core/tools/]
+ D --> E[File system or terminal output]
```
diff --git a/tutorials/roo-code-tutorial/04-context-and-indexing.md b/tutorials/roo-code-tutorial/04-context-and-indexing.md
index 67b18a9c..9a71db32 100644
--- a/tutorials/roo-code-tutorial/04-context-and-indexing.md
+++ b/tutorials/roo-code-tutorial/04-context-and-indexing.md
@@ -102,98 +102,23 @@ You now have a context/indexing model for large repos:
Next: [Chapter 5: Checkpoints and Recovery](05-checkpoints-and-recovery.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `webview-ui/vite.config.ts`
-
-The `getGitSha` function in [`webview-ui/vite.config.ts`](https://github.com/RooCodeInc/Roo-Code/blob/HEAD/webview-ui/vite.config.ts) handles a key part of this chapter's functionality:
-
-```ts
-import { sourcemapPlugin } from "./src/vite-plugins/sourcemapPlugin"
-
-function getGitSha() {
- let gitSha: string | undefined = undefined
-
- try {
- gitSha = execSync("git rev-parse HEAD").toString().trim()
- } catch (_error) {
- // Do nothing.
- }
-
- return gitSha
-}
-
-const wasmPlugin = (): Plugin => ({
- name: "wasm",
- async load(id) {
- if (id.endsWith(".wasm")) {
- const wasmBinary = await import(id)
-
- return `
- const wasmModule = new WebAssembly.Module(${wasmBinary.default});
- export default wasmModule;
- `
- }
- },
-})
-
-const persistPortPlugin = (): Plugin => ({
- name: "write-port-to-file",
- configureServer(viteDevServer) {
- viteDevServer?.httpServer?.once("listening", () => {
-```
-
-This function is important because it defines how Roo Code Tutorial: Run an AI Dev Team in Your Editor implements the patterns covered in this chapter.
-
-### `scripts/find-missing-translations.js`
+Use the following upstream sources to verify context and indexing implementation details while reading this chapter:
-The `findKeys` function in [`scripts/find-missing-translations.js`](https://github.com/RooCodeInc/Roo-Code/blob/HEAD/scripts/find-missing-translations.js) handles a key part of this chapter's functionality:
-
-```js
-
-// Recursively find all keys in an object
-function findKeys(obj, parentKey = "") {
- let keys = []
-
- for (const [key, value] of Object.entries(obj)) {
- const currentKey = parentKey ? `${parentKey}.${key}` : key
-
- if (typeof value === "object" && value !== null) {
- // If value is an object, recurse
- keys = [...keys, ...findKeys(value, currentKey)]
- } else {
- // If value is a primitive, add the key
- keys.push(currentKey)
- }
- }
-
- return keys
-}
-
-// Get value at a dotted path in an object
-function getValueAtPath(obj, path) {
- const parts = path.split(".")
- let current = obj
-
- for (const part of parts) {
- if (current === undefined || current === null) {
- return undefined
- }
- current = current[part]
- }
-
-```
-
-This function is important because it defines how Roo Code Tutorial: Run an AI Dev Team in Your Editor implements the patterns covered in this chapter.
+- [`src/services/glob/list-files.ts`](https://github.com/RooCodeInc/Roo-Code/blob/HEAD/src/services/glob/list-files.ts) — implements repository file listing and glob filtering used to build the file tree that Roo Code sends to the model as workspace context.
+- [`src/core/context-management/`](https://github.com/RooCodeInc/Roo-Code/blob/HEAD/src/core/context-management/) — contains context window management utilities that truncate, slice, and prioritize messages to stay within model token limits.
+Suggested trace strategy:
+- trace how `list-files.ts` builds file manifests that feed into context window construction
+- review context-management utilities to understand truncation strategies when context grows large
+- look at `src/shared/context-window-utils.ts` for token-limit calculations applied before each request
## How These Components Connect
```mermaid
-flowchart TD
- A[getGitSha]
- B[findKeys]
- A --> B
+flowchart LR
+ A[Workspace files] --> B[list-files.ts glob scan]
+ B --> C[Context window manager]
+ C --> D[Truncated context sent to model]
```
diff --git a/tutorials/roo-code-tutorial/05-checkpoints-and-recovery.md b/tutorials/roo-code-tutorial/05-checkpoints-and-recovery.md
index ba46bcfb..f5c89e52 100644
--- a/tutorials/roo-code-tutorial/05-checkpoints-and-recovery.md
+++ b/tutorials/roo-code-tutorial/05-checkpoints-and-recovery.md
@@ -88,98 +88,23 @@ You now have a checkpoint-driven reliability model:
Next: [Chapter 6: MCP and Tool Extensions](06-mcp-and-tool-extensions.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `scripts/find-missing-translations.js`
-
-The `getValueAtPath` function in [`scripts/find-missing-translations.js`](https://github.com/RooCodeInc/Roo-Code/blob/HEAD/scripts/find-missing-translations.js) handles a key part of this chapter's functionality:
-
-```js
-
-// Get value at a dotted path in an object
-function getValueAtPath(obj, path) {
- const parts = path.split(".")
- let current = obj
-
- for (const part of parts) {
- if (current === undefined || current === null) {
- return undefined
- }
- current = current[part]
- }
-
- return current
-}
-
-// Shared utility to safely parse JSON files with error handling
-async function parseJsonFile(filePath) {
- try {
- const content = await readFile(filePath, "utf8")
- return JSON.parse(content)
- } catch (error) {
- if (error.code === "ENOENT") {
- return null // File doesn't exist
- }
- throw new Error(`Error parsing JSON file '${filePath}': ${error.message}`)
- }
-}
-
-// Validate that a JSON object has a flat structure (no nested objects)
-function validateFlatStructure(obj, filePath) {
- for (const [key, value] of Object.entries(obj)) {
-```
+Use the following upstream sources to verify checkpoint and recovery implementation details while reading this chapter:
-This function is important because it defines how Roo Code Tutorial: Run an AI Dev Team in Your Editor implements the patterns covered in this chapter.
-
-### `scripts/find-missing-translations.js`
-
-The `parseJsonFile` function in [`scripts/find-missing-translations.js`](https://github.com/RooCodeInc/Roo-Code/blob/HEAD/scripts/find-missing-translations.js) handles a key part of this chapter's functionality:
-
-```js
-
-// Shared utility to safely parse JSON files with error handling
-async function parseJsonFile(filePath) {
- try {
- const content = await readFile(filePath, "utf8")
- return JSON.parse(content)
- } catch (error) {
- if (error.code === "ENOENT") {
- return null // File doesn't exist
- }
- throw new Error(`Error parsing JSON file '${filePath}': ${error.message}`)
- }
-}
-
-// Validate that a JSON object has a flat structure (no nested objects)
-function validateFlatStructure(obj, filePath) {
- for (const [key, value] of Object.entries(obj)) {
- if (typeof value === "object" && value !== null) {
- console.error(`Error: ${filePath} should be a flat JSON structure. Found nested object at key '${key}'`)
- process.exit(1)
- }
- }
-}
-
-// Function to check translations for a specific area
-async function checkAreaTranslations(area) {
- const LOCALES_DIR = LOCALES_DIRS[area]
-
- // Get all locale directories (or filter to the specified locale)
- const dirContents = await readdir(LOCALES_DIR)
- const allLocales = await Promise.all(
- dirContents.map(async (item) => {
-```
-
-This function is important because it defines how Roo Code Tutorial: Run an AI Dev Team in Your Editor implements the patterns covered in this chapter.
+- [`src/integrations/checkpoints/`](https://github.com/RooCodeInc/Roo-Code/blob/HEAD/src/integrations/checkpoints/) — contains the checkpoint manager that captures task state snapshots using shadow git commits, enabling diff comparison and rollback between task steps.
+- [`src/core/task/index.ts`](https://github.com/RooCodeInc/Roo-Code/blob/HEAD/src/core/task/index.ts) — integrates with the checkpoint system to record state before destructive operations and expose restore/compare actions to the user.
+Suggested trace strategy:
+- trace checkpoint creation calls in `src/integrations/checkpoints/` to understand how shadow commits are structured
+- review `src/core/task/index.ts` for the task lifecycle points where checkpoints are triggered
+- check `src/shared/WebviewMessage.ts` for the message types that drive checkpoint UI interactions (restore, compare)
## How These Components Connect
```mermaid
-flowchart TD
- A[getValueAtPath]
- B[parseJsonFile]
- A --> B
+flowchart LR
+ A[Task step begins] --> B[Checkpoint captured in checkpoints/]
+ B --> C[Files modified]
+ C --> D[User can compare or restore via task/index.ts]
```
diff --git a/tutorials/roo-code-tutorial/06-mcp-and-tool-extensions.md b/tutorials/roo-code-tutorial/06-mcp-and-tool-extensions.md
index cc5990eb..7414377b 100644
--- a/tutorials/roo-code-tutorial/06-mcp-and-tool-extensions.md
+++ b/tutorials/roo-code-tutorial/06-mcp-and-tool-extensions.md
@@ -86,98 +86,24 @@ You now have a practical extension strategy for Roo Code:
Next: [Chapter 7: Profiles and Team Standards](07-profiles-and-team-standards.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `scripts/find-missing-translations.js`
-
-The `validateFlatStructure` function in [`scripts/find-missing-translations.js`](https://github.com/RooCodeInc/Roo-Code/blob/HEAD/scripts/find-missing-translations.js) handles a key part of this chapter's functionality:
-
-```js
-
-// Validate that a JSON object has a flat structure (no nested objects)
-function validateFlatStructure(obj, filePath) {
- for (const [key, value] of Object.entries(obj)) {
- if (typeof value === "object" && value !== null) {
- console.error(`Error: ${filePath} should be a flat JSON structure. Found nested object at key '${key}'`)
- process.exit(1)
- }
- }
-}
-
-// Function to check translations for a specific area
-async function checkAreaTranslations(area) {
- const LOCALES_DIR = LOCALES_DIRS[area]
-
- // Get all locale directories (or filter to the specified locale)
- const dirContents = await readdir(LOCALES_DIR)
- const allLocales = await Promise.all(
- dirContents.map(async (item) => {
- const stats = await stat(path.join(LOCALES_DIR, item))
- return stats.isDirectory() && item !== "en" ? item : null
- }),
- )
- const filteredLocales = allLocales.filter(Boolean)
-
- // Filter to the specified locale if provided
- const locales = args.locale ? filteredLocales.filter((locale) => locale === args.locale) : filteredLocales
-
- if (args.locale && locales.length === 0) {
- console.error(`Error: Locale '${args.locale}' not found in ${LOCALES_DIR}`)
- process.exit(1)
- }
-```
-
-This function is important because it defines how Roo Code Tutorial: Run an AI Dev Team in Your Editor implements the patterns covered in this chapter.
-
-### `scripts/find-missing-translations.js`
-
-The `checkAreaTranslations` function in [`scripts/find-missing-translations.js`](https://github.com/RooCodeInc/Roo-Code/blob/HEAD/scripts/find-missing-translations.js) handles a key part of this chapter's functionality:
-
-```js
-
-// Function to check translations for a specific area
-async function checkAreaTranslations(area) {
- const LOCALES_DIR = LOCALES_DIRS[area]
-
- // Get all locale directories (or filter to the specified locale)
- const dirContents = await readdir(LOCALES_DIR)
- const allLocales = await Promise.all(
- dirContents.map(async (item) => {
- const stats = await stat(path.join(LOCALES_DIR, item))
- return stats.isDirectory() && item !== "en" ? item : null
- }),
- )
- const filteredLocales = allLocales.filter(Boolean)
+Use the following upstream sources to verify MCP and tool extension implementation details while reading this chapter:
- // Filter to the specified locale if provided
- const locales = args.locale ? filteredLocales.filter((locale) => locale === args.locale) : filteredLocales
-
- if (args.locale && locales.length === 0) {
- console.error(`Error: Locale '${args.locale}' not found in ${LOCALES_DIR}`)
- process.exit(1)
- }
-
- console.log(
- `\n${area === "core" ? "BACKEND" : "FRONTEND"} - Checking ${locales.length} non-English locale(s): ${locales.join(", ")}`,
- )
-
- // Get all English JSON files
- const englishDir = path.join(LOCALES_DIR, "en")
- const englishDirContents = await readdir(englishDir)
- let englishFiles = englishDirContents.filter((file) => file.endsWith(".json") && !file.startsWith("."))
-
-```
-
-This function is important because it defines how Roo Code Tutorial: Run an AI Dev Team in Your Editor implements the patterns covered in this chapter.
+- [`src/shared/mcp.ts`](https://github.com/RooCodeInc/Roo-Code/blob/HEAD/src/shared/mcp.ts) — defines the MCP server configuration types and connection settings used to declare external tool servers in Roo Code's settings.
+- [`src/services/mcp/McpHub.ts`](https://github.com/RooCodeInc/Roo-Code/blob/HEAD/src/services/mcp/McpHub.ts) — manages the lifecycle of MCP server connections, tool discovery, and tool invocation routing for all registered MCP servers.
+Suggested trace strategy:
+- review the `McpServerConfig` type in `src/shared/mcp.ts` to understand what connection parameters are configurable
+- trace `McpHub.ts` for connection establishment, tool listing (`listTools`), and invocation flow
+- check `src/core/tools/use_mcp_tool.ts` for how the agent constructs MCP tool calls during task execution
## How These Components Connect
```mermaid
-flowchart TD
- A[validateFlatStructure]
- B[checkAreaTranslations]
- A --> B
+flowchart LR
+ A[mcp.ts config] --> B[McpHub.ts connection manager]
+ B --> C[MCP server process]
+ C --> D[use_mcp_tool.ts invocation]
+ D --> E[Tool result returned to agent]
```
diff --git a/tutorials/roo-code-tutorial/07-profiles-and-team-standards.md b/tutorials/roo-code-tutorial/07-profiles-and-team-standards.md
index 551c65dd..32bf946c 100644
--- a/tutorials/roo-code-tutorial/07-profiles-and-team-standards.md
+++ b/tutorials/roo-code-tutorial/07-profiles-and-team-standards.md
@@ -81,88 +81,86 @@ You now have a profile-driven scaling model for Roo Code:
Next: [Chapter 8: Enterprise Operations](08-enterprise-operations.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `scripts/find-missing-translations.js`
-
-The `outputResults` function in [`scripts/find-missing-translations.js`](https://github.com/RooCodeInc/Roo-Code/blob/HEAD/scripts/find-missing-translations.js) handles a key part of this chapter's functionality:
-
-```js
- )
-
- return { missingTranslations, hasMissingTranslations: outputResults(missingTranslations, area) }
-}
-
-// Function to output results for an area
-function outputResults(missingTranslations, area) {
- let hasMissingTranslations = false
-
- console.log(`\n${area === "core" ? "BACKEND" : "FRONTEND"} Missing Translations Report:\n`)
-
- for (const [locale, files] of Object.entries(missingTranslations)) {
- if (Object.keys(files).length === 0) {
- console.log(`✅ ${locale}: No missing translations`)
- continue
+### `src/extension.ts`
+
+The `checkWorktreeAutoOpen` function in [`src/extension.ts`](https://github.com/RooCodeInc/Roo-Code/blob/HEAD/src/extension.ts) handles a key part of this chapter's functionality:
+
+```ts
+ * This is called during extension activation to handle the worktree auto-open flow.
+ */
+async function checkWorktreeAutoOpen(
+ context: vscode.ExtensionContext,
+ outputChannel: vscode.OutputChannel,
+): Promise<void> {
+ try {
+ const worktreeAutoOpenPath = context.globalState.get<string>("worktreeAutoOpenPath")
+ if (!worktreeAutoOpenPath) {
+ return
}
- hasMissingTranslations = true
- console.log(`📝 ${locale}:`)
-
- for (const [fileName, missingItems] of Object.entries(files)) {
- if (missingItems.file) {
- console.log(` - ${fileName}: ${missingItems.file}`)
- continue
- }
-
- console.log(` - ${fileName}: ${missingItems.length} missing translations`)
-
- for (const { key, englishValue } of missingItems) {
- console.log(` ${key}: "${englishValue}"`)
- }
+ const workspaceFolders = vscode.workspace.workspaceFolders
+ if (!workspaceFolders || workspaceFolders.length === 0) {
+ return
}
-```
-
-This function is important because it defines how Roo Code Tutorial: Run an AI Dev Team in Your Editor implements the patterns covered in this chapter.
-
-### `scripts/find-missing-translations.js`
-The `checkPackageNlsTranslations` function in [`scripts/find-missing-translations.js`](https://github.com/RooCodeInc/Roo-Code/blob/HEAD/scripts/find-missing-translations.js) handles a key part of this chapter's functionality:
+ const currentPath = workspaceFolders[0].uri.fsPath
-```js
+ // Normalize paths for comparison
+ const normalizePath = (p: string) => p.replace(/\/+$/, "").replace(/\\+/g, "/").toLowerCase()
-// Function to check package.nls.json translations
-async function checkPackageNlsTranslations() {
- const SRC_DIR = path.join(__dirname, "../src")
+ // Check if current workspace matches the worktree path
+ if (normalizePath(currentPath) === normalizePath(worktreeAutoOpenPath)) {
+ // Clear the state first to prevent re-triggering
+ await context.globalState.update("worktreeAutoOpenPath", undefined)
- // Read the base package.nls.json file
- const baseFilePath = path.join(SRC_DIR, "package.nls.json")
- const baseContent = await parseJsonFile(baseFilePath)
+ outputChannel.appendLine(`[Worktree] Auto-opening Roo Code sidebar for worktree: ${worktreeAutoOpenPath}`)
- if (!baseContent) {
- console.warn(`Warning: Base package.nls.json not found at ${baseFilePath} - skipping package.nls checks`)
- return { missingTranslations: {}, hasMissingTranslations: false }
- }
-
- // Validate that the base file has a flat structure
- validateFlatStructure(baseContent, baseFilePath)
-
- // Get all package.nls.*.json files
- const srcDirContents = await readdir(SRC_DIR)
- const nlsFiles = srcDirContents
- .filter((file) => file.startsWith("package.nls.") && file.endsWith(".json"))
- .filter((file) => file !== "package.nls.json") // Exclude the base file
+ // Open the Roo Code sidebar with a slight delay to ensure UI is ready
+ setTimeout(async () => {
+ try {
+```
- // Filter to the specified locale if provided
- const filesToCheck = args.locale
- ? nlsFiles.filter((file) => {
- const locale = file.replace("package.nls.", "").replace(".json", "")
- return locale === args.locale
- })
- : nlsFiles
+This function is important because it defines how Roo Code Tutorial: Run an AI Dev Team in Your Editor implements the patterns covered in this chapter.
- if (args.locale && filesToCheck.length === 0) {
+### `src/extension.ts`
+
+The `activate` function in [`src/extension.ts`](https://github.com/RooCodeInc/Roo-Code/blob/HEAD/src/extension.ts) handles a key part of this chapter's functionality:
+
+```ts
+ registerTerminalActions,
+ CodeActionProvider,
+} from "./activate"
+import { initializeI18n } from "./i18n"
+import { flushModels, initializeModelCacheRefresh, refreshModels } from "./api/providers/fetchers/modelCache"
+
+/**
+ * Built using https://github.com/microsoft/vscode-webview-ui-toolkit
+ *
+ * Inspired by:
+ * - https://github.com/microsoft/vscode-webview-ui-toolkit-samples/tree/main/default/weather-webview
+ * - https://github.com/microsoft/vscode-webview-ui-toolkit-samples/tree/main/frameworks/hello-world-react-cra
+ */
+
+let outputChannel: vscode.OutputChannel
+let extensionContext: vscode.ExtensionContext
+let cloudService: CloudService | undefined
+
+let authStateChangedHandler: ((data: { state: AuthState; previousState: AuthState }) => Promise<void>) | undefined
+let settingsUpdatedHandler: (() => void) | undefined
+let userInfoHandler: ((data: { userInfo: CloudUserInfo }) => Promise<void>) | undefined
+
+/**
+ * Check if we should auto-open the Roo Code sidebar after switching to a worktree.
+ * This is called during extension activation to handle the worktree auto-open flow.
+ */
+async function checkWorktreeAutoOpen(
+ context: vscode.ExtensionContext,
+ outputChannel: vscode.OutputChannel,
+): Promise<void> {
+ try {
+ const worktreeAutoOpenPath = context.globalState.get<string>("worktreeAutoOpenPath")
```
This function is important because it defines how Roo Code Tutorial: Run an AI Dev Team in Your Editor implements the patterns covered in this chapter.
@@ -172,7 +170,7 @@ This function is important because it defines how Roo Code Tutorial: Run an AI D
```mermaid
flowchart TD
- A[outputResults]
- B[checkPackageNlsTranslations]
+ A[checkWorktreeAutoOpen]
+ B[activate]
A --> B
```
diff --git a/tutorials/roo-code-tutorial/08-enterprise-operations.md b/tutorials/roo-code-tutorial/08-enterprise-operations.md
index 646b4171..6ea808f0 100644
--- a/tutorials/roo-code-tutorial/08-enterprise-operations.md
+++ b/tutorials/roo-code-tutorial/08-enterprise-operations.md
@@ -107,88 +107,86 @@ Related:
- [OpenHands Tutorial](../openhands-tutorial/)
- [MCP Servers Tutorial](../mcp-servers-tutorial/)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `scripts/find-missing-translations.js`
-
-The `outputPackageNlsResults` function in [`scripts/find-missing-translations.js`](https://github.com/RooCodeInc/Roo-Code/blob/HEAD/scripts/find-missing-translations.js) handles a key part of this chapter's functionality:
-
-```js
- )
-
- return { missingTranslations, hasMissingTranslations: outputPackageNlsResults(missingTranslations) }
-}
+### `src/extension.ts`
-// Function to output package.nls results
-function outputPackageNlsResults(missingTranslations) {
- let hasMissingTranslations = false
+The `deactivate` function in [`src/extension.ts`](https://github.com/RooCodeInc/Roo-Code/blob/HEAD/src/extension.ts) handles a key part of this chapter's functionality:
- console.log(`\nPACKAGE.NLS Missing Translations Report:\n`)
+```ts
+ }
- for (const [locale, files] of Object.entries(missingTranslations)) {
- if (Object.keys(files).length === 0) {
- console.log(`✅ ${locale}: No missing translations`)
- continue
- }
+ // Add to subscriptions for proper cleanup on deactivate.
+ context.subscriptions.push(cloudService)
- hasMissingTranslations = true
- console.log(`📝 ${locale}:`)
+ // Trigger initial cloud profile sync now that CloudService is ready.
+ try {
+ await provider.initializeCloudProfileSyncWhenReady()
+ } catch (error) {
+ outputChannel.appendLine(
+ `[CloudService] Failed to initialize cloud profile sync: ${error instanceof Error ? error.message : String(error)}`,
+ )
+ }
- for (const [fileName, missingItems] of Object.entries(files)) {
- console.log(` - ${fileName}: ${missingItems.length} missing translations`)
+ // Finish initializing the provider.
+ TelemetryService.instance.setProvider(provider)
- for (const { key, englishValue } of missingItems) {
- console.log(` ${key}: "${englishValue}"`)
- }
- }
+ context.subscriptions.push(
+ vscode.window.registerWebviewViewProvider(ClineProvider.sideBarId, provider, {
+ webviewOptions: { retainContextWhenHidden: true },
+ }),
+ )
- console.log("")
- }
+ // Check for worktree auto-open path (set when switching to a worktree)
+ await checkWorktreeAutoOpen(context, outputChannel)
- return hasMissingTranslations
+ // Auto-import configuration if specified in settings.
+ try {
+ await autoImportSettings(outputChannel, {
+ providerSettingsManager: provider.providerSettingsManager,
+ contextProxy: provider.contextProxy,
+ customModesManager: provider.customModesManager,
```
This function is important because it defines how Roo Code Tutorial: Run an AI Dev Team in Your Editor implements the patterns covered in this chapter.
-### `scripts/find-missing-translations.js`
+### `scripts/find-missing-i18n-key.js`
-The `findMissingTranslations` function in [`scripts/find-missing-translations.js`](https://github.com/RooCodeInc/Roo-Code/blob/HEAD/scripts/find-missing-translations.js) handles a key part of this chapter's functionality:
+The `getLocaleDirs` function in [`scripts/find-missing-i18n-key.js`](https://github.com/RooCodeInc/Roo-Code/blob/HEAD/scripts/find-missing-i18n-key.js) handles a key part of this chapter's functionality:
```js
-// Main function to find missing translations
-async function findMissingTranslations() {
+// Get all language directories for a specific locales directory
+function getLocaleDirs(localesDir) {
try {
- console.log("Starting translation check...")
-
- let anyAreaMissingTranslations = false
-
- // Check each requested area
- for (const area of areasToCheck) {
- if (area === "package-nls") {
- const { hasMissingTranslations } = await checkPackageNlsTranslations()
- anyAreaMissingTranslations = anyAreaMissingTranslations || hasMissingTranslations
- } else {
- const { hasMissingTranslations } = await checkAreaTranslations(area)
- anyAreaMissingTranslations = anyAreaMissingTranslations || hasMissingTranslations
- }
+ const allLocales = fs.readdirSync(localesDir).filter((file) => {
+ const stats = fs.statSync(path.join(localesDir, file))
+ return stats.isDirectory() // Do not exclude any language directories
+ })
+
+ // Filter to a specific language if specified
+ return args.locale ? allLocales.filter((locale) => locale === args.locale) : allLocales
+ } catch (error) {
+ if (error.code === "ENOENT") {
+ console.warn(`Warning: Locales directory not found: ${localesDir}`)
+ return []
}
+ throw error
+ }
+}
+
+// Get the value from JSON by path
+function getValueByPath(obj, path) {
+ const parts = path.split(".")
+ let current = obj
- // Summary
- if (!anyAreaMissingTranslations) {
- console.log("\n✅ All translations are complete across all checked areas!")
- } else {
- console.log("\n✏️ To add missing translations:")
- console.log("1. Add the missing keys to the corresponding locale files")
- console.log("2. Translate the English values to the appropriate language")
- console.log("3. Run this script again to verify all translations are complete")
- // Exit with error code to fail CI checks
- process.exit(1)
+ for (const part of parts) {
+ if (current === undefined || current === null) {
+ return undefined
}
- } catch (error) {
- console.error("Error:", error.message)
+ current = current[part]
+ }
+
```
This function is important because it defines how Roo Code Tutorial: Run an AI Dev Team in Your Editor implements the patterns covered in this chapter.
@@ -198,7 +196,7 @@ This function is important because it defines how Roo Code Tutorial: Run an AI D
```mermaid
flowchart TD
- A[outputPackageNlsResults]
- B[findMissingTranslations]
+ A[deactivate]
+ B[getLocaleDirs]
A --> B
```
diff --git a/tutorials/serena-tutorial/01-getting-started.md b/tutorials/serena-tutorial/01-getting-started.md
index 9bcb094d..03c92797 100644
--- a/tutorials/serena-tutorial/01-getting-started.md
+++ b/tutorials/serena-tutorial/01-getting-started.md
@@ -52,10 +52,49 @@ You now have Serena launched and connected as an MCP server.
Next: [Chapter 2: Semantic Toolkit and Agent Loop](02-semantic-toolkit-and-agent-loop.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
+### `docs/_config.yml`
+
+The `interactive` interface in [`docs/_config.yml`](https://github.com/oraios/serena/blob/HEAD/docs/_config.yml) handles a key part of this chapter's functionality:
+
+```yml
+# Launch button settings
+launch_buttons:
+ notebook_interface : classic # The interface interactive links will activate ["classic", "jupyterlab"]
+ binderhub_url : "" # The URL of the BinderHub (e.g., https://mybinder.org)
+ jupyterhub_url : "" # The URL of the JupyterHub (e.g., https://datahub.berkeley.edu)
+ thebe : false # Add a thebe button to pages (requires the repository to run on Binder)
+ colab_url : "https://colab.research.google.com"
+
+repository:
+ url : https://github.com/oraios/serena # The URL to your book's repository
+ path_to_book : docs # A path to your book's folder, relative to the repository root.
+ branch : main # Which branch of the repository should be used when creating links
+
+#######################################################################################
+# Advanced and power-user settings
+sphinx:
+ extra_extensions :
+ - sphinx.ext.autodoc
+ - sphinx.ext.viewcode
+ - sphinx_toolbox.more_autodoc.sourcelink
+ #- sphinxcontrib.spelling
+ local_extensions : # A list of local extensions to load by sphinx specified by "name: path" items
+ recursive_update : false # A boolean indicating whether to overwrite the Sphinx config (true) or recursively update (false)
+ config : # key-value pairs to directly over-ride the Sphinx configuration
+ master_doc: "01-about/000_intro.md"
+ html_theme_options:
+ logo:
+ image_light: ../resources/serena-logo.svg
+ image_dark: ../resources/serena-logo-dark-mode.svg
+ autodoc_typehints_format: "short"
+ autodoc_member_order: "bysource"
+ autoclass_content: "both"
+```
+
+This interface is important because it defines how Serena Tutorial: Semantic Code Retrieval Toolkit for Coding Agents implements the patterns covered in this chapter.
+
### `docs/autogen_docs.py`
The `module_template` function in [`docs/autogen_docs.py`](https://github.com/oraios/serena/blob/HEAD/docs/autogen_docs.py) handles a key part of this chapter's functionality:
@@ -179,57 +218,16 @@ def make_rst(src_root, rst_root, clean=False, overwrite=False, package_prefix=""
This function is important because it defines how Serena Tutorial: Semantic Code Retrieval Toolkit for Coding Agents implements the patterns covered in this chapter.
-### `docs/autogen_docs.py`
-
-The `make_rst` function in [`docs/autogen_docs.py`](https://github.com/oraios/serena/blob/HEAD/docs/autogen_docs.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def make_rst(src_root, rst_root, clean=False, overwrite=False, package_prefix=""):
- """Creates/updates documentation in form of rst files for modules and packages.
-
- Does not delete any existing rst files. Thus, rst files for packages or modules that have been removed or renamed
- should be deleted by hand.
-
- This method should be executed from the project's top-level directory
-
- :param src_root: path to library base directory, typically "src/<library_name>"
- :param rst_root: path to the root directory to which .rst files will be written
- :param clean: whether to completely clean the target directory beforehand, removing any existing .rst files
- :param overwrite: whether to overwrite existing rst files. This should be used with caution as it will delete
- all manual changes to documentation files
- :package_prefix: a prefix to prepend to each module (for the case where the src_root is not the base package),
- which, if not empty, should end with a "."
- :return:
- """
- rst_root = os.path.abspath(rst_root)
-
- if clean and os.path.isdir(rst_root):
- shutil.rmtree(rst_root)
-
- base_package_name = package_prefix + os.path.basename(src_root)
-
- # TODO: reduce duplication with same logic for subpackages below
- files_in_dir = os.listdir(src_root)
- module_names = [f[:-3] for f in files_in_dir if f.endswith(".py") and not f.startswith("_")]
- subdir_refs = [
- f"{f}/index"
- for f in files_in_dir
-```
-
-This function is important because it defines how Serena Tutorial: Semantic Code Retrieval Toolkit for Coding Agents implements the patterns covered in this chapter.
-
## How These Components Connect
```mermaid
flowchart TD
- A[module_template]
- B[index_template]
- C[write_to_file]
- D[make_rst]
- E[autogen_tool_list]
+ A[interactive]
+ B[module_template]
+ C[index_template]
+ D[write_to_file]
+ E[make_rst]
A --> B
B --> C
C --> D
diff --git a/tutorials/serena-tutorial/02-semantic-toolkit-and-agent-loop.md b/tutorials/serena-tutorial/02-semantic-toolkit-and-agent-loop.md
index fca59781..e526b5ba 100644
--- a/tutorials/serena-tutorial/02-semantic-toolkit-and-agent-loop.md
+++ b/tutorials/serena-tutorial/02-semantic-toolkit-and-agent-loop.md
@@ -49,17 +49,37 @@ You now understand Serena's core leverage: semantic precision instead of file-wi
Next: [Chapter 3: MCP Client Integrations](03-mcp-client-integrations.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `repo_dir_sync.py`
-The `gitLog` function in [`repo_dir_sync.py`](https://github.com/oraios/serena/blob/HEAD/repo_dir_sync.py) handles a key part of this chapter's functionality:
+The `call` function in [`repo_dir_sync.py`](https://github.com/oraios/serena/blob/HEAD/repo_dir_sync.py) handles a key part of this chapter's functionality:
```py
+def call(cmd):
+ p = popen(cmd)
+ return p.stdout.read().decode("utf-8")
+
+
+def execute(cmd, exceptionOnError=True):
+ """
+ :param cmd: the command to execute
+ :param exceptionOnError: if True, raise on exception on error (return code not 0); if False return
+ whether the call was successful
+ :return: True if the call was successful, False otherwise (if exceptionOnError==False)
+ """
+ p = popen(cmd)
+ p.wait()
+ success = p.returncode == 0
+ if exceptionOnError:
+ if not success:
+ raise Exception("Command failed: %s" % cmd)
+ else:
+ return success
+
+
def gitLog(path, arg):
oldPath = os.getcwd()
os.chdir(path)
@@ -68,39 +88,66 @@ def gitLog(path, arg):
return lg
-def gitCommit(msg):
- with open(COMMIT_MSG_FILENAME, "wb") as f:
- f.write(msg.encode("utf-8"))
- gitCommitWithMessageFromFile(COMMIT_MSG_FILENAME)
+```
+This function is important because it defines how Serena Tutorial: Semantic Code Retrieval Toolkit for Coding Agents implements the patterns covered in this chapter.
-def gitCommitWithMessageFromFile(commitMsgFilename):
- if not os.path.exists(commitMsgFilename):
- raise FileNotFoundError(f"{commitMsgFilename} not found in {os.path.abspath(os.getcwd())}")
- os.system(f"git commit --file={commitMsgFilename}")
- os.unlink(commitMsgFilename)
+### `repo_dir_sync.py`
+The `execute` function in [`repo_dir_sync.py`](https://github.com/oraios/serena/blob/HEAD/repo_dir_sync.py) handles a key part of this chapter's functionality:
-COMMIT_MSG_FILENAME = "commitmsg.txt"
+```py
-class OtherRepo:
- SYNC_COMMIT_ID_FILE_LIB_REPO = ".syncCommitId.remote"
- SYNC_COMMIT_ID_FILE_THIS_REPO = ".syncCommitId.this"
- SYNC_COMMIT_MESSAGE = f"Updated %s sync commit identifiers"
- SYNC_BACKUP_DIR = ".syncBackup"
-
+def execute(cmd, exceptionOnError=True):
+ """
+ :param cmd: the command to execute
+ :param exceptionOnError: if True, raise on exception on error (return code not 0); if False return
+ whether the call was successful
+ :return: True if the call was successful, False otherwise (if exceptionOnError==False)
+ """
+ p = popen(cmd)
+ p.wait()
+ success = p.returncode == 0
+ if exceptionOnError:
+ if not success:
+ raise Exception("Command failed: %s" % cmd)
+ else:
+ return success
+
+
+def gitLog(path, arg):
+ oldPath = os.getcwd()
+ os.chdir(path)
+ lg = call("git log --no-merges " + arg)
+ os.chdir(oldPath)
+ return lg
+
+
+def gitCommit(msg):
+ with open(COMMIT_MSG_FILENAME, "wb") as f:
+ f.write(msg.encode("utf-8"))
+ gitCommitWithMessageFromFile(COMMIT_MSG_FILENAME)
+
```
This function is important because it defines how Serena Tutorial: Semantic Code Retrieval Toolkit for Coding Agents implements the patterns covered in this chapter.
### `repo_dir_sync.py`
-The `gitCommit` function in [`repo_dir_sync.py`](https://github.com/oraios/serena/blob/HEAD/repo_dir_sync.py) handles a key part of this chapter's functionality:
+The `gitLog` function in [`repo_dir_sync.py`](https://github.com/oraios/serena/blob/HEAD/repo_dir_sync.py) handles a key part of this chapter's functionality:
```py
+def gitLog(path, arg):
+ oldPath = os.getcwd()
+ os.chdir(path)
+ lg = call("git log --no-merges " + arg)
+ os.chdir(oldPath)
+ return lg
+
+
def gitCommit(msg):
with open(COMMIT_MSG_FILENAME, "wb") as f:
f.write(msg.encode("utf-8"))
@@ -123,23 +170,18 @@ class OtherRepo:
SYNC_COMMIT_MESSAGE = f"Updated %s sync commit identifiers"
SYNC_BACKUP_DIR = ".syncBackup"
- def __init__(self, name, branch, pathToLib):
- self.pathToLibInThisRepo = os.path.abspath(pathToLib)
- if not os.path.exists(self.pathToLibInThisRepo):
- raise ValueError(f"Repository directory '{self.pathToLibInThisRepo}' does not exist")
- self.name = name
- self.branch = branch
- self.libRepo: Optional[LibRepo] = None
-
```
This function is important because it defines how Serena Tutorial: Semantic Code Retrieval Toolkit for Coding Agents implements the patterns covered in this chapter.
### `repo_dir_sync.py`
-The `gitCommitWithMessageFromFile` function in [`repo_dir_sync.py`](https://github.com/oraios/serena/blob/HEAD/repo_dir_sync.py) handles a key part of this chapter's functionality:
+The `gitCommit` function in [`repo_dir_sync.py`](https://github.com/oraios/serena/blob/HEAD/repo_dir_sync.py) handles a key part of this chapter's functionality:
```py
+
+
+def gitCommit(msg):
with open(COMMIT_MSG_FILENAME, "wb") as f:
f.write(msg.encode("utf-8"))
gitCommitWithMessageFromFile(COMMIT_MSG_FILENAME)
@@ -169,64 +211,20 @@ class OtherRepo:
self.branch = branch
self.libRepo: Optional[LibRepo] = None
- def isSyncEstablished(self):
- return os.path.exists(os.path.join(self.pathToLibInThisRepo, self.SYNC_COMMIT_ID_FILE_LIB_REPO))
-
```
This function is important because it defines how Serena Tutorial: Semantic Code Retrieval Toolkit for Coding Agents implements the patterns covered in this chapter.
-### `.serena/project.yml`
-
-The `here` interface in [`.serena/project.yml`](https://github.com/oraios/serena/blob/HEAD/.serena/project.yml) handles a key part of this chapter's functionality:
-
-```yml
-# terraform toml typescript typescript_vts vue
-# yaml zig
-# (This list may be outdated. For the current list, see values of Language enum here:
-# https://github.com/oraios/serena/blob/main/src/solidlsp/ls_config.py
-# For some languages, there are alternative language servers, e.g. csharp_omnisharp, ruby_solargraph.)
-# Note:
-# - For C, use cpp
-# - For JavaScript, use typescript
-# - For Free Pascal/Lazarus, use pascal
-# Special requirements:
-# - csharp: Requires the presence of a .sln file in the project folder.
-# - pascal: Requires Free Pascal Compiler (fpc) and optionally Lazarus.
-# When using multiple languages, the first language server that supports a given file will be used for that file.
-# The first language is the default language and the respective language server will be used as a fallback.
-# Note that when using the JetBrains backend, language servers are not used and this list is correspondingly ignored.
-languages:
-- python
-- typescript
-
-# whether to use project's .gitignore files to ignore files
-ignore_all_files_in_gitignore: true
-
-
-# list of additional paths to ignore in all projects
-# same syntax as gitignore, so you can use * and **
-ignored_paths: []
-
-# whether the project is in read-only mode
-# If set to true, all editing tools will be disabled and attempts to use them will result in an error
-read_only: false
-
-
-```
-
-This interface is important because it defines how Serena Tutorial: Semantic Code Retrieval Toolkit for Coding Agents implements the patterns covered in this chapter.
-
## How These Components Connect
```mermaid
flowchart TD
- A[gitLog]
- B[gitCommit]
- C[gitCommitWithMessageFromFile]
- D[here]
- E[interactive]
+ A[call]
+ B[execute]
+ C[gitLog]
+ D[gitCommit]
+ E[gitCommitWithMessageFromFile]
A --> B
B --> C
C --> D
diff --git a/tutorials/serena-tutorial/03-mcp-client-integrations.md b/tutorials/serena-tutorial/03-mcp-client-integrations.md
index 1967452f..f2df5cd8 100644
--- a/tutorials/serena-tutorial/03-mcp-client-integrations.md
+++ b/tutorials/serena-tutorial/03-mcp-client-integrations.md
@@ -49,170 +49,168 @@ You now know how Serena fits across multiple agent clients without locking into
Next: [Chapter 4: Language Backends and Analysis Strategy](04-language-backends-and-analysis-strategy.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/serena/agent.py`
+### `src/serena/project.py`
-The `ActiveModes` class in [`src/serena/agent.py`](https://github.com/oraios/serena/blob/HEAD/src/serena/agent.py) handles a key part of this chapter's functionality:
+The `MemoriesManager` class in [`src/serena/project.py`](https://github.com/oraios/serena/blob/HEAD/src/serena/project.py) handles a key part of this chapter's functionality:
```py
-class ActiveModes:
- def __init__(self) -> None:
- self._base_modes: Sequence[str] | None = None
- self._default_modes: Sequence[str] | None = None
- self._active_mode_names: Sequence[str] | None = []
- self._active_modes: Sequence[SerenaAgentMode] | None = []
-
- def apply(self, mode_selection: ModeSelectionDefinition) -> None:
- # invalidate active modes
- self._active_mode_names = None
- self._active_modes = None
-
- # apply overrides
- log.debug("Applying mode selection: default_modes=%s, base_modes=%s", mode_selection.default_modes, mode_selection.base_modes)
- if mode_selection.base_modes is not None:
- self._base_modes = mode_selection.base_modes
- if mode_selection.default_modes is not None:
- self._default_modes = mode_selection.default_modes
- log.debug("Current mode selection: base_modes=%s, default_modes=%s", self._base_modes, self._default_modes)
-
- def get_mode_names(self) -> Sequence[str]:
- if self._active_mode_names is not None:
- return self._active_mode_names
- active_mode_names: set[str] = set()
- if self._base_modes is not None:
- active_mode_names.update(self._base_modes)
- if self._default_modes is not None:
- active_mode_names.update(self._default_modes)
- self._active_mode_names = sorted(active_mode_names)
- log.info("Active modes: %s", self._active_mode_names)
+class MemoriesManager:
+ GLOBAL_TOPIC = "global"
+ _global_memory_dir = SerenaPaths().global_memories_path
+
+ def __init__(
+ self,
+ serena_data_folder: str | Path | None,
+ read_only_memory_patterns: Sequence[str] = (),
+ ignored_memory_patterns: Sequence[str] = (),
+ ):
+ """
+ :param serena_data_folder: the absolute path to the project's .serena data folder
+ :param read_only_memory_patterns: whether to allow writing global memories in tool execution contexts
+ :param ignored_memory_patterns: regex patterns for memories to completely exclude from listing, reading, and writing.
+ Matching memories will not appear in list_memories or activate_project output and cannot be accessed
+ via read_memory or write_memory. Use read_file on the raw path to access ignored memory files.
+ """
+ self._project_memory_dir: Path | None = None
+ if serena_data_folder is not None:
+ self._project_memory_dir = Path(serena_data_folder) / "memories"
+ self._project_memory_dir.mkdir(parents=True, exist_ok=True)
+ self._encoding = SERENA_FILE_ENCODING
+ self._read_only_memory_patterns = [re.compile(pattern) for pattern in set(read_only_memory_patterns)]
+ self._ignored_memory_patterns = [re.compile(pattern) for pattern in set(ignored_memory_patterns)]
+
+ def _is_read_only_memory(self, name: str) -> bool:
+ for pattern in self._read_only_memory_patterns:
+ if pattern.fullmatch(name):
+ return True
+ return False
+```
+
+This class is important because it defines how Serena Tutorial: Semantic Code Retrieval Toolkit for Coding Agents implements the patterns covered in this chapter.
+
+### `src/serena/project.py`
+
+The `MemoriesList` class in [`src/serena/project.py`](https://github.com/oraios/serena/blob/HEAD/src/serena/project.py) handles a key part of this chapter's functionality:
+
+```py
+ return f"Memory {name} written."
+
+ class MemoriesList:
+ def __init__(self) -> None:
+ self.memories: list[str] = []
+ self.read_only_memories: list[str] = []
+
+ def __len__(self) -> int:
+ return len(self.memories) + len(self.read_only_memories)
+
+ def add(self, memory_name: str, is_read_only: bool) -> None:
+ if is_read_only:
+ self.read_only_memories.append(memory_name)
+ else:
+ self.memories.append(memory_name)
+
+ def extend(self, other: "MemoriesManager.MemoriesList") -> None:
+ self.memories.extend(other.memories)
+ self.read_only_memories.extend(other.read_only_memories)
+
+ def to_dict(self) -> dict[str, list[str]]:
+ result = {}
+ if self.memories:
+ result["memories"] = sorted(self.memories)
+ if self.read_only_memories:
+ result["read_only_memories"] = sorted(self.read_only_memories)
+ return result
+
+ def get_full_list(self) -> list[str]:
+ return sorted(self.memories + self.read_only_memories)
+
+ def _list_memories(self, search_dir: Path, base_dir: Path, prefix: str = "") -> MemoriesList:
```
This class is important because it defines how Serena Tutorial: Semantic Code Retrieval Toolkit for Coding Agents implements the patterns covered in this chapter.
-### `src/serena/agent.py`
+### `src/serena/project.py`
-The `SerenaAgent` class in [`src/serena/agent.py`](https://github.com/oraios/serena/blob/HEAD/src/serena/agent.py) handles a key part of this chapter's functionality:
+The `Project` class in [`src/serena/project.py`](https://github.com/oraios/serena/blob/HEAD/src/serena/project.py) handles a key part of this chapter's functionality:
```py
-from serena import serena_version
-from serena.analytics import RegisteredTokenCountEstimator, ToolUsageStats
-from serena.config.context_mode import SerenaAgentContext, SerenaAgentMode
+
from serena.config.serena_config import (
- LanguageBackend,
- ModeSelectionDefinition,
- NamedToolInclusionDefinition,
- RegisteredProject,
+ ProjectConfig,
SerenaConfig,
SerenaPaths,
- ToolInclusionDefinition,
)
-from serena.dashboard import SerenaDashboardAPI
-from serena.ls_manager import LanguageServerManager
-from serena.project import MemoriesManager, Project
-from serena.prompt_factory import SerenaPromptFactory
-from serena.task_executor import TaskExecutor
-from serena.tools import ActivateProjectTool, GetCurrentConfigTool, OpenDashboardTool, ReplaceContentTool, Tool, ToolMarker, ToolRegistry
-from serena.util.gui import system_has_usable_display
-from serena.util.inspection import iter_subclasses
-from serena.util.logging import MemoryLogHandler
+from serena.constants import SERENA_FILE_ENCODING
+from serena.ls_manager import LanguageServerFactory, LanguageServerManager
+from serena.util.file_system import GitignoreParser, match_path
+from serena.util.text_utils import ContentReplacer, MatchedConsecutiveLines, search_files
+from solidlsp import SolidLanguageServer
from solidlsp.ls_config import Language
+from solidlsp.ls_utils import FileUtils
if TYPE_CHECKING:
- from serena.gui_log_viewer import GuiLogViewer
+ from serena.agent import SerenaAgent
log = logging.getLogger(__name__)
-TTool = TypeVar("TTool", bound="Tool")
-T = TypeVar("T")
-SUCCESS_RESULT = "OK"
+class MemoriesManager:
+ GLOBAL_TOPIC = "global"
+ _global_memory_dir = SerenaPaths().global_memories_path
+
+ def __init__(
+ self,
+ serena_data_folder: str | Path | None,
+ read_only_memory_patterns: Sequence[str] = (),
+ ignored_memory_patterns: Sequence[str] = (),
+ ):
+ """
+ :param serena_data_folder: the absolute path to the project's .serena data folder
```
This class is important because it defines how Serena Tutorial: Semantic Code Retrieval Toolkit for Coding Agents implements the patterns covered in this chapter.
-### `src/serena/agent.py`
+### `src/serena/dashboard.py`
-The `in` class in [`src/serena/agent.py`](https://github.com/oraios/serena/blob/HEAD/src/serena/agent.py) handles a key part of this chapter's functionality:
+The `RequestLog` class in [`src/serena/dashboard.py`](https://github.com/oraios/serena/blob/HEAD/src/serena/dashboard.py) handles a key part of this chapter's functionality:
```py
-from collections.abc import Callable, Iterator, Sequence
-from contextlib import contextmanager
-from logging import Logger
-from typing import TYPE_CHECKING, Optional, TypeVar
-
-from sensai.util import logging
-from sensai.util.logging import LogTime
-from sensai.util.string import dict_string
-
-from interprompt.jinja_template import JinjaTemplate
-from serena import serena_version
-from serena.analytics import RegisteredTokenCountEstimator, ToolUsageStats
-from serena.config.context_mode import SerenaAgentContext, SerenaAgentMode
-from serena.config.serena_config import (
- LanguageBackend,
- ModeSelectionDefinition,
- NamedToolInclusionDefinition,
- RegisteredProject,
- SerenaConfig,
- SerenaPaths,
- ToolInclusionDefinition,
-)
-from serena.dashboard import SerenaDashboardAPI
-from serena.ls_manager import LanguageServerManager
-from serena.project import MemoriesManager, Project
-from serena.prompt_factory import SerenaPromptFactory
-from serena.task_executor import TaskExecutor
-from serena.tools import ActivateProjectTool, GetCurrentConfigTool, OpenDashboardTool, ReplaceContentTool, Tool, ToolMarker, ToolRegistry
-from serena.util.gui import system_has_usable_display
-from serena.util.inspection import iter_subclasses
-from serena.util.logging import MemoryLogHandler
-from solidlsp.ls_config import Language
-```
-
-This class is important because it defines how Serena Tutorial: Semantic Code Retrieval Toolkit for Coding Agents implements the patterns covered in this chapter.
-### `src/serena/project.py`
-The `MemoriesManager` class in [`src/serena/project.py`](https://github.com/oraios/serena/blob/HEAD/src/serena/project.py) handles a key part of this chapter's functionality:
+class RequestLog(BaseModel):
+ start_idx: int = 0
-```py
+class ResponseLog(BaseModel):
+ messages: list[str]
+ max_idx: int
+ active_project: str | None = None
-class MemoriesManager:
- GLOBAL_TOPIC = "global"
- _global_memory_dir = SerenaPaths().global_memories_path
- def __init__(self, serena_data_folder: str | Path | None, read_only_memory_patterns: Sequence[str] = ()):
- """
- :param serena_data_folder: the absolute path to the project's .serena data folder
- :param read_only_memory_patterns: whether to allow writing global memories in tool execution contexts
- """
- self._project_memory_dir: Path | None = None
- if serena_data_folder is not None:
- self._project_memory_dir = Path(serena_data_folder) / "memories"
- self._project_memory_dir.mkdir(parents=True, exist_ok=True)
- self._encoding = SERENA_FILE_ENCODING
- self._read_only_memory_patterns = [re.compile(pattern) for pattern in set(read_only_memory_patterns)]
+class ResponseToolNames(BaseModel):
+ tool_names: list[str]
- def _is_read_only_memory(self, name: str) -> bool:
- for pattern in self._read_only_memory_patterns:
- if pattern.fullmatch(name):
- return True
- return False
- def _is_global(self, name: str) -> bool:
- return name == self.GLOBAL_TOPIC or name.startswith(self.GLOBAL_TOPIC + "/")
+class ResponseToolStats(BaseModel):
+ stats: dict[str, dict[str, int]]
- def get_memory_file_path(self, name: str) -> Path:
- # Strip .md extension if present
- name = name.replace(".md", "")
- if self._is_global(name):
+class ResponseConfigOverview(BaseModel):
+ active_project: dict[str, str | None]
+ context: dict[str, str]
+ modes: list[dict[str, str]]
+ active_tools: list[str]
+ tool_stats_summary: dict[str, dict[str, int]]
+ registered_projects: list[dict[str, str | bool]]
+ available_tools: list[dict[str, str | bool]]
+ available_modes: list[dict[str, str | bool]]
+ available_contexts: list[dict[str, str | bool]]
+ available_memories: list[str] | None
+ jetbrains_mode: bool
```
This class is important because it defines how Serena Tutorial: Semantic Code Retrieval Toolkit for Coding Agents implements the patterns covered in this chapter.
@@ -222,11 +220,11 @@ This class is important because it defines how Serena Tutorial: Semantic Code Re
```mermaid
flowchart TD
- A[ActiveModes]
- B[SerenaAgent]
- C[in]
- D[MemoriesManager]
- E[MemoriesList]
+ A[MemoriesManager]
+ B[MemoriesList]
+ C[Project]
+ D[RequestLog]
+ E[ResponseLog]
A --> B
B --> C
C --> D
diff --git a/tutorials/serena-tutorial/04-language-backends-and-analysis-strategy.md b/tutorials/serena-tutorial/04-language-backends-and-analysis-strategy.md
index 4a183370..53231b5f 100644
--- a/tutorials/serena-tutorial/04-language-backends-and-analysis-strategy.md
+++ b/tutorials/serena-tutorial/04-language-backends-and-analysis-strategy.md
@@ -46,170 +46,168 @@ You now can select analysis backend strategy based on workflow, language set, an
Next: [Chapter 5: Project Workflow and Context Practices](05-project-workflow-and-context-practices.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/serena/symbol.py`
+### `src/serena/dashboard.py`
-The `NamePathComponent` class in [`src/serena/symbol.py`](https://github.com/oraios/serena/blob/HEAD/src/serena/symbol.py) handles a key part of this chapter's functionality:
+The `RequestGetMemory` class in [`src/serena/dashboard.py`](https://github.com/oraios/serena/blob/HEAD/src/serena/dashboard.py) handles a key part of this chapter's functionality:
```py
-class NamePathComponent:
- def __init__(self, name: str, overload_idx: int | None = None) -> None:
- self.name = name
- self.overload_idx = overload_idx
+class RequestGetMemory(BaseModel):
+ memory_name: str
+
+
+class ResponseGetMemory(BaseModel):
+ content: str
+ memory_name: str
+
+
+class RequestSaveMemory(BaseModel):
+ memory_name: str
+ content: str
+
- def __repr__(self) -> str:
- if self.overload_idx is not None:
- return f"{self.name}[{self.overload_idx}]"
- else:
- return self.name
+class RequestDeleteMemory(BaseModel):
+ memory_name: str
-class NamePathMatcher(ToStringMixin):
- """
- Matches name paths of symbols against search patterns.
+class RequestRenameMemory(BaseModel):
+ old_name: str
+ new_name: str
- A name path is a path in the symbol tree *within a source file*.
- For example, the method `my_method` defined in class `MyClass` would have the name path `MyClass/my_method`.
- If a symbol is overloaded (e.g., in Java), a 0-based index is appended (e.g. "MyClass/my_method[0]") to
- uniquely identify it.
- A matching pattern can be:
- * a simple name (e.g. "method"), which will match any symbol with that name
- * a relative path like "class/method", which will match any symbol with that name path suffix
- * an absolute name path "/class/method" (absolute name path), which requires an exact match of the full name path within the source file.
- Append an index `[i]` to match a specific overload only, e.g. "MyClass/my_method[1]".
- """
+class ResponseGetSerenaConfig(BaseModel):
+ content: str
+
+
+class RequestSaveSerenaConfig(BaseModel):
+ content: str
- class PatternComponent(NamePathComponent):
- @classmethod
```
This class is important because it defines how Serena Tutorial: Semantic Code Retrieval Toolkit for Coding Agents implements the patterns covered in this chapter.
-### `src/serena/symbol.py`
+### `src/serena/dashboard.py`
-The `NamePathMatcher` class in [`src/serena/symbol.py`](https://github.com/oraios/serena/blob/HEAD/src/serena/symbol.py) handles a key part of this chapter's functionality:
+The `ResponseGetMemory` class in [`src/serena/dashboard.py`](https://github.com/oraios/serena/blob/HEAD/src/serena/dashboard.py) handles a key part of this chapter's functionality:
```py
-class NamePathMatcher(ToStringMixin):
- """
- Matches name paths of symbols against search patterns.
-
- A name path is a path in the symbol tree *within a source file*.
- For example, the method `my_method` defined in class `MyClass` would have the name path `MyClass/my_method`.
- If a symbol is overloaded (e.g., in Java), a 0-based index is appended (e.g. "MyClass/my_method[0]") to
- uniquely identify it.
-
- A matching pattern can be:
- * a simple name (e.g. "method"), which will match any symbol with that name
- * a relative path like "class/method", which will match any symbol with that name path suffix
- * an absolute name path "/class/method" (absolute name path), which requires an exact match of the full name path within the source file.
- Append an index `[i]` to match a specific overload only, e.g. "MyClass/my_method[1]".
- """
-
- class PatternComponent(NamePathComponent):
- @classmethod
- def from_string(cls, component_str: str) -> Self:
- overload_idx = None
- if component_str.endswith("]") and "[" in component_str:
- bracket_idx = component_str.rfind("[")
- index_part = component_str[bracket_idx + 1 : -1]
- if index_part.isdigit():
- component_str = component_str[:bracket_idx]
- overload_idx = int(index_part)
- return cls(name=component_str, overload_idx=overload_idx)
-
- def matches(self, name_path_component: NamePathComponent, substring_matching: bool) -> bool:
- if substring_matching:
+class ResponseGetMemory(BaseModel):
+ content: str
+ memory_name: str
+
+
+class RequestSaveMemory(BaseModel):
+ memory_name: str
+ content: str
+
+
+class RequestDeleteMemory(BaseModel):
+ memory_name: str
+
+
+class RequestRenameMemory(BaseModel):
+ old_name: str
+ new_name: str
+
+
+class ResponseGetSerenaConfig(BaseModel):
+ content: str
+
+
+class RequestSaveSerenaConfig(BaseModel):
+ content: str
+
+
+class RequestCancelTaskExecution(BaseModel):
+ task_id: int
+
```
This class is important because it defines how Serena Tutorial: Semantic Code Retrieval Toolkit for Coding Agents implements the patterns covered in this chapter.
-### `src/serena/symbol.py`
+### `src/serena/dashboard.py`
-The `PatternComponent` class in [`src/serena/symbol.py`](https://github.com/oraios/serena/blob/HEAD/src/serena/symbol.py) handles a key part of this chapter's functionality:
+The `RequestSaveMemory` class in [`src/serena/dashboard.py`](https://github.com/oraios/serena/blob/HEAD/src/serena/dashboard.py) handles a key part of this chapter's functionality:
```py
- """
-
- class PatternComponent(NamePathComponent):
- @classmethod
- def from_string(cls, component_str: str) -> Self:
- overload_idx = None
- if component_str.endswith("]") and "[" in component_str:
- bracket_idx = component_str.rfind("[")
- index_part = component_str[bracket_idx + 1 : -1]
- if index_part.isdigit():
- component_str = component_str[:bracket_idx]
- overload_idx = int(index_part)
- return cls(name=component_str, overload_idx=overload_idx)
-
- def matches(self, name_path_component: NamePathComponent, substring_matching: bool) -> bool:
- if substring_matching:
- if self.name not in name_path_component.name:
- return False
- else:
- if self.name != name_path_component.name:
- return False
- if self.overload_idx is not None and self.overload_idx != name_path_component.overload_idx:
- return False
- return True
-
- def __init__(self, name_path_pattern: str, substring_matching: bool) -> None:
- """
- :param name_path_pattern: the name path expression to match against
- :param substring_matching: whether to use substring matching for the last segment
- """
- assert name_path_pattern, "name_path must not be empty"
- self._expr = name_path_pattern
+
+
+class RequestSaveMemory(BaseModel):
+ memory_name: str
+ content: str
+
+
+class RequestDeleteMemory(BaseModel):
+ memory_name: str
+
+
+class RequestRenameMemory(BaseModel):
+ old_name: str
+ new_name: str
+
+
+class ResponseGetSerenaConfig(BaseModel):
+ content: str
+
+
+class RequestSaveSerenaConfig(BaseModel):
+ content: str
+
+
+class RequestCancelTaskExecution(BaseModel):
+ task_id: int
+
+
+class QueuedExecution(BaseModel):
+ task_id: int
+ is_running: bool
+ name: str
```
This class is important because it defines how Serena Tutorial: Semantic Code Retrieval Toolkit for Coding Agents implements the patterns covered in this chapter.
-### `src/serena/symbol.py`
+### `src/serena/dashboard.py`
-The `LanguageServerSymbol` class in [`src/serena/symbol.py`](https://github.com/oraios/serena/blob/HEAD/src/serena/symbol.py) handles a key part of this chapter's functionality:
+The `RequestDeleteMemory` class in [`src/serena/dashboard.py`](https://github.com/oraios/serena/blob/HEAD/src/serena/dashboard.py) handles a key part of this chapter's functionality:
```py
-@dataclass
-class LanguageServerSymbolLocation:
- """
- Represents the (start) location of a symbol identifier, which, within Serena, uniquely identifies the symbol.
- """
-
- relative_path: str | None
- """
- the relative path of the file containing the symbol; if None, the symbol is defined outside of the project's scope
- """
- line: int | None
- """
- the line number in which the symbol identifier is defined (if the symbol is a function, class, etc.);
- may be None for some types of symbols (e.g. SymbolKind.File)
- """
- column: int | None
- """
- the column number in which the symbol identifier is defined (if the symbol is a function, class, etc.);
- may be None for some types of symbols (e.g. SymbolKind.File)
- """
-
- def __post_init__(self) -> None:
- if self.relative_path is not None:
- self.relative_path = self.relative_path.replace("/", os.path.sep)
-
- def to_dict(self, include_relative_path: bool = True) -> dict[str, Any]:
- result = asdict(self)
- if not include_relative_path:
- result.pop("relative_path", None)
- return result
+class RequestDeleteMemory(BaseModel):
+ memory_name: str
+
+
+class RequestRenameMemory(BaseModel):
+ old_name: str
+ new_name: str
+
+
+class ResponseGetSerenaConfig(BaseModel):
+ content: str
+
+
+class RequestSaveSerenaConfig(BaseModel):
+ content: str
+
+
+class RequestCancelTaskExecution(BaseModel):
+ task_id: int
+
+
+class QueuedExecution(BaseModel):
+ task_id: int
+ is_running: bool
+ name: str
+ finished_successfully: bool
+ logged: bool
+
+ @classmethod
+ def from_task_info(cls, task_info: TaskExecutor.TaskInfo) -> Self:
```
This class is important because it defines how Serena Tutorial: Semantic Code Retrieval Toolkit for Coding Agents implements the patterns covered in this chapter.
@@ -219,11 +217,11 @@ This class is important because it defines how Serena Tutorial: Semantic Code Re
```mermaid
flowchart TD
- A[NamePathComponent]
- B[NamePathMatcher]
- C[PatternComponent]
- D[LanguageServerSymbol]
- E[OutputDict]
+ A[RequestGetMemory]
+ B[ResponseGetMemory]
+ C[RequestSaveMemory]
+ D[RequestDeleteMemory]
+ E[RequestRenameMemory]
A --> B
B --> C
C --> D
diff --git a/tutorials/serena-tutorial/05-project-workflow-and-context-practices.md b/tutorials/serena-tutorial/05-project-workflow-and-context-practices.md
index ba1de9d3..302bffde 100644
--- a/tutorials/serena-tutorial/05-project-workflow-and-context-practices.md
+++ b/tutorials/serena-tutorial/05-project-workflow-and-context-practices.md
@@ -46,176 +46,182 @@ You now have practical workflow patterns for getting consistent value from Seren
Next: [Chapter 6: Configuration and Operational Controls](06-configuration-and-operational-controls.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/serena/symbol.py`
+### `src/solidlsp/ls_process.py`
-The `LanguageServerSymbolDictGrouper` class in [`src/serena/symbol.py`](https://github.com/oraios/serena/blob/HEAD/src/serena/symbol.py) handles a key part of this chapter's functionality:
+The `from` class in [`src/solidlsp/ls_process.py`](https://github.com/oraios/serena/blob/HEAD/src/solidlsp/ls_process.py) handles a key part of this chapter's functionality:
```py
+import threading
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+from queue import Empty, Queue
+from typing import Any
+
+import psutil
+from sensai.util.string import ToStringMixin
+
+from solidlsp.ls_config import Language
+from solidlsp.ls_exceptions import SolidLSPException
+from solidlsp.ls_request import LanguageServerRequest
+from solidlsp.lsp_protocol_handler.lsp_requests import LspNotification
+from solidlsp.lsp_protocol_handler.lsp_types import ErrorCodes
+from solidlsp.lsp_protocol_handler.server import (
+ ENCODING,
+ LSPError,
+ PayloadLike,
+ ProcessLaunchInfo,
+ StringDict,
+ content_length,
+ create_message,
+ make_error_response,
+ make_notification,
+ make_request,
+ make_response,
+)
+from solidlsp.util.subprocess_util import quote_arg, subprocess_kwargs
+
+log = logging.getLogger(__name__)
-
-class LanguageServerSymbolDictGrouper(SymbolDictGrouper[LanguageServerSymbol.OutputDict]):
- def __init__(
- self,
- group_keys: list[LanguageServerSymbol.OutputDictKey],
- group_children_keys: list[LanguageServerSymbol.OutputDictKey],
- collapse_singleton: bool = False,
- ) -> None:
- super().__init__(LanguageServerSymbol.OutputDict, "children", group_keys, group_children_keys, collapse_singleton)
-
-
-class JetBrainsSymbolDictGrouper(SymbolDictGrouper[jb.SymbolDTO]):
- def __init__(
- self,
- group_keys: list[jb.SymbolDTOKey],
- group_children_keys: list[jb.SymbolDTOKey],
- collapse_singleton: bool = False,
- map_name_path_to_name: bool = False,
- ) -> None:
- super().__init__(jb.SymbolDTO, "children", group_keys, group_children_keys, collapse_singleton)
- self._map_name_path_to_name = map_name_path_to_name
-
- def _transform_item(self, item: dict) -> dict:
- if self._map_name_path_to_name:
- # {"name_path: "Class/myMethod"} -> {"name: "myMethod"}
- new_item = dict(item)
- if "name_path" in item:
- name_path = new_item.pop("name_path")
- new_item["name"] = name_path.split("/")[-1]
- return super()._transform_item(new_item)
- else:
```
This class is important because it defines how Serena Tutorial: Semantic Code Retrieval Toolkit for Coding Agents implements the patterns covered in this chapter.
-### `src/serena/symbol.py`
+### `src/solidlsp/ls_process.py`
-The `JetBrainsSymbolDictGrouper` class in [`src/serena/symbol.py`](https://github.com/oraios/serena/blob/HEAD/src/serena/symbol.py) handles a key part of this chapter's functionality:
+The `LanguageServerTerminatedException` class in [`src/solidlsp/ls_process.py`](https://github.com/oraios/serena/blob/HEAD/src/solidlsp/ls_process.py) handles a key part of this chapter's functionality:
```py
-class JetBrainsSymbolDictGrouper(SymbolDictGrouper[jb.SymbolDTO]):
- def __init__(
- self,
- group_keys: list[jb.SymbolDTOKey],
- group_children_keys: list[jb.SymbolDTOKey],
- collapse_singleton: bool = False,
- map_name_path_to_name: bool = False,
- ) -> None:
- super().__init__(jb.SymbolDTO, "children", group_keys, group_children_keys, collapse_singleton)
- self._map_name_path_to_name = map_name_path_to_name
-
- def _transform_item(self, item: dict) -> dict:
- if self._map_name_path_to_name:
- # {"name_path: "Class/myMethod"} -> {"name: "myMethod"}
- new_item = dict(item)
- if "name_path" in item:
- name_path = new_item.pop("name_path")
- new_item["name"] = name_path.split("/")[-1]
- return super()._transform_item(new_item)
- else:
- return super()._transform_item(item)
+class LanguageServerTerminatedException(Exception):
+ """
+ Exception raised when the language server process has terminated unexpectedly.
+ """
+
+ def __init__(self, message: str, language: Language, cause: Exception | None = None) -> None:
+ super().__init__(message)
+ self.message = message
+ self.language = language
+ self.cause = cause
+
+ def __str__(self) -> str:
+ return f"LanguageServerTerminatedException: {self.message}" + (f"; Cause: {self.cause}" if self.cause else "")
+
+
+class Request(ToStringMixin):
+ @dataclass
+ class Result:
+ payload: PayloadLike | None = None
+ error: Exception | None = None
+
+ def is_error(self) -> bool:
+ return self.error is not None
+
+ def __init__(self, request_id: int, method: str) -> None:
+ self._request_id = request_id
+ self._method = method
+ self._status = "pending"
+ self._result_queue: Queue[Request.Result] = Queue()
```
This class is important because it defines how Serena Tutorial: Semantic Code Retrieval Toolkit for Coding Agents implements the patterns covered in this chapter.
-### `src/serena/symbol.py`
+### `src/solidlsp/ls_process.py`
-The `item` interface in [`src/serena/symbol.py`](https://github.com/oraios/serena/blob/HEAD/src/serena/symbol.py) handles a key part of this chapter's functionality:
+The `Request` class in [`src/solidlsp/ls_process.py`](https://github.com/oraios/serena/blob/HEAD/src/solidlsp/ls_process.py) handles a key part of this chapter's functionality:
```py
- def symbol_kind_name(self) -> str:
- """
- :return: string representation of the symbol kind (name attribute of the `SymbolKind` enum item)
- """
- return SymbolKind(self.symbol_kind).name
-
- @property
- def symbol_kind(self) -> SymbolKind:
- return self.symbol_root["kind"]
-
- def is_low_level(self) -> bool:
- """
- :return: whether the symbol is a low-level symbol (variable, constant, etc.), which typically represents data
- rather than structure and therefore is not relevant in a high-level overview of the code.
- """
- return self.symbol_kind >= SymbolKind.Variable.value
-
- @property
- def overload_idx(self) -> int | None:
- return self.symbol_root.get("overload_idx")
-
- def is_neighbouring_definition_separated_by_empty_line(self) -> bool:
- return self.symbol_kind in (SymbolKind.Function, SymbolKind.Method, SymbolKind.Class, SymbolKind.Interface, SymbolKind.Struct)
-
- @property
- def relative_path(self) -> str | None:
- location = self.symbol_root.get("location")
- if location:
- return location.get("relativePath")
- return None
-
- @property
+from solidlsp.ls_config import Language
+from solidlsp.ls_exceptions import SolidLSPException
+from solidlsp.ls_request import LanguageServerRequest
+from solidlsp.lsp_protocol_handler.lsp_requests import LspNotification
+from solidlsp.lsp_protocol_handler.lsp_types import ErrorCodes
+from solidlsp.lsp_protocol_handler.server import (
+ ENCODING,
+ LSPError,
+ PayloadLike,
+ ProcessLaunchInfo,
+ StringDict,
+ content_length,
+ create_message,
+ make_error_response,
+ make_notification,
+ make_request,
+ make_response,
+)
+from solidlsp.util.subprocess_util import quote_arg, subprocess_kwargs
+
+log = logging.getLogger(__name__)
+
+
+class LanguageServerTerminatedException(Exception):
+ """
+ Exception raised when the language server process has terminated unexpectedly.
+ """
+
+ def __init__(self, message: str, language: Language, cause: Exception | None = None) -> None:
+ super().__init__(message)
+ self.message = message
+ self.language = language
```
-This interface is important because it defines how Serena Tutorial: Semantic Code Retrieval Toolkit for Coding Agents implements the patterns covered in this chapter.
+This class is important because it defines how Serena Tutorial: Semantic Code Retrieval Toolkit for Coding Agents implements the patterns covered in this chapter.
-### `src/serena/symbol.py`
+### `src/solidlsp/ls_process.py`
-The `item` interface in [`src/serena/symbol.py`](https://github.com/oraios/serena/blob/HEAD/src/serena/symbol.py) handles a key part of this chapter's functionality:
+The `class` class in [`src/solidlsp/ls_process.py`](https://github.com/oraios/serena/blob/HEAD/src/solidlsp/ls_process.py) handles a key part of this chapter's functionality:
```py
- def symbol_kind_name(self) -> str:
- """
- :return: string representation of the symbol kind (name attribute of the `SymbolKind` enum item)
- """
- return SymbolKind(self.symbol_kind).name
-
- @property
- def symbol_kind(self) -> SymbolKind:
- return self.symbol_root["kind"]
-
- def is_low_level(self) -> bool:
- """
- :return: whether the symbol is a low-level symbol (variable, constant, etc.), which typically represents data
- rather than structure and therefore is not relevant in a high-level overview of the code.
- """
- return self.symbol_kind >= SymbolKind.Variable.value
-
- @property
- def overload_idx(self) -> int | None:
- return self.symbol_root.get("overload_idx")
-
- def is_neighbouring_definition_separated_by_empty_line(self) -> bool:
- return self.symbol_kind in (SymbolKind.Function, SymbolKind.Method, SymbolKind.Class, SymbolKind.Interface, SymbolKind.Struct)
-
- @property
- def relative_path(self) -> str | None:
- location = self.symbol_root.get("location")
- if location:
- return location.get("relativePath")
- return None
-
- @property
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+from queue import Empty, Queue
+from typing import Any
+
+import psutil
+from sensai.util.string import ToStringMixin
+
+from solidlsp.ls_config import Language
+from solidlsp.ls_exceptions import SolidLSPException
+from solidlsp.ls_request import LanguageServerRequest
+from solidlsp.lsp_protocol_handler.lsp_requests import LspNotification
+from solidlsp.lsp_protocol_handler.lsp_types import ErrorCodes
+from solidlsp.lsp_protocol_handler.server import (
+ ENCODING,
+ LSPError,
+ PayloadLike,
+ ProcessLaunchInfo,
+ StringDict,
+ content_length,
+ create_message,
+ make_error_response,
+ make_notification,
+ make_request,
+ make_response,
+)
+from solidlsp.util.subprocess_util import quote_arg, subprocess_kwargs
+
+log = logging.getLogger(__name__)
+
+
```
-This interface is important because it defines how Serena Tutorial: Semantic Code Retrieval Toolkit for Coding Agents implements the patterns covered in this chapter.
+This class is important because it defines how Serena Tutorial: Semantic Code Retrieval Toolkit for Coding Agents implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[LanguageServerSymbolDictGrouper]
- B[JetBrainsSymbolDictGrouper]
- C[item]
- D[item]
- E[RequestLog]
+ A[from]
+ B[LanguageServerTerminatedException]
+ C[Request]
+ D[class]
+ E[LanguageServerProcess]
A --> B
B --> C
C --> D
diff --git a/tutorials/serena-tutorial/06-configuration-and-operational-controls.md b/tutorials/serena-tutorial/06-configuration-and-operational-controls.md
index 4c7c9eca..852a9616 100644
--- a/tutorials/serena-tutorial/06-configuration-and-operational-controls.md
+++ b/tutorials/serena-tutorial/06-configuration-and-operational-controls.md
@@ -46,169 +46,167 @@ You now have a configuration governance baseline for Serena deployments.
Next: [Chapter 7: Extending Serena and Custom Agent Integration](07-extending-serena-and-custom-agent-integration.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/serena/dashboard.py`
+### `src/serena/agent.py`
-The `RequestAddLanguage` class in [`src/serena/dashboard.py`](https://github.com/oraios/serena/blob/HEAD/src/serena/dashboard.py) handles a key part of this chapter's functionality:
+The `in` class in [`src/serena/agent.py`](https://github.com/oraios/serena/blob/HEAD/src/serena/agent.py) handles a key part of this chapter's functionality:
```py
-
-class RequestAddLanguage(BaseModel):
- language: str
-
-
-class RequestRemoveLanguage(BaseModel):
- language: str
-
-
-class RequestGetMemory(BaseModel):
- memory_name: str
-
-
-class ResponseGetMemory(BaseModel):
- content: str
- memory_name: str
-
-
-class RequestSaveMemory(BaseModel):
- memory_name: str
- content: str
-
-
-class RequestDeleteMemory(BaseModel):
- memory_name: str
-
-
-class RequestRenameMemory(BaseModel):
- old_name: str
- new_name: str
-
+import json
+import multiprocessing
+import os
+import platform
+import subprocess
+import sys
+from collections.abc import Callable, Iterator, Sequence
+from contextlib import contextmanager
+from logging import Logger
+from typing import TYPE_CHECKING, Optional, TypeVar
+
+import webview
+from sensai.util import logging
+from sensai.util.logging import LogTime
+from sensai.util.string import dict_string
+
+from interprompt.jinja_template import JinjaTemplate
+from serena import serena_version
+from serena.analytics import RegisteredTokenCountEstimator, ToolUsageStats
+from serena.config.context_mode import SerenaAgentContext, SerenaAgentMode
+from serena.config.serena_config import (
+ LanguageBackend,
+ ModeSelectionDefinition,
+ NamedToolInclusionDefinition,
+ RegisteredProject,
+ SerenaConfig,
+ SerenaPaths,
+ ToolInclusionDefinition,
+)
+from serena.dashboard import SerenaDashboardAPI, SerenaDashboardViewer
+from serena.ls_manager import LanguageServerManager
```
This class is important because it defines how Serena Tutorial: Semantic Code Retrieval Toolkit for Coding Agents implements the patterns covered in this chapter.
-### `src/serena/dashboard.py`
+### `src/solidlsp/ls_utils.py`
-The `RequestRemoveLanguage` class in [`src/serena/dashboard.py`](https://github.com/oraios/serena/blob/HEAD/src/serena/dashboard.py) handles a key part of this chapter's functionality:
+The `InvalidTextLocationError` class in [`src/solidlsp/ls_utils.py`](https://github.com/oraios/serena/blob/HEAD/src/solidlsp/ls_utils.py) handles a key part of this chapter's functionality:
```py
-class RequestRemoveLanguage(BaseModel):
- language: str
-
-
-class RequestGetMemory(BaseModel):
- memory_name: str
-
-
-class ResponseGetMemory(BaseModel):
- content: str
- memory_name: str
-
-
-class RequestSaveMemory(BaseModel):
- memory_name: str
- content: str
-
-
-class RequestDeleteMemory(BaseModel):
- memory_name: str
-
-
-class RequestRenameMemory(BaseModel):
- old_name: str
- new_name: str
-
-
-class ResponseGetSerenaConfig(BaseModel):
- content: str
-
+class InvalidTextLocationError(Exception):
+ pass
+
+
+class TextUtils:
+ """
+ Utilities for text operations.
+ """
+
+ @staticmethod
+ def get_line_col_from_index(text: str, index: int) -> tuple[int, int]:
+ """
+ Returns the zero-indexed line and column number of the given index in the given text
+ """
+ l = 0
+ c = 0
+ idx = 0
+ while idx < index:
+ if text[idx] == "\n":
+ l += 1
+ c = 0
+ else:
+ c += 1
+ idx += 1
+
+ return l, c
+
+ @staticmethod
+ def get_index_from_line_col(text: str, line: int, col: int) -> int:
+ """
```
This class is important because it defines how Serena Tutorial: Semantic Code Retrieval Toolkit for Coding Agents implements the patterns covered in this chapter.
-### `src/serena/dashboard.py`
+### `src/solidlsp/ls_utils.py`
-The `RequestGetMemory` class in [`src/serena/dashboard.py`](https://github.com/oraios/serena/blob/HEAD/src/serena/dashboard.py) handles a key part of this chapter's functionality:
+The `TextUtils` class in [`src/solidlsp/ls_utils.py`](https://github.com/oraios/serena/blob/HEAD/src/solidlsp/ls_utils.py) handles a key part of this chapter's functionality:
```py
-class RequestGetMemory(BaseModel):
- memory_name: str
-
-
-class ResponseGetMemory(BaseModel):
- content: str
- memory_name: str
-
-
-class RequestSaveMemory(BaseModel):
- memory_name: str
- content: str
-
-
-class RequestDeleteMemory(BaseModel):
- memory_name: str
-
-
-class RequestRenameMemory(BaseModel):
- old_name: str
- new_name: str
-
-
-class ResponseGetSerenaConfig(BaseModel):
- content: str
-
-
-class RequestSaveSerenaConfig(BaseModel):
- content: str
-
+class TextUtils:
+ """
+ Utilities for text operations.
+ """
+
+ @staticmethod
+ def get_line_col_from_index(text: str, index: int) -> tuple[int, int]:
+ """
+ Returns the zero-indexed line and column number of the given index in the given text
+ """
+ l = 0
+ c = 0
+ idx = 0
+ while idx < index:
+ if text[idx] == "\n":
+ l += 1
+ c = 0
+ else:
+ c += 1
+ idx += 1
+
+ return l, c
+
+ @staticmethod
+ def get_index_from_line_col(text: str, line: int, col: int) -> int:
+ """
+ Returns the index of the given zero-indexed line and column number in the given text
+ """
+ idx = 0
+ while line > 0:
```
This class is important because it defines how Serena Tutorial: Semantic Code Retrieval Toolkit for Coding Agents implements the patterns covered in this chapter.
-### `src/serena/dashboard.py`
+### `src/solidlsp/ls_utils.py`
-The `ResponseGetMemory` class in [`src/serena/dashboard.py`](https://github.com/oraios/serena/blob/HEAD/src/serena/dashboard.py) handles a key part of this chapter's functionality:
+The `PathUtils` class in [`src/solidlsp/ls_utils.py`](https://github.com/oraios/serena/blob/HEAD/src/solidlsp/ls_utils.py) handles a key part of this chapter's functionality:
```py
-class ResponseGetMemory(BaseModel):
- content: str
- memory_name: str
-
-
-class RequestSaveMemory(BaseModel):
- memory_name: str
- content: str
-
-
-class RequestDeleteMemory(BaseModel):
- memory_name: str
-
-
-class RequestRenameMemory(BaseModel):
- old_name: str
- new_name: str
-
-
-class ResponseGetSerenaConfig(BaseModel):
- content: str
-
-
-class RequestSaveSerenaConfig(BaseModel):
- content: str
-
-
-class RequestCancelTaskExecution(BaseModel):
- task_id: int
+class PathUtils:
+ """
+ Utilities for platform-agnostic path operations.
+ """
+
+ @staticmethod
+ def uri_to_path(uri: str) -> str:
+ """
+ Converts a URI to a file path. Works on both Linux and Windows.
+
+ This method was obtained from https://stackoverflow.com/a/61922504
+ """
+ try:
+ from urllib.parse import unquote, urlparse
+ from urllib.request import url2pathname
+ except ImportError:
+ # backwards compatibility (Python 2)
+ from urllib.parse import unquote as unquote_py2
+ from urllib.request import url2pathname as url2pathname_py2
+
+ from urlparse import urlparse as urlparse_py2
+
+ unquote = unquote_py2
+ url2pathname = url2pathname_py2
+ urlparse = urlparse_py2
+ parsed = urlparse(uri)
+ host = f"{os.path.sep}{os.path.sep}{parsed.netloc}{os.path.sep}"
+ path = os.path.normpath(os.path.join(host, url2pathname(unquote(parsed.path))))
+ return path
```
@@ -219,11 +217,11 @@ This class is important because it defines how Serena Tutorial: Semantic Code Re
```mermaid
flowchart TD
- A[RequestAddLanguage]
- B[RequestRemoveLanguage]
- C[RequestGetMemory]
- D[ResponseGetMemory]
- E[RequestSaveMemory]
+ A[in]
+ B[InvalidTextLocationError]
+ C[TextUtils]
+ D[PathUtils]
+ E[FileUtils]
A --> B
B --> C
C --> D
diff --git a/tutorials/serena-tutorial/07-extending-serena-and-custom-agent-integration.md b/tutorials/serena-tutorial/07-extending-serena-and-custom-agent-integration.md
index 73b78a83..c5e6c9c9 100644
--- a/tutorials/serena-tutorial/07-extending-serena-and-custom-agent-integration.md
+++ b/tutorials/serena-tutorial/07-extending-serena-and-custom-agent-integration.md
@@ -44,142 +44,120 @@ You now know how to plug Serena into bespoke agent systems and extend it safely.
Next: [Chapter 8: Production Operations and Governance](08-production-operations-and-governance.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/serena/dashboard.py`
+### `src/solidlsp/ls_utils.py`
-The `QueuedExecution` class in [`src/serena/dashboard.py`](https://github.com/oraios/serena/blob/HEAD/src/serena/dashboard.py) handles a key part of this chapter's functionality:
+The `_S` class in [`src/solidlsp/ls_utils.py`](https://github.com/oraios/serena/blob/HEAD/src/solidlsp/ls_utils.py) handles a key part of this chapter's functionality:
```py
+ shutil.copyfileobj(source_file, output_file)
+
+ ZIP_SYSTEM_UNIX = 3
+ if zip_info.create_system == ZIP_SYSTEM_UNIX:
+ attrs = (zip_info.external_attr >> 16) & 0o777
+ if attrs:
+ os.chmod(extracted_path, attrs)
+
+ @staticmethod
+ def _extract_tar_archive(archive_path: str, target_path: str, archive_type: str) -> None:
+ """
+ Extracts a tar archive safely into the target directory.
+ """
+ archive_mode_by_type = {
+ "tar": "r:",
+ "gztar": "r:gz",
+ "bztar": "r:bz2",
+ "xztar": "r:xz",
+ }
+ tar_mode = cast(Literal["r:", "r:gz", "r:bz2", "r:xz"], archive_mode_by_type[archive_type])
+
+ with tarfile.open(archive_path, tar_mode) as tar_ref:
+ for tar_member in tar_ref.getmembers():
+ FileUtils._validate_extraction_path(tar_member.name, target_path)
+
+ tar_ref.extractall(target_path)
-class QueuedExecution(BaseModel):
- task_id: int
- is_running: bool
- name: str
- finished_successfully: bool
- logged: bool
-
- @classmethod
- def from_task_info(cls, task_info: TaskExecutor.TaskInfo) -> Self:
- return cls(
- task_id=task_info.task_id,
- is_running=task_info.is_running,
- name=task_info.name,
- finished_successfully=task_info.finished_successfully(),
- logged=task_info.logged,
- )
-
-
-class SerenaDashboardAPI:
- log = logging.getLogger(__qualname__)
-
- def __init__(
- self,
- memory_log_handler: MemoryLogHandler,
- tool_names: list[str],
- agent: "SerenaAgent",
- shutdown_callback: Callable[[], None] | None = None,
- tool_usage_stats: ToolUsageStats | None = None,
- ) -> None:
- self._memory_log_handler = memory_log_handler
+class PlatformId(str, Enum):
+ WIN_x86 = "win-x86"
+ WIN_x64 = "win-x64"
+ WIN_arm64 = "win-arm64"
```
This class is important because it defines how Serena Tutorial: Semantic Code Retrieval Toolkit for Coding Agents implements the patterns covered in this chapter.
-### `src/serena/dashboard.py`
+### `src/solidlsp/ls_utils.py`
-The `SerenaDashboardAPI` class in [`src/serena/dashboard.py`](https://github.com/oraios/serena/blob/HEAD/src/serena/dashboard.py) handles a key part of this chapter's functionality:
+The `SymbolUtils` class in [`src/solidlsp/ls_utils.py`](https://github.com/oraios/serena/blob/HEAD/src/solidlsp/ls_utils.py) handles a key part of this chapter's functionality:
```py
-class SerenaDashboardAPI:
- log = logging.getLogger(__qualname__)
-
- def __init__(
- self,
- memory_log_handler: MemoryLogHandler,
- tool_names: list[str],
- agent: "SerenaAgent",
- shutdown_callback: Callable[[], None] | None = None,
- tool_usage_stats: ToolUsageStats | None = None,
- ) -> None:
- self._memory_log_handler = memory_log_handler
- self._tool_names = tool_names
- self._agent = agent
- self._shutdown_callback = shutdown_callback
- self._app = Flask(__name__)
- self._tool_usage_stats = tool_usage_stats
- self._setup_routes()
-
- @property
- def memory_log_handler(self) -> MemoryLogHandler:
- return self._memory_log_handler
-
- def _setup_routes(self) -> None:
- # Static files
- @self._app.route("/dashboard/<path:filename>")
- def serve_dashboard(filename: str) -> Response:
- return send_from_directory(SERENA_DASHBOARD_DIR, filename)
-
- @self._app.route("/dashboard/")
+class SymbolUtils:
+ @staticmethod
+ def symbol_tree_contains_name(roots: list[UnifiedSymbolInformation], name: str) -> bool:
+ """
+ Check if any symbol in the tree has a name matching the given name.
+ """
+ for symbol in roots:
+ if symbol["name"] == name:
+ return True
+ if SymbolUtils.symbol_tree_contains_name(symbol["children"], name):
+ return True
+ return False
+
```
This class is important because it defines how Serena Tutorial: Semantic Code Retrieval Toolkit for Coding Agents implements the patterns covered in this chapter.
-### `src/solidlsp/ls_config.py`
+### `src/solidlsp/ls_utils.py`
-The `FilenameMatcher` class in [`src/solidlsp/ls_config.py`](https://github.com/oraios/serena/blob/HEAD/src/solidlsp/ls_config.py) handles a key part of this chapter's functionality:
+The `import` interface in [`src/solidlsp/ls_utils.py`](https://github.com/oraios/serena/blob/HEAD/src/solidlsp/ls_utils.py) handles a key part of this chapter's functionality:
```py
+"""
+import gzip
+import hashlib
+import logging
+import os
+import platform
+import shutil
+import subprocess
+import tarfile
+import uuid
+import zipfile
+from enum import Enum
+from pathlib import Path, PurePath
+from typing import Literal, cast
+from urllib.parse import urlparse
-class FilenameMatcher:
- def __init__(self, *patterns: str) -> None:
- """
- :param patterns: fnmatch-compatible patterns
- """
- self.patterns = patterns
+import charset_normalizer
+import requests
- def is_relevant_filename(self, fn: str) -> bool:
- for pattern in self.patterns:
- if fnmatch.fnmatch(fn, pattern):
- return True
- return False
+from solidlsp.ls_exceptions import SolidLSPException
+from solidlsp.ls_types import UnifiedSymbolInformation
+log = logging.getLogger(__name__)
-class Language(str, Enum):
- """
- Enumeration of language servers supported by SolidLSP.
- """
- CSHARP = "csharp"
- PYTHON = "python"
- RUST = "rust"
- JAVA = "java"
- KOTLIN = "kotlin"
- TYPESCRIPT = "typescript"
- GO = "go"
- RUBY = "ruby"
- DART = "dart"
- CPP = "cpp"
- CPP_CCLS = "cpp_ccls"
+class InvalidTextLocationError(Exception):
+ pass
+
+
+class TextUtils:
+ """
```
-This class is important because it defines how Serena Tutorial: Semantic Code Retrieval Toolkit for Coding Agents implements the patterns covered in this chapter.
+This interface is important because it defines how Serena Tutorial: Semantic Code Retrieval Toolkit for Coding Agents implements the patterns covered in this chapter.
### `src/solidlsp/ls_config.py`
-The `Language` class in [`src/solidlsp/ls_config.py`](https://github.com/oraios/serena/blob/HEAD/src/solidlsp/ls_config.py) handles a key part of this chapter's functionality:
+The `FilenameMatcher` class in [`src/solidlsp/ls_config.py`](https://github.com/oraios/serena/blob/HEAD/src/solidlsp/ls_config.py) handles a key part of this chapter's functionality:
```py
-if TYPE_CHECKING:
- from solidlsp import SolidLanguageServer
-
class FilenameMatcher:
def __init__(self, *patterns: str) -> None:
@@ -208,6 +186,9 @@ class Language(str, Enum):
TYPESCRIPT = "typescript"
GO = "go"
RUBY = "ruby"
+ DART = "dart"
+ CPP = "cpp"
+ CPP_CCLS = "cpp_ccls"
```
This class is important because it defines how Serena Tutorial: Semantic Code Retrieval Toolkit for Coding Agents implements the patterns covered in this chapter.
@@ -217,11 +198,11 @@ This class is important because it defines how Serena Tutorial: Semantic Code Re
```mermaid
flowchart TD
- A[QueuedExecution]
- B[SerenaDashboardAPI]
- C[FilenameMatcher]
- D[Language]
- E[to]
+ A[_S]
+ B[SymbolUtils]
+ C[import]
+ D[FilenameMatcher]
+ E[Language]
A --> B
B --> C
C --> D
diff --git a/tutorials/serena-tutorial/08-production-operations-and-governance.md b/tutorials/serena-tutorial/08-production-operations-and-governance.md
index e57decea..1c567b8f 100644
--- a/tutorials/serena-tutorial/08-production-operations-and-governance.md
+++ b/tutorials/serena-tutorial/08-production-operations-and-governance.md
@@ -48,170 +48,168 @@ You now have a complete operational model for deploying Serena as a production-g
Continue with the [Onlook Tutorial](../onlook-tutorial/) for visual-first coding workflows.
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/serena/code_editor.py`
+### `src/serena/symbol.py`
-The `CodeEditor` class in [`src/serena/code_editor.py`](https://github.com/oraios/serena/blob/HEAD/src/serena/code_editor.py) handles a key part of this chapter's functionality:
+The `from` class in [`src/serena/symbol.py`](https://github.com/oraios/serena/blob/HEAD/src/serena/symbol.py) handles a key part of this chapter's functionality:
```py
-
-
-class CodeEditor(Generic[TSymbol], ABC):
- def __init__(self, project: Project) -> None:
- self.project_root = project.project_root
- self.encoding = project.project_config.encoding
- self.newline = project.line_ending.newline_str
-
- class EditedFile(ABC):
- def __init__(self, relative_path: str) -> None:
- self.relative_path = relative_path
-
- @abstractmethod
- def get_contents(self) -> str:
- """
- :return: the contents of the file.
- """
-
- @abstractmethod
- def set_contents(self, contents: str) -> None:
- """
- Fully resets the contents of the file.
-
- :param contents: the new contents
- """
-
- @abstractmethod
- def delete_text_between_positions(self, start_pos: PositionInFile, end_pos: PositionInFile) -> None:
- pass
-
- @abstractmethod
- def insert_text_at_position(self, pos: PositionInFile, text: str) -> None:
+import logging
+import os
+from abc import ABC, abstractmethod
+from collections.abc import Callable, Iterable, Iterator, Sequence
+from dataclasses import asdict, dataclass
+from time import perf_counter
+from typing import Any, Generic, Literal, NotRequired, Self, TypedDict, TypeVar
+
+from sensai.util.string import ToStringMixin
+
+import serena.jetbrains.jetbrains_types as jb
+from solidlsp import SolidLanguageServer
+from solidlsp.ls import LSPFileBuffer
+from solidlsp.ls import ReferenceInSymbol as LSPReferenceInSymbol
+from solidlsp.ls_types import Position, SymbolKind, UnifiedSymbolInformation
+
+from .ls_manager import LanguageServerManager
+from .project import Project
+
+log = logging.getLogger(__name__)
+NAME_PATH_SEP = "/"
+
+
+@dataclass
+class LanguageServerSymbolLocation:
+ """
+ Represents the (start) location of a symbol identifier, which, within Serena, uniquely identifies the symbol.
+ """
+
+ relative_path: str | None
+ """
+ the relative path of the file containing the symbol; if None, the symbol is defined outside of the project's scope
```
This class is important because it defines how Serena Tutorial: Semantic Code Retrieval Toolkit for Coding Agents implements the patterns covered in this chapter.
-### `src/serena/code_editor.py`
+### `src/serena/symbol.py`
-The `EditedFile` class in [`src/serena/code_editor.py`](https://github.com/oraios/serena/blob/HEAD/src/serena/code_editor.py) handles a key part of this chapter's functionality:
+The `class` class in [`src/serena/symbol.py`](https://github.com/oraios/serena/blob/HEAD/src/serena/symbol.py) handles a key part of this chapter's functionality:
```py
- self.newline = project.line_ending.newline_str
-
- class EditedFile(ABC):
- def __init__(self, relative_path: str) -> None:
- self.relative_path = relative_path
-
- @abstractmethod
- def get_contents(self) -> str:
- """
- :return: the contents of the file.
- """
-
- @abstractmethod
- def set_contents(self, contents: str) -> None:
- """
- Fully resets the contents of the file.
-
- :param contents: the new contents
- """
-
- @abstractmethod
- def delete_text_between_positions(self, start_pos: PositionInFile, end_pos: PositionInFile) -> None:
- pass
-
- @abstractmethod
- def insert_text_at_position(self, pos: PositionInFile, text: str) -> None:
- pass
-
- @contextmanager
- def _open_file_context(self, relative_path: str) -> Iterator["CodeEditor.EditedFile"]:
- """
- Context manager for opening a file
+from abc import ABC, abstractmethod
+from collections.abc import Callable, Iterable, Iterator, Sequence
+from dataclasses import asdict, dataclass
+from time import perf_counter
+from typing import Any, Generic, Literal, NotRequired, Self, TypedDict, TypeVar
+
+from sensai.util.string import ToStringMixin
+
+import serena.jetbrains.jetbrains_types as jb
+from solidlsp import SolidLanguageServer
+from solidlsp.ls import LSPFileBuffer
+from solidlsp.ls import ReferenceInSymbol as LSPReferenceInSymbol
+from solidlsp.ls_types import Position, SymbolKind, UnifiedSymbolInformation
+
+from .ls_manager import LanguageServerManager
+from .project import Project
+
+log = logging.getLogger(__name__)
+NAME_PATH_SEP = "/"
+
+
+@dataclass
+class LanguageServerSymbolLocation:
+ """
+ Represents the (start) location of a symbol identifier, which, within Serena, uniquely identifies the symbol.
+ """
+
+ relative_path: str | None
+ """
+ the relative path of the file containing the symbol; if None, the symbol is defined outside of the project's scope
+ """
+ line: int | None
```
This class is important because it defines how Serena Tutorial: Semantic Code Retrieval Toolkit for Coding Agents implements the patterns covered in this chapter.
-### `src/serena/code_editor.py`
+### `src/serena/symbol.py`
-The `LanguageServerCodeEditor` class in [`src/serena/code_editor.py`](https://github.com/oraios/serena/blob/HEAD/src/serena/code_editor.py) handles a key part of this chapter's functionality:
+The `class` class in [`src/serena/symbol.py`](https://github.com/oraios/serena/blob/HEAD/src/serena/symbol.py) handles a key part of this chapter's functionality:
```py
-
-
-class LanguageServerCodeEditor(CodeEditor[LanguageServerSymbol]):
- def __init__(self, symbol_retriever: LanguageServerSymbolRetriever):
- super().__init__(project=symbol_retriever.project)
- self._symbol_retriever = symbol_retriever
-
- def _get_language_server(self, relative_path: str) -> SolidLanguageServer:
- return self._symbol_retriever.get_language_server(relative_path)
-
- class EditedFile(CodeEditor.EditedFile):
- def __init__(self, lang_server: SolidLanguageServer, relative_path: str, file_buffer: LSPFileBuffer):
- super().__init__(relative_path)
- self._lang_server = lang_server
- self._file_buffer = file_buffer
-
- def get_contents(self) -> str:
- return self._file_buffer.contents
-
- def set_contents(self, contents: str) -> None:
- self._file_buffer.contents = contents
-
- def delete_text_between_positions(self, start_pos: PositionInFile, end_pos: PositionInFile) -> None:
- self._lang_server.delete_text_between_positions(self.relative_path, start_pos.to_lsp_position(), end_pos.to_lsp_position())
-
- def insert_text_at_position(self, pos: PositionInFile, text: str) -> None:
- self._lang_server.insert_text_at_position(self.relative_path, pos.line, pos.col, text)
-
- def apply_text_edits(self, text_edits: list[ls_types.TextEdit]) -> None:
- return self._lang_server.apply_text_edits_to_file(self.relative_path, text_edits)
-
- @contextmanager
+from abc import ABC, abstractmethod
+from collections.abc import Callable, Iterable, Iterator, Sequence
+from dataclasses import asdict, dataclass
+from time import perf_counter
+from typing import Any, Generic, Literal, NotRequired, Self, TypedDict, TypeVar
+
+from sensai.util.string import ToStringMixin
+
+import serena.jetbrains.jetbrains_types as jb
+from solidlsp import SolidLanguageServer
+from solidlsp.ls import LSPFileBuffer
+from solidlsp.ls import ReferenceInSymbol as LSPReferenceInSymbol
+from solidlsp.ls_types import Position, SymbolKind, UnifiedSymbolInformation
+
+from .ls_manager import LanguageServerManager
+from .project import Project
+
+log = logging.getLogger(__name__)
+NAME_PATH_SEP = "/"
+
+
+@dataclass
+class LanguageServerSymbolLocation:
+ """
+ Represents the (start) location of a symbol identifier, which, within Serena, uniquely identifies the symbol.
+ """
+
+ relative_path: str | None
+ """
+ the relative path of the file containing the symbol; if None, the symbol is defined outside of the project's scope
+ """
+ line: int | None
```
This class is important because it defines how Serena Tutorial: Semantic Code Retrieval Toolkit for Coding Agents implements the patterns covered in this chapter.
-### `src/serena/code_editor.py`
+### `src/serena/symbol.py`
-The `EditedFile` class in [`src/serena/code_editor.py`](https://github.com/oraios/serena/blob/HEAD/src/serena/code_editor.py) handles a key part of this chapter's functionality:
+The `Symbol` class in [`src/serena/symbol.py`](https://github.com/oraios/serena/blob/HEAD/src/serena/symbol.py) handles a key part of this chapter's functionality:
```py
- self.newline = project.line_ending.newline_str
-
- class EditedFile(ABC):
- def __init__(self, relative_path: str) -> None:
- self.relative_path = relative_path
-
- @abstractmethod
- def get_contents(self) -> str:
- """
- :return: the contents of the file.
- """
-
- @abstractmethod
- def set_contents(self, contents: str) -> None:
- """
- Fully resets the contents of the file.
-
- :param contents: the new contents
- """
-
- @abstractmethod
- def delete_text_between_positions(self, start_pos: PositionInFile, end_pos: PositionInFile) -> None:
- pass
-
- @abstractmethod
- def insert_text_at_position(self, pos: PositionInFile, text: str) -> None:
- pass
-
- @contextmanager
- def _open_file_context(self, relative_path: str) -> Iterator["CodeEditor.EditedFile"]:
- """
- Context manager for opening a file
+from solidlsp import SolidLanguageServer
+from solidlsp.ls import LSPFileBuffer
+from solidlsp.ls import ReferenceInSymbol as LSPReferenceInSymbol
+from solidlsp.ls_types import Position, SymbolKind, UnifiedSymbolInformation
+
+from .ls_manager import LanguageServerManager
+from .project import Project
+
+log = logging.getLogger(__name__)
+NAME_PATH_SEP = "/"
+
+
+@dataclass
+class LanguageServerSymbolLocation:
+ """
+ Represents the (start) location of a symbol identifier, which, within Serena, uniquely identifies the symbol.
+ """
+
+ relative_path: str | None
+ """
+ the relative path of the file containing the symbol; if None, the symbol is defined outside of the project's scope
+ """
+ line: int | None
+ """
+ the line number in which the symbol identifier is defined (if the symbol is a function, class, etc.);
+ may be None for some types of symbols (e.g. SymbolKind.File)
+ """
+ column: int | None
+ """
+ the column number in which the symbol identifier is defined (if the symbol is a function, class, etc.);
+ may be None for some types of symbols (e.g. SymbolKind.File)
+ """
```
This class is important because it defines how Serena Tutorial: Semantic Code Retrieval Toolkit for Coding Agents implements the patterns covered in this chapter.
@@ -221,11 +219,11 @@ This class is important because it defines how Serena Tutorial: Semantic Code Re
```mermaid
flowchart TD
- A[CodeEditor]
- B[EditedFile]
- C[LanguageServerCodeEditor]
- D[EditedFile]
- E[EditOperation]
+ A[from]
+ B[class]
+ C[class]
+ D[Symbol]
+ E[NamePathComponent]
A --> B
B --> C
C --> D
diff --git a/tutorials/shotgun-tutorial/01-getting-started.md b/tutorials/shotgun-tutorial/01-getting-started.md
index 0f60641e..0d2af8f1 100644
--- a/tutorials/shotgun-tutorial/01-getting-started.md
+++ b/tutorials/shotgun-tutorial/01-getting-started.md
@@ -49,8 +49,6 @@ You now have Shotgun running with a first research and planning loop.
Next: [Chapter 2: Router Architecture and Agent Lifecycle](02-router-architecture-and-agent-lifecycle.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `scripts/count_tokens.py`
diff --git a/tutorials/shotgun-tutorial/02-router-architecture-and-agent-lifecycle.md b/tutorials/shotgun-tutorial/02-router-architecture-and-agent-lifecycle.md
index 22aafc96..b5a70360 100644
--- a/tutorials/shotgun-tutorial/02-router-architecture-and-agent-lifecycle.md
+++ b/tutorials/shotgun-tutorial/02-router-architecture-and-agent-lifecycle.md
@@ -44,8 +44,6 @@ You now understand how Shotgun sequences specialized agents across the delivery
Next: [Chapter 3: Planning vs Drafting Execution Modes](03-planning-vs-drafting-execution-modes.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `evals/models.py`
diff --git a/tutorials/shotgun-tutorial/03-planning-vs-drafting-execution-modes.md b/tutorials/shotgun-tutorial/03-planning-vs-drafting-execution-modes.md
index dc27bef4..17aedbc0 100644
--- a/tutorials/shotgun-tutorial/03-planning-vs-drafting-execution-modes.md
+++ b/tutorials/shotgun-tutorial/03-planning-vs-drafting-execution-modes.md
@@ -50,8 +50,6 @@ You can now choose execution mode based on risk, ambiguity, and throughput needs
Next: [Chapter 4: Codebase Indexing and Context Retrieval](04-codebase-indexing-and-context-retrieval.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `evals/models.py`
diff --git a/tutorials/shotgun-tutorial/04-codebase-indexing-and-context-retrieval.md b/tutorials/shotgun-tutorial/04-codebase-indexing-and-context-retrieval.md
index 8548c9e6..aec78757 100644
--- a/tutorials/shotgun-tutorial/04-codebase-indexing-and-context-retrieval.md
+++ b/tutorials/shotgun-tutorial/04-codebase-indexing-and-context-retrieval.md
@@ -40,184 +40,182 @@ You now understand how codebase indexing improves planning and reduces execution
Next: [Chapter 5: CLI Automation and Scripting](05-cli-automation-and-scripting.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `evals/runner.py`
-The `RunnerConfig` class in [`evals/runner.py`](https://github.com/shotgun-sh/shotgun/blob/HEAD/evals/runner.py) handles a key part of this chapter's functionality:
+The `main` function in [`evals/runner.py`](https://github.com/shotgun-sh/shotgun/blob/HEAD/evals/runner.py) handles a key part of this chapter's functionality:
```py
-class RunnerConfig:
- """Configuration for the evaluation runner."""
+async def main() -> int:
+ """Main entry point for the evaluation runner."""
+ args = parse_args()
- def __init__(
- self,
- max_concurrency: int = 2,
- enable_judge: bool = True,
- judge_concurrency: int = 1,
- timeout_seconds: float = 300.0,
- ) -> None:
- """Initialize runner configuration.
+ # Configure logging
+ logging.basicConfig(
+ level=logging.INFO,
+ format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+ )
- Args:
- max_concurrency: Maximum concurrent test case executions
- enable_judge: Whether to run LLM judge evaluation
- judge_concurrency: Concurrency for judge calls (conservative default)
- timeout_seconds: Timeout per test case
- """
- self.max_concurrency = max_concurrency
- self.enable_judge = enable_judge
- self.judge_concurrency = judge_concurrency
- self.timeout_seconds = timeout_seconds
+ # Create runner config
+ config = RunnerConfig(
+ max_concurrency=args.concurrency,
+ enable_judge=not args.no_judge,
+ judge_concurrency=args.judge_concurrency,
+ )
+ # Create runner
+ runner = EvaluationRunner(config=config)
-class EvaluationRunner:
- """
- Runs evaluation suites and produces reports.
+ # Determine which models to run
+ models_to_run = get_models_to_run(args)
- Orchestrates:
- 1. Test case execution via RouterExecutor
+ try:
+ reports: list[EvaluationReport] = []
+
+ # If no models specified, run with default
+ if not models_to_run:
+ models_to_run_iter: list[ModelName | None] = [None]
+ else:
```
-This class is important because it defines how Shotgun Tutorial: Spec-Driven Development for Coding Agents implements the patterns covered in this chapter.
+This function is important because it defines how Shotgun Tutorial: Spec-Driven Development for Coding Agents implements the patterns covered in this chapter.
-### `evals/runner.py`
+### `evals/executor.py`
-The `EvaluationRunner` class in [`evals/runner.py`](https://github.com/shotgun-sh/shotgun/blob/HEAD/evals/runner.py) handles a key part of this chapter's functionality:
+The `ExecutionError` class in [`evals/executor.py`](https://github.com/shotgun-sh/shotgun/blob/HEAD/evals/executor.py) handles a key part of this chapter's functionality:
```py
-class EvaluationRunner:
+class ExecutionError(Exception):
+ """Raised when test case execution fails."""
+
+
+class ExecutionResult(BaseModel):
+ """Result from executing a single test case."""
+
+ test_case_name: str = Field(..., description="Name of the executed test case")
+ output: AgentExecutionOutput = Field(
+ ..., description="Captured execution output from the agent"
+ )
+ trace_ref: TraceRef = Field(
+ ..., description="Logfire trace reference for debugging"
+ )
+ error: str | None = Field(
+ default=None, description="Error message if execution failed"
+ )
+
+
+class RouterExecutor:
"""
- Runs evaluation suites and produces reports.
-
- Orchestrates:
- 1. Test case execution via RouterExecutor
- 2. Deterministic evaluation
- 3. LLM judge evaluation (optional, with conservative concurrency)
- 4. Result aggregation
- 5. Report generation
+ Executes Router agent test cases with Logfire instrumentation.
+
+ This executor wraps the AgentManager to run test cases and capture
+ evaluable outputs with trace references for debugging.
"""
- def __init__(
- self,
- config: RunnerConfig | None = None,
- working_directory: Path | None = None,
- ) -> None:
- """Initialize the evaluation runner.
+ def __init__(self, working_directory: Path | None = None) -> None:
+ """Initialize the RouterExecutor.
- Args:
- config: Runner configuration
- working_directory: Working directory for agent execution
- """
- self.config = config or RunnerConfig()
- self.executor = RouterExecutor(working_directory=working_directory)
- # Initialize judges lazily based on evaluator_names
- self._router_judge: RouterQualityJudge | None = None
- self._file_requests_judge: FileRequestsJudge | None = None
- self._web_search_efficiency_judge: WebSearchEfficiencyJudge | None = None
- self.aggregator = RouterAggregator()
```
This class is important because it defines how Shotgun Tutorial: Spec-Driven Development for Coding Agents implements the patterns covered in this chapter.
-### `evals/runner.py`
+### `evals/executor.py`
-The `get_model_presets` function in [`evals/runner.py`](https://github.com/shotgun-sh/shotgun/blob/HEAD/evals/runner.py) handles a key part of this chapter's functionality:
+The `ExecutionResult` class in [`evals/executor.py`](https://github.com/shotgun-sh/shotgun/blob/HEAD/evals/executor.py) handles a key part of this chapter's functionality:
```py
-def get_model_presets() -> dict[str, list[ModelName]]:
- """Build model presets from MODEL_SPECS registry.
+class ExecutionResult(BaseModel):
+ """Result from executing a single test case."""
+
+ test_case_name: str = Field(..., description="Name of the executed test case")
+ output: AgentExecutionOutput = Field(
+ ..., description="Captured execution output from the agent"
+ )
+ trace_ref: TraceRef = Field(
+ ..., description="Logfire trace reference for debugging"
+ )
+ error: str | None = Field(
+ default=None, description="Error message if execution failed"
+ )
+
- Returns:
- Dictionary mapping preset names to lists of ModelName enums.
- Presets include 'all', 'anthropic', 'openai', 'google', and 'fast'.
+class RouterExecutor:
"""
- all_models = list(MODEL_SPECS.keys())
-
- # Group by provider
- by_provider: dict[ProviderType, list[ModelName]] = {}
- for model_name, spec in MODEL_SPECS.items():
- by_provider.setdefault(spec.provider, []).append(model_name)
-
- return {
- "all": all_models,
- "anthropic": by_provider.get(ProviderType.ANTHROPIC, []),
- "openai": by_provider.get(ProviderType.OPENAI, []),
- "google": by_provider.get(ProviderType.GOOGLE, []),
- # Fast models - one per provider (cheapest/fastest)
- "fast": [
- ModelName.CLAUDE_HAIKU_4_5,
- ModelName.GPT_5_1,
- ModelName.GEMINI_2_5_FLASH_LITE,
- ],
- }
-
-
-# Available model presets for CLI
-MODEL_PRESETS = get_model_presets()
+ Executes Router agent test cases with Logfire instrumentation.
+
+ This executor wraps the AgentManager to run test cases and capture
+ evaluable outputs with trace references for debugging.
+ """
+
+ def __init__(self, working_directory: Path | None = None) -> None:
+ """Initialize the RouterExecutor.
+
+ Args:
+ working_directory: Working directory for agent execution.
+ Defaults to current working directory.
+ """
```
-This function is important because it defines how Shotgun Tutorial: Spec-Driven Development for Coding Agents implements the patterns covered in this chapter.
+This class is important because it defines how Shotgun Tutorial: Spec-Driven Development for Coding Agents implements the patterns covered in this chapter.
-### `evals/runner.py`
+### `evals/executor.py`
-The `parse_args` function in [`evals/runner.py`](https://github.com/shotgun-sh/shotgun/blob/HEAD/evals/runner.py) handles a key part of this chapter's functionality:
+The `RouterExecutor` class in [`evals/executor.py`](https://github.com/shotgun-sh/shotgun/blob/HEAD/evals/executor.py) handles a key part of this chapter's functionality:
```py
-def parse_args() -> argparse.Namespace:
- """Parse command line arguments."""
- # Build available model choices from MODEL_SPECS
- available_models = [m.value for m in ModelName]
-
- parser = argparse.ArgumentParser(
- description="Run Router agent evaluation suites",
- formatter_class=argparse.RawDescriptionHelpFormatter,
- epilog=f"""
-Examples:
- python -m evals.runner --suite router_smoke --report json --out evals/reports/router_smoke.json
- python -m evals.runner --suite router_core --report console
- python -m evals.runner --case local_models_clarifying_questions
- python -m evals.runner --tag smoke
-
-Model comparison examples:
- python -m evals.runner --suite router_smoke --model claude-sonnet-4-6
- python -m evals.runner --suite router_smoke --model claude-sonnet-4-6 --model gpt-5.1
- python -m evals.runner --suite router_smoke --models anthropic
- python -m evals.runner --suite router_smoke --models fast
-
-Available models: {", ".join(available_models)}
-Available presets: {", ".join(MODEL_PRESETS.keys())}
- """,
- )
+class RouterExecutor:
+ """
+ Executes Router agent test cases with Logfire instrumentation.
+
+ This executor wraps the AgentManager to run test cases and capture
+ evaluable outputs with trace references for debugging.
+ """
+
+ def __init__(self, working_directory: Path | None = None) -> None:
+ """Initialize the RouterExecutor.
+
+ Args:
+ working_directory: Working directory for agent execution.
+ Defaults to current working directory.
+ """
+ self._configured = False
+ self._working_directory = working_directory or Path.cwd()
+
+ async def _ensure_configured(self) -> None:
+ """Ensure Logfire and API keys are configured. Raises if misconfigured."""
+ if not self._configured:
+ configure_logfire_or_fail()
+ await inject_env_api_keys()
+ self._configured = True
- # Selection options (mutually exclusive)
- selection = parser.add_mutually_exclusive_group(required=True)
- selection.add_argument("--suite", help="Run a named suite")
- selection.add_argument("--tag", help="Run all suites matching a tag")
+ async def execute_case(
+ self,
+ test_case: ShotgunTestCase,
+ suite_name: str = "default",
+ model_override: ModelName | None = None,
```
-This function is important because it defines how Shotgun Tutorial: Spec-Driven Development for Coding Agents implements the patterns covered in this chapter.
+This class is important because it defines how Shotgun Tutorial: Spec-Driven Development for Coding Agents implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[RunnerConfig]
- B[EvaluationRunner]
- C[get_model_presets]
- D[parse_args]
- E[get_models_to_run]
+ A[main]
+ B[ExecutionError]
+ C[ExecutionResult]
+ D[RouterExecutor]
+ E[inject_env_api_keys]
A --> B
B --> C
C --> D
diff --git a/tutorials/shotgun-tutorial/05-cli-automation-and-scripting.md b/tutorials/shotgun-tutorial/05-cli-automation-and-scripting.md
index db316355..7c1f0542 100644
--- a/tutorials/shotgun-tutorial/05-cli-automation-and-scripting.md
+++ b/tutorials/shotgun-tutorial/05-cli-automation-and-scripting.md
@@ -41,184 +41,182 @@ You can now run Shotgun workflows both interactively and in scripted pipelines.
Next: [Chapter 6: Context7 MCP and Local Models](06-context7-mcp-and-local-models.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `evals/judges/file_requests_judge.py`
-The `import` interface in [`evals/judges/file_requests_judge.py`](https://github.com/shotgun-sh/shotgun/blob/HEAD/evals/judges/file_requests_judge.py) handles a key part of this chapter's functionality:
+The `FileRequestsScoreOutput` class in [`evals/judges/file_requests_judge.py`](https://github.com/shotgun-sh/shotgun/blob/HEAD/evals/judges/file_requests_judge.py) handles a key part of this chapter's functionality:
```py
-"""
-
-import logging
-from enum import StrEnum
-import logfire
-from pydantic import BaseModel, Field
-from pydantic_ai import Agent
-from evals.models import (
- AgentExecutionOutput,
- DimensionScoreOutput,
- EvaluationResult,
- JudgeModelConfig,
- JudgeProviderType,
- ShotgunTestCase,
-)
+class FileRequestsScoreOutput(BaseModel):
+ """Output structure for all file_requests dimension scores."""
-logger = logging.getLogger(__name__)
+ file_request_usage: DimensionScoreOutput = Field(
+ description="Score for correct file_requests usage"
+ )
+ no_unnecessary_questions: DimensionScoreOutput = Field(
+ description="Score for not asking unnecessary clarifying questions"
+ )
+ appropriate_response: DimensionScoreOutput = Field(
+ description="Score for appropriate response text"
+ )
+ no_wrong_delegation: DimensionScoreOutput = Field(
+ description="Score for not delegating to wrong agents"
+ )
-class FileRequestsDimension(StrEnum):
- """Dimensions for evaluating file_requests behavior."""
+class FileRequestsJudgeResult(BaseModel):
+ """Result from file_requests judge evaluation."""
- FILE_REQUEST_USAGE = "file_request_usage"
- NO_UNNECESSARY_QUESTIONS = "no_unnecessary_questions"
- APPROPRIATE_RESPONSE = "appropriate_response"
- NO_WRONG_DELEGATION = "no_wrong_delegation"
+ dimension_scores: dict[str, DimensionScoreOutput]
+ overall_score: float
+ overall_passed: bool
+ summary: str
-class FileRequestsDimensionRubric(BaseModel):
- """Rubric definition for a file_requests evaluation dimension."""
+# Default rubrics for file_requests evaluation dimensions
+DEFAULT_FILE_REQUESTS_RUBRICS: dict[
+ FileRequestsDimension, FileRequestsDimensionRubric
+] = {
```
-This interface is important because it defines how Shotgun Tutorial: Spec-Driven Development for Coding Agents implements the patterns covered in this chapter.
+This class is important because it defines how Shotgun Tutorial: Spec-Driven Development for Coding Agents implements the patterns covered in this chapter.
-### `src/shotgun/main.py`
+### `evals/judges/file_requests_judge.py`
-The `version_callback` function in [`src/shotgun/main.py`](https://github.com/shotgun-sh/shotgun/blob/HEAD/src/shotgun/main.py) handles a key part of this chapter's functionality:
+The `FileRequestsJudgeResult` class in [`evals/judges/file_requests_judge.py`](https://github.com/shotgun-sh/shotgun/blob/HEAD/evals/judges/file_requests_judge.py) handles a key part of this chapter's functionality:
```py
-def version_callback(value: bool) -> None:
- """Show version and exit."""
- if value:
- from rich.console import Console
-
- console = Console()
- console.print(f"shotgun {__version__}")
- raise typer.Exit()
-
-
-@app.callback(invoke_without_command=True)
-def main(
- ctx: typer.Context,
- version: Annotated[
- bool,
- typer.Option(
- "--version",
- "-v",
- callback=version_callback,
- is_eager=True,
- help="Show version and exit",
- ),
- ] = False,
- no_update_check: Annotated[
- bool,
- typer.Option(
- "--no-update-check",
- help="Disable automatic update checks",
- ),
- ] = False,
+class FileRequestsJudgeResult(BaseModel):
+ """Result from file_requests judge evaluation."""
+
+ dimension_scores: dict[str, DimensionScoreOutput]
+ overall_score: float
+ overall_passed: bool
+ summary: str
+
+
+# Default rubrics for file_requests evaluation dimensions
+DEFAULT_FILE_REQUESTS_RUBRICS: dict[
+ FileRequestsDimension, FileRequestsDimensionRubric
+] = {
+ FileRequestsDimension.FILE_REQUEST_USAGE: FileRequestsDimensionRubric(
+ dimension=FileRequestsDimension.FILE_REQUEST_USAGE,
+ description="Did the Router correctly use file_requests to load the binary file?",
+ weight=2.0, # Highest weight - this is the core behavior being tested
+ rubric_text="""
+Evaluate if the Router correctly used file_requests to load the binary file on a 1-5 scale:
+
+**File Request Usage:**
+5 (Excellent): Router immediately used file_requests with the correct file path. No hesitation or unnecessary steps.
+4 (Good): Router used file_requests correctly but with minor issues (slight delay or extra explanation).
+3 (Average): Router eventually used file_requests but took unnecessary steps first.
+2 (Fair): Router attempted to use file_requests but with incorrect path or format.
+1 (Poor): Router did not use file_requests at all, or claimed inability to access the file.
+
+Consider:
+- Did the Router include the file path in file_requests?
+- Was the response immediate rather than asking for more information first?
```
-This function is important because it defines how Shotgun Tutorial: Spec-Driven Development for Coding Agents implements the patterns covered in this chapter.
+This class is important because it defines how Shotgun Tutorial: Spec-Driven Development for Coding Agents implements the patterns covered in this chapter.
-### `src/shotgun/main.py`
+### `evals/judges/file_requests_judge.py`
-The `main` function in [`src/shotgun/main.py`](https://github.com/shotgun-sh/shotgun/blob/HEAD/src/shotgun/main.py) handles a key part of this chapter's functionality:
+The `FileRequestsJudge` class in [`evals/judges/file_requests_judge.py`](https://github.com/shotgun-sh/shotgun/blob/HEAD/evals/judges/file_requests_judge.py) handles a key part of this chapter's functionality:
```py
-@app.callback(invoke_without_command=True)
-def main(
- ctx: typer.Context,
- version: Annotated[
- bool,
- typer.Option(
- "--version",
- "-v",
- callback=version_callback,
- is_eager=True,
- help="Show version and exit",
- ),
- ] = False,
- no_update_check: Annotated[
- bool,
- typer.Option(
- "--no-update-check",
- help="Disable automatic update checks",
- ),
- ] = False,
- continue_session: Annotated[
- bool,
- typer.Option(
- "--continue",
- "-c",
- help="Continue previous TUI conversation",
- ),
- ] = False,
- web: Annotated[
- bool,
- typer.Option(
+
+class FileRequestsJudgeResult(BaseModel):
+ """Result from file_requests judge evaluation."""
+
+ dimension_scores: dict[str, DimensionScoreOutput]
+ overall_score: float
+ overall_passed: bool
+ summary: str
+
+
+# Default rubrics for file_requests evaluation dimensions
+DEFAULT_FILE_REQUESTS_RUBRICS: dict[
+ FileRequestsDimension, FileRequestsDimensionRubric
+] = {
+ FileRequestsDimension.FILE_REQUEST_USAGE: FileRequestsDimensionRubric(
+ dimension=FileRequestsDimension.FILE_REQUEST_USAGE,
+ description="Did the Router correctly use file_requests to load the binary file?",
+ weight=2.0, # Highest weight - this is the core behavior being tested
+ rubric_text="""
+Evaluate if the Router correctly used file_requests to load the binary file on a 1-5 scale:
+
+**File Request Usage:**
+5 (Excellent): Router immediately used file_requests with the correct file path. No hesitation or unnecessary steps.
+4 (Good): Router used file_requests correctly but with minor issues (slight delay or extra explanation).
+3 (Average): Router eventually used file_requests but took unnecessary steps first.
+2 (Fair): Router attempted to use file_requests but with incorrect path or format.
+1 (Poor): Router did not use file_requests at all, or claimed inability to access the file.
+
+Consider:
+- Did the Router include the file path in file_requests?
+- Was the response immediate rather than asking for more information first?
```
-This function is important because it defines how Shotgun Tutorial: Spec-Driven Development for Coding Agents implements the patterns covered in this chapter.
+This class is important because it defines how Shotgun Tutorial: Spec-Driven Development for Coding Agents implements the patterns covered in this chapter.
-### `src/shotgun/exceptions.py`
+### `evals/judges/file_requests_judge.py`
-The `UserActionableError` class in [`src/shotgun/exceptions.py`](https://github.com/shotgun-sh/shotgun/blob/HEAD/src/shotgun/exceptions.py) handles a key part of this chapter's functionality:
+The `import` interface in [`evals/judges/file_requests_judge.py`](https://github.com/shotgun-sh/shotgun/blob/HEAD/evals/judges/file_requests_judge.py) handles a key part of this chapter's functionality:
```py
+"""
+import logging
+from enum import StrEnum
-class UserActionableError(Exception): # noqa: N818
- """Base for user-actionable errors that shouldn't be sent to telemetry.
-
- These errors represent expected user conditions requiring action
- rather than bugs that need tracking.
-
- All subclasses should implement to_markdown() and to_plain_text() methods
- for consistent error message formatting.
- """
-
- def to_markdown(self) -> str:
- """Generate markdown-formatted error message for TUI.
+import logfire
+from pydantic import BaseModel, Field
+from pydantic_ai import Agent
- Subclasses should override this method.
- """
- return f"⚠️ {str(self)}"
+from evals.models import (
+ AgentExecutionOutput,
+ DimensionScoreOutput,
+ EvaluationResult,
+ JudgeModelConfig,
+ JudgeProviderType,
+ ShotgunTestCase,
+)
- def to_plain_text(self) -> str:
- """Generate plain text error message for CLI.
+logger = logging.getLogger(__name__)
- Subclasses should override this method.
- """
- return f"⚠️ {str(self)}"
+class FileRequestsDimension(StrEnum):
+ """Dimensions for evaluating file_requests behavior."""
-# ============================================================================
-# User Action Required Errors
-# ============================================================================
+ FILE_REQUEST_USAGE = "file_request_usage"
+ NO_UNNECESSARY_QUESTIONS = "no_unnecessary_questions"
+ APPROPRIATE_RESPONSE = "appropriate_response"
+ NO_WRONG_DELEGATION = "no_wrong_delegation"
+class FileRequestsDimensionRubric(BaseModel):
+ """Rubric definition for a file_requests evaluation dimension."""
```
-This class is important because it defines how Shotgun Tutorial: Spec-Driven Development for Coding Agents implements the patterns covered in this chapter.
+This interface is important because it defines how Shotgun Tutorial: Spec-Driven Development for Coding Agents implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[import]
- B[version_callback]
- C[main]
- D[UserActionableError]
- E[AgentCancelledException]
+ A[FileRequestsScoreOutput]
+ B[FileRequestsJudgeResult]
+ C[FileRequestsJudge]
+ D[import]
+ E[LogfireConfigurationError]
A --> B
B --> C
C --> D
diff --git a/tutorials/shotgun-tutorial/06-context7-mcp-and-local-models.md b/tutorials/shotgun-tutorial/06-context7-mcp-and-local-models.md
index fc8c56f7..1089751e 100644
--- a/tutorials/shotgun-tutorial/06-context7-mcp-and-local-models.md
+++ b/tutorials/shotgun-tutorial/06-context7-mcp-and-local-models.md
@@ -38,170 +38,168 @@ You now have a model for combining live docs retrieval and local-model execution
Next: [Chapter 7: Spec Sharing and Collaboration Workflows](07-spec-sharing-and-collaboration-workflows.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/shotgun/exceptions.py`
+### `src/shotgun/settings.py`
-The `BYOKQuotaBillingException` class in [`src/shotgun/exceptions.py`](https://github.com/shotgun-sh/shotgun/blob/HEAD/src/shotgun/exceptions.py) handles a key part of this chapter's functionality:
+The `that` class in [`src/shotgun/settings.py`](https://github.com/shotgun-sh/shotgun/blob/HEAD/src/shotgun/settings.py) handles a key part of this chapter's functionality:
```py
+ """Main application settings with SHOTGUN_ prefix.
+ This is the main settings class that composes all other settings groups.
+ Access settings via the global `settings` singleton instance.
-class BYOKQuotaBillingException(BYOKAPIException):
- """Raised when BYOK user has quota or billing issues."""
-
- def __init__(self, message: str):
- """Initialize the exception.
-
- Args:
- message: The error message from the API
- """
- super().__init__(message, specific_error="Quota or billing issue")
-
+ Example:
+ from shotgun.settings import settings
-class BYOKAuthenticationException(BYOKAPIException):
- """Raised when BYOK authentication fails."""
+ # Telemetry settings
+ settings.telemetry.posthog_api_key
+ settings.telemetry.logfire_enabled
- def __init__(self, message: str):
- """Initialize the exception.
+ # Logging settings
+ settings.logging.log_level
+ settings.logging.logging_to_console
- Args:
- message: The error message from the API
- """
- super().__init__(message, specific_error="Authentication error")
+ # API settings
+ settings.api.web_base_url
+ settings.api.account_llm_base_url
+ # Development settings
+ settings.dev.home
+ settings.dev.pipx_simulate
-class BYOKServiceOverloadException(BYOKAPIException):
- """Raised when BYOK service is overloaded."""
-
- def __init__(self, message: str):
- """Initialize the exception.
+ # Indexing settings
+ settings.indexing.index_parallel
+ settings.indexing.index_workers
+ """
+ telemetry: TelemetrySettings = Field(default_factory=TelemetrySettings)
+ logging: LoggingSettings = Field(default_factory=LoggingSettings)
+ api: ApiSettings = Field(default_factory=ApiSettings)
```
This class is important because it defines how Shotgun Tutorial: Spec-Driven Development for Coding Agents implements the patterns covered in this chapter.
-### `src/shotgun/exceptions.py`
+### `evals/reporters/console.py`
-The `BYOKAuthenticationException` class in [`src/shotgun/exceptions.py`](https://github.com/shotgun-sh/shotgun/blob/HEAD/src/shotgun/exceptions.py) handles a key part of this chapter's functionality:
+The `ConsoleReporter` class in [`evals/reporters/console.py`](https://github.com/shotgun-sh/shotgun/blob/HEAD/evals/reporters/console.py) handles a key part of this chapter's functionality:
```py
-class BYOKAuthenticationException(BYOKAPIException):
- """Raised when BYOK authentication fails."""
-
- def __init__(self, message: str):
- """Initialize the exception.
+class ConsoleReporter:
+ """
+ Formats evaluation reports for console output.
- Args:
- message: The error message from the API
- """
- super().__init__(message, specific_error="Authentication error")
+ Emphasizes scores and trace references for quick debugging.
+ """
+ # ANSI color codes
+ GREEN = "\033[92m"
+ RED = "\033[91m"
+ YELLOW = "\033[93m"
+ BLUE = "\033[94m"
+ BOLD = "\033[1m"
+ RESET = "\033[0m"
-class BYOKServiceOverloadException(BYOKAPIException):
- """Raised when BYOK service is overloaded."""
-
- def __init__(self, message: str):
- """Initialize the exception.
+ def __init__(self, use_color: bool = True) -> None:
+ """Initialize the console reporter.
Args:
- message: The error message from the API
+ use_color: Whether to use ANSI color codes
"""
- super().__init__(message, specific_error="Service overloaded")
-
-
-class BYOKGenericAPIException(BYOKAPIException):
- """Raised for generic BYOK API errors."""
+ self.use_color = use_color and sys.stdout.isatty()
- def __init__(self, message: str):
- """Initialize the exception.
+ def _color(self, text: str, color: str) -> str:
+ """Apply color to text if colors are enabled."""
+ if self.use_color:
+ return f"{color}{text}{self.RESET}"
+ return text
+ def _status_icon(self, passed: bool) -> str:
```
This class is important because it defines how Shotgun Tutorial: Spec-Driven Development for Coding Agents implements the patterns covered in this chapter.
-### `src/shotgun/exceptions.py`
+### `evals/aggregators/router_aggregator.py`
-The `BYOKServiceOverloadException` class in [`src/shotgun/exceptions.py`](https://github.com/shotgun-sh/shotgun/blob/HEAD/src/shotgun/exceptions.py) handles a key part of this chapter's functionality:
+The `RouterAggregator` class in [`evals/aggregators/router_aggregator.py`](https://github.com/shotgun-sh/shotgun/blob/HEAD/evals/aggregators/router_aggregator.py) handles a key part of this chapter's functionality:
```py
-class BYOKServiceOverloadException(BYOKAPIException):
- """Raised when BYOK service is overloaded."""
+class RouterAggregator:
+ """
+ Aggregates evaluation results from deterministic evaluators and LLM judge.
- def __init__(self, message: str):
- """Initialize the exception.
+ Aggregation rules:
+ 1. Any HARD failure from deterministic evaluators -> overall failure
+ 2. SOFT failures are recorded but don't cause overall failure
+ 3. LLM judge scores contribute to dimension averages
+ 4. Overall score is weighted average of all dimensions
+ 5. Trace reference is attached for debugging
+ """
- Args:
- message: The error message from the API
- """
- super().__init__(message, specific_error="Service overloaded")
-
-
-class BYOKGenericAPIException(BYOKAPIException):
- """Raised for generic BYOK API errors."""
-
- def __init__(self, message: str):
- """Initialize the exception.
+ def __init__(
+ self,
+ hard_failure_causes_fail: bool = True,
+ soft_failure_weight: float = 0.5,
+ pass_threshold: float = 3.0,
+ ) -> None:
+ """Initialize the aggregator.
Args:
- message: The error message from the API
+ hard_failure_causes_fail: Whether hard failures cause overall fail
+ soft_failure_weight: Weight for soft failure penalty (0-1)
+ pass_threshold: Minimum score to pass (1-5 scale, default 3.0)
"""
- super().__init__(message, specific_error="API error")
-
-
-# ============================================================================
-# Generic Errors
-# ============================================================================
-
+ self.hard_failure_causes_fail = hard_failure_causes_fail
+ self.soft_failure_weight = soft_failure_weight
+ self.pass_threshold = pass_threshold
-class GenericAPIStatusException(UserActionableError): # noqa: N818
+ def aggregate(
```
This class is important because it defines how Shotgun Tutorial: Spec-Driven Development for Coding Agents implements the patterns covered in this chapter.
-### `src/shotgun/exceptions.py`
+### `src/shotgun/logging_config.py`
-The `BYOKGenericAPIException` class in [`src/shotgun/exceptions.py`](https://github.com/shotgun-sh/shotgun/blob/HEAD/src/shotgun/exceptions.py) handles a key part of this chapter's functionality:
+The `ColoredFormatter` class in [`src/shotgun/logging_config.py`](https://github.com/shotgun-sh/shotgun/blob/HEAD/src/shotgun/logging_config.py) handles a key part of this chapter's functionality:
```py
-class BYOKGenericAPIException(BYOKAPIException):
- """Raised for generic BYOK API errors."""
+class ColoredFormatter(logging.Formatter):
+ """Custom formatter with colors for different log levels."""
- def __init__(self, message: str):
- """Initialize the exception.
+ # ANSI color codes
+ COLORS = {
+ "DEBUG": "\033[36m", # Cyan
+ "INFO": "\033[32m", # Green
+ "WARNING": "\033[33m", # Yellow
+ "ERROR": "\033[31m", # Red
+ "CRITICAL": "\033[35m", # Magenta
+ }
+ RESET = "\033[0m"
- Args:
- message: The error message from the API
- """
- super().__init__(message, specific_error="API error")
-
-
-# ============================================================================
-# Generic Errors
-# ============================================================================
+ def format(self, record: logging.LogRecord) -> str:
+ # Create a copy of the record to avoid modifying the original
+ record = logging.makeLogRecord(record.__dict__)
+ # Add color to levelname
+ if record.levelname in self.COLORS:
+ colored_levelname = (
+ f"{self.COLORS[record.levelname]}{record.levelname}{self.RESET}"
+ )
+ record.levelname = colored_levelname
-class GenericAPIStatusException(UserActionableError): # noqa: N818
- """Raised for generic API status errors that don't fit other categories."""
+ return super().format(record)
- def __init__(self, message: str):
- """Initialize the exception.
-
- Args:
- message: The error message from the API
- """
- self.api_message = message
- super().__init__(message)
- def to_markdown(self) -> str:
+def setup_logger(
+ name: str,
+ format_string: str | None = None,
```
This class is important because it defines how Shotgun Tutorial: Spec-Driven Development for Coding Agents implements the patterns covered in this chapter.
@@ -211,11 +209,11 @@ This class is important because it defines how Shotgun Tutorial: Spec-Driven Dev
```mermaid
flowchart TD
- A[BYOKQuotaBillingException]
- B[BYOKAuthenticationException]
- C[BYOKServiceOverloadException]
- D[BYOKGenericAPIException]
- E[GenericAPIStatusException]
+ A[that]
+ B[ConsoleReporter]
+ C[RouterAggregator]
+ D[ColoredFormatter]
+ E[get_log_directory]
A --> B
B --> C
C --> D
diff --git a/tutorials/shotgun-tutorial/07-spec-sharing-and-collaboration-workflows.md b/tutorials/shotgun-tutorial/07-spec-sharing-and-collaboration-workflows.md
index 96eaa3b2..86ffa81f 100644
--- a/tutorials/shotgun-tutorial/07-spec-sharing-and-collaboration-workflows.md
+++ b/tutorials/shotgun-tutorial/07-spec-sharing-and-collaboration-workflows.md
@@ -40,170 +40,166 @@ You can now structure multi-person review around stable spec artifacts instead o
Next: [Chapter 8: Production Operations, Observability, and Security](08-production-operations-observability-and-security.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/shotgun/settings.py`
+### `src/shotgun/exceptions.py`
-The `ApiSettings` class in [`src/shotgun/settings.py`](https://github.com/shotgun-sh/shotgun/blob/HEAD/src/shotgun/settings.py) handles a key part of this chapter's functionality:
+The `ContextSizeLimitExceeded` class in [`src/shotgun/exceptions.py`](https://github.com/shotgun-sh/shotgun/blob/HEAD/src/shotgun/exceptions.py) handles a key part of this chapter's functionality:
```py
-class ApiSettings(BaseSettings):
- """API endpoint settings.
+class ContextSizeLimitExceeded(UserActionableError): # noqa: N818
+ """Raised when conversation context exceeds the model's limits.
- Configuration for Shotgun backend services.
+ This is a user-actionable error - they need to either:
+ 1. Switch to a larger context model
+ 2. Switch to a larger model, compact their conversation, then switch back
+ 3. Clear the conversation and start fresh
"""
- web_base_url: str = Field(
- default="https://api-219702594231.us-east4.run.app",
- description="Shotgun Web API base URL (authentication/subscription)",
- )
- account_llm_base_url: str = Field(
- default="https://litellm-219702594231.us-east4.run.app",
- description="Shotgun's LiteLLM proxy base URL (AI model requests)",
- )
+ def __init__(self, model_name: str, max_tokens: int):
+ """Initialize the exception.
+
+ Args:
+ model_name: Name of the model whose limit was exceeded
+ max_tokens: Maximum tokens allowed by the model
+ """
+ self.model_name = model_name
+ self.max_tokens = max_tokens
+ super().__init__(
+ f"Context too large for {model_name} (limit: {max_tokens:,} tokens)"
+ )
+
+ def to_markdown(self) -> str:
+ """Generate markdown-formatted error message for TUI."""
+ return (
+ f"⚠️ **Context too large for {self.model_name}**\n\n"
+ f"Your conversation history exceeds this model's limit ({self.max_tokens:,} tokens).\n\n"
+ f"**Choose an action:**\n\n"
+ f"1. Switch to a larger model (`/` → Change Model)\n"
+ f"2. Switch to a larger model, compact (`/compact`), then switch back to {self.model_name}\n"
+```
+
+This class is important because it defines how Shotgun Tutorial: Spec-Driven Development for Coding Agents implements the patterns covered in this chapter.
+
+### `src/shotgun/exceptions.py`
+
+The `ShotgunAccountException` class in [`src/shotgun/exceptions.py`](https://github.com/shotgun-sh/shotgun/blob/HEAD/src/shotgun/exceptions.py) handles a key part of this chapter's functionality:
- model_config = SettingsConfigDict(
- env_prefix="SHOTGUN_",
- env_file=".env",
- env_file_encoding="utf-8",
- extra="ignore",
- )
+```py
+
+
+class ShotgunAccountException(UserActionableError): # noqa: N818
+ """Base class for Shotgun Account service errors.
+
+ TUI will check isinstance() of this class to show contact email UI.
+ """
-class DevelopmentSettings(BaseSettings):
- """Development and testing settings.
+class BudgetExceededException(ShotgunAccountException):
+ """Raised when Shotgun Account budget has been exceeded.
- These settings are primarily used for testing and development purposes.
+ This is a user-actionable error - they need to contact support
+ to increase their budget limit. This is a temporary exception
+ until self-service budget increases are implemented.
"""
- home: str | None = Field(
+ def __init__(
+ self,
+ current_cost: float | None = None,
+ max_budget: float | None = None,
+ message: str | None = None,
+ ):
+ """Initialize the exception.
+
+ Args:
+ current_cost: Current total spend/cost (optional)
+ max_budget: Maximum budget limit (optional)
+ message: Optional custom error message from API
+ """
+ self.current_cost = current_cost
+ self.max_budget = max_budget
```
This class is important because it defines how Shotgun Tutorial: Spec-Driven Development for Coding Agents implements the patterns covered in this chapter.
-### `src/shotgun/settings.py`
+### `src/shotgun/exceptions.py`
-The `DevelopmentSettings` class in [`src/shotgun/settings.py`](https://github.com/shotgun-sh/shotgun/blob/HEAD/src/shotgun/settings.py) handles a key part of this chapter's functionality:
+The `for` class in [`src/shotgun/exceptions.py`](https://github.com/shotgun-sh/shotgun/blob/HEAD/src/shotgun/exceptions.py) handles a key part of this chapter's functionality:
```py
+"""General exceptions for Shotgun application."""
+from shotgun.utils import get_shotgun_home
-class DevelopmentSettings(BaseSettings):
- """Development and testing settings.
+# Shotgun Account signup URL for BYOK users
+SHOTGUN_SIGNUP_URL = "https://shotgun.sh"
+SHOTGUN_CONTACT_EMAIL = "contact@shotgun.sh"
- These settings are primarily used for testing and development purposes.
+
+class UserActionableError(Exception): # noqa: N818
+ """Base for user-actionable errors that shouldn't be sent to telemetry.
+
+ These errors represent expected user conditions requiring action
+ rather than bugs that need tracking.
+
+ All subclasses should implement to_markdown() and to_plain_text() methods
+ for consistent error message formatting.
"""
- home: str | None = Field(
- default=None,
- description="Override Shotgun home directory (for testing)",
- )
- pipx_simulate: bool = Field(
- default=False,
- description="Simulate pipx installation (for testing)",
- )
- version_override: str | None = Field(
- default=None,
- description="Override current version for testing (e.g., '0.1.0')",
- )
- install_method_override: str | None = Field(
- default=None,
- description="Override installation method for testing (uvx, uv-tool, pipx, pip, venv)",
- )
-
- model_config = SettingsConfigDict(
- env_prefix="SHOTGUN_",
- env_file=".env",
- env_file_encoding="utf-8",
- extra="ignore",
- )
+ def to_markdown(self) -> str:
+ """Generate markdown-formatted error message for TUI.
+ Subclasses should override this method.
+ """
+ return f"⚠️ {str(self)}"
+
+ def to_plain_text(self) -> str:
+ """Generate plain text error message for CLI.
+
+ Subclasses should override this method.
```
This class is important because it defines how Shotgun Tutorial: Spec-Driven Development for Coding Agents implements the patterns covered in this chapter.
-### `src/shotgun/settings.py`
+### `src/shotgun/exceptions.py`
-The `IndexingSettings` class in [`src/shotgun/settings.py`](https://github.com/shotgun-sh/shotgun/blob/HEAD/src/shotgun/settings.py) handles a key part of this chapter's functionality:
+The `to` class in [`src/shotgun/exceptions.py`](https://github.com/shotgun-sh/shotgun/blob/HEAD/src/shotgun/exceptions.py) handles a key part of this chapter's functionality:
```py
+class UserActionableError(Exception): # noqa: N818
+ """Base for user-actionable errors that shouldn't be sent to telemetry.
-class IndexingSettings(BaseSettings):
- """Codebase indexing settings.
+ These errors represent expected user conditions requiring action
+ rather than bugs that need tracking.
- Controls parallel processing behavior for code indexing.
+ All subclasses should implement to_markdown() and to_plain_text() methods
+ for consistent error message formatting.
"""
- index_parallel: bool = Field(
- default=True,
- description="Enable parallel indexing (requires 4+ CPU cores)",
- )
- index_workers: int | None = Field(
- default=None,
- description="Number of worker processes for parallel indexing (default: CPU count - 1)",
- ge=1,
- )
- index_batch_size: int | None = Field(
- default=None,
- description="Files per batch for parallel indexing (default: auto-calculated)",
- ge=1,
- )
-
- model_config = SettingsConfigDict(
- env_prefix="SHOTGUN_",
- env_file=".env",
- env_file_encoding="utf-8",
- extra="ignore",
- )
-
- @field_validator("index_parallel", mode="before")
- @classmethod
-```
+ def to_markdown(self) -> str:
+ """Generate markdown-formatted error message for TUI.
-This class is important because it defines how Shotgun Tutorial: Spec-Driven Development for Coding Agents implements the patterns covered in this chapter.
-
-### `src/shotgun/settings.py`
+ Subclasses should override this method.
+ """
+ return f"⚠️ {str(self)}"
-The `OpenAICompatSettings` class in [`src/shotgun/settings.py`](https://github.com/shotgun-sh/shotgun/blob/HEAD/src/shotgun/settings.py) handles a key part of this chapter's functionality:
+ def to_plain_text(self) -> str:
+ """Generate plain text error message for CLI.
-```py
+ Subclasses should override this method.
+ """
+ return f"⚠️ {str(self)}"
-class OpenAICompatSettings(BaseSettings):
- """OpenAI-compatible endpoint settings.
+# ============================================================================
+# User Action Required Errors
+# ============================================================================
- When base_url is set, Shotgun bypasses normal provider configuration
- and uses the specified endpoint directly for all LLM requests.
-
- Environment variables:
- SHOTGUN_OPENAI_COMPAT_BASE_URL: The base URL of the OpenAI-compatible endpoint
- SHOTGUN_OPENAI_COMPAT_API_KEY: API key for authentication
- SHOTGUN_OPENAI_COMPAT_WEB_SEARCH_MODEL: Model to use for web search (optional)
- """
- base_url: str | None = Field(
- default=None,
- description="Base URL for OpenAI-compatible endpoint (e.g., https://api.example.com/v1)",
- )
- api_key: str | None = Field(
- default=None,
- description="API key for the OpenAI-compatible endpoint",
- )
- web_search_model: str | None = Field(
- default=None,
- description="Model to use for web search (defaults to openai/gpt-5.2 if not set)",
- )
-
- model_config = SettingsConfigDict(
- env_prefix="SHOTGUN_OPENAI_COMPAT_",
- env_file=".env",
- env_file_encoding="utf-8",
- extra="ignore",
+class AgentCancelledException(UserActionableError): # noqa: N818
```
This class is important because it defines how Shotgun Tutorial: Spec-Driven Development for Coding Agents implements the patterns covered in this chapter.
@@ -213,11 +209,11 @@ This class is important because it defines how Shotgun Tutorial: Spec-Driven Dev
```mermaid
flowchart TD
- A[ApiSettings]
- B[DevelopmentSettings]
- C[IndexingSettings]
- D[OpenAICompatSettings]
- E[Settings]
+ A[ContextSizeLimitExceeded]
+ B[ShotgunAccountException]
+ C[for]
+ D[to]
+ E[BudgetExceededException]
A --> B
B --> C
C --> D
diff --git a/tutorials/shotgun-tutorial/08-production-operations-observability-and-security.md b/tutorials/shotgun-tutorial/08-production-operations-observability-and-security.md
index d2239dfd..207183be 100644
--- a/tutorials/shotgun-tutorial/08-production-operations-observability-and-security.md
+++ b/tutorials/shotgun-tutorial/08-production-operations-observability-and-security.md
@@ -42,184 +42,174 @@ Production use of Shotgun requires clear controls across CI, runtime telemetry,
You now have an operating baseline for running Shotgun in team and production workflows.
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/shotgun/posthog_telemetry.py`
+### `src/shotgun/exceptions.py`
-The `and` interface in [`src/shotgun/posthog_telemetry.py`](https://github.com/shotgun-sh/shotgun/blob/HEAD/src/shotgun/posthog_telemetry.py) handles a key part of this chapter's functionality:
+The `IncompleteToolCallError` class in [`src/shotgun/exceptions.py`](https://github.com/shotgun-sh/shotgun/blob/HEAD/src/shotgun/exceptions.py) handles a key part of this chapter's functionality:
```py
-from shotgun.settings import settings
-
-# Use early logger to prevent automatic StreamHandler creation
-logger = get_early_logger(__name__)
-def _get_environment() -> str:
- """Determine environment from version string.
+class IncompleteToolCallError(UserActionableError): # noqa: N818
+ """Raised when the model generates a tool call with truncated/incomplete JSON arguments.
- Returns:
- 'development' for dev/rc/alpha/beta versions, 'production' otherwise
+ This can happen when the model's output is cut off mid-stream (e.g., due to
+ token limits, network issues, or oversized arguments).
"""
- if any(marker in __version__ for marker in ["dev", "rc", "alpha", "beta"]):
- return "development"
- return "production"
-
-
-# Global PostHog client instance
-_posthog_client: Posthog | None = None
-
-# Cache user context to avoid async calls during event tracking
-_shotgun_instance_id: str | None = None
-_user_context: dict[str, Any] = {}
-
-# Store original exception hook
-_original_excepthook: Any = None
-
-
-def _install_exception_hook() -> None:
- """Install custom exception hook to capture unhandled exceptions with full context."""
- import sys
-
-```
-
-This interface is important because it defines how Shotgun Tutorial: Spec-Driven Development for Coding Agents implements the patterns covered in this chapter.
-
-### `src/shotgun/posthog_telemetry.py`
-
-The `and` interface in [`src/shotgun/posthog_telemetry.py`](https://github.com/shotgun-sh/shotgun/blob/HEAD/src/shotgun/posthog_telemetry.py) handles a key part of this chapter's functionality:
-
-```py
-from shotgun.settings import settings
-
-# Use early logger to prevent automatic StreamHandler creation
-logger = get_early_logger(__name__)
-
-
-def _get_environment() -> str:
- """Determine environment from version string.
-
- Returns:
- 'development' for dev/rc/alpha/beta versions, 'production' otherwise
- """
- if any(marker in __version__ for marker in ["dev", "rc", "alpha", "beta"]):
- return "development"
- return "production"
-
-# Global PostHog client instance
-_posthog_client: Posthog | None = None
+ def __init__(self, tool_name: str | None = None):
+ """Initialize the exception.
-# Cache user context to avoid async calls during event tracking
-_shotgun_instance_id: str | None = None
-_user_context: dict[str, Any] = {}
-
-# Store original exception hook
-_original_excepthook: Any = None
-
-
-def _install_exception_hook() -> None:
- """Install custom exception hook to capture unhandled exceptions with full context."""
- import sys
+ Args:
+ tool_name: Optional name of the tool that had incomplete args
+ """
+ self.tool_name = tool_name
+ msg = "Tool call failed due to incomplete arguments"
+ if tool_name:
+ msg = f"Tool call '{tool_name}' failed due to incomplete arguments"
+ super().__init__(msg)
+
+ def to_markdown(self) -> str:
+ """Generate markdown-formatted error message for TUI."""
+ tool_info = f" (`{self.tool_name}`)" if self.tool_name else ""
+ return (
+ f"⚠️ **A tool call{tool_info} failed due to truncated arguments.**\n\n"
+ "The model's output was cut off before completing the tool call.\n\n"
+ "**Try again** — this is usually a transient issue."
+ )
+ def to_plain_text(self) -> str:
+ """Generate plain text error message for CLI."""
```
-This interface is important because it defines how Shotgun Tutorial: Spec-Driven Development for Coding Agents implements the patterns covered in this chapter.
+This class is important because it defines how Shotgun Tutorial: Spec-Driven Development for Coding Agents implements the patterns covered in this chapter.
-### `evals/judges/router_quality_judge.py`
+### `src/shotgun/exceptions.py`
-The `RouterQualityJudge` class in [`evals/judges/router_quality_judge.py`](https://github.com/shotgun-sh/shotgun/blob/HEAD/evals/judges/router_quality_judge.py) handles a key part of this chapter's functionality:
+The `UnknownAgentException` class in [`src/shotgun/exceptions.py`](https://github.com/shotgun-sh/shotgun/blob/HEAD/src/shotgun/exceptions.py) handles a key part of this chapter's functionality:
```py
-class RouterQualityJudge:
- """
- LLM-as-a-judge evaluator for Router agent quality.
-
- Uses structured output to evaluate Router outputs against rubrics.
- Configured with low temperature for consistent, deterministic evaluation.
- """
+class UnknownAgentException(UserActionableError): # noqa: N818
+ """Raised for unknown/unclassified agent errors."""
- def __init__(
- self,
- model_config: JudgeModelConfig | None = None,
- dimensions: list[RouterDimension] | None = None,
- ) -> None:
- """Initialize the Router quality judge.
+ def __init__(self, original_exception: Exception):
+ """Initialize the exception.
Args:
- model_config: Judge model configuration. Defaults to Claude Sonnet.
- dimensions: Dimensions to evaluate. Defaults to all dimensions.
+ original_exception: The original exception that was caught
"""
- self.model_config = model_config or JudgeModelConfig(
- provider=JudgeProviderType.ANTHROPIC,
- model_name="claude-opus-4-6",
- temperature=0.2, # Low temperature for consistency
- max_tokens=2000,
- )
+ self.original_exception = original_exception
+ super().__init__(str(original_exception))
+
+ def to_markdown(self) -> str:
+ """Generate markdown-formatted error message for TUI."""
+ log_path = get_shotgun_home() / "logs" / "shotgun.log"
+ return f"⚠️ An error occurred: {str(self.original_exception)}\n\nCheck logs at {log_path}"
- self.dimensions = dimensions or list(RouterDimension)
- self.rubrics = {dim: DEFAULT_RUBRICS[dim] for dim in self.dimensions}
+ def to_plain_text(self) -> str:
+ """Generate plain text error message for CLI."""
+ log_path = get_shotgun_home() / "logs" / "shotgun.log"
+ return f"⚠️ An error occurred: {str(self.original_exception)}\n\nCheck logs at {log_path}"
- def _create_combined_judge_agent(self) -> Agent[None, AllDimensionsScoreOutput]:
```
This class is important because it defines how Shotgun Tutorial: Spec-Driven Development for Coding Agents implements the patterns covered in this chapter.
-### `evals/reporters/console.py`
+### `src/shotgun/main.py`
-The `ConsoleReporter` class in [`evals/reporters/console.py`](https://github.com/shotgun-sh/shotgun/blob/HEAD/evals/reporters/console.py) handles a key part of this chapter's functionality:
+The `version_callback` function in [`src/shotgun/main.py`](https://github.com/shotgun-sh/shotgun/blob/HEAD/src/shotgun/main.py) handles a key part of this chapter's functionality:
```py
-class ConsoleReporter:
- """
- Formats evaluation reports for console output.
-
- Emphasizes scores and trace references for quick debugging.
- """
+def version_callback(value: bool) -> None:
+ """Show version and exit."""
+ if value:
+ from rich.console import Console
+
+ console = Console()
+ console.print(f"shotgun {__version__}")
+ raise typer.Exit()
+
+
+@app.callback(invoke_without_command=True)
+def main(
+ ctx: typer.Context,
+ version: Annotated[
+ bool,
+ typer.Option(
+ "--version",
+ "-v",
+ callback=version_callback,
+ is_eager=True,
+ help="Show version and exit",
+ ),
+ ] = False,
+ no_update_check: Annotated[
+ bool,
+ typer.Option(
+ "--no-update-check",
+ help="Disable automatic update checks",
+ ),
+ ] = False,
+```
- # ANSI color codes
- GREEN = "\033[92m"
- RED = "\033[91m"
- YELLOW = "\033[93m"
- BLUE = "\033[94m"
- BOLD = "\033[1m"
- RESET = "\033[0m"
+This function is important because it defines how Shotgun Tutorial: Spec-Driven Development for Coding Agents implements the patterns covered in this chapter.
- def __init__(self, use_color: bool = True) -> None:
- """Initialize the console reporter.
+### `src/shotgun/main.py`
- Args:
- use_color: Whether to use ANSI color codes
- """
- self.use_color = use_color and sys.stdout.isatty()
+The `main` function in [`src/shotgun/main.py`](https://github.com/shotgun-sh/shotgun/blob/HEAD/src/shotgun/main.py) handles a key part of this chapter's functionality:
- def _color(self, text: str, color: str) -> str:
- """Apply color to text if colors are enabled."""
- if self.use_color:
- return f"{color}{text}{self.RESET}"
- return text
+```py
- def _status_icon(self, passed: bool) -> str:
+@app.callback(invoke_without_command=True)
+def main(
+ ctx: typer.Context,
+ version: Annotated[
+ bool,
+ typer.Option(
+ "--version",
+ "-v",
+ callback=version_callback,
+ is_eager=True,
+ help="Show version and exit",
+ ),
+ ] = False,
+ no_update_check: Annotated[
+ bool,
+ typer.Option(
+ "--no-update-check",
+ help="Disable automatic update checks",
+ ),
+ ] = False,
+ continue_session: Annotated[
+ bool,
+ typer.Option(
+ "--continue",
+ "-c",
+ help="Continue previous TUI conversation",
+ ),
+ ] = False,
+ web: Annotated[
+ bool,
+ typer.Option(
```
-This class is important because it defines how Shotgun Tutorial: Spec-Driven Development for Coding Agents implements the patterns covered in this chapter.
+This function is important because it defines how Shotgun Tutorial: Spec-Driven Development for Coding Agents implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[and]
- B[and]
- C[RouterQualityJudge]
- D[ConsoleReporter]
- E[RouterAggregator]
+ A[IncompleteToolCallError]
+ B[UnknownAgentException]
+ C[version_callback]
+ D[main]
+ E[FeedbackKind]
A --> B
B --> C
C --> D
diff --git a/tutorials/stagewise-tutorial/01-getting-started-and-cli-bootstrap.md b/tutorials/stagewise-tutorial/01-getting-started-and-cli-bootstrap.md
index a0874620..b8dc6a42 100644
--- a/tutorials/stagewise-tutorial/01-getting-started-and-cli-bootstrap.md
+++ b/tutorials/stagewise-tutorial/01-getting-started-and-cli-bootstrap.md
@@ -50,186 +50,24 @@ You now have a working Stagewise baseline and understand the root-directory requ
Next: [Chapter 2: Proxy and Toolbar Architecture](02-proxy-and-toolbar-architecture.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `scripts/release/generate-changelog.ts`
-
-The `getReleaseNotesPath` function in [`scripts/release/generate-changelog.ts`](https://github.com/stagewise-io/stagewise/blob/HEAD/scripts/release/generate-changelog.ts) handles a key part of this chapter's functionality:
-
-```ts
- * Get the path to release notes file for a package
- */
-export async function getReleaseNotesPath(
- packageName: string,
-): Promise<string> {
- const repoRoot = await getRepoRoot();
- return path.join(repoRoot, '.release-notes', `${packageName}.md`);
-}
-
-/**
- * Read custom release notes for a package
- * Returns null if no release notes file exists
- */
-export async function readReleaseNotes(
- packageName: string,
-): Promise<string | null> {
- const notesPath = await getReleaseNotesPath(packageName);
-
- if (!existsSync(notesPath)) {
- return null;
- }
-
- const content = await readFile(notesPath, 'utf-8');
- return content.trim() || null;
-}
-
-/**
- * Delete the release notes file after it's been used
- */
-export async function deleteReleaseNotes(packageName: string): Promise<void> {
- const notesPath = await getReleaseNotesPath(packageName);
-
-```
-
-This function is important because it defines how Stagewise Tutorial: Frontend Coding Agent Workflows in Real Browser Context implements the patterns covered in this chapter.
-
-### `scripts/release/generate-changelog.ts`
-
-The `readReleaseNotes` function in [`scripts/release/generate-changelog.ts`](https://github.com/stagewise-io/stagewise/blob/HEAD/scripts/release/generate-changelog.ts) handles a key part of this chapter's functionality:
-
-```ts
- * Returns null if no release notes file exists
- */
-export async function readReleaseNotes(
- packageName: string,
-): Promise<string | null> {
- const notesPath = await getReleaseNotesPath(packageName);
-
- if (!existsSync(notesPath)) {
- return null;
- }
-
- const content = await readFile(notesPath, 'utf-8');
- return content.trim() || null;
-}
-
-/**
- * Delete the release notes file after it's been used
- */
-export async function deleteReleaseNotes(packageName: string): Promise<void> {
- const notesPath = await getReleaseNotesPath(packageName);
-
- if (existsSync(notesPath)) {
- await unlink(notesPath);
- }
-}
-
-/**
- * Group commits by type for changelog sections
- */
-interface GroupedCommits {
- features: ConventionalCommit[];
- fixes: ConventionalCommit[];
-```
-
-This function is important because it defines how Stagewise Tutorial: Frontend Coding Agent Workflows in Real Browser Context implements the patterns covered in this chapter.
-
-### `scripts/release/generate-changelog.ts`
-
-The `deleteReleaseNotes` function in [`scripts/release/generate-changelog.ts`](https://github.com/stagewise-io/stagewise/blob/HEAD/scripts/release/generate-changelog.ts) handles a key part of this chapter's functionality:
-
-```ts
- * Delete the release notes file after it's been used
- */
-export async function deleteReleaseNotes(packageName: string): Promise<void> {
- const notesPath = await getReleaseNotesPath(packageName);
-
- if (existsSync(notesPath)) {
- await unlink(notesPath);
- }
-}
-
-/**
- * Group commits by type for changelog sections
- */
-interface GroupedCommits {
- features: ConventionalCommit[];
- fixes: ConventionalCommit[];
- breaking: ConventionalCommit[];
- other: ConventionalCommit[];
-}
-
-function groupCommitsByType(commits: ConventionalCommit[]): GroupedCommits {
- return {
- features: commits.filter((c) => c.type === 'feat'),
- fixes: commits.filter((c) => c.type === 'fix'),
- breaking: commits.filter((c) => c.breaking),
- other: commits.filter(
- (c) => !['feat', 'fix'].includes(c.type) && !c.breaking,
- ),
- };
-}
-
-/**
-```
-
-This function is important because it defines how Stagewise Tutorial: Frontend Coding Agent Workflows in Real Browser Context implements the patterns covered in this chapter.
-
-### `scripts/release/generate-changelog.ts`
-
-The `groupCommitsByType` function in [`scripts/release/generate-changelog.ts`](https://github.com/stagewise-io/stagewise/blob/HEAD/scripts/release/generate-changelog.ts) handles a key part of this chapter's functionality:
-
-```ts
-}
-
-function groupCommitsByType(commits: ConventionalCommit[]): GroupedCommits {
- return {
- features: commits.filter((c) => c.type === 'feat'),
- fixes: commits.filter((c) => c.type === 'fix'),
- breaking: commits.filter((c) => c.breaking),
- other: commits.filter(
- (c) => !['feat', 'fix'].includes(c.type) && !c.breaking,
- ),
- };
-}
-
-/**
- * Generate markdown for a single commit
- */
-function formatCommit(commit: ConventionalCommit): string {
- const breaking = commit.breaking ? '**BREAKING** ' : '';
- return `* ${breaking}${commit.subject} (${commit.shortHash})`;
-}
-
-/**
- * Detect if version is a channel promotion (e.g., alpha→beta or prerelease→release)
- */
-function detectPromotion(version: string): {
- isPromotion: boolean;
- fromChannel: string | null;
- toChannel: string;
-} {
- const parsed = parseVersion(version);
-
- // Determine the target channel from the version
-```
+Use the following upstream sources to verify CLI bootstrap and getting-started implementation details while reading this chapter:
-This function is important because it defines how Stagewise Tutorial: Frontend Coding Agent Workflows in Real Browser Context implements the patterns covered in this chapter.
+- [`apps/stagewise/src/index.ts`](https://github.com/stagewise-io/stagewise/blob/HEAD/apps/stagewise/src/index.ts) — the main CLI entry point that bootstraps the Stagewise proxy server, injects the toolbar into the running frontend dev server, and launches the agent connection.
+- [`apps/stagewise/package.json`](https://github.com/stagewise-io/stagewise/blob/HEAD/apps/stagewise/package.json) — defines the `stagewise` CLI bin entry, dependencies, and the script commands used during `npx stagewise` execution.
+Suggested trace strategy:
+- trace the bootstrap sequence in the CLI entry point to see how the proxy port, target URL, and workspace root are resolved
+- check `package.json` bin fields to understand how `npx stagewise` resolves to the CLI executable
+- look at monorepo `pnpm-workspace.yaml` to understand which packages are composed during a full install
## How These Components Connect
```mermaid
-flowchart TD
- A[getReleaseNotesPath]
- B[readReleaseNotes]
- C[deleteReleaseNotes]
- D[groupCommitsByType]
- E[formatCommit]
- A --> B
- B --> C
- C --> D
- D --> E
+flowchart LR
+ A[npx stagewise] --> B[CLI entry point]
+ B --> C[Proxy server launched]
+ C --> D[Toolbar injected into browser]
+ D --> E[Agent connection established]
```
diff --git a/tutorials/stagewise-tutorial/02-proxy-and-toolbar-architecture.md b/tutorials/stagewise-tutorial/02-proxy-and-toolbar-architecture.md
index 18b91d91..b39ac41d 100644
--- a/tutorials/stagewise-tutorial/02-proxy-and-toolbar-architecture.md
+++ b/tutorials/stagewise-tutorial/02-proxy-and-toolbar-architecture.md
@@ -55,186 +55,24 @@ You now understand how Stagewise integrates without replacing your existing dev
Next: [Chapter 3: Bridge Mode and Multi-Agent Integrations](03-bridge-mode-and-multi-agent-integrations.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `scripts/release/generate-changelog.ts`
-
-The `detectPromotion` function in [`scripts/release/generate-changelog.ts`](https://github.com/stagewise-io/stagewise/blob/HEAD/scripts/release/generate-changelog.ts) handles a key part of this chapter's functionality:
-
-```ts
- * Detect if version is a channel promotion (e.g., alpha→beta or prerelease→release)
- */
-function detectPromotion(version: string): {
- isPromotion: boolean;
- fromChannel: string | null;
- toChannel: string;
-} {
- const parsed = parseVersion(version);
-
- // Determine the target channel from the version
- let toChannel: string;
- if (parsed.prerelease === 'alpha') {
- toChannel = 'alpha';
- } else if (parsed.prerelease === 'beta') {
- toChannel = 'beta';
- } else {
- toChannel = 'release';
- }
-
- // For promotions, the previous channel is indicated by the prereleaseNum being 1
- // (first of a new channel series)
- const isFirstOfChannel = parsed.prereleaseNum === 1;
-
- return {
- isPromotion: isFirstOfChannel && toChannel !== 'alpha',
- fromChannel:
- isFirstOfChannel && toChannel === 'beta'
- ? 'alpha'
- : isFirstOfChannel && toChannel === 'release'
- ? 'prerelease'
- : null,
- toChannel,
-```
+Use the following upstream sources to verify proxy and toolbar architecture details while reading this chapter:
-This function is important because it defines how Stagewise Tutorial: Frontend Coding Agent Workflows in Real Browser Context implements the patterns covered in this chapter.
-
-### `scripts/release/generate-changelog.ts`
-
-The `generateChangelogMarkdown` function in [`scripts/release/generate-changelog.ts`](https://github.com/stagewise-io/stagewise/blob/HEAD/scripts/release/generate-changelog.ts) handles a key part of this chapter's functionality:
-
-```ts
- * Generate the changelog markdown for a new version
- */
-export function generateChangelogMarkdown(
- version: string,
- commits: ConventionalCommit[],
- date: Date = new Date(),
- customNotes: string | null = null,
-): string {
- const dateStr = date.toISOString().split('T')[0];
- const { features, fixes, breaking, other } = groupCommitsByType(commits);
-
- let markdown = `## ${version} (${dateStr})\n\n`;
-
- // Add custom release notes at the top if provided
- if (customNotes) {
- markdown += `${customNotes}\n\n`;
- }
-
- // Handle case when there are no commits (channel promotion)
- if (commits.length === 0) {
- const promotion = detectPromotion(version);
- if (promotion.isPromotion && promotion.fromChannel) {
- markdown += `Promoted from ${promotion.fromChannel} to ${promotion.toChannel}.\n\n`;
- } else {
- markdown += `No changes in this release.\n\n`;
- }
- return markdown;
- }
-
- // Breaking changes section
- if (breaking.length > 0) {
- markdown += `### Breaking Changes\n\n`;
-```
-
-This function is important because it defines how Stagewise Tutorial: Frontend Coding Agent Workflows in Real Browser Context implements the patterns covered in this chapter.
-
-### `scripts/release/generate-changelog.ts`
-
-The `readExistingChangelog` function in [`scripts/release/generate-changelog.ts`](https://github.com/stagewise-io/stagewise/blob/HEAD/scripts/release/generate-changelog.ts) handles a key part of this chapter's functionality:
-
-```ts
- * Read existing changelog or return header
- */
-async function readExistingChangelog(changelogPath: string): Promise<string> {
- if (existsSync(changelogPath)) {
- return await readFile(changelogPath, 'utf-8');
- }
- return '';
-}
-
-/**
- * Prepend new changelog entry to existing changelog
- */
-export async function prependToChangelog(
- packageConfig: PackageConfig,
- newEntry: string,
-): Promise<void> {
- const repoRoot = await getRepoRoot();
- const packageDir = path.dirname(path.join(repoRoot, packageConfig.path));
- const changelogPath = path.join(packageDir, 'CHANGELOG.md');
-
- const existing = await readExistingChangelog(changelogPath);
-
- // Check if changelog has a header
- const hasHeader = existing.startsWith('# Changelog');
-
- let newContent: string;
- if (hasHeader) {
- // Insert after the header line
- const headerEnd = existing.indexOf('\n\n');
- if (headerEnd !== -1) {
- newContent =
- existing.slice(0, headerEnd + 2) +
-```
-
-This function is important because it defines how Stagewise Tutorial: Frontend Coding Agent Workflows in Real Browser Context implements the patterns covered in this chapter.
-
-### `scripts/release/generate-changelog.ts`
-
-The `prependToChangelog` function in [`scripts/release/generate-changelog.ts`](https://github.com/stagewise-io/stagewise/blob/HEAD/scripts/release/generate-changelog.ts) handles a key part of this chapter's functionality:
-
-```ts
- * Prepend new changelog entry to existing changelog
- */
-export async function prependToChangelog(
- packageConfig: PackageConfig,
- newEntry: string,
-): Promise<void> {
- const repoRoot = await getRepoRoot();
- const packageDir = path.dirname(path.join(repoRoot, packageConfig.path));
- const changelogPath = path.join(packageDir, 'CHANGELOG.md');
-
- const existing = await readExistingChangelog(changelogPath);
-
- // Check if changelog has a header
- const hasHeader = existing.startsWith('# Changelog');
-
- let newContent: string;
- if (hasHeader) {
- // Insert after the header line
- const headerEnd = existing.indexOf('\n\n');
- if (headerEnd !== -1) {
- newContent =
- existing.slice(0, headerEnd + 2) +
- newEntry +
- existing.slice(headerEnd + 2);
- } else {
- newContent = `${existing}\n\n${newEntry}`;
- }
- } else if (existing) {
- // No header, just prepend
- newContent = newEntry + existing;
- } else {
- // Empty file, create with header
-```
-
-This function is important because it defines how Stagewise Tutorial: Frontend Coding Agent Workflows in Real Browser Context implements the patterns covered in this chapter.
+- [`toolbars/stagewise-toolbar/src/`](https://github.com/stagewise-io/stagewise/blob/HEAD/toolbars/stagewise-toolbar/src/) — the main toolbar package that gets injected into the running frontend browser session, providing the UI for element selection and prompt submission.
+- [`apps/stagewise/src/proxy/`](https://github.com/stagewise-io/stagewise/blob/HEAD/apps/stagewise/src/) — the proxy server that intercepts dev server requests, injects the toolbar script into HTML responses, and routes messages between the browser toolbar and the agent.
+Suggested trace strategy:
+- browse the toolbar `src/` directory to find the component that handles DOM element selection and context capture
+- trace the proxy server entry to see how HTML injection and WebSocket message routing are implemented
+- review `apps/stagewise/src/ipc/` for the inter-process channel that connects the proxy to the Cursor/Copilot agent bridge
## How These Components Connect
```mermaid
-flowchart TD
- A[detectPromotion]
- B[generateChangelogMarkdown]
- C[readExistingChangelog]
- D[prependToChangelog]
- E[consolidatePrereleaseEntries]
- A --> B
- B --> C
- C --> D
- D --> E
-```
+flowchart LR
+ A[Dev server HTML response] --> B[Proxy injects toolbar script]
+ B --> C[Browser renders toolbar UI]
+ C --> D[User selects DOM element]
+ D --> E[Context and prompt sent to agent]
+```
\ No newline at end of file
diff --git a/tutorials/stagewise-tutorial/03-bridge-mode-and-multi-agent-integrations.md b/tutorials/stagewise-tutorial/03-bridge-mode-and-multi-agent-integrations.md
index 6996c1df..66099d74 100644
--- a/tutorials/stagewise-tutorial/03-bridge-mode-and-multi-agent-integrations.md
+++ b/tutorials/stagewise-tutorial/03-bridge-mode-and-multi-agent-integrations.md
@@ -51,184 +51,24 @@ You now know how to route Stagewise browser context into external coding-agent e
Next: [Chapter 4: Configuration and Plugin Loading](04-configuration-and-plugin-loading.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `scripts/release/generate-changelog.ts`
-
-The `escapeRegex` function in [`scripts/release/generate-changelog.ts`](https://github.com/stagewise-io/stagewise/blob/HEAD/scripts/release/generate-changelog.ts) handles a key part of this chapter's functionality:
-
-```ts
- // Regex to match prerelease versions of the same base
- const prereleasePattern = new RegExp(
- `## ${escapeRegex(baseVersion)}-(alpha|beta)\\.\\d+[^#]*`,
- 'g',
- );
-
- // Remove prerelease entries from existing changelog
- const cleanedChangelog = existing.replace(prereleasePattern, '');
-
- // Generate consolidated release entry
- const releaseEntry = generateChangelogMarkdown(
- releaseVersion,
- commits,
- new Date(),
- customNotes,
- );
-
- // Reconstruct changelog
- const hasHeader = cleanedChangelog.startsWith('# Changelog');
- let newContent: string;
-
- if (hasHeader) {
- const headerEnd = cleanedChangelog.indexOf('\n\n');
- if (headerEnd !== -1) {
- newContent =
- cleanedChangelog.slice(0, headerEnd + 2) +
- releaseEntry +
- cleanedChangelog.slice(headerEnd + 2);
- } else {
- newContent = `${cleanedChangelog}\n\n${releaseEntry}`;
- }
- } else {
-```
-
-This function is important because it defines how Stagewise Tutorial: Frontend Coding Agent Workflows in Real Browser Context implements the patterns covered in this chapter.
-
-### `scripts/release/generate-changelog.ts`
-
-The `updateChangelog` function in [`scripts/release/generate-changelog.ts`](https://github.com/stagewise-io/stagewise/blob/HEAD/scripts/release/generate-changelog.ts) handles a key part of this chapter's functionality:
-
-```ts
- * Update changelog for a new release
- */
-export async function updateChangelog(
- packageConfig: PackageConfig,
- newVersion: string,
- targetChannel: ReleaseChannel,
- commits: ConventionalCommit[],
- customNotes: string | null = null,
-): Promise<string> {
- // For stable releases, consolidate any prerelease entries
- if (targetChannel === 'release') {
- return await consolidatePrereleaseEntries(
- packageConfig,
- newVersion,
- commits,
- customNotes,
- );
- }
-
- // For prerelease, just prepend the new entry
- const entry = generateChangelogMarkdown(
- newVersion,
- commits,
- new Date(),
- customNotes,
- );
- await prependToChangelog(packageConfig, entry);
- return entry;
-}
-
-```
-
-This function is important because it defines how Stagewise Tutorial: Frontend Coding Agent Workflows in Real Browser Context implements the patterns covered in this chapter.
-
-### `scripts/release/generate-changelog.ts`
-
-The `GroupedCommits` interface in [`scripts/release/generate-changelog.ts`](https://github.com/stagewise-io/stagewise/blob/HEAD/scripts/release/generate-changelog.ts) handles a key part of this chapter's functionality:
-
-```ts
- * Group commits by type for changelog sections
- */
-interface GroupedCommits {
- features: ConventionalCommit[];
- fixes: ConventionalCommit[];
- breaking: ConventionalCommit[];
- other: ConventionalCommit[];
-}
-
-function groupCommitsByType(commits: ConventionalCommit[]): GroupedCommits {
- return {
- features: commits.filter((c) => c.type === 'feat'),
- fixes: commits.filter((c) => c.type === 'fix'),
- breaking: commits.filter((c) => c.breaking),
- other: commits.filter(
- (c) => !['feat', 'fix'].includes(c.type) && !c.breaking,
- ),
- };
-}
-
-/**
- * Generate markdown for a single commit
- */
-function formatCommit(commit: ConventionalCommit): string {
- const breaking = commit.breaking ? '**BREAKING** ' : '';
- return `* ${breaking}${commit.subject} (${commit.shortHash})`;
-}
-
-/**
- * Detect if version is a channel promotion (e.g., alpha→beta or prerelease→release)
- */
-function detectPromotion(version: string): {
-```
+Use the following upstream sources to verify bridge mode and multi-agent integration details while reading this chapter:
-This interface is important because it defines how Stagewise Tutorial: Frontend Coding Agent Workflows in Real Browser Context implements the patterns covered in this chapter.
-
-### `scripts/release/generate-changelog.ts`
-
-The `changelog` interface in [`scripts/release/generate-changelog.ts`](https://github.com/stagewise-io/stagewise/blob/HEAD/scripts/release/generate-changelog.ts) handles a key part of this chapter's functionality:
-
-```ts
-
-/**
- * Group commits by type for changelog sections
- */
-interface GroupedCommits {
- features: ConventionalCommit[];
- fixes: ConventionalCommit[];
- breaking: ConventionalCommit[];
- other: ConventionalCommit[];
-}
-
-function groupCommitsByType(commits: ConventionalCommit[]): GroupedCommits {
- return {
- features: commits.filter((c) => c.type === 'feat'),
- fixes: commits.filter((c) => c.type === 'fix'),
- breaking: commits.filter((c) => c.breaking),
- other: commits.filter(
- (c) => !['feat', 'fix'].includes(c.type) && !c.breaking,
- ),
- };
-}
-
-/**
- * Generate markdown for a single commit
- */
-function formatCommit(commit: ConventionalCommit): string {
- const breaking = commit.breaking ? '**BREAKING** ' : '';
- return `* ${breaking}${commit.subject} (${commit.shortHash})`;
-}
-
-/**
- * Detect if version is a channel promotion (e.g., alpha→beta or prerelease→release)
-```
-
-This interface is important because it defines how Stagewise Tutorial: Frontend Coding Agent Workflows in Real Browser Context implements the patterns covered in this chapter.
+- [`packages/agent-interface/src/`](https://github.com/stagewise-io/stagewise/blob/HEAD/packages/agent-interface/src/) — defines the agent interface contract used by all bridge integrations, specifying the message format and handshake protocol for connecting external coding agents.
+- [`apps/stagewise/src/agents/`](https://github.com/stagewise-io/stagewise/blob/HEAD/apps/stagewise/src/) — contains the bridge implementations for Cursor, Copilot, and other supported agents, each wrapping the agent interface contract to route toolbar prompts into the agent's input.
+Suggested trace strategy:
+- review the agent interface package to understand the `AgentMessage` type and the connection lifecycle
+- compare bridge implementations across different agents to see how Cursor vs. VS Code Copilot bridge differs
+- trace how the proxy routes a user prompt from the toolbar through the correct bridge to the target agent
## How These Components Connect
```mermaid
-flowchart TD
- A[escapeRegex]
- B[updateChangelog]
- C[GroupedCommits]
- D[changelog]
- E[parseVersion]
- A --> B
- B --> C
- C --> D
- D --> E
-```
+flowchart LR
+ A[Toolbar prompt] --> B[Proxy bridge router]
+ B --> C[Agent interface contract]
+ C --> D[Cursor or Copilot bridge]
+ D --> E[Agent receives context and prompt]
+```
\ No newline at end of file
diff --git a/tutorials/stagewise-tutorial/04-configuration-and-plugin-loading.md b/tutorials/stagewise-tutorial/04-configuration-and-plugin-loading.md
index 170fda53..733f5227 100644
--- a/tutorials/stagewise-tutorial/04-configuration-and-plugin-loading.md
+++ b/tutorials/stagewise-tutorial/04-configuration-and-plugin-loading.md
@@ -53,184 +53,24 @@ You now have a configuration model for predictable per-project Stagewise behavio
Next: [Chapter 5: Building Plugins with Plugin SDK](05-building-plugins-with-plugin-sdk.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `scripts/release/bump-version.ts`
-
-The `calculateNextVersion` function in [`scripts/release/bump-version.ts`](https://github.com/stagewise-io/stagewise/blob/HEAD/scripts/release/bump-version.ts) handles a key part of this chapter's functionality:
-
-```ts
- * - From release to prerelease: apply bump, add prerelease (1.0.0 -> 1.0.1-alpha.1)
- */
-export function calculateNextVersion(
- currentVersion: string,
- bumpType: VersionBump,
- targetChannel: ReleaseChannel,
-): string {
- const current = parseVersion(currentVersion);
-
- // Case 1: Target is a stable release
- if (targetChannel === 'release') {
- // If already a release version, apply the bump
- if (!current.prerelease) {
- return semver.inc(currentVersion, bumpType) || currentVersion;
- }
-
- // If coming from prerelease, just drop the prerelease tag
- // The base version already represents the "next" version
- return current.base;
- }
-
- // Case 2: Target is a prerelease (alpha or beta)
-
- // If current is a stable release, apply bump and start at prerelease.1
- if (!current.prerelease) {
- const bumpedBase = semver.inc(currentVersion, bumpType);
- if (!bumpedBase) {
- throw new Error(
- `Failed to bump version ${currentVersion} with ${bumpType}`,
- );
- }
- return `${bumpedBase}-${targetChannel}.1`;
-```
-
-This function is important because it defines how Stagewise Tutorial: Frontend Coding Agent Workflows in Real Browser Context implements the patterns covered in this chapter.
-
-### `scripts/release/bump-version.ts`
-
-The `getPossibleNextVersions` function in [`scripts/release/bump-version.ts`](https://github.com/stagewise-io/stagewise/blob/HEAD/scripts/release/bump-version.ts) handles a key part of this chapter's functionality:
-
-```ts
- * Get a list of possible next versions for display
- */
-export function getPossibleNextVersions(
- currentVersion: string,
- bumpType: VersionBump,
-): Record<ReleaseChannel, string> {
- return {
- alpha: calculateNextVersion(currentVersion, bumpType, 'alpha'),
- beta: calculateNextVersion(currentVersion, bumpType, 'beta'),
- release: calculateNextVersion(currentVersion, bumpType, 'release'),
- };
-}
-
-/**
- * Validate that a channel transition is allowed
- */
-export function isValidChannelTransition(
- currentChannel: ReleaseChannel | null,
- targetChannel: ReleaseChannel,
-): boolean {
- // From release to any prerelease is allowed
- if (currentChannel === null) {
- return true;
- }
-
- // To release is always allowed
- if (targetChannel === 'release') {
- return true;
- }
-
- // Same channel is allowed
- if (currentChannel === targetChannel) {
-```
-
-This function is important because it defines how Stagewise Tutorial: Frontend Coding Agent Workflows in Real Browser Context implements the patterns covered in this chapter.
-
-### `scripts/release/bump-version.ts`
-
-The `isValidChannelTransition` function in [`scripts/release/bump-version.ts`](https://github.com/stagewise-io/stagewise/blob/HEAD/scripts/release/bump-version.ts) handles a key part of this chapter's functionality:
-
-```ts
- * Validate that a channel transition is allowed
- */
-export function isValidChannelTransition(
- currentChannel: ReleaseChannel | null,
- targetChannel: ReleaseChannel,
-): boolean {
- // From release to any prerelease is allowed
- if (currentChannel === null) {
- return true;
- }
-
- // To release is always allowed
- if (targetChannel === 'release') {
- return true;
- }
-
- // Same channel is allowed
- if (currentChannel === targetChannel) {
- return true;
- }
-
- // alpha -> beta is allowed
- if (currentChannel === 'alpha' && targetChannel === 'beta') {
- return true;
- }
-
- // beta -> alpha is NOT allowed
- return false;
-}
-
-```
-
-This function is important because it defines how Stagewise Tutorial: Frontend Coding Agent Workflows in Real Browser Context implements the patterns covered in this chapter.
-
-### `scripts/release/git-utils.ts`
-
-The `getLastTag` function in [`scripts/release/git-utils.ts`](https://github.com/stagewise-io/stagewise/blob/HEAD/scripts/release/git-utils.ts) handles a key part of this chapter's functionality:
-
-```ts
- * Get the most recent tag matching a prefix
- */
-export async function getLastTag(prefix: string): Promise<string | null> {
- try {
- const { stdout } = await exec(
- `git tag --list "${prefix}*" --sort=-version:refname | head -n 1`,
- );
- const tag = stdout.trim();
- return tag || null;
- } catch {
- return null;
- }
-}
-
-/**
- * Get the most recent stable (non-prerelease) tag matching a prefix
- */
-export async function getLastStableTag(prefix: string): Promise<string | null> {
- try {
- const { stdout } = await exec(
- `git tag --list "${prefix}*" --sort=-version:refname`,
- );
- const tags = stdout.trim().split('\n').filter(Boolean);
-
- // Find the first tag that doesn't contain alpha or beta
- for (const tag of tags) {
- const version = tag.replace(prefix, '');
- if (!version.includes('-alpha') && !version.includes('-beta')) {
- return tag;
- }
- }
- return null;
-```
+Use the following upstream sources to verify configuration and plugin loading details while reading this chapter:
-This function is important because it defines how Stagewise Tutorial: Frontend Coding Agent Workflows in Real Browser Context implements the patterns covered in this chapter.
+- [`apps/stagewise/src/config.ts`](https://github.com/stagewise-io/stagewise/blob/HEAD/apps/stagewise/src/) — resolves and validates the `stagewise.json` workspace config file, loading proxy settings, plugin declarations, and agent connection parameters.
+- [`packages/stagewise-plugin-sdk/src/`](https://github.com/stagewise-io/stagewise/blob/HEAD/packages/stagewise-plugin-sdk/src/) — exports the plugin contract types and loader utilities used to discover and register plugins at startup.
+Suggested trace strategy:
+- trace config resolution to understand how `stagewise.json` fields map to runtime behavior (port, target URL, plugins array)
+- review the plugin SDK loader to see how plugin module paths are resolved and their hooks registered
+- check the startup sequence for the order in which config is read, plugins are loaded, and the proxy starts
## How These Components Connect
```mermaid
-flowchart TD
- A[calculateNextVersion]
- B[getPossibleNextVersions]
- C[isValidChannelTransition]
- D[getLastTag]
- E[getLastStableTag]
- A --> B
- B --> C
- C --> D
- D --> E
-```
+flowchart LR
+ A[stagewise.json] --> B[config.ts resolver]
+ B --> C[Plugin SDK loader]
+ C --> D[Plugin hooks registered]
+ D --> E[Proxy starts with full config]
+```
\ No newline at end of file
diff --git a/tutorials/stagewise-tutorial/05-building-plugins-with-plugin-sdk.md b/tutorials/stagewise-tutorial/05-building-plugins-with-plugin-sdk.md
index 22717e63..eece32ec 100644
--- a/tutorials/stagewise-tutorial/05-building-plugins-with-plugin-sdk.md
+++ b/tutorials/stagewise-tutorial/05-building-plugins-with-plugin-sdk.md
@@ -57,186 +57,23 @@ You now know how to create and iterate on custom Stagewise plugins.
Next: [Chapter 6: Custom Agent Integrations with Agent Interface](06-custom-agent-integrations-with-agent-interface.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `scripts/release/git-utils.ts`
-
-The `getFirstPrereleaseTagForCycle` function in [`scripts/release/git-utils.ts`](https://github.com/stagewise-io/stagewise/blob/HEAD/scripts/release/git-utils.ts) handles a key part of this chapter's functionality:
-
-```ts
- * (i.e., the first alpha/beta tag with the same base version)
- */
-export async function getFirstPrereleaseTagForCycle(
- prefix: string,
- baseVersion: string,
-): Promise<string | null> {
- try {
- const { stdout } = await exec(
- `git tag --list "${prefix}${baseVersion}-*" --sort=version:refname | head -n 1`,
- );
- const tag = stdout.trim();
- return tag || null;
- } catch {
- return null;
- }
-}
-
-/**
- * Get all commits since a given tag (or all commits if no tag)
- */
-export async function getCommitsSince(
- sinceTag: string | null,
- scope: string,
-): Promise<ConventionalCommit[]> {
- const range = sinceTag ? `${sinceTag}..HEAD` : '';
-
- try {
- // Get commits with full details
- // Format: hash|subject|body using null byte as commit separator
- // (null bytes can't appear in commit messages)
- const { stdout } = await exec(
- `git log ${range} --format="%H|%s|%b%x00" --no-merges`,
-```
-
-This function is important because it defines how Stagewise Tutorial: Frontend Coding Agent Workflows in Real Browser Context implements the patterns covered in this chapter.
-
-### `scripts/release/git-utils.ts`
-
-The `getCommitsSince` function in [`scripts/release/git-utils.ts`](https://github.com/stagewise-io/stagewise/blob/HEAD/scripts/release/git-utils.ts) handles a key part of this chapter's functionality:
-
-```ts
- * Get all commits since a given tag (or all commits if no tag)
- */
-export async function getCommitsSince(
- sinceTag: string | null,
- scope: string,
-): Promise<ConventionalCommit[]> {
- const range = sinceTag ? `${sinceTag}..HEAD` : '';
-
- try {
- // Get commits with full details
- // Format: hash|subject|body using null byte as commit separator
- // (null bytes can't appear in commit messages)
- const { stdout } = await exec(
- `git log ${range} --format="%H|%s|%b%x00" --no-merges`,
- );
-
- if (!stdout.trim()) {
- return [];
- }
-
- const commits: ConventionalCommit[] = [];
+Use the following upstream sources to verify plugin SDK implementation details while reading this chapter:
- // Split by null byte delimiter (end of each commit)
- const rawCommits = stdout.split('\0').filter((c) => c.trim());
-
- for (const rawCommit of rawCommits) {
- const parts = rawCommit.trim().split('|');
- if (parts.length < 2) continue;
-
- const hash = parts[0];
- const subject = parts[1];
- const body = parts.slice(2).join('|').trim() || null;
-```
-
-This function is important because it defines how Stagewise Tutorial: Frontend Coding Agent Workflows in Real Browser Context implements the patterns covered in this chapter.
-
-### `scripts/release/git-utils.ts`
-
-The `getRecommendedBump` function in [`scripts/release/git-utils.ts`](https://github.com/stagewise-io/stagewise/blob/HEAD/scripts/release/git-utils.ts) handles a key part of this chapter's functionality:
-
-```ts
- * Get the recommended version bump based on commits
- */
-export function getRecommendedBump(
- commits: ConventionalCommit[],
-): 'major' | 'minor' | 'patch' | null {
- if (commits.length === 0) {
- return null;
- }
-
- // Check for breaking changes first
- if (commits.some((c) => c.breaking)) {
- return 'major';
- }
-
- // Check for features
- if (commits.some((c) => c.type === 'feat')) {
- return 'minor';
- }
-
- // Check for fixes or other changes
- if (commits.some((c) => ['fix', 'perf', 'refactor'].includes(c.type))) {
- return 'patch';
- }
-
- // For other types (docs, style, test, chore), return patch as fallback
- return 'patch';
-}
-
-/**
- * Check if there are any uncommitted changes
- */
-export async function hasUncommittedChanges(): Promise<boolean> {
-```
-
-This function is important because it defines how Stagewise Tutorial: Frontend Coding Agent Workflows in Real Browser Context implements the patterns covered in this chapter.
-
-### `scripts/release/git-utils.ts`
-
-The `hasUncommittedChanges` function in [`scripts/release/git-utils.ts`](https://github.com/stagewise-io/stagewise/blob/HEAD/scripts/release/git-utils.ts) handles a key part of this chapter's functionality:
-
-```ts
- * Check if there are any uncommitted changes
- */
-export async function hasUncommittedChanges(): Promise<boolean> {
- try {
- const { stdout } = await exec('git status --porcelain');
- return stdout.trim().length > 0;
- } catch {
- return true;
- }
-}
-
-/**
- * Get the current branch name
- */
-export async function getCurrentBranch(): Promise<string> {
- const { stdout } = await exec('git rev-parse --abbrev-ref HEAD');
- return stdout.trim();
-}
-
-/**
- * Create a git tag
- */
-export async function createTag(
- tagName: string,
- message: string,
-): Promise<void> {
- await exec(`git tag -a "${tagName}" -m "${message}"`);
-}
-
-/**
- * Push a tag to remote
- */
-```
-
-This function is important because it defines how Stagewise Tutorial: Frontend Coding Agent Workflows in Real Browser Context implements the patterns covered in this chapter.
+- [`packages/stagewise-plugin-sdk/src/index.ts`](https://github.com/stagewise-io/stagewise/blob/HEAD/packages/stagewise-plugin-sdk/src/) — the main export of the plugin SDK, exposing the `definePlugin` factory, hook types, and context utilities that plugin authors use to extend toolbar behavior.
+- [`packages/stagewise-plugin-sdk/src/types.ts`](https://github.com/stagewise-io/stagewise/blob/HEAD/packages/stagewise-plugin-sdk/src/) — defines the `PluginDefinition` interface and the full lifecycle hook contract including `onContextCapture`, `onPromptSend`, and `onAgentResponse`.
+Suggested trace strategy:
+- read `definePlugin` to understand the required and optional fields a plugin must export
+- review the hook type definitions to understand what context data is available at each lifecycle stage
+- look at example plugins in `examples/` if present to see how common patterns are implemented
## How These Components Connect
```mermaid
-flowchart TD
- A[getFirstPrereleaseTagForCycle]
- B[getCommitsSince]
- C[getRecommendedBump]
- D[hasUncommittedChanges]
- E[getCurrentBranch]
- A --> B
- B --> C
- C --> D
- D --> E
-```
+flowchart LR
+ A[Plugin author uses definePlugin] --> B[Plugin exports lifecycle hooks]
+ B --> C[Plugin SDK loader registers hooks]
+ C --> D[Hooks called during toolbar and agent lifecycle]
+```
\ No newline at end of file
diff --git a/tutorials/stagewise-tutorial/06-custom-agent-integrations-with-agent-interface.md b/tutorials/stagewise-tutorial/06-custom-agent-integrations-with-agent-interface.md
index 49c962a1..8841aaa9 100644
--- a/tutorials/stagewise-tutorial/06-custom-agent-integrations-with-agent-interface.md
+++ b/tutorials/stagewise-tutorial/06-custom-agent-integrations-with-agent-interface.md
@@ -48,135 +48,23 @@ You now have an implementation map for connecting custom agents into Stagewise w
Next: [Chapter 7: Troubleshooting, Security, and Operations](07-troubleshooting-security-and-operations.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `scripts/release/git-utils.ts`
-
-The `createTag` function in [`scripts/release/git-utils.ts`](https://github.com/stagewise-io/stagewise/blob/HEAD/scripts/release/git-utils.ts) handles a key part of this chapter's functionality:
-
-```ts
- * Create a git tag
- */
-export async function createTag(
- tagName: string,
- message: string,
-): Promise<void> {
- await exec(`git tag -a "${tagName}" -m "${message}"`);
-}
-
-/**
- * Push a tag to remote
- */
-export async function pushTag(tagName: string): Promise<void> {
- await exec(`git push origin "${tagName}"`);
-}
-
-/**
- * Get the repo root directory
- */
-export async function getRepoRoot(): Promise<string> {
- const { stdout } = await exec('git rev-parse --show-toplevel');
- return stdout.trim();
-}
-
-```
-
-This function is important because it defines how Stagewise Tutorial: Frontend Coding Agent Workflows in Real Browser Context implements the patterns covered in this chapter.
-
-### `scripts/release/git-utils.ts`
-
-The `pushTag` function in [`scripts/release/git-utils.ts`](https://github.com/stagewise-io/stagewise/blob/HEAD/scripts/release/git-utils.ts) handles a key part of this chapter's functionality:
-
-```ts
- * Push a tag to remote
- */
-export async function pushTag(tagName: string): Promise<void> {
- await exec(`git push origin "${tagName}"`);
-}
-
-/**
- * Get the repo root directory
- */
-export async function getRepoRoot(): Promise<string> {
- const { stdout } = await exec('git rev-parse --show-toplevel');
- return stdout.trim();
-}
-
-```
+Use the following upstream sources to verify custom agent integration details while reading this chapter:
-This function is important because it defines how Stagewise Tutorial: Frontend Coding Agent Workflows in Real Browser Context implements the patterns covered in this chapter.
-
-### `scripts/release/git-utils.ts`
-
-The `getRepoRoot` function in [`scripts/release/git-utils.ts`](https://github.com/stagewise-io/stagewise/blob/HEAD/scripts/release/git-utils.ts) handles a key part of this chapter's functionality:
-
-```ts
- * Get the repo root directory
- */
-export async function getRepoRoot(): Promise<string> {
- const { stdout } = await exec('git rev-parse --show-toplevel');
- return stdout.trim();
-}
-
-```
-
-This function is important because it defines how Stagewise Tutorial: Frontend Coding Agent Workflows in Real Browser Context implements the patterns covered in this chapter.
-
-### `scripts/release/index.ts`
-
-The `parseCliArgs` function in [`scripts/release/index.ts`](https://github.com/stagewise-io/stagewise/blob/HEAD/scripts/release/index.ts) handles a key part of this chapter's functionality:
-
-```ts
- * Parse command line arguments
- */
-function parseCliArgs(): CLIOptions {
- const { values } = parseArgs({
- options: {
- package: { type: 'string', short: 'p' },
- channel: { type: 'string', short: 'c' },
- 'dry-run': { type: 'boolean', default: false },
- 'new-cycle': { type: 'boolean', default: false },
- since: { type: 'string', short: 's' },
- help: { type: 'boolean', short: 'h' },
- },
- });
-
- if (values.help) {
- console.log(`
-Release CLI - Version bumping and changelog generation
-
-Usage:
- pnpm tsx scripts/release/index.ts --package <name> [--channel <channel>] [--dry-run]
-
-Options:
- -p, --package <name> Package to release (${getAvailablePackageNames().join(', ')})
- -c, --channel <channel> Release channel (alpha, beta, release)
- -s, --since <ref> Git ref to start from (commit, tag, branch) for first releases
- --new-cycle Abandon current prerelease and start fresh version cycle
- --dry-run Preview changes without applying them
- -h, --help Show this help message
-
-Examples:
- pnpm tsx scripts/release/index.ts --package stagewise --channel beta
- pnpm tsx scripts/release/index.ts --package karton --channel release
-```
-
-This function is important because it defines how Stagewise Tutorial: Frontend Coding Agent Workflows in Real Browser Context implements the patterns covered in this chapter.
+- [`packages/agent-interface/src/index.ts`](https://github.com/stagewise-io/stagewise/blob/HEAD/packages/agent-interface/src/) — the root export of the agent interface package, defining the `AgentIntegration` abstract class and the `registerAgent` function used to wire a custom agent implementation into Stagewise.
+- [`packages/agent-interface/src/types.ts`](https://github.com/stagewise-io/stagewise/blob/HEAD/packages/agent-interface/src/) — contains the full type surface for agent integrations including `AgentContext`, `AgentPrompt`, and the response streaming interface.
+Suggested trace strategy:
+- read `AgentIntegration` to understand the methods a custom agent must implement (`connect`, `sendPrompt`, `disconnect`)
+- trace how `registerAgent` wires a custom implementation into the proxy bridge router
+- compare against an existing bridge (e.g., Cursor bridge) to see a reference implementation pattern
## How These Components Connect
```mermaid
-flowchart TD
- A[createTag]
- B[pushTag]
- C[getRepoRoot]
- D[parseCliArgs]
- E[getCurrentVersion]
- A --> B
- B --> C
- C --> D
- D --> E
-```
+flowchart LR
+ A[Custom agent class extends AgentIntegration] --> B[registerAgent call]
+ B --> C[Bridge router maps agent name to implementation]
+ C --> D[Toolbar prompts route to custom agent]
+```
\ No newline at end of file
diff --git a/tutorials/stagewise-tutorial/07-troubleshooting-security-and-operations.md b/tutorials/stagewise-tutorial/07-troubleshooting-security-and-operations.md
index 956bbf48..140a8ffa 100644
--- a/tutorials/stagewise-tutorial/07-troubleshooting-security-and-operations.md
+++ b/tutorials/stagewise-tutorial/07-troubleshooting-security-and-operations.md
@@ -44,186 +44,24 @@ You now have a troubleshooting and operations baseline for reliable Stagewise se
Next: [Chapter 8: Contribution Workflow and Ecosystem Evolution](08-contribution-workflow-and-ecosystem-evolution.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `scripts/release/index.ts`
-
-The `updatePackageVersion` function in [`scripts/release/index.ts`](https://github.com/stagewise-io/stagewise/blob/HEAD/scripts/release/index.ts) handles a key part of this chapter's functionality:
-
-```ts
- * Update package.json version
- */
-async function updatePackageVersion(
- packageConfig: PackageConfig,
- newVersion: string,
-): Promise<void> {
- const repoRoot = await getRepoRoot();
- const packageJsonPath = path.join(repoRoot, packageConfig.path);
- const content = await readFile(packageJsonPath, 'utf-8');
- const pkg = JSON.parse(content);
- pkg.version = newVersion;
- await writeFile(
- packageJsonPath,
- `${JSON.stringify(pkg, null, 2)}\n`,
- 'utf-8',
- );
-}
-
-/**
- * Write release artifacts for CI
- */
-async function writeReleaseArtifacts(
- version: string,
- tag: string,
- releaseNotes: string,
-): Promise<void> {
- const repoRoot = await getRepoRoot();
- await writeFile(path.join(repoRoot, '.release-version'), version, 'utf-8');
- await writeFile(path.join(repoRoot, '.release-tag'), tag, 'utf-8');
- await writeFile(
- path.join(repoRoot, '.release-notes.md'),
- releaseNotes,
-```
-
-This function is important because it defines how Stagewise Tutorial: Frontend Coding Agent Workflows in Real Browser Context implements the patterns covered in this chapter.
-
-### `scripts/release/index.ts`
-
-The `writeReleaseArtifacts` function in [`scripts/release/index.ts`](https://github.com/stagewise-io/stagewise/blob/HEAD/scripts/release/index.ts) handles a key part of this chapter's functionality:
-
-```ts
- * Write release artifacts for CI
- */
-async function writeReleaseArtifacts(
- version: string,
- tag: string,
- releaseNotes: string,
-): Promise<void> {
- const repoRoot = await getRepoRoot();
- await writeFile(path.join(repoRoot, '.release-version'), version, 'utf-8');
- await writeFile(path.join(repoRoot, '.release-tag'), tag, 'utf-8');
- await writeFile(
- path.join(repoRoot, '.release-notes.md'),
- releaseNotes,
- 'utf-8',
- );
-}
-
-/**
- * Prompt user to select a channel interactively
- */
-async function promptForChannel(
- currentVersion: string,
- bumpType: 'patch' | 'minor' | 'major',
-): Promise<ReleaseChannel> {
- const possibleVersions = getPossibleNextVersions(currentVersion, bumpType);
- const parsed = parseVersion(currentVersion);
-
- console.log('\nSelect release channel:');
-
- // Filter available channels based on current version
- const availableChannels = VALID_CHANNELS.filter((channel) =>
- isValidChannelTransition(parsed.prerelease, channel),
-```
-
-This function is important because it defines how Stagewise Tutorial: Frontend Coding Agent Workflows in Real Browser Context implements the patterns covered in this chapter.
-
-### `scripts/release/index.ts`
-
-The `promptForChannel` function in [`scripts/release/index.ts`](https://github.com/stagewise-io/stagewise/blob/HEAD/scripts/release/index.ts) handles a key part of this chapter's functionality:
-
-```ts
- * Prompt user to select a channel interactively
- */
-async function promptForChannel(
- currentVersion: string,
- bumpType: 'patch' | 'minor' | 'major',
-): Promise<ReleaseChannel> {
- const possibleVersions = getPossibleNextVersions(currentVersion, bumpType);
- const parsed = parseVersion(currentVersion);
-
- console.log('\nSelect release channel:');
-
- // Filter available channels based on current version
- const availableChannels = VALID_CHANNELS.filter((channel) =>
- isValidChannelTransition(parsed.prerelease, channel),
- );
-
- for (const [i, channel] of availableChannels.entries()) {
- const version = possibleVersions[channel];
- console.log(` ${i + 1}. ${channel} -> ${version}`);
- }
-
- const rl = readline.createInterface({
- input: process.stdin,
- output: process.stdout,
- });
-
- return new Promise((resolve) => {
- rl.question(
- `\nEnter choice (1-${availableChannels.length}): `,
- (answer) => {
- rl.close();
- const choice = Number.parseInt(answer, 10) - 1;
-```
-
-This function is important because it defines how Stagewise Tutorial: Frontend Coding Agent Workflows in Real Browser Context implements the patterns covered in this chapter.
-
-### `scripts/release/index.ts`
-
-The `confirmRelease` function in [`scripts/release/index.ts`](https://github.com/stagewise-io/stagewise/blob/HEAD/scripts/release/index.ts) handles a key part of this chapter's functionality:
-
-```ts
- * Confirm release with user
- */
-async function confirmRelease(): Promise<boolean> {
- const rl = readline.createInterface({
- input: process.stdin,
- output: process.stdout,
- });
-
- return new Promise((resolve) => {
- rl.question('\nProceed with release? (y/N): ', (answer) => {
- rl.close();
- resolve(answer.toLowerCase() === 'y');
- });
- });
-}
-
-/**
- * Main release flow
- */
-async function main(): Promise<void> {
- const options = parseCliArgs();
-
- // Get package config
- const packageConfig = getPackageConfig(options.package);
- if (!packageConfig) {
- console.error(`Error: Unknown package "${options.package}"`);
- console.error(
- `Available packages: ${getAvailablePackageNames().join(', ')}`,
- );
- process.exit(1);
- }
-
-```
-
-This function is important because it defines how Stagewise Tutorial: Frontend Coding Agent Workflows in Real Browser Context implements the patterns covered in this chapter.
+Use the following upstream sources to verify troubleshooting, security, and operations details while reading this chapter:
+
+- [`apps/stagewise/src/proxy/middleware/`](https://github.com/stagewise-io/stagewise/blob/HEAD/apps/stagewise/src/) — proxy middleware layer where security controls such as localhost-only binding, header validation, and request origin checks are implemented.
+- [`apps/stagewise/src/logger.ts`](https://github.com/stagewise-io/stagewise/blob/HEAD/apps/stagewise/src/) — the structured logger used across the proxy and agent bridge, outputting debug traces that are essential for diagnosing connection failures and plugin errors.
+Suggested trace strategy:
+- review the middleware stack to identify which security boundaries are enforced at the proxy layer vs. the agent layer
+- trace the logger output levels to understand how to increase verbosity (`--debug` flag) for incident diagnosis
+- check the error handling paths in the proxy entry point to see how startup failures are surfaced to the operator
## How These Components Connect
```mermaid
-flowchart TD
- A[updatePackageVersion]
- B[writeReleaseArtifacts]
- C[promptForChannel]
- D[confirmRelease]
- E[main]
- A --> B
- B --> C
- C --> D
- D --> E
-```
+flowchart LR
+ A[Incoming request] --> B[Security middleware: origin and binding checks]
+ B --> C[Request routed or rejected]
+ C --> D[Logger records outcome]
+ D --> E[Debug trace available for diagnosis]
+```
\ No newline at end of file
diff --git a/tutorials/stagewise-tutorial/08-contribution-workflow-and-ecosystem-evolution.md b/tutorials/stagewise-tutorial/08-contribution-workflow-and-ecosystem-evolution.md
index 44757608..baaf5c87 100644
--- a/tutorials/stagewise-tutorial/08-contribution-workflow-and-ecosystem-evolution.md
+++ b/tutorials/stagewise-tutorial/08-contribution-workflow-and-ecosystem-evolution.md
@@ -50,186 +50,24 @@ You now have an end-to-end model for adopting, extending, and contributing to St
Next: connect this flow with [VibeSDK](../vibesdk-tutorial/) and [OpenCode](../opencode-tutorial/).
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `scripts/release/types.ts`
-
-The `PackageConfig` interface in [`scripts/release/types.ts`](https://github.com/stagewise-io/stagewise/blob/HEAD/scripts/release/types.ts) handles a key part of this chapter's functionality:
-
-```ts
-export type VersionBump = 'patch' | 'minor' | 'major';
-
-export interface PackageConfig {
- /** Short name for the package (used in CLI) */
- name: string;
- /** Path to package.json relative to repo root */
- path: string;
- /** Commit scope(s) that map to this package */
- scope: string;
- /** Whether to publish to npm registry */
- publishToNpm: boolean;
- /** Whether to create GitHub release */
- createGithubRelease: boolean;
- /** Git tag prefix (e.g., "stagewise@", "@stagewise/karton@") */
- tagPrefix: string;
- /** Whether prerelease channels (alpha/beta) are enabled. Default: true */
- prereleaseEnabled?: boolean;
-}
-
-export interface ParsedVersion {
- /** Full version string (e.g., "1.0.0-alpha.1") */
- full: string;
- /** Major version number */
- major: number;
- /** Minor version number */
- minor: number;
- /** Patch version number */
- patch: number;
- /** Prerelease channel (alpha, beta) or null for release */
- prerelease: ReleaseChannel | null;
- /** Prerelease number (e.g., 1 in "alpha.1") or null */
- prereleaseNum: number | null;
-```
+Use the following upstream sources to verify contribution workflow and ecosystem evolution details while reading this chapter:
-This interface is important because it defines how Stagewise Tutorial: Frontend Coding Agent Workflows in Real Browser Context implements the patterns covered in this chapter.
-
-### `scripts/release/types.ts`
-
-The `ParsedVersion` interface in [`scripts/release/types.ts`](https://github.com/stagewise-io/stagewise/blob/HEAD/scripts/release/types.ts) handles a key part of this chapter's functionality:
-
-```ts
-}
-
-export interface ParsedVersion {
- /** Full version string (e.g., "1.0.0-alpha.1") */
- full: string;
- /** Major version number */
- major: number;
- /** Minor version number */
- minor: number;
- /** Patch version number */
- patch: number;
- /** Prerelease channel (alpha, beta) or null for release */
- prerelease: ReleaseChannel | null;
- /** Prerelease number (e.g., 1 in "alpha.1") or null */
- prereleaseNum: number | null;
- /** Base version without prerelease (e.g., "1.0.0") */
- base: string;
-}
-
-export interface ConventionalCommit {
- /** Full commit hash */
- hash: string;
- /** Short commit hash (7 chars) */
- shortHash: string;
- /** Commit type (feat, fix, etc.) */
- type: string;
- /** Commit scope */
- scope: string | null;
- /** Commit subject/description */
- subject: string;
- /** Commit body */
- body: string | null;
-```
-
-This interface is important because it defines how Stagewise Tutorial: Frontend Coding Agent Workflows in Real Browser Context implements the patterns covered in this chapter.
-
-### `scripts/release/types.ts`
-
-The `ConventionalCommit` interface in [`scripts/release/types.ts`](https://github.com/stagewise-io/stagewise/blob/HEAD/scripts/release/types.ts) handles a key part of this chapter's functionality:
-
-```ts
-}
-
-export interface ConventionalCommit {
- /** Full commit hash */
- hash: string;
- /** Short commit hash (7 chars) */
- shortHash: string;
- /** Commit type (feat, fix, etc.) */
- type: string;
- /** Commit scope */
- scope: string | null;
- /** Commit subject/description */
- subject: string;
- /** Commit body */
- body: string | null;
- /** Whether this is a breaking change */
- breaking: boolean;
- /** Breaking change description if present */
- breakingDescription: string | null;
-}
-
-export interface ChangelogEntry {
- /** Version string */
- version: string;
- /** Release date (YYYY-MM-DD) */
- date: string;
- /** Features added */
- features: ConventionalCommit[];
- /** Bug fixes */
- fixes: ConventionalCommit[];
- /** Breaking changes */
- breaking: ConventionalCommit[];
-```
-
-This interface is important because it defines how Stagewise Tutorial: Frontend Coding Agent Workflows in Real Browser Context implements the patterns covered in this chapter.
-
-### `scripts/release/types.ts`
-
-The `ChangelogEntry` interface in [`scripts/release/types.ts`](https://github.com/stagewise-io/stagewise/blob/HEAD/scripts/release/types.ts) handles a key part of this chapter's functionality:
-
-```ts
-}
-
-export interface ChangelogEntry {
- /** Version string */
- version: string;
- /** Release date (YYYY-MM-DD) */
- date: string;
- /** Features added */
- features: ConventionalCommit[];
- /** Bug fixes */
- fixes: ConventionalCommit[];
- /** Breaking changes */
- breaking: ConventionalCommit[];
- /** Other changes (refactor, perf, etc.) */
- other: ConventionalCommit[];
-}
-
-export interface ReleaseResult {
- /** The new version string */
- version: string;
- /** Git tag name */
- tag: string;
- /** Generated changelog markdown */
- changelog: string;
- /** Whether this was a dry run */
- dryRun: boolean;
-}
-
-export interface CLIOptions {
- /** Package name to release */
- package: string;
- /** Target release channel */
-```
-
-This interface is important because it defines how Stagewise Tutorial: Frontend Coding Agent Workflows in Real Browser Context implements the patterns covered in this chapter.
+- [`CONTRIBUTING.md`](https://github.com/stagewise-io/stagewise/blob/HEAD/CONTRIBUTING.md) — the official contributor guide covering branch strategy, PR requirements, commit conventions, and the review process for the Stagewise monorepo.
+- [`pnpm-workspace.yaml`](https://github.com/stagewise-io/stagewise/blob/HEAD/pnpm-workspace.yaml) — defines the monorepo workspace structure, which packages are published, and the dependency graph that contributors must keep in sync when adding new packages.
+Suggested trace strategy:
+- read the contribution guide for the commit message format and the CI checks that run on every PR
+- review `pnpm-workspace.yaml` to understand the relationship between `apps/`, `packages/`, and `toolbars/`
+- check `.github/workflows/` for the CI pipeline steps to know what tests and lint checks must pass before merge
## How These Components Connect
```mermaid
-flowchart TD
- A[PackageConfig]
- B[ParsedVersion]
- C[ConventionalCommit]
- D[ChangelogEntry]
- E[ReleaseResult]
- A --> B
- B --> C
- C --> D
- D --> E
-```
+flowchart LR
+ A[Contributor creates PR] --> B[CI runs from .github/workflows/]
+ B --> C[Lint and tests across pnpm workspace]
+ C --> D[Reviewers approve via CONTRIBUTING.md standards]
+ D --> E[Merge and release pipeline triggered]
+```
\ No newline at end of file
diff --git a/tutorials/strands-agents-tutorial/01-getting-started.md b/tutorials/strands-agents-tutorial/01-getting-started.md
index 21723292..8f5d226f 100644
--- a/tutorials/strands-agents-tutorial/01-getting-started.md
+++ b/tutorials/strands-agents-tutorial/01-getting-started.md
@@ -49,180 +49,23 @@ You now have Strands installed with a working first invocation.
Next: [Chapter 2: Agent Loop and Model-Driven Architecture](02-agent-loop-and-model-driven-architecture.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/strands/_async.py`
-
-The `run_async` function in [`src/strands/_async.py`](https://github.com/strands-agents/sdk-python/blob/HEAD/src/strands/_async.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def run_async(async_func: Callable[[], Awaitable[T]]) -> T:
- """Run an async function in a separate thread to avoid event loop conflicts.
-
- This utility handles the common pattern of running async code from sync contexts
- by using ThreadPoolExecutor to isolate the async execution.
-
- Args:
- async_func: A callable that returns an awaitable
-
- Returns:
- The result of the async function
- """
-
- async def execute_async() -> T:
- return await async_func()
-
- def execute() -> T:
- return asyncio.run(execute_async())
-
- with ThreadPoolExecutor() as executor:
- context = contextvars.copy_context()
- future = executor.submit(context.run, execute)
- return future.result()
-
-```
-
-This function is important because it defines how Strands Agents Tutorial: Model-Driven Agent Systems with Native MCP Support implements the patterns covered in this chapter.
-
-### `src/strands/interrupt.py`
-
-The `class` class in [`src/strands/interrupt.py`](https://github.com/strands-agents/sdk-python/blob/HEAD/src/strands/interrupt.py) handles a key part of this chapter's functionality:
-
-```py
-"""Human-in-the-loop interrupt system for agent workflows."""
-
-from dataclasses import asdict, dataclass, field
-from typing import TYPE_CHECKING, Any, cast
-
-if TYPE_CHECKING:
- from .types.agent import AgentInput
- from .types.interrupt import InterruptResponseContent
-
-
-@dataclass
-class Interrupt:
- """Represents an interrupt that can pause agent execution for human-in-the-loop workflows.
-
- Attributes:
- id: Unique identifier.
- name: User defined name.
- reason: User provided reason for raising the interrupt.
- response: Human response provided when resuming the agent after an interrupt.
- """
-
- id: str
- name: str
- reason: Any = None
- response: Any = None
-
- def to_dict(self) -> dict[str, Any]:
- """Serialize to dict for session management."""
- return asdict(self)
-
-
-class InterruptException(Exception):
-```
-
-This class is important because it defines how Strands Agents Tutorial: Model-Driven Agent Systems with Native MCP Support implements the patterns covered in this chapter.
-
-### `src/strands/interrupt.py`
+Use the following upstream sources to verify getting started details while reading this chapter:
-The `InterruptException` class in [`src/strands/interrupt.py`](https://github.com/strands-agents/sdk-python/blob/HEAD/src/strands/interrupt.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-class InterruptException(Exception):
- """Exception raised when human input is required."""
-
- def __init__(self, interrupt: Interrupt) -> None:
- """Set the interrupt."""
- self.interrupt = interrupt
-
-
-@dataclass
-class _InterruptState:
- """Track the state of interrupt events raised by the user.
-
- Note, interrupt state is cleared after resuming.
-
- Attributes:
- interrupts: Interrupts raised by the user.
- context: Additional context associated with an interrupt event.
- activated: True if agent is in an interrupt state, False otherwise.
- """
-
- interrupts: dict[str, Interrupt] = field(default_factory=dict)
- context: dict[str, Any] = field(default_factory=dict)
- activated: bool = False
- _version: int = field(default=0, compare=False, repr=False)
-
- def activate(self) -> None:
- """Activate the interrupt state."""
- self.activated = True
- self._version += 1
-
-```
-
-This class is important because it defines how Strands Agents Tutorial: Model-Driven Agent Systems with Native MCP Support implements the patterns covered in this chapter.
-
-### `src/strands/interrupt.py`
-
-The `class` class in [`src/strands/interrupt.py`](https://github.com/strands-agents/sdk-python/blob/HEAD/src/strands/interrupt.py) handles a key part of this chapter's functionality:
-
-```py
-"""Human-in-the-loop interrupt system for agent workflows."""
-
-from dataclasses import asdict, dataclass, field
-from typing import TYPE_CHECKING, Any, cast
-
-if TYPE_CHECKING:
- from .types.agent import AgentInput
- from .types.interrupt import InterruptResponseContent
-
-
-@dataclass
-class Interrupt:
- """Represents an interrupt that can pause agent execution for human-in-the-loop workflows.
-
- Attributes:
- id: Unique identifier.
- name: User defined name.
- reason: User provided reason for raising the interrupt.
- response: Human response provided when resuming the agent after an interrupt.
- """
-
- id: str
- name: str
- reason: Any = None
- response: Any = None
-
- def to_dict(self) -> dict[str, Any]:
- """Serialize to dict for session management."""
- return asdict(self)
-
-
-class InterruptException(Exception):
-```
-
-This class is important because it defines how Strands Agents Tutorial: Model-Driven Agent Systems with Native MCP Support implements the patterns covered in this chapter.
+- [`src/strands/agent/agent.py`](https://github.com/strands-agents/sdk-python/blob/HEAD/src/strands/agent/agent.py) — the primary `Agent` class that developers instantiate to run agent loops; this is the entry point for any Strands agent and the first class to understand when getting started.
+- [`examples/`](https://github.com/strands-agents/sdk-python/blob/HEAD/examples/) — the official examples directory with minimal working agents demonstrating tool registration, model selection, and basic invocation patterns.
+Suggested trace strategy:
+- read the `Agent.__init__` signature to understand required and optional parameters (model, tools, system_prompt)
+- trace a simple `agent("hello")` call through `agent.py` to see the full invocation path from user input to model response
+- check `examples/` for the simplest possible working example to use as a baseline for first runs
## How These Components Connect
```mermaid
-flowchart TD
- A[run_async]
- B[class]
- C[InterruptException]
- D[class]
- E[add_exception_note]
- A --> B
- B --> C
- C --> D
- D --> E
-```
+flowchart LR
+ A[agent = Agent(model, tools)] --> B[agent.py Agent class]
+ B --> C[Agent loop invoked with user input]
+ C --> D[Model response returned]
+```
\ No newline at end of file
diff --git a/tutorials/strands-agents-tutorial/02-agent-loop-and-model-driven-architecture.md b/tutorials/strands-agents-tutorial/02-agent-loop-and-model-driven-architecture.md
index 61647102..1c0adcfa 100644
--- a/tutorials/strands-agents-tutorial/02-agent-loop-and-model-driven-architecture.md
+++ b/tutorials/strands-agents-tutorial/02-agent-loop-and-model-driven-architecture.md
@@ -38,184 +38,182 @@ You now have the foundation to design Strands agents with clearer tradeoff aware
Next: [Chapter 3: Tools and MCP Integration](03-tools-and-mcp-integration.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/strands/telemetry/tracer.py`
+### `src/strands/models/llamacpp.py`
-The `get_tracer` function in [`src/strands/telemetry/tracer.py`](https://github.com/strands-agents/sdk-python/blob/HEAD/src/strands/telemetry/tracer.py) handles a key part of this chapter's functionality:
+The `consistency` interface in [`src/strands/models/llamacpp.py`](https://github.com/strands-agents/sdk-python/blob/HEAD/src/strands/models/llamacpp.py) handles a key part of this chapter's functionality:
```py
- self.service_name = __name__
- self.tracer_provider: trace_api.TracerProvider | None = None
- self.tracer_provider = trace_api.get_tracer_provider()
- self.tracer = self.tracer_provider.get_tracer(self.service_name)
- ThreadingInstrumentor().instrument()
-
- # Read OTEL_SEMCONV_STABILITY_OPT_IN environment variable
- opt_in_values = self._parse_semconv_opt_in()
- ## To-do: should not set below attributes directly, use env var instead
- self.use_latest_genai_conventions = "gen_ai_latest_experimental" in opt_in_values
- self._include_tool_definitions = "gen_ai_tool_definitions" in opt_in_values
-
- def _parse_semconv_opt_in(self) -> set[str]:
- """Parse the OTEL_SEMCONV_STABILITY_OPT_IN environment variable.
-
- Returns:
- A set of opt-in values from the environment variable.
- """
- opt_in_env = os.getenv("OTEL_SEMCONV_STABILITY_OPT_IN", "")
- return {value.strip() for value in opt_in_env.split(",")}
+ system_prompt: System prompt to provide context to the model.
+ tool_choice: Selection strategy for tool invocation. **Note: This parameter is accepted for
+ interface consistency but is currently ignored for this model provider.**
+ **kwargs: Additional keyword arguments for future extensibility.
- @property
- def is_langfuse(self) -> bool:
- """Check if Langfuse is configured as the OTLP endpoint.
+ Yields:
+ Formatted message chunks from the model.
- Returns:
- True if Langfuse is the OTLP endpoint, False otherwise.
+ Raises:
+ ContextWindowOverflowException: When the context window is exceeded.
+ ModelThrottledException: When the llama.cpp server is overloaded.
"""
- return any(
- "langfuse" in os.getenv(var, "")
- for var in ("OTEL_EXPORTER_OTLP_ENDPOINT", "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT", "LANGFUSE_BASE_URL")
- )
-```
+ warn_on_tool_choice_not_supported(tool_choice)
-This function is important because it defines how Strands Agents Tutorial: Model-Driven Agent Systems with Native MCP Support implements the patterns covered in this chapter.
+ # Track request start time for latency calculation
+ start_time = time.perf_counter()
-### `src/strands/telemetry/tracer.py`
+ try:
+ logger.debug("formatting request")
+ request = self._format_request(messages, tool_specs, system_prompt)
+ logger.debug("request=<%s>", request)
-The `serialize` function in [`src/strands/telemetry/tracer.py`](https://github.com/strands-agents/sdk-python/blob/HEAD/src/strands/telemetry/tracer.py) handles a key part of this chapter's functionality:
+ logger.debug("invoking model")
+ response = await self.client.post("/v1/chat/completions", json=request)
+ response.raise_for_status()
-```py
- "gen_ai.client.inference.operation.details",
- {
- "gen_ai.output.messages": serialize(
- [
- {
- "role": message["role"],
- "parts": self._map_content_blocks_to_otel_parts(message["content"]),
- "finish_reason": str(stop_reason),
- }
- ]
- ),
- },
- to_span_attributes=self.is_langfuse,
- )
- else:
- self._add_event(
- span,
- "gen_ai.choice",
- event_attributes={"finish_reason": str(stop_reason), "message": serialize(message["content"])},
- )
-
- span.set_attributes(attributes)
-
- def start_tool_call_span(
- self,
- tool: ToolUse,
- parent_span: Span | None = None,
- custom_trace_attributes: Mapping[str, AttributeValue] | None = None,
- **kwargs: Any,
- ) -> Span:
- """Start a new span for a tool call.
+ logger.debug("got response from model")
+ yield self._format_chunk({"chunk_type": "message_start"})
+ yield self._format_chunk({"chunk_type": "content_start", "data_type": "text"})
+ tool_calls: dict[int, list] = {}
+ usage_data = None
```
-This function is important because it defines how Strands Agents Tutorial: Model-Driven Agent Systems with Native MCP Support implements the patterns covered in this chapter.
+This interface is important because it defines how Strands Agents Tutorial: Model-Driven Agent Systems with Native MCP Support implements the patterns covered in this chapter.
-### `src/strands/telemetry/tracer.py`
+### `src/strands/models/openai_responses.py`
-The `for` interface in [`src/strands/telemetry/tracer.py`](https://github.com/strands-agents/sdk-python/blob/HEAD/src/strands/telemetry/tracer.py) handles a key part of this chapter's functionality:
+The `_ToolCallInfo` class in [`src/strands/models/openai_responses.py`](https://github.com/strands-agents/sdk-python/blob/HEAD/src/strands/models/openai_responses.py) handles a key part of this chapter's functionality:
```py
- # Handle datetime objects directly
- if isinstance(value, (datetime, date)):
- return value.isoformat()
- # Handle dictionaries
- elif isinstance(value, dict):
- return {k: self._process_value(v) for k, v in value.items()}
- # Handle lists
- elif isinstance(value, list):
- return [self._process_value(item) for item in value]
+class _ToolCallInfo(TypedDict):
+ """Internal type for tracking tool call information during streaming."""
+
+ name: str
+ arguments: str
+ call_id: str
+ item_id: str
+
- # Handle all other values
- else:
- try:
- # Test if the value is JSON serializable
- json.dumps(value)
- return value
- except (TypeError, OverflowError, ValueError):
- return "<replaced>"
+class Client(Protocol):
+ """Protocol defining the OpenAI Responses API interface for the underlying provider client."""
+
+ @property
+ # pragma: no cover
+ def responses(self) -> Any:
+ """Responses interface."""
+ ...
-class Tracer:
- """Handles OpenTelemetry tracing.
+class OpenAIResponsesModel(Model):
+ """OpenAI Responses API model provider implementation."""
- This class provides a simple interface for creating and managing traces,
- with support for sending to OTLP endpoints.
+ client: Client
+ client_args: dict[str, Any]
- When the OTEL_EXPORTER_OTLP_ENDPOINT environment variable is set, traces
- are sent to the OTLP endpoint.
+ class OpenAIResponsesConfig(TypedDict, total=False):
+ """Configuration options for OpenAI Responses API models.
- Both attributes are controlled by including "gen_ai_latest_experimental" or "gen_ai_tool_definitions",
+ Attributes:
+ model_id: Model ID (e.g., "gpt-4o").
```
-This interface is important because it defines how Strands Agents Tutorial: Model-Driven Agent Systems with Native MCP Support implements the patterns covered in this chapter.
+This class is important because it defines how Strands Agents Tutorial: Model-Driven Agent Systems with Native MCP Support implements the patterns covered in this chapter.
-### `src/strands/telemetry/tracer.py`
+### `src/strands/models/openai_responses.py`
-The `of` interface in [`src/strands/telemetry/tracer.py`](https://github.com/strands-agents/sdk-python/blob/HEAD/src/strands/telemetry/tracer.py) handles a key part of this chapter's functionality:
+The `Client` class in [`src/strands/models/openai_responses.py`](https://github.com/strands-agents/sdk-python/blob/HEAD/src/strands/models/openai_responses.py) handles a key part of this chapter's functionality:
```py
- Returns:
- JSON string representation of the object
- """
- # Process the object to handle non-serializable values
- processed_obj = self._process_value(obj)
- # Use the parent class to encode the processed object
- return super().encode(processed_obj)
-
- def _process_value(self, value: Any) -> Any:
- """Process any value, handling containers recursively.
- Args:
- value: The value to process
+class Client(Protocol):
+ """Protocol defining the OpenAI Responses API interface for the underlying provider client."""
- Returns:
- Processed value with unserializable parts replaced
+ @property
+ # pragma: no cover
+ def responses(self) -> Any:
+ """Responses interface."""
+ ...
+
+
+class OpenAIResponsesModel(Model):
+ """OpenAI Responses API model provider implementation."""
+
+ client: Client
+ client_args: dict[str, Any]
+
+ class OpenAIResponsesConfig(TypedDict, total=False):
+ """Configuration options for OpenAI Responses API models.
+
+ Attributes:
+ model_id: Model ID (e.g., "gpt-4o").
+ For a complete list of supported models, see https://platform.openai.com/docs/models.
+ params: Model parameters (e.g., max_output_tokens, temperature, etc.).
+ For a complete list of supported parameters, see
+ https://platform.openai.com/docs/api-reference/responses/create.
+ stateful: Whether to enable server-side conversation state management.
+ When True, the server stores conversation history and the client does not need to
+ send the full message history with each request. Defaults to False.
"""
- # Handle datetime objects directly
- if isinstance(value, (datetime, date)):
- return value.isoformat()
- # Handle dictionaries
- elif isinstance(value, dict):
- return {k: self._process_value(v) for k, v in value.items()}
+```
+
+This class is important because it defines how Strands Agents Tutorial: Model-Driven Agent Systems with Native MCP Support implements the patterns covered in this chapter.
+
+### `src/strands/models/openai_responses.py`
- # Handle lists
- elif isinstance(value, list):
- return [self._process_value(item) for item in value]
+The `OpenAIResponsesModel` class in [`src/strands/models/openai_responses.py`](https://github.com/strands-agents/sdk-python/blob/HEAD/src/strands/models/openai_responses.py) handles a key part of this chapter's functionality:
- # Handle all other values
- else:
+```py
+ if _openai_version < _MIN_OPENAI_VERSION:
+ raise ImportError(
+ f"OpenAIResponsesModel requires openai>={_MIN_OPENAI_VERSION} (found {_openai_version}). "
+ "Install/upgrade with: pip install -U openai. "
+ "For older SDKs, use OpenAIModel (Chat Completions)."
+ )
+except ImportError:
+ # Re-raise ImportError as-is (covers both our explicit raise above and missing openai package)
+ raise
+except Exception as e:
+ raise ImportError(
+ f"OpenAIResponsesModel requires openai>={_MIN_OPENAI_VERSION}. Install with: pip install -U openai"
+ ) from e
+
+import openai # noqa: E402 - must import after version check
+
+from ..types.citations import WebLocationDict # noqa: E402
+from ..types.content import ContentBlock, Messages, Role # noqa: E402
+from ..types.exceptions import ContextWindowOverflowException, ModelThrottledException # noqa: E402
+from ..types.streaming import StreamEvent # noqa: E402
+from ..types.tools import ToolChoice, ToolResult, ToolSpec, ToolUse # noqa: E402
+from ._validation import validate_config_keys # noqa: E402
+from .model import Model # noqa: E402
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar("T", bound=BaseModel)
+
+# Maximum file size for media content in tool results (20MB)
+_MAX_MEDIA_SIZE_BYTES = 20 * 1024 * 1024
+_MAX_MEDIA_SIZE_LABEL = "20MB"
+_DEFAULT_MIME_TYPE = "application/octet-stream"
```
-This interface is important because it defines how Strands Agents Tutorial: Model-Driven Agent Systems with Native MCP Support implements the patterns covered in this chapter.
+This class is important because it defines how Strands Agents Tutorial: Model-Driven Agent Systems with Native MCP Support implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[get_tracer]
- B[serialize]
- C[for]
- D[of]
- E[methods]
+ A[consistency]
+ B[_ToolCallInfo]
+ C[Client]
+ D[OpenAIResponsesModel]
+ E[OpenAIResponsesConfig]
A --> B
B --> C
C --> D
diff --git a/tutorials/strands-agents-tutorial/03-tools-and-mcp-integration.md b/tutorials/strands-agents-tutorial/03-tools-and-mcp-integration.md
index c8bae0ba..b36dee15 100644
--- a/tutorials/strands-agents-tutorial/03-tools-and-mcp-integration.md
+++ b/tutorials/strands-agents-tutorial/03-tools-and-mcp-integration.md
@@ -42,54 +42,93 @@ You now have practical patterns for integrating tools and MCP safely in Strands.
Next: [Chapter 4: Model Providers and Runtime Strategy](04-model-providers-and-runtime-strategy.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `src/strands/tools/decorator.py`
-The `tool` function in [`src/strands/tools/decorator.py`](https://github.com/strands-agents/sdk-python/blob/HEAD/src/strands/tools/decorator.py) handles a key part of this chapter's functionality:
+The `DecoratedFunctionTool` class in [`src/strands/tools/decorator.py`](https://github.com/strands-agents/sdk-python/blob/HEAD/src/strands/tools/decorator.py) handles a key part of this chapter's functionality:
```py
-"""Tool decorator for SDK.
-This module provides the @tool decorator that transforms Python functions into SDK Agent tools with automatic metadata
-extraction and validation.
-The @tool decorator performs several functions:
+class DecoratedFunctionTool(AgentTool, Generic[P, R]):
+ """An AgentTool that wraps a function that was decorated with @tool.
-1. Extracts function metadata (name, description, parameters) from docstrings and type hints
-2. Generates a JSON schema for input validation
-3. Handles two different calling patterns:
- - Standard function calls (func(arg1, arg2))
- - Tool use calls (agent.my_tool(param1="hello", param2=123))
-4. Provides error handling and result formatting
-5. Works with both standalone functions and class methods
+ This class adapts Python functions decorated with @tool to the AgentTool interface. It handles both direct
+ function calls and tool use invocations, maintaining the function's
+ original behavior while adding tool capabilities.
-Example:
- ```python
- from strands import Agent, tool
+ The class is generic over the function's parameter types (P) and return type (R) to maintain type safety.
+ """
- @tool
- def my_tool(param1: str, param2: int = 42) -> dict:
- '''
- Tool description - explain what it does.
+ _tool_name: str
+ _tool_spec: ToolSpec
+ _tool_func: Callable[P, R]
+ _metadata: FunctionToolMetadata
+
+ def __init__(
+ self,
+ tool_name: str,
+ tool_spec: ToolSpec,
+ tool_func: Callable[P, R],
+ metadata: FunctionToolMetadata,
+ ):
+ """Initialize the decorated function tool.
+
+ Args:
+ tool_name: The name to use for the tool (usually the function name).
+ tool_spec: The tool specification containing metadata for Agent integration.
+ tool_func: The original function being decorated.
+ metadata: The FunctionToolMetadata object with extracted function information.
+ """
+```
- #Args:
- param1: Description of first parameter.
- param2: Description of second parameter (default: 42).
+This class is important because it defines how Strands Agents Tutorial: Model-Driven Agent Systems with Native MCP Support implements the patterns covered in this chapter.
- #Returns:
- A dictionary with the results.
- '''
- result = do_something(param1, param2)
+### `src/strands/tools/decorator.py`
+
+The `adapts` class in [`src/strands/tools/decorator.py`](https://github.com/strands-agents/sdk-python/blob/HEAD/src/strands/tools/decorator.py) handles a key part of this chapter's functionality:
+
+```py
+ """An AgentTool that wraps a function that was decorated with @tool.
+
+ This class adapts Python functions decorated with @tool to the AgentTool interface. It handles both direct
+ function calls and tool use invocations, maintaining the function's
+ original behavior while adding tool capabilities.
+
+ The class is generic over the function's parameter types (P) and return type (R) to maintain type safety.
+ """
+
+ _tool_name: str
+ _tool_spec: ToolSpec
+ _tool_func: Callable[P, R]
+ _metadata: FunctionToolMetadata
+
+ def __init__(
+ self,
+ tool_name: str,
+ tool_spec: ToolSpec,
+ tool_func: Callable[P, R],
+ metadata: FunctionToolMetadata,
+ ):
+ """Initialize the decorated function tool.
+
+ Args:
+ tool_name: The name to use for the tool (usually the function name).
+ tool_spec: The tool specification containing metadata for Agent integration.
+ tool_func: The original function being decorated.
+ metadata: The FunctionToolMetadata object with extracted function information.
+ """
+ super().__init__()
+
+ self._tool_name = tool_name
```
-This function is important because it defines how Strands Agents Tutorial: Model-Driven Agent Systems with Native MCP Support implements the patterns covered in this chapter.
+This class is important because it defines how Strands Agents Tutorial: Model-Driven Agent Systems with Native MCP Support implements the patterns covered in this chapter.
### `src/strands/tools/decorator.py`
-The `tool` function in [`src/strands/tools/decorator.py`](https://github.com/strands-agents/sdk-python/blob/HEAD/src/strands/tools/decorator.py) handles a key part of this chapter's functionality:
+The `is` class in [`src/strands/tools/decorator.py`](https://github.com/strands-agents/sdk-python/blob/HEAD/src/strands/tools/decorator.py) handles a key part of this chapter's functionality:
```py
"""Tool decorator for SDK.
@@ -126,24 +165,13 @@ Example:
result = do_something(param1, param2)
```
-This function is important because it defines how Strands Agents Tutorial: Model-Driven Agent Systems with Native MCP Support implements the patterns covered in this chapter.
+This class is important because it defines how Strands Agents Tutorial: Model-Driven Agent Systems with Native MCP Support implements the patterns covered in this chapter.
### `src/strands/tools/decorator.py`
-The `tool` function in [`src/strands/tools/decorator.py`](https://github.com/strands-agents/sdk-python/blob/HEAD/src/strands/tools/decorator.py) handles a key part of this chapter's functionality:
+The `method` class in [`src/strands/tools/decorator.py`](https://github.com/strands-agents/sdk-python/blob/HEAD/src/strands/tools/decorator.py) handles a key part of this chapter's functionality:
```py
-"""Tool decorator for SDK.
-
-This module provides the @tool decorator that transforms Python functions into SDK Agent tools with automatic metadata
-extraction and validation.
-
-The @tool decorator performs several functions:
-
-1. Extracts function metadata (name, description, parameters) from docstrings and type hints
-2. Generates a JSON schema for input validation
-3. Handles two different calling patterns:
- - Standard function calls (func(arg1, arg2))
- Tool use calls (agent.my_tool(param1="hello", param2=123))
4. Provides error handling and result formatting
5. Works with both standalone functions and class methods
@@ -165,61 +193,31 @@ Example:
A dictionary with the results.
'''
result = do_something(param1, param2)
-```
+ return {
+ "status": "success",
+ "content": [{"text": f"Result: {result}"}]
+ }
-This function is important because it defines how Strands Agents Tutorial: Model-Driven Agent Systems with Native MCP Support implements the patterns covered in this chapter.
-
-### `src/strands/tools/decorator.py`
-
-The `del` interface in [`src/strands/tools/decorator.py`](https://github.com/strands-agents/sdk-python/blob/HEAD/src/strands/tools/decorator.py) handles a key part of this chapter's functionality:
-
-```py
-
-import docstring_parser
-from pydantic import BaseModel, Field, create_model
-from pydantic.fields import FieldInfo
-from pydantic_core import PydanticSerializationError
-from typing_extensions import override
-
-from ..interrupt import InterruptException
-from ..types._events import ToolInterruptEvent, ToolResultEvent, ToolStreamEvent
-from ..types.tools import AgentTool, JSONSchema, ToolContext, ToolGenerator, ToolResult, ToolSpec, ToolUse
-
-logger = logging.getLogger(__name__)
-
-
-# Type for wrapped function
-T = TypeVar("T", bound=Callable[..., Any])
-
-
-class FunctionToolMetadata:
- """Helper class to extract and manage function metadata for tool decoration.
-
- This class handles the extraction of metadata from Python functions including:
-
- - Function name and description from docstrings
- - Parameter names, types, and descriptions
- - Return type information
- - Creation of Pydantic models for input validation
-
- The extracted metadata is used to generate a tool specification that can be used by Strands Agent to understand and
- validate tool usage.
- """
+ agent = Agent(tools=[my_tool])
+ agent.tool.my_tool(param1="hello", param2=123)
+ ```
+"""
+import asyncio
```
-This interface is important because it defines how Strands Agents Tutorial: Model-Driven Agent Systems with Native MCP Support implements the patterns covered in this chapter.
+This class is important because it defines how Strands Agents Tutorial: Model-Driven Agent Systems with Native MCP Support implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[tool]
- B[tool]
- C[tool]
- D[del]
- E[class]
+ A[DecoratedFunctionTool]
+ B[adapts]
+ C[is]
+ D[method]
+ E[through]
A --> B
B --> C
C --> D
diff --git a/tutorials/strands-agents-tutorial/04-model-providers-and-runtime-strategy.md b/tutorials/strands-agents-tutorial/04-model-providers-and-runtime-strategy.md
index e5fea39b..1803dedc 100644
--- a/tutorials/strands-agents-tutorial/04-model-providers-and-runtime-strategy.md
+++ b/tutorials/strands-agents-tutorial/04-model-providers-and-runtime-strategy.md
@@ -38,184 +38,24 @@ You can now make provider decisions that align with product and operations goals
Next: [Chapter 5: Hooks, State, and Reliability Controls](05-hooks-state-and-reliability-controls.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/strands/agent/agent.py`
-
-The `_DefaultRetryStrategySentinel` class in [`src/strands/agent/agent.py`](https://github.com/strands-agents/sdk-python/blob/HEAD/src/strands/agent/agent.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-class _DefaultRetryStrategySentinel:
- """Sentinel class to distinguish between explicit None and default parameter value for retry_strategy."""
-
- pass
-
-
-_DEFAULT_CALLBACK_HANDLER = _DefaultCallbackHandlerSentinel()
-_DEFAULT_RETRY_STRATEGY = _DefaultRetryStrategySentinel()
-_DEFAULT_AGENT_NAME = "Strands Agents"
-_DEFAULT_AGENT_ID = "default"
-
-
-class Agent(AgentBase):
- """Core Agent implementation.
-
- An agent orchestrates the following workflow:
-
- 1. Receives user input
- 2. Processes the input using a language model
- 3. Decides whether to use tools to gather information or perform actions
- 4. Executes those tools and receives results
- 5. Continues reasoning with the new information
- 6. Produces a final response
- """
-
- # For backwards compatibility
- ToolCaller = _ToolCaller
-
- def __init__(
- self,
-```
-
-This class is important because it defines how Strands Agents Tutorial: Model-Driven Agent Systems with Native MCP Support implements the patterns covered in this chapter.
-
-### `src/strands/agent/agent.py`
-
-The `to` class in [`src/strands/agent/agent.py`](https://github.com/strands-agents/sdk-python/blob/HEAD/src/strands/agent/agent.py) handles a key part of this chapter's functionality:
-
-```py
-
-This module implements the core Agent class that serves as the primary entry point for interacting with foundation
-models and tools in the SDK.
-
-The Agent interface supports two complementary interaction patterns:
-
-1. Natural language for conversation: `agent("Analyze this data")`
-2. Method-style for direct tool access: `agent.tool.tool_name(param1="value")`
-"""
-
-import logging
-import threading
-import warnings
-from collections.abc import AsyncGenerator, AsyncIterator, Callable, Mapping
-from typing import (
- TYPE_CHECKING,
- Any,
- TypeVar,
- Union,
- cast,
-)
-
-from opentelemetry import trace as trace_api
-from pydantic import BaseModel
-
-from .. import _identifier
-from .._async import run_async
-from ..event_loop._retry import ModelRetryStrategy
-from ..event_loop.event_loop import INITIAL_DELAY, MAX_ATTEMPTS, MAX_DELAY, event_loop_cycle
-from ..tools._tool_helpers import generate_missing_tool_result_content
-
-if TYPE_CHECKING:
-```
-
-This class is important because it defines how Strands Agents Tutorial: Model-Driven Agent Systems with Native MCP Support implements the patterns covered in this chapter.
-
-### `src/strands/agent/agent.py`
-
-The `Agent` class in [`src/strands/agent/agent.py`](https://github.com/strands-agents/sdk-python/blob/HEAD/src/strands/agent/agent.py) handles a key part of this chapter's functionality:
-
-```py
-"""Agent Interface.
-
-This module implements the core Agent class that serves as the primary entry point for interacting with foundation
-models and tools in the SDK.
-
-The Agent interface supports two complementary interaction patterns:
-
-1. Natural language for conversation: `agent("Analyze this data")`
-2. Method-style for direct tool access: `agent.tool.tool_name(param1="value")`
-"""
-
-import logging
-import threading
-import warnings
-from collections.abc import AsyncGenerator, AsyncIterator, Callable, Mapping
-from typing import (
- TYPE_CHECKING,
- Any,
- TypeVar,
- Union,
- cast,
-)
-
-from opentelemetry import trace as trace_api
-from pydantic import BaseModel
-
-from .. import _identifier
-from .._async import run_async
-from ..event_loop._retry import ModelRetryStrategy
-from ..event_loop.event_loop import INITIAL_DELAY, MAX_ATTEMPTS, MAX_DELAY, event_loop_cycle
-```
-
-This class is important because it defines how Strands Agents Tutorial: Model-Driven Agent Systems with Native MCP Support implements the patterns covered in this chapter.
-
-### `src/strands/agent/agent.py`
-
-The `but` class in [`src/strands/agent/agent.py`](https://github.com/strands-agents/sdk-python/blob/HEAD/src/strands/agent/agent.py) handles a key part of this chapter's functionality:
-
-```py
-from ..types.content import ContentBlock, Message, Messages, SystemContentBlock
-from ..types.exceptions import ConcurrencyException, ContextWindowOverflowException
-from ..types.traces import AttributeValue
-from .agent_result import AgentResult
-from .base import AgentBase
-from .conversation_manager import (
- ConversationManager,
- SlidingWindowConversationManager,
-)
-from .state import AgentState
-
-logger = logging.getLogger(__name__)
-
-# TypeVar for generic structured output
-T = TypeVar("T", bound=BaseModel)
-
-
-# Sentinel class and object to distinguish between explicit None and default parameter value
-class _DefaultCallbackHandlerSentinel:
- """Sentinel class to distinguish between explicit None and default parameter value."""
-
- pass
-
-
-class _DefaultRetryStrategySentinel:
- """Sentinel class to distinguish between explicit None and default parameter value for retry_strategy."""
-
- pass
-
-
-_DEFAULT_CALLBACK_HANDLER = _DefaultCallbackHandlerSentinel()
-_DEFAULT_RETRY_STRATEGY = _DefaultRetryStrategySentinel()
-```
+Use the following upstream sources to verify model provider and runtime strategy details while reading this chapter:
-This class is important because it defines how Strands Agents Tutorial: Model-Driven Agent Systems with Native MCP Support implements the patterns covered in this chapter.
+- [`src/strands/models/`](https://github.com/strands-agents/sdk-python/blob/HEAD/src/strands/models/) — the model provider implementations directory; each file implements the `Model` protocol for a specific provider (Bedrock, LiteLLM, Ollama, OpenAI-compatible).
+- [`src/strands/models/bedrock.py`](https://github.com/strands-agents/sdk-python/blob/HEAD/src/strands/models/bedrock.py) — the Amazon Bedrock model provider, which is the default and most feature-complete provider implementation in the Strands SDK.
+Suggested trace strategy:
+- compare the `__init__` signatures across model providers in `src/strands/models/` to understand which parameters are provider-specific vs. universal
+- trace how a model provider handles the `stream` method to understand the interface contract all providers must satisfy
+- review `src/strands/models/litellm.py` to see how LiteLLM is used as a multi-provider gateway for non-Bedrock deployments
## How These Components Connect
```mermaid
-flowchart TD
- A[_DefaultRetryStrategySentinel]
- B[to]
- C[Agent]
- D[but]
- E[type]
- A --> B
- B --> C
- C --> D
- D --> E
-```
+flowchart LR
+ A[Agent configured with model provider] --> B[Model protocol interface]
+ B --> C[Provider-specific implementation in models/]
+ C --> D[API call to Bedrock / LiteLLM / Ollama]
+ D --> E[Token stream returned to agent loop]
+```
\ No newline at end of file
diff --git a/tutorials/strands-agents-tutorial/05-hooks-state-and-reliability-controls.md b/tutorials/strands-agents-tutorial/05-hooks-state-and-reliability-controls.md
index 9eb88eb4..a1c92d2b 100644
--- a/tutorials/strands-agents-tutorial/05-hooks-state-and-reliability-controls.md
+++ b/tutorials/strands-agents-tutorial/05-hooks-state-and-reliability-controls.md
@@ -38,184 +38,24 @@ You now have a safe pattern for applying runtime controls while preserving Stran
Next: [Chapter 6: Multi-Agent and Advanced Patterns](06-multi-agent-and-advanced-patterns.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/strands/tools/registry.py`
-
-The `and` interface in [`src/strands/tools/registry.py`](https://github.com/strands-agents/sdk-python/blob/HEAD/src/strands/tools/registry.py) handles a key part of this chapter's functionality:
-
-```py
-"""Tool registry.
-
-This module provides the central registry for all tools available to the agent, including discovery, validation, and
-invocation capabilities.
-"""
-
-import inspect
-import logging
-import os
-import sys
-import uuid
-import warnings
-from collections.abc import Iterable, Sequence
-from importlib import import_module, util
-from os.path import expanduser
-from pathlib import Path
-from typing import Any, cast
-
-from typing_extensions import TypedDict
-
-from .._async import run_async
-from ..tools.decorator import DecoratedFunctionTool
-from ..types.tools import AgentTool, ToolSpec
-from . import ToolProvider
-from .loader import load_tool_from_string, load_tools_from_module
-from .tools import _COMPOSITION_KEYWORDS, PythonAgentTool, normalize_schema, normalize_tool_spec
-
-logger = logging.getLogger(__name__)
-
-
-class ToolRegistry:
- """Central registry for all tools available to the agent.
-```
-
-This interface is important because it defines how Strands Agents Tutorial: Model-Driven Agent Systems with Native MCP Support implements the patterns covered in this chapter.
-
-### `src/strands/types/_events.py`
-
-The `TypedEvent` class in [`src/strands/types/_events.py`](https://github.com/strands-agents/sdk-python/blob/HEAD/src/strands/types/_events.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-class TypedEvent(dict):
- """Base class for all typed events in the agent system."""
-
- def __init__(self, data: dict[str, Any] | None = None) -> None:
- """Initialize the typed event with optional data.
-
- Args:
- data: Optional dictionary of event data to initialize with
- """
- super().__init__(data or {})
-
- @property
- def is_callback_event(self) -> bool:
- """True if this event should trigger the callback_handler to fire."""
- return True
-
- def as_dict(self) -> dict:
- """Convert this event to a raw dictionary for emitting purposes."""
- return {**self}
-
- def prepare(self, invocation_state: dict) -> None:
- """Prepare the event for emission by adding invocation state.
-
- This allows a subset of events to merge with the invocation_state without needing to
- pass around the invocation_state throughout the system.
- """
- ...
-
-
-class InitEventLoopEvent(TypedEvent):
-```
-
-This class is important because it defines how Strands Agents Tutorial: Model-Driven Agent Systems with Native MCP Support implements the patterns covered in this chapter.
-
-### `src/strands/types/_events.py`
-
-The `for` class in [`src/strands/types/_events.py`](https://github.com/strands-agents/sdk-python/blob/HEAD/src/strands/types/_events.py) handles a key part of this chapter's functionality:
-
-```py
-"""event system for the Strands Agents framework.
-
-This module defines the event types that are emitted during agent execution,
-providing a structured way to observe to different events of the event loop and
-agent lifecycle.
-"""
-
-from collections.abc import Sequence
-from typing import TYPE_CHECKING, Any, cast
-
-from pydantic import BaseModel
-from typing_extensions import override
-
-from ..interrupt import Interrupt
-from ..telemetry import EventLoopMetrics
-from .citations import Citation
-from .content import Message
-from .event_loop import Metrics, StopReason, Usage
-from .streaming import ContentBlockDelta, StreamEvent
-from .tools import ToolResult, ToolUse
-
-if TYPE_CHECKING:
- from ..agent import AgentResult
- from ..multiagent.base import MultiAgentResult, NodeResult
-
-
-class TypedEvent(dict):
- """Base class for all typed events in the agent system."""
-
- def __init__(self, data: dict[str, Any] | None = None) -> None:
-```
-
-This class is important because it defines how Strands Agents Tutorial: Model-Driven Agent Systems with Native MCP Support implements the patterns covered in this chapter.
-
-### `src/strands/types/_events.py`
-
-The `InitEventLoopEvent` class in [`src/strands/types/_events.py`](https://github.com/strands-agents/sdk-python/blob/HEAD/src/strands/types/_events.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-class InitEventLoopEvent(TypedEvent):
- """Event emitted at the very beginning of agent execution.
-
- This event is fired before any processing begins and provides access to the
- initial invocation state.
-
- Args:
- invocation_state: The invocation state passed into the request
- """
-
- def __init__(self) -> None:
- """Initialize the event loop initialization event."""
- super().__init__({"init_event_loop": True})
-
- @override
- def prepare(self, invocation_state: dict) -> None:
- self.update(invocation_state)
-
-
-class StartEvent(TypedEvent):
- """Event emitted at the start of each event loop cycle.
-
- !!deprecated!!
- Use StartEventLoopEvent instead.
-
- This event events the beginning of a new processing cycle within the agent's
- event loop. It's fired before model invocation and tool execution begin.
- """
-
- def __init__(self) -> None:
-```
+Use the following upstream sources to verify hooks, state, and reliability control details while reading this chapter:
-This class is important because it defines how Strands Agents Tutorial: Model-Driven Agent Systems with Native MCP Support implements the patterns covered in this chapter.
+- [`src/strands/hooks/`](https://github.com/strands-agents/sdk-python/blob/HEAD/src/strands/hooks/) — the hooks system that allows intercepting agent lifecycle events (before/after tool calls, model responses, loop iterations) for observability and control.
+- [`src/strands/session/`](https://github.com/strands-agents/sdk-python/blob/HEAD/src/strands/session/) — the session management layer that persists conversation history and agent state across invocations, essential for multi-turn reliability.
+Suggested trace strategy:
+- review the hook types in `src/strands/hooks/` to understand which lifecycle points are hookable and what context data is available
+- trace `src/strands/session/repository_session_manager.py` to see how sessions are stored and retrieved for state continuity
+- check `src/strands/agent/agent.py` for the `max_turns` and stop condition parameters that control agent reliability boundaries
## How These Components Connect
```mermaid
-flowchart TD
- A[and]
- B[TypedEvent]
- C[for]
- D[InitEventLoopEvent]
- E[StartEvent]
- A --> B
- B --> C
- C --> D
- D --> E
-```
+flowchart LR
+ A[Agent loop iteration] --> B[hooks/ lifecycle events fired]
+ B --> C[Observer callbacks for logging or control]
+ A --> D[session/ state persisted]
+ D --> E[Next invocation restores context]
+```
\ No newline at end of file
diff --git a/tutorials/strands-agents-tutorial/06-multi-agent-and-advanced-patterns.md b/tutorials/strands-agents-tutorial/06-multi-agent-and-advanced-patterns.md
index f64b8a37..fce8b1af 100644
--- a/tutorials/strands-agents-tutorial/06-multi-agent-and-advanced-patterns.md
+++ b/tutorials/strands-agents-tutorial/06-multi-agent-and-advanced-patterns.md
@@ -38,186 +38,25 @@ You now have a roadmap for scaling Strands workflows without losing architectura
Next: [Chapter 7: Deployment and Production Operations](07-deployment-and-production-operations.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/strands/types/_events.py`
-
-The `StructuredOutputEvent` class in [`src/strands/types/_events.py`](https://github.com/strands-agents/sdk-python/blob/HEAD/src/strands/types/_events.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-class StructuredOutputEvent(TypedEvent):
- """Event emitted when structured output is detected and processed."""
-
- def __init__(self, structured_output: BaseModel) -> None:
- """Initialize with the structured output result.
-
- Args:
- structured_output: The parsed structured output instance
- """
- super().__init__({"structured_output": structured_output})
-
-
-class EventLoopThrottleEvent(TypedEvent):
- """Event emitted when the event loop is throttled due to rate limiting."""
-
- def __init__(self, delay: int) -> None:
- """Initialize with the throttle delay duration.
-
- Args:
- delay: Delay in seconds before the next retry attempt
- """
- super().__init__({"event_loop_throttled_delay": delay})
-
- @override
- def prepare(self, invocation_state: dict) -> None:
- self.update(invocation_state)
-
-
-class ToolResultEvent(TypedEvent):
- """Event emitted when a tool execution completes."""
-```
-
-This class is important because it defines how Strands Agents Tutorial: Model-Driven Agent Systems with Native MCP Support implements the patterns covered in this chapter.
-
-### `src/strands/types/_events.py`
-
-The `EventLoopThrottleEvent` class in [`src/strands/types/_events.py`](https://github.com/strands-agents/sdk-python/blob/HEAD/src/strands/types/_events.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-class EventLoopThrottleEvent(TypedEvent):
- """Event emitted when the event loop is throttled due to rate limiting."""
-
- def __init__(self, delay: int) -> None:
- """Initialize with the throttle delay duration.
-
- Args:
- delay: Delay in seconds before the next retry attempt
- """
- super().__init__({"event_loop_throttled_delay": delay})
-
- @override
- def prepare(self, invocation_state: dict) -> None:
- self.update(invocation_state)
-
-
-class ToolResultEvent(TypedEvent):
- """Event emitted when a tool execution completes."""
-
- def __init__(self, tool_result: ToolResult, exception: Exception | None = None) -> None:
- """Initialize tool result event."""
- super().__init__({"type": "tool_result", "tool_result": tool_result})
- self._exception = exception
-
- @property
- def exception(self) -> Exception | None:
- """The original exception that occurred, if any.
-
- Can be used for re-raising or type-based error handling.
- """
-```
-
-This class is important because it defines how Strands Agents Tutorial: Model-Driven Agent Systems with Native MCP Support implements the patterns covered in this chapter.
-
-### `src/strands/types/_events.py`
-
-The `ToolResultEvent` class in [`src/strands/types/_events.py`](https://github.com/strands-agents/sdk-python/blob/HEAD/src/strands/types/_events.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-class ToolResultEvent(TypedEvent):
- """Event emitted when a tool execution completes."""
-
- def __init__(self, tool_result: ToolResult, exception: Exception | None = None) -> None:
- """Initialize tool result event."""
- super().__init__({"type": "tool_result", "tool_result": tool_result})
- self._exception = exception
-
- @property
- def exception(self) -> Exception | None:
- """The original exception that occurred, if any.
-
- Can be used for re-raising or type-based error handling.
- """
- return self._exception
-
- @property
- def tool_use_id(self) -> str:
- """The toolUseId associated with this result."""
- return cast(ToolResult, self.get("tool_result"))["toolUseId"]
-
- @property
- def tool_result(self) -> ToolResult:
- """Final result from the completed tool execution."""
- return cast(ToolResult, self.get("tool_result"))
-
- @property
- @override
- def is_callback_event(self) -> bool:
- return False
-```
-
-This class is important because it defines how Strands Agents Tutorial: Model-Driven Agent Systems with Native MCP Support implements the patterns covered in this chapter.
-
-### `src/strands/types/_events.py`
-
-The `ToolStreamEvent` class in [`src/strands/types/_events.py`](https://github.com/strands-agents/sdk-python/blob/HEAD/src/strands/types/_events.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-class ToolStreamEvent(TypedEvent):
- """Event emitted when a tool yields sub-events as part of tool execution."""
-
- def __init__(self, tool_use: ToolUse, tool_stream_data: Any) -> None:
- """Initialize with tool streaming data.
-
- Args:
- tool_use: The tool invocation producing the stream
- tool_stream_data: The yielded event from the tool execution
- """
- super().__init__({"type": "tool_stream", "tool_stream_event": {"tool_use": tool_use, "data": tool_stream_data}})
-
- @property
- def tool_use_id(self) -> str:
- """The toolUseId associated with this stream."""
- return cast(ToolUse, cast(dict, self.get("tool_stream_event")).get("tool_use"))["toolUseId"]
-
-
-class ToolCancelEvent(TypedEvent):
- """Event emitted when a user cancels a tool call from their BeforeToolCallEvent hook."""
-
- def __init__(self, tool_use: ToolUse, message: str) -> None:
- """Initialize with tool streaming data.
-
- Args:
- tool_use: Information about the tool being cancelled
- message: The tool cancellation message
- """
- super().__init__({"tool_cancel_event": {"tool_use": tool_use, "message": message}})
-
-```
+Use the following upstream sources to verify multi-agent and advanced pattern details while reading this chapter:
-This class is important because it defines how Strands Agents Tutorial: Model-Driven Agent Systems with Native MCP Support implements the patterns covered in this chapter.
+- [`src/strands/multiagent/`](https://github.com/strands-agents/sdk-python/blob/HEAD/src/strands/multiagent/) — the multi-agent coordination module containing swarm patterns, agent-as-tool composition, and pipeline orchestration primitives.
+- [`src/strands/multiagent/swarm.py`](https://github.com/strands-agents/sdk-python/blob/HEAD/src/strands/multiagent/swarm.py) — the swarm implementation that enables parallel agent execution with shared context and result aggregation.
+Suggested trace strategy:
+- review `src/strands/multiagent/` to understand the available coordination patterns (swarm, pipeline, agent-as-tool)
+- trace how `swarm.py` manages concurrent agent execution and merges outputs
+- check the agent-as-tool pattern to understand how one agent can be registered as a callable tool for another agent
## How These Components Connect
```mermaid
-flowchart TD
- A[StructuredOutputEvent]
- B[EventLoopThrottleEvent]
- C[ToolResultEvent]
- D[ToolStreamEvent]
- E[ToolCancelEvent]
- A --> B
- B --> C
- C --> D
+flowchart LR
+ A[Orchestrator agent] --> B[multiagent/ coordination]
+ B --> C[Swarm: parallel sub-agents]
+ B --> D[Pipeline: sequential agent chain]
+ C --> E[Aggregated result]
D --> E
-```
+```
\ No newline at end of file
diff --git a/tutorials/strands-agents-tutorial/07-deployment-and-production-operations.md b/tutorials/strands-agents-tutorial/07-deployment-and-production-operations.md
index dfea308a..2a4ae168 100644
--- a/tutorials/strands-agents-tutorial/07-deployment-and-production-operations.md
+++ b/tutorials/strands-agents-tutorial/07-deployment-and-production-operations.md
@@ -39,179 +39,25 @@ You now have a deployment and operations baseline for production Strands usage.
Next: [Chapter 8: Contribution Workflow and Ecosystem Extensions](08-contribution-workflow-and-ecosystem-extensions.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/strands/types/_events.py`
-
-The `MultiAgentNodeInterruptEvent` class in [`src/strands/types/_events.py`](https://github.com/strands-agents/sdk-python/blob/HEAD/src/strands/types/_events.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-class MultiAgentNodeInterruptEvent(TypedEvent):
- """Event emitted when a node is interrupted."""
-
- def __init__(self, node_id: str, interrupts: list[Interrupt]) -> None:
- """Set interrupt in the event payload.
-
- Args:
- node_id: Unique identifier for the node generating the event.
- interrupts: Interrupts raised by user.
- """
- super().__init__(
- {
- "type": "multiagent_node_interrupt",
- "node_id": node_id,
- "interrupts": interrupts,
- }
- )
-
- @property
- def interrupts(self) -> list[Interrupt]:
- """The interrupt instances."""
- return cast(list[Interrupt], self["interrupts"])
-
-```
-
-This class is important because it defines how Strands Agents Tutorial: Model-Driven Agent Systems with Native MCP Support implements the patterns covered in this chapter.
-
-### `src/strands/models/litellm.py`
-
-The `LiteLLMModel` class in [`src/strands/models/litellm.py`](https://github.com/strands-agents/sdk-python/blob/HEAD/src/strands/models/litellm.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-class LiteLLMModel(OpenAIModel):
- """LiteLLM model provider implementation."""
-
- class LiteLLMConfig(TypedDict, total=False):
- """Configuration options for LiteLLM models.
-
- Attributes:
- model_id: Model ID (e.g., "openai/gpt-4o", "anthropic/claude-3-sonnet").
- For a complete list of supported models, see https://docs.litellm.ai/docs/providers.
- params: Model parameters (e.g., max_tokens).
- For a complete list of supported parameters, see
- https://docs.litellm.ai/docs/completion/input#input-params-1.
- """
-
- model_id: str
- params: dict[str, Any] | None
-
- def __init__(self, client_args: dict[str, Any] | None = None, **model_config: Unpack[LiteLLMConfig]) -> None:
- """Initialize provider instance.
-
- Args:
- client_args: Arguments for the LiteLLM client.
- For a complete list of supported arguments, see
- https://github.com/BerriAI/litellm/blob/main/litellm/main.py.
- **model_config: Configuration options for the LiteLLM model.
- """
- self.client_args = client_args or {}
- validate_config_keys(model_config, self.LiteLLMConfig)
- self.config = dict(model_config)
- self._apply_proxy_prefix()
-```
-
-This class is important because it defines how Strands Agents Tutorial: Model-Driven Agent Systems with Native MCP Support implements the patterns covered in this chapter.
-
-### `src/strands/models/litellm.py`
-
-The `LiteLLMConfig` class in [`src/strands/models/litellm.py`](https://github.com/strands-agents/sdk-python/blob/HEAD/src/strands/models/litellm.py) handles a key part of this chapter's functionality:
-
-```py
- """LiteLLM model provider implementation."""
-
- class LiteLLMConfig(TypedDict, total=False):
- """Configuration options for LiteLLM models.
-
- Attributes:
- model_id: Model ID (e.g., "openai/gpt-4o", "anthropic/claude-3-sonnet").
- For a complete list of supported models, see https://docs.litellm.ai/docs/providers.
- params: Model parameters (e.g., max_tokens).
- For a complete list of supported parameters, see
- https://docs.litellm.ai/docs/completion/input#input-params-1.
- """
-
- model_id: str
- params: dict[str, Any] | None
-
- def __init__(self, client_args: dict[str, Any] | None = None, **model_config: Unpack[LiteLLMConfig]) -> None:
- """Initialize provider instance.
-
- Args:
- client_args: Arguments for the LiteLLM client.
- For a complete list of supported arguments, see
- https://github.com/BerriAI/litellm/blob/main/litellm/main.py.
- **model_config: Configuration options for the LiteLLM model.
- """
- self.client_args = client_args or {}
- validate_config_keys(model_config, self.LiteLLMConfig)
- self.config = dict(model_config)
- self._apply_proxy_prefix()
-
- logger.debug("config=<%s> | initializing", self.config)
-
-```
-
-This class is important because it defines how Strands Agents Tutorial: Model-Driven Agent Systems with Native MCP Support implements the patterns covered in this chapter.
-
-### `src/strands/models/sagemaker.py`
-
-The `from` class in [`src/strands/models/sagemaker.py`](https://github.com/strands-agents/sdk-python/blob/HEAD/src/strands/models/sagemaker.py) handles a key part of this chapter's functionality:
-
-```py
-import logging
-import os
-from collections.abc import AsyncGenerator
-from dataclasses import dataclass
-from typing import Any, Literal, TypedDict, TypeVar
-
-import boto3
-from botocore.config import Config as BotocoreConfig
-from mypy_boto3_sagemaker_runtime import SageMakerRuntimeClient
-from pydantic import BaseModel
-from typing_extensions import Unpack, override
-
-from ..types.content import ContentBlock, Messages
-from ..types.streaming import StreamEvent
-from ..types.tools import ToolChoice, ToolResult, ToolSpec
-from ._validation import validate_config_keys, warn_on_tool_choice_not_supported
-from .openai import OpenAIModel
-
-T = TypeVar("T", bound=BaseModel)
-
-logger = logging.getLogger(__name__)
-
-
-@dataclass
-class UsageMetadata:
- """Usage metadata for the model.
-
- Attributes:
- total_tokens: Total number of tokens used in the request
- completion_tokens: Number of tokens used in the completion
- prompt_tokens: Number of tokens used in the prompt
- prompt_tokens_details: Additional information about the prompt tokens (optional)
-```
+Use the following upstream sources to verify deployment and production operations details while reading this chapter:
-This class is important because it defines how Strands Agents Tutorial: Model-Driven Agent Systems with Native MCP Support implements the patterns covered in this chapter.
+- [`src/strands/telemetry/`](https://github.com/strands-agents/sdk-python/blob/HEAD/src/strands/telemetry/) — the observability module providing OpenTelemetry tracing and metrics export for production monitoring of agent invocations, tool calls, and model latency.
+- [`src/strands/telemetry/metrics.py`](https://github.com/strands-agents/sdk-python/blob/HEAD/src/strands/telemetry/metrics.py) — the metrics collection implementation that records token counts, latency, and tool call frequency as OTEL metrics for dashboarding and alerting.
+Suggested trace strategy:
+- review `src/strands/telemetry/tracer.py` to see how OpenTelemetry spans are created around agent invocations and tool calls
+- trace `metrics.py` to understand which metrics are emitted by default and how to extend with custom metrics
+- check environment variable documentation for `OTEL_EXPORTER_OTLP_ENDPOINT` and related settings that control telemetry export in production
## How These Components Connect
```mermaid
-flowchart TD
- A[MultiAgentNodeInterruptEvent]
- B[LiteLLMModel]
- C[LiteLLMConfig]
- D[from]
- E[class]
- A --> B
- B --> C
- C --> D
- D --> E
-```
+flowchart LR
+ A[Agent invocation in production] --> B[telemetry/ OTEL tracing]
+ B --> C[Spans sent to OTLP endpoint]
+ C --> D[Dashboards and alerts]
+ B --> E[metrics.py token and latency counts]
+ E --> D
+```
\ No newline at end of file
diff --git a/tutorials/strands-agents-tutorial/08-contribution-workflow-and-ecosystem-extensions.md b/tutorials/strands-agents-tutorial/08-contribution-workflow-and-ecosystem-extensions.md
index cb3a36f5..60f86c8e 100644
--- a/tutorials/strands-agents-tutorial/08-contribution-workflow-and-ecosystem-extensions.md
+++ b/tutorials/strands-agents-tutorial/08-contribution-workflow-and-ecosystem-extensions.md
@@ -39,184 +39,182 @@ You now have a full Strands track from first agent to ecosystem-level contributi
Next tutorial: [ADK Python Tutorial](../adk-python-tutorial/)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/strands/models/gemini.py`
+### `src/strands/telemetry/metrics.py`
-The `for` interface in [`src/strands/models/gemini.py`](https://github.com/strands-agents/sdk-python/blob/HEAD/src/strands/models/gemini.py) handles a key part of this chapter's functionality:
+The `class` class in [`src/strands/telemetry/metrics.py`](https://github.com/strands-agents/sdk-python/blob/HEAD/src/strands/telemetry/metrics.py) handles a key part of this chapter's functionality:
```py
+import uuid
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+import opentelemetry.metrics as metrics_api
+from opentelemetry.metrics import Counter, Histogram, Meter
+
+from ..telemetry import metrics_constants as constants
+from ..types.content import Message
+from ..types.event_loop import Metrics, Usage
+from ..types.tools import ToolUse
+
+logger = logging.getLogger(__name__)
- class GeminiConfig(TypedDict, total=False):
- """Configuration options for Gemini models.
-
- Attributes:
- model_id: Gemini model ID (e.g., "gemini-2.5-flash").
- For a complete list of supported models, see
- https://ai.google.dev/gemini-api/docs/models
- params: Additional model parameters (e.g., temperature).
- For a complete list of supported parameters, see
- https://ai.google.dev/api/generate-content#generationconfig.
- gemini_tools: Gemini-specific tools that are not FunctionDeclarations
- (e.g., GoogleSearch, CodeExecution, ComputerUse, UrlContext, FileSearch).
- Use the standard tools interface for function calling tools.
- For a complete list of supported tools, see
- https://ai.google.dev/api/caching#Tool
- """
-
- model_id: Required[str]
- params: dict[str, Any]
- gemini_tools: list[genai.types.Tool]
+
+class Trace:
+ """A trace representing a single operation or step in the execution flow."""
def __init__(
self,
- *,
- client: genai.Client | None = None,
- client_args: dict[str, Any] | None = None,
- **model_config: Unpack[GeminiConfig],
+ name: str,
+ parent_id: str | None = None,
+ start_time: float | None = None,
+ raw_name: str | None = None,
+ metadata: dict[str, Any] | None = None,
+ message: Message | None = None,
) -> None:
- """Initialize provider instance.
+ """Initialize a new trace.
Args:
+ name: Human-readable name of the operation being traced.
```
-This interface is important because it defines how Strands Agents Tutorial: Model-Driven Agent Systems with Native MCP Support implements the patterns covered in this chapter.
+This class is important because it defines how Strands Agents Tutorial: Model-Driven Agent Systems with Native MCP Support implements the patterns covered in this chapter.
-### `src/strands/models/mistral.py`
+### `src/strands/telemetry/metrics.py`
-The `MistralModel` class in [`src/strands/models/mistral.py`](https://github.com/strands-agents/sdk-python/blob/HEAD/src/strands/models/mistral.py) handles a key part of this chapter's functionality:
+The `class` class in [`src/strands/telemetry/metrics.py`](https://github.com/strands-agents/sdk-python/blob/HEAD/src/strands/telemetry/metrics.py) handles a key part of this chapter's functionality:
```py
+import uuid
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+from typing import Any, Optional
+import opentelemetry.metrics as metrics_api
+from opentelemetry.metrics import Counter, Histogram, Meter
-class MistralModel(Model):
- """Mistral API model provider implementation.
-
- The implementation handles Mistral-specific features such as:
+from ..telemetry import metrics_constants as constants
+from ..types.content import Message
+from ..types.event_loop import Metrics, Usage
+from ..types.tools import ToolUse
- - Chat and text completions
- - Streaming responses
- - Tool/function calling
- - System prompts
- """
+logger = logging.getLogger(__name__)
- class MistralConfig(TypedDict, total=False):
- """Configuration parameters for Mistral models.
- Attributes:
- model_id: Mistral model ID (e.g., "mistral-large-latest", "mistral-medium-latest").
- max_tokens: Maximum number of tokens to generate in the response.
- temperature: Controls randomness in generation (0.0 to 1.0).
- top_p: Controls diversity via nucleus sampling.
- stream: Whether to enable streaming responses.
- """
-
- model_id: str
- max_tokens: int | None
- temperature: float | None
- top_p: float | None
- stream: bool | None
+class Trace:
+ """A trace representing a single operation or step in the execution flow."""
def __init__(
self,
+ name: str,
+ parent_id: str | None = None,
+ start_time: float | None = None,
+ raw_name: str | None = None,
+ metadata: dict[str, Any] | None = None,
+ message: Message | None = None,
+ ) -> None:
+ """Initialize a new trace.
+
+ Args:
+ name: Human-readable name of the operation being traced.
```
This class is important because it defines how Strands Agents Tutorial: Model-Driven Agent Systems with Native MCP Support implements the patterns covered in this chapter.
-### `src/strands/models/mistral.py`
+### `src/strands/telemetry/metrics.py`
-The `MistralConfig` class in [`src/strands/models/mistral.py`](https://github.com/strands-agents/sdk-python/blob/HEAD/src/strands/models/mistral.py) handles a key part of this chapter's functionality:
+The `class` class in [`src/strands/telemetry/metrics.py`](https://github.com/strands-agents/sdk-python/blob/HEAD/src/strands/telemetry/metrics.py) handles a key part of this chapter's functionality:
```py
- """
+import uuid
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+import opentelemetry.metrics as metrics_api
+from opentelemetry.metrics import Counter, Histogram, Meter
+
+from ..telemetry import metrics_constants as constants
+from ..types.content import Message
+from ..types.event_loop import Metrics, Usage
+from ..types.tools import ToolUse
- class MistralConfig(TypedDict, total=False):
- """Configuration parameters for Mistral models.
+logger = logging.getLogger(__name__)
- Attributes:
- model_id: Mistral model ID (e.g., "mistral-large-latest", "mistral-medium-latest").
- max_tokens: Maximum number of tokens to generate in the response.
- temperature: Controls randomness in generation (0.0 to 1.0).
- top_p: Controls diversity via nucleus sampling.
- stream: Whether to enable streaming responses.
- """
- model_id: str
- max_tokens: int | None
- temperature: float | None
- top_p: float | None
- stream: bool | None
+class Trace:
+ """A trace representing a single operation or step in the execution flow."""
def __init__(
self,
- api_key: str | None = None,
- *,
- client_args: dict[str, Any] | None = None,
- **model_config: Unpack[MistralConfig],
+ name: str,
+ parent_id: str | None = None,
+ start_time: float | None = None,
+ raw_name: str | None = None,
+ metadata: dict[str, Any] | None = None,
+ message: Message | None = None,
) -> None:
- """Initialize provider instance.
+ """Initialize a new trace.
Args:
- api_key: Mistral API key. If not provided, will use MISTRAL_API_KEY env var.
- client_args: Additional arguments for the Mistral client.
- **model_config: Configuration options for the Mistral model.
+ name: Human-readable name of the operation being traced.
```
This class is important because it defines how Strands Agents Tutorial: Model-Driven Agent Systems with Native MCP Support implements the patterns covered in this chapter.
-### `src/strands/models/mistral.py`
+### `src/strands/telemetry/metrics.py`
-The `consistency` interface in [`src/strands/models/mistral.py`](https://github.com/strands-agents/sdk-python/blob/HEAD/src/strands/models/mistral.py) handles a key part of this chapter's functionality:
+The `class` class in [`src/strands/telemetry/metrics.py`](https://github.com/strands-agents/sdk-python/blob/HEAD/src/strands/telemetry/metrics.py) handles a key part of this chapter's functionality:
```py
- system_prompt: System prompt to provide context to the model.
- tool_choice: Selection strategy for tool invocation. **Note: This parameter is accepted for
- interface consistency but is currently ignored for this model provider.**
- **kwargs: Additional keyword arguments for future extensibility.
-
- Yields:
- Formatted message chunks from the model.
-
- Raises:
- ModelThrottledException: When the model service is throttling requests.
- """
- warn_on_tool_choice_not_supported(tool_choice)
-
- logger.debug("formatting request")
- request = self.format_request(messages, tool_specs, system_prompt)
- logger.debug("request=<%s>", request)
-
- logger.debug("invoking model")
- try:
- logger.debug("got response from model")
- if not self.config.get("stream", True):
- # Use non-streaming API
- async with mistralai.Mistral(**self.client_args) as client:
- response = await client.chat.complete_async(**request)
- for event in self._handle_non_streaming_response(response):
- yield self.format_chunk(event)
-
- return
-
- # Use the streaming API
- async with mistralai.Mistral(**self.client_args) as client:
- stream_response = await client.chat.stream_async(**request)
+import uuid
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+import opentelemetry.metrics as metrics_api
+from opentelemetry.metrics import Counter, Histogram, Meter
+
+from ..telemetry import metrics_constants as constants
+from ..types.content import Message
+from ..types.event_loop import Metrics, Usage
+from ..types.tools import ToolUse
+
+logger = logging.getLogger(__name__)
+
+
+class Trace:
+ """A trace representing a single operation or step in the execution flow."""
+
+ def __init__(
+ self,
+ name: str,
+ parent_id: str | None = None,
+ start_time: float | None = None,
+ raw_name: str | None = None,
+ metadata: dict[str, Any] | None = None,
+ message: Message | None = None,
+ ) -> None:
+ """Initialize a new trace.
+
+ Args:
+ name: Human-readable name of the operation being traced.
```
-This interface is important because it defines how Strands Agents Tutorial: Model-Driven Agent Systems with Native MCP Support implements the patterns covered in this chapter.
+This class is important because it defines how Strands Agents Tutorial: Model-Driven Agent Systems with Native MCP Support implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[for]
- B[MistralModel]
- C[MistralConfig]
- D[consistency]
- E[event_loop_cycle]
+ A[class]
+ B[class]
+ C[class]
+ D[class]
+ E[MetricsClient]
A --> B
B --> C
C --> D
diff --git a/tutorials/superagi-tutorial/03-tool-integration.md b/tutorials/superagi-tutorial/03-tool-integration.md
index 1323348f..4e448e74 100644
--- a/tutorials/superagi-tutorial/03-tool-integration.md
+++ b/tutorials/superagi-tutorial/03-tool-integration.md
@@ -699,6 +699,17 @@ Under the hood, `Chapter 3: Tool Integration` usually follows a repeatable contr
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## Architecture Flow
+
+```mermaid
+flowchart LR
+ A[Agent task] --> B[Tool selector]
+ B --> C[Tool executor]
+ C --> D[External API or service]
+ D --> E[Tool result returned to agent]
+ E --> B
+```
+
## Source Walkthrough
Use the following upstream sources to verify implementation details while reading this chapter:
diff --git a/tutorials/superagi-tutorial/04-memory-learning.md b/tutorials/superagi-tutorial/04-memory-learning.md
index a5d995e6..b50caea5 100644
--- a/tutorials/superagi-tutorial/04-memory-learning.md
+++ b/tutorials/superagi-tutorial/04-memory-learning.md
@@ -703,6 +703,17 @@ Under the hood, `Chapter 4: Memory & Learning` usually follows a repeatable cont
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## Architecture Flow
+
+```mermaid
+flowchart LR
+ A[Agent experience] --> B[Memory storage layer]
+ B --> C[Short-term context buffer]
+ B --> D[Long-term vector store]
+ C --> E[Current task reasoning]
+ D --> E
+```
+
## Source Walkthrough
Use the following upstream sources to verify implementation details while reading this chapter:
diff --git a/tutorials/superagi-tutorial/05-task-planning.md b/tutorials/superagi-tutorial/05-task-planning.md
index f323150b..f14f9961 100644
--- a/tutorials/superagi-tutorial/05-task-planning.md
+++ b/tutorials/superagi-tutorial/05-task-planning.md
@@ -716,6 +716,17 @@ Under the hood, `Chapter 5: Task Planning` usually follows a repeatable control
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## Architecture Flow
+
+```mermaid
+flowchart LR
+ A[High-level goal] --> B[Task planner]
+ B --> C[Sub-task decomposition]
+ C --> D[Execution queue]
+ D --> E[Agent executes each sub-task]
+ E --> F[Results aggregated]
+```
+
## Source Walkthrough
Use the following upstream sources to verify implementation details while reading this chapter:
diff --git a/tutorials/superagi-tutorial/06-multi-agent-systems.md b/tutorials/superagi-tutorial/06-multi-agent-systems.md
index c5918a84..810cf52b 100644
--- a/tutorials/superagi-tutorial/06-multi-agent-systems.md
+++ b/tutorials/superagi-tutorial/06-multi-agent-systems.md
@@ -766,6 +766,19 @@ Under the hood, `Chapter 6: Multi-Agent Systems` usually follows a repeatable co
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## Architecture Flow
+
+```mermaid
+flowchart LR
+ A[Complex objective] --> B[Orchestrator agent]
+ B --> C[Sub-agent 1: research]
+ B --> D[Sub-agent 2: execution]
+ B --> E[Sub-agent 3: validation]
+ C --> F[Aggregated output]
+ D --> F
+ E --> F
+```
+
## Source Walkthrough
Use the following upstream sources to verify implementation details while reading this chapter:
diff --git a/tutorials/superagi-tutorial/07-deployment-scaling.md b/tutorials/superagi-tutorial/07-deployment-scaling.md
index e890ec63..479a7c89 100644
--- a/tutorials/superagi-tutorial/07-deployment-scaling.md
+++ b/tutorials/superagi-tutorial/07-deployment-scaling.md
@@ -1043,6 +1043,16 @@ Under the hood, `Chapter 7: Deployment & Scaling` usually follows a repeatable c
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## Architecture Flow
+
+```mermaid
+flowchart LR
+ A[Agent workload] --> B[Docker deployment]
+ B --> C[SuperAGI server]
+ C --> D[Agent pool]
+ D --> E[Horizontal scaling with load balancer]
+```
+
## Source Walkthrough
Use the following upstream sources to verify implementation details while reading this chapter:
diff --git a/tutorials/superagi-tutorial/08-advanced-features.md b/tutorials/superagi-tutorial/08-advanced-features.md
index 6f44100e..4bcfa536 100644
--- a/tutorials/superagi-tutorial/08-advanced-features.md
+++ b/tutorials/superagi-tutorial/08-advanced-features.md
@@ -1123,6 +1123,16 @@ Under the hood, `Chapter 8: Advanced Features` usually follows a repeatable cont
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## Architecture Flow
+
+```mermaid
+flowchart LR
+ A[Custom plugin defined] --> B[Plugin registry]
+ B --> C[Agent runtime loads plugin]
+ C --> D[Plugin hooks called during execution]
+ D --> E[Enhanced agent behavior]
+```
+
## Source Walkthrough
Use the following upstream sources to verify implementation details while reading this chapter:
diff --git a/tutorials/superagi-tutorial/README.md b/tutorials/superagi-tutorial/README.md
index 46e00166..c286fa92 100644
--- a/tutorials/superagi-tutorial/README.md
+++ b/tutorials/superagi-tutorial/README.md
@@ -14,10 +14,11 @@ format_version: v2
[](https://opensource.org/licenses/MIT)
[](https://github.com/TransformerOptimus/SuperAGI)
+> **Project Status Notice**: SuperAGI is effectively inactive. The last code push was January 2025, the most recent release (`v0.0.14`) was published in January 2024, and no active development has occurred since. The repository is not formally archived but should be treated as unmaintained. This tutorial is preserved as a reference for the architecture and patterns SuperAGI introduced; teams should evaluate actively maintained alternatives (such as CrewAI, AutoGen/AG2, or ADK) for production use.
-SuperAGI<sup>[View Repo](https://github.com/TransformerOptimus/SuperAGI)</sup> is a production-ready autonomous AI agent framework that enables developers to build sophisticated AI agents capable of performing complex tasks independently. It provides a comprehensive platform for creating, deploying, and managing autonomous agents with advanced reasoning, tool integration, and self-improvement capabilities.
+SuperAGI<sup>[View Repo](https://github.com/TransformerOptimus/SuperAGI)</sup> was a production-oriented autonomous AI agent framework that enabled developers to build sophisticated AI agents capable of performing complex tasks independently. It provided a comprehensive platform for creating, deploying, and managing autonomous agents with advanced reasoning, tool integration, and self-improvement capabilities.
-SuperAGI combines the power of large language models with practical agent architectures, enabling agents to plan, execute, and learn from their experiences in real-world applications.
+SuperAGI combined the power of large language models with practical agent architectures, enabling agents to plan, execute, and learn from their experiences in real-world applications.
## Mental Model
diff --git a/tutorials/swarm-tutorial/01-getting-started.md b/tutorials/swarm-tutorial/01-getting-started.md
index ff48e103..c0870fcc 100644
--- a/tutorials/swarm-tutorial/01-getting-started.md
+++ b/tutorials/swarm-tutorial/01-getting-started.md
@@ -10,6 +10,20 @@ nav_order: 1
Welcome to Swarm! In this chapter, you'll learn the fundamentals of OpenAI's educational multi-agent framework and create your first collaborative agents.
## What is Swarm?
+```mermaid
+flowchart LR
+ A[User Message] --> B[Swarm.run]
+ B --> C[Active Agent]
+ C --> D{Function call?}
+ D -->|yes| E[Execute function]
+ D -->|no| F[LLM response]
+ E --> G{Returns Agent?}
+ G -->|yes| H[Handoff to new agent]
+ G -->|no| F
+ H --> C
+ F --> I[Response messages]
+```
+
Swarm is an experimental framework from OpenAI that makes it easy to build and orchestrate multi-agent systems. Unlike complex orchestration frameworks, Swarm focuses on being:
diff --git a/tutorials/swarm-tutorial/README.md b/tutorials/swarm-tutorial/README.md
index a2c3d9bb..203de722 100644
--- a/tutorials/swarm-tutorial/README.md
+++ b/tutorials/swarm-tutorial/README.md
@@ -23,7 +23,7 @@ format_version: v2
## Why This Track Matters
-OpenAI Swarm matters for developers building production systems. This track covers chapter 1: getting started with openai swarm, chapter 2: agent design, chapter 3: function calling & tools and helps you understand how the components fit together for real-world use.
+OpenAI Swarm is an **experimental, educational** framework — it is not intended for production use. Its value is in teaching multi-agent concepts: handoffs, context variables, and agent composition patterns. This track covers getting started with Swarm, agent design, function calling, and multi-agent orchestration to help you understand how lightweight agent coordination works before building with more robust solutions.
This track focuses on:
diff --git a/tutorials/swe-agent-tutorial/01-getting-started.md b/tutorials/swe-agent-tutorial/01-getting-started.md
index 65b52ce7..92465186 100644
--- a/tutorials/swe-agent-tutorial/01-getting-started.md
+++ b/tutorials/swe-agent-tutorial/01-getting-started.md
@@ -39,8 +39,6 @@ You now have a working SWE-agent baseline and can execute initial issue workflow
Next: [Chapter 2: Core Architecture and YAML Configuration](02-core-architecture-and-yaml-configuration.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `config/coding_challenge.yaml`
diff --git a/tutorials/swe-agent-tutorial/02-core-architecture-and-yaml-configuration.md b/tutorials/swe-agent-tutorial/02-core-architecture-and-yaml-configuration.md
index 6e51608b..67cb9310 100644
--- a/tutorials/swe-agent-tutorial/02-core-architecture-and-yaml-configuration.md
+++ b/tutorials/swe-agent-tutorial/02-core-architecture-and-yaml-configuration.md
@@ -39,8 +39,6 @@ You now understand the key control points for predictable SWE-agent behavior.
Next: [Chapter 3: CLI Workflows and Usage Modes](03-cli-workflows-and-usage-modes.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `sweagent/exceptions.py`
diff --git a/tutorials/swe-agent-tutorial/03-cli-workflows-and-usage-modes.md b/tutorials/swe-agent-tutorial/03-cli-workflows-and-usage-modes.md
index 0bf52b8d..54948d8a 100644
--- a/tutorials/swe-agent-tutorial/03-cli-workflows-and-usage-modes.md
+++ b/tutorials/swe-agent-tutorial/03-cli-workflows-and-usage-modes.md
@@ -38,170 +38,168 @@ You can now choose the right execution mode for local debugging or scale evaluat
Next: [Chapter 4: Tooling, Environments, and Model Strategy](04-tooling-environments-and-model-strategy.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `sweagent/run/batch_instances.py`
+### `sweagent/agent/models.py`
-The `InstancesFromFile` class in [`sweagent/run/batch_instances.py`](https://github.com/SWE-agent/SWE-agent/blob/HEAD/sweagent/run/batch_instances.py) handles a key part of this chapter's functionality:
+The `InstantEmptySubmitModelConfig` class in [`sweagent/agent/models.py`](https://github.com/SWE-agent/SWE-agent/blob/HEAD/sweagent/agent/models.py) handles a key part of this chapter's functionality:
```py
-class InstancesFromFile(BaseModel, AbstractInstanceSource):
- """Load instances from a file."""
+class InstantEmptySubmitModelConfig(GenericAPIModelConfig):
+ """Model that immediately submits an empty patch"""
- path: Path
- filter: str = ".*"
- """Regular expression to filter the instances by instance id."""
- slice: str = ""
- """Select only a slice of the instances (after filtering by `filter`).
- Possible values are stop or start:stop or start:stop:step
- (i.e., it behaves exactly like python's list slicing `list[slice]`).
- """
- shuffle: bool = False
- """Shuffle the instances (before filtering and slicing)."""
+ name: Literal["instant_empty_submit"] = Field(default="instant_empty_submit", description="Model name.")
- deployment: DeploymentConfig = Field(
- default_factory=lambda: DockerDeploymentConfig(image="python:3.11"),
- description="Deployment options.",
+ per_instance_cost_limit: float = Field(
+ default=0.0, description="Cost limit for every instance (task). This is a dummy value here."
+ )
+ total_cost_limit: float = Field(
+ default=0.0, description="Cost limit for all instances (tasks). This is a dummy value here."
)
- """Note that the image_name option is overwritten by the images specified in the task instances."""
+ delay: float = 0.0
+ """Delay before answering"""
- simple: Literal[True] = True
- """Convenience discriminator for (de)serialization/CLI. Do not change."""
+ model_config = ConfigDict(extra="forbid")
+
+
+class HumanModelConfig(GenericAPIModelConfig):
+ name: Literal["human"] = Field(default="human", description="Model name.")
+
+ per_instance_cost_limit: float = Field(
+ default=0.0, description="Cost limit for every instance (task). This is a dummy value here."
+ )
+ total_cost_limit: float = Field(default=0.0, description="Cost limit for all instances (tasks).")
+ cost_per_call: float = 0.0
+ catch_eof: bool = True
+ """Whether to catch EOF and return 'exit' when ^D is pressed. Set to False when used in human_step_in mode."""
+ model_config = ConfigDict(extra="forbid")
- type: Literal["file"] = "file"
- """Discriminator for (de)serialization/CLI. Do not change."""
- def get_instance_configs(self) -> list[BatchInstance]:
- instance_dicts = load_file(self.path)
- simple_instances = [SimpleBatchInstance.model_validate(instance_dict) for instance_dict in instance_dicts]
- instances = [instance.to_full_batch_instance(self.deployment) for instance in simple_instances]
```
This class is important because it defines how SWE-agent Tutorial: Autonomous Repository Repair and Benchmark-Driven Engineering implements the patterns covered in this chapter.
-### `sweagent/run/batch_instances.py`
+### `sweagent/agent/models.py`
-The `InstancesFromHuggingFace` class in [`sweagent/run/batch_instances.py`](https://github.com/SWE-agent/SWE-agent/blob/HEAD/sweagent/run/batch_instances.py) handles a key part of this chapter's functionality:
+The `HumanModelConfig` class in [`sweagent/agent/models.py`](https://github.com/SWE-agent/SWE-agent/blob/HEAD/sweagent/agent/models.py) handles a key part of this chapter's functionality:
```py
-class InstancesFromHuggingFace(BaseModel, AbstractInstanceSource):
- """Load instances from HuggingFace."""
-
- dataset_name: str
- """Name of the HuggingFace dataset. Same as when using `datasets.load_dataset`."""
- split: str = "dev"
- filter: str = ".*"
- """Regular expression to filter the instances by instance id."""
- slice: str = ""
- """Select only a slice of the instances (after filtering by `filter`).
- Possible values are stop or start:stop or start:stop:step.
- (i.e., it behaves exactly like python's list slicing `list[slice]`).
- """
- shuffle: bool = False
- """Shuffle the instances (before filtering and slicing)."""
-
- deployment: DeploymentConfig = Field(
- default_factory=lambda: DockerDeploymentConfig(image="python:3.11"),
+class HumanModelConfig(GenericAPIModelConfig):
+ name: Literal["human"] = Field(default="human", description="Model name.")
+
+ per_instance_cost_limit: float = Field(
+ default=0.0, description="Cost limit for every instance (task). This is a dummy value here."
)
- """Deployment configuration. Note that the `image_name` option is overwritten by the images specified in the task instances.
- """
- type: Literal["huggingface"] = "huggingface"
- """Discriminator for (de)serialization/CLI. Do not change."""
+ total_cost_limit: float = Field(default=0.0, description="Cost limit for all instances (tasks).")
+ cost_per_call: float = 0.0
+ catch_eof: bool = True
+ """Whether to catch EOF and return 'exit' when ^D is pressed. Set to False when used in human_step_in mode."""
+ model_config = ConfigDict(extra="forbid")
+
+
+class HumanThoughtModelConfig(HumanModelConfig):
+ name: Literal["human_thought"] = Field(default="human_thought", description="Model name.")
+
+ per_instance_cost_limit: float = Field(
+ default=0.0, description="Cost limit for every instance (task). This is a dummy value here."
+ )
+ total_cost_limit: float = Field(
+ default=0.0, description="Cost limit for all instances (tasks). This is a dummy value here."
+ )
+ cost_per_call: float = 0.0
+
+ model_config = ConfigDict(extra="forbid")
- def get_instance_configs(self) -> list[BatchInstance]:
- from datasets import load_dataset
- ds: list[dict[str, Any]] = load_dataset(self.dataset_name, split=self.split) # type: ignore
- simple_instances: list[SimpleBatchInstance] = [SimpleBatchInstance.model_validate(instance) for instance in ds]
- instances = [instance.to_full_batch_instance(self.deployment) for instance in simple_instances]
+ModelConfig = Annotated[
+ GenericAPIModelConfig
+ | ReplayModelConfig
```
This class is important because it defines how SWE-agent Tutorial: Autonomous Repository Repair and Benchmark-Driven Engineering implements the patterns covered in this chapter.
-### `sweagent/run/batch_instances.py`
+### `sweagent/agent/models.py`
-The `SWEBenchInstances` class in [`sweagent/run/batch_instances.py`](https://github.com/SWE-agent/SWE-agent/blob/HEAD/sweagent/run/batch_instances.py) handles a key part of this chapter's functionality:
+The `HumanThoughtModelConfig` class in [`sweagent/agent/models.py`](https://github.com/SWE-agent/SWE-agent/blob/HEAD/sweagent/agent/models.py) handles a key part of this chapter's functionality:
```py
-class SWEBenchInstances(BaseModel, AbstractInstanceSource):
- """Load instances from SWE-bench."""
+class HumanThoughtModelConfig(HumanModelConfig):
+ name: Literal["human_thought"] = Field(default="human_thought", description="Model name.")
- subset: Literal["lite", "verified", "full", "multimodal", "multilingual"] = "lite"
- """Subset of swe-bench to use"""
+ per_instance_cost_limit: float = Field(
+ default=0.0, description="Cost limit for every instance (task). This is a dummy value here."
+ )
+ total_cost_limit: float = Field(
+ default=0.0, description="Cost limit for all instances (tasks). This is a dummy value here."
+ )
+ cost_per_call: float = 0.0
- # IMPORTANT: Do not call this `path`, because then if people do not specify instance.type,
- # it might be resolved to ExpertInstancesFromFile or something like that.
- path_override: str | Path | None = None
- """Allow to specify a different huggingface dataset name or path to a huggingface
- dataset. This will override the automatic path set by `subset`.
- """
+ model_config = ConfigDict(extra="forbid")
- split: Literal["dev", "test"] = "dev"
- deployment: DeploymentConfig = Field(
- default_factory=lambda: DockerDeploymentConfig(image="python:3.11"),
- )
- """Deployment configuration. Note that the image_name option is overwritten by the images specified in the task instances.
- """
-
- type: Literal["swe_bench"] = "swe_bench"
- """Discriminator for (de)serialization/CLI. Do not change."""
-
- filter: str = ".*"
- """Regular expression to filter the instances by instance id."""
- slice: str = ""
- """Select only a slice of the instances (after filtering by `filter`).
- Possible values are stop or start:stop or start:stop:step.
- (i.e., it behaves exactly like python's list slicing `list[slice]`).
+ModelConfig = Annotated[
+ GenericAPIModelConfig
+ | ReplayModelConfig
+ | InstantEmptySubmitModelConfig
+ | HumanModelConfig
+ | HumanThoughtModelConfig,
+ Field(union_mode="left_to_right"),
+]
+
+
+class GlobalStats(PydanticBaseModel):
+ """This class tracks usage numbers (costs etc.) across all instances."""
+
+ total_cost: float = 0
+ """Cumulative cost for all instances so far"""
+
```
This class is important because it defines how SWE-agent Tutorial: Autonomous Repository Repair and Benchmark-Driven Engineering implements the patterns covered in this chapter.
-### `sweagent/run/batch_instances.py`
+### `sweagent/agent/models.py`
-The `ExpertInstancesFromFile` class in [`sweagent/run/batch_instances.py`](https://github.com/SWE-agent/SWE-agent/blob/HEAD/sweagent/run/batch_instances.py) handles a key part of this chapter's functionality:
+The `GlobalStats` class in [`sweagent/agent/models.py`](https://github.com/SWE-agent/SWE-agent/blob/HEAD/sweagent/agent/models.py) handles a key part of this chapter's functionality:
```py
- # IMPORTANT: Do not call this `path`, because then if people do not specify instance.type,
- # it might be resolved to ExpertInstancesFromFile or something like that.
- path_override: str | Path | None = None
- """Allow to specify a different huggingface dataset name or path to a huggingface
- dataset. This will override the automatic path set by `subset`.
- """
- split: Literal["dev", "test"] = "dev"
+class GlobalStats(PydanticBaseModel):
+ """This class tracks usage numbers (costs etc.) across all instances."""
- deployment: DeploymentConfig = Field(
- default_factory=lambda: DockerDeploymentConfig(image="python:3.11"),
- )
- """Deployment configuration. Note that the image_name option is overwritten by the images specified in the task instances.
- """
+ total_cost: float = 0
+ """Cumulative cost for all instances so far"""
+
+ last_query_timestamp: float = 0
+ """Timestamp of the last query. Currently only used with API models."""
+
+
+GLOBAL_STATS = GlobalStats()
+"""This object tracks usage numbers (costs etc.) across all instances.
+Please use the `GLOBAL_STATS_LOCK` lock when accessing this object to avoid race conditions.
+"""
+
+GLOBAL_STATS_LOCK = Lock()
+"""Lock for accessing `GLOBAL_STATS` without race conditions"""
- type: Literal["swe_bench"] = "swe_bench"
- """Discriminator for (de)serialization/CLI. Do not change."""
- filter: str = ".*"
- """Regular expression to filter the instances by instance id."""
- slice: str = ""
- """Select only a slice of the instances (after filtering by `filter`).
- Possible values are stop or start:stop or start:stop:step.
- (i.e., it behaves exactly like python's list slicing `list[slice]`).
- """
- shuffle: bool = False
- """Shuffle the instances (before filtering and slicing)."""
+class InstanceStats(PydanticBaseModel):
+ """This object tracks usage numbers (costs etc.) for a single instance."""
- evaluate: bool = False
- """Run sb-cli to evaluate"""
+ instance_cost: float = 0
+ tokens_sent: int = 0
+ tokens_received: int = 0
+ api_calls: int = 0
+ def __add__(self, other: InstanceStats) -> InstanceStats:
+ return InstanceStats(
+ **{field: getattr(self, field) + getattr(other, field) for field in self.model_fields.keys()},
```
This class is important because it defines how SWE-agent Tutorial: Autonomous Repository Repair and Benchmark-Driven Engineering implements the patterns covered in this chapter.
@@ -211,11 +209,11 @@ This class is important because it defines how SWE-agent Tutorial: Autonomous Re
```mermaid
flowchart TD
- A[InstancesFromFile]
- B[InstancesFromHuggingFace]
- C[SWEBenchInstances]
- D[ExpertInstancesFromFile]
- E[SWESmithInstances]
+ A[InstantEmptySubmitModelConfig]
+ B[HumanModelConfig]
+ C[HumanThoughtModelConfig]
+ D[GlobalStats]
+ E[tracks]
A --> B
B --> C
C --> D
diff --git a/tutorials/swe-agent-tutorial/04-tooling-environments-and-model-strategy.md b/tutorials/swe-agent-tutorial/04-tooling-environments-and-model-strategy.md
index 43d83586..0cdb1e79 100644
--- a/tutorials/swe-agent-tutorial/04-tooling-environments-and-model-strategy.md
+++ b/tutorials/swe-agent-tutorial/04-tooling-environments-and-model-strategy.md
@@ -39,171 +39,182 @@ You now have a strategy for balancing reliability, cost, and speed in SWE-agent
Next: [Chapter 5: Benchmarking and Evaluation Practices](05-benchmarking-and-evaluation-practices.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `sweagent/run/run_batch.py`
+### `sweagent/agent/models.py`
-The `RunBatchConfig` class in [`sweagent/run/run_batch.py`](https://github.com/SWE-agent/SWE-agent/blob/HEAD/sweagent/run/run_batch.py) handles a key part of this chapter's functionality:
+The `get_model` function in [`sweagent/agent/models.py`](https://github.com/SWE-agent/SWE-agent/blob/HEAD/sweagent/agent/models.py) handles a key part of this chapter's functionality:
```py
-class RunBatchConfig(BaseSettings, cli_implicit_flags=False):
- instances: BatchInstanceSourceConfig = Field(description="Instances to run.")
- agent: AgentConfig = Field(description="Agent options.")
- output_dir: Path = Field(default=Path("DEFAULT"), description="Output directory.")
- suffix: str = ""
- """Suffix to add to the output directory. Only used if `output_dir` is `DEFAULT`."""
- raise_exceptions: bool = False
- """Raise exceptions instead of skipping instances."""
- redo_existing: bool = False
- """Do not skip instances that already have a trajectory."""
- env_var_path: Path | None = None
- """Path to a .env file to load environment variables from."""
- num_workers: int = Field(default=1)
- """Number of parallel workers to use."""
- random_delay_multiplier: float = 0.3
- """We will wait for a random amount of time between 0 and `random_delay_multiplier`
- times the number of workers at the start of each instance. This is to avoid any
- potential race condition or issues with bottlenecks, e.g., when running on a platform
- with few CPUs that cannot handle the startup of all containers in time.
- """
- progress_bar: bool = True
- """Whether to show a progress bar. Progress bar is never shown for human models.
- Progress bar is always shown for multi-worker runs.
- """
-
- # pydantic config
- model_config = SettingsConfigDict(extra="forbid", env_prefix="SWE_AGENT_")
+def get_model(args: ModelConfig, tools: ToolConfig) -> AbstractModel:
+ """Returns correct model object given arguments and commands"""
+ # Convert GenericAPIModelConfig to specific model config if needed
+ if isinstance(args, GenericAPIModelConfig) and not isinstance(
+ args, HumanModelConfig | HumanThoughtModelConfig | ReplayModelConfig | InstantEmptySubmitModelConfig
+ ):
+ if args.name == "human":
+ args = HumanModelConfig(**args.model_dump())
+ elif args.name == "human_thought":
+ args = HumanThoughtModelConfig(**args.model_dump())
+ elif args.name == "replay":
+ args = ReplayModelConfig(**args.model_dump())
+ elif args.name == "instant_empty_submit":
+ args = InstantEmptySubmitModelConfig(**args.model_dump())
+
+ if args.name == "human":
+ assert isinstance(args, HumanModelConfig), f"Expected {HumanModelConfig}, got {args}"
+ return HumanModel(args, tools)
+ if args.name == "human_thought":
+ assert isinstance(args, HumanThoughtModelConfig), f"Expected {HumanThoughtModelConfig}, got {args}"
+ return HumanThoughtModel(args, tools)
+ if args.name == "replay":
+ assert isinstance(args, ReplayModelConfig), f"Expected {ReplayModelConfig}, got {args}"
+ return ReplayModel(args, tools)
+ elif args.name == "instant_empty_submit":
+ assert isinstance(args, InstantEmptySubmitModelConfig), f"Expected {InstantEmptySubmitModelConfig}, got {args}"
+ return InstantEmptySubmitTestModel(args, tools)
+ assert isinstance(args, GenericAPIModelConfig), f"Expected {GenericAPIModelConfig}, got {args}"
+ return LiteLLMModel(args, tools)
- def set_default_output_dir(self) -> None:
- # Needs to be called explicitly, because self._config_files will be setup
```
-This class is important because it defines how SWE-agent Tutorial: Autonomous Repository Repair and Benchmark-Driven Engineering implements the patterns covered in this chapter.
+This function is important because it defines how SWE-agent Tutorial: Autonomous Repository Repair and Benchmark-Driven Engineering implements the patterns covered in this chapter.
-### `sweagent/run/run_batch.py`
+### `sweagent/agent/reviewer.py`
-The `_BreakLoop` class in [`sweagent/run/run_batch.py`](https://github.com/SWE-agent/SWE-agent/blob/HEAD/sweagent/run/run_batch.py) handles a key part of this chapter's functionality:
+The `ReviewSubmission` class in [`sweagent/agent/reviewer.py`](https://github.com/SWE-agent/SWE-agent/blob/HEAD/sweagent/agent/reviewer.py) handles a key part of this chapter's functionality:
```py
-class _BreakLoop(Exception):
- """Used for internal control flow"""
+class ReviewSubmission(BaseModel):
+ """Information that's passed to the reviewer"""
+ #: Total trajectory (including several retries)
+ trajectory: Trajectory
+ #: Aggregate info dict (including several retries)
+ info: AgentInfo
+ #: Model stats for this attempt
+ model_stats: InstanceStats
-class RunBatch:
- def __init__(
- self,
- instances: list[BatchInstance],
- agent_config: AgentConfig,
- *,
- output_dir: Path = Path("."),
- hooks: list[RunHook] | None = None,
- raise_exceptions: bool = False,
- redo_existing: bool = False,
- num_workers: int = 1,
- progress_bar: bool = True,
- random_delay_multiplier: float = 0.3,
- ):
- """Note: When initializing this class, make sure to add the hooks that are required by your actions.
- See `from_config` for an example.
-
- Args:
- hooks: If not specified, the default hooks will be used.
- num_workers: Number of parallel workers to use. Default is 1 (sequential execution).
- progress_bar: Whether to show a progress bar. Progress bar is never shown for human models.
- Progress bar is always shown for multi-worker runs.
- random_delay_multiplier: We will wait for a random amount of time between 0 and `random_delay_multiplier`
- times the number of workers at the start of each instance. This is to avoid any
- potential race conditions.
+ def to_format_dict(self, *, suffix="") -> dict[str, Any]:
+ """Return all the data that is used to format the
+ messages. Trajectory is excluded because it needs special treatment.
"""
+ out = {}
+ info = copy.deepcopy(self.info)
+ if not info.get("submission"):
+ # Observed that not all exit_cost lead to autosubmission
+ # so sometimes this might be missing.
+ info["submission"] = ""
+ for k, v in info.items():
+ if isinstance(v, str):
+ out[f"{k}{suffix}"] = v
+ elif isinstance(v, dict):
+ for k2, v2 in v.items():
+ out[f"{k}_{k2}{suffix}"] = v2
+ return out
+
+
+class ReviewerResult(BaseModel):
```
This class is important because it defines how SWE-agent Tutorial: Autonomous Repository Repair and Benchmark-Driven Engineering implements the patterns covered in this chapter.
-### `sweagent/run/run_batch.py`
+### `sweagent/agent/reviewer.py`
-The `RunBatch` class in [`sweagent/run/run_batch.py`](https://github.com/SWE-agent/SWE-agent/blob/HEAD/sweagent/run/run_batch.py) handles a key part of this chapter's functionality:
+The `ReviewerResult` class in [`sweagent/agent/reviewer.py`](https://github.com/SWE-agent/SWE-agent/blob/HEAD/sweagent/agent/reviewer.py) handles a key part of this chapter's functionality:
```py
-from sweagent.environment.swe_env import SWEEnv
-from sweagent.exceptions import ModelConfigurationError, TotalCostLimitExceededError
-from sweagent.run._progress import RunBatchProgressManager
-from sweagent.run.batch_instances import BatchInstance, BatchInstanceSourceConfig, SWEBenchInstances
-from sweagent.run.common import BasicCLI, ConfigHelper, save_predictions
-from sweagent.run.hooks.abstract import CombinedRunHooks, RunHook
-from sweagent.run.hooks.apply_patch import SaveApplyPatchHook
-from sweagent.run.merge_predictions import merge_predictions
-from sweagent.run.run_single import RunSingleConfig
-from sweagent.types import AgentRunResult
-from sweagent.utils.config import load_environment_variables
-from sweagent.utils.log import (
- add_file_handler,
- add_logger_names_to_stream_handlers,
- get_logger,
- register_thread_name,
- remove_file_handler,
- set_stream_handler_levels,
-)
-
-
-class RunBatchConfig(BaseSettings, cli_implicit_flags=False):
- instances: BatchInstanceSourceConfig = Field(description="Instances to run.")
- agent: AgentConfig = Field(description="Agent options.")
- output_dir: Path = Field(default=Path("DEFAULT"), description="Output directory.")
- suffix: str = ""
- """Suffix to add to the output directory. Only used if `output_dir` is `DEFAULT`."""
- raise_exceptions: bool = False
- """Raise exceptions instead of skipping instances."""
- redo_existing: bool = False
- """Do not skip instances that already have a trajectory."""
- env_var_path: Path | None = None
+
+
+class ReviewerResult(BaseModel):
+ accept: bool | float
+ outputs: list[str]
+ messages: list[dict[str, Any]]
+
+
+class PreselectorOutput(BaseModel):
+ chosen_idx: list[int]
+ response: str
+ messages: list[dict[str, Any]]
+
+
+class ChooserOutput(BaseModel):
+ chosen_idx: int
+ response: str
+ preselector_output: PreselectorOutput | None = None
+ messages: list[dict[str, Any]]
+
+
+# --- INTERFACES ---
+
+
+class AbstractReviewer(ABC):
+ """The reviewer checks a single solution and tries to predict
+ if it successfully solves the issue.
+ """
+
+ @abstractmethod
+ def review(self, instance: ProblemStatement, submission: ReviewSubmission) -> ReviewerResult:
+ """Returns True if the submission is believed to be correct"""
```
This class is important because it defines how SWE-agent Tutorial: Autonomous Repository Repair and Benchmark-Driven Engineering implements the patterns covered in this chapter.
-### `sweagent/run/run_batch.py`
+### `sweagent/agent/reviewer.py`
-The `run_from_config` function in [`sweagent/run/run_batch.py`](https://github.com/SWE-agent/SWE-agent/blob/HEAD/sweagent/run/run_batch.py) handles a key part of this chapter's functionality:
+The `PreselectorOutput` class in [`sweagent/agent/reviewer.py`](https://github.com/SWE-agent/SWE-agent/blob/HEAD/sweagent/agent/reviewer.py) handles a key part of this chapter's functionality:
```py
-def run_from_config(config: RunBatchConfig):
- RunBatch.from_config(config).main()
+class PreselectorOutput(BaseModel):
+ chosen_idx: list[int]
+ response: str
+ messages: list[dict[str, Any]]
+
+class ChooserOutput(BaseModel):
+ chosen_idx: int
+ response: str
+ preselector_output: PreselectorOutput | None = None
+ messages: list[dict[str, Any]]
-def run_from_cli(args: list[str] | None = None):
- if args is None:
- args = sys.argv[1:]
- assert __doc__ is not None
- help_text = ( # type: ignore
- __doc__ + "\n[cyan][bold]=== ALL THE OPTIONS ===[/bold][/cyan]\n\n" + ConfigHelper().get_help(RunBatchConfig)
- )
- run_from_config(BasicCLI(RunBatchConfig, help_text=help_text).get_config(args)) # type: ignore
+# --- INTERFACES ---
-if __name__ == "__main__":
- run_from_cli()
+class AbstractReviewer(ABC):
+ """The reviewer checks a single solution and tries to predict
+ if it successfully solves the issue.
+ """
+
+ @abstractmethod
+ def review(self, instance: ProblemStatement, submission: ReviewSubmission) -> ReviewerResult:
+ """Returns True if the submission is believed to be correct"""
+
+
+class AbstractRetryLoop(ABC):
+ """The review loop controls how often the agent tries to solve
+ the issue and how it selects the best solution.
+ """
```
-This function is important because it defines how SWE-agent Tutorial: Autonomous Repository Repair and Benchmark-Driven Engineering implements the patterns covered in this chapter.
+This class is important because it defines how SWE-agent Tutorial: Autonomous Repository Repair and Benchmark-Driven Engineering implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[RunBatchConfig]
- B[_BreakLoop]
- C[RunBatch]
- D[run_from_config]
- E[run_from_cli]
+ A[get_model]
+ B[ReviewSubmission]
+ C[ReviewerResult]
+ D[PreselectorOutput]
+ E[ChooserOutput]
A --> B
B --> C
C --> D
diff --git a/tutorials/swe-agent-tutorial/05-benchmarking-and-evaluation-practices.md b/tutorials/swe-agent-tutorial/05-benchmarking-and-evaluation-practices.md
index 36046719..cb897b5e 100644
--- a/tutorials/swe-agent-tutorial/05-benchmarking-and-evaluation-practices.md
+++ b/tutorials/swe-agent-tutorial/05-benchmarking-and-evaluation-practices.md
@@ -39,170 +39,168 @@ You now have a repeatable framework for benchmarking SWE-agent systems.
Next: [Chapter 6: Offensive Security Mode and Specialized Workloads](06-offensive-security-mode-and-specialized-workloads.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `sweagent/agent/reviewer.py`
-The `TrajFormatterConfig` class in [`sweagent/agent/reviewer.py`](https://github.com/SWE-agent/SWE-agent/blob/HEAD/sweagent/agent/reviewer.py) handles a key part of this chapter's functionality:
+The `Preselector` class in [`sweagent/agent/reviewer.py`](https://github.com/SWE-agent/SWE-agent/blob/HEAD/sweagent/agent/reviewer.py) handles a key part of this chapter's functionality:
```py
-class TrajFormatterConfig(BaseModel):
- #: Filter the following actions from the trajectory
- filter: list[str] = []
- #: Filter outputs from the following actions from the trajectory
- output_filter: list[str] = []
- #: Format of the trajectory item
- item_template: str = "Model: {{response}}\n\nObservation: {{observation}}"
- only_show_last_n_output: int = 0
+class PreselectorOutput(BaseModel):
+ chosen_idx: list[int]
+ response: str
+ messages: list[dict[str, Any]]
+
- model_config = ConfigDict(extra="forbid")
+class ChooserOutput(BaseModel):
+ chosen_idx: int
+ response: str
+ preselector_output: PreselectorOutput | None = None
+ messages: list[dict[str, Any]]
-class ReviewerConfig(BaseModel):
- """The configuration for the reviewer"""
+# --- INTERFACES ---
- system_template: str
- instance_template: str
- #: If a submission autosubmits because of total cost or a similar exit status,
- #: it will get this malus to its score
- failure_score_penalty: float = 0.0
- traj_formatter: TrajFormatterConfig
- n_sample: int = 5
- reduce_by_std: float = 0.0
- score_range: tuple[float | None, float | None] = (None, None)
- #: If set, we assume that the score is in the range [score_range[0], score_range[1]]
- #: Reviews that are outside this range will be ignored
- type: Literal["reviewer"] = "reviewer"
+class AbstractReviewer(ABC):
+ """The reviewer checks a single solution and tries to predict
+ if it successfully solves the issue.
+ """
+
+ @abstractmethod
+ def review(self, instance: ProblemStatement, submission: ReviewSubmission) -> ReviewerResult:
+ """Returns True if the submission is believed to be correct"""
- model_config = ConfigDict(extra="forbid")
+
+class AbstractRetryLoop(ABC):
+ """The review loop controls how often the agent tries to solve
+ the issue and how it selects the best solution.
+ """
```
This class is important because it defines how SWE-agent Tutorial: Autonomous Repository Repair and Benchmark-Driven Engineering implements the patterns covered in this chapter.
### `sweagent/agent/reviewer.py`
-The `ReviewerConfig` class in [`sweagent/agent/reviewer.py`](https://github.com/SWE-agent/SWE-agent/blob/HEAD/sweagent/agent/reviewer.py) handles a key part of this chapter's functionality:
+The `Chooser` class in [`sweagent/agent/reviewer.py`](https://github.com/SWE-agent/SWE-agent/blob/HEAD/sweagent/agent/reviewer.py) handles a key part of this chapter's functionality:
```py
-class ReviewerConfig(BaseModel):
- """The configuration for the reviewer"""
+class ChooserOutput(BaseModel):
+ chosen_idx: int
+ response: str
+ preselector_output: PreselectorOutput | None = None
+ messages: list[dict[str, Any]]
- system_template: str
- instance_template: str
- #: If a submission autosubmits because of total cost or a similar exit status,
- #: it will get this malus to its score
- failure_score_penalty: float = 0.0
- traj_formatter: TrajFormatterConfig
- n_sample: int = 5
- reduce_by_std: float = 0.0
- score_range: tuple[float | None, float | None] = (None, None)
- #: If set, we assume that the score is in the range [score_range[0], score_range[1]]
- #: Reviews that are outside this range will be ignored
- type: Literal["reviewer"] = "reviewer"
+# --- INTERFACES ---
- model_config = ConfigDict(extra="forbid")
- def get_reviewer(self, model: AbstractModel) -> AbstractReviewer:
- return Reviewer(self, model)
+class AbstractReviewer(ABC):
+ """The reviewer checks a single solution and tries to predict
+ if it successfully solves the issue.
+ """
+ @abstractmethod
+ def review(self, instance: ProblemStatement, submission: ReviewSubmission) -> ReviewerResult:
+ """Returns True if the submission is believed to be correct"""
-class ChooserRetryLoopConfig(BaseModel):
- type: Literal["chooser"] = "chooser"
- chooser: ChooserConfig
- max_attempts: int
- min_budget_for_new_attempt: float = 0.0
- """Minimal $ that need to be left in order for us to start a new attempt.
+class AbstractRetryLoop(ABC):
+ """The review loop controls how often the agent tries to solve
+ the issue and how it selects the best solution.
+ """
+
+ def retry(self) -> bool:
+ """Returns True if the agent should retry solving the issue"""
+ return False
+
+ def on_submit(self, submission: ReviewSubmission) -> None:
```
This class is important because it defines how SWE-agent Tutorial: Autonomous Repository Repair and Benchmark-Driven Engineering implements the patterns covered in this chapter.
### `sweagent/agent/reviewer.py`
-The `ChooserRetryLoopConfig` class in [`sweagent/agent/reviewer.py`](https://github.com/SWE-agent/SWE-agent/blob/HEAD/sweagent/agent/reviewer.py) handles a key part of this chapter's functionality:
+The `Reviewer` class in [`sweagent/agent/reviewer.py`](https://github.com/SWE-agent/SWE-agent/blob/HEAD/sweagent/agent/reviewer.py) handles a key part of this chapter's functionality:
```py
-class ChooserRetryLoopConfig(BaseModel):
- type: Literal["chooser"] = "chooser"
- chooser: ChooserConfig
+class ReviewerResult(BaseModel):
+ accept: bool | float
+ outputs: list[str]
+ messages: list[dict[str, Any]]
- max_attempts: int
- min_budget_for_new_attempt: float = 0.0
- """Minimal $ that need to be left in order for us to start a new attempt.
- If set to 0: Always.
- """
- cost_limit: float
- """The maximum cost to spend on all attempts. Does not include cost of choosing.
- """
+class PreselectorOutput(BaseModel):
+ chosen_idx: list[int]
+ response: str
+ messages: list[dict[str, Any]]
- model_config = ConfigDict(extra="forbid")
- def get_retry_loop(self, problem_statement: ProblemStatement) -> ChooserRetryLoop:
- return ChooserRetryLoop(self, problem_statement)
+class ChooserOutput(BaseModel):
+ chosen_idx: int
+ response: str
+ preselector_output: PreselectorOutput | None = None
+ messages: list[dict[str, Any]]
-class ScoreRetryLoopConfig(BaseModel):
- """The configuration for the review loop"""
+# --- INTERFACES ---
- type: Literal["score"] = "score"
- reviewer_config: ReviewerConfig
+class AbstractReviewer(ABC):
+ """The reviewer checks a single solution and tries to predict
+ if it successfully solves the issue.
+ """
- accept_score: float
- max_accepts: int = 1
- max_attempts: int
+ @abstractmethod
+ def review(self, instance: ProblemStatement, submission: ReviewSubmission) -> ReviewerResult:
+ """Returns True if the submission is believed to be correct"""
```
This class is important because it defines how SWE-agent Tutorial: Autonomous Repository Repair and Benchmark-Driven Engineering implements the patterns covered in this chapter.
### `sweagent/agent/reviewer.py`
-The `ScoreRetryLoopConfig` class in [`sweagent/agent/reviewer.py`](https://github.com/SWE-agent/SWE-agent/blob/HEAD/sweagent/agent/reviewer.py) handles a key part of this chapter's functionality:
+The `TrajectoryFormatter` class in [`sweagent/agent/reviewer.py`](https://github.com/SWE-agent/SWE-agent/blob/HEAD/sweagent/agent/reviewer.py) handles a key part of this chapter's functionality:
```py
-
-
-class ScoreRetryLoopConfig(BaseModel):
- """The configuration for the review loop"""
-
- type: Literal["score"] = "score"
-
- reviewer_config: ReviewerConfig
-
- accept_score: float
- max_accepts: int = 1
- max_attempts: int
-
- min_budget_for_new_attempt: float = 0.0
- """Minimal $ that need to be left in order for us to start a new attempt.
- If set to 0: Always.
- """
-
- cost_limit: float
- """The maximum cost to spend on all attempts and reviews except the last review.
- The last review is not included in the cost limit, because we would waste the last
- attempt if we couldn't score it.
- """
-
- model: ModelConfig
-
- model_config = ConfigDict(extra="forbid")
-
- def validate(self):
- """Checks config. Raises `ValueError` in case of misconfiguration"""
- ...
-
+ self._config = config
+ self._model = model
+ self._traj_formatter = TrajectoryFormatter(config=config.traj_formatter)
+ self.logger = get_logger("reviewer", emoji="🧑⚖️")
+
+ def format_messages(self, instance: ProblemStatement, submission: ReviewSubmission):
+ system_message = self._config.system_template
+ self.logger.debug(f"MODEL INPUT (system)\n{system_message}")
+ ps_format_dict = {
+ "problem_statement": instance.get_problem_statement(),
+ **instance.get_extra_fields(),
+ }
+ user_message = Template(self._config.instance_template).render(
+ **ps_format_dict,
+ **submission.to_format_dict(),
+ traj=self._traj_formatter.format_trajectory(submission.trajectory),
+ )
+ self.logger.debug(f"MODEL INPUT (user)\n{user_message}")
+ return [
+ {"role": "system", "content": system_message},
+ {"role": "user", "content": user_message},
+ ]
+
+ def interpret(self, response: str) -> bool | float:
+ last_line = response.strip().split("\n")[-1].strip()
+ # Find all numbers in the last line and take the last one
+ numbers = re.findall(r"-?\d+\.?\d*", last_line)
+ if not numbers:
+ msg = f"Could not interpret response: {last_line!r}"
+ raise ValueError(msg)
+ number = float(numbers[-1])
+ if self._config.score_range[0] is not None and number < self._config.score_range[0]:
```
This class is important because it defines how SWE-agent Tutorial: Autonomous Repository Repair and Benchmark-Driven Engineering implements the patterns covered in this chapter.
@@ -212,11 +210,11 @@ This class is important because it defines how SWE-agent Tutorial: Autonomous Re
```mermaid
flowchart TD
- A[TrajFormatterConfig]
- B[ReviewerConfig]
- C[ChooserRetryLoopConfig]
- D[ScoreRetryLoopConfig]
- E[Preselector]
+ A[Preselector]
+ B[Chooser]
+ C[Reviewer]
+ D[TrajectoryFormatter]
+ E[ChooserRetryLoop]
A --> B
B --> C
C --> D
diff --git a/tutorials/swe-agent-tutorial/06-offensive-security-mode-and-specialized-workloads.md b/tutorials/swe-agent-tutorial/06-offensive-security-mode-and-specialized-workloads.md
index 06008b95..9c07f272 100644
--- a/tutorials/swe-agent-tutorial/06-offensive-security-mode-and-specialized-workloads.md
+++ b/tutorials/swe-agent-tutorial/06-offensive-security-mode-and-specialized-workloads.md
@@ -36,170 +36,167 @@ You now understand how specialized security workloads fit into the broader SWE-a
Next: [Chapter 7: Development and Contribution Workflow](07-development-and-contribution-workflow.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `sweagent/agent/models.py`
+### `sweagent/run/batch_instances.py`
-The `ReplayModelConfig` class in [`sweagent/agent/models.py`](https://github.com/SWE-agent/SWE-agent/blob/HEAD/sweagent/agent/models.py) handles a key part of this chapter's functionality:
+The `ExpertInstancesFromFile` class in [`sweagent/run/batch_instances.py`](https://github.com/SWE-agent/SWE-agent/blob/HEAD/sweagent/run/batch_instances.py) handles a key part of this chapter's functionality:
```py
+ # IMPORTANT: Do not call this `path`, because then if people do not specify instance.type,
+ # it might be resolved to ExpertInstancesFromFile or something like that.
+ path_override: str | Path | None = None
+ """Allow to specify a different huggingface dataset name or path to a huggingface
+ dataset. This will override the automatic path set by `subset`.
+ """
-class ReplayModelConfig(GenericAPIModelConfig):
- replay_path: Path = Field(description="Path to replay file when using the replay model.")
+ split: Literal["dev", "test"] = "dev"
- per_instance_cost_limit: float = Field(
- default=0.0, description="Cost limit for every instance (task). This is a dummy value here."
- )
- total_cost_limit: float = Field(
- default=0.0, description="Cost limit for all instances (tasks). This is a dummy value here."
+ deployment: DeploymentConfig = Field(
+ default_factory=lambda: DockerDeploymentConfig(image="python:3.11"),
)
+ """Deployment configuration. Note that the image_name option is overwritten by the images specified in the task instances.
+ """
- name: Literal["replay"] = Field(default="replay", description="Model name.")
-
- model_config = ConfigDict(extra="forbid")
-
+ type: Literal["swe_bench"] = "swe_bench"
+ """Discriminator for (de)serialization/CLI. Do not change."""
-class InstantEmptySubmitModelConfig(GenericAPIModelConfig):
- """Model that immediately submits an empty patch"""
+ filter: str = ".*"
+ """Regular expression to filter the instances by instance id."""
+ slice: str = ""
+ """Select only a slice of the instances (after filtering by `filter`).
+ Possible values are stop or start:stop or start:stop:step.
+ (i.e., it behaves exactly like python's list slicing `list[slice]`).
+ """
+ shuffle: bool = False
+ """Shuffle the instances (before filtering and slicing)."""
- name: Literal["instant_empty_submit"] = Field(default="instant_empty_submit", description="Model name.")
-
- per_instance_cost_limit: float = Field(
- default=0.0, description="Cost limit for every instance (task). This is a dummy value here."
- )
- total_cost_limit: float = Field(
- default=0.0, description="Cost limit for all instances (tasks). This is a dummy value here."
- )
- delay: float = 0.0
- """Delay before answering"""
+ evaluate: bool = False
+ """Run sb-cli to evaluate"""
- model_config = ConfigDict(extra="forbid")
```
This class is important because it defines how SWE-agent Tutorial: Autonomous Repository Repair and Benchmark-Driven Engineering implements the patterns covered in this chapter.
-### `sweagent/agent/models.py`
+### `sweagent/run/batch_instances.py`
-The `InstantEmptySubmitModelConfig` class in [`sweagent/agent/models.py`](https://github.com/SWE-agent/SWE-agent/blob/HEAD/sweagent/agent/models.py) handles a key part of this chapter's functionality:
+The `SWESmithInstances` class in [`sweagent/run/batch_instances.py`](https://github.com/SWE-agent/SWE-agent/blob/HEAD/sweagent/run/batch_instances.py) handles a key part of this chapter's functionality:
```py
-class InstantEmptySubmitModelConfig(GenericAPIModelConfig):
- """Model that immediately submits an empty patch"""
+class SWESmithInstances(BaseModel, AbstractInstanceSource):
+ """Load instances from SWE-smith."""
- name: Literal["instant_empty_submit"] = Field(default="instant_empty_submit", description="Model name.")
+ path: Path
- per_instance_cost_limit: float = Field(
- default=0.0, description="Cost limit for every instance (task). This is a dummy value here."
+ deployment: DeploymentConfig = Field(
+ default_factory=lambda: DockerDeploymentConfig(image="python:3.11"),
)
- total_cost_limit: float = Field(
- default=0.0, description="Cost limit for all instances (tasks). This is a dummy value here."
- )
- delay: float = 0.0
- """Delay before answering"""
-
- model_config = ConfigDict(extra="forbid")
+ """Deployment configuration. Note that the image_name option is overwritten by the images specified in the task instances.
+ """
+ filter: str = ".*"
+ """Regular expression to filter the instances by instance id."""
+ slice: str = ""
+ """Select only a slice of the instances (after filtering by `filter`).
+ Possible values are stop or start:stop or start:stop:step.
+ (i.e., it behaves exactly like python's list slicing `list[slice]`).
+ """
+ shuffle: bool = False
+ """Shuffle the instances (before filtering and slicing)."""
-class HumanModelConfig(GenericAPIModelConfig):
- name: Literal["human"] = Field(default="human", description="Model name.")
+ type: Literal["swesmith"] = "swesmith"
+ """Discriminator for (de)serialization/CLI. Do not change."""
- per_instance_cost_limit: float = Field(
- default=0.0, description="Cost limit for every instance (task). This is a dummy value here."
- )
- total_cost_limit: float = Field(default=0.0, description="Cost limit for all instances (tasks).")
- cost_per_call: float = 0.0
- catch_eof: bool = True
- """Whether to catch EOF and return 'exit' when ^D is pressed. Set to False when used in human_step_in mode."""
- model_config = ConfigDict(extra="forbid")
+ def get_instance_configs(self) -> list[BatchInstance]:
+ github_token = os.getenv("GITHUB_TOKEN", "")
+ instance_dicts = load_file(self.path)
+ instances = []
```
This class is important because it defines how SWE-agent Tutorial: Autonomous Repository Repair and Benchmark-Driven Engineering implements the patterns covered in this chapter.
-### `sweagent/agent/models.py`
+### `trajectories/demonstrations/str_replace_anthropic_demo.yaml`
-The `HumanModelConfig` class in [`sweagent/agent/models.py`](https://github.com/SWE-agent/SWE-agent/blob/HEAD/sweagent/agent/models.py) handles a key part of this chapter's functionality:
+The `consists` interface in [`trajectories/demonstrations/str_replace_anthropic_demo.yaml`](https://github.com/SWE-agent/SWE-agent/blob/HEAD/trajectories/demonstrations/str_replace_anthropic_demo.yaml) handles a key part of this chapter's functionality:
-```py
+```yaml
+ </IMPORTANT>
+ The special interface consists of a file editor that shows you {{WINDOW}} lines of a file at a time.
+ In addition to typical bash commands, you can also use specific commands to help you navigate and edit files.
+ To call a command, you need to invoke it with a function call/tool call.
-class HumanModelConfig(GenericAPIModelConfig):
- name: Literal["human"] = Field(default="human", description="Model name.")
+ <notes>
+ Please note that THE EDIT COMMAND REQUIRES PROPER INDENTATION.
- per_instance_cost_limit: float = Field(
- default=0.0, description="Cost limit for every instance (task). This is a dummy value here."
- )
- total_cost_limit: float = Field(default=0.0, description="Cost limit for all instances (tasks).")
- cost_per_call: float = 0.0
- catch_eof: bool = True
- """Whether to catch EOF and return 'exit' when ^D is pressed. Set to False when used in human_step_in mode."""
- model_config = ConfigDict(extra="forbid")
+ For example, if you are looking at this file:
+ def fct():
+ print("Hello world")
-class HumanThoughtModelConfig(HumanModelConfig):
- name: Literal["human_thought"] = Field(default="human_thought", description="Model name.")
+ and you want to edit the file to read:
- per_instance_cost_limit: float = Field(
- default=0.0, description="Cost limit for every instance (task). This is a dummy value here."
- )
- total_cost_limit: float = Field(
- default=0.0, description="Cost limit for all instances (tasks). This is a dummy value here."
- )
- cost_per_call: float = 0.0
+ def fct():
+ print("Hello")
+ print("world")
- model_config = ConfigDict(extra="forbid")
+ you search string should be `Hello world` and your replace string should be `"Hello"\n print("world")`
+ (note the extra spaces before the print statement!).
+ You could also get the same result by search for ` print("Hello world")` and replace with ` print("Hello")\n print("world")`.
+ </notes>
+ <response_format>
+ Your shell prompt is formatted as follows:
+ (Open file: <path>)
+ (Current directory: <cwd>)
+ bash-$
-ModelConfig = Annotated[
- GenericAPIModelConfig
- | ReplayModelConfig
+ First, you should _always_ include a general thought about what you're going to do next.
```
-This class is important because it defines how SWE-agent Tutorial: Autonomous Repository Repair and Benchmark-Driven Engineering implements the patterns covered in this chapter.
+This interface is important because it defines how SWE-agent Tutorial: Autonomous Repository Repair and Benchmark-Driven Engineering implements the patterns covered in this chapter.
-### `sweagent/agent/models.py`
+### `sweagent/tools/tools.py`
-The `HumanThoughtModelConfig` class in [`sweagent/agent/models.py`](https://github.com/SWE-agent/SWE-agent/blob/HEAD/sweagent/agent/models.py) handles a key part of this chapter's functionality:
+The `is` class in [`sweagent/tools/tools.py`](https://github.com/SWE-agent/SWE-agent/blob/HEAD/sweagent/tools/tools.py) handles a key part of this chapter's functionality:
```py
-
-
-class HumanThoughtModelConfig(HumanModelConfig):
- name: Literal["human_thought"] = Field(default="human_thought", description="Model name.")
-
- per_instance_cost_limit: float = Field(
- default=0.0, description="Cost limit for every instance (task). This is a dummy value here."
- )
- total_cost_limit: float = Field(
- default=0.0, description="Cost limit for all instances (tasks). This is a dummy value here."
- )
- cost_per_call: float = 0.0
-
- model_config = ConfigDict(extra="forbid")
-
-
-ModelConfig = Annotated[
- GenericAPIModelConfig
- | ReplayModelConfig
- | InstantEmptySubmitModelConfig
- | HumanModelConfig
- | HumanThoughtModelConfig,
- Field(union_mode="left_to_right"),
-]
-
-
-class GlobalStats(PydanticBaseModel):
- """This class tracks usage numbers (costs etc.) across all instances."""
-
- total_cost: float = 0
- """Cumulative cost for all instances so far"""
-
+"""
+This module contains the configuration for the tools that are made available to the agent.
+
+The `ToolConfig` class is used to configure the tools that are available to the agent.
+The `ToolHandler` class is used to handle the tools that are available to the agent.
+"""
+
+import asyncio
+import json
+import os
+import re
+from functools import cached_property
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, Field
+from swerex.runtime.abstract import Command as RexCommand
+from swerex.runtime.abstract import UploadRequest
+from typing_extensions import Self
+
+from sweagent.environment.swe_env import SWEEnv
+from sweagent.tools.bundle import Bundle
+from sweagent.tools.commands import BASH_COMMAND, Command
+from sweagent.tools.parsing import FunctionCallingParser, JsonParser, ParseFunction
+from sweagent.tools.utils import _guard_multiline_input, generate_command_docs
+from sweagent.utils.log import get_logger
+
+
+class ToolFilterConfig(BaseModel):
+ """Filter out commands that are blocked by the environment
+ (for example interactive commands like `vim`).
```
This class is important because it defines how SWE-agent Tutorial: Autonomous Repository Repair and Benchmark-Driven Engineering implements the patterns covered in this chapter.
@@ -209,11 +206,11 @@ This class is important because it defines how SWE-agent Tutorial: Autonomous Re
```mermaid
flowchart TD
- A[ReplayModelConfig]
- B[InstantEmptySubmitModelConfig]
- C[HumanModelConfig]
- D[HumanThoughtModelConfig]
- E[GlobalStats]
+ A[ExpertInstancesFromFile]
+ B[SWESmithInstances]
+ C[consists]
+ D[is]
+ E[is]
A --> B
B --> C
C --> D
diff --git a/tutorials/swe-agent-tutorial/07-development-and-contribution-workflow.md b/tutorials/swe-agent-tutorial/07-development-and-contribution-workflow.md
index 931f5356..41bcc89d 100644
--- a/tutorials/swe-agent-tutorial/07-development-and-contribution-workflow.md
+++ b/tutorials/swe-agent-tutorial/07-development-and-contribution-workflow.md
@@ -39,169 +39,167 @@ You now have a practical contribution workflow aligned with SWE-agent maintainer
Next: [Chapter 8: Production Operations and Governance](08-production-operations-and-governance.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `sweagent/agent/models.py`
+### `sweagent/tools/parsing.py`
-The `LiteLLMModel` class in [`sweagent/agent/models.py`](https://github.com/SWE-agent/SWE-agent/blob/HEAD/sweagent/agent/models.py) handles a key part of this chapter's functionality:
+The `ThoughtActionParser` class in [`sweagent/tools/parsing.py`](https://github.com/SWE-agent/SWE-agent/blob/HEAD/sweagent/tools/parsing.py) handles a key part of this chapter's functionality:
```py
+"""Our parsers parse output from the LM into thoughts and actions.
+For example, our most basic parser is the `ThoughtActionParser`.
+It expects the model response to be a discussion followed by a command wrapped in backticks like so:
-class LiteLLMModel(AbstractModel):
- def __init__(self, args: GenericAPIModelConfig, tools: ToolConfig):
- """Model served by the `litellm` library."""
- # Always copy config to avoid shared state between different instances
- self.config: GenericAPIModelConfig = args.model_copy(deep=True)
- self.stats = InstanceStats()
- self.tools = tools
- self.logger = get_logger("swea-lm", emoji="🤖")
-
- if tools.use_function_calling:
- if not litellm.utils.supports_function_calling(model=self.config.name):
- msg = (
- f"Model {self.config.name} does not support function calling. If your model"
- " does not support function calling, you can use `parse_function='thought_action'` instead. "
- "See https://swe-agent.com/latest/faq/ for more information."
- )
- self.logger.warning(msg)
- if self.config.litellm_model_registry is not None:
- with open(self.config.litellm_model_registry) as f:
- model_costs = json.load(f)
- litellm.register_model(model_costs)
- if self.config.max_input_tokens is not None:
- self.model_max_input_tokens = self.config.max_input_tokens
- else:
- self.model_max_input_tokens = litellm.model_cost.get(self.config.name, {}).get("max_input_tokens")
-
- if self.config.max_output_tokens is not None:
- self.model_max_output_tokens = self.config.max_output_tokens
- else:
- self.model_max_output_tokens = litellm.model_cost.get(self.config.name, {}).get("max_output_tokens")
```
+Let's look at the files in the current directory.
-This class is important because it defines how SWE-agent Tutorial: Autonomous Repository Repair and Benchmark-Driven Engineering implements the patterns covered in this chapter.
-
-### `sweagent/agent/models.py`
+Action:
+ ```
+ls -l
+ ```
+```
-The `get_model` function in [`sweagent/agent/models.py`](https://github.com/SWE-agent/SWE-agent/blob/HEAD/sweagent/agent/models.py) handles a key part of this chapter's functionality:
+For models that support function calling, we instead recommend using the `FunctionCallingParser`.
-```py
+To use a specific parser, set the `parse_function` key in your tool config to the `type` field of the parser.
+```yaml
+agent:
+ tools:
+ ...
+ parse_function:
+ type: "thought_action"
+```
-def get_model(args: ModelConfig, tools: ToolConfig) -> AbstractModel:
- """Returns correct model object given arguments and commands"""
- # Convert GenericAPIModelConfig to specific model config if needed
- if isinstance(args, GenericAPIModelConfig) and not isinstance(
- args, HumanModelConfig | HumanThoughtModelConfig | ReplayModelConfig | InstantEmptySubmitModelConfig
- ):
- if args.name == "human":
- args = HumanModelConfig(**args.model_dump())
- elif args.name == "human_thought":
- args = HumanThoughtModelConfig(**args.model_dump())
- elif args.name == "replay":
- args = ReplayModelConfig(**args.model_dump())
- elif args.name == "instant_empty_submit":
- args = InstantEmptySubmitModelConfig(**args.model_dump())
-
- if args.name == "human":
- assert isinstance(args, HumanModelConfig), f"Expected {HumanModelConfig}, got {args}"
- return HumanModel(args, tools)
- if args.name == "human_thought":
- assert isinstance(args, HumanThoughtModelConfig), f"Expected {HumanThoughtModelConfig}, got {args}"
- return HumanThoughtModel(args, tools)
- if args.name == "replay":
- assert isinstance(args, ReplayModelConfig), f"Expected {ReplayModelConfig}, got {args}"
- return ReplayModel(args, tools)
- elif args.name == "instant_empty_submit":
- assert isinstance(args, InstantEmptySubmitModelConfig), f"Expected {InstantEmptySubmitModelConfig}, got {args}"
- return InstantEmptySubmitTestModel(args, tools)
- assert isinstance(args, GenericAPIModelConfig), f"Expected {GenericAPIModelConfig}, got {args}"
- return LiteLLMModel(args, tools)
+Or from the command line: `--agent.tools.parse_function.type=thought_action`.
+!!! note "Describing available tools"
+ If you do not use the `FunctionCallingParser`, you need to include documentation about the available tools
+ in your system prompt. You can use the `{{command_docs}}` variable to include the automatically generated
+ documentation or explicitly describe the available tools.
```
-This function is important because it defines how SWE-agent Tutorial: Autonomous Repository Repair and Benchmark-Driven Engineering implements the patterns covered in this chapter.
+This class is important because it defines how SWE-agent Tutorial: Autonomous Repository Repair and Benchmark-Driven Engineering implements the patterns covered in this chapter.
-### `sweagent/agent/history_processors.py`
+### `sweagent/tools/parsing.py`
-The `AbstractHistoryProcessor` class in [`sweagent/agent/history_processors.py`](https://github.com/SWE-agent/SWE-agent/blob/HEAD/sweagent/agent/history_processors.py) handles a key part of this chapter's functionality:
+The `XMLThoughtActionParser` class in [`sweagent/tools/parsing.py`](https://github.com/SWE-agent/SWE-agent/blob/HEAD/sweagent/tools/parsing.py) handles a key part of this chapter's functionality:
```py
-class AbstractHistoryProcessor(Protocol):
- @abstractmethod
- def __call__(self, history: History) -> History:
- raise NotImplementedError
-
-
-# Utility functions
-# -----------------
+class XMLThoughtActionParser(AbstractParseFunction, BaseModel):
+ """
+ Expects the model response to be a discussion followed by a command wrapped in XML tags.
+ Example:
+ Let's look at the files in the current directory.
+ <command>
+ ls -l
+ </command>
+ """
+
+ error_message: str = dedent("""\
+ Your output was not formatted correctly. You must always include one discussion and one command as part of your response. Make sure you do not have multiple discussion/command tags.
+ Please make sure your output precisely matches the following format:
+ """)
+
+ type: Literal["xml_thought_action"] = "xml_thought_action"
+ """Type for (de)serialization. Do not change."""
+
+ def __call__(self, model_response: dict, commands: list[Command], strict=False) -> tuple[str, str]:
+ """
+ Parses the action from the output of the API call.
+ We assume that the action is the last code block in the model_response.
+ We also assume that the action is not nested within another code block.
+ This is problematic if the model_response includes many unnamed ``` blocks.
+ For instance:
+ <command>
+ This is a code block.
+ </command>
+ <command>
+ This is another code block.
+```
+This class is important because it defines how SWE-agent Tutorial: Autonomous Repository Repair and Benchmark-Driven Engineering implements the patterns covered in this chapter.
-def _get_content_stats(entry: HistoryItem) -> tuple[int, int]:
- if isinstance(entry["content"], str):
- return len(entry["content"].splitlines()), 0
- n_text_lines = sum(len(item["text"].splitlines()) for item in entry["content"] if item.get("type") == "text")
- n_images = sum(1 for item in entry["content"] if item.get("type") == "image_url")
- return n_text_lines, n_images
+### `sweagent/tools/parsing.py`
+The `XMLFunctionCallingParser` class in [`sweagent/tools/parsing.py`](https://github.com/SWE-agent/SWE-agent/blob/HEAD/sweagent/tools/parsing.py) handles a key part of this chapter's functionality:
-def _get_content_text(entry: HistoryItem) -> str:
- if isinstance(entry["content"], str):
- return entry["content"]
- assert len(entry["content"]) == 1, "Expected single message in content"
- return entry["content"][0]["text"]
+```py
-def _set_content_text(entry: HistoryItem, text: str) -> None:
- if isinstance(entry["content"], str):
- entry["content"] = text
- else:
- assert len(entry["content"]) == 1, "Expected single message in content"
+class XMLFunctionCallingParser(AbstractParseFunction, BaseModel):
+ """
+ Expects the model response to be a tool calling format, where the command and parameters are specified
+ in XML tags.
+ Example:
+ Let's look at the files in the current directory.
+ <function=bash>
+ <parameter=command>find /testbed -type f -name "_discovery.py"</parameter>
+ </function>
+ """
+
+ error_message: str = dedent("""\
+ {%- if error_code == "missing" -%}
+ Your last output did not use any tool calls!
+ Please make sure your output includes exactly _ONE_ function call!
+ If you think you have already resolved the issue, please submit your changes by running the `submit` command.
+ If you think you cannot solve the problem, please run `submit`.
+ Else, please continue with a new tool call!
+ {%- elif error_code == "multiple" -%}
+ Your last output included multiple tool calls!
+ Please make sure your output includes a thought and exactly _ONE_ function call.
+ {%- elif error_code == "unexpected_arg" -%}
+ Your action could not be parsed properly: {{exception_message}}.
+ Make sure your function call doesn't include any extra arguments that are not in the allowed arguments, and only use the allowed commands.
+ {%- else -%}
+ Your action could not be parsed properly: {{exception_message}}.
+ {% endif %}
+ """)
+
+ type: Literal["xml_function_calling"] = "xml_function_calling"
```
This class is important because it defines how SWE-agent Tutorial: Autonomous Repository Repair and Benchmark-Driven Engineering implements the patterns covered in this chapter.
-### `sweagent/agent/history_processors.py`
+### `sweagent/tools/parsing.py`
-The `DefaultHistoryProcessor` class in [`sweagent/agent/history_processors.py`](https://github.com/SWE-agent/SWE-agent/blob/HEAD/sweagent/agent/history_processors.py) handles a key part of this chapter's functionality:
+The `EditFormat` class in [`sweagent/tools/parsing.py`](https://github.com/SWE-agent/SWE-agent/blob/HEAD/sweagent/tools/parsing.py) handles a key part of this chapter's functionality:
```py
-class DefaultHistoryProcessor(BaseModel):
- type: Literal["default"] = "default"
- """Do not change. Used for (de)serialization."""
-
- # pydantic config
- model_config = ConfigDict(extra="forbid")
-
- def __call__(self, history: History) -> History:
- return history
-
-
-class LastNObservations(BaseModel):
- """Elide all but the last n observations or remove tagged observations.
-
- This is our most classic history processor, used in the original paper
- to elide but the last 5 observations.
- Elided observations are replaced by "Old environment output: (n lines omitted)".
+class EditFormat(ThoughtActionParser, BaseModel):
+ """
+ Expects the model response to be a discussion followed by a command wrapped in backticks.
+ Example:
+ We'll replace the contents of the current window with the following:
+ ```
+ import os
+ os.listdir()
+ ```
+ """
- Typical configuration:
+ error_message: str = dedent("""\
+ Your output was not formatted correctly. You must wrap the replacement text in backticks (```).
+ Please make sure your output precisely matches the following format:
+ COMMENTS
+ You can write comments here about what you're going to do if you want.
- ```yaml
- agent:
- history_processors:
- - type: last_n_observations
- n: 5
```
+ New window contents.
+ Make sure you copy the entire contents of the window here, with the required indentation.
+ Make the changes to the window above directly in this window.
+ Remember that all of the window's contents will be replaced with the contents of this window.
+ Don't include line numbers in your response.
+ ```
+ """)
+
+ type: Literal["edit_format"] = "edit_format"
+ """Type for (de)serialization. Do not change."""
- as for example in use in the SWE-agent 0.7 config at
- https://github.com/SWE-agent/SWE-agent/blob/main/config/sweagent_0_7/07.yaml
```
@@ -212,11 +210,11 @@ This class is important because it defines how SWE-agent Tutorial: Autonomous Re
```mermaid
flowchart TD
- A[LiteLLMModel]
- B[get_model]
- C[AbstractHistoryProcessor]
- D[DefaultHistoryProcessor]
- E[LastNObservations]
+ A[ThoughtActionParser]
+ B[XMLThoughtActionParser]
+ C[XMLFunctionCallingParser]
+ D[EditFormat]
+ E[Identity]
A --> B
B --> C
C --> D
diff --git a/tutorials/swe-agent-tutorial/08-production-operations-and-governance.md b/tutorials/swe-agent-tutorial/08-production-operations-and-governance.md
index e2aad6cc..cdc08847 100644
--- a/tutorials/swe-agent-tutorial/08-production-operations-and-governance.md
+++ b/tutorials/swe-agent-tutorial/08-production-operations-and-governance.md
@@ -39,170 +39,168 @@ You now have a full SWE-agent learning path from setup to production governance.
Next tutorial: [Open SWE Tutorial](../open-swe-tutorial/)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `sweagent/tools/parsing.py`
+### `sweagent/agent/history_processors.py`
-The `ActionOnlyParser` class in [`sweagent/tools/parsing.py`](https://github.com/SWE-agent/SWE-agent/blob/HEAD/sweagent/tools/parsing.py) handles a key part of this chapter's functionality:
+The `ClosedWindowHistoryProcessor` class in [`sweagent/agent/history_processors.py`](https://github.com/SWE-agent/SWE-agent/blob/HEAD/sweagent/agent/history_processors.py) handles a key part of this chapter's functionality:
```py
-class ActionOnlyParser(AbstractParseFunction, BaseModel):
- """Expects the model response to be a single command."""
-
- error_message: str = "No message found in model response."
-
- type: Literal["action_only"] = "action_only"
- """Type for (de)serialization. Do not change."""
-
- def __call__(self, model_response: dict, commands: list[Command], strict=False):
- return "", model_response["message"]
-
-
-class ThoughtActionParser(AbstractParseFunction, BaseModel):
+class ClosedWindowHistoryProcessor(BaseModel):
+ """For each value in history, keep track of which windows have been shown.
+ We want to mark windows that should stay open (they're the last window for a particular file)
+ Then we'll replace all other windows with a simple summary of the window (i.e. number of lines)
"""
- Expects the model response to be a discussion followed by a command wrapped in backticks.
- Example:
- Let's look at the files in the current directory.
- ```
- ls -l
- ```
- """
-
- error_message: str = dedent("""\
- Your output was not formatted correctly. You must always include one discussion and one command as part of your response. Make sure you do not have multiple discussion/command tags.
- Please make sure your output precisely matches the following format:
- DISCUSSION
- Discuss here with yourself about what your planning and what you're going to do in this step.
- ```
- command(s) that you're going to run
+ type: Literal["closed_window"] = "closed_window"
+ """Do not change. Used for (de)serialization."""
+
+ _pattern = re.compile(r"^(\d+)\:.*?(\n|$)", re.MULTILINE)
+ _file_pattern = re.compile(r"\[File:\s+(.*)\s+\(\d+\s+lines\ total\)\]")
+
+ # pydantic config
+ model_config = ConfigDict(extra="forbid")
+
+ def __call__(self, history):
+ new_history = list()
+ windows = set()
+ for entry in reversed(history):
+ data = entry.copy()
+ if data["role"] != "user":
+ new_history.append(entry)
+ continue
+ if data.get("is_demo", False):
+ new_history.append(entry)
+ continue
+ matches = list(self._pattern.finditer(entry["content"]))
+ if len(matches) >= 1:
+ file_match = self._file_pattern.search(entry["content"])
+ if file_match:
```
This class is important because it defines how SWE-agent Tutorial: Autonomous Repository Repair and Benchmark-Driven Engineering implements the patterns covered in this chapter.
-### `sweagent/tools/parsing.py`
+### `sweagent/agent/history_processors.py`
-The `ThoughtActionParser` class in [`sweagent/tools/parsing.py`](https://github.com/SWE-agent/SWE-agent/blob/HEAD/sweagent/tools/parsing.py) handles a key part of this chapter's functionality:
+The `CacheControlHistoryProcessor` class in [`sweagent/agent/history_processors.py`](https://github.com/SWE-agent/SWE-agent/blob/HEAD/sweagent/agent/history_processors.py) handles a key part of this chapter's functionality:
```py
-"""Our parsers parse output from the LM into thoughts and actions.
-For example, our most basic parser is the `ThoughtActionParser`.
-It expects the model response to be a discussion followed by a command wrapped in backticks like so:
-```
-Let's look at the files in the current directory.
+class CacheControlHistoryProcessor(BaseModel):
+ """This history processor adds manual cache control marks to the history.
+ Use this when running with anthropic claude.
+ """
-Action:
- ```
-ls -l
- ```
-```
+ type: Literal["cache_control"] = "cache_control"
+ """Do not change. Used for (de)serialization."""
-For models that support function calling, we instead recommend using the `FunctionCallingParser`.
+ last_n_messages: int = 2
+ """Add cache control to the last n user messages (and clear it for anything else).
+ In most cases this should be set to 2 (caching for multi-turn conversations).
+ When resampling and running concurrent instances, you want to set it to 1.
+ If set to <= 0, any set cache control will be removed from all messages.
+ """
-To use a specific parser, set the `parse_function` key in your tool config to the `type` field of the parser.
+ last_n_messages_offset: int = 0
+ """E.g., set to 1 to start cache control after the second to last user message.
+ This can be useful in rare cases, when you want to modify the last message after
+ we've got the completion and you want to avoid cache mismatch.
+ """
-```yaml
-agent:
- tools:
- ...
- parse_function:
- type: "thought_action"
-```
+ tagged_roles: list[str] = ["user", "tool"]
+ """Only add cache control to messages with these roles."""
-Or from the command line: `--agent.tools.parse_function.type=thought_action`.
+ # pydantic config
+ model_config = ConfigDict(extra="forbid")
-!!! note "Describing available tools"
- If you do not use the `FunctionCallingParser`, you need to include documentation about the available tools
- in your system prompt. You can use the `{{command_docs}}` variable to include the automatically generated
- documentation or explicitly describe the available tools.
+ def __call__(self, history: History) -> History:
+ new_history = []
+ n_tagged = 0
```
This class is important because it defines how SWE-agent Tutorial: Autonomous Repository Repair and Benchmark-Driven Engineering implements the patterns covered in this chapter.
-### `sweagent/tools/parsing.py`
+### `sweagent/agent/history_processors.py`
-The `XMLThoughtActionParser` class in [`sweagent/tools/parsing.py`](https://github.com/SWE-agent/SWE-agent/blob/HEAD/sweagent/tools/parsing.py) handles a key part of this chapter's functionality:
+The `RemoveRegex` class in [`sweagent/agent/history_processors.py`](https://github.com/SWE-agent/SWE-agent/blob/HEAD/sweagent/agent/history_processors.py) handles a key part of this chapter's functionality:
```py
-class XMLThoughtActionParser(AbstractParseFunction, BaseModel):
- """
- Expects the model response to be a discussion followed by a command wrapped in XML tags.
- Example:
- Let's look at the files in the current directory.
- <command>
- ls -l
- </command>
- """
-
- error_message: str = dedent("""\
- Your output was not formatted correctly. You must always include one discussion and one command as part of your response. Make sure you do not have multiple discussion/command tags.
- Please make sure your output precisely matches the following format:
- """)
-
- type: Literal["xml_thought_action"] = "xml_thought_action"
- """Type for (de)serialization. Do not change."""
-
- def __call__(self, model_response: dict, commands: list[Command], strict=False) -> tuple[str, str]:
- """
- Parses the action from the output of the API call.
- We assume that the action is the last code block in the model_response.
- We also assume that the action is not nested within another code block.
- This is problematic if the model_response includes many unnamed ``` blocks.
- For instance:
- <command>
- This is a code block.
- </command>
- <command>
- This is another code block.
+class RemoveRegex(BaseModel):
+ """This history processor can remove arbitrary content from history items"""
+
+ remove: list[str] = ["<diff>.*</diff>"]
+ """Regex patterns to remove from history items"""
+
+ keep_last: int = 0
+ """Keep the last n history items unchanged"""
+
+ type: Literal["remove_regex"] = "remove_regex"
+ """Do not change. Used for (de)serialization."""
+
+ # pydantic config
+ model_config = ConfigDict(extra="forbid")
+
+ def __call__(self, history: History) -> History:
+ new_history = []
+ for i_entry, entry in enumerate(reversed(history)):
+ entry = copy.deepcopy(entry)
+ if i_entry < self.keep_last:
+ new_history.append(entry)
+ else:
+ if isinstance(entry["content"], list):
+ for item in entry["content"]:
+ if item["type"] == "text":
+ for pattern in self.remove:
+ item["text"] = re.sub(pattern, "", item["text"], flags=re.DOTALL)
+ else:
+ assert isinstance(entry["content"], str), "Expected string content"
+ for pattern in self.remove:
```
This class is important because it defines how SWE-agent Tutorial: Autonomous Repository Repair and Benchmark-Driven Engineering implements the patterns covered in this chapter.
-### `sweagent/tools/parsing.py`
+### `sweagent/agent/history_processors.py`
-The `XMLFunctionCallingParser` class in [`sweagent/tools/parsing.py`](https://github.com/SWE-agent/SWE-agent/blob/HEAD/sweagent/tools/parsing.py) handles a key part of this chapter's functionality:
+The `ImageParsingHistoryProcessor` class in [`sweagent/agent/history_processors.py`](https://github.com/SWE-agent/SWE-agent/blob/HEAD/sweagent/agent/history_processors.py) handles a key part of this chapter's functionality:
```py
-class XMLFunctionCallingParser(AbstractParseFunction, BaseModel):
- """
- Expects the model response to be a tool calling format, where the command and parameters are specified
- in XML tags.
- Example:
- Let's look at the files in the current directory.
- <function=bash>
- <parameter=command>find /testbed -type f -name "_discovery.py"</parameter>
- </function>
- """
+class ImageParsingHistoryProcessor(BaseModel):
+ """Parse embedded base64 images from markdown and convert to multi-modal format."""
+
+ type: Literal["image_parsing"] = "image_parsing"
+ allowed_mime_types: set[str] = {"image/png", "image/jpeg", "image/webp"}
+
+ _pattern = re.compile(r"(!\[([^\]]*)\]\(data:)([^;]+);base64,([^)]+)(\))")
+ model_config = ConfigDict(extra="forbid")
+
+ def __call__(self, history: History) -> History:
+ return [self._process_entry(entry) for entry in history]
+
+ def _process_entry(self, entry: HistoryItem) -> HistoryItem:
+ if entry.get("role") not in ["user", "tool"]:
+ return entry
+ entry = copy.deepcopy(entry)
+ content = _get_content_text(entry)
+ segments = self._parse_images(content)
+ if any(seg["type"] == "image_url" for seg in segments):
+ entry["content"] = segments
+ return entry
+
+ def _parse_images(self, content: str) -> list[dict]:
+ segments = []
+ last_end = 0
+ has_images = False
- error_message: str = dedent("""\
- {%- if error_code == "missing" -%}
- Your last output did not use any tool calls!
- Please make sure your output includes exactly _ONE_ function call!
- If you think you have already resolved the issue, please submit your changes by running the `submit` command.
- If you think you cannot solve the problem, please run `submit`.
- Else, please continue with a new tool call!
- {%- elif error_code == "multiple" -%}
- Your last output included multiple tool calls!
- Please make sure your output includes a thought and exactly _ONE_ function call.
- {%- elif error_code == "unexpected_arg" -%}
- Your action could not be parsed properly: {{exception_message}}.
- Make sure your function call doesn't include any extra arguments that are not in the allowed arguments, and only use the allowed commands.
- {%- else -%}
- Your action could not be parsed properly: {{exception_message}}.
- {% endif %}
- """)
-
- type: Literal["xml_function_calling"] = "xml_function_calling"
+ def add_text(text: str) -> None:
+ """Add text to the last segment if it's text, otherwise create new text segment."""
+ if text and segments and segments[-1]["type"] == "text":
```
This class is important because it defines how SWE-agent Tutorial: Autonomous Repository Repair and Benchmark-Driven Engineering implements the patterns covered in this chapter.
@@ -212,11 +210,11 @@ This class is important because it defines how SWE-agent Tutorial: Autonomous Re
```mermaid
flowchart TD
- A[ActionOnlyParser]
- B[ThoughtActionParser]
- C[XMLThoughtActionParser]
- D[XMLFunctionCallingParser]
- E[EditFormat]
+ A[ClosedWindowHistoryProcessor]
+ B[CacheControlHistoryProcessor]
+ C[RemoveRegex]
+ D[ImageParsingHistoryProcessor]
+ E[AutoCorrectSuggestion]
A --> B
B --> C
C --> D
diff --git a/tutorials/sweep-tutorial/01-getting-started-and-current-product-posture.md b/tutorials/sweep-tutorial/01-getting-started-and-current-product-posture.md
index f2ba9015..53d59f82 100644
--- a/tutorials/sweep-tutorial/01-getting-started-and-current-product-posture.md
+++ b/tutorials/sweep-tutorial/01-getting-started-and-current-product-posture.md
@@ -52,170 +52,168 @@ You now have a realistic starting context and first execution path.
Next: [Chapter 2: Issue to PR Workflow Architecture](02-issue-to-pr-workflow-architecture.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `sweepai/api.py`
+### `sweepai/cli.py`
-The `run_on_ticket` function in [`sweepai/api.py`](https://github.com/sweepai/sweep/blob/HEAD/sweepai/api.py) handles a key part of this chapter's functionality:
+The `posthog_capture` function in [`sweepai/cli.py`](https://github.com/sweepai/sweep/blob/HEAD/sweepai/cli.py) handles a key part of this chapter's functionality:
```py
-logger.bind(application="webhook")
-
-def run_on_ticket(*args, **kwargs):
- tracking_id = get_hash()
- with logger.contextualize(
- **kwargs,
- name="ticket_" + kwargs["username"],
- tracking_id=tracking_id,
- ):
- return on_ticket(*args, **kwargs, tracking_id=tracking_id)
-
-
-def run_on_comment(*args, **kwargs):
- tracking_id = get_hash()
- with logger.contextualize(
- **kwargs,
- name="comment_" + kwargs["username"],
- tracking_id=tracking_id,
- ):
- on_comment(*args, **kwargs, tracking_id=tracking_id)
-
-def run_review_pr(*args, **kwargs):
- tracking_id = get_hash()
- with logger.contextualize(
- **kwargs,
- name="review_" + kwargs["username"],
- tracking_id=tracking_id,
- ):
- review_pr(*args, **kwargs, tracking_id=tracking_id)
-
-
-def run_on_button_click(*args, **kwargs):
+
+
+def posthog_capture(event_name, properties, *args, **kwargs):
+ POSTHOG_DISTINCT_ID = os.environ.get("POSTHOG_DISTINCT_ID")
+ if POSTHOG_DISTINCT_ID:
+ posthog.capture(POSTHOG_DISTINCT_ID, event_name, properties, *args, **kwargs)
+
+
+def load_config():
+ if os.path.exists(config_path):
+ cprint(f"\nLoading configuration from {config_path}", style="yellow")
+ with open(config_path, "r") as f:
+ config = json.load(f)
+ for key, value in config.items():
+ try:
+ os.environ[key] = value
+ except Exception as e:
+ cprint(f"Error loading config: {e}, skipping.", style="yellow")
+ os.environ["POSTHOG_DISTINCT_ID"] = str(os.environ.get("POSTHOG_DISTINCT_ID", ""))
+ # Should contain:
+ # GITHUB_PAT
+ # OPENAI_API_KEY
+ # ANTHROPIC_API_KEY
+ # VOYAGE_API_KEY
+ # POSTHOG_DISTINCT_ID
+
+
+def fetch_issue_request(issue_url: str, __version__: str = "0"):
+ (
+ protocol_name,
+ _,
+ _base_url,
```
This function is important because it defines how Sweep Tutorial: Issue-to-PR AI Coding Workflows on GitHub implements the patterns covered in this chapter.
-### `sweepai/api.py`
+### `sweepai/cli.py`
-The `run_on_comment` function in [`sweepai/api.py`](https://github.com/sweepai/sweep/blob/HEAD/sweepai/api.py) handles a key part of this chapter's functionality:
+The `load_config` function in [`sweepai/cli.py`](https://github.com/sweepai/sweep/blob/HEAD/sweepai/cli.py) handles a key part of this chapter's functionality:
```py
-def run_on_comment(*args, **kwargs):
- tracking_id = get_hash()
- with logger.contextualize(
- **kwargs,
- name="comment_" + kwargs["username"],
- tracking_id=tracking_id,
- ):
- on_comment(*args, **kwargs, tracking_id=tracking_id)
-
-def run_review_pr(*args, **kwargs):
- tracking_id = get_hash()
- with logger.contextualize(
- **kwargs,
- name="review_" + kwargs["username"],
- tracking_id=tracking_id,
- ):
- review_pr(*args, **kwargs, tracking_id=tracking_id)
-
-
-def run_on_button_click(*args, **kwargs):
- thread = threading.Thread(target=handle_button_click, args=args, kwargs=kwargs)
- thread.start()
- global_threads.append(thread)
-
-
-def terminate_thread(thread):
- """Terminate a python threading.Thread."""
- try:
- if not thread.is_alive():
- return
+def load_config():
+ if os.path.exists(config_path):
+ cprint(f"\nLoading configuration from {config_path}", style="yellow")
+ with open(config_path, "r") as f:
+ config = json.load(f)
+ for key, value in config.items():
+ try:
+ os.environ[key] = value
+ except Exception as e:
+ cprint(f"Error loading config: {e}, skipping.", style="yellow")
+ os.environ["POSTHOG_DISTINCT_ID"] = str(os.environ.get("POSTHOG_DISTINCT_ID", ""))
+ # Should contain:
+ # GITHUB_PAT
+ # OPENAI_API_KEY
+ # ANTHROPIC_API_KEY
+ # VOYAGE_API_KEY
+ # POSTHOG_DISTINCT_ID
+
+
+def fetch_issue_request(issue_url: str, __version__: str = "0"):
+ (
+ protocol_name,
+ _,
+ _base_url,
+ org_name,
+ repo_name,
+ _issues,
+ issue_number,
+ ) = issue_url.split("/")
+ cprint("Fetching installation ID...")
```
This function is important because it defines how Sweep Tutorial: Issue-to-PR AI Coding Workflows on GitHub implements the patterns covered in this chapter.
-### `sweepai/api.py`
+### `sweepai/cli.py`
-The `run_review_pr` function in [`sweepai/api.py`](https://github.com/sweepai/sweep/blob/HEAD/sweepai/api.py) handles a key part of this chapter's functionality:
+The `fetch_issue_request` function in [`sweepai/cli.py`](https://github.com/sweepai/sweep/blob/HEAD/sweepai/cli.py) handles a key part of this chapter's functionality:
```py
- on_comment(*args, **kwargs, tracking_id=tracking_id)
-
-def run_review_pr(*args, **kwargs):
- tracking_id = get_hash()
- with logger.contextualize(
- **kwargs,
- name="review_" + kwargs["username"],
- tracking_id=tracking_id,
- ):
- review_pr(*args, **kwargs, tracking_id=tracking_id)
-
-
-def run_on_button_click(*args, **kwargs):
- thread = threading.Thread(target=handle_button_click, args=args, kwargs=kwargs)
- thread.start()
- global_threads.append(thread)
-
-def terminate_thread(thread):
- """Terminate a python threading.Thread."""
- try:
- if not thread.is_alive():
- return
- exc = ctypes.py_object(SystemExit)
- res = ctypes.pythonapi.PyThreadState_SetAsyncExc(
- ctypes.c_long(thread.ident), exc
- )
- if res == 0:
- raise ValueError("Invalid thread ID")
- elif res != 1:
- # Call with exception set to 0 is needed to cleanup properly.
+def fetch_issue_request(issue_url: str, __version__: str = "0"):
+ (
+ protocol_name,
+ _,
+ _base_url,
+ org_name,
+ repo_name,
+ _issues,
+ issue_number,
+ ) = issue_url.split("/")
+ cprint("Fetching installation ID...")
+ installation_id = -1
+ cprint("Fetching access token...")
+ _token, g = get_github_client(installation_id)
+ g: Github = g
+ cprint("Fetching repo...")
+ issue = g.get_repo(f"{org_name}/{repo_name}").get_issue(int(issue_number))
+
+ issue_request = IssueRequest(
+ action="labeled",
+ issue=IssueRequest.Issue(
+ title=issue.title,
+ number=int(issue_number),
+ html_url=issue_url,
+ user=IssueRequest.Issue.User(
+ login=issue.user.login,
+ type="User",
+ ),
+ body=issue.body,
+ labels=[
```
This function is important because it defines how Sweep Tutorial: Issue-to-PR AI Coding Workflows on GitHub implements the patterns covered in this chapter.
-### `sweepai/api.py`
+### `sweepai/cli.py`
-The `run_on_button_click` function in [`sweepai/api.py`](https://github.com/sweepai/sweep/blob/HEAD/sweepai/api.py) handles a key part of this chapter's functionality:
+The `pascal_to_snake` function in [`sweepai/cli.py`](https://github.com/sweepai/sweep/blob/HEAD/sweepai/cli.py) handles a key part of this chapter's functionality:
```py
-def run_on_button_click(*args, **kwargs):
- thread = threading.Thread(target=handle_button_click, args=args, kwargs=kwargs)
- thread.start()
- global_threads.append(thread)
-
-
-def terminate_thread(thread):
- """Terminate a python threading.Thread."""
- try:
- if not thread.is_alive():
- return
+def pascal_to_snake(name):
+ return "".join(["_" + i.lower() if i.isupper() else i for i in name]).lstrip("_")
- exc = ctypes.py_object(SystemExit)
- res = ctypes.pythonapi.PyThreadState_SetAsyncExc(
- ctypes.c_long(thread.ident), exc
- )
- if res == 0:
- raise ValueError("Invalid thread ID")
- elif res != 1:
- # Call with exception set to 0 is needed to cleanup properly.
- ctypes.pythonapi.PyThreadState_SetAsyncExc(thread.ident, 0)
- raise SystemError("PyThreadState_SetAsyncExc failed")
- except Exception as e:
- logger.exception(f"Failed to terminate thread: {e}")
+def get_event_type(event: Event | IssueEvent):
+ if isinstance(event, IssueEvent):
+ return "issues"
+ else:
+ return pascal_to_snake(event.type)[: -len("_event")]
-# def delayed_kill(thread: threading.Thread, delay: int = 60 * 60):
-# time.sleep(delay)
-# terminate_thread(thread)
+@app.command()
+def test():
+ cprint("Sweep AI is installed correctly and ready to go!", style="yellow")
+@app.command()
+def watch(
+ repo_name: str,
+ debug: bool = False,
+ record_events: bool = False,
+ max_events: int = 30,
+):
+ if not os.path.exists(config_path):
+ cprint(
+ f"\nConfiguration not found at {config_path}. Please run [green]'sweep init'[/green] to initialize the CLI.\n",
+ style="yellow",
+ )
+ raise ValueError(
+ "Configuration not found, please run 'sweep init' to initialize the CLI."
+ )
+ posthog_capture(
```
This function is important because it defines how Sweep Tutorial: Issue-to-PR AI Coding Workflows on GitHub implements the patterns covered in this chapter.
@@ -225,10 +223,10 @@ This function is important because it defines how Sweep Tutorial: Issue-to-PR AI
```mermaid
flowchart TD
- A[run_on_ticket]
- B[run_on_comment]
- C[run_review_pr]
- D[run_on_button_click]
+ A[posthog_capture]
+ B[load_config]
+ C[fetch_issue_request]
+ D[pascal_to_snake]
A --> B
B --> C
C --> D
diff --git a/tutorials/sweep-tutorial/02-issue-to-pr-workflow-architecture.md b/tutorials/sweep-tutorial/02-issue-to-pr-workflow-architecture.md
index f8060bbb..e56fc1de 100644
--- a/tutorials/sweep-tutorial/02-issue-to-pr-workflow-architecture.md
+++ b/tutorials/sweep-tutorial/02-issue-to-pr-workflow-architecture.md
@@ -57,170 +57,168 @@ You now have a lifecycle map for how Sweep executes issue-driven coding work.
Next: [Chapter 3: Repository Configuration and Governance](03-repository-configuration-and-governance.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `sweepai/api.py`
+### `sweepai/cli.py`
-The `terminate_thread` function in [`sweepai/api.py`](https://github.com/sweepai/sweep/blob/HEAD/sweepai/api.py) handles a key part of this chapter's functionality:
+The `get_event_type` function in [`sweepai/cli.py`](https://github.com/sweepai/sweep/blob/HEAD/sweepai/cli.py) handles a key part of this chapter's functionality:
```py
-def terminate_thread(thread):
- """Terminate a python threading.Thread."""
- try:
- if not thread.is_alive():
- return
-
- exc = ctypes.py_object(SystemExit)
- res = ctypes.pythonapi.PyThreadState_SetAsyncExc(
- ctypes.c_long(thread.ident), exc
+def get_event_type(event: Event | IssueEvent):
+ if isinstance(event, IssueEvent):
+ return "issues"
+ else:
+ return pascal_to_snake(event.type)[: -len("_event")]
+
+@app.command()
+def test():
+ cprint("Sweep AI is installed correctly and ready to go!", style="yellow")
+
+@app.command()
+def watch(
+ repo_name: str,
+ debug: bool = False,
+ record_events: bool = False,
+ max_events: int = 30,
+):
+ if not os.path.exists(config_path):
+ cprint(
+ f"\nConfiguration not found at {config_path}. Please run [green]'sweep init'[/green] to initialize the CLI.\n",
+ style="yellow",
)
- if res == 0:
- raise ValueError("Invalid thread ID")
- elif res != 1:
- # Call with exception set to 0 is needed to cleanup properly.
- ctypes.pythonapi.PyThreadState_SetAsyncExc(thread.ident, 0)
- raise SystemError("PyThreadState_SetAsyncExc failed")
- except Exception as e:
- logger.exception(f"Failed to terminate thread: {e}")
-
-
-# def delayed_kill(thread: threading.Thread, delay: int = 60 * 60):
-# time.sleep(delay)
-# terminate_thread(thread)
-
-
-def call_on_ticket(*args, **kwargs):
- global on_ticket_events
- key = f"{kwargs['repo_full_name']}-{kwargs['issue_number']}" # Full name, issue number as key
-
- # Use multithreading
+ raise ValueError(
+ "Configuration not found, please run 'sweep init' to initialize the CLI."
+ )
+ posthog_capture(
+ "sweep_watch_started",
+ {
+ "repo": repo_name,
+ "debug": debug,
```
This function is important because it defines how Sweep Tutorial: Issue-to-PR AI Coding Workflows on GitHub implements the patterns covered in this chapter.
-### `sweepai/api.py`
+### `sweepai/cli.py`
-The `call_on_ticket` function in [`sweepai/api.py`](https://github.com/sweepai/sweep/blob/HEAD/sweepai/api.py) handles a key part of this chapter's functionality:
+The `test` function in [`sweepai/cli.py`](https://github.com/sweepai/sweep/blob/HEAD/sweepai/cli.py) handles a key part of this chapter's functionality:
```py
-
-def call_on_ticket(*args, **kwargs):
- global on_ticket_events
- key = f"{kwargs['repo_full_name']}-{kwargs['issue_number']}" # Full name, issue number as key
-
- # Use multithreading
- # Check if a previous process exists for the same key, cancel it
- e = on_ticket_events.get(key, None)
- if e:
- logger.info(f"Found previous thread for key {key} and cancelling it")
- terminate_thread(e)
-
- thread = threading.Thread(target=run_on_ticket, args=args, kwargs=kwargs)
- on_ticket_events[key] = thread
- thread.start()
- global_threads.append(thread)
-
-def call_on_comment(
- *args, **kwargs
-): # TODO: if its a GHA delete all previous GHA and append to the end
- def worker():
- while not events[key].empty():
- task_args, task_kwargs = events[key].get()
- run_on_comment(*task_args, **task_kwargs)
-
- global events
- repo_full_name = kwargs["repo_full_name"]
- pr_id = kwargs["pr_number"]
- key = f"{repo_full_name}-{pr_id}" # Full name, comment number as key
-
- comment_type = kwargs["comment_type"]
+@app.command()
+def test():
+ cprint("Sweep AI is installed correctly and ready to go!", style="yellow")
+
+@app.command()
+def watch(
+ repo_name: str,
+ debug: bool = False,
+ record_events: bool = False,
+ max_events: int = 30,
+):
+ if not os.path.exists(config_path):
+ cprint(
+ f"\nConfiguration not found at {config_path}. Please run [green]'sweep init'[/green] to initialize the CLI.\n",
+ style="yellow",
+ )
+ raise ValueError(
+ "Configuration not found, please run 'sweep init' to initialize the CLI."
+ )
+ posthog_capture(
+ "sweep_watch_started",
+ {
+ "repo": repo_name,
+ "debug": debug,
+ "record_events": record_events,
+ "max_events": max_events,
+ },
+ )
+ GITHUB_PAT = os.environ.get("GITHUB_PAT", None)
+ if GITHUB_PAT is None:
+ raise ValueError("GITHUB_PAT environment variable must be set")
```
This function is important because it defines how Sweep Tutorial: Issue-to-PR AI Coding Workflows on GitHub implements the patterns covered in this chapter.
-### `sweepai/api.py`
+### `sweepai/cli.py`
-The `call_on_comment` function in [`sweepai/api.py`](https://github.com/sweepai/sweep/blob/HEAD/sweepai/api.py) handles a key part of this chapter's functionality:
+The `watch` function in [`sweepai/cli.py`](https://github.com/sweepai/sweep/blob/HEAD/sweepai/cli.py) handles a key part of this chapter's functionality:
```py
- global_threads.append(thread)
-
-def call_on_comment(
- *args, **kwargs
-): # TODO: if its a GHA delete all previous GHA and append to the end
- def worker():
- while not events[key].empty():
- task_args, task_kwargs = events[key].get()
- run_on_comment(*task_args, **task_kwargs)
-
- global events
- repo_full_name = kwargs["repo_full_name"]
- pr_id = kwargs["pr_number"]
- key = f"{repo_full_name}-{pr_id}" # Full name, comment number as key
-
- comment_type = kwargs["comment_type"]
- logger.info(f"Received comment type: {comment_type}")
-
- if key not in events:
- events[key] = SafePriorityQueue()
-
- events[key].put(0, (args, kwargs))
-
- # If a thread isn't running, start one
- if not any(
- thread.name == key and thread.is_alive() for thread in threading.enumerate()
- ):
- thread = threading.Thread(target=worker, name=key)
- thread.start()
- global_threads.append(thread)
-
-# add a review by sweep on the pr
+
+@app.command()
+def watch(
+ repo_name: str,
+ debug: bool = False,
+ record_events: bool = False,
+ max_events: int = 30,
+):
+ if not os.path.exists(config_path):
+ cprint(
+ f"\nConfiguration not found at {config_path}. Please run [green]'sweep init'[/green] to initialize the CLI.\n",
+ style="yellow",
+ )
+ raise ValueError(
+ "Configuration not found, please run 'sweep init' to initialize the CLI."
+ )
+ posthog_capture(
+ "sweep_watch_started",
+ {
+ "repo": repo_name,
+ "debug": debug,
+ "record_events": record_events,
+ "max_events": max_events,
+ },
+ )
+ GITHUB_PAT = os.environ.get("GITHUB_PAT", None)
+ if GITHUB_PAT is None:
+ raise ValueError("GITHUB_PAT environment variable must be set")
+ g = Github(os.environ["GITHUB_PAT"])
+ repo = g.get_repo(repo_name)
+ if debug:
+ logger.debug("Debug mode enabled")
```
This function is important because it defines how Sweep Tutorial: Issue-to-PR AI Coding Workflows on GitHub implements the patterns covered in this chapter.
-### `sweepai/api.py`
+### `sweepai/cli.py`
-The `call_review_pr` function in [`sweepai/api.py`](https://github.com/sweepai/sweep/blob/HEAD/sweepai/api.py) handles a key part of this chapter's functionality:
+The `init` function in [`sweepai/cli.py`](https://github.com/sweepai/sweep/blob/HEAD/sweepai/cli.py) handles a key part of this chapter's functionality:
```py
-
-# add a review by sweep on the pr
-def call_review_pr(*args, **kwargs):
- global review_pr_events
- key = f"{kwargs['repository'].full_name}-{kwargs['pr'].number}" # Full name, issue number as key
-
- # Use multithreading
- # Check if a previous process exists for the same key, cancel it
- e = review_pr_events.get(key, None)
- if e:
- logger.info(f"Found previous thread for key {key} and cancelling it")
- terminate_thread(e)
-
- thread = threading.Thread(target=run_review_pr, args=args, kwargs=kwargs)
- review_pr_events[key] = thread
- thread.start()
- global_threads.append(thread)
-
-
-@app.get("/health")
-def redirect_to_health():
- return health_check()
-
-
-@app.get("/", response_class=HTMLResponse)
-def home(request: Request):
- try:
- validate_license()
- license_expired = False
- except Exception as e:
- logger.warning(e)
- license_expired = True
+ if not os.path.exists(config_path):
+ cprint(
+ f"\nConfiguration not found at {config_path}. Please run [green]'sweep init'[/green] to initialize the CLI.\n",
+ style="yellow",
+ )
+ raise ValueError(
+ "Configuration not found, please run 'sweep init' to initialize the CLI."
+ )
+ posthog_capture(
+ "sweep_watch_started",
+ {
+ "repo": repo_name,
+ "debug": debug,
+ "record_events": record_events,
+ "max_events": max_events,
+ },
+ )
+ GITHUB_PAT = os.environ.get("GITHUB_PAT", None)
+ if GITHUB_PAT is None:
+ raise ValueError("GITHUB_PAT environment variable must be set")
+ g = Github(os.environ["GITHUB_PAT"])
+ repo = g.get_repo(repo_name)
+ if debug:
+ logger.debug("Debug mode enabled")
+
+ def stream_events(repo: Repository, timeout: int = 2, offset: int = 2 * 60):
+ processed_event_ids = set()
+ current_time = time.time() - offset
+ current_time = datetime.datetime.fromtimestamp(current_time)
+ local_tz = datetime.datetime.now(datetime.timezone.utc).astimezone().tzinfo
+
+ while True:
```
This function is important because it defines how Sweep Tutorial: Issue-to-PR AI Coding Workflows on GitHub implements the patterns covered in this chapter.
@@ -230,10 +228,10 @@ This function is important because it defines how Sweep Tutorial: Issue-to-PR AI
```mermaid
flowchart TD
- A[terminate_thread]
- B[call_on_ticket]
- C[call_on_comment]
- D[call_review_pr]
+ A[get_event_type]
+ B[test]
+ C[watch]
+ D[init]
A --> B
B --> C
C --> D
diff --git a/tutorials/sweep-tutorial/03-repository-configuration-and-governance.md b/tutorials/sweep-tutorial/03-repository-configuration-and-governance.md
index bad58438..569178c8 100644
--- a/tutorials/sweep-tutorial/03-repository-configuration-and-governance.md
+++ b/tutorials/sweep-tutorial/03-repository-configuration-and-governance.md
@@ -56,170 +56,168 @@ You now have a policy foundation for safer, more consistent Sweep behavior.
Next: [Chapter 4: Feedback Loops, Review Comments, and CI Repair](04-feedback-loops-review-comments-and-ci-repair.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `sweepai/api.py`
+### `sweepai/cli.py`
-The `redirect_to_health` function in [`sweepai/api.py`](https://github.com/sweepai/sweep/blob/HEAD/sweepai/api.py) handles a key part of this chapter's functionality:
+The `run` function in [`sweepai/cli.py`](https://github.com/sweepai/sweep/blob/HEAD/sweepai/cli.py) handles a key part of this chapter's functionality:
```py
-
-@app.get("/health")
-def redirect_to_health():
- return health_check()
-
-
-@app.get("/", response_class=HTMLResponse)
-def home(request: Request):
- try:
- validate_license()
- license_expired = False
- except Exception as e:
- logger.warning(e)
- license_expired = True
- return templates.TemplateResponse(
- name="index.html", context={"version": version, "request": request, "license_expired": license_expired}
+ if not os.path.exists(config_path):
+ cprint(
+ f"\nConfiguration not found at {config_path}. Please run [green]'sweep init'[/green] to initialize the CLI.\n",
+ style="yellow",
+ )
+ raise ValueError(
+ "Configuration not found, please run 'sweep init' to initialize the CLI."
+ )
+ posthog_capture(
+ "sweep_watch_started",
+ {
+ "repo": repo_name,
+ "debug": debug,
+ "record_events": record_events,
+ "max_events": max_events,
+ },
)
-
-
-@app.get("/ticket_progress/{tracking_id}")
-def progress(tracking_id: str = Path(...)):
- ticket_progress = TicketProgress.load(tracking_id)
- return ticket_progress.dict()
-
-
-def handle_github_webhook(event_payload):
- handle_event(event_payload.get("request"), event_payload.get("event"))
-
-
-def handle_request(request_dict, event=None):
- """So it can be exported to the listen endpoint."""
- with logger.contextualize(tracking_id="main", env=ENV):
+ GITHUB_PAT = os.environ.get("GITHUB_PAT", None)
+ if GITHUB_PAT is None:
+ raise ValueError("GITHUB_PAT environment variable must be set")
+ g = Github(os.environ["GITHUB_PAT"])
+ repo = g.get_repo(repo_name)
+ if debug:
+ logger.debug("Debug mode enabled")
+
+ def stream_events(repo: Repository, timeout: int = 2, offset: int = 2 * 60):
+ processed_event_ids = set()
+ current_time = time.time() - offset
+ current_time = datetime.datetime.fromtimestamp(current_time)
+ local_tz = datetime.datetime.now(datetime.timezone.utc).astimezone().tzinfo
+
+ while True:
```
This function is important because it defines how Sweep Tutorial: Issue-to-PR AI Coding Workflows on GitHub implements the patterns covered in this chapter.
-### `sweepai/api.py`
+### `sweepai/cli.py`
-The `home` function in [`sweepai/api.py`](https://github.com/sweepai/sweep/blob/HEAD/sweepai/api.py) handles a key part of this chapter's functionality:
+The `main` function in [`sweepai/cli.py`](https://github.com/sweepai/sweep/blob/HEAD/sweepai/cli.py) handles a key part of this chapter's functionality:
```py
-
-@app.get("/", response_class=HTMLResponse)
-def home(request: Request):
- try:
- validate_license()
- license_expired = False
- except Exception as e:
- logger.warning(e)
- license_expired = True
- return templates.TemplateResponse(
- name="index.html", context={"version": version, "request": request, "license_expired": license_expired}
+ return handle_request(payload, get_event_type(event))
+
+ def main():
+ cprint(
+ f"\n[bold black on white] Starting server, listening to events from {repo_name}... [/bold black on white]\n",
+ )
+ cprint(
+ f"To create a PR, please create an issue at https://github.com/{repo_name}/issues with a title prefixed with 'Sweep:' or label an existing issue with 'sweep'. The events will be logged here, but there may be a brief delay.\n"
+ )
+ for event in stream_events(repo):
+ handle_event(event)
+
+ if __name__ == "__main__":
+ main()
+
+
+@app.command()
+def init(override: bool = False):
+ # TODO: Fix telemetry
+ if not override:
+ if os.path.exists(config_path):
+ with open(config_path, "r") as f:
+ config = json.load(f)
+ if "OPENAI_API_KEY" in config and "ANTHROPIC_API_KEY" in config and "GITHUB_PAT" in config:
+ override = typer.confirm(
+ f"\nConfiguration already exists at {config_path}. Override?",
+ default=False,
+ abort=True,
+ )
+ cprint(
+ "\n[bold black on white] Initializing Sweep CLI... [/bold black on white]\n",
)
+```
+This function is important because it defines how Sweep Tutorial: Issue-to-PR AI Coding Workflows on GitHub implements the patterns covered in this chapter.
-@app.get("/ticket_progress/{tracking_id}")
-def progress(tracking_id: str = Path(...)):
- ticket_progress = TicketProgress.load(tracking_id)
- return ticket_progress.dict()
-
-
-def handle_github_webhook(event_payload):
- handle_event(event_payload.get("request"), event_payload.get("event"))
-
+### `sweepai/api.py`
-def handle_request(request_dict, event=None):
- """So it can be exported to the listen endpoint."""
- with logger.contextualize(tracking_id="main", env=ENV):
- action = request_dict.get("action")
+The `run_on_ticket` function in [`sweepai/api.py`](https://github.com/sweepai/sweep/blob/HEAD/sweepai/api.py) handles a key part of this chapter's functionality:
- try:
- handle_github_webhook(
- {
+```py
+logger.bind(application="webhook")
+
+def run_on_ticket(*args, **kwargs):
+ tracking_id = get_hash()
+ with logger.contextualize(
+ **kwargs,
+ name="ticket_" + kwargs["username"],
+ tracking_id=tracking_id,
+ ):
+ return on_ticket(*args, **kwargs, tracking_id=tracking_id)
+
+
+def run_on_comment(*args, **kwargs):
+ tracking_id = get_hash()
+ with logger.contextualize(
+ **kwargs,
+ name="comment_" + kwargs["username"],
+ tracking_id=tracking_id,
+ ):
+ on_comment(*args, **kwargs, tracking_id=tracking_id)
+
+def run_review_pr(*args, **kwargs):
+ tracking_id = get_hash()
+ with logger.contextualize(
+ **kwargs,
+ name="review_" + kwargs["username"],
+ tracking_id=tracking_id,
+ ):
+ review_pr(*args, **kwargs, tracking_id=tracking_id)
+
+
+def run_on_button_click(*args, **kwargs):
```
This function is important because it defines how Sweep Tutorial: Issue-to-PR AI Coding Workflows on GitHub implements the patterns covered in this chapter.
### `sweepai/api.py`
-The `progress` function in [`sweepai/api.py`](https://github.com/sweepai/sweep/blob/HEAD/sweepai/api.py) handles a key part of this chapter's functionality:
+The `run_on_comment` function in [`sweepai/api.py`](https://github.com/sweepai/sweep/blob/HEAD/sweepai/api.py) handles a key part of this chapter's functionality:
```py
-from sweepai.utils.github_utils import CURRENT_USERNAME, get_github_client
-from sweepai.utils.hash import verify_signature
-from sweepai.utils.progress import TicketProgress
-from sweepai.utils.safe_pqueue import SafePriorityQueue
-from sweepai.utils.str_utils import BOT_SUFFIX, get_hash
-from sweepai.utils.validate_license import validate_license
-from sweepai.web.events import (
- CheckRunCompleted,
- CommentCreatedRequest,
- IssueCommentRequest,
- IssueRequest,
- PREdited,
- PRLabeledRequest,
- PRRequest,
-)
-from sweepai.web.health import health_check
-import sentry_sdk
-from sentry_sdk import set_user
-
-version = time.strftime("%y.%m.%d.%H")
-
-if SENTRY_URL:
- sentry_sdk.init(
- dsn=SENTRY_URL,
- traces_sample_rate=1.0,
- profiles_sample_rate=1.0,
- release=version
- )
-app = FastAPI()
-app.mount("/chat", chat_app)
-```
+def run_on_comment(*args, **kwargs):
+ tracking_id = get_hash()
+ with logger.contextualize(
+ **kwargs,
+ name="comment_" + kwargs["username"],
+ tracking_id=tracking_id,
+ ):
+ on_comment(*args, **kwargs, tracking_id=tracking_id)
-This function is important because it defines how Sweep Tutorial: Issue-to-PR AI Coding Workflows on GitHub implements the patterns covered in this chapter.
+def run_review_pr(*args, **kwargs):
+ tracking_id = get_hash()
+ with logger.contextualize(
+ **kwargs,
+ name="review_" + kwargs["username"],
+ tracking_id=tracking_id,
+ ):
+ review_pr(*args, **kwargs, tracking_id=tracking_id)
-### `sweepai/api.py`
-The `handle_github_webhook` function in [`sweepai/api.py`](https://github.com/sweepai/sweep/blob/HEAD/sweepai/api.py) handles a key part of this chapter's functionality:
-
-```py
+def run_on_button_click(*args, **kwargs):
+ thread = threading.Thread(target=handle_button_click, args=args, kwargs=kwargs)
+ thread.start()
+ global_threads.append(thread)
-def handle_github_webhook(event_payload):
- handle_event(event_payload.get("request"), event_payload.get("event"))
-
-
-def handle_request(request_dict, event=None):
- """So it can be exported to the listen endpoint."""
- with logger.contextualize(tracking_id="main", env=ENV):
- action = request_dict.get("action")
-
- try:
- handle_github_webhook(
- {
- "request": request_dict,
- "event": event,
- }
- )
- except Exception as e:
- logger.exception(str(e))
- logger.info(f"Done handling {event}, {action}")
- return {"success": True}
-
-
-# @app.post("/")
-async def validate_signature(
- request: Request,
- x_hub_signature: Optional[str] = Header(None, alias="X-Hub-Signature-256")
-):
- payload_body = await request.body()
- if not verify_signature(payload_body=payload_body, signature_header=x_hub_signature):
- raise HTTPException(status_code=403, detail="Request signatures didn't match!")
+def terminate_thread(thread):
+ """Terminate a python threading.Thread."""
+ try:
+ if not thread.is_alive():
+ return
```
This function is important because it defines how Sweep Tutorial: Issue-to-PR AI Coding Workflows on GitHub implements the patterns covered in this chapter.
@@ -229,10 +227,10 @@ This function is important because it defines how Sweep Tutorial: Issue-to-PR AI
```mermaid
flowchart TD
- A[redirect_to_health]
- B[home]
- C[progress]
- D[handle_github_webhook]
+ A[run]
+ B[main]
+ C[run_on_ticket]
+ D[run_on_comment]
A --> B
B --> C
C --> D
diff --git a/tutorials/sweep-tutorial/04-feedback-loops-review-comments-and-ci-repair.md b/tutorials/sweep-tutorial/04-feedback-loops-review-comments-and-ci-repair.md
index c8373869..96fc2022 100644
--- a/tutorials/sweep-tutorial/04-feedback-loops-review-comments-and-ci-repair.md
+++ b/tutorials/sweep-tutorial/04-feedback-loops-review-comments-and-ci-repair.md
@@ -44,170 +44,168 @@ You now know how to turn generated PRs into high-quality merge candidates throug
Next: [Chapter 5: CLI and Self-Hosted Deployment](05-cli-and-self-hosted-deployment.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `sweepai/api.py`
-The `handle_request` function in [`sweepai/api.py`](https://github.com/sweepai/sweep/blob/HEAD/sweepai/api.py) handles a key part of this chapter's functionality:
+The `run_review_pr` function in [`sweepai/api.py`](https://github.com/sweepai/sweep/blob/HEAD/sweepai/api.py) handles a key part of this chapter's functionality:
```py
+ on_comment(*args, **kwargs, tracking_id=tracking_id)
+
+def run_review_pr(*args, **kwargs):
+ tracking_id = get_hash()
+ with logger.contextualize(
+ **kwargs,
+ name="review_" + kwargs["username"],
+ tracking_id=tracking_id,
+ ):
+ review_pr(*args, **kwargs, tracking_id=tracking_id)
-def handle_request(request_dict, event=None):
- """So it can be exported to the listen endpoint."""
- with logger.contextualize(tracking_id="main", env=ENV):
- action = request_dict.get("action")
-
- try:
- handle_github_webhook(
- {
- "request": request_dict,
- "event": event,
- }
- )
- except Exception as e:
- logger.exception(str(e))
- logger.info(f"Done handling {event}, {action}")
- return {"success": True}
-
-
-# @app.post("/")
-async def validate_signature(
- request: Request,
- x_hub_signature: Optional[str] = Header(None, alias="X-Hub-Signature-256")
-):
- payload_body = await request.body()
- if not verify_signature(payload_body=payload_body, signature_header=x_hub_signature):
- raise HTTPException(status_code=403, detail="Request signatures didn't match!")
-
-@app.post("/", dependencies=[Depends(validate_signature)])
-def webhook(
- request_dict: dict = Body(...),
+def run_on_button_click(*args, **kwargs):
+ thread = threading.Thread(target=handle_button_click, args=args, kwargs=kwargs)
+ thread.start()
+ global_threads.append(thread)
+
+
+def terminate_thread(thread):
+ """Terminate a python threading.Thread."""
+ try:
+ if not thread.is_alive():
+ return
+
+ exc = ctypes.py_object(SystemExit)
+ res = ctypes.pythonapi.PyThreadState_SetAsyncExc(
+ ctypes.c_long(thread.ident), exc
+ )
+ if res == 0:
+ raise ValueError("Invalid thread ID")
+ elif res != 1:
+ # Call with exception set to 0 is needed to cleanup properly.
```
This function is important because it defines how Sweep Tutorial: Issue-to-PR AI Coding Workflows on GitHub implements the patterns covered in this chapter.
### `sweepai/api.py`
-The `validate_signature` function in [`sweepai/api.py`](https://github.com/sweepai/sweep/blob/HEAD/sweepai/api.py) handles a key part of this chapter's functionality:
+The `run_on_button_click` function in [`sweepai/api.py`](https://github.com/sweepai/sweep/blob/HEAD/sweepai/api.py) handles a key part of this chapter's functionality:
```py
-# @app.post("/")
-async def validate_signature(
- request: Request,
- x_hub_signature: Optional[str] = Header(None, alias="X-Hub-Signature-256")
-):
- payload_body = await request.body()
- if not verify_signature(payload_body=payload_body, signature_header=x_hub_signature):
- raise HTTPException(status_code=403, detail="Request signatures didn't match!")
-
-@app.post("/", dependencies=[Depends(validate_signature)])
-def webhook(
- request_dict: dict = Body(...),
- x_github_event: Optional[str] = Header(None, alias="X-GitHub-Event"),
-):
- """Handle a webhook request from GitHub"""
- with logger.contextualize(tracking_id="main", env=ENV):
- action = request_dict.get("action", None)
-
- logger.info(f"Received event: {x_github_event}, {action}")
- return handle_request(request_dict, event=x_github_event)
-
-@app.post("/jira")
-def jira_webhook(
- request_dict: dict = Body(...),
-) -> None:
- def call_jira_ticket(*args, **kwargs):
- thread = threading.Thread(target=handle_jira_ticket, args=args, kwargs=kwargs)
- thread.start()
- call_jira_ticket(event=request_dict)
-
-# Set up cronjob for this
+
+def run_on_button_click(*args, **kwargs):
+ thread = threading.Thread(target=handle_button_click, args=args, kwargs=kwargs)
+ thread.start()
+ global_threads.append(thread)
+
+
+def terminate_thread(thread):
+ """Terminate a python threading.Thread."""
+ try:
+ if not thread.is_alive():
+ return
+
+ exc = ctypes.py_object(SystemExit)
+ res = ctypes.pythonapi.PyThreadState_SetAsyncExc(
+ ctypes.c_long(thread.ident), exc
+ )
+ if res == 0:
+ raise ValueError("Invalid thread ID")
+ elif res != 1:
+ # Call with exception set to 0 is needed to cleanup properly.
+ ctypes.pythonapi.PyThreadState_SetAsyncExc(thread.ident, 0)
+ raise SystemError("PyThreadState_SetAsyncExc failed")
+ except Exception as e:
+ logger.exception(f"Failed to terminate thread: {e}")
+
+
+# def delayed_kill(thread: threading.Thread, delay: int = 60 * 60):
+# time.sleep(delay)
+# terminate_thread(thread)
+
```
This function is important because it defines how Sweep Tutorial: Issue-to-PR AI Coding Workflows on GitHub implements the patterns covered in this chapter.
### `sweepai/api.py`
-The `webhook` function in [`sweepai/api.py`](https://github.com/sweepai/sweep/blob/HEAD/sweepai/api.py) handles a key part of this chapter's functionality:
+The `terminate_thread` function in [`sweepai/api.py`](https://github.com/sweepai/sweep/blob/HEAD/sweepai/api.py) handles a key part of this chapter's functionality:
```py
-templates = Jinja2Templates(directory="sweepai/web")
-logger.bind(application="webhook")
-def run_on_ticket(*args, **kwargs):
- tracking_id = get_hash()
- with logger.contextualize(
- **kwargs,
- name="ticket_" + kwargs["username"],
- tracking_id=tracking_id,
- ):
- return on_ticket(*args, **kwargs, tracking_id=tracking_id)
+def terminate_thread(thread):
+ """Terminate a python threading.Thread."""
+ try:
+ if not thread.is_alive():
+ return
+ exc = ctypes.py_object(SystemExit)
+ res = ctypes.pythonapi.PyThreadState_SetAsyncExc(
+ ctypes.c_long(thread.ident), exc
+ )
+ if res == 0:
+ raise ValueError("Invalid thread ID")
+ elif res != 1:
+ # Call with exception set to 0 is needed to cleanup properly.
+ ctypes.pythonapi.PyThreadState_SetAsyncExc(thread.ident, 0)
+ raise SystemError("PyThreadState_SetAsyncExc failed")
+ except Exception as e:
+ logger.exception(f"Failed to terminate thread: {e}")
-def run_on_comment(*args, **kwargs):
- tracking_id = get_hash()
- with logger.contextualize(
- **kwargs,
- name="comment_" + kwargs["username"],
- tracking_id=tracking_id,
- ):
- on_comment(*args, **kwargs, tracking_id=tracking_id)
-def run_review_pr(*args, **kwargs):
- tracking_id = get_hash()
- with logger.contextualize(
- **kwargs,
- name="review_" + kwargs["username"],
- tracking_id=tracking_id,
- ):
- review_pr(*args, **kwargs, tracking_id=tracking_id)
+# def delayed_kill(thread: threading.Thread, delay: int = 60 * 60):
+# time.sleep(delay)
+# terminate_thread(thread)
+
+def call_on_ticket(*args, **kwargs):
+ global on_ticket_events
+ key = f"{kwargs['repo_full_name']}-{kwargs['issue_number']}" # Full name, issue number as key
+
+ # Use multithreading
```
This function is important because it defines how Sweep Tutorial: Issue-to-PR AI Coding Workflows on GitHub implements the patterns covered in this chapter.
### `sweepai/api.py`
-The `jira_webhook` function in [`sweepai/api.py`](https://github.com/sweepai/sweep/blob/HEAD/sweepai/api.py) handles a key part of this chapter's functionality:
+The `call_on_ticket` function in [`sweepai/api.py`](https://github.com/sweepai/sweep/blob/HEAD/sweepai/api.py) handles a key part of this chapter's functionality:
```py
-@app.post("/jira")
-def jira_webhook(
- request_dict: dict = Body(...),
-) -> None:
- def call_jira_ticket(*args, **kwargs):
- thread = threading.Thread(target=handle_jira_ticket, args=args, kwargs=kwargs)
- thread.start()
- call_jira_ticket(event=request_dict)
-
-# Set up cronjob for this
-@app.get("/update_sweep_prs_v2")
-def update_sweep_prs_v2(repo_full_name: str, installation_id: int):
- # Get a Github client
- _, g = get_github_client(installation_id)
-
- # Get the repository
- repo = g.get_repo(repo_full_name)
- config = SweepConfig.get_config(repo)
-
- try:
- branch_ttl = int(config.get("branch_ttl", 7))
- except Exception:
- branch_ttl = 7
- branch_ttl = max(branch_ttl, 1)
-
- # Get all open pull requests created by Sweep
- pulls = repo.get_pulls(
- state="open", head="sweep", sort="updated", direction="desc"
- )[:5]
- # For each pull request, attempt to merge the changes from the default branch into the pull request branch
+def call_on_ticket(*args, **kwargs):
+ global on_ticket_events
+ key = f"{kwargs['repo_full_name']}-{kwargs['issue_number']}" # Full name, issue number as key
+
+ # Use multithreading
+ # Check if a previous process exists for the same key, cancel it
+ e = on_ticket_events.get(key, None)
+ if e:
+ logger.info(f"Found previous thread for key {key} and cancelling it")
+ terminate_thread(e)
+
+ thread = threading.Thread(target=run_on_ticket, args=args, kwargs=kwargs)
+ on_ticket_events[key] = thread
+ thread.start()
+ global_threads.append(thread)
+
+def call_on_comment(
+ *args, **kwargs
+): # TODO: if its a GHA delete all previous GHA and append to the end
+ def worker():
+ while not events[key].empty():
+ task_args, task_kwargs = events[key].get()
+ run_on_comment(*task_args, **task_kwargs)
+
+ global events
+ repo_full_name = kwargs["repo_full_name"]
+ pr_id = kwargs["pr_number"]
+ key = f"{repo_full_name}-{pr_id}" # Full name, comment number as key
+
+ comment_type = kwargs["comment_type"]
```
This function is important because it defines how Sweep Tutorial: Issue-to-PR AI Coding Workflows on GitHub implements the patterns covered in this chapter.
@@ -217,10 +215,10 @@ This function is important because it defines how Sweep Tutorial: Issue-to-PR AI
```mermaid
flowchart TD
- A[handle_request]
- B[validate_signature]
- C[webhook]
- D[jira_webhook]
+ A[run_review_pr]
+ B[run_on_button_click]
+ C[terminate_thread]
+ D[call_on_ticket]
A --> B
B --> C
C --> D
diff --git a/tutorials/sweep-tutorial/05-cli-and-self-hosted-deployment.md b/tutorials/sweep-tutorial/05-cli-and-self-hosted-deployment.md
index 854868f2..86618c04 100644
--- a/tutorials/sweep-tutorial/05-cli-and-self-hosted-deployment.md
+++ b/tutorials/sweep-tutorial/05-cli-and-self-hosted-deployment.md
@@ -53,98 +53,156 @@ You now have a mode-selection model for operating Sweep in different risk and co
Next: [Chapter 6: Search, Planning, and Execution Patterns](06-search-planning-and-execution-patterns.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `sweepai/api.py`
-The `update_sweep_prs_v2` function in [`sweepai/api.py`](https://github.com/sweepai/sweep/blob/HEAD/sweepai/api.py) handles a key part of this chapter's functionality:
+The `call_on_comment` function in [`sweepai/api.py`](https://github.com/sweepai/sweep/blob/HEAD/sweepai/api.py) handles a key part of this chapter's functionality:
```py
+ global_threads.append(thread)
+
+def call_on_comment(
+ *args, **kwargs
+): # TODO: if its a GHA delete all previous GHA and append to the end
+ def worker():
+ while not events[key].empty():
+ task_args, task_kwargs = events[key].get()
+ run_on_comment(*task_args, **task_kwargs)
+
+ global events
+ repo_full_name = kwargs["repo_full_name"]
+ pr_id = kwargs["pr_number"]
+ key = f"{repo_full_name}-{pr_id}" # Full name, comment number as key
+
+ comment_type = kwargs["comment_type"]
+ logger.info(f"Received comment type: {comment_type}")
+
+ if key not in events:
+ events[key] = SafePriorityQueue()
+
+ events[key].put(0, (args, kwargs))
+
+ # If a thread isn't running, start one
+ if not any(
+ thread.name == key and thread.is_alive() for thread in threading.enumerate()
+ ):
+ thread = threading.Thread(target=worker, name=key)
+ thread.start()
+ global_threads.append(thread)
+
+# add a review by sweep on the pr
+```
-# Set up cronjob for this
-@app.get("/update_sweep_prs_v2")
-def update_sweep_prs_v2(repo_full_name: str, installation_id: int):
- # Get a Github client
- _, g = get_github_client(installation_id)
+This function is important because it defines how Sweep Tutorial: Issue-to-PR AI Coding Workflows on GitHub implements the patterns covered in this chapter.
- # Get the repository
- repo = g.get_repo(repo_full_name)
- config = SweepConfig.get_config(repo)
+### `sweepai/api.py`
- try:
- branch_ttl = int(config.get("branch_ttl", 7))
- except Exception:
- branch_ttl = 7
- branch_ttl = max(branch_ttl, 1)
+The `call_review_pr` function in [`sweepai/api.py`](https://github.com/sweepai/sweep/blob/HEAD/sweepai/api.py) handles a key part of this chapter's functionality:
+
+```py
+
+# add a review by sweep on the pr
+def call_review_pr(*args, **kwargs):
+ global review_pr_events
+ key = f"{kwargs['repository'].full_name}-{kwargs['pr'].number}" # Full name, issue number as key
+
+ # Use multithreading
+ # Check if a previous process exists for the same key, cancel it
+ e = review_pr_events.get(key, None)
+ if e:
+ logger.info(f"Found previous thread for key {key} and cancelling it")
+ terminate_thread(e)
+
+ thread = threading.Thread(target=run_review_pr, args=args, kwargs=kwargs)
+ review_pr_events[key] = thread
+ thread.start()
+ global_threads.append(thread)
- # Get all open pull requests created by Sweep
- pulls = repo.get_pulls(
- state="open", head="sweep", sort="updated", direction="desc"
- )[:5]
- # For each pull request, attempt to merge the changes from the default branch into the pull request branch
+@app.get("/health")
+def redirect_to_health():
+ return health_check()
+
+
+@app.get("/", response_class=HTMLResponse)
+def home(request: Request):
try:
- for pr in pulls:
- try:
- # make sure it's a sweep ticket
- feature_branch = pr.head.ref
- if not feature_branch.startswith(
- "sweep/"
- ) and not feature_branch.startswith("sweep_"):
- continue
+ validate_license()
+ license_expired = False
+ except Exception as e:
+ logger.warning(e)
+ license_expired = True
```
This function is important because it defines how Sweep Tutorial: Issue-to-PR AI Coding Workflows on GitHub implements the patterns covered in this chapter.
### `sweepai/api.py`
-The `should_handle_comment` function in [`sweepai/api.py`](https://github.com/sweepai/sweep/blob/HEAD/sweepai/api.py) handles a key part of this chapter's functionality:
+The `redirect_to_health` function in [`sweepai/api.py`](https://github.com/sweepai/sweep/blob/HEAD/sweepai/api.py) handles a key part of this chapter's functionality:
```py
- logger.warning("Failed to update sweep PRs")
-
-def should_handle_comment(request: CommentCreatedRequest | IssueCommentRequest):
- comment = request.comment.body
- return (
- (
- comment.lower().startswith("sweep:") # we will handle all comments (with or without label) that start with "sweep:"
- )
- and request.comment.user.type == "User" # ensure it's a user comment
- and request.comment.user.login not in BLACKLISTED_USERS # ensure it's not a blacklisted user
- and BOT_SUFFIX not in comment # we don't handle bot commnents
+
+@app.get("/health")
+def redirect_to_health():
+ return health_check()
+
+
+@app.get("/", response_class=HTMLResponse)
+def home(request: Request):
+ try:
+ validate_license()
+ license_expired = False
+ except Exception as e:
+ logger.warning(e)
+ license_expired = True
+ return templates.TemplateResponse(
+ name="index.html", context={"version": version, "request": request, "license_expired": license_expired}
)
-def handle_event(request_dict, event):
- action = request_dict.get("action")
-
- username = request_dict.get("sender", {}).get("login")
- if username:
- set_user({"username": username})
- if repo_full_name := request_dict.get("repository", {}).get("full_name"):
- if repo_full_name in DISABLED_REPOS:
- logger.warning(f"Repo {repo_full_name} is disabled")
- return {"success": False, "error_message": "Repo is disabled"}
+@app.get("/ticket_progress/{tracking_id}")
+def progress(tracking_id: str = Path(...)):
+ ticket_progress = TicketProgress.load(tracking_id)
+ return ticket_progress.dict()
+
+
+def handle_github_webhook(event_payload):
+ handle_event(event_payload.get("request"), event_payload.get("event"))
+
+def handle_request(request_dict, event=None):
+ """So it can be exported to the listen endpoint."""
with logger.contextualize(tracking_id="main", env=ENV):
- match event, action:
- case "check_run", "completed":
- request = CheckRunCompleted(**request_dict)
- _, g = get_github_client(request.installation.id)
- repo = g.get_repo(request.repository.full_name)
- pull_requests = request.check_run.pull_requests
```
This function is important because it defines how Sweep Tutorial: Issue-to-PR AI Coding Workflows on GitHub implements the patterns covered in this chapter.
### `sweepai/api.py`
-The `handle_event` function in [`sweepai/api.py`](https://github.com/sweepai/sweep/blob/HEAD/sweepai/api.py) handles a key part of this chapter's functionality:
+The `home` function in [`sweepai/api.py`](https://github.com/sweepai/sweep/blob/HEAD/sweepai/api.py) handles a key part of this chapter's functionality:
```py
+@app.get("/", response_class=HTMLResponse)
+def home(request: Request):
+ try:
+ validate_license()
+ license_expired = False
+ except Exception as e:
+ logger.warning(e)
+ license_expired = True
+ return templates.TemplateResponse(
+ name="index.html", context={"version": version, "request": request, "license_expired": license_expired}
+ )
+
+
+@app.get("/ticket_progress/{tracking_id}")
+def progress(tracking_id: str = Path(...)):
+ ticket_progress = TicketProgress.load(tracking_id)
+ return ticket_progress.dict()
+
+
def handle_github_webhook(event_payload):
handle_event(event_payload.get("request"), event_payload.get("event"))
@@ -157,66 +215,6 @@ def handle_request(request_dict, event=None):
try:
handle_github_webhook(
{
- "request": request_dict,
- "event": event,
- }
- )
- except Exception as e:
- logger.exception(str(e))
- logger.info(f"Done handling {event}, {action}")
- return {"success": True}
-
-
-# @app.post("/")
-async def validate_signature(
- request: Request,
- x_hub_signature: Optional[str] = Header(None, alias="X-Hub-Signature-256")
-):
- payload_body = await request.body()
- if not verify_signature(payload_body=payload_body, signature_header=x_hub_signature):
- raise HTTPException(status_code=403, detail="Request signatures didn't match!")
-
-```
-
-This function is important because it defines how Sweep Tutorial: Issue-to-PR AI Coding Workflows on GitHub implements the patterns covered in this chapter.
-
-### `sweepai/cli.py`
-
-The `posthog_capture` function in [`sweepai/cli.py`](https://github.com/sweepai/sweep/blob/HEAD/sweepai/cli.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def posthog_capture(event_name, properties, *args, **kwargs):
- POSTHOG_DISTINCT_ID = os.environ.get("POSTHOG_DISTINCT_ID")
- if POSTHOG_DISTINCT_ID:
- posthog.capture(POSTHOG_DISTINCT_ID, event_name, properties, *args, **kwargs)
-
-
-def load_config():
- if os.path.exists(config_path):
- cprint(f"\nLoading configuration from {config_path}", style="yellow")
- with open(config_path, "r") as f:
- config = json.load(f)
- for key, value in config.items():
- try:
- os.environ[key] = value
- except Exception as e:
- cprint(f"Error loading config: {e}, skipping.", style="yellow")
- os.environ["POSTHOG_DISTINCT_ID"] = str(os.environ.get("POSTHOG_DISTINCT_ID", ""))
- # Should contain:
- # GITHUB_PAT
- # OPENAI_API_KEY
- # ANTHROPIC_API_KEY
- # VOYAGE_API_KEY
- # POSTHOG_DISTINCT_ID
-
-
-def fetch_issue_request(issue_url: str, __version__: str = "0"):
- (
- protocol_name,
- _,
- _base_url,
```
This function is important because it defines how Sweep Tutorial: Issue-to-PR AI Coding Workflows on GitHub implements the patterns covered in this chapter.
@@ -226,10 +224,10 @@ This function is important because it defines how Sweep Tutorial: Issue-to-PR AI
```mermaid
flowchart TD
- A[update_sweep_prs_v2]
- B[should_handle_comment]
- C[handle_event]
- D[posthog_capture]
+ A[call_on_comment]
+ B[call_review_pr]
+ C[redirect_to_health]
+ D[home]
A --> B
B --> C
C --> D
diff --git a/tutorials/sweep-tutorial/06-search-planning-and-execution-patterns.md b/tutorials/sweep-tutorial/06-search-planning-and-execution-patterns.md
index f70af7c4..260e0bd5 100644
--- a/tutorials/sweep-tutorial/06-search-planning-and-execution-patterns.md
+++ b/tutorials/sweep-tutorial/06-search-planning-and-execution-patterns.md
@@ -47,170 +47,168 @@ You now understand the core behavioral pattern that drives Sweep output quality.
Next: [Chapter 7: Limitations, Risk Controls, and Safe Scope](07-limitations-risk-controls-and-safe-scope.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `sweepai/cli.py`
+### `sweepai/api.py`
-The `load_config` function in [`sweepai/cli.py`](https://github.com/sweepai/sweep/blob/HEAD/sweepai/cli.py) handles a key part of this chapter's functionality:
+The `progress` function in [`sweepai/api.py`](https://github.com/sweepai/sweep/blob/HEAD/sweepai/api.py) handles a key part of this chapter's functionality:
```py
-
-
-def load_config():
- if os.path.exists(config_path):
- cprint(f"\nLoading configuration from {config_path}", style="yellow")
- with open(config_path, "r") as f:
- config = json.load(f)
- for key, value in config.items():
- try:
- os.environ[key] = value
- except Exception as e:
- cprint(f"Error loading config: {e}, skipping.", style="yellow")
- os.environ["POSTHOG_DISTINCT_ID"] = str(os.environ.get("POSTHOG_DISTINCT_ID", ""))
- # Should contain:
- # GITHUB_PAT
- # OPENAI_API_KEY
- # ANTHROPIC_API_KEY
- # VOYAGE_API_KEY
- # POSTHOG_DISTINCT_ID
-
-
-def fetch_issue_request(issue_url: str, __version__: str = "0"):
- (
- protocol_name,
- _,
- _base_url,
- org_name,
- repo_name,
- _issues,
- issue_number,
- ) = issue_url.split("/")
- cprint("Fetching installation ID...")
+from sweepai.utils.github_utils import CURRENT_USERNAME, get_github_client
+from sweepai.utils.hash import verify_signature
+from sweepai.utils.progress import TicketProgress
+from sweepai.utils.safe_pqueue import SafePriorityQueue
+from sweepai.utils.str_utils import BOT_SUFFIX, get_hash
+from sweepai.utils.validate_license import validate_license
+from sweepai.web.events import (
+ CheckRunCompleted,
+ CommentCreatedRequest,
+ IssueCommentRequest,
+ IssueRequest,
+ PREdited,
+ PRLabeledRequest,
+ PRRequest,
+)
+from sweepai.web.health import health_check
+import sentry_sdk
+from sentry_sdk import set_user
+
+version = time.strftime("%y.%m.%d.%H")
+
+if SENTRY_URL:
+ sentry_sdk.init(
+ dsn=SENTRY_URL,
+ traces_sample_rate=1.0,
+ profiles_sample_rate=1.0,
+ release=version
+ )
+
+app = FastAPI()
+
+app.mount("/chat", chat_app)
```
This function is important because it defines how Sweep Tutorial: Issue-to-PR AI Coding Workflows on GitHub implements the patterns covered in this chapter.
-### `sweepai/cli.py`
+### `sweepai/api.py`
-The `fetch_issue_request` function in [`sweepai/cli.py`](https://github.com/sweepai/sweep/blob/HEAD/sweepai/cli.py) handles a key part of this chapter's functionality:
+The `handle_github_webhook` function in [`sweepai/api.py`](https://github.com/sweepai/sweep/blob/HEAD/sweepai/api.py) handles a key part of this chapter's functionality:
```py
-def fetch_issue_request(issue_url: str, __version__: str = "0"):
- (
- protocol_name,
- _,
- _base_url,
- org_name,
- repo_name,
- _issues,
- issue_number,
- ) = issue_url.split("/")
- cprint("Fetching installation ID...")
- installation_id = -1
- cprint("Fetching access token...")
- _token, g = get_github_client(installation_id)
- g: Github = g
- cprint("Fetching repo...")
- issue = g.get_repo(f"{org_name}/{repo_name}").get_issue(int(issue_number))
-
- issue_request = IssueRequest(
- action="labeled",
- issue=IssueRequest.Issue(
- title=issue.title,
- number=int(issue_number),
- html_url=issue_url,
- user=IssueRequest.Issue.User(
- login=issue.user.login,
- type="User",
- ),
- body=issue.body,
- labels=[
-```
+def handle_github_webhook(event_payload):
+ handle_event(event_payload.get("request"), event_payload.get("event"))
-This function is important because it defines how Sweep Tutorial: Issue-to-PR AI Coding Workflows on GitHub implements the patterns covered in this chapter.
-### `sweepai/cli.py`
+def handle_request(request_dict, event=None):
+ """So it can be exported to the listen endpoint."""
+ with logger.contextualize(tracking_id="main", env=ENV):
+ action = request_dict.get("action")
-The `pascal_to_snake` function in [`sweepai/cli.py`](https://github.com/sweepai/sweep/blob/HEAD/sweepai/cli.py) handles a key part of this chapter's functionality:
+ try:
+ handle_github_webhook(
+ {
+ "request": request_dict,
+ "event": event,
+ }
+ )
+ except Exception as e:
+ logger.exception(str(e))
+ logger.info(f"Done handling {event}, {action}")
+ return {"success": True}
-```py
+# @app.post("/")
+async def validate_signature(
+ request: Request,
+ x_hub_signature: Optional[str] = Header(None, alias="X-Hub-Signature-256")
+):
+ payload_body = await request.body()
+ if not verify_signature(payload_body=payload_body, signature_header=x_hub_signature):
+ raise HTTPException(status_code=403, detail="Request signatures didn't match!")
+```
+
+This function is important because it defines how Sweep Tutorial: Issue-to-PR AI Coding Workflows on GitHub implements the patterns covered in this chapter.
-def pascal_to_snake(name):
- return "".join(["_" + i.lower() if i.isupper() else i for i in name]).lstrip("_")
+### `sweepai/api.py`
+The `handle_request` function in [`sweepai/api.py`](https://github.com/sweepai/sweep/blob/HEAD/sweepai/api.py) handles a key part of this chapter's functionality:
-def get_event_type(event: Event | IssueEvent):
- if isinstance(event, IssueEvent):
- return "issues"
- else:
- return pascal_to_snake(event.type)[: -len("_event")]
+```py
-@app.command()
-def test():
- cprint("Sweep AI is installed correctly and ready to go!", style="yellow")
-@app.command()
-def watch(
- repo_name: str,
- debug: bool = False,
- record_events: bool = False,
- max_events: int = 30,
+def handle_request(request_dict, event=None):
+ """So it can be exported to the listen endpoint."""
+ with logger.contextualize(tracking_id="main", env=ENV):
+ action = request_dict.get("action")
+
+ try:
+ handle_github_webhook(
+ {
+ "request": request_dict,
+ "event": event,
+ }
+ )
+ except Exception as e:
+ logger.exception(str(e))
+ logger.info(f"Done handling {event}, {action}")
+ return {"success": True}
+
+
+# @app.post("/")
+async def validate_signature(
+ request: Request,
+ x_hub_signature: Optional[str] = Header(None, alias="X-Hub-Signature-256")
):
- if not os.path.exists(config_path):
- cprint(
- f"\nConfiguration not found at {config_path}. Please run [green]'sweep init'[/green] to initialize the CLI.\n",
- style="yellow",
- )
- raise ValueError(
- "Configuration not found, please run 'sweep init' to initialize the CLI."
- )
- posthog_capture(
+ payload_body = await request.body()
+ if not verify_signature(payload_body=payload_body, signature_header=x_hub_signature):
+ raise HTTPException(status_code=403, detail="Request signatures didn't match!")
+
+@app.post("/", dependencies=[Depends(validate_signature)])
+def webhook(
+ request_dict: dict = Body(...),
```
This function is important because it defines how Sweep Tutorial: Issue-to-PR AI Coding Workflows on GitHub implements the patterns covered in this chapter.
-### `sweepai/cli.py`
+### `sweepai/api.py`
-The `get_event_type` function in [`sweepai/cli.py`](https://github.com/sweepai/sweep/blob/HEAD/sweepai/cli.py) handles a key part of this chapter's functionality:
+The `validate_signature` function in [`sweepai/api.py`](https://github.com/sweepai/sweep/blob/HEAD/sweepai/api.py) handles a key part of this chapter's functionality:
```py
-
-def get_event_type(event: Event | IssueEvent):
- if isinstance(event, IssueEvent):
- return "issues"
- else:
- return pascal_to_snake(event.type)[: -len("_event")]
-
-@app.command()
-def test():
- cprint("Sweep AI is installed correctly and ready to go!", style="yellow")
-
-@app.command()
-def watch(
- repo_name: str,
- debug: bool = False,
- record_events: bool = False,
- max_events: int = 30,
+# @app.post("/")
+async def validate_signature(
+ request: Request,
+ x_hub_signature: Optional[str] = Header(None, alias="X-Hub-Signature-256")
+):
+ payload_body = await request.body()
+ if not verify_signature(payload_body=payload_body, signature_header=x_hub_signature):
+ raise HTTPException(status_code=403, detail="Request signatures didn't match!")
+
+@app.post("/", dependencies=[Depends(validate_signature)])
+def webhook(
+ request_dict: dict = Body(...),
+ x_github_event: Optional[str] = Header(None, alias="X-GitHub-Event"),
):
- if not os.path.exists(config_path):
- cprint(
- f"\nConfiguration not found at {config_path}. Please run [green]'sweep init'[/green] to initialize the CLI.\n",
- style="yellow",
- )
- raise ValueError(
- "Configuration not found, please run 'sweep init' to initialize the CLI."
- )
- posthog_capture(
- "sweep_watch_started",
- {
- "repo": repo_name,
- "debug": debug,
+ """Handle a webhook request from GitHub"""
+ with logger.contextualize(tracking_id="main", env=ENV):
+ action = request_dict.get("action", None)
+
+ logger.info(f"Received event: {x_github_event}, {action}")
+ return handle_request(request_dict, event=x_github_event)
+
+@app.post("/jira")
+def jira_webhook(
+ request_dict: dict = Body(...),
+) -> None:
+ def call_jira_ticket(*args, **kwargs):
+ thread = threading.Thread(target=handle_jira_ticket, args=args, kwargs=kwargs)
+ thread.start()
+ call_jira_ticket(event=request_dict)
+
+# Set up cronjob for this
```
This function is important because it defines how Sweep Tutorial: Issue-to-PR AI Coding Workflows on GitHub implements the patterns covered in this chapter.
@@ -220,10 +218,10 @@ This function is important because it defines how Sweep Tutorial: Issue-to-PR AI
```mermaid
flowchart TD
- A[load_config]
- B[fetch_issue_request]
- C[pascal_to_snake]
- D[get_event_type]
+ A[progress]
+ B[handle_github_webhook]
+ C[handle_request]
+ D[validate_signature]
A --> B
B --> C
C --> D
diff --git a/tutorials/sweep-tutorial/07-limitations-risk-controls-and-safe-scope.md b/tutorials/sweep-tutorial/07-limitations-risk-controls-and-safe-scope.md
index 09bb33a7..4a58a6f1 100644
--- a/tutorials/sweep-tutorial/07-limitations-risk-controls-and-safe-scope.md
+++ b/tutorials/sweep-tutorial/07-limitations-risk-controls-and-safe-scope.md
@@ -44,170 +44,168 @@ You now have a guardrail framework for assigning tasks Sweep can complete with h
Next: [Chapter 8: Migration Strategy and Long-Term Operations](08-migration-strategy-and-long-term-operations.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `sweepai/cli.py`
+### `sweepai/api.py`
-The `test` function in [`sweepai/cli.py`](https://github.com/sweepai/sweep/blob/HEAD/sweepai/cli.py) handles a key part of this chapter's functionality:
+The `webhook` function in [`sweepai/api.py`](https://github.com/sweepai/sweep/blob/HEAD/sweepai/api.py) handles a key part of this chapter's functionality:
```py
-@app.command()
-def test():
- cprint("Sweep AI is installed correctly and ready to go!", style="yellow")
-
-@app.command()
-def watch(
- repo_name: str,
- debug: bool = False,
- record_events: bool = False,
- max_events: int = 30,
-):
- if not os.path.exists(config_path):
- cprint(
- f"\nConfiguration not found at {config_path}. Please run [green]'sweep init'[/green] to initialize the CLI.\n",
- style="yellow",
- )
- raise ValueError(
- "Configuration not found, please run 'sweep init' to initialize the CLI."
- )
- posthog_capture(
- "sweep_watch_started",
- {
- "repo": repo_name,
- "debug": debug,
- "record_events": record_events,
- "max_events": max_events,
- },
- )
- GITHUB_PAT = os.environ.get("GITHUB_PAT", None)
- if GITHUB_PAT is None:
- raise ValueError("GITHUB_PAT environment variable must be set")
+templates = Jinja2Templates(directory="sweepai/web")
+logger.bind(application="webhook")
+
+def run_on_ticket(*args, **kwargs):
+ tracking_id = get_hash()
+ with logger.contextualize(
+ **kwargs,
+ name="ticket_" + kwargs["username"],
+ tracking_id=tracking_id,
+ ):
+ return on_ticket(*args, **kwargs, tracking_id=tracking_id)
+
+
+def run_on_comment(*args, **kwargs):
+ tracking_id = get_hash()
+ with logger.contextualize(
+ **kwargs,
+ name="comment_" + kwargs["username"],
+ tracking_id=tracking_id,
+ ):
+ on_comment(*args, **kwargs, tracking_id=tracking_id)
+
+def run_review_pr(*args, **kwargs):
+ tracking_id = get_hash()
+ with logger.contextualize(
+ **kwargs,
+ name="review_" + kwargs["username"],
+ tracking_id=tracking_id,
+ ):
+ review_pr(*args, **kwargs, tracking_id=tracking_id)
+
```
This function is important because it defines how Sweep Tutorial: Issue-to-PR AI Coding Workflows on GitHub implements the patterns covered in this chapter.
-### `sweepai/cli.py`
+### `sweepai/api.py`
-The `watch` function in [`sweepai/cli.py`](https://github.com/sweepai/sweep/blob/HEAD/sweepai/cli.py) handles a key part of this chapter's functionality:
+The `jira_webhook` function in [`sweepai/api.py`](https://github.com/sweepai/sweep/blob/HEAD/sweepai/api.py) handles a key part of this chapter's functionality:
```py
-@app.command()
-def watch(
- repo_name: str,
- debug: bool = False,
- record_events: bool = False,
- max_events: int = 30,
-):
- if not os.path.exists(config_path):
- cprint(
- f"\nConfiguration not found at {config_path}. Please run [green]'sweep init'[/green] to initialize the CLI.\n",
- style="yellow",
- )
- raise ValueError(
- "Configuration not found, please run 'sweep init' to initialize the CLI."
- )
- posthog_capture(
- "sweep_watch_started",
- {
- "repo": repo_name,
- "debug": debug,
- "record_events": record_events,
- "max_events": max_events,
- },
- )
- GITHUB_PAT = os.environ.get("GITHUB_PAT", None)
- if GITHUB_PAT is None:
- raise ValueError("GITHUB_PAT environment variable must be set")
- g = Github(os.environ["GITHUB_PAT"])
- repo = g.get_repo(repo_name)
- if debug:
- logger.debug("Debug mode enabled")
+@app.post("/jira")
+def jira_webhook(
+ request_dict: dict = Body(...),
+) -> None:
+ def call_jira_ticket(*args, **kwargs):
+ thread = threading.Thread(target=handle_jira_ticket, args=args, kwargs=kwargs)
+ thread.start()
+ call_jira_ticket(event=request_dict)
+
+# Set up cronjob for this
+@app.get("/update_sweep_prs_v2")
+def update_sweep_prs_v2(repo_full_name: str, installation_id: int):
+ # Get a Github client
+ _, g = get_github_client(installation_id)
+
+ # Get the repository
+ repo = g.get_repo(repo_full_name)
+ config = SweepConfig.get_config(repo)
+
+ try:
+ branch_ttl = int(config.get("branch_ttl", 7))
+ except Exception:
+ branch_ttl = 7
+ branch_ttl = max(branch_ttl, 1)
+
+ # Get all open pull requests created by Sweep
+ pulls = repo.get_pulls(
+ state="open", head="sweep", sort="updated", direction="desc"
+ )[:5]
+
+ # For each pull request, attempt to merge the changes from the default branch into the pull request branch
```
This function is important because it defines how Sweep Tutorial: Issue-to-PR AI Coding Workflows on GitHub implements the patterns covered in this chapter.
-### `sweepai/cli.py`
+### `sweepai/api.py`
-The `init` function in [`sweepai/cli.py`](https://github.com/sweepai/sweep/blob/HEAD/sweepai/cli.py) handles a key part of this chapter's functionality:
+The `update_sweep_prs_v2` function in [`sweepai/api.py`](https://github.com/sweepai/sweep/blob/HEAD/sweepai/api.py) handles a key part of this chapter's functionality:
```py
- if not os.path.exists(config_path):
- cprint(
- f"\nConfiguration not found at {config_path}. Please run [green]'sweep init'[/green] to initialize the CLI.\n",
- style="yellow",
- )
- raise ValueError(
- "Configuration not found, please run 'sweep init' to initialize the CLI."
- )
- posthog_capture(
- "sweep_watch_started",
- {
- "repo": repo_name,
- "debug": debug,
- "record_events": record_events,
- "max_events": max_events,
- },
- )
- GITHUB_PAT = os.environ.get("GITHUB_PAT", None)
- if GITHUB_PAT is None:
- raise ValueError("GITHUB_PAT environment variable must be set")
- g = Github(os.environ["GITHUB_PAT"])
- repo = g.get_repo(repo_name)
- if debug:
- logger.debug("Debug mode enabled")
-
- def stream_events(repo: Repository, timeout: int = 2, offset: int = 2 * 60):
- processed_event_ids = set()
- current_time = time.time() - offset
- current_time = datetime.datetime.fromtimestamp(current_time)
- local_tz = datetime.datetime.now(datetime.timezone.utc).astimezone().tzinfo
-
- while True:
+
+# Set up cronjob for this
+@app.get("/update_sweep_prs_v2")
+def update_sweep_prs_v2(repo_full_name: str, installation_id: int):
+ # Get a Github client
+ _, g = get_github_client(installation_id)
+
+ # Get the repository
+ repo = g.get_repo(repo_full_name)
+ config = SweepConfig.get_config(repo)
+
+ try:
+ branch_ttl = int(config.get("branch_ttl", 7))
+ except Exception:
+ branch_ttl = 7
+ branch_ttl = max(branch_ttl, 1)
+
+ # Get all open pull requests created by Sweep
+ pulls = repo.get_pulls(
+ state="open", head="sweep", sort="updated", direction="desc"
+ )[:5]
+
+ # For each pull request, attempt to merge the changes from the default branch into the pull request branch
+ try:
+ for pr in pulls:
+ try:
+ # make sure it's a sweep ticket
+ feature_branch = pr.head.ref
+ if not feature_branch.startswith(
+ "sweep/"
+ ) and not feature_branch.startswith("sweep_"):
+ continue
```
This function is important because it defines how Sweep Tutorial: Issue-to-PR AI Coding Workflows on GitHub implements the patterns covered in this chapter.
-### `sweepai/cli.py`
+### `sweepai/api.py`
-The `run` function in [`sweepai/cli.py`](https://github.com/sweepai/sweep/blob/HEAD/sweepai/cli.py) handles a key part of this chapter's functionality:
+The `should_handle_comment` function in [`sweepai/api.py`](https://github.com/sweepai/sweep/blob/HEAD/sweepai/api.py) handles a key part of this chapter's functionality:
```py
- if not os.path.exists(config_path):
- cprint(
- f"\nConfiguration not found at {config_path}. Please run [green]'sweep init'[/green] to initialize the CLI.\n",
- style="yellow",
- )
- raise ValueError(
- "Configuration not found, please run 'sweep init' to initialize the CLI."
+ logger.warning("Failed to update sweep PRs")
+
+def should_handle_comment(request: CommentCreatedRequest | IssueCommentRequest):
+ comment = request.comment.body
+ return (
+ (
+ comment.lower().startswith("sweep:") # we will handle all comments (with or without label) that start with "sweep:"
)
- posthog_capture(
- "sweep_watch_started",
- {
- "repo": repo_name,
- "debug": debug,
- "record_events": record_events,
- "max_events": max_events,
- },
+ and request.comment.user.type == "User" # ensure it's a user comment
+ and request.comment.user.login not in BLACKLISTED_USERS # ensure it's not a blacklisted user
+ and BOT_SUFFIX not in comment # we don't handle bot commnents
)
- GITHUB_PAT = os.environ.get("GITHUB_PAT", None)
- if GITHUB_PAT is None:
- raise ValueError("GITHUB_PAT environment variable must be set")
- g = Github(os.environ["GITHUB_PAT"])
- repo = g.get_repo(repo_name)
- if debug:
- logger.debug("Debug mode enabled")
-
- def stream_events(repo: Repository, timeout: int = 2, offset: int = 2 * 60):
- processed_event_ids = set()
- current_time = time.time() - offset
- current_time = datetime.datetime.fromtimestamp(current_time)
- local_tz = datetime.datetime.now(datetime.timezone.utc).astimezone().tzinfo
-
- while True:
+
+def handle_event(request_dict, event):
+ action = request_dict.get("action")
+
+ username = request_dict.get("sender", {}).get("login")
+ if username:
+ set_user({"username": username})
+
+ if repo_full_name := request_dict.get("repository", {}).get("full_name"):
+ if repo_full_name in DISABLED_REPOS:
+ logger.warning(f"Repo {repo_full_name} is disabled")
+ return {"success": False, "error_message": "Repo is disabled"}
+
+ with logger.contextualize(tracking_id="main", env=ENV):
+ match event, action:
+ case "check_run", "completed":
+ request = CheckRunCompleted(**request_dict)
+ _, g = get_github_client(request.installation.id)
+ repo = g.get_repo(request.repository.full_name)
+ pull_requests = request.check_run.pull_requests
```
This function is important because it defines how Sweep Tutorial: Issue-to-PR AI Coding Workflows on GitHub implements the patterns covered in this chapter.
@@ -217,10 +215,10 @@ This function is important because it defines how Sweep Tutorial: Issue-to-PR AI
```mermaid
flowchart TD
- A[test]
- B[watch]
- C[init]
- D[run]
+ A[webhook]
+ B[jira_webhook]
+ C[update_sweep_prs_v2]
+ D[should_handle_comment]
A --> B
B --> C
C --> D
diff --git a/tutorials/sweep-tutorial/08-migration-strategy-and-long-term-operations.md b/tutorials/sweep-tutorial/08-migration-strategy-and-long-term-operations.md
index af19680c..a38fce63 100644
--- a/tutorials/sweep-tutorial/08-migration-strategy-and-long-term-operations.md
+++ b/tutorials/sweep-tutorial/08-migration-strategy-and-long-term-operations.md
@@ -45,47 +45,45 @@ You now have a long-term operating approach for using Sweep responsibly within a
Next: compare adjacent architectures in [OpenCode](../opencode-tutorial/) and [Stagewise](../stagewise-tutorial/).
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `sweepai/cli.py`
+### `sweepai/api.py`
-The `main` function in [`sweepai/cli.py`](https://github.com/sweepai/sweep/blob/HEAD/sweepai/cli.py) handles a key part of this chapter's functionality:
+The `handle_event` function in [`sweepai/api.py`](https://github.com/sweepai/sweep/blob/HEAD/sweepai/api.py) handles a key part of this chapter's functionality:
```py
- return handle_request(payload, get_event_type(event))
- def main():
- cprint(
- f"\n[bold black on white] Starting server, listening to events from {repo_name}... [/bold black on white]\n",
- )
- cprint(
- f"To create a PR, please create an issue at https://github.com/{repo_name}/issues with a title prefixed with 'Sweep:' or label an existing issue with 'sweep'. The events will be logged here, but there may be a brief delay.\n"
- )
- for event in stream_events(repo):
- handle_event(event)
-
- if __name__ == "__main__":
- main()
-
-
-@app.command()
-def init(override: bool = False):
- # TODO: Fix telemetry
- if not override:
- if os.path.exists(config_path):
- with open(config_path, "r") as f:
- config = json.load(f)
- if "OPENAI_API_KEY" in config and "ANTHROPIC_API_KEY" in config and "GITHUB_PAT" in config:
- override = typer.confirm(
- f"\nConfiguration already exists at {config_path}. Override?",
- default=False,
- abort=True,
- )
- cprint(
- "\n[bold black on white] Initializing Sweep CLI... [/bold black on white]\n",
- )
+def handle_github_webhook(event_payload):
+ handle_event(event_payload.get("request"), event_payload.get("event"))
+
+
+def handle_request(request_dict, event=None):
+ """So it can be exported to the listen endpoint."""
+ with logger.contextualize(tracking_id="main", env=ENV):
+ action = request_dict.get("action")
+
+ try:
+ handle_github_webhook(
+ {
+ "request": request_dict,
+ "event": event,
+ }
+ )
+ except Exception as e:
+ logger.exception(str(e))
+ logger.info(f"Done handling {event}, {action}")
+ return {"success": True}
+
+
+# @app.post("/")
+async def validate_signature(
+ request: Request,
+ x_hub_signature: Optional[str] = Header(None, alias="X-Hub-Signature-256")
+):
+ payload_body = await request.body()
+ if not verify_signature(payload_body=payload_body, signature_header=x_hub_signature):
+ raise HTTPException(status_code=403, detail="Request signatures didn't match!")
+
```
This function is important because it defines how Sweep Tutorial: Issue-to-PR AI Coding Workflows on GitHub implements the patterns covered in this chapter.
@@ -218,7 +216,7 @@ This function is important because it defines how Sweep Tutorial: Issue-to-PR AI
```mermaid
flowchart TD
- A[main]
+ A[handle_event]
B[pascal_to_snake]
C[get_event_type]
D[stream_events]
diff --git a/tutorials/sweep-tutorial/README.md b/tutorials/sweep-tutorial/README.md
index 1e2c9465..24cecb24 100644
--- a/tutorials/sweep-tutorial/README.md
+++ b/tutorials/sweep-tutorial/README.md
@@ -15,16 +15,18 @@ format_version: v2
[](https://docs.sweep.dev/)
[](https://sweep.dev)
+> **Product Status Notice**: The original Sweep GitHub issue-to-PR product has been abandoned. The `sweepai/sweep` README now redirects users to a new JetBrains AI coding plugin. The hosted Sweep GitHub App and the issue-to-PR workflow documented in this tutorial are no longer actively supported. This tutorial is preserved as a reference for the architecture patterns and operational workflows Sweep introduced. Teams building new automation should evaluate current alternatives such as SWE-agent, Aider, or OpenHands.
+
## Why This Track Matters
-Sweep popularized an issue-to-PR coding-agent workflow on GitHub. Even with product evolution over time, the repository and docs still provide strong patterns for asynchronous AI delivery loops, feedback handling, and operational controls.
+Sweep popularized an issue-to-PR coding-agent workflow on GitHub. The repository and docs still provide strong reference patterns for asynchronous AI delivery loops, feedback handling, and operational controls even though the original hosted product is no longer active.
This track focuses on:
-- running Sweep issue and PR workflows effectively
+- understanding the original Sweep issue-to-PR architecture and config model
- configuring repository-level behavior through `sweep.yaml`
- operating review, CI, and retry loops for higher output quality
-- understanding self-hosted and local CLI deployment paths
+- understanding self-hosted and local CLI deployment paths as legacy reference
## Current Snapshot (auto-updated)
diff --git a/tutorials/tabby-tutorial/01-getting-started-and-first-server.md b/tutorials/tabby-tutorial/01-getting-started-and-first-server.md
index 00e2600e..5d7afdff 100644
--- a/tutorials/tabby-tutorial/01-getting-started-and-first-server.md
+++ b/tutorials/tabby-tutorial/01-getting-started-and-first-server.md
@@ -75,36 +75,22 @@ Next: [Chapter 2: Architecture and Runtime Components](02-architecture-and-runti
## Source Code Walkthrough
-### `rules/use-schema-result.yml`
-
-The `severity` interface in [`rules/use-schema-result.yml`](https://github.com/TabbyML/tabby/blob/HEAD/rules/use-schema-result.yml) handles a key part of this chapter's functionality:
-
-```yml
-id: use-schema-result
-message: Use schema::Result as API interface
-severity: error
-language: rust
-files:
-- ./ee/tabby-schema/src/**
-ignores:
-- ./ee/tabby-schema/src/lib.rs
-- ./ee/tabby-schema/src/dao.rs
-rule:
- any:
- - pattern: anyhow
- not:
- inside:
- kind: enum_variant
- stopBy: end
- - pattern: FieldResult
-```
+Use the following upstream sources to verify getting started and first server details while reading this chapter:
-This interface is important because it defines how Tabby Tutorial: Self-Hosted AI Coding Assistant Architecture and Operations implements the patterns covered in this chapter.
+- [`crates/tabby/src/main.rs`](https://github.com/TabbyML/tabby/blob/HEAD/crates/tabby/src/main.rs) — the Rust binary entry point for the Tabby server, handling CLI argument parsing, configuration loading, and the HTTP server startup sequence.
+- [`crates/tabby/src/serve.rs`](https://github.com/TabbyML/tabby/blob/HEAD/crates/tabby/src/serve.rs) — the primary server initialization module that wires together the completion API, chat API, health endpoint, and model backend into a running Axum HTTP service.
+Suggested trace strategy:
+- trace `main.rs` to understand the startup flags (model path, port, device) and how they map to server behavior
+- review `serve.rs` to see how the completion and chat routes are registered and which middleware is applied
+- check `ee/tabby-webserver/` for the enterprise web server layer that adds authentication and UI
## How These Components Connect
```mermaid
-flowchart TD
- A[severity]
-```
+flowchart LR
+ A[tabby serve command] --> B[main.rs CLI parsing]
+ B --> C[serve.rs server init]
+ C --> D[Completion and chat routes registered]
+ D --> E[Server accepting requests on configured port]
+```
\ No newline at end of file
diff --git a/tutorials/tabby-tutorial/02-architecture-and-runtime-components.md b/tutorials/tabby-tutorial/02-architecture-and-runtime-components.md
index 0add7d4b..18597203 100644
--- a/tutorials/tabby-tutorial/02-architecture-and-runtime-components.md
+++ b/tutorials/tabby-tutorial/02-architecture-and-runtime-components.md
@@ -78,51 +78,22 @@ Next: [Chapter 3: Model Serving and Completion Pipeline](03-model-serving-and-co
## Source Code Walkthrough
-### `website/docusaurus.config.js`
-
-The `tailwind` function in [`website/docusaurus.config.js`](https://github.com/TabbyML/tabby/blob/HEAD/website/docusaurus.config.js) handles a key part of this chapter's functionality:
-
-```js
-
- plugins: [
- async function tailwind(context, options) {
- return {
- name: "docusaurus-tailwindcss",
- configurePostCss(postcssOptions) {
- // Appends TailwindCSS and AutoPrefixer.
- postcssOptions.plugins.push(require("tailwindcss"));
- postcssOptions.plugins.push(require("autoprefixer"));
- return postcssOptions;
- },
- };
- },
- [
- "posthog-docusaurus",
- {
- apiKey: "phc_aBzNGHzlOy2C8n1BBDtH7d4qQsIw9d8T0unVlnKfdxB",
- appUrl: "https://app.posthog.com",
- enableInDevelopment: false,
- },
- ],
- [
- '@docusaurus/plugin-client-redirects',
- {
- redirects: [
- {
- to: '/blog/2024/02/05/create-tabby-extension-with-language-server-protocol',
- from: '/blog/running-tabby-as-a-language-server'
- },
- {
- to: '/blog/2023/09/05/deploy-tabby-to-huggingface-space',
- from: '/blog/deploy-tabby-to-huggingface-space.md',
-```
+Use the following upstream sources to verify architecture and runtime component details while reading this chapter:
-This function is important because it defines how Tabby Tutorial: Self-Hosted AI Coding Assistant Architecture and Operations implements the patterns covered in this chapter.
+- [`Cargo.toml`](https://github.com/TabbyML/tabby/blob/HEAD/Cargo.toml) — the Rust workspace manifest that lists all crates composing the Tabby runtime: `tabby`, `tabby-common`, `tabby-inference`, `tabby-index`, `tabby-crawler`, and the enterprise `ee/` components.
+- [`crates/tabby-inference/src/lib.rs`](https://github.com/TabbyML/tabby/blob/HEAD/crates/tabby-inference/src/lib.rs) — the inference abstraction layer that defines the `TextGenerationStream` trait implemented by each model backend (llama.cpp, GGML, HTTP API).
+Suggested trace strategy:
+- read `Cargo.toml` to map the crate dependency graph and identify which crates handle serving, inference, and indexing
+- trace `tabby-inference/src/lib.rs` to understand the trait abstraction that decouples the API server from specific model backends
+- review `crates/tabby-common/` for shared data types (completion request/response, configuration structs) used across crates
## How These Components Connect
```mermaid
-flowchart TD
- A[tailwind]
-```
+flowchart LR
+ A[HTTP API request] --> B[tabby crate: request routing]
+ B --> C[tabby-inference: TextGenerationStream trait]
+ C --> D[Backend: llama.cpp or GGML or HTTP model]
+ D --> E[Completion tokens streamed back]
+```
\ No newline at end of file
diff --git a/tutorials/tabby-tutorial/03-model-serving-and-completion-pipeline.md b/tutorials/tabby-tutorial/03-model-serving-and-completion-pipeline.md
index 122ebb0e..0eae10b4 100644
--- a/tutorials/tabby-tutorial/03-model-serving-and-completion-pipeline.md
+++ b/tutorials/tabby-tutorial/03-model-serving-and-completion-pipeline.md
@@ -74,51 +74,22 @@ Next: [Chapter 4: Answer Engine and Context Indexing](04-answer-engine-and-conte
## Source Code Walkthrough
-### `python/tabby/trainer.py`
-
-The `ConstantLengthDataset` class in [`python/tabby/trainer.py`](https://github.com/TabbyML/tabby/blob/HEAD/python/tabby/trainer.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-class ConstantLengthDataset:
- """
- Iterable dataset that returns constant length chunks of tokens from stream of text files.
- Args:
- tokenizer (Tokenizer): The processor used for proccessing the data.
- dataset (dataset.Dataset): Dataset with text files.
- infinite (bool): If True the iterator is reset after dataset reaches end else stops.
- seq_length (int): Length of token sequences to return.
- num_of_sequences (int): Number of token sequences to keep in buffer.
- chars_per_token (int): Number of characters per token used to estimate number of tokens in text buffer.
- """
-
- def __init__(
- self,
- tokenizer,
- dataset,
- infinite=False,
- seq_length=1024,
- num_of_sequences=1024,
- chars_per_token=3.6,
- content_field="content",
- ):
- self.tokenizer = tokenizer
- self.concat_token_id = tokenizer.eos_token_id
- self.dataset = dataset
- self.seq_length = seq_length
- self.infinite = infinite
- self.current_size = 0
- self.max_buffer_size = seq_length * chars_per_token * num_of_sequences
- self.content_field = content_field
-```
+Use the following upstream sources to verify model serving and completion pipeline details while reading this chapter:
-This class is important because it defines how Tabby Tutorial: Self-Hosted AI Coding Assistant Architecture and Operations implements the patterns covered in this chapter.
+- [`crates/tabby/src/routes/completions.rs`](https://github.com/TabbyML/tabby/blob/HEAD/crates/tabby/src/routes/) — the completion API route handler that validates completion requests, applies FIM (fill-in-the-middle) template formatting, invokes the inference backend, and streams completion tokens.
+- [`crates/tabby-inference/src/lib.rs`](https://github.com/TabbyML/tabby/blob/HEAD/crates/tabby-inference/src/lib.rs) — the inference backend trait and request dispatch logic that routes completion requests to the correct model backend.
+Suggested trace strategy:
+- trace the completion request from the Axum handler in `completions.rs` through inference dispatch to the backend
+- review FIM template construction to understand how prefix/suffix/middle context is formatted for different model families
+- check `crates/tabby-common/src/api/` for the completion request/response schema definitions
## How These Components Connect
```mermaid
-flowchart TD
- A[ConstantLengthDataset]
-```
+flowchart LR
+ A[Completion request from editor] --> B[completions.rs route handler]
+ B --> C[FIM template formatting]
+ C --> D[tabby-inference backend dispatch]
+ D --> E[Token stream returned]
+```
\ No newline at end of file
diff --git a/tutorials/tabby-tutorial/04-answer-engine-and-context-indexing.md b/tutorials/tabby-tutorial/04-answer-engine-and-context-indexing.md
index 57a3c07c..5545d72e 100644
--- a/tutorials/tabby-tutorial/04-answer-engine-and-context-indexing.md
+++ b/tutorials/tabby-tutorial/04-answer-engine-and-context-indexing.md
@@ -63,51 +63,22 @@ Next: [Chapter 5: Editor Agents and Client Integrations](05-editor-agents-and-cl
## Source Code Walkthrough
-### `python/tabby/trainer.py`
-
-The `class` class in [`python/tabby/trainer.py`](https://github.com/TabbyML/tabby/blob/HEAD/python/tabby/trainer.py) handles a key part of this chapter's functionality:
-
-```py
-import os
-import glob
-from dataclasses import dataclass, field
-from typing import List
-
-import peft
-import torch
-from transformers import (
- AutoModelForCausalLM,
- AutoTokenizer,
- HfArgumentParser,
- Trainer,
- TrainingArguments,
-)
-from datasets import Dataset, load_dataset
-
-
-class ConstantLengthDataset:
- """
- Iterable dataset that returns constant length chunks of tokens from stream of text files.
- Args:
- tokenizer (Tokenizer): The processor used for proccessing the data.
- dataset (dataset.Dataset): Dataset with text files.
- infinite (bool): If True the iterator is reset after dataset reaches end else stops.
- seq_length (int): Length of token sequences to return.
- num_of_sequences (int): Number of token sequences to keep in buffer.
- chars_per_token (int): Number of characters per token used to estimate number of tokens in text buffer.
- """
-
- def __init__(
- self,
- tokenizer,
-```
+Use the following upstream sources to verify answer engine and context indexing details while reading this chapter:
-This class is important because it defines how Tabby Tutorial: Self-Hosted AI Coding Assistant Architecture and Operations implements the patterns covered in this chapter.
+- [`crates/tabby-index/src/lib.rs`](https://github.com/TabbyML/tabby/blob/HEAD/crates/tabby-index/src/lib.rs) — the repository and documentation indexing crate that builds the vector store used by the answer engine to retrieve relevant code context.
+- [`crates/tabby-crawler/src/lib.rs`](https://github.com/TabbyML/tabby/blob/HEAD/crates/tabby-crawler/src/lib.rs) — the document crawler that fetches and preprocesses external documentation sources before they are passed to the indexer.
+Suggested trace strategy:
+- trace the indexing pipeline in `tabby-index` from document ingestion through embedding to vector store write
+- review the `tabby-crawler` to understand which source types (git, web, docs) are supported and how content is extracted
+- check `crates/tabby/src/routes/chat.rs` to see how the answer engine retrieves context from the index before generating chat responses
## How These Components Connect
```mermaid
-flowchart TD
- A[class]
-```
+flowchart LR
+ A[Repository or docs source] --> B[tabby-crawler ingestion]
+ B --> C[tabby-index embedding and storage]
+ C --> D[Answer engine context retrieval]
+ D --> E[Chat response grounded in repo knowledge]
+```
\ No newline at end of file
diff --git a/tutorials/tabby-tutorial/05-editor-agents-and-client-integrations.md b/tutorials/tabby-tutorial/05-editor-agents-and-client-integrations.md
index 999c3e07..963dae1f 100644
--- a/tutorials/tabby-tutorial/05-editor-agents-and-client-integrations.md
+++ b/tutorials/tabby-tutorial/05-editor-agents-and-client-integrations.md
@@ -63,51 +63,22 @@ Next: [Chapter 6: Configuration, Security, and Enterprise Controls](06-configura
## Source Code Walkthrough
-### `python/tabby/trainer.py`
+Use the following upstream sources to verify editor agent and client integration details while reading this chapter:
-The `parse_args` function in [`python/tabby/trainer.py`](https://github.com/TabbyML/tabby/blob/HEAD/python/tabby/trainer.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def parse_args() -> TrainLoraArguments:
- parser = HfArgumentParser(TrainLoraArguments)
- return parser.parse_args()
-
-
-def train(args: TrainLoraArguments):
- gradient_accumulation_steps = args.batch_size // args.micro_batch_size
-
- model = AutoModelForCausalLM.from_pretrained(
- args.base_model, torch_dtype=torch.float16 if args.half else torch.float32
- )
-
- tokenizer = AutoTokenizer.from_pretrained(args.base_model)
-
- config = peft.LoraConfig(
- r=args.lora_r,
- lora_alpha=args.lora_alpha,
- target_modules=args.lora_target_modules,
- lora_dropout=args.lora_dropout,
- bias="none",
- task_type=peft.TaskType.CAUSAL_LM,
- )
- model = peft.get_peft_model(model, config)
-
- data_files = glob.glob(os.path.join(args.data_path, "*.jsonl"))
- print("Collected data files...", data_files)
- dataset = load_dataset("json", data_files=data_files)["train"]
- data = Dataset.from_generator(ConstantLengthDataset(tokenizer, dataset))
-
- resume_from_checkpoint = args.resume_from_checkpoint
-```
-
-This function is important because it defines how Tabby Tutorial: Self-Hosted AI Coding Assistant Architecture and Operations implements the patterns covered in this chapter.
+- [`clients/tabby-agent/src/index.ts`](https://github.com/TabbyML/tabby/blob/HEAD/clients/tabby-agent/src/index.ts) — the TypeScript LSP bridge that editor extensions communicate with; it handles completion requests, inline completion debounce, and connection management to the Tabby server.
+- [`clients/tabby-agent/src/TabbyClient.ts`](https://github.com/TabbyML/tabby/blob/HEAD/clients/tabby-agent/src/TabbyClient.ts) — the HTTP client layer inside `tabby-agent` that sends requests to the Tabby server API and handles authentication headers and retry logic.
+Suggested trace strategy:
+- trace how the VS Code extension calls `tabby-agent` for inline completions and how the agent proxies to the server
+- review `TabbyClient.ts` to understand the request/response lifecycle including token auth and error recovery
+- check `clients/tabby-vscode/` for the VS Code extension source to see the full editor integration surface
## How These Components Connect
```mermaid
-flowchart TD
- A[parse_args]
-```
+flowchart LR
+ A[VS Code inline completion trigger] --> B[tabby-vscode extension]
+ B --> C[tabby-agent LSP bridge]
+ C --> D[TabbyClient HTTP request]
+ D --> E[Tabby server completion API]
+```
\ No newline at end of file
diff --git a/tutorials/tabby-tutorial/06-configuration-security-and-enterprise-controls.md b/tutorials/tabby-tutorial/06-configuration-security-and-enterprise-controls.md
index bc0d198e..38100bee 100644
--- a/tutorials/tabby-tutorial/06-configuration-security-and-enterprise-controls.md
+++ b/tutorials/tabby-tutorial/06-configuration-security-and-enterprise-controls.md
@@ -66,51 +66,22 @@ Next: [Chapter 7: Operations, Upgrades, and Observability](07-operations-upgrade
## Source Code Walkthrough
-### `python/tabby/trainer.py`
-
-The `train` function in [`python/tabby/trainer.py`](https://github.com/TabbyML/tabby/blob/HEAD/python/tabby/trainer.py) handles a key part of this chapter's functionality:
-
-```py
-@dataclass
-class TrainLoraArguments:
- data_path: str = field(metadata={"help": "Dataset dir for training / eval "})
- output_dir: str = field(metadata={"help": "Output dir for checkpoint"})
- base_model: str = field(
- default="TabbyML/J-350M", metadata={"help": "Base model for fine-tuning"}
- )
-
- batch_size: int = 128
- micro_batch_size: int = 4
- num_epochs: int = 3
- learning_rate: float = 3e-4
- cutoff_len: int = 256
-
- # Evaluations
- val_set_size: int = 2000
- eval_steps: int = 200
-
- # Lora Hyperparams
- lora_r: int = 8
- lora_alpha: int = 16
- lora_dropout: float = 0.05
- lora_target_modules: List[str] = (
- [
- "q_proj",
- "v_proj",
- ],
- )
- resume_from_checkpoint: str = None # either training checkpoint or final adapter
- half: bool = True
+Use the following upstream sources to verify configuration, security, and enterprise controls while reading this chapter:
+- [`ee/tabby-webserver/src/lib.rs`](https://github.com/TabbyML/tabby/blob/HEAD/ee/tabby-webserver/src/lib.rs) — the enterprise web server layer that adds JWT authentication, user management, team access controls, and the web UI on top of the core Tabby server.
+- [`ee/tabby-schema/src/lib.rs`](https://github.com/TabbyML/tabby/blob/HEAD/ee/tabby-schema/src/lib.rs) — the GraphQL schema definition for the enterprise web server, covering user, team, repository, and integration management APIs.
-```
-
-This function is important because it defines how Tabby Tutorial: Self-Hosted AI Coding Assistant Architecture and Operations implements the patterns covered in this chapter.
-
+Suggested trace strategy:
+- trace authentication middleware in `tabby-webserver` to understand how API tokens and JWT are validated per request
+- review the schema types in `tabby-schema` to understand which entities are access-controlled and at which granularity
+- check `config.toml` documentation (https://tabby.tabbyml.com/docs/administration/config-toml) for all security-relevant settings
## How These Components Connect
```mermaid
-flowchart TD
- A[train]
-```
+flowchart LR
+ A[Editor request with token] --> B[tabby-webserver auth middleware]
+ B --> C[JWT or API token validation]
+ C --> D[Access control check via tabby-schema]
+ D --> E[Request forwarded or rejected]
+```
\ No newline at end of file
diff --git a/tutorials/tabby-tutorial/07-operations-upgrades-and-observability.md b/tutorials/tabby-tutorial/07-operations-upgrades-and-observability.md
index 7b52bd23..b801d0e7 100644
--- a/tutorials/tabby-tutorial/07-operations-upgrades-and-observability.md
+++ b/tutorials/tabby-tutorial/07-operations-upgrades-and-observability.md
@@ -56,54 +56,23 @@ Next: [Chapter 8: Contribution, Roadmap, and Team Adoption](08-contribution-road
## Source Code Walkthrough
-### `Cargo.toml`
-
-The `Cargo` module in [`Cargo.toml`](https://github.com/TabbyML/tabby/blob/HEAD/Cargo.toml) handles a key part of this chapter's functionality:
-
-```toml
-[workspace]
-resolver = "1"
-members = [
- "crates/tabby",
- "crates/tabby-common",
- "crates/tabby-download",
- "crates/tabby-git",
- "crates/tabby-inference",
- "crates/tabby-index",
- "crates/tabby-crawler",
-
- "crates/aim-downloader",
- "crates/http-api-bindings",
- "crates/llama-cpp-server",
- "crates/ollama-api-bindings",
- "crates/tabby-index-cli",
- "crates/hash-ids",
- "crates/sqlx-migrate-validate",
-
- "ee/tabby-webserver",
- "ee/tabby-db",
- "ee/tabby-db-macros",
- "ee/tabby-schema",
-]
-
-[workspace.package]
-version = "0.33.0-dev.0"
-edition = "2021"
-authors = ["TabbyML Team"]
-homepage = "https://github.com/TabbyML/tabby"
-
-[workspace.dependencies]
-cached = "0.49.3"
-lazy_static = "1.4.0"
-serde = { version = "1.0", features = ["derive"] }
-```
-
-This module is important because it defines how Tabby Tutorial: Self-Hosted AI Coding Assistant Architecture and Operations implements the patterns covered in this chapter.
+Use the following upstream sources to verify operations, upgrade, and observability details while reading this chapter:
+- [`crates/tabby/src/routes/health.rs`](https://github.com/TabbyML/tabby/blob/HEAD/crates/tabby/src/routes/) — the health check endpoint that returns server status, model load state, and runtime version information used by monitoring systems.
+- [`CHANGELOG.md`](https://github.com/TabbyML/tabby/blob/HEAD/CHANGELOG.md) — the official release changelog documenting breaking changes, upgrade notes, and feature additions per version, essential for planning safe upgrades.
+
+Suggested trace strategy:
+- review `health.rs` to understand what the `/health` endpoint returns and how to use it for readiness and liveness probes
+- read `CHANGELOG.md` entries for any migration steps required between the current and target version before upgrading
+- check the Docker Compose and Kubernetes deployment examples for volume mount patterns that preserve model cache across upgrades
## How These Components Connect
```mermaid
-flowchart TD
- A[Cargo]
-```
+flowchart LR
+ A[Monitoring system] --> B[GET /health endpoint]
+ B --> C[health.rs returns status and version]
+ C --> D[Alert if unhealthy]
+ E[Upgrade planned] --> F[CHANGELOG.md migration notes]
+ F --> G[Safe upgrade executed]
+```
\ No newline at end of file
diff --git a/tutorials/tabby-tutorial/08-contribution-roadmap-and-team-adoption.md b/tutorials/tabby-tutorial/08-contribution-roadmap-and-team-adoption.md
index f107d5ac..ff29b143 100644
--- a/tutorials/tabby-tutorial/08-contribution-roadmap-and-team-adoption.md
+++ b/tutorials/tabby-tutorial/08-contribution-roadmap-and-team-adoption.md
@@ -54,54 +54,22 @@ Next: pick a related implementation track such as [Continue](../continue-tutoria
## Source Code Walkthrough
-### `Cargo.toml`
-
-The `Cargo` module in [`Cargo.toml`](https://github.com/TabbyML/tabby/blob/HEAD/Cargo.toml) handles a key part of this chapter's functionality:
-
-```toml
-[workspace]
-resolver = "1"
-members = [
- "crates/tabby",
- "crates/tabby-common",
- "crates/tabby-download",
- "crates/tabby-git",
- "crates/tabby-inference",
- "crates/tabby-index",
- "crates/tabby-crawler",
-
- "crates/aim-downloader",
- "crates/http-api-bindings",
- "crates/llama-cpp-server",
- "crates/ollama-api-bindings",
- "crates/tabby-index-cli",
- "crates/hash-ids",
- "crates/sqlx-migrate-validate",
-
- "ee/tabby-webserver",
- "ee/tabby-db",
- "ee/tabby-db-macros",
- "ee/tabby-schema",
-]
-
-[workspace.package]
-version = "0.33.0-dev.0"
-edition = "2021"
-authors = ["TabbyML Team"]
-homepage = "https://github.com/TabbyML/tabby"
-
-[workspace.dependencies]
-cached = "0.49.3"
-lazy_static = "1.4.0"
-serde = { version = "1.0", features = ["derive"] }
-```
-
-This module is important because it defines how Tabby Tutorial: Self-Hosted AI Coding Assistant Architecture and Operations implements the patterns covered in this chapter.
+Use the following upstream sources to verify contribution workflow and team adoption details while reading this chapter:
+- [`CONTRIBUTING.md`](https://github.com/TabbyML/tabby/blob/HEAD/CONTRIBUTING.md) — the contributor guide covering how to set up a development environment, run tests, submit pull requests, and follow the project's coding standards.
+- [`Cargo.toml`](https://github.com/TabbyML/tabby/blob/HEAD/Cargo.toml) — the workspace manifest used by contributors to understand the crate layout, add new crates, and manage inter-crate dependencies when extending Tabby.
+
+Suggested trace strategy:
+- read `CONTRIBUTING.md` for the dev environment setup steps (Rust toolchain, LLVM requirements) and the test suite commands
+- review `Cargo.toml` workspace member list to identify where a new feature or integration should be placed
+- check `.github/workflows/` for the CI pipeline to understand what checks must pass before a PR can be merged
## How These Components Connect
```mermaid
-flowchart TD
- A[Cargo]
-```
+flowchart LR
+ A[Contributor forks repo] --> B[CONTRIBUTING.md setup guide]
+ B --> C[Cargo.toml workspace orientation]
+ C --> D[Code changes in appropriate crate]
+ D --> E[CI passes and PR merged]
+```
\ No newline at end of file
diff --git a/tutorials/taskade-docs-tutorial/01-getting-started-and-docs-entry-points.md b/tutorials/taskade-docs-tutorial/01-getting-started-and-docs-entry-points.md
index 3e16f61f..85cd60cb 100644
--- a/tutorials/taskade-docs-tutorial/01-getting-started-and-docs-entry-points.md
+++ b/tutorials/taskade-docs-tutorial/01-getting-started-and-docs-entry-points.md
@@ -52,58 +52,23 @@ You now have an entry-point strategy that matches role and objective.
Next: [Chapter 2: GitBook Structure, Navigation, and Information Architecture](02-gitbook-structure-navigation-and-information-architecture.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `archive/help-center/_imported/CLEANUP_SUMMARY.json`
-
-The `CLEANUP_SUMMARY` module in [`archive/help-center/_imported/CLEANUP_SUMMARY.json`](https://github.com/taskade/docs/blob/HEAD/archive/help-center/_imported/CLEANUP_SUMMARY.json) handles a key part of this chapter's functionality:
-
-```json
-{
- "cleanup_date": "2025-09-14T01:11:04.798Z",
- "total_unique_articles": 1145,
- "duplicates_removed": 0,
- "published_articles": 1057,
- "unpublished_articles": 88,
- "categories": [
- "ai-agents",
- "ai-automation",
- "ai-basics",
- "ai-features",
- "automations",
- "collaboration",
- "essentials",
- "folders",
- "general",
- "genesis",
- "getting-started",
- "integrations",
- "known-urls",
- "mobile",
- "overview",
- "productivity",
- "project-views",
- "projects",
- "sharing",
- "structure",
- "taskade-ai",
- "tasks",
- "templates",
- "tips",
- "workspaces"
- ],
- "published_by_category": {
- "ai-agents": 22,
-```
-
-This module is important because it defines how Taskade Docs Tutorial: Operating the Living-DNA Documentation Stack implements the patterns covered in this chapter.
+Use the following upstream sources to verify docs entry point and navigation details while reading this chapter:
+
+- [`README.md`](https://github.com/taskade/docs/blob/HEAD/README.md) — the root entry point for the Taskade docs repo, containing the primary navigation overview and links to the major documentation sections.
+- [`SUMMARY.md`](https://github.com/taskade/docs/blob/HEAD/SUMMARY.md) — the GitBook navigation manifest that defines the complete document tree, section ordering, and all internal page links.
+Suggested trace strategy:
+- read `README.md` to understand the intended reader journey and which sections are prioritized for new users
+- browse `SUMMARY.md` to map the full navigation structure before diving into individual sections
+- check `.gitbook.yaml` for any redirects or custom config that affects URL resolution
## How These Components Connect
```mermaid
-flowchart TD
- A[CLEANUP_SUMMARY]
-```
+flowchart LR
+ A[New reader arrives] --> B[README.md entry point]
+ B --> C[SUMMARY.md navigation tree]
+ C --> D[Section-specific docs pages]
+```
\ No newline at end of file
diff --git a/tutorials/taskade-docs-tutorial/02-gitbook-structure-navigation-and-information-architecture.md b/tutorials/taskade-docs-tutorial/02-gitbook-structure-navigation-and-information-architecture.md
index 7acd1328..a6a6d631 100644
--- a/tutorials/taskade-docs-tutorial/02-gitbook-structure-navigation-and-information-architecture.md
+++ b/tutorials/taskade-docs-tutorial/02-gitbook-structure-navigation-and-information-architecture.md
@@ -55,58 +55,23 @@ You now understand the navigation control plane and where to enforce consistency
Next: [Chapter 3: Genesis, Workspace DNA, and Living-System Docs Model](03-genesis-workspace-dna-and-living-systems-doc-model.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `archive/help-center/_imported/CLEANUP_SUMMARY.json`
-
-The `CLEANUP_SUMMARY` module in [`archive/help-center/_imported/CLEANUP_SUMMARY.json`](https://github.com/taskade/docs/blob/HEAD/archive/help-center/_imported/CLEANUP_SUMMARY.json) handles a key part of this chapter's functionality:
-
-```json
-{
- "cleanup_date": "2025-09-14T01:11:04.798Z",
- "total_unique_articles": 1145,
- "duplicates_removed": 0,
- "published_articles": 1057,
- "unpublished_articles": 88,
- "categories": [
- "ai-agents",
- "ai-automation",
- "ai-basics",
- "ai-features",
- "automations",
- "collaboration",
- "essentials",
- "folders",
- "general",
- "genesis",
- "getting-started",
- "integrations",
- "known-urls",
- "mobile",
- "overview",
- "productivity",
- "project-views",
- "projects",
- "sharing",
- "structure",
- "taskade-ai",
- "tasks",
- "templates",
- "tips",
- "workspaces"
- ],
- "published_by_category": {
- "ai-agents": 22,
-```
+Use the following upstream sources to verify GitBook structure and navigation details while reading this chapter:
-This module is important because it defines how Taskade Docs Tutorial: Operating the Living-DNA Documentation Stack implements the patterns covered in this chapter.
+- [`SUMMARY.md`](https://github.com/taskade/docs/blob/HEAD/SUMMARY.md) — the canonical GitBook navigation manifest that structures the entire docs site; section headings, page order, and internal links are all controlled here.
+- [`.gitbook.yaml`](https://github.com/taskade/docs/blob/HEAD/.gitbook.yaml) — the GitBook configuration file that specifies the root document, redirects, and any build-level overrides applied to the published site.
+Suggested trace strategy:
+- review `SUMMARY.md` structure to understand how top-level sections, subsections, and leaf pages are organized
+- check `.gitbook.yaml` for redirect rules that indicate pages that have moved and must be kept accessible
+- count section depths in `SUMMARY.md` to identify information architecture choices (breadth vs. depth tradeoffs)
## How These Components Connect
```mermaid
-flowchart TD
- A[CLEANUP_SUMMARY]
-```
+flowchart LR
+ A[.gitbook.yaml config] --> B[SUMMARY.md navigation tree]
+ B --> C[Published GitBook site structure]
+ C --> D[Reader navigation paths]
+```
\ No newline at end of file
diff --git a/tutorials/taskade-docs-tutorial/03-genesis-workspace-dna-and-living-systems-doc-model.md b/tutorials/taskade-docs-tutorial/03-genesis-workspace-dna-and-living-systems-doc-model.md
index c03053b0..ed970275 100644
--- a/tutorials/taskade-docs-tutorial/03-genesis-workspace-dna-and-living-systems-doc-model.md
+++ b/tutorials/taskade-docs-tutorial/03-genesis-workspace-dna-and-living-systems-doc-model.md
@@ -54,58 +54,23 @@ You now have a method for converting conceptual product docs into concrete rollo
Next: [Chapter 4: API Documentation Surface and Endpoint Coverage](04-api-documentation-surface-and-endpoint-coverage.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `archive/help-center/_imported/CLEANUP_SUMMARY.json`
-
-The `CLEANUP_SUMMARY` module in [`archive/help-center/_imported/CLEANUP_SUMMARY.json`](https://github.com/taskade/docs/blob/HEAD/archive/help-center/_imported/CLEANUP_SUMMARY.json) handles a key part of this chapter's functionality:
-
-```json
-{
- "cleanup_date": "2025-09-14T01:11:04.798Z",
- "total_unique_articles": 1145,
- "duplicates_removed": 0,
- "published_articles": 1057,
- "unpublished_articles": 88,
- "categories": [
- "ai-agents",
- "ai-automation",
- "ai-basics",
- "ai-features",
- "automations",
- "collaboration",
- "essentials",
- "folders",
- "general",
- "genesis",
- "getting-started",
- "integrations",
- "known-urls",
- "mobile",
- "overview",
- "productivity",
- "project-views",
- "projects",
- "sharing",
- "structure",
- "taskade-ai",
- "tasks",
- "templates",
- "tips",
- "workspaces"
- ],
- "published_by_category": {
- "ai-agents": 22,
-```
-
-This module is important because it defines how Taskade Docs Tutorial: Operating the Living-DNA Documentation Stack implements the patterns covered in this chapter.
+Use the following upstream sources to verify Genesis and Workspace DNA documentation details while reading this chapter:
+
+- [`README.md`](https://github.com/taskade/docs/blob/HEAD/README.md) — introduces the Living DNA and Genesis concepts at the top level, providing the narrative framing for the entire documentation system.
+- [`SUMMARY.md`](https://github.com/taskade/docs/blob/HEAD/SUMMARY.md) — the navigation manifest; look for the Genesis and Workspace DNA section to understand how these concepts are organized relative to other product pillars.
+Suggested trace strategy:
+- locate the Genesis and Workspace DNA sections in `SUMMARY.md` to understand doc surface coverage
+- cross-reference help center article IDs from the help.taskade.com knowledge base with docs pages to check alignment
+- read the introductory Genesis page to see how the Tree of Life and EVE (Evolving Virtual Environment) metaphors are presented
## How These Components Connect
```mermaid
-flowchart TD
- A[CLEANUP_SUMMARY]
-```
+flowchart LR
+ A[README.md product narrative] --> B[Genesis section in SUMMARY.md]
+ B --> C[Workspace DNA detail pages]
+ C --> D[Help center cross-references]
+```
\ No newline at end of file
diff --git a/tutorials/taskade-docs-tutorial/04-api-documentation-surface-and-endpoint-coverage.md b/tutorials/taskade-docs-tutorial/04-api-documentation-surface-and-endpoint-coverage.md
index fe68ff25..57cd7c58 100644
--- a/tutorials/taskade-docs-tutorial/04-api-documentation-surface-and-endpoint-coverage.md
+++ b/tutorials/taskade-docs-tutorial/04-api-documentation-surface-and-endpoint-coverage.md
@@ -60,58 +60,24 @@ You now have a pragmatic way to consume API docs safely and in the right sequenc
Next: [Chapter 5: AI Agents and Automation Documentation Patterns](05-ai-agents-and-automation-documentation-patterns.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `archive/help-center/_imported/CLEANUP_SUMMARY.json`
-
-The `CLEANUP_SUMMARY` module in [`archive/help-center/_imported/CLEANUP_SUMMARY.json`](https://github.com/taskade/docs/blob/HEAD/archive/help-center/_imported/CLEANUP_SUMMARY.json) handles a key part of this chapter's functionality:
-
-```json
-{
- "cleanup_date": "2025-09-14T01:11:04.798Z",
- "total_unique_articles": 1145,
- "duplicates_removed": 0,
- "published_articles": 1057,
- "unpublished_articles": 88,
- "categories": [
- "ai-agents",
- "ai-automation",
- "ai-basics",
- "ai-features",
- "automations",
- "collaboration",
- "essentials",
- "folders",
- "general",
- "genesis",
- "getting-started",
- "integrations",
- "known-urls",
- "mobile",
- "overview",
- "productivity",
- "project-views",
- "projects",
- "sharing",
- "structure",
- "taskade-ai",
- "tasks",
- "templates",
- "tips",
- "workspaces"
- ],
- "published_by_category": {
- "ai-agents": 22,
-```
-
-This module is important because it defines how Taskade Docs Tutorial: Operating the Living-DNA Documentation Stack implements the patterns covered in this chapter.
+Use the following upstream sources to verify API documentation surface details while reading this chapter:
+
+- [`SUMMARY.md`](https://github.com/taskade/docs/blob/HEAD/SUMMARY.md) — navigate to the API and developer reference sections to understand how endpoint coverage is organized across authentication, workspace, project, task, and agent surfaces.
+- [`README.md`](https://github.com/taskade/docs/blob/HEAD/README.md) — the developer quickstart section points to primary API entry points and links to the `developers.taskade.com` reference site.
+Suggested trace strategy:
+- scan the API sections in `SUMMARY.md` to assess breadth of endpoint coverage
+- compare the docs API surface against the live `developers.taskade.com` OpenAPI spec to identify gaps
+- check if webhook documentation, pagination patterns, and error codes are covered in separate dedicated pages
## How These Components Connect
```mermaid
-flowchart TD
- A[CLEANUP_SUMMARY]
-```
+flowchart LR
+ A[Developer reader] --> B[README.md quickstart]
+ B --> C[API section in SUMMARY.md]
+ C --> D[Endpoint reference pages]
+ D --> E[developers.taskade.com full spec]
+```
\ No newline at end of file
diff --git a/tutorials/taskade-docs-tutorial/05-ai-agents-and-automation-documentation-patterns.md b/tutorials/taskade-docs-tutorial/05-ai-agents-and-automation-documentation-patterns.md
index 90e9f1b3..94764f36 100644
--- a/tutorials/taskade-docs-tutorial/05-ai-agents-and-automation-documentation-patterns.md
+++ b/tutorials/taskade-docs-tutorial/05-ai-agents-and-automation-documentation-patterns.md
@@ -55,58 +55,24 @@ You now have a repeatable pattern to combine agent and automation docs into exec
Next: [Chapter 6: Release Notes, Changelog, and Timeline Operations](06-release-notes-changelog-and-timeline-operations.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `archive/help-center/_imported/CLEANUP_SUMMARY.json`
-
-The `CLEANUP_SUMMARY` module in [`archive/help-center/_imported/CLEANUP_SUMMARY.json`](https://github.com/taskade/docs/blob/HEAD/archive/help-center/_imported/CLEANUP_SUMMARY.json) handles a key part of this chapter's functionality:
-
-```json
-{
- "cleanup_date": "2025-09-14T01:11:04.798Z",
- "total_unique_articles": 1145,
- "duplicates_removed": 0,
- "published_articles": 1057,
- "unpublished_articles": 88,
- "categories": [
- "ai-agents",
- "ai-automation",
- "ai-basics",
- "ai-features",
- "automations",
- "collaboration",
- "essentials",
- "folders",
- "general",
- "genesis",
- "getting-started",
- "integrations",
- "known-urls",
- "mobile",
- "overview",
- "productivity",
- "project-views",
- "projects",
- "sharing",
- "structure",
- "taskade-ai",
- "tasks",
- "templates",
- "tips",
- "workspaces"
- ],
- "published_by_category": {
- "ai-agents": 22,
-```
+Use the following upstream sources to verify AI agent and automation documentation details while reading this chapter:
-This module is important because it defines how Taskade Docs Tutorial: Operating the Living-DNA Documentation Stack implements the patterns covered in this chapter.
+- [`SUMMARY.md`](https://github.com/taskade/docs/blob/HEAD/SUMMARY.md) — navigate to the AI Agents and Automations sections to see how these two capability pillars are separated and cross-linked in the documentation tree.
+- [`README.md`](https://github.com/taskade/docs/blob/HEAD/README.md) — the main product narrative that positions AI agents (Intelligence pillar) and Automations (Execution pillar) relative to other platform capabilities.
+Suggested trace strategy:
+- identify the AI Agents and Automations leaf pages in `SUMMARY.md` to assess documentation depth per feature
+- check whether trigger/action/condition concepts appear in both the automation docs and the agent training docs for consistency
+- compare docs coverage against the `help.taskade.com` articles for agents and automations to spot content drift
## How These Components Connect
```mermaid
-flowchart TD
- A[CLEANUP_SUMMARY]
-```
+flowchart LR
+ A[AI Agents section in SUMMARY.md] --> B[Agent creation and training pages]
+ C[Automations section in SUMMARY.md] --> D[Trigger and action reference pages]
+ B --> E[Cross-links between agents and automations]
+ D --> E
+```
\ No newline at end of file
diff --git a/tutorials/taskade-docs-tutorial/06-release-notes-changelog-and-timeline-operations.md b/tutorials/taskade-docs-tutorial/06-release-notes-changelog-and-timeline-operations.md
index aea03394..d9cb57ee 100644
--- a/tutorials/taskade-docs-tutorial/06-release-notes-changelog-and-timeline-operations.md
+++ b/tutorials/taskade-docs-tutorial/06-release-notes-changelog-and-timeline-operations.md
@@ -67,58 +67,24 @@ You now have a process to turn docs updates into controlled operational change.
Next: [Chapter 7: Doc Quality Governance and Link Hygiene](07-doc-quality-governance-and-link-hygiene.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `archive/help-center/_imported/CLEANUP_SUMMARY.json`
-
-The `CLEANUP_SUMMARY` module in [`archive/help-center/_imported/CLEANUP_SUMMARY.json`](https://github.com/taskade/docs/blob/HEAD/archive/help-center/_imported/CLEANUP_SUMMARY.json) handles a key part of this chapter's functionality:
-
-```json
-{
- "cleanup_date": "2025-09-14T01:11:04.798Z",
- "total_unique_articles": 1145,
- "duplicates_removed": 0,
- "published_articles": 1057,
- "unpublished_articles": 88,
- "categories": [
- "ai-agents",
- "ai-automation",
- "ai-basics",
- "ai-features",
- "automations",
- "collaboration",
- "essentials",
- "folders",
- "general",
- "genesis",
- "getting-started",
- "integrations",
- "known-urls",
- "mobile",
- "overview",
- "productivity",
- "project-views",
- "projects",
- "sharing",
- "structure",
- "taskade-ai",
- "tasks",
- "templates",
- "tips",
- "workspaces"
- ],
- "published_by_category": {
- "ai-agents": 22,
-```
-
-This module is important because it defines how Taskade Docs Tutorial: Operating the Living-DNA Documentation Stack implements the patterns covered in this chapter.
+Use the following upstream sources to verify release notes and changelog details while reading this chapter:
+
+- [`SUMMARY.md`](https://github.com/taskade/docs/blob/HEAD/SUMMARY.md) — navigate to the changelog or release notes section to understand how release cadence and version history are documented and organized.
+- [`README.md`](https://github.com/taskade/docs/blob/HEAD/README.md) — may include a link to the changelog or a version history overview that anchors how updates are surfaced to documentation readers.
+Suggested trace strategy:
+- find the release/changelog section in `SUMMARY.md` to check release note frequency and coverage depth
+- compare docs release notes against the `taskade.com/changelog` product site for alignment
+- check whether breaking API changes are flagged differently from feature additions in the release notes format
## How These Components Connect
```mermaid
-flowchart TD
- A[CLEANUP_SUMMARY]
-```
+flowchart LR
+ A[Product release event] --> B[Changelog entry created]
+ B --> C[Release notes page in SUMMARY.md tree]
+ C --> D[Timeline section updated]
+ D --> E[Reader visible at taskade.com/changelog]
+```
\ No newline at end of file
diff --git a/tutorials/taskade-docs-tutorial/07-doc-quality-governance-and-link-hygiene.md b/tutorials/taskade-docs-tutorial/07-doc-quality-governance-and-link-hygiene.md
index 4026cb39..49f51091 100644
--- a/tutorials/taskade-docs-tutorial/07-doc-quality-governance-and-link-hygiene.md
+++ b/tutorials/taskade-docs-tutorial/07-doc-quality-governance-and-link-hygiene.md
@@ -55,58 +55,24 @@ You now have a governance baseline to protect documentation trust at scale.
Next: [Chapter 8: Contribution Workflow and Docs Operations Playbook](08-contribution-workflow-and-docs-operations-playbook.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `archive/help-center/_imported/CLEANUP_SUMMARY.json`
-
-The `CLEANUP_SUMMARY` module in [`archive/help-center/_imported/CLEANUP_SUMMARY.json`](https://github.com/taskade/docs/blob/HEAD/archive/help-center/_imported/CLEANUP_SUMMARY.json) handles a key part of this chapter's functionality:
-
-```json
-{
- "cleanup_date": "2025-09-14T01:11:04.798Z",
- "total_unique_articles": 1145,
- "duplicates_removed": 0,
- "published_articles": 1057,
- "unpublished_articles": 88,
- "categories": [
- "ai-agents",
- "ai-automation",
- "ai-basics",
- "ai-features",
- "automations",
- "collaboration",
- "essentials",
- "folders",
- "general",
- "genesis",
- "getting-started",
- "integrations",
- "known-urls",
- "mobile",
- "overview",
- "productivity",
- "project-views",
- "projects",
- "sharing",
- "structure",
- "taskade-ai",
- "tasks",
- "templates",
- "tips",
- "workspaces"
- ],
- "published_by_category": {
- "ai-agents": 22,
-```
-
-This module is important because it defines how Taskade Docs Tutorial: Operating the Living-DNA Documentation Stack implements the patterns covered in this chapter.
+Use the following upstream sources to verify doc quality governance details while reading this chapter:
+
+- [`SUMMARY.md`](https://github.com/taskade/docs/blob/HEAD/SUMMARY.md) — the source of truth for all internal navigation links; broken or mismatched entries here produce broken navigation across the entire docs site.
+- [`.gitbook.yaml`](https://github.com/taskade/docs/blob/HEAD/.gitbook.yaml) — contains redirect definitions that must be maintained when pages are renamed or moved to preserve URL consistency for external links.
+Suggested trace strategy:
+- audit `SUMMARY.md` for orphaned entries (pages listed but files missing) and missing entries (files present but not listed)
+- check `.gitbook.yaml` redirects against current `SUMMARY.md` structure to identify stale redirect rules
+- scan doc pages for external links to `help.taskade.com` and `developers.taskade.com` that may have drifted
## How These Components Connect
```mermaid
-flowchart TD
- A[CLEANUP_SUMMARY]
-```
+flowchart LR
+ A[SUMMARY.md navigation links] --> B[Link hygiene audit]
+ C[.gitbook.yaml redirects] --> B
+ B --> D[Broken link report]
+ D --> E[Fix or remove stale references]
+```
\ No newline at end of file
diff --git a/tutorials/taskade-docs-tutorial/08-contribution-workflow-and-docs-operations-playbook.md b/tutorials/taskade-docs-tutorial/08-contribution-workflow-and-docs-operations-playbook.md
index b5adc916..b847b864 100644
--- a/tutorials/taskade-docs-tutorial/08-contribution-workflow-and-docs-operations-playbook.md
+++ b/tutorials/taskade-docs-tutorial/08-contribution-workflow-and-docs-operations-playbook.md
@@ -53,58 +53,24 @@ You now have a complete framework for onboarding, evaluating, and operating the
Natural next step: pair this with [Taskade MCP Tutorial](../taskade-mcp-tutorial/) to align docs governance with integration runtime workflows.
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `archive/help-center/_imported/CLEANUP_SUMMARY.json`
-
-The `CLEANUP_SUMMARY` module in [`archive/help-center/_imported/CLEANUP_SUMMARY.json`](https://github.com/taskade/docs/blob/HEAD/archive/help-center/_imported/CLEANUP_SUMMARY.json) handles a key part of this chapter's functionality:
-
-```json
-{
- "cleanup_date": "2025-09-14T01:11:04.798Z",
- "total_unique_articles": 1145,
- "duplicates_removed": 0,
- "published_articles": 1057,
- "unpublished_articles": 88,
- "categories": [
- "ai-agents",
- "ai-automation",
- "ai-basics",
- "ai-features",
- "automations",
- "collaboration",
- "essentials",
- "folders",
- "general",
- "genesis",
- "getting-started",
- "integrations",
- "known-urls",
- "mobile",
- "overview",
- "productivity",
- "project-views",
- "projects",
- "sharing",
- "structure",
- "taskade-ai",
- "tasks",
- "templates",
- "tips",
- "workspaces"
- ],
- "published_by_category": {
- "ai-agents": 22,
-```
-
-This module is important because it defines how Taskade Docs Tutorial: Operating the Living-DNA Documentation Stack implements the patterns covered in this chapter.
+Use the following upstream sources to verify contribution workflow and docs operations details while reading this chapter:
+
+- [`README.md`](https://github.com/taskade/docs/blob/HEAD/README.md) — contains contributing guidelines, the branching model for docs PRs, and the review process for documentation changes.
+- [`SUMMARY.md`](https://github.com/taskade/docs/blob/HEAD/SUMMARY.md) — the file that contributors must update when adding new pages; understanding its structure is prerequisite to contributing correctly.
+Suggested trace strategy:
+- read the contribution section of `README.md` to understand the PR workflow and review expectations
+- check if a `CONTRIBUTING.md` file exists for more detailed contribution standards
+- review `.github/workflows/` if present for any automated checks that run on docs PRs (link checking, spell checking)
## How These Components Connect
```mermaid
-flowchart TD
- A[CLEANUP_SUMMARY]
-```
+flowchart LR
+ A[Contributor opens PR] --> B[README.md contribution guidelines]
+ B --> C[SUMMARY.md updated for new pages]
+ C --> D[Automated CI checks if present]
+ D --> E[Reviewer approves and merges]
+```
\ No newline at end of file
diff --git a/tutorials/taskade-mcp-tutorial/01-getting-started-and-first-client-connection.md b/tutorials/taskade-mcp-tutorial/01-getting-started-and-first-client-connection.md
index 555da2e7..0dbaa193 100644
--- a/tutorials/taskade-mcp-tutorial/01-getting-started-and-first-client-connection.md
+++ b/tutorials/taskade-mcp-tutorial/01-getting-started-and-first-client-connection.md
@@ -88,55 +88,53 @@ You now have a working Taskade MCP connection in at least one client mode.
Next: [Chapter 2: Repository Architecture and Package Layout](02-repository-architecture-and-package-layout.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `packages/openapi-codegen/src/openapi.ts`
+### `packages/server/src/server.ts`
-The `if` interface in [`packages/openapi-codegen/src/openapi.ts`](https://github.com/taskade/mcp/blob/HEAD/packages/openapi-codegen/src/openapi.ts) handles a key part of this chapter's functionality:
+The `TaskadeMCPServer` class in [`packages/server/src/server.ts`](https://github.com/taskade/mcp/blob/HEAD/packages/server/src/server.ts) handles a key part of this chapter's functionality:
```ts
- response: OpenAPIV3.ResponseObject | OpenAPIV3.ReferenceObject,
-): OpenAPIV3.ResponseObject => {
- if ('$ref' in response) {
- throw new Error('Reference not supported');
- }
-
- return response;
};
-export const convertOpenApiSchemaToJsonSchema = (
- schema: OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject,
-): IJsonSchema => {
- if ('$ref' in schema) {
- // Should already be dereferenced
- throw new Error('Reference not supported');
- }
-
- const jsonSchema: IJsonSchema = {};
-
- // Handle basic properties
- if (schema.type) {
- jsonSchema.type = schema.type;
- }
-
- if (schema.description) {
- jsonSchema.description = schema.description;
- }
-
- if (schema.default !== undefined) {
- jsonSchema.default = schema.default;
- }
-
+export class TaskadeMCPServer extends McpServer {
+ readonly config: TaskadeServerOpts;
+
+ constructor(opts: TaskadeServerOpts) {
+ super({
+ name: 'taskade',
+ version: '0.0.1',
+ capabilities: {
+ resources: {},
+ tools: {},
+ },
+ });
+
+ this.config = opts;
+
+ setupTools(this, {
+ url: 'https://www.taskade.com/api/v1',
+ fetch,
+ headers: {
+ Authorization: `Bearer ${this.config.accessToken}`,
+ },
+ normalizeResponse: {
+ folderProjectsGet: (response) => {
+ return {
+ content: [
+ {
+ type: 'text',
+ text: JSON.stringify(response),
+ },
+ {
```
-This interface is important because it defines how Taskade MCP Tutorial: OpenAPI-Driven MCP Server for Taskade Workflows implements the patterns covered in this chapter.
+This class is important because it defines how Taskade MCP Tutorial: OpenAPI-Driven MCP Server for Taskade Workflows implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[if]
+ A[TaskadeMCPServer]
```
diff --git a/tutorials/taskade-mcp-tutorial/02-repository-architecture-and-package-layout.md b/tutorials/taskade-mcp-tutorial/02-repository-architecture-and-package-layout.md
index 325a40d6..f4484efa 100644
--- a/tutorials/taskade-mcp-tutorial/02-repository-architecture-and-package-layout.md
+++ b/tutorials/taskade-mcp-tutorial/02-repository-architecture-and-package-layout.md
@@ -86,47 +86,45 @@ You now know where generation happens, where runtime happens, and which scripts
Next: [Chapter 3: MCP Server Tools, Auth, and API Surface](03-mcp-server-tools-auth-and-api-surface.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `packages/server/src/server.ts`
+### `packages/server/src/tools.generated.ts`
-The `TaskadeMCPServer` class in [`packages/server/src/server.ts`](https://github.com/taskade/mcp/blob/HEAD/packages/server/src/server.ts) handles a key part of this chapter's functionality:
+The `OpenAPIToolRuntimeConfig` class in [`packages/server/src/tools.generated.ts`](https://github.com/taskade/mcp/blob/HEAD/packages/server/src/tools.generated.ts) handles a key part of this chapter's functionality:
```ts
};
-export class TaskadeMCPServer extends McpServer {
- readonly config: TaskadeServerOpts;
+export type OpenAPIToolRuntimeConfigOpts = {
+ // basic configuration
+ url?: string;
+ fetch?: (...args: any[]) => Promise<any>;
+ headers?: Record<string, string>;
- constructor(opts: TaskadeServerOpts) {
- super({
- name: 'taskade',
- version: '0.0.1',
- capabilities: {
- resources: {},
- tools: {},
- },
- });
+ // custom implementation of the tool call
+ executeToolCall?: ExecuteToolCallOpenApiOperationCb;
+ normalizeResponse?: Record<string, (response: any) => CallToolResult>;
+};
- this.config = opts;
+export class OpenAPIToolRuntimeConfig {
+ config: OpenAPIToolRuntimeConfigOpts;
- setupTools(this, {
- url: 'https://www.taskade.com/api/v1',
- fetch,
+ constructor(config: OpenAPIToolRuntimeConfigOpts) {
+ this.config = config;
+ }
+
+ private async defaultExecuteToolCall(payload: ExecuteToolCallOpenApiOperationCbPayload) {
+ const response = await this.fetch(`${this.baseUrl}${payload.url}`, {
+ method: payload.method,
+ body: payload.body,
headers: {
- Authorization: `Bearer ${this.config.accessToken}`,
+ ...payload.headers,
+ ...this.config.headers,
},
- normalizeResponse: {
- folderProjectsGet: (response) => {
- return {
- content: [
- {
- type: 'text',
- text: JSON.stringify(response),
- },
- {
+ });
+
+ return await response.json();
+ }
```
This class is important because it defines how Taskade MCP Tutorial: OpenAPI-Driven MCP Server for Taskade Workflows implements the patterns covered in this chapter.
@@ -136,5 +134,5 @@ This class is important because it defines how Taskade MCP Tutorial: OpenAPI-Dri
```mermaid
flowchart TD
- A[TaskadeMCPServer]
+ A[OpenAPIToolRuntimeConfig]
```
diff --git a/tutorials/taskade-mcp-tutorial/03-mcp-server-tools-auth-and-api-surface.md b/tutorials/taskade-mcp-tutorial/03-mcp-server-tools-auth-and-api-surface.md
index a2fefc12..89ffb218 100644
--- a/tutorials/taskade-mcp-tutorial/03-mcp-server-tools-auth-and-api-surface.md
+++ b/tutorials/taskade-mcp-tutorial/03-mcp-server-tools-auth-and-api-surface.md
@@ -75,55 +75,53 @@ You now understand how Taskade MCP tool domains and auth context map into runtim
Next: [Chapter 4: OpenAPI to MCP Codegen Pipeline](04-openapi-to-mcp-codegen-pipeline.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `packages/server/src/tools.generated.ts`
-The `OpenAPIToolRuntimeConfig` class in [`packages/server/src/tools.generated.ts`](https://github.com/taskade/mcp/blob/HEAD/packages/server/src/tools.generated.ts) handles a key part of this chapter's functionality:
+The `toQueryParams` function in [`packages/server/src/tools.generated.ts`](https://github.com/taskade/mcp/blob/HEAD/packages/server/src/tools.generated.ts) handles a key part of this chapter's functionality:
```ts
-};
+) => Promise<any>;
-export type OpenAPIToolRuntimeConfigOpts = {
- // basic configuration
- url?: string;
- fetch?: (...args: any[]) => Promise<any>;
- headers?: Record<string, string>;
+function toQueryParams(obj: Record<string, any>): string {
+ const params = new URLSearchParams();
- // custom implementation of the tool call
- executeToolCall?: ExecuteToolCallOpenApiOperationCb;
- normalizeResponse?: Record<string, (response: any) => CallToolResult>;
-};
+ for (const key in obj) {
+ const value = obj[key];
-export class OpenAPIToolRuntimeConfig {
- config: OpenAPIToolRuntimeConfigOpts;
+ if (value == null) {
+ continue;
+ }
- constructor(config: OpenAPIToolRuntimeConfigOpts) {
- this.config = config;
+ if (Array.isArray(value)) {
+ value.forEach((v) => params.append(key, String(v)));
+ } else if (typeof value === 'object') {
+ params.append(key, JSON.stringify(value));
+ } else {
+ params.append(key, String(value));
+ }
}
- private async defaultExecuteToolCall(payload: ExecuteToolCallOpenApiOperationCbPayload) {
- const response = await this.fetch(`${this.baseUrl}${payload.url}`, {
- method: payload.method,
- body: payload.body,
- headers: {
- ...payload.headers,
- ...this.config.headers,
- },
- });
-
- return await response.json();
+ const str = params.toString();
+
+ if (str === '') {
+ return '';
}
+
+ return `?${str}`;
+}
+
+export const prepareToolCallOperation = (
+ operation: ToolCallOpenApiOperation,
```
-This class is important because it defines how Taskade MCP Tutorial: OpenAPI-Driven MCP Server for Taskade Workflows implements the patterns covered in this chapter.
+This function is important because it defines how Taskade MCP Tutorial: OpenAPI-Driven MCP Server for Taskade Workflows implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[OpenAPIToolRuntimeConfig]
+ A[toQueryParams]
```
diff --git a/tutorials/taskade-mcp-tutorial/04-openapi-to-mcp-codegen-pipeline.md b/tutorials/taskade-mcp-tutorial/04-openapi-to-mcp-codegen-pipeline.md
index 56f635ae..ac1afeb1 100644
--- a/tutorials/taskade-mcp-tutorial/04-openapi-to-mcp-codegen-pipeline.md
+++ b/tutorials/taskade-mcp-tutorial/04-openapi-to-mcp-codegen-pipeline.md
@@ -72,55 +72,53 @@ You now have a repeatable pattern to regenerate MCP tools from OpenAPI updates.
Next: [Chapter 5: Client Integration Across Claude, Cursor, Windsurf, and n8n](05-client-integration-across-claude-cursor-windsurf-and-n8n.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `packages/server/src/tools.generated.ts`
+### `packages/openapi-codegen/src/openapi.ts`
-The `toQueryParams` function in [`packages/server/src/tools.generated.ts`](https://github.com/taskade/mcp/blob/HEAD/packages/server/src/tools.generated.ts) handles a key part of this chapter's functionality:
+The `if` interface in [`packages/openapi-codegen/src/openapi.ts`](https://github.com/taskade/mcp/blob/HEAD/packages/openapi-codegen/src/openapi.ts) handles a key part of this chapter's functionality:
```ts
-) => Promise<any>;
+ response: OpenAPIV3.ResponseObject | OpenAPIV3.ReferenceObject,
+): OpenAPIV3.ResponseObject => {
+ if ('$ref' in response) {
+ throw new Error('Reference not supported');
+ }
-function toQueryParams(obj: Record<string, any>): string {
- const params = new URLSearchParams();
+ return response;
+};
- for (const key in obj) {
- const value = obj[key];
+export const convertOpenApiSchemaToJsonSchema = (
+ schema: OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject,
+): IJsonSchema => {
+ if ('$ref' in schema) {
+ // Should already be dereferenced
+ throw new Error('Reference not supported');
+ }
- if (value == null) {
- continue;
- }
+ const jsonSchema: IJsonSchema = {};
- if (Array.isArray(value)) {
- value.forEach((v) => params.append(key, String(v)));
- } else if (typeof value === 'object') {
- params.append(key, JSON.stringify(value));
- } else {
- params.append(key, String(value));
- }
+ // Handle basic properties
+ if (schema.type) {
+ jsonSchema.type = schema.type;
}
- const str = params.toString();
-
- if (str === '') {
- return '';
+ if (schema.description) {
+ jsonSchema.description = schema.description;
}
- return `?${str}`;
-}
+ if (schema.default !== undefined) {
+ jsonSchema.default = schema.default;
+ }
-export const prepareToolCallOperation = (
- operation: ToolCallOpenApiOperation,
```
-This function is important because it defines how Taskade MCP Tutorial: OpenAPI-Driven MCP Server for Taskade Workflows implements the patterns covered in this chapter.
+This interface is important because it defines how Taskade MCP Tutorial: OpenAPI-Driven MCP Server for Taskade Workflows implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[toQueryParams]
+ A[if]
```
diff --git a/tutorials/taskade-mcp-tutorial/05-client-integration-across-claude-cursor-windsurf-and-n8n.md b/tutorials/taskade-mcp-tutorial/05-client-integration-across-claude-cursor-windsurf-and-n8n.md
index 6a25d7d4..eb154ea3 100644
--- a/tutorials/taskade-mcp-tutorial/05-client-integration-across-claude-cursor-windsurf-and-n8n.md
+++ b/tutorials/taskade-mcp-tutorial/05-client-integration-across-claude-cursor-windsurf-and-n8n.md
@@ -69,8 +69,6 @@ You now have a clear client integration strategy with transport and validation p
Next: [Chapter 6: Deployment, Configuration, and Operations](06-deployment-configuration-and-operations.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `packages/openapi-codegen/src/runtime.ts`
diff --git a/tutorials/taskade-mcp-tutorial/06-deployment-configuration-and-operations.md b/tutorials/taskade-mcp-tutorial/06-deployment-configuration-and-operations.md
index e504342b..de798a98 100644
--- a/tutorials/taskade-mcp-tutorial/06-deployment-configuration-and-operations.md
+++ b/tutorials/taskade-mcp-tutorial/06-deployment-configuration-and-operations.md
@@ -67,8 +67,6 @@ You now have a deployment and operations baseline that supports shared-team adop
Next: [Chapter 7: Security Guardrails and Governance](07-security-guardrails-and-governance.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `packages/openapi-codegen/src/runtime.ts`
diff --git a/tutorials/taskade-mcp-tutorial/07-security-guardrails-and-governance.md b/tutorials/taskade-mcp-tutorial/07-security-guardrails-and-governance.md
index b022494b..1a84cdbe 100644
--- a/tutorials/taskade-mcp-tutorial/07-security-guardrails-and-governance.md
+++ b/tutorials/taskade-mcp-tutorial/07-security-guardrails-and-governance.md
@@ -60,8 +60,6 @@ You now have a governance model that keeps Taskade MCP useful without sacrificin
Next: [Chapter 8: Contribution, Testing, and Release Operations](08-contribution-testing-and-release-operations.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `packages/server/src/cli.ts`
diff --git a/tutorials/taskade-mcp-tutorial/08-contribution-testing-and-release-operations.md b/tutorials/taskade-mcp-tutorial/08-contribution-testing-and-release-operations.md
index 8706a6d2..5ea52fa6 100644
--- a/tutorials/taskade-mcp-tutorial/08-contribution-testing-and-release-operations.md
+++ b/tutorials/taskade-mcp-tutorial/08-contribution-testing-and-release-operations.md
@@ -72,8 +72,6 @@ You now have a full production-oriented lifecycle for adopting and maintaining T
Natural next step: cross-link this with your workspace/Genesis governance patterns from [Taskade Tutorial](../taskade-tutorial/).
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `packages/server/src/cli.ts`
diff --git a/tutorials/teable-tutorial/04-api-development.md b/tutorials/teable-tutorial/04-api-development.md
index 3672c0b2..a5abbbe2 100644
--- a/tutorials/teable-tutorial/04-api-development.md
+++ b/tutorials/teable-tutorial/04-api-development.md
@@ -6,6 +6,7 @@ has_children: false
parent: "Teable Database Platform"
---
+
# Chapter 4: API Development
Welcome to **Chapter 4: API Development**. In this part of **Teable: Deep Dive Tutorial**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
@@ -89,502 +90,111 @@ Suggested trace strategy:
## Depth Expansion Playbook
-<!-- depth-expansion-v2 -->
-
-This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
-
-### Strategic Context
-
-- tutorial: **Teable: Deep Dive Tutorial**
-- tutorial slug: **teable-tutorial**
-- chapter focus: **Chapter 4: API Development**
-- system context: **Teable Database Platform**
-- objective: move from surface-level usage to repeatable engineering operation
-
-### Architecture Decomposition
-
-1. Define the runtime boundary for `Chapter 4: API Development`.
-2. Separate control-plane decisions from data-plane execution.
-3. Capture input contracts, transformation points, and output contracts.
-4. Trace state transitions across request lifecycle stages.
-5. Identify extension hooks and policy interception points.
-6. Map ownership boundaries for team and automation workflows.
-7. Specify rollback and recovery paths for unsafe changes.
-8. Track observability signals for correctness, latency, and cost.
-
-### Operator Decision Matrix
-
-| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
-|:--------------|:--------------|:------------------|:---------|
-| Runtime mode | managed defaults | explicit policy config | speed vs control |
-| State handling | local ephemeral | durable persisted state | simplicity vs auditability |
-| Tool integration | direct API use | mediated adapter layer | velocity vs governance |
-| Rollout method | manual change | staged + canary rollout | effort vs safety |
-| Incident response | best effort logs | runbooks + SLO alerts | cost vs reliability |
-
-### Failure Modes and Countermeasures
-
-| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
-|:-------------|:-------------|:-------------------|:---------------|
-| stale context | inconsistent outputs | missing refresh window | enforce context TTL and refresh hooks |
-| policy drift | unexpected execution | ad hoc overrides | centralize policy profiles |
-| auth mismatch | 401/403 bursts | credential sprawl | rotation schedule + scope minimization |
-| schema breakage | parser/validation errors | unmanaged upstream changes | contract tests per release |
-| retry storms | queue congestion | no backoff controls | jittered backoff + circuit breakers |
-| silent regressions | quality drop without alerts | weak baseline metrics | eval harness with thresholds |
-
-### Implementation Runbook
-
-1. Establish a reproducible baseline environment.
-2. Capture chapter-specific success criteria before changes.
-3. Implement minimal viable path with explicit interfaces.
-4. Add observability before expanding feature scope.
-5. Run deterministic tests for happy-path behavior.
-6. Inject failure scenarios for negative-path validation.
-7. Compare output quality against baseline snapshots.
-8. Promote through staged environments with rollback gates.
-9. Record operational lessons in release notes.
-
-### Quality Gate Checklist
-
-- [ ] chapter-level assumptions are explicit and testable
-- [ ] API/tool boundaries are documented with input/output examples
-- [ ] failure handling includes retry, timeout, and fallback policy
-- [ ] security controls include auth scopes and secret rotation plans
-- [ ] observability includes logs, metrics, traces, and alert thresholds
-- [ ] deployment guidance includes canary and rollback paths
-- [ ] docs include links to upstream sources and related tracks
-- [ ] post-release verification confirms expected behavior under load
-
-### Source Alignment
-
-- [Teable](https://github.com/teableio/teable)
-- [AI Codebase Knowledge Builder](https://github.com/The-Pocket/Tutorial-Codebase-Knowledge)
-
-### Cross-Tutorial Connection Map
-
-- Related tutorials are listed in this tutorial index.
-
-### Advanced Practice Exercises
-
-1. Build a minimal end-to-end implementation for `Chapter 4: API Development`.
-2. Add instrumentation and measure baseline latency and error rate.
-3. Introduce one controlled failure and confirm graceful recovery.
-4. Add policy constraints and verify they are enforced consistently.
-5. Run a staged rollout and document rollback decision criteria.
-
-### Review Questions
-
-1. Which execution boundary matters most for this chapter and why?
-2. What signal detects regressions earliest in your environment?
-3. What tradeoff did you make between delivery speed and governance?
-4. How would you recover from the highest-impact failure mode?
-5. What must be automated before scaling to team-wide adoption?
-
-### Scenario Playbook 1: Chapter 4: API Development
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 2: Chapter 4: API Development
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 3: Chapter 4: API Development
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 4: Chapter 4: API Development
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 5: Chapter 4: API Development
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 6: Chapter 4: API Development
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 7: Chapter 4: API Development
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 8: Chapter 4: API Development
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 9: Chapter 4: API Development
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 10: Chapter 4: API Development
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 11: Chapter 4: API Development
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 12: Chapter 4: API Development
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 13: Chapter 4: API Development
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 14: Chapter 4: API Development
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 15: Chapter 4: API Development
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 16: Chapter 4: API Development
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 17: Chapter 4: API Development
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 18: Chapter 4: API Development
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 19: Chapter 4: API Development
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 20: Chapter 4: API Development
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 21: Chapter 4: API Development
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 22: Chapter 4: API Development
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 23: Chapter 4: API Development
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 24: Chapter 4: API Development
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 25: Chapter 4: API Development
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 26: Chapter 4: API Development
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 27: Chapter 4: API Development
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 28: Chapter 4: API Development
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 29: Chapter 4: API Development
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 30: Chapter 4: API Development
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 31: Chapter 4: API Development
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 32: Chapter 4: API Development
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 33: Chapter 4: API Development
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 34: Chapter 4: API Development
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
+## Source Code Walkthrough
+
+### `.ncurc.yml`
+
+The `.ncurc` module in [`.ncurc.yml`](https://github.com/teableio/teable/blob/HEAD/.ncurc.yml) handles a key part of this chapter's functionality:
+
+```yml
+# npm-check-updates configuration used by yarn deps:check && yarn deps:update
+# convenience scripts.
+# @link https://github.com/raineorshine/npm-check-updates
+
+# Add here exclusions on packages if any
+reject: [
+ 'vite-plugin-svgr',
+
+ # Too early cause in esm
+ 'is-port-reachable',
+ 'nanoid',
+ 'node-fetch',
+ ]
+
+```
+
+This module is important because it defines how Teable: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+### `tsconfig.base.json`
+
+The `tsconfig.base` module in [`tsconfig.base.json`](https://github.com/teableio/teable/blob/HEAD/tsconfig.base.json) handles a key part of this chapter's functionality:
+
+```json
+{
+ "$schema": "https://json.schemastore.org/tsconfig",
+ "compilerOptions": {
+ "strict": true,
+ "useUnknownInCatchVariables": true,
+ "allowJs": true,
+ "skipLibCheck": true,
+ "forceConsistentCasingInFileNames": true,
+ "noEmit": true,
+ "esModuleInterop": true,
+ "moduleResolution": "node",
+ "resolveJsonModule": true,
+ "isolatedModules": true,
+ "incremental": true,
+ "newLine": "lf"
+ },
+ "exclude": ["**/node_modules", "**/.*/"]
+}
+
+```
+
+This module is important because it defines how Teable: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+### `package.json`
+
+The `package` module in [`package.json`](https://github.com/teableio/teable/blob/HEAD/package.json) handles a key part of this chapter's functionality:
+
+```json
+{
+ "name": "@teable/teable",
+ "version": "1.10.0",
+ "license": "AGPL-3.0",
+ "private": true,
+ "homepage": "https://github.com/teableio/teable",
+ "repository": {
+ "type": "git",
+ "url": "https://github.com/teableio/teable"
+ },
+ "author": {
+ "name": "tea artist",
+ "url": "https://github.com/tea-artist"
+ },
+ "keywords": [
+ "teable",
+ "database"
+ ],
+ "workspaces": [
+ "apps/*",
+ "packages/*",
+ "packages/v2/*",
+ "plugins",
+ "!apps/electron"
+ ],
+ "scripts": {
+ "clean:global-cache": "rimraf ./.cache",
+ "deps:check": "pnpm --package=npm-check-updates@latest dlx npm-check-updates --configFileName .ncurc.yml --workspaces --root --mergeConfig",
+ "deps:update": "pnpm --package=npm-check-updates@latest dlx npm-check-updates --configFileName .ncurc.yml -u --workspaces --root --mergeConfig",
+ "dev:v2": "pnpm -r --parallel --stream -F @teable/formula -F './packages/v2/*' dev",
+ "clean:v2": "pnpm -r --parallel --stream -F @teable/formula -F './packages/v2/*' clean",
+ "build:v2": "pnpm -r --parallel --stream -F @teable/formula -F './packages/v2/*' build",
+ "build:packages": "pnpm -r -F './packages/**' build",
+ "g:build": "pnpm -r run build",
+ "g:build-changed": "pnpm -r -F '...[origin/main]' build",
+```
+
+This module is important because it defines how Teable: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+
+## How These Components Connect
+
+```mermaid
+flowchart TD
+ A[.ncurc]
+ B[tsconfig.base]
+ C[package]
+ A --> B
+ B --> C
+```
diff --git a/tutorials/teable-tutorial/05-realtime-collaboration.md b/tutorials/teable-tutorial/05-realtime-collaboration.md
index dfc57a55..5b5bc55a 100644
--- a/tutorials/teable-tutorial/05-realtime-collaboration.md
+++ b/tutorials/teable-tutorial/05-realtime-collaboration.md
@@ -6,6 +6,7 @@ has_children: false
parent: "Teable Database Platform"
---
+
# Chapter 5: Realtime Collaboration
Welcome to **Chapter 5: Realtime Collaboration**. In this part of **Teable: Deep Dive Tutorial**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
@@ -89,502 +90,111 @@ Suggested trace strategy:
## Depth Expansion Playbook
-<!-- depth-expansion-v2 -->
-
-This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
-
-### Strategic Context
-
-- tutorial: **Teable: Deep Dive Tutorial**
-- tutorial slug: **teable-tutorial**
-- chapter focus: **Chapter 5: Realtime Collaboration**
-- system context: **Teable Database Platform**
-- objective: move from surface-level usage to repeatable engineering operation
-
-### Architecture Decomposition
-
-1. Define the runtime boundary for `Chapter 5: Realtime Collaboration`.
-2. Separate control-plane decisions from data-plane execution.
-3. Capture input contracts, transformation points, and output contracts.
-4. Trace state transitions across request lifecycle stages.
-5. Identify extension hooks and policy interception points.
-6. Map ownership boundaries for team and automation workflows.
-7. Specify rollback and recovery paths for unsafe changes.
-8. Track observability signals for correctness, latency, and cost.
-
-### Operator Decision Matrix
-
-| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
-|:--------------|:--------------|:------------------|:---------|
-| Runtime mode | managed defaults | explicit policy config | speed vs control |
-| State handling | local ephemeral | durable persisted state | simplicity vs auditability |
-| Tool integration | direct API use | mediated adapter layer | velocity vs governance |
-| Rollout method | manual change | staged + canary rollout | effort vs safety |
-| Incident response | best effort logs | runbooks + SLO alerts | cost vs reliability |
-
-### Failure Modes and Countermeasures
-
-| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
-|:-------------|:-------------|:-------------------|:---------------|
-| stale context | inconsistent outputs | missing refresh window | enforce context TTL and refresh hooks |
-| policy drift | unexpected execution | ad hoc overrides | centralize policy profiles |
-| auth mismatch | 401/403 bursts | credential sprawl | rotation schedule + scope minimization |
-| schema breakage | parser/validation errors | unmanaged upstream changes | contract tests per release |
-| retry storms | queue congestion | no backoff controls | jittered backoff + circuit breakers |
-| silent regressions | quality drop without alerts | weak baseline metrics | eval harness with thresholds |
-
-### Implementation Runbook
-
-1. Establish a reproducible baseline environment.
-2. Capture chapter-specific success criteria before changes.
-3. Implement minimal viable path with explicit interfaces.
-4. Add observability before expanding feature scope.
-5. Run deterministic tests for happy-path behavior.
-6. Inject failure scenarios for negative-path validation.
-7. Compare output quality against baseline snapshots.
-8. Promote through staged environments with rollback gates.
-9. Record operational lessons in release notes.
-
-### Quality Gate Checklist
-
-- [ ] chapter-level assumptions are explicit and testable
-- [ ] API/tool boundaries are documented with input/output examples
-- [ ] failure handling includes retry, timeout, and fallback policy
-- [ ] security controls include auth scopes and secret rotation plans
-- [ ] observability includes logs, metrics, traces, and alert thresholds
-- [ ] deployment guidance includes canary and rollback paths
-- [ ] docs include links to upstream sources and related tracks
-- [ ] post-release verification confirms expected behavior under load
-
-### Source Alignment
-
-- [Teable](https://github.com/teableio/teable)
-- [AI Codebase Knowledge Builder](https://github.com/The-Pocket/Tutorial-Codebase-Knowledge)
-
-### Cross-Tutorial Connection Map
-
-- Related tutorials are listed in this tutorial index.
-
-### Advanced Practice Exercises
-
-1. Build a minimal end-to-end implementation for `Chapter 5: Realtime Collaboration`.
-2. Add instrumentation and measure baseline latency and error rate.
-3. Introduce one controlled failure and confirm graceful recovery.
-4. Add policy constraints and verify they are enforced consistently.
-5. Run a staged rollout and document rollback decision criteria.
-
-### Review Questions
-
-1. Which execution boundary matters most for this chapter and why?
-2. What signal detects regressions earliest in your environment?
-3. What tradeoff did you make between delivery speed and governance?
-4. How would you recover from the highest-impact failure mode?
-5. What must be automated before scaling to team-wide adoption?
-
-### Scenario Playbook 1: Chapter 5: Realtime Collaboration
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 2: Chapter 5: Realtime Collaboration
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 3: Chapter 5: Realtime Collaboration
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 4: Chapter 5: Realtime Collaboration
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 5: Chapter 5: Realtime Collaboration
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 6: Chapter 5: Realtime Collaboration
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 7: Chapter 5: Realtime Collaboration
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 8: Chapter 5: Realtime Collaboration
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 9: Chapter 5: Realtime Collaboration
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 10: Chapter 5: Realtime Collaboration
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 11: Chapter 5: Realtime Collaboration
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 12: Chapter 5: Realtime Collaboration
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 13: Chapter 5: Realtime Collaboration
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 14: Chapter 5: Realtime Collaboration
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 15: Chapter 5: Realtime Collaboration
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 16: Chapter 5: Realtime Collaboration
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 17: Chapter 5: Realtime Collaboration
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 18: Chapter 5: Realtime Collaboration
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 19: Chapter 5: Realtime Collaboration
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 20: Chapter 5: Realtime Collaboration
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 21: Chapter 5: Realtime Collaboration
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 22: Chapter 5: Realtime Collaboration
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 23: Chapter 5: Realtime Collaboration
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 24: Chapter 5: Realtime Collaboration
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 25: Chapter 5: Realtime Collaboration
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 26: Chapter 5: Realtime Collaboration
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 27: Chapter 5: Realtime Collaboration
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 28: Chapter 5: Realtime Collaboration
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 29: Chapter 5: Realtime Collaboration
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 30: Chapter 5: Realtime Collaboration
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 31: Chapter 5: Realtime Collaboration
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 32: Chapter 5: Realtime Collaboration
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 33: Chapter 5: Realtime Collaboration
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 34: Chapter 5: Realtime Collaboration
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
+## Source Code Walkthrough
+
+### `.ncurc.yml`
+
+The `.ncurc` module in [`.ncurc.yml`](https://github.com/teableio/teable/blob/HEAD/.ncurc.yml) handles a key part of this chapter's functionality:
+
+```yml
+# npm-check-updates configuration used by yarn deps:check && yarn deps:update
+# convenience scripts.
+# @link https://github.com/raineorshine/npm-check-updates
+
+# Add here exclusions on packages if any
+reject: [
+ 'vite-plugin-svgr',
+
+ # Too early cause in esm
+ 'is-port-reachable',
+ 'nanoid',
+ 'node-fetch',
+ ]
+
+```
+
+This module is important because it defines how Teable: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+### `tsconfig.base.json`
+
+The `tsconfig.base` module in [`tsconfig.base.json`](https://github.com/teableio/teable/blob/HEAD/tsconfig.base.json) handles a key part of this chapter's functionality:
+
+```json
+{
+ "$schema": "https://json.schemastore.org/tsconfig",
+ "compilerOptions": {
+ "strict": true,
+ "useUnknownInCatchVariables": true,
+ "allowJs": true,
+ "skipLibCheck": true,
+ "forceConsistentCasingInFileNames": true,
+ "noEmit": true,
+ "esModuleInterop": true,
+ "moduleResolution": "node",
+ "resolveJsonModule": true,
+ "isolatedModules": true,
+ "incremental": true,
+ "newLine": "lf"
+ },
+ "exclude": ["**/node_modules", "**/.*/"]
+}
+
+```
+
+This module is important because it defines how Teable: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+### `package.json`
+
+The `package` module in [`package.json`](https://github.com/teableio/teable/blob/HEAD/package.json) handles a key part of this chapter's functionality:
+
+```json
+{
+ "name": "@teable/teable",
+ "version": "1.10.0",
+ "license": "AGPL-3.0",
+ "private": true,
+ "homepage": "https://github.com/teableio/teable",
+ "repository": {
+ "type": "git",
+ "url": "https://github.com/teableio/teable"
+ },
+ "author": {
+ "name": "tea artist",
+ "url": "https://github.com/tea-artist"
+ },
+ "keywords": [
+ "teable",
+ "database"
+ ],
+ "workspaces": [
+ "apps/*",
+ "packages/*",
+ "packages/v2/*",
+ "plugins",
+ "!apps/electron"
+ ],
+ "scripts": {
+ "clean:global-cache": "rimraf ./.cache",
+ "deps:check": "pnpm --package=npm-check-updates@latest dlx npm-check-updates --configFileName .ncurc.yml --workspaces --root --mergeConfig",
+ "deps:update": "pnpm --package=npm-check-updates@latest dlx npm-check-updates --configFileName .ncurc.yml -u --workspaces --root --mergeConfig",
+ "dev:v2": "pnpm -r --parallel --stream -F @teable/formula -F './packages/v2/*' dev",
+ "clean:v2": "pnpm -r --parallel --stream -F @teable/formula -F './packages/v2/*' clean",
+ "build:v2": "pnpm -r --parallel --stream -F @teable/formula -F './packages/v2/*' build",
+ "build:packages": "pnpm -r -F './packages/**' build",
+ "g:build": "pnpm -r run build",
+ "g:build-changed": "pnpm -r -F '...[origin/main]' build",
+```
+
+This module is important because it defines how Teable: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+
+## How These Components Connect
+
+```mermaid
+flowchart TD
+ A[.ncurc]
+ B[tsconfig.base]
+ C[package]
+ A --> B
+ B --> C
+```
diff --git a/tutorials/teable-tutorial/06-query-system.md b/tutorials/teable-tutorial/06-query-system.md
index c9a0df64..f9598b0f 100644
--- a/tutorials/teable-tutorial/06-query-system.md
+++ b/tutorials/teable-tutorial/06-query-system.md
@@ -6,6 +6,7 @@ has_children: false
parent: "Teable Database Platform"
---
+
# Chapter 6: Query System
Welcome to **Chapter 6: Query System**. In this part of **Teable: Deep Dive Tutorial**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
@@ -88,502 +89,111 @@ Suggested trace strategy:
## Depth Expansion Playbook
-<!-- depth-expansion-v2 -->
-
-This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
-
-### Strategic Context
-
-- tutorial: **Teable: Deep Dive Tutorial**
-- tutorial slug: **teable-tutorial**
-- chapter focus: **Chapter 6: Query System**
-- system context: **Teable Database Platform**
-- objective: move from surface-level usage to repeatable engineering operation
-
-### Architecture Decomposition
-
-1. Define the runtime boundary for `Chapter 6: Query System`.
-2. Separate control-plane decisions from data-plane execution.
-3. Capture input contracts, transformation points, and output contracts.
-4. Trace state transitions across request lifecycle stages.
-5. Identify extension hooks and policy interception points.
-6. Map ownership boundaries for team and automation workflows.
-7. Specify rollback and recovery paths for unsafe changes.
-8. Track observability signals for correctness, latency, and cost.
-
-### Operator Decision Matrix
-
-| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
-|:--------------|:--------------|:------------------|:---------|
-| Runtime mode | managed defaults | explicit policy config | speed vs control |
-| State handling | local ephemeral | durable persisted state | simplicity vs auditability |
-| Tool integration | direct API use | mediated adapter layer | velocity vs governance |
-| Rollout method | manual change | staged + canary rollout | effort vs safety |
-| Incident response | best effort logs | runbooks + SLO alerts | cost vs reliability |
-
-### Failure Modes and Countermeasures
-
-| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
-|:-------------|:-------------|:-------------------|:---------------|
-| stale context | inconsistent outputs | missing refresh window | enforce context TTL and refresh hooks |
-| policy drift | unexpected execution | ad hoc overrides | centralize policy profiles |
-| auth mismatch | 401/403 bursts | credential sprawl | rotation schedule + scope minimization |
-| schema breakage | parser/validation errors | unmanaged upstream changes | contract tests per release |
-| retry storms | queue congestion | no backoff controls | jittered backoff + circuit breakers |
-| silent regressions | quality drop without alerts | weak baseline metrics | eval harness with thresholds |
-
-### Implementation Runbook
-
-1. Establish a reproducible baseline environment.
-2. Capture chapter-specific success criteria before changes.
-3. Implement minimal viable path with explicit interfaces.
-4. Add observability before expanding feature scope.
-5. Run deterministic tests for happy-path behavior.
-6. Inject failure scenarios for negative-path validation.
-7. Compare output quality against baseline snapshots.
-8. Promote through staged environments with rollback gates.
-9. Record operational lessons in release notes.
-
-### Quality Gate Checklist
-
-- [ ] chapter-level assumptions are explicit and testable
-- [ ] API/tool boundaries are documented with input/output examples
-- [ ] failure handling includes retry, timeout, and fallback policy
-- [ ] security controls include auth scopes and secret rotation plans
-- [ ] observability includes logs, metrics, traces, and alert thresholds
-- [ ] deployment guidance includes canary and rollback paths
-- [ ] docs include links to upstream sources and related tracks
-- [ ] post-release verification confirms expected behavior under load
-
-### Source Alignment
-
-- [Teable](https://github.com/teableio/teable)
-- [AI Codebase Knowledge Builder](https://github.com/The-Pocket/Tutorial-Codebase-Knowledge)
-
-### Cross-Tutorial Connection Map
-
-- Related tutorials are listed in this tutorial index.
-
-### Advanced Practice Exercises
-
-1. Build a minimal end-to-end implementation for `Chapter 6: Query System`.
-2. Add instrumentation and measure baseline latency and error rate.
-3. Introduce one controlled failure and confirm graceful recovery.
-4. Add policy constraints and verify they are enforced consistently.
-5. Run a staged rollout and document rollback decision criteria.
-
-### Review Questions
-
-1. Which execution boundary matters most for this chapter and why?
-2. What signal detects regressions earliest in your environment?
-3. What tradeoff did you make between delivery speed and governance?
-4. How would you recover from the highest-impact failure mode?
-5. What must be automated before scaling to team-wide adoption?
-
-### Scenario Playbook 1: Chapter 6: Query System
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 2: Chapter 6: Query System
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 3: Chapter 6: Query System
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 4: Chapter 6: Query System
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 5: Chapter 6: Query System
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 6: Chapter 6: Query System
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 7: Chapter 6: Query System
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 8: Chapter 6: Query System
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 9: Chapter 6: Query System
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 10: Chapter 6: Query System
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 11: Chapter 6: Query System
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 12: Chapter 6: Query System
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 13: Chapter 6: Query System
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 14: Chapter 6: Query System
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 15: Chapter 6: Query System
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 16: Chapter 6: Query System
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 17: Chapter 6: Query System
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 18: Chapter 6: Query System
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 19: Chapter 6: Query System
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 20: Chapter 6: Query System
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 21: Chapter 6: Query System
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 22: Chapter 6: Query System
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 23: Chapter 6: Query System
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 24: Chapter 6: Query System
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 25: Chapter 6: Query System
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 26: Chapter 6: Query System
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 27: Chapter 6: Query System
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 28: Chapter 6: Query System
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 29: Chapter 6: Query System
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 30: Chapter 6: Query System
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 31: Chapter 6: Query System
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 32: Chapter 6: Query System
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 33: Chapter 6: Query System
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 34: Chapter 6: Query System
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
+## Source Code Walkthrough
+
+### `.ncurc.yml`
+
+The `.ncurc` module in [`.ncurc.yml`](https://github.com/teableio/teable/blob/HEAD/.ncurc.yml) handles a key part of this chapter's functionality:
+
+```yml
+# npm-check-updates configuration used by yarn deps:check && yarn deps:update
+# convenience scripts.
+# @link https://github.com/raineorshine/npm-check-updates
+
+# Add here exclusions on packages if any
+reject: [
+ 'vite-plugin-svgr',
+
+ # Too early cause in esm
+ 'is-port-reachable',
+ 'nanoid',
+ 'node-fetch',
+ ]
+
+```
+
+This module is important because it defines how Teable: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+### `tsconfig.base.json`
+
+The `tsconfig.base` module in [`tsconfig.base.json`](https://github.com/teableio/teable/blob/HEAD/tsconfig.base.json) handles a key part of this chapter's functionality:
+
+```json
+{
+ "$schema": "https://json.schemastore.org/tsconfig",
+ "compilerOptions": {
+ "strict": true,
+ "useUnknownInCatchVariables": true,
+ "allowJs": true,
+ "skipLibCheck": true,
+ "forceConsistentCasingInFileNames": true,
+ "noEmit": true,
+ "esModuleInterop": true,
+ "moduleResolution": "node",
+ "resolveJsonModule": true,
+ "isolatedModules": true,
+ "incremental": true,
+ "newLine": "lf"
+ },
+ "exclude": ["**/node_modules", "**/.*/"]
+}
+
+```
+
+This module is important because it defines how Teable: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+### `package.json`
+
+The `package` module in [`package.json`](https://github.com/teableio/teable/blob/HEAD/package.json) handles a key part of this chapter's functionality:
+
+```json
+{
+ "name": "@teable/teable",
+ "version": "1.10.0",
+ "license": "AGPL-3.0",
+ "private": true,
+ "homepage": "https://github.com/teableio/teable",
+ "repository": {
+ "type": "git",
+ "url": "https://github.com/teableio/teable"
+ },
+ "author": {
+ "name": "tea artist",
+ "url": "https://github.com/tea-artist"
+ },
+ "keywords": [
+ "teable",
+ "database"
+ ],
+ "workspaces": [
+ "apps/*",
+ "packages/*",
+ "packages/v2/*",
+ "plugins",
+ "!apps/electron"
+ ],
+ "scripts": {
+ "clean:global-cache": "rimraf ./.cache",
+ "deps:check": "pnpm --package=npm-check-updates@latest dlx npm-check-updates --configFileName .ncurc.yml --workspaces --root --mergeConfig",
+ "deps:update": "pnpm --package=npm-check-updates@latest dlx npm-check-updates --configFileName .ncurc.yml -u --workspaces --root --mergeConfig",
+ "dev:v2": "pnpm -r --parallel --stream -F @teable/formula -F './packages/v2/*' dev",
+ "clean:v2": "pnpm -r --parallel --stream -F @teable/formula -F './packages/v2/*' clean",
+ "build:v2": "pnpm -r --parallel --stream -F @teable/formula -F './packages/v2/*' build",
+ "build:packages": "pnpm -r -F './packages/**' build",
+ "g:build": "pnpm -r run build",
+ "g:build-changed": "pnpm -r -F '...[origin/main]' build",
+```
+
+This module is important because it defines how Teable: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+
+## How These Components Connect
+
+```mermaid
+flowchart TD
+ A[.ncurc]
+ B[tsconfig.base]
+ C[package]
+ A --> B
+ B --> C
+```
diff --git a/tutorials/teable-tutorial/07-frontend-architecture.md b/tutorials/teable-tutorial/07-frontend-architecture.md
index 24bf1387..e9d36f41 100644
--- a/tutorials/teable-tutorial/07-frontend-architecture.md
+++ b/tutorials/teable-tutorial/07-frontend-architecture.md
@@ -6,6 +6,7 @@ has_children: false
parent: "Teable Database Platform"
---
+
# Chapter 7: Frontend Architecture
Welcome to **Chapter 7: Frontend Architecture**. In this part of **Teable: Deep Dive Tutorial**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
@@ -89,502 +90,111 @@ Suggested trace strategy:
## Depth Expansion Playbook
-<!-- depth-expansion-v2 -->
-
-This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
-
-### Strategic Context
-
-- tutorial: **Teable: Deep Dive Tutorial**
-- tutorial slug: **teable-tutorial**
-- chapter focus: **Chapter 7: Frontend Architecture**
-- system context: **Teable Database Platform**
-- objective: move from surface-level usage to repeatable engineering operation
-
-### Architecture Decomposition
-
-1. Define the runtime boundary for `Chapter 7: Frontend Architecture`.
-2. Separate control-plane decisions from data-plane execution.
-3. Capture input contracts, transformation points, and output contracts.
-4. Trace state transitions across request lifecycle stages.
-5. Identify extension hooks and policy interception points.
-6. Map ownership boundaries for team and automation workflows.
-7. Specify rollback and recovery paths for unsafe changes.
-8. Track observability signals for correctness, latency, and cost.
-
-### Operator Decision Matrix
-
-| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
-|:--------------|:--------------|:------------------|:---------|
-| Runtime mode | managed defaults | explicit policy config | speed vs control |
-| State handling | local ephemeral | durable persisted state | simplicity vs auditability |
-| Tool integration | direct API use | mediated adapter layer | velocity vs governance |
-| Rollout method | manual change | staged + canary rollout | effort vs safety |
-| Incident response | best effort logs | runbooks + SLO alerts | cost vs reliability |
-
-### Failure Modes and Countermeasures
-
-| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
-|:-------------|:-------------|:-------------------|:---------------|
-| stale context | inconsistent outputs | missing refresh window | enforce context TTL and refresh hooks |
-| policy drift | unexpected execution | ad hoc overrides | centralize policy profiles |
-| auth mismatch | 401/403 bursts | credential sprawl | rotation schedule + scope minimization |
-| schema breakage | parser/validation errors | unmanaged upstream changes | contract tests per release |
-| retry storms | queue congestion | no backoff controls | jittered backoff + circuit breakers |
-| silent regressions | quality drop without alerts | weak baseline metrics | eval harness with thresholds |
-
-### Implementation Runbook
-
-1. Establish a reproducible baseline environment.
-2. Capture chapter-specific success criteria before changes.
-3. Implement minimal viable path with explicit interfaces.
-4. Add observability before expanding feature scope.
-5. Run deterministic tests for happy-path behavior.
-6. Inject failure scenarios for negative-path validation.
-7. Compare output quality against baseline snapshots.
-8. Promote through staged environments with rollback gates.
-9. Record operational lessons in release notes.
-
-### Quality Gate Checklist
-
-- [ ] chapter-level assumptions are explicit and testable
-- [ ] API/tool boundaries are documented with input/output examples
-- [ ] failure handling includes retry, timeout, and fallback policy
-- [ ] security controls include auth scopes and secret rotation plans
-- [ ] observability includes logs, metrics, traces, and alert thresholds
-- [ ] deployment guidance includes canary and rollback paths
-- [ ] docs include links to upstream sources and related tracks
-- [ ] post-release verification confirms expected behavior under load
-
-### Source Alignment
-
-- [Teable](https://github.com/teableio/teable)
-- [AI Codebase Knowledge Builder](https://github.com/The-Pocket/Tutorial-Codebase-Knowledge)
-
-### Cross-Tutorial Connection Map
-
-- Related tutorials are listed in this tutorial index.
-
-### Advanced Practice Exercises
-
-1. Build a minimal end-to-end implementation for `Chapter 7: Frontend Architecture`.
-2. Add instrumentation and measure baseline latency and error rate.
-3. Introduce one controlled failure and confirm graceful recovery.
-4. Add policy constraints and verify they are enforced consistently.
-5. Run a staged rollout and document rollback decision criteria.
-
-### Review Questions
-
-1. Which execution boundary matters most for this chapter and why?
-2. What signal detects regressions earliest in your environment?
-3. What tradeoff did you make between delivery speed and governance?
-4. How would you recover from the highest-impact failure mode?
-5. What must be automated before scaling to team-wide adoption?
-
-### Scenario Playbook 1: Chapter 7: Frontend Architecture
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 2: Chapter 7: Frontend Architecture
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 3: Chapter 7: Frontend Architecture
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 4: Chapter 7: Frontend Architecture
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 5: Chapter 7: Frontend Architecture
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 6: Chapter 7: Frontend Architecture
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 7: Chapter 7: Frontend Architecture
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 8: Chapter 7: Frontend Architecture
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 9: Chapter 7: Frontend Architecture
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 10: Chapter 7: Frontend Architecture
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 11: Chapter 7: Frontend Architecture
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 12: Chapter 7: Frontend Architecture
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 13: Chapter 7: Frontend Architecture
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 14: Chapter 7: Frontend Architecture
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 15: Chapter 7: Frontend Architecture
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 16: Chapter 7: Frontend Architecture
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 17: Chapter 7: Frontend Architecture
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 18: Chapter 7: Frontend Architecture
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 19: Chapter 7: Frontend Architecture
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 20: Chapter 7: Frontend Architecture
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 21: Chapter 7: Frontend Architecture
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 22: Chapter 7: Frontend Architecture
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 23: Chapter 7: Frontend Architecture
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 24: Chapter 7: Frontend Architecture
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 25: Chapter 7: Frontend Architecture
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 26: Chapter 7: Frontend Architecture
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 27: Chapter 7: Frontend Architecture
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 28: Chapter 7: Frontend Architecture
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 29: Chapter 7: Frontend Architecture
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 30: Chapter 7: Frontend Architecture
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 31: Chapter 7: Frontend Architecture
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 32: Chapter 7: Frontend Architecture
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 33: Chapter 7: Frontend Architecture
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 34: Chapter 7: Frontend Architecture
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
+## Source Code Walkthrough
+
+### `.ncurc.yml`
+
+The `.ncurc` module in [`.ncurc.yml`](https://github.com/teableio/teable/blob/HEAD/.ncurc.yml) handles a key part of this chapter's functionality:
+
+```yml
+# npm-check-updates configuration used by yarn deps:check && yarn deps:update
+# convenience scripts.
+# @link https://github.com/raineorshine/npm-check-updates
+
+# Add here exclusions on packages if any
+reject: [
+ 'vite-plugin-svgr',
+
+ # Too early cause in esm
+ 'is-port-reachable',
+ 'nanoid',
+ 'node-fetch',
+ ]
+
+```
+
+This module is important because it defines how Teable: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+### `tsconfig.base.json`
+
+The `tsconfig.base` module in [`tsconfig.base.json`](https://github.com/teableio/teable/blob/HEAD/tsconfig.base.json) handles a key part of this chapter's functionality:
+
+```json
+{
+ "$schema": "https://json.schemastore.org/tsconfig",
+ "compilerOptions": {
+ "strict": true,
+ "useUnknownInCatchVariables": true,
+ "allowJs": true,
+ "skipLibCheck": true,
+ "forceConsistentCasingInFileNames": true,
+ "noEmit": true,
+ "esModuleInterop": true,
+ "moduleResolution": "node",
+ "resolveJsonModule": true,
+ "isolatedModules": true,
+ "incremental": true,
+ "newLine": "lf"
+ },
+ "exclude": ["**/node_modules", "**/.*/"]
+}
+
+```
+
+This module is important because it defines how Teable: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+### `package.json`
+
+The `package` module in [`package.json`](https://github.com/teableio/teable/blob/HEAD/package.json) handles a key part of this chapter's functionality:
+
+```json
+{
+ "name": "@teable/teable",
+ "version": "1.10.0",
+ "license": "AGPL-3.0",
+ "private": true,
+ "homepage": "https://github.com/teableio/teable",
+ "repository": {
+ "type": "git",
+ "url": "https://github.com/teableio/teable"
+ },
+ "author": {
+ "name": "tea artist",
+ "url": "https://github.com/tea-artist"
+ },
+ "keywords": [
+ "teable",
+ "database"
+ ],
+ "workspaces": [
+ "apps/*",
+ "packages/*",
+ "packages/v2/*",
+ "plugins",
+ "!apps/electron"
+ ],
+ "scripts": {
+ "clean:global-cache": "rimraf ./.cache",
+ "deps:check": "pnpm --package=npm-check-updates@latest dlx npm-check-updates --configFileName .ncurc.yml --workspaces --root --mergeConfig",
+ "deps:update": "pnpm --package=npm-check-updates@latest dlx npm-check-updates --configFileName .ncurc.yml -u --workspaces --root --mergeConfig",
+ "dev:v2": "pnpm -r --parallel --stream -F @teable/formula -F './packages/v2/*' dev",
+ "clean:v2": "pnpm -r --parallel --stream -F @teable/formula -F './packages/v2/*' clean",
+ "build:v2": "pnpm -r --parallel --stream -F @teable/formula -F './packages/v2/*' build",
+ "build:packages": "pnpm -r -F './packages/**' build",
+ "g:build": "pnpm -r run build",
+ "g:build-changed": "pnpm -r -F '...[origin/main]' build",
+```
+
+This module is important because it defines how Teable: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+
+## How These Components Connect
+
+```mermaid
+flowchart TD
+ A[.ncurc]
+ B[tsconfig.base]
+ C[package]
+ A --> B
+ B --> C
+```
diff --git a/tutorials/teable-tutorial/08-production-deployment.md b/tutorials/teable-tutorial/08-production-deployment.md
index 88e05cd1..d0b87336 100644
--- a/tutorials/teable-tutorial/08-production-deployment.md
+++ b/tutorials/teable-tutorial/08-production-deployment.md
@@ -6,6 +6,7 @@ has_children: false
parent: "Teable Database Platform"
---
+
# Chapter 8: Production Deployment
Welcome to **Chapter 8: Production Deployment**. In this part of **Teable: Deep Dive Tutorial**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
@@ -90,502 +91,111 @@ Suggested trace strategy:
## Depth Expansion Playbook
-<!-- depth-expansion-v2 -->
-
-This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
-
-### Strategic Context
-
-- tutorial: **Teable: Deep Dive Tutorial**
-- tutorial slug: **teable-tutorial**
-- chapter focus: **Chapter 8: Production Deployment**
-- system context: **Teable Database Platform**
-- objective: move from surface-level usage to repeatable engineering operation
-
-### Architecture Decomposition
-
-1. Define the runtime boundary for `Chapter 8: Production Deployment`.
-2. Separate control-plane decisions from data-plane execution.
-3. Capture input contracts, transformation points, and output contracts.
-4. Trace state transitions across request lifecycle stages.
-5. Identify extension hooks and policy interception points.
-6. Map ownership boundaries for team and automation workflows.
-7. Specify rollback and recovery paths for unsafe changes.
-8. Track observability signals for correctness, latency, and cost.
-
-### Operator Decision Matrix
-
-| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
-|:--------------|:--------------|:------------------|:---------|
-| Runtime mode | managed defaults | explicit policy config | speed vs control |
-| State handling | local ephemeral | durable persisted state | simplicity vs auditability |
-| Tool integration | direct API use | mediated adapter layer | velocity vs governance |
-| Rollout method | manual change | staged + canary rollout | effort vs safety |
-| Incident response | best effort logs | runbooks + SLO alerts | cost vs reliability |
-
-### Failure Modes and Countermeasures
-
-| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
-|:-------------|:-------------|:-------------------|:---------------|
-| stale context | inconsistent outputs | missing refresh window | enforce context TTL and refresh hooks |
-| policy drift | unexpected execution | ad hoc overrides | centralize policy profiles |
-| auth mismatch | 401/403 bursts | credential sprawl | rotation schedule + scope minimization |
-| schema breakage | parser/validation errors | unmanaged upstream changes | contract tests per release |
-| retry storms | queue congestion | no backoff controls | jittered backoff + circuit breakers |
-| silent regressions | quality drop without alerts | weak baseline metrics | eval harness with thresholds |
-
-### Implementation Runbook
-
-1. Establish a reproducible baseline environment.
-2. Capture chapter-specific success criteria before changes.
-3. Implement minimal viable path with explicit interfaces.
-4. Add observability before expanding feature scope.
-5. Run deterministic tests for happy-path behavior.
-6. Inject failure scenarios for negative-path validation.
-7. Compare output quality against baseline snapshots.
-8. Promote through staged environments with rollback gates.
-9. Record operational lessons in release notes.
-
-### Quality Gate Checklist
-
-- [ ] chapter-level assumptions are explicit and testable
-- [ ] API/tool boundaries are documented with input/output examples
-- [ ] failure handling includes retry, timeout, and fallback policy
-- [ ] security controls include auth scopes and secret rotation plans
-- [ ] observability includes logs, metrics, traces, and alert thresholds
-- [ ] deployment guidance includes canary and rollback paths
-- [ ] docs include links to upstream sources and related tracks
-- [ ] post-release verification confirms expected behavior under load
-
-### Source Alignment
-
-- [Teable](https://github.com/teableio/teable)
-- [AI Codebase Knowledge Builder](https://github.com/The-Pocket/Tutorial-Codebase-Knowledge)
-
-### Cross-Tutorial Connection Map
-
-- Related tutorials are listed in this tutorial index.
-
-### Advanced Practice Exercises
-
-1. Build a minimal end-to-end implementation for `Chapter 8: Production Deployment`.
-2. Add instrumentation and measure baseline latency and error rate.
-3. Introduce one controlled failure and confirm graceful recovery.
-4. Add policy constraints and verify they are enforced consistently.
-5. Run a staged rollout and document rollback decision criteria.
-
-### Review Questions
-
-1. Which execution boundary matters most for this chapter and why?
-2. What signal detects regressions earliest in your environment?
-3. What tradeoff did you make between delivery speed and governance?
-4. How would you recover from the highest-impact failure mode?
-5. What must be automated before scaling to team-wide adoption?
-
-### Scenario Playbook 1: Chapter 8: Production Deployment
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 2: Chapter 8: Production Deployment
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 3: Chapter 8: Production Deployment
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 4: Chapter 8: Production Deployment
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 5: Chapter 8: Production Deployment
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 6: Chapter 8: Production Deployment
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 7: Chapter 8: Production Deployment
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 8: Chapter 8: Production Deployment
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 9: Chapter 8: Production Deployment
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 10: Chapter 8: Production Deployment
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 11: Chapter 8: Production Deployment
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 12: Chapter 8: Production Deployment
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 13: Chapter 8: Production Deployment
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 14: Chapter 8: Production Deployment
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 15: Chapter 8: Production Deployment
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 16: Chapter 8: Production Deployment
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 17: Chapter 8: Production Deployment
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 18: Chapter 8: Production Deployment
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 19: Chapter 8: Production Deployment
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 20: Chapter 8: Production Deployment
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 21: Chapter 8: Production Deployment
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 22: Chapter 8: Production Deployment
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 23: Chapter 8: Production Deployment
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 24: Chapter 8: Production Deployment
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 25: Chapter 8: Production Deployment
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 26: Chapter 8: Production Deployment
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 27: Chapter 8: Production Deployment
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 28: Chapter 8: Production Deployment
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 29: Chapter 8: Production Deployment
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 30: Chapter 8: Production Deployment
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 31: Chapter 8: Production Deployment
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 32: Chapter 8: Production Deployment
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 33: Chapter 8: Production Deployment
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 34: Chapter 8: Production Deployment
-
-- tutorial context: **Teable: Deep Dive Tutorial**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
+## Source Code Walkthrough
+
+### `.ncurc.yml`
+
+The `.ncurc` module in [`.ncurc.yml`](https://github.com/teableio/teable/blob/HEAD/.ncurc.yml) handles a key part of this chapter's functionality:
+
+```yml
+# npm-check-updates configuration used by yarn deps:check && yarn deps:update
+# convenience scripts.
+# @link https://github.com/raineorshine/npm-check-updates
+
+# Add here exclusions on packages if any
+reject: [
+ 'vite-plugin-svgr',
+
+ # Too early cause in esm
+ 'is-port-reachable',
+ 'nanoid',
+ 'node-fetch',
+ ]
+
+```
+
+This module is important because it defines how Teable: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+### `tsconfig.base.json`
+
+The `tsconfig.base` module in [`tsconfig.base.json`](https://github.com/teableio/teable/blob/HEAD/tsconfig.base.json) handles a key part of this chapter's functionality:
+
+```json
+{
+ "$schema": "https://json.schemastore.org/tsconfig",
+ "compilerOptions": {
+ "strict": true,
+ "useUnknownInCatchVariables": true,
+ "allowJs": true,
+ "skipLibCheck": true,
+ "forceConsistentCasingInFileNames": true,
+ "noEmit": true,
+ "esModuleInterop": true,
+ "moduleResolution": "node",
+ "resolveJsonModule": true,
+ "isolatedModules": true,
+ "incremental": true,
+ "newLine": "lf"
+ },
+ "exclude": ["**/node_modules", "**/.*/"]
+}
+
+```
+
+This module is important because it defines how Teable: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+### `package.json`
+
+The `package` module in [`package.json`](https://github.com/teableio/teable/blob/HEAD/package.json) handles a key part of this chapter's functionality:
+
+```json
+{
+ "name": "@teable/teable",
+ "version": "1.10.0",
+ "license": "AGPL-3.0",
+ "private": true,
+ "homepage": "https://github.com/teableio/teable",
+ "repository": {
+ "type": "git",
+ "url": "https://github.com/teableio/teable"
+ },
+ "author": {
+ "name": "tea artist",
+ "url": "https://github.com/tea-artist"
+ },
+ "keywords": [
+ "teable",
+ "database"
+ ],
+ "workspaces": [
+ "apps/*",
+ "packages/*",
+ "packages/v2/*",
+ "plugins",
+ "!apps/electron"
+ ],
+ "scripts": {
+ "clean:global-cache": "rimraf ./.cache",
+ "deps:check": "pnpm --package=npm-check-updates@latest dlx npm-check-updates --configFileName .ncurc.yml --workspaces --root --mergeConfig",
+ "deps:update": "pnpm --package=npm-check-updates@latest dlx npm-check-updates --configFileName .ncurc.yml -u --workspaces --root --mergeConfig",
+ "dev:v2": "pnpm -r --parallel --stream -F @teable/formula -F './packages/v2/*' dev",
+ "clean:v2": "pnpm -r --parallel --stream -F @teable/formula -F './packages/v2/*' clean",
+ "build:v2": "pnpm -r --parallel --stream -F @teable/formula -F './packages/v2/*' build",
+ "build:packages": "pnpm -r -F './packages/**' build",
+ "g:build": "pnpm -r run build",
+ "g:build-changed": "pnpm -r -F '...[origin/main]' build",
+```
+
+This module is important because it defines how Teable: Deep Dive Tutorial implements the patterns covered in this chapter.
+
+
+## How These Components Connect
+
+```mermaid
+flowchart TD
+ A[.ncurc]
+ B[tsconfig.base]
+ C[package]
+ A --> B
+ B --> C
+```
diff --git a/tutorials/tiktoken-tutorial/01-getting-started.md b/tutorials/tiktoken-tutorial/01-getting-started.md
index 61644a1d..aa3883c9 100644
--- a/tutorials/tiktoken-tutorial/01-getting-started.md
+++ b/tutorials/tiktoken-tutorial/01-getting-started.md
@@ -110,10 +110,49 @@ Suggested trace strategy:
- [Main Catalog](../../README.md#-tutorial-catalog)
- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
+### `src/py.rs`
+
+The `TiktokenBuffer` interface in [`src/py.rs`](https://github.com/openai/tiktoken/blob/HEAD/src/py.rs) handles a key part of this chapter's functionality:
+
+```rs
+ };
+
+ let buffer = TiktokenBuffer { tokens };
+ buffer.into_py_any(py)
+ }
+
+ fn _encode_bytes(&self, py: Python, bytes: &[u8]) -> Vec<Rank> {
+ py.detach(|| {
+ match std::str::from_utf8(bytes) {
+ // Straightforward case
+ Ok(text) => self.encode_ordinary(text),
+ // Oops, don't actually have UTF-8. But we need to do the regex splitting in
+ // Unicode space, so we make our best guess at where we would have splits
+ Err(e) => {
+ let text = unsafe { std::str::from_utf8_unchecked(&bytes[..e.valid_up_to()]) };
+ let (tokens, last_piece_token_len) =
+ self.encode(text, &HashSet::new()).unwrap();
+ let (mut tokens, last_piece_token_len) =
+ self._increase_last_piece_token_len(tokens, last_piece_token_len);
+
+ let mut unstable_bytes;
+ if !tokens.is_empty() && last_piece_token_len > 0 {
+ // Lop off the tokens from the last piece and run BPE on the remaining bytes
+ // This likely matches what models see better, e.g. if you assume we're
+ // dealing with truncated UTF-8 bytes.
+ // Niche, but note this may not be correct if we'd have had a regex
+ // split between the valid UTF-8 and the invalid bytes.
+ unstable_bytes = self
+ .decode_bytes(&tokens[tokens.len() - last_piece_token_len..])
+ .unwrap();
+ unstable_bytes.extend_from_slice(&bytes[e.valid_up_to()..]);
+
+```
+
+This interface is important because it defines how tiktoken Tutorial: OpenAI Token Encoding & Optimization implements the patterns covered in this chapter.
+
### `tiktoken/load.py`
The `read_file` function in [`tiktoken/load.py`](https://github.com/openai/tiktoken/blob/HEAD/tiktoken/load.py) handles a key part of this chapter's functionality:
@@ -237,57 +276,16 @@ def read_file_cached(blobpath: str, expected_hash: str | None = None) -> bytes:
This function is important because it defines how tiktoken Tutorial: OpenAI Token Encoding & Optimization implements the patterns covered in this chapter.
-### `tiktoken/load.py`
-
-The `data_gym_to_mergeable_bpe_ranks` function in [`tiktoken/load.py`](https://github.com/openai/tiktoken/blob/HEAD/tiktoken/load.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def data_gym_to_mergeable_bpe_ranks(
- vocab_bpe_file: str,
- encoder_json_file: str,
- vocab_bpe_hash: str | None = None,
- encoder_json_hash: str | None = None,
- clobber_one_byte_tokens: bool = False,
-) -> dict[bytes, int]:
- # NB: do not add caching to this function
- rank_to_intbyte = [b for b in range(2**8) if chr(b).isprintable() and chr(b) != " "]
-
- data_gym_byte_to_byte = {chr(b): b for b in rank_to_intbyte}
- n = 0
- for b in range(2**8):
- if b not in rank_to_intbyte:
- rank_to_intbyte.append(b)
- data_gym_byte_to_byte[chr(2**8 + n)] = b
- n += 1
- assert len(rank_to_intbyte) == 2**8
-
- # vocab_bpe contains the merges along with associated ranks
- vocab_bpe_contents = read_file_cached(vocab_bpe_file, vocab_bpe_hash).decode()
- bpe_merges = [tuple(merge_str.split()) for merge_str in vocab_bpe_contents.split("\n")[1:-1]]
-
- def decode_data_gym(value: str) -> bytes:
- return bytes(data_gym_byte_to_byte[b] for b in value)
-
- # add the single byte tokens
- # if clobber_one_byte_tokens is True, we'll replace these with ones from the encoder json
- bpe_ranks = {bytes([b]): i for i, b in enumerate(rank_to_intbyte)}
- del rank_to_intbyte
-```
-
-This function is important because it defines how tiktoken Tutorial: OpenAI Token Encoding & Optimization implements the patterns covered in this chapter.
-
## How These Components Connect
```mermaid
flowchart TD
- A[read_file]
- B[check_hash]
- C[read_file_cached]
- D[data_gym_to_mergeable_bpe_ranks]
- E[dump_tiktoken_bpe]
+ A[TiktokenBuffer]
+ B[read_file]
+ C[check_hash]
+ D[read_file_cached]
+ E[data_gym_to_mergeable_bpe_ranks]
A --> B
B --> C
C --> D
diff --git a/tutorials/tiktoken-tutorial/02-tokenization-mechanics.md b/tutorials/tiktoken-tutorial/02-tokenization-mechanics.md
index 56cdd729..59822337 100644
--- a/tutorials/tiktoken-tutorial/02-tokenization-mechanics.md
+++ b/tutorials/tiktoken-tutorial/02-tokenization-mechanics.md
@@ -101,17 +101,27 @@ Suggested trace strategy:
- [Main Catalog](../../README.md#-tutorial-catalog)
- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `tiktoken/load.py`
-The `load_tiktoken_bpe` function in [`tiktoken/load.py`](https://github.com/openai/tiktoken/blob/HEAD/tiktoken/load.py) handles a key part of this chapter's functionality:
+The `dump_tiktoken_bpe` function in [`tiktoken/load.py`](https://github.com/openai/tiktoken/blob/HEAD/tiktoken/load.py) handles a key part of this chapter's functionality:
```py
+def dump_tiktoken_bpe(bpe_ranks: dict[bytes, int], tiktoken_bpe_file: str) -> None:
+ try:
+ import blobfile
+ except ImportError as e:
+ raise ImportError(
+ "blobfile is not installed. Please install it by running `pip install blobfile`."
+ ) from e
+ with blobfile.BlobFile(tiktoken_bpe_file, "wb") as f:
+ for token, rank in sorted(bpe_ranks.items(), key=lambda x: x[1]):
+ f.write(base64.b64encode(token) + b" " + str(rank).encode() + b"\n")
+
+
def load_tiktoken_bpe(tiktoken_bpe_file: str, expected_hash: str | None = None) -> dict[bytes, int]:
# NB: do not add caching to this function
contents = read_file_cached(tiktoken_bpe_file, expected_hash)
@@ -130,125 +140,109 @@ def load_tiktoken_bpe(tiktoken_bpe_file: str, expected_hash: str | None = None)
This function is important because it defines how tiktoken Tutorial: OpenAI Token Encoding & Optimization implements the patterns covered in this chapter.
-### `tiktoken/_educational.py`
+### `tiktoken/load.py`
-The `SimpleBytePairEncoding` class in [`tiktoken/_educational.py`](https://github.com/openai/tiktoken/blob/HEAD/tiktoken/_educational.py) handles a key part of this chapter's functionality:
+The `load_tiktoken_bpe` function in [`tiktoken/load.py`](https://github.com/openai/tiktoken/blob/HEAD/tiktoken/load.py) handles a key part of this chapter's functionality:
```py
-class SimpleBytePairEncoding:
- def __init__(self, *, pat_str: str, mergeable_ranks: dict[bytes, int]) -> None:
- """Creates an Encoding object."""
- # A regex pattern string that is used to split the input text
- self.pat_str = pat_str
- # A dictionary mapping token bytes to their ranks. The ranks correspond to merge priority
- self.mergeable_ranks = mergeable_ranks
-
- self._decoder = {token: token_bytes for token_bytes, token in mergeable_ranks.items()}
- self._pat = regex.compile(pat_str)
-
- def encode(self, text: str, visualise: str | None = "colour") -> list[int]:
- """Encodes a string into tokens.
-
- >>> enc.encode("hello world")
- [388, 372]
- """
- # Use the regex to split the text into (approximately) words
- words = self._pat.findall(text)
- tokens = []
- for word in words:
- # Turn each word into tokens, using the byte pair encoding algorithm
- word_bytes = word.encode("utf-8")
- word_tokens = bpe_encode(self.mergeable_ranks, word_bytes, visualise=visualise)
- tokens.extend(word_tokens)
- return tokens
-
- def decode_bytes(self, tokens: list[int]) -> bytes:
- """Decodes a list of tokens into bytes.
+def load_tiktoken_bpe(tiktoken_bpe_file: str, expected_hash: str | None = None) -> dict[bytes, int]:
+ # NB: do not add caching to this function
+ contents = read_file_cached(tiktoken_bpe_file, expected_hash)
+ ret = {}
+ for line in contents.splitlines():
+ if not line:
+ continue
+ try:
+ token, rank = line.split()
+ ret[base64.b64decode(token)] = int(rank)
+ except Exception as e:
+ raise ValueError(f"Error parsing line {line!r} in {tiktoken_bpe_file}") from e
+ return ret
```
-This class is important because it defines how tiktoken Tutorial: OpenAI Token Encoding & Optimization implements the patterns covered in this chapter.
-
-### `tiktoken/_educational.py`
-
-The `bpe_encode` function in [`tiktoken/_educational.py`](https://github.com/openai/tiktoken/blob/HEAD/tiktoken/_educational.py) handles a key part of this chapter's functionality:
-
-```py
- # Turn each word into tokens, using the byte pair encoding algorithm
- word_bytes = word.encode("utf-8")
- word_tokens = bpe_encode(self.mergeable_ranks, word_bytes, visualise=visualise)
- tokens.extend(word_tokens)
- return tokens
-
- def decode_bytes(self, tokens: list[int]) -> bytes:
- """Decodes a list of tokens into bytes.
-
- >>> enc.decode_bytes([388, 372])
- b'hello world'
- """
- return b"".join(self._decoder[token] for token in tokens)
-
- def decode(self, tokens: list[int]) -> str:
- """Decodes a list of tokens into a string.
-
- Decoded bytes are not guaranteed to be valid UTF-8. In that case, we replace
- the invalid bytes with the replacement character "�".
-
- >>> enc.decode([388, 372])
- 'hello world'
- """
- return self.decode_bytes(tokens).decode("utf-8", errors="replace")
-
- def decode_tokens_bytes(self, tokens: list[int]) -> list[bytes]:
- """Decodes a list of tokens into a list of bytes.
-
- Useful for visualising how a string is tokenised.
+This function is important because it defines how tiktoken Tutorial: OpenAI Token Encoding & Optimization implements the patterns covered in this chapter.
- >>> enc.decode_tokens_bytes([388, 372])
- [b'hello', b' world']
+### `src/lib.rs`
+
+The `byte_pair_encode` function in [`src/lib.rs`](https://github.com/openai/tiktoken/blob/HEAD/src/lib.rs) handles a key part of this chapter's functionality:
+
+```rs
+}
+
+pub fn byte_pair_encode(piece: &[u8], ranks: &HashMap<Vec<u8>, Rank>) -> Vec<Rank> {
+ let piece_len = piece.len();
+
+ if piece_len == 1 {
+ return vec![ranks[piece]];
+ }
+ if piece_len < 100 {
+ return _byte_pair_merge(ranks, piece)
+ .windows(2)
+ .map(|part| ranks[&piece[part[0].0..part[1].0]])
+ .collect();
+ }
+ _byte_pair_merge_large(ranks, piece)
+}
+
+pub fn byte_pair_split<'a>(piece: &'a [u8], ranks: &HashMap<Vec<u8>, Rank>) -> Vec<&'a [u8]> {
+ assert!(piece.len() > 1);
+ _byte_pair_merge(ranks, piece)
+ .windows(2)
+ .map(|part| &piece[part[0].0..part[1].0])
+ .collect()
+}
+
+// Various performance notes:
+//
+// Regex
+// =====
+// Most of the time is spent in regex. The easiest way to speed this up is by using less fancy
+// regex features. For instance, using a regex parse-able by `regex` crate is 3x faster than
+// the usual regex we use.
```
This function is important because it defines how tiktoken Tutorial: OpenAI Token Encoding & Optimization implements the patterns covered in this chapter.
-### `tiktoken/_educational.py`
-
-The `bpe_train` function in [`tiktoken/_educational.py`](https://github.com/openai/tiktoken/blob/HEAD/tiktoken/_educational.py) handles a key part of this chapter's functionality:
-
-```py
- def train(training_data: str, vocab_size: int, pat_str: str):
- """Train a BPE tokeniser on some data!"""
- mergeable_ranks = bpe_train(data=training_data, vocab_size=vocab_size, pat_str=pat_str)
- return SimpleBytePairEncoding(pat_str=pat_str, mergeable_ranks=mergeable_ranks)
-
- @staticmethod
- def from_tiktoken(encoding):
- if isinstance(encoding, str):
- encoding = tiktoken.get_encoding(encoding)
- return SimpleBytePairEncoding(
- pat_str=encoding._pat_str, mergeable_ranks=encoding._mergeable_ranks
- )
-
-
-def bpe_encode(
- mergeable_ranks: dict[bytes, int], input: bytes, visualise: str | None = "colour"
-) -> list[int]:
- parts = [bytes([b]) for b in input]
- while True:
- # See the intermediate merges play out!
- if visualise:
- if visualise in ["colour", "color"]:
- visualise_tokens(parts)
- elif visualise == "simple":
- print(parts)
-
- # Iterate over all pairs and find the pair we want to merge the most
- min_idx = None
- min_rank = None
- for i, pair in enumerate(zip(parts[:-1], parts[1:])):
- rank = mergeable_ranks.get(pair[0] + pair[1])
- if rank is not None and (min_rank is None or rank < min_rank):
+### `src/lib.rs`
+
+The `byte_pair_split` function in [`src/lib.rs`](https://github.com/openai/tiktoken/blob/HEAD/src/lib.rs) handles a key part of this chapter's functionality:
+
+```rs
+}
+
+pub fn byte_pair_split<'a>(piece: &'a [u8], ranks: &HashMap<Vec<u8>, Rank>) -> Vec<&'a [u8]> {
+ assert!(piece.len() > 1);
+ _byte_pair_merge(ranks, piece)
+ .windows(2)
+ .map(|part| &piece[part[0].0..part[1].0])
+ .collect()
+}
+
+// Various performance notes:
+//
+// Regex
+// =====
+// Most of the time is spent in regex. The easiest way to speed this up is by using less fancy
+// regex features. For instance, using a regex parse-able by `regex` crate is 3x faster than
+// the usual regex we use.
+//
+// However, given that we're using a regex parse-able by `regex`, there isn't much difference
+// between using the `regex` crate and using the `fancy_regex` crate.
+//
+// There is an important interaction between threading, `regex` and `fancy_regex`.
+// When using `fancy_regex`, we hit `regex.find_at`. It turns out that this causes contention on
+// some mutable scratch space inside of `regex`. This absolutely kills performance. When using plain
+// old `regex`, we don't hit this, because `find_iter` has a different code path.
+// Related: https://github.com/rust-lang/regex/blob/master/PERFORMANCE.md
+// Anyway, the way we get around this is with having a (mostly) thread local clone of the regex for
+// each thread.
+//
+// Threading
+// =========
+// I tried using `rayon`. It wasn't really faster than using Python threads and releasing the GIL.
```
This function is important because it defines how tiktoken Tutorial: OpenAI Token Encoding & Optimization implements the patterns covered in this chapter.
@@ -258,11 +252,11 @@ This function is important because it defines how tiktoken Tutorial: OpenAI Toke
```mermaid
flowchart TD
- A[load_tiktoken_bpe]
- B[SimpleBytePairEncoding]
- C[bpe_encode]
- D[bpe_train]
- E[visualise_tokens]
+ A[dump_tiktoken_bpe]
+ B[load_tiktoken_bpe]
+ C[byte_pair_encode]
+ D[byte_pair_split]
+ E[Merge]
A --> B
B --> C
C --> D
diff --git a/tutorials/tiktoken-tutorial/03-practical-applications.md b/tutorials/tiktoken-tutorial/03-practical-applications.md
index 1b50b416..262b01bc 100644
--- a/tutorials/tiktoken-tutorial/03-practical-applications.md
+++ b/tutorials/tiktoken-tutorial/03-practical-applications.md
@@ -105,171 +105,182 @@ Suggested trace strategy:
- [Main Catalog](../../README.md#-tutorial-catalog)
- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `tiktoken/_educational.py`
-
-The `train_simple_encoding` function in [`tiktoken/_educational.py`](https://github.com/openai/tiktoken/blob/HEAD/tiktoken/_educational.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def train_simple_encoding():
- gpt2_pattern = (
- r"""'s|'t|'re|'ve|'m|'ll|'d| ?[\p{L}]+| ?[\p{N}]+| ?[^\s\p{L}\p{N}]+|\s+(?!\S)|\s+"""
- )
- with open(__file__) as f:
- data = f.read()
+### `src/lib.rs`
- enc = SimpleBytePairEncoding.train(data, vocab_size=600, pat_str=gpt2_pattern)
+The `State` interface in [`src/lib.rs`](https://github.com/openai/tiktoken/blob/HEAD/src/lib.rs) handles a key part of this chapter's functionality:
- print("This is the sequence of merges performed in order to encode 'hello world':")
- tokens = enc.encode("hello world")
- assert enc.decode(tokens) == "hello world"
- assert enc.decode_bytes(tokens) == b"hello world"
- assert enc.decode_tokens_bytes(tokens) == [b"hello", b" world"]
+```rs
+}
- return enc
+struct State {
+ prev: usize,
+ end: usize,
+ next_end: usize,
+ next_rank: Rank,
+ cur_rank: Rank,
+}
+fn _byte_pair_merge_large(ranks: &HashMap<Vec<u8>, Rank>, piece: &[u8]) -> Vec<Rank> {
+ let mut state = Vec::with_capacity(piece.len());
+ state.push(State {
+ prev: usize::MAX,
+ end: 1,
+ next_end: 2,
+ next_rank: Rank::MAX,
+ cur_rank: Rank::MAX,
+ });
+
+ let mut heap = BinaryHeap::with_capacity(piece.len());
+ for i in 0..piece.len() - 1 {
+ if let Some(&rank) = ranks.get(&piece[i..i + 2]) {
+ heap.push(Merge { start: i, rank });
+ state[i].next_rank = rank;
+ }
+ // note this is happening offset by 1
+ state.push(State {
+ prev: i,
+ end: i + 2,
+ next_end: i + 3,
+ next_rank: Rank::MAX,
```
-This function is important because it defines how tiktoken Tutorial: OpenAI Token Encoding & Optimization implements the patterns covered in this chapter.
+This interface is important because it defines how tiktoken Tutorial: OpenAI Token Encoding & Optimization implements the patterns covered in this chapter.
-### `src/py.rs`
+### `src/lib.rs`
-The `TiktokenBuffer` interface in [`src/py.rs`](https://github.com/openai/tiktoken/blob/HEAD/src/py.rs) handles a key part of this chapter's functionality:
+The `FakeThreadId` interface in [`src/lib.rs`](https://github.com/openai/tiktoken/blob/HEAD/src/lib.rs) handles a key part of this chapter's functionality:
```rs
- };
+// to be hashing of two-tuples of ints, which looks like it may also be a couple percent faster.
+
+struct FakeThreadId(NonZeroU64);
+
+fn hash_current_thread() -> usize {
+ // It's easier to use unsafe than to use nightly. Rust has this nice u64 thread id counter
+ // that works great for our use case of avoiding collisions in our array. Unfortunately,
+ // it's private. However, there are only so many ways you can layout a u64, so just transmute
+ // https://github.com/rust-lang/rust/issues/67939
+ const _: [u8; 8] = [0; std::mem::size_of::<std::thread::ThreadId>()];
+ const _: [u8; 8] = [0; std::mem::size_of::<FakeThreadId>()];
+ let x = unsafe {
+ std::mem::transmute::<std::thread::ThreadId, FakeThreadId>(thread::current().id()).0
+ };
+ u64::from(x) as usize
+}
+
+#[derive(Debug, Clone)]
+pub struct DecodeKeyError {
+ pub token: Rank,
+}
- let buffer = TiktokenBuffer { tokens };
- buffer.into_py_any(py)
+impl std::fmt::Display for DecodeKeyError {
+ fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
+ write!(f, "Invalid token for decoding: {}", self.token)
}
+}
- fn _encode_bytes(&self, py: Python, bytes: &[u8]) -> Vec<Rank> {
- py.detach(|| {
- match std::str::from_utf8(bytes) {
- // Straightforward case
- Ok(text) => self.encode_ordinary(text),
- // Oops, don't actually have UTF-8. But we need to do the regex splitting in
- // Unicode space, so we make our best guess at where we would have splits
- Err(e) => {
- let text = unsafe { std::str::from_utf8_unchecked(&bytes[..e.valid_up_to()]) };
- let (tokens, last_piece_token_len) =
- self.encode(text, &HashSet::new()).unwrap();
- let (mut tokens, last_piece_token_len) =
- self._increase_last_piece_token_len(tokens, last_piece_token_len);
-
- let mut unstable_bytes;
- if !tokens.is_empty() && last_piece_token_len > 0 {
- // Lop off the tokens from the last piece and run BPE on the remaining bytes
- // This likely matches what models see better, e.g. if you assume we're
- // dealing with truncated UTF-8 bytes.
- // Niche, but note this may not be correct if we'd have had a regex
- // split between the valid UTF-8 and the invalid bytes.
- unstable_bytes = self
- .decode_bytes(&tokens[tokens.len() - last_piece_token_len..])
- .unwrap();
- unstable_bytes.extend_from_slice(&bytes[e.valid_up_to()..]);
+impl std::error::Error for DecodeKeyError {}
+#[derive(Debug, Clone)]
+pub struct DecodeError {
```
This interface is important because it defines how tiktoken Tutorial: OpenAI Token Encoding & Optimization implements the patterns covered in this chapter.
### `src/lib.rs`
-The `byte_pair_encode` function in [`src/lib.rs`](https://github.com/openai/tiktoken/blob/HEAD/src/lib.rs) handles a key part of this chapter's functionality:
+The `DecodeKeyError` interface in [`src/lib.rs`](https://github.com/openai/tiktoken/blob/HEAD/src/lib.rs) handles a key part of this chapter's functionality:
```rs
-}
-pub fn byte_pair_encode(piece: &[u8], ranks: &HashMap<Vec<u8>, Rank>) -> Vec<Rank> {
- let piece_len = piece.len();
+#[derive(Debug, Clone)]
+pub struct DecodeKeyError {
+ pub token: Rank,
+}
- if piece_len == 1 {
- return vec![ranks[piece]];
+impl std::fmt::Display for DecodeKeyError {
+ fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
+ write!(f, "Invalid token for decoding: {}", self.token)
}
- if piece_len < 100 {
- return _byte_pair_merge(ranks, piece)
- .windows(2)
- .map(|part| ranks[&piece[part[0].0..part[1].0]])
- .collect();
+}
+
+impl std::error::Error for DecodeKeyError {}
+
+#[derive(Debug, Clone)]
+pub struct DecodeError {
+ pub message: String,
+}
+
+impl std::fmt::Display for DecodeError {
+ fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
+ write!(f, "Could not decode tokens: {}", self.message)
}
- _byte_pair_merge_large(ranks, piece)
}
-pub fn byte_pair_split<'a>(piece: &'a [u8], ranks: &HashMap<Vec<u8>, Rank>) -> Vec<&'a [u8]> {
- assert!(piece.len() > 1);
- _byte_pair_merge(ranks, piece)
- .windows(2)
- .map(|part| &piece[part[0].0..part[1].0])
- .collect()
+impl std::error::Error for DecodeError {}
+
+#[derive(Debug, Clone)]
+pub struct EncodeError {
+ pub message: String,
}
-// Various performance notes:
-//
-// Regex
-// =====
-// Most of the time is spent in regex. The easiest way to speed this up is by using less fancy
-// regex features. For instance, using a regex parse-able by `regex` crate is 3x faster than
-// the usual regex we use.
```
-This function is important because it defines how tiktoken Tutorial: OpenAI Token Encoding & Optimization implements the patterns covered in this chapter.
+This interface is important because it defines how tiktoken Tutorial: OpenAI Token Encoding & Optimization implements the patterns covered in this chapter.
### `src/lib.rs`
-The `byte_pair_split` function in [`src/lib.rs`](https://github.com/openai/tiktoken/blob/HEAD/src/lib.rs) handles a key part of this chapter's functionality:
+The `DecodeError` interface in [`src/lib.rs`](https://github.com/openai/tiktoken/blob/HEAD/src/lib.rs) handles a key part of this chapter's functionality:
```rs
+
+#[derive(Debug, Clone)]
+pub struct DecodeError {
+ pub message: String,
}
-pub fn byte_pair_split<'a>(piece: &'a [u8], ranks: &HashMap<Vec<u8>, Rank>) -> Vec<&'a [u8]> {
- assert!(piece.len() > 1);
- _byte_pair_merge(ranks, piece)
- .windows(2)
- .map(|part| &piece[part[0].0..part[1].0])
- .collect()
+impl std::fmt::Display for DecodeError {
+ fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
+ write!(f, "Could not decode tokens: {}", self.message)
+ }
}
-// Various performance notes:
-//
-// Regex
-// =====
-// Most of the time is spent in regex. The easiest way to speed this up is by using less fancy
-// regex features. For instance, using a regex parse-able by `regex` crate is 3x faster than
-// the usual regex we use.
-//
-// However, given that we're using a regex parse-able by `regex`, there isn't much difference
-// between using the `regex` crate and using the `fancy_regex` crate.
-//
-// There is an important interaction between threading, `regex` and `fancy_regex`.
-// When using `fancy_regex`, we hit `regex.find_at`. It turns out that this causes contention on
-// some mutable scratch space inside of `regex`. This absolutely kills performance. When using plain
-// old `regex`, we don't hit this, because `find_iter` has a different code path.
-// Related: https://github.com/rust-lang/regex/blob/master/PERFORMANCE.md
-// Anyway, the way we get around this is with having a (mostly) thread local clone of the regex for
-// each thread.
-//
-// Threading
-// =========
-// I tried using `rayon`. It wasn't really faster than using Python threads and releasing the GIL.
+impl std::error::Error for DecodeError {}
+
+#[derive(Debug, Clone)]
+pub struct EncodeError {
+ pub message: String,
+}
+
+impl std::fmt::Display for EncodeError {
+ fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
+ write!(f, "Could not encode string: {}", self.message)
+ }
+}
+
+impl std::error::Error for EncodeError {}
+
+const MAX_NUM_THREADS: usize = 128;
+
+#[cfg_attr(feature = "python", pyclass(frozen))]
+#[derive(Clone)]
+pub struct CoreBPE {
```
-This function is important because it defines how tiktoken Tutorial: OpenAI Token Encoding & Optimization implements the patterns covered in this chapter.
+This interface is important because it defines how tiktoken Tutorial: OpenAI Token Encoding & Optimization implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[train_simple_encoding]
- B[TiktokenBuffer]
- C[byte_pair_encode]
- D[byte_pair_split]
- E[Merge]
+ A[State]
+ B[FakeThreadId]
+ C[DecodeKeyError]
+ D[DecodeError]
+ E[EncodeError]
A --> B
B --> C
C --> D
diff --git a/tutorials/tiktoken-tutorial/04-educational-module.md b/tutorials/tiktoken-tutorial/04-educational-module.md
index 51143ba8..2a0b8298 100644
--- a/tutorials/tiktoken-tutorial/04-educational-module.md
+++ b/tutorials/tiktoken-tutorial/04-educational-module.md
@@ -96,184 +96,182 @@ Suggested trace strategy:
- [Main Catalog](../../README.md#-tutorial-catalog)
- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `src/lib.rs`
-The `State` interface in [`src/lib.rs`](https://github.com/openai/tiktoken/blob/HEAD/src/lib.rs) handles a key part of this chapter's functionality:
+The `CoreBPE` interface in [`src/lib.rs`](https://github.com/openai/tiktoken/blob/HEAD/src/lib.rs) handles a key part of this chapter's functionality:
```rs
+#[cfg_attr(feature = "python", pyclass(frozen))]
+#[derive(Clone)]
+pub struct CoreBPE {
+ encoder: HashMap<Vec<u8>, Rank>,
+ special_tokens_encoder: HashMap<String, Rank>,
+ decoder: HashMap<Rank, Vec<u8>>,
+ special_tokens_decoder: HashMap<Rank, Vec<u8>>,
+ regex_tls: Vec<Regex>,
+ special_regex_tls: Vec<Regex>,
+ sorted_token_bytes: Vec<Vec<u8>>,
}
-struct State {
- prev: usize,
- end: usize,
- next_end: usize,
- next_rank: Rank,
- cur_rank: Rank,
-}
-
-fn _byte_pair_merge_large(ranks: &HashMap<Vec<u8>, Rank>, piece: &[u8]) -> Vec<Rank> {
- let mut state = Vec::with_capacity(piece.len());
- state.push(State {
- prev: usize::MAX,
- end: 1,
- next_end: 2,
- next_rank: Rank::MAX,
- cur_rank: Rank::MAX,
- });
-
- let mut heap = BinaryHeap::with_capacity(piece.len());
- for i in 0..piece.len() - 1 {
- if let Some(&rank) = ranks.get(&piece[i..i + 2]) {
- heap.push(Merge { start: i, rank });
- state[i].next_rank = rank;
- }
- // note this is happening offset by 1
- state.push(State {
- prev: i,
- end: i + 2,
- next_end: i + 3,
- next_rank: Rank::MAX,
-```
-
-This interface is important because it defines how tiktoken Tutorial: OpenAI Token Encoding & Optimization implements the patterns covered in this chapter.
-
-### `src/lib.rs`
-
-The `FakeThreadId` interface in [`src/lib.rs`](https://github.com/openai/tiktoken/blob/HEAD/src/lib.rs) handles a key part of this chapter's functionality:
-
-```rs
-// to be hashing of two-tuples of ints, which looks like it may also be a couple percent faster.
-
-struct FakeThreadId(NonZeroU64);
-
-fn hash_current_thread() -> usize {
- // It's easier to use unsafe than to use nightly. Rust has this nice u64 thread id counter
- // that works great for our use case of avoiding collisions in our array. Unfortunately,
- // it's private. However, there are only so many ways you can layout a u64, so just transmute
- // https://github.com/rust-lang/rust/issues/67939
- const _: [u8; 8] = [0; std::mem::size_of::<std::thread::ThreadId>()];
- const _: [u8; 8] = [0; std::mem::size_of::<FakeThreadId>()];
- let x = unsafe {
- std::mem::transmute::<std::thread::ThreadId, FakeThreadId>(thread::current().id()).0
- };
- u64::from(x) as usize
-}
-
-#[derive(Debug, Clone)]
-pub struct DecodeKeyError {
- pub token: Rank,
-}
-
-impl std::fmt::Display for DecodeKeyError {
- fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
- write!(f, "Invalid token for decoding: {}", self.token)
+impl CoreBPE {
+ fn _get_tl_regex(&self) -> &Regex {
+ // See performance notes above for what this is about
+ // It's also a little janky, please make a better version of it!
+ // However, it's nice that this doesn't leak memory to short-lived threads
+ &self.regex_tls[hash_current_thread() % MAX_NUM_THREADS]
}
-}
-impl std::error::Error for DecodeKeyError {}
+ fn _get_tl_special_regex(&self) -> &Regex {
+ &self.special_regex_tls[hash_current_thread() % MAX_NUM_THREADS]
+ }
-#[derive(Debug, Clone)]
-pub struct DecodeError {
+ /// Decodes tokens into a list of bytes.
+ ///
+ /// The bytes are not gauranteed to be a valid utf-8 string.
+ fn decode_bytes(&self, tokens: &[Rank]) -> Result<Vec<u8>, DecodeKeyError> {
+ let mut ret = Vec::with_capacity(tokens.len() * 2);
+ for &token in tokens {
+ let token_bytes = match self.decoder.get(&token) {
+ Some(bytes) => bytes,
```
This interface is important because it defines how tiktoken Tutorial: OpenAI Token Encoding & Optimization implements the patterns covered in this chapter.
-### `src/lib.rs`
+### `tiktoken/_educational.py`
-The `DecodeKeyError` interface in [`src/lib.rs`](https://github.com/openai/tiktoken/blob/HEAD/src/lib.rs) handles a key part of this chapter's functionality:
+The `SimpleBytePairEncoding` class in [`tiktoken/_educational.py`](https://github.com/openai/tiktoken/blob/HEAD/tiktoken/_educational.py) handles a key part of this chapter's functionality:
-```rs
+```py
-#[derive(Debug, Clone)]
-pub struct DecodeKeyError {
- pub token: Rank,
-}
-impl std::fmt::Display for DecodeKeyError {
- fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
- write!(f, "Invalid token for decoding: {}", self.token)
- }
-}
+class SimpleBytePairEncoding:
+ def __init__(self, *, pat_str: str, mergeable_ranks: dict[bytes, int]) -> None:
+ """Creates an Encoding object."""
+ # A regex pattern string that is used to split the input text
+ self.pat_str = pat_str
+ # A dictionary mapping token bytes to their ranks. The ranks correspond to merge priority
+ self.mergeable_ranks = mergeable_ranks
-impl std::error::Error for DecodeKeyError {}
+ self._decoder = {token: token_bytes for token_bytes, token in mergeable_ranks.items()}
+ self._pat = regex.compile(pat_str)
-#[derive(Debug, Clone)]
-pub struct DecodeError {
- pub message: String,
-}
+ def encode(self, text: str, visualise: str | None = "colour") -> list[int]:
+ """Encodes a string into tokens.
-impl std::fmt::Display for DecodeError {
- fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
- write!(f, "Could not decode tokens: {}", self.message)
- }
-}
+ >>> enc.encode("hello world")
+ [388, 372]
+ """
+ # Use the regex to split the text into (approximately) words
+ words = self._pat.findall(text)
+ tokens = []
+ for word in words:
+ # Turn each word into tokens, using the byte pair encoding algorithm
+ word_bytes = word.encode("utf-8")
+ word_tokens = bpe_encode(self.mergeable_ranks, word_bytes, visualise=visualise)
+ tokens.extend(word_tokens)
+ return tokens
-impl std::error::Error for DecodeError {}
-
-#[derive(Debug, Clone)]
-pub struct EncodeError {
- pub message: String,
-}
+ def decode_bytes(self, tokens: list[int]) -> bytes:
+ """Decodes a list of tokens into bytes.
```
-This interface is important because it defines how tiktoken Tutorial: OpenAI Token Encoding & Optimization implements the patterns covered in this chapter.
+This class is important because it defines how tiktoken Tutorial: OpenAI Token Encoding & Optimization implements the patterns covered in this chapter.
-### `src/lib.rs`
+### `tiktoken/_educational.py`
-The `DecodeError` interface in [`src/lib.rs`](https://github.com/openai/tiktoken/blob/HEAD/src/lib.rs) handles a key part of this chapter's functionality:
+The `bpe_encode` function in [`tiktoken/_educational.py`](https://github.com/openai/tiktoken/blob/HEAD/tiktoken/_educational.py) handles a key part of this chapter's functionality:
-```rs
+```py
+ # Turn each word into tokens, using the byte pair encoding algorithm
+ word_bytes = word.encode("utf-8")
+ word_tokens = bpe_encode(self.mergeable_ranks, word_bytes, visualise=visualise)
+ tokens.extend(word_tokens)
+ return tokens
-#[derive(Debug, Clone)]
-pub struct DecodeError {
- pub message: String,
-}
+ def decode_bytes(self, tokens: list[int]) -> bytes:
+ """Decodes a list of tokens into bytes.
-impl std::fmt::Display for DecodeError {
- fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
- write!(f, "Could not decode tokens: {}", self.message)
- }
-}
+ >>> enc.decode_bytes([388, 372])
+ b'hello world'
+ """
+ return b"".join(self._decoder[token] for token in tokens)
-impl std::error::Error for DecodeError {}
+ def decode(self, tokens: list[int]) -> str:
+ """Decodes a list of tokens into a string.
-#[derive(Debug, Clone)]
-pub struct EncodeError {
- pub message: String,
-}
+ Decoded bytes are not guaranteed to be valid UTF-8. In that case, we replace
+ the invalid bytes with the replacement character "�".
-impl std::fmt::Display for EncodeError {
- fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
- write!(f, "Could not encode string: {}", self.message)
- }
-}
+ >>> enc.decode([388, 372])
+ 'hello world'
+ """
+ return self.decode_bytes(tokens).decode("utf-8", errors="replace")
-impl std::error::Error for EncodeError {}
+ def decode_tokens_bytes(self, tokens: list[int]) -> list[bytes]:
+ """Decodes a list of tokens into a list of bytes.
-const MAX_NUM_THREADS: usize = 128;
+ Useful for visualising how a string is tokenised.
-#[cfg_attr(feature = "python", pyclass(frozen))]
-#[derive(Clone)]
-pub struct CoreBPE {
+ >>> enc.decode_tokens_bytes([388, 372])
+ [b'hello', b' world']
```
-This interface is important because it defines how tiktoken Tutorial: OpenAI Token Encoding & Optimization implements the patterns covered in this chapter.
+This function is important because it defines how tiktoken Tutorial: OpenAI Token Encoding & Optimization implements the patterns covered in this chapter.
+
+### `tiktoken/_educational.py`
+
+The `bpe_train` function in [`tiktoken/_educational.py`](https://github.com/openai/tiktoken/blob/HEAD/tiktoken/_educational.py) handles a key part of this chapter's functionality:
+
+```py
+ def train(training_data: str, vocab_size: int, pat_str: str):
+ """Train a BPE tokeniser on some data!"""
+ mergeable_ranks = bpe_train(data=training_data, vocab_size=vocab_size, pat_str=pat_str)
+ return SimpleBytePairEncoding(pat_str=pat_str, mergeable_ranks=mergeable_ranks)
+
+ @staticmethod
+ def from_tiktoken(encoding):
+ if isinstance(encoding, str):
+ encoding = tiktoken.get_encoding(encoding)
+ return SimpleBytePairEncoding(
+ pat_str=encoding._pat_str, mergeable_ranks=encoding._mergeable_ranks
+ )
+
+
+def bpe_encode(
+ mergeable_ranks: dict[bytes, int], input: bytes, visualise: str | None = "colour"
+) -> list[int]:
+ parts = [bytes([b]) for b in input]
+ while True:
+ # See the intermediate merges play out!
+ if visualise:
+ if visualise in ["colour", "color"]:
+ visualise_tokens(parts)
+ elif visualise == "simple":
+ print(parts)
+
+ # Iterate over all pairs and find the pair we want to merge the most
+ min_idx = None
+ min_rank = None
+ for i, pair in enumerate(zip(parts[:-1], parts[1:])):
+ rank = mergeable_ranks.get(pair[0] + pair[1])
+ if rank is not None and (min_rank is None or rank < min_rank):
+```
+
+This function is important because it defines how tiktoken Tutorial: OpenAI Token Encoding & Optimization implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[State]
- B[FakeThreadId]
- C[DecodeKeyError]
- D[DecodeError]
- E[EncodeError]
+ A[CoreBPE]
+ B[SimpleBytePairEncoding]
+ C[bpe_encode]
+ D[bpe_train]
+ E[visualise_tokens]
A --> B
B --> C
C --> D
diff --git a/tutorials/tiktoken-tutorial/05-optimization-strategies.md b/tutorials/tiktoken-tutorial/05-optimization-strategies.md
index d85961ac..3757bbb2 100644
--- a/tutorials/tiktoken-tutorial/05-optimization-strategies.md
+++ b/tutorials/tiktoken-tutorial/05-optimization-strategies.md
@@ -111,50 +111,35 @@ Suggested trace strategy:
- [Main Catalog](../../README.md#-tutorial-catalog)
- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `src/lib.rs`
-
-The `CoreBPE` interface in [`src/lib.rs`](https://github.com/openai/tiktoken/blob/HEAD/src/lib.rs) handles a key part of this chapter's functionality:
-
-```rs
-#[cfg_attr(feature = "python", pyclass(frozen))]
-#[derive(Clone)]
-pub struct CoreBPE {
- encoder: HashMap<Vec<u8>, Rank>,
- special_tokens_encoder: HashMap<String, Rank>,
- decoder: HashMap<Rank, Vec<u8>>,
- special_tokens_decoder: HashMap<Rank, Vec<u8>>,
- regex_tls: Vec<Regex>,
- special_regex_tls: Vec<Regex>,
- sorted_token_bytes: Vec<Vec<u8>>,
-}
-
-impl CoreBPE {
- fn _get_tl_regex(&self) -> &Regex {
- // See performance notes above for what this is about
- // It's also a little janky, please make a better version of it!
- // However, it's nice that this doesn't leak memory to short-lived threads
- &self.regex_tls[hash_current_thread() % MAX_NUM_THREADS]
- }
-
- fn _get_tl_special_regex(&self) -> &Regex {
- &self.special_regex_tls[hash_current_thread() % MAX_NUM_THREADS]
- }
-
- /// Decodes tokens into a list of bytes.
- ///
- /// The bytes are not gauranteed to be a valid utf-8 string.
- fn decode_bytes(&self, tokens: &[Rank]) -> Result<Vec<u8>, DecodeKeyError> {
- let mut ret = Vec::with_capacity(tokens.len() * 2);
- for &token in tokens {
- let token_bytes = match self.decoder.get(&token) {
- Some(bytes) => bytes,
+### `tiktoken/_educational.py`
+
+The `train_simple_encoding` function in [`tiktoken/_educational.py`](https://github.com/openai/tiktoken/blob/HEAD/tiktoken/_educational.py) handles a key part of this chapter's functionality:
+
+```py
+
+
+def train_simple_encoding():
+ gpt2_pattern = (
+ r"""'s|'t|'re|'ve|'m|'ll|'d| ?[\p{L}]+| ?[\p{N}]+| ?[^\s\p{L}\p{N}]+|\s+(?!\S)|\s+"""
+ )
+ with open(__file__) as f:
+ data = f.read()
+
+ enc = SimpleBytePairEncoding.train(data, vocab_size=600, pat_str=gpt2_pattern)
+
+ print("This is the sequence of merges performed in order to encode 'hello world':")
+ tokens = enc.encode("hello world")
+ assert enc.decode(tokens) == "hello world"
+ assert enc.decode_bytes(tokens) == b"hello world"
+ assert enc.decode_tokens_bytes(tokens) == [b"hello", b" world"]
+
+ return enc
+
```
-This interface is important because it defines how tiktoken Tutorial: OpenAI Token Encoding & Optimization implements the patterns covered in this chapter.
+This function is important because it defines how tiktoken Tutorial: OpenAI Token Encoding & Optimization implements the patterns covered in this chapter.
### `tiktoken/core.py`
@@ -282,7 +267,7 @@ This interface is important because it defines how tiktoken Tutorial: OpenAI Tok
```mermaid
flowchart TD
- A[CoreBPE]
+ A[train_simple_encoding]
B[Encoding]
C[raise_disallowed_special_token]
D[an]
diff --git a/tutorials/tiktoken-tutorial/06-chatml-and-tool-calls.md b/tutorials/tiktoken-tutorial/06-chatml-and-tool-calls.md
index f5dd40e2..35fad010 100644
--- a/tutorials/tiktoken-tutorial/06-chatml-and-tool-calls.md
+++ b/tutorials/tiktoken-tutorial/06-chatml-and-tool-calls.md
@@ -103,8 +103,6 @@ Suggested trace strategy:
- [Main Catalog](../../README.md#-tutorial-catalog)
- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `tiktoken/model.py`
@@ -125,125 +123,125 @@ def encoding_for_model(model_name: str) -> Encoding:
This function is important because it defines how tiktoken Tutorial: OpenAI Token Encoding & Optimization implements the patterns covered in this chapter.
-### `scripts/wheel_download.py`
+### `tiktoken_ext/openai_public.py`
-The `download_artifacts` function in [`scripts/wheel_download.py`](https://github.com/openai/tiktoken/blob/HEAD/scripts/wheel_download.py) handles a key part of this chapter's functionality:
+The `gpt2` function in [`tiktoken_ext/openai_public.py`](https://github.com/openai/tiktoken/blob/HEAD/tiktoken_ext/openai_public.py) handles a key part of this chapter's functionality:
```py
-def download_artifacts(token, owner, repo, run_id, output_dir):
- headers = {"Authorization": f"token {token}", "Accept": "application/vnd.github.v3+json"}
-
- # Get list of artifacts
- artifacts_url = f"https://api.github.com/repos/{owner}/{repo}/actions/runs/{run_id}/artifacts"
- response = requests.get(artifacts_url, headers=headers)
- response.raise_for_status()
- artifacts = response.json()["artifacts"]
-
- if not artifacts:
- print(f"No artifacts found for run ID: {run_id}")
- return
-
- output_dir = Path(output_dir)
- output_dir.mkdir(parents=True, exist_ok=True)
-
- print(f"Found {len(artifacts)} artifacts")
- for artifact in artifacts:
- name = artifact["name"]
- download_url = artifact["archive_download_url"]
-
- print(f"Downloading {name}...")
+def gpt2():
+ mergeable_ranks = data_gym_to_mergeable_bpe_ranks(
+ vocab_bpe_file="https://openaipublic.blob.core.windows.net/gpt-2/encodings/main/vocab.bpe",
+ encoder_json_file="https://openaipublic.blob.core.windows.net/gpt-2/encodings/main/encoder.json",
+ vocab_bpe_hash="1ce1664773c50f3e0cc8842619a93edc4624525b728b188a9e0be33b7726adc5",
+ encoder_json_hash="196139668be63f3b5d6574427317ae82f612a97c5d1cdaf36ed2256dbf636783",
+ )
+ return {
+ "name": "gpt2",
+ "explicit_n_vocab": 50257,
+ "pat_str": r50k_pat_str,
+ "mergeable_ranks": mergeable_ranks,
+ "special_tokens": {ENDOFTEXT: 50256},
+ }
+
+
+def r50k_base():
+ mergeable_ranks = load_tiktoken_bpe(
+ "https://openaipublic.blob.core.windows.net/encodings/r50k_base.tiktoken",
+ expected_hash="306cd27f03c1a714eca7108e03d66b7dc042abe8c258b44c199a7ed9838dd930",
+ )
+ return {
+ "name": "r50k_base",
+ "explicit_n_vocab": 50257,
+ "pat_str": r50k_pat_str,
+ "mergeable_ranks": mergeable_ranks,
+ "special_tokens": {ENDOFTEXT: 50256},
+ }
- response = requests.get(download_url, headers=headers, stream=True)
- response.raise_for_status()
- temp_zip = output_dir / f"{name}.zip"
- with open(temp_zip, "wb") as f:
- for chunk in response.iter_content(chunk_size=8192):
- f.write(chunk)
```
This function is important because it defines how tiktoken Tutorial: OpenAI Token Encoding & Optimization implements the patterns covered in this chapter.
-### `scripts/redact.py`
+### `tiktoken_ext/openai_public.py`
-The `redact_file` function in [`scripts/redact.py`](https://github.com/openai/tiktoken/blob/HEAD/scripts/redact.py) handles a key part of this chapter's functionality:
+The `r50k_base` function in [`tiktoken_ext/openai_public.py`](https://github.com/openai/tiktoken/blob/HEAD/tiktoken_ext/openai_public.py) handles a key part of this chapter's functionality:
```py
-def redact_file(path: Path, dry_run: bool) -> None:
- if not path.exists() or path.is_dir():
- return
-
- text = path.read_text()
- if not text:
- return
-
- first_line = text.splitlines()[0]
- if "redact" in first_line:
- if not dry_run:
- path.unlink()
- print(f"Deleted {path}")
- return
-
- pattern = "|".join(
- r" *" + re.escape(x)
- for x in [
- "# ===== redact-beg =====\n",
- "# ===== redact-end =====\n",
- "<!--- redact-beg -->\n",
- "<!--- redact-end -->\n",
- ]
+def r50k_base():
+ mergeable_ranks = load_tiktoken_bpe(
+ "https://openaipublic.blob.core.windows.net/encodings/r50k_base.tiktoken",
+ expected_hash="306cd27f03c1a714eca7108e03d66b7dc042abe8c258b44c199a7ed9838dd930",
+ )
+ return {
+ "name": "r50k_base",
+ "explicit_n_vocab": 50257,
+ "pat_str": r50k_pat_str,
+ "mergeable_ranks": mergeable_ranks,
+ "special_tokens": {ENDOFTEXT: 50256},
+ }
+
+
+def p50k_base():
+ mergeable_ranks = load_tiktoken_bpe(
+ "https://openaipublic.blob.core.windows.net/encodings/p50k_base.tiktoken",
+ expected_hash="94b5ca7dff4d00767bc256fdd1b27e5b17361d7b8a5f968547f9f23eb70d2069",
)
+ return {
+ "name": "p50k_base",
+ "explicit_n_vocab": 50281,
+ "pat_str": r50k_pat_str,
+ "mergeable_ranks": mergeable_ranks,
+ "special_tokens": {ENDOFTEXT: 50256},
+ }
- if re.search(pattern, text):
- redacted_text = "".join(re.split(pattern, text)[::2])
- if not dry_run:
- path.write_text(redacted_text)
- print(f"Redacted {path}")
+
+def p50k_edit():
+ mergeable_ranks = load_tiktoken_bpe(
```
This function is important because it defines how tiktoken Tutorial: OpenAI Token Encoding & Optimization implements the patterns covered in this chapter.
-### `scripts/redact.py`
+### `tiktoken_ext/openai_public.py`
-The `redact` function in [`scripts/redact.py`](https://github.com/openai/tiktoken/blob/HEAD/scripts/redact.py) handles a key part of this chapter's functionality:
+The `p50k_base` function in [`tiktoken_ext/openai_public.py`](https://github.com/openai/tiktoken/blob/HEAD/tiktoken_ext/openai_public.py) handles a key part of this chapter's functionality:
```py
-def redact_file(path: Path, dry_run: bool) -> None:
- if not path.exists() or path.is_dir():
- return
-
- text = path.read_text()
- if not text:
- return
-
- first_line = text.splitlines()[0]
- if "redact" in first_line:
- if not dry_run:
- path.unlink()
- print(f"Deleted {path}")
- return
-
- pattern = "|".join(
- r" *" + re.escape(x)
- for x in [
- "# ===== redact-beg =====\n",
- "# ===== redact-end =====\n",
- "<!--- redact-beg -->\n",
- "<!--- redact-end -->\n",
- ]
+def p50k_base():
+ mergeable_ranks = load_tiktoken_bpe(
+ "https://openaipublic.blob.core.windows.net/encodings/p50k_base.tiktoken",
+ expected_hash="94b5ca7dff4d00767bc256fdd1b27e5b17361d7b8a5f968547f9f23eb70d2069",
+ )
+ return {
+ "name": "p50k_base",
+ "explicit_n_vocab": 50281,
+ "pat_str": r50k_pat_str,
+ "mergeable_ranks": mergeable_ranks,
+ "special_tokens": {ENDOFTEXT: 50256},
+ }
+
+
+def p50k_edit():
+ mergeable_ranks = load_tiktoken_bpe(
+ "https://openaipublic.blob.core.windows.net/encodings/p50k_base.tiktoken",
+ expected_hash="94b5ca7dff4d00767bc256fdd1b27e5b17361d7b8a5f968547f9f23eb70d2069",
)
+ special_tokens = {ENDOFTEXT: 50256, FIM_PREFIX: 50281, FIM_MIDDLE: 50282, FIM_SUFFIX: 50283}
+ return {
+ "name": "p50k_edit",
+ "pat_str": r50k_pat_str,
+ "mergeable_ranks": mergeable_ranks,
+ "special_tokens": special_tokens,
+ }
+
- if re.search(pattern, text):
- redacted_text = "".join(re.split(pattern, text)[::2])
- if not dry_run:
- path.write_text(redacted_text)
- print(f"Redacted {path}")
+def cl100k_base():
+ mergeable_ranks = load_tiktoken_bpe(
```
This function is important because it defines how tiktoken Tutorial: OpenAI Token Encoding & Optimization implements the patterns covered in this chapter.
@@ -254,10 +252,10 @@ This function is important because it defines how tiktoken Tutorial: OpenAI Toke
```mermaid
flowchart TD
A[encoding_for_model]
- B[download_artifacts]
- C[redact_file]
- D[redact]
- E[main]
+ B[gpt2]
+ C[r50k_base]
+ D[p50k_base]
+ E[p50k_edit]
A --> B
B --> C
C --> D
diff --git a/tutorials/tiktoken-tutorial/07-multilingual-tokenization.md b/tutorials/tiktoken-tutorial/07-multilingual-tokenization.md
index 3f73a54a..835e41ea 100644
--- a/tutorials/tiktoken-tutorial/07-multilingual-tokenization.md
+++ b/tutorials/tiktoken-tutorial/07-multilingual-tokenization.md
@@ -99,147 +99,168 @@ Suggested trace strategy:
- [Main Catalog](../../README.md#-tutorial-catalog)
- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `tiktoken/registry.py`
+### `tiktoken_ext/openai_public.py`
-The `get_encoding` function in [`tiktoken/registry.py`](https://github.com/openai/tiktoken/blob/HEAD/tiktoken/registry.py) handles a key part of this chapter's functionality:
+The `cl100k_base` function in [`tiktoken_ext/openai_public.py`](https://github.com/openai/tiktoken/blob/HEAD/tiktoken_ext/openai_public.py) handles a key part of this chapter's functionality:
```py
-def get_encoding(encoding_name: str) -> Encoding:
- if not isinstance(encoding_name, str):
- raise ValueError(f"Expected a string in get_encoding, got {type(encoding_name)}")
-
- if encoding_name in ENCODINGS:
- return ENCODINGS[encoding_name]
-
- with _lock:
- if encoding_name in ENCODINGS:
- return ENCODINGS[encoding_name]
-
- if ENCODING_CONSTRUCTORS is None:
- _find_constructors()
- assert ENCODING_CONSTRUCTORS is not None
-
- if encoding_name not in ENCODING_CONSTRUCTORS:
- raise ValueError(
- f"Unknown encoding {encoding_name}.\n"
- f"Plugins found: {_available_plugin_modules()}\n"
- f"tiktoken version: {tiktoken.__version__} (are you on latest?)"
- )
-
- constructor = ENCODING_CONSTRUCTORS[encoding_name]
- enc = Encoding(**constructor())
- ENCODINGS[encoding_name] = enc
- return enc
+def cl100k_base():
+ mergeable_ranks = load_tiktoken_bpe(
+ "https://openaipublic.blob.core.windows.net/encodings/cl100k_base.tiktoken",
+ expected_hash="223921b76ee99bde995b7ff738513eef100fb51d18c93597a113bcffe865b2a7",
+ )
+ special_tokens = {
+ ENDOFTEXT: 100257,
+ FIM_PREFIX: 100258,
+ FIM_MIDDLE: 100259,
+ FIM_SUFFIX: 100260,
+ ENDOFPROMPT: 100276,
+ }
+ return {
+ "name": "cl100k_base",
+ "pat_str": r"""'(?i:[sdmt]|ll|ve|re)|[^\r\n\p{L}\p{N}]?+\p{L}++|\p{N}{1,3}+| ?[^\s\p{L}\p{N}]++[\r\n]*+|\s++$|\s*[\r\n]|\s+(?!\S)|\s""",
+ "mergeable_ranks": mergeable_ranks,
+ "special_tokens": special_tokens,
+ }
-def list_encoding_names() -> list[str]:
- with _lock:
+def o200k_base():
+ mergeable_ranks = load_tiktoken_bpe(
+ "https://openaipublic.blob.core.windows.net/encodings/o200k_base.tiktoken",
+ expected_hash="446a9538cb6c348e3516120d7c08b09f57c36495e2acfffe59a5bf8b0cfb1a2d",
+ )
+ special_tokens = {ENDOFTEXT: 199999, ENDOFPROMPT: 200018}
+ # This regex could be made more efficient. If I was the one working on this encoding, I would
+ # have done a few other things differently too, e.g. I think you can allocate tokens more
+ # efficiently across languages.
+ pat_str = "|".join(
```
This function is important because it defines how tiktoken Tutorial: OpenAI Token Encoding & Optimization implements the patterns covered in this chapter.
-### `tiktoken/registry.py`
+### `tiktoken_ext/openai_public.py`
-The `list_encoding_names` function in [`tiktoken/registry.py`](https://github.com/openai/tiktoken/blob/HEAD/tiktoken/registry.py) handles a key part of this chapter's functionality:
+The `o200k_base` function in [`tiktoken_ext/openai_public.py`](https://github.com/openai/tiktoken/blob/HEAD/tiktoken_ext/openai_public.py) handles a key part of this chapter's functionality:
```py
-def list_encoding_names() -> list[str]:
- with _lock:
- if ENCODING_CONSTRUCTORS is None:
- _find_constructors()
- assert ENCODING_CONSTRUCTORS is not None
- return list(ENCODING_CONSTRUCTORS)
+def o200k_base():
+ mergeable_ranks = load_tiktoken_bpe(
+ "https://openaipublic.blob.core.windows.net/encodings/o200k_base.tiktoken",
+ expected_hash="446a9538cb6c348e3516120d7c08b09f57c36495e2acfffe59a5bf8b0cfb1a2d",
+ )
+ special_tokens = {ENDOFTEXT: 199999, ENDOFPROMPT: 200018}
+ # This regex could be made more efficient. If I was the one working on this encoding, I would
+ # have done a few other things differently too, e.g. I think you can allocate tokens more
+ # efficiently across languages.
+ pat_str = "|".join(
+ [
+ r"""[^\r\n\p{L}\p{N}]?[\p{Lu}\p{Lt}\p{Lm}\p{Lo}\p{M}]*[\p{Ll}\p{Lm}\p{Lo}\p{M}]+(?i:'s|'t|'re|'ve|'m|'ll|'d)?""",
+ r"""[^\r\n\p{L}\p{N}]?[\p{Lu}\p{Lt}\p{Lm}\p{Lo}\p{M}]+[\p{Ll}\p{Lm}\p{Lo}\p{M}]*(?i:'s|'t|'re|'ve|'m|'ll|'d)?""",
+ r"""\p{N}{1,3}""",
+ r""" ?[^\s\p{L}\p{N}]+[\r\n/]*""",
+ r"""\s*[\r\n]+""",
+ r"""\s+(?!\S)""",
+ r"""\s+""",
+ ]
+ )
+ return {
+ "name": "o200k_base",
+ "pat_str": pat_str,
+ "mergeable_ranks": mergeable_ranks,
+ "special_tokens": special_tokens,
+ }
+
+def o200k_harmony():
+ base_enc = o200k_base()
```
This function is important because it defines how tiktoken Tutorial: OpenAI Token Encoding & Optimization implements the patterns covered in this chapter.
### `tiktoken_ext/openai_public.py`
-The `gpt2` function in [`tiktoken_ext/openai_public.py`](https://github.com/openai/tiktoken/blob/HEAD/tiktoken_ext/openai_public.py) handles a key part of this chapter's functionality:
+The `o200k_harmony` function in [`tiktoken_ext/openai_public.py`](https://github.com/openai/tiktoken/blob/HEAD/tiktoken_ext/openai_public.py) handles a key part of this chapter's functionality:
```py
-def gpt2():
- mergeable_ranks = data_gym_to_mergeable_bpe_ranks(
- vocab_bpe_file="https://openaipublic.blob.core.windows.net/gpt-2/encodings/main/vocab.bpe",
- encoder_json_file="https://openaipublic.blob.core.windows.net/gpt-2/encodings/main/encoder.json",
- vocab_bpe_hash="1ce1664773c50f3e0cc8842619a93edc4624525b728b188a9e0be33b7726adc5",
- encoder_json_hash="196139668be63f3b5d6574427317ae82f612a97c5d1cdaf36ed2256dbf636783",
- )
+def o200k_harmony():
+ base_enc = o200k_base()
+ name = "o200k_harmony"
+ pat_str = base_enc["pat_str"]
+ mergeable_ranks = base_enc["mergeable_ranks"]
+ special_tokens = {
+ **base_enc["special_tokens"],
+ "<|startoftext|>": 199998,
+ "<|endoftext|>": 199999,
+ "<|reserved_200000|>": 200000,
+ "<|reserved_200001|>": 200001,
+ "<|return|>": 200002,
+ "<|constrain|>": 200003,
+ "<|reserved_200004|>": 200004,
+ "<|channel|>": 200005,
+ "<|start|>": 200006,
+ "<|end|>": 200007,
+ "<|message|>": 200008,
+ "<|reserved_200009|>": 200009,
+ "<|reserved_200010|>": 200010,
+ "<|reserved_200011|>": 200011,
+ "<|call|>": 200012,
+ } | {f"<|reserved_{i}|>": i for i in range(200013, 201088)}
return {
- "name": "gpt2",
- "explicit_n_vocab": 50257,
- "pat_str": r50k_pat_str,
+ "name": name,
+ "pat_str": pat_str,
"mergeable_ranks": mergeable_ranks,
- "special_tokens": {ENDOFTEXT: 50256},
+ "special_tokens": special_tokens,
}
-
-def r50k_base():
- mergeable_ranks = load_tiktoken_bpe(
- "https://openaipublic.blob.core.windows.net/encodings/r50k_base.tiktoken",
- expected_hash="306cd27f03c1a714eca7108e03d66b7dc042abe8c258b44c199a7ed9838dd930",
- )
- return {
- "name": "r50k_base",
- "explicit_n_vocab": 50257,
- "pat_str": r50k_pat_str,
- "mergeable_ranks": mergeable_ranks,
- "special_tokens": {ENDOFTEXT: 50256},
- }
-
-
```
This function is important because it defines how tiktoken Tutorial: OpenAI Token Encoding & Optimization implements the patterns covered in this chapter.
-### `tiktoken_ext/openai_public.py`
+### `tiktoken/registry.py`
-The `r50k_base` function in [`tiktoken_ext/openai_public.py`](https://github.com/openai/tiktoken/blob/HEAD/tiktoken_ext/openai_public.py) handles a key part of this chapter's functionality:
+The `get_encoding` function in [`tiktoken/registry.py`](https://github.com/openai/tiktoken/blob/HEAD/tiktoken/registry.py) handles a key part of this chapter's functionality:
```py
-def r50k_base():
- mergeable_ranks = load_tiktoken_bpe(
- "https://openaipublic.blob.core.windows.net/encodings/r50k_base.tiktoken",
- expected_hash="306cd27f03c1a714eca7108e03d66b7dc042abe8c258b44c199a7ed9838dd930",
- )
- return {
- "name": "r50k_base",
- "explicit_n_vocab": 50257,
- "pat_str": r50k_pat_str,
- "mergeable_ranks": mergeable_ranks,
- "special_tokens": {ENDOFTEXT: 50256},
- }
+def get_encoding(encoding_name: str) -> Encoding:
+ if not isinstance(encoding_name, str):
+ raise ValueError(f"Expected a string in get_encoding, got {type(encoding_name)}")
+ if encoding_name in ENCODINGS:
+ return ENCODINGS[encoding_name]
-def p50k_base():
- mergeable_ranks = load_tiktoken_bpe(
- "https://openaipublic.blob.core.windows.net/encodings/p50k_base.tiktoken",
- expected_hash="94b5ca7dff4d00767bc256fdd1b27e5b17361d7b8a5f968547f9f23eb70d2069",
- )
- return {
- "name": "p50k_base",
- "explicit_n_vocab": 50281,
- "pat_str": r50k_pat_str,
- "mergeable_ranks": mergeable_ranks,
- "special_tokens": {ENDOFTEXT: 50256},
- }
+ with _lock:
+ if encoding_name in ENCODINGS:
+ return ENCODINGS[encoding_name]
+ if ENCODING_CONSTRUCTORS is None:
+ _find_constructors()
+ assert ENCODING_CONSTRUCTORS is not None
-def p50k_edit():
- mergeable_ranks = load_tiktoken_bpe(
+ if encoding_name not in ENCODING_CONSTRUCTORS:
+ raise ValueError(
+ f"Unknown encoding {encoding_name}.\n"
+ f"Plugins found: {_available_plugin_modules()}\n"
+ f"tiktoken version: {tiktoken.__version__} (are you on latest?)"
+ )
+
+ constructor = ENCODING_CONSTRUCTORS[encoding_name]
+ enc = Encoding(**constructor())
+ ENCODINGS[encoding_name] = enc
+ return enc
+
+
+def list_encoding_names() -> list[str]:
+ with _lock:
```
This function is important because it defines how tiktoken Tutorial: OpenAI Token Encoding & Optimization implements the patterns covered in this chapter.
@@ -249,11 +270,11 @@ This function is important because it defines how tiktoken Tutorial: OpenAI Toke
```mermaid
flowchart TD
- A[get_encoding]
- B[list_encoding_names]
- C[gpt2]
- D[r50k_base]
- E[p50k_base]
+ A[cl100k_base]
+ B[o200k_base]
+ C[o200k_harmony]
+ D[get_encoding]
+ E[list_encoding_names]
A --> B
B --> C
C --> D
diff --git a/tutorials/tiktoken-tutorial/08-cost-governance.md b/tutorials/tiktoken-tutorial/08-cost-governance.md
index 116d85d9..1f0a28d4 100644
--- a/tutorials/tiktoken-tutorial/08-cost-governance.md
+++ b/tutorials/tiktoken-tutorial/08-cost-governance.md
@@ -100,169 +100,145 @@ Suggested trace strategy:
- [Main Catalog](../../README.md#-tutorial-catalog)
- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `tiktoken_ext/openai_public.py`
+### `scripts/benchmark.py`
-The `p50k_edit` function in [`tiktoken_ext/openai_public.py`](https://github.com/openai/tiktoken/blob/HEAD/tiktoken_ext/openai_public.py) handles a key part of this chapter's functionality:
+The `benchmark_batch` function in [`scripts/benchmark.py`](https://github.com/openai/tiktoken/blob/HEAD/scripts/benchmark.py) handles a key part of this chapter's functionality:
```py
-def p50k_edit():
- mergeable_ranks = load_tiktoken_bpe(
- "https://openaipublic.blob.core.windows.net/encodings/p50k_base.tiktoken",
- expected_hash="94b5ca7dff4d00767bc256fdd1b27e5b17361d7b8a5f968547f9f23eb70d2069",
- )
- special_tokens = {ENDOFTEXT: 50256, FIM_PREFIX: 50281, FIM_MIDDLE: 50282, FIM_SUFFIX: 50283}
- return {
- "name": "p50k_edit",
- "pat_str": r50k_pat_str,
- "mergeable_ranks": mergeable_ranks,
- "special_tokens": special_tokens,
- }
-
-
-def cl100k_base():
- mergeable_ranks = load_tiktoken_bpe(
- "https://openaipublic.blob.core.windows.net/encodings/cl100k_base.tiktoken",
- expected_hash="223921b76ee99bde995b7ff738513eef100fb51d18c93597a113bcffe865b2a7",
- )
- special_tokens = {
- ENDOFTEXT: 100257,
- FIM_PREFIX: 100258,
- FIM_MIDDLE: 100259,
- FIM_SUFFIX: 100260,
- ENDOFPROMPT: 100276,
- }
- return {
- "name": "cl100k_base",
- "pat_str": r"""'(?i:[sdmt]|ll|ve|re)|[^\r\n\p{L}\p{N}]?+\p{L}++|\p{N}{1,3}+| ?[^\s\p{L}\p{N}]++[\r\n]*+|\s++$|\s*[\r\n]|\s+(?!\S)|\s""",
- "mergeable_ranks": mergeable_ranks,
+def benchmark_batch(documents: list[str]) -> None:
+ num_threads = int(os.environ["RAYON_NUM_THREADS"])
+ num_bytes = sum(map(len, map(str.encode, documents)))
+ print(f"num_threads: {num_threads}, num_bytes: {num_bytes}")
+
+ enc = tiktoken.get_encoding("gpt2")
+ enc.encode("warmup")
+
+ start = time.perf_counter_ns()
+ enc.encode_ordinary_batch(documents, num_threads=num_threads)
+ end = time.perf_counter_ns()
+ print(f"tiktoken \t{num_bytes / (end - start) * 1e9} bytes / s")
+
+ import transformers
+
+ hf_enc = cast(Any, transformers).GPT2TokenizerFast.from_pretrained("gpt2")
+ hf_enc.model_max_length = 1e30 # silence!
+ hf_enc.encode("warmup")
+
+ start = time.perf_counter_ns()
+ hf_enc(documents)
+ end = time.perf_counter_ns()
+ print(f"huggingface \t{num_bytes / (end - start) * 1e9} bytes / s")
+
+
+
```
This function is important because it defines how tiktoken Tutorial: OpenAI Token Encoding & Optimization implements the patterns covered in this chapter.
-### `tiktoken_ext/openai_public.py`
+### `scripts/redact.py`
-The `cl100k_base` function in [`tiktoken_ext/openai_public.py`](https://github.com/openai/tiktoken/blob/HEAD/tiktoken_ext/openai_public.py) handles a key part of this chapter's functionality:
+The `redact_file` function in [`scripts/redact.py`](https://github.com/openai/tiktoken/blob/HEAD/scripts/redact.py) handles a key part of this chapter's functionality:
```py
-def cl100k_base():
- mergeable_ranks = load_tiktoken_bpe(
- "https://openaipublic.blob.core.windows.net/encodings/cl100k_base.tiktoken",
- expected_hash="223921b76ee99bde995b7ff738513eef100fb51d18c93597a113bcffe865b2a7",
- )
- special_tokens = {
- ENDOFTEXT: 100257,
- FIM_PREFIX: 100258,
- FIM_MIDDLE: 100259,
- FIM_SUFFIX: 100260,
- ENDOFPROMPT: 100276,
- }
- return {
- "name": "cl100k_base",
- "pat_str": r"""'(?i:[sdmt]|ll|ve|re)|[^\r\n\p{L}\p{N}]?+\p{L}++|\p{N}{1,3}+| ?[^\s\p{L}\p{N}]++[\r\n]*+|\s++$|\s*[\r\n]|\s+(?!\S)|\s""",
- "mergeable_ranks": mergeable_ranks,
- "special_tokens": special_tokens,
- }
-
-
-def o200k_base():
- mergeable_ranks = load_tiktoken_bpe(
- "https://openaipublic.blob.core.windows.net/encodings/o200k_base.tiktoken",
- expected_hash="446a9538cb6c348e3516120d7c08b09f57c36495e2acfffe59a5bf8b0cfb1a2d",
+def redact_file(path: Path, dry_run: bool) -> None:
+ if not path.exists() or path.is_dir():
+ return
+
+ text = path.read_text()
+ if not text:
+ return
+
+ first_line = text.splitlines()[0]
+ if "redact" in first_line:
+ if not dry_run:
+ path.unlink()
+ print(f"Deleted {path}")
+ return
+
+ pattern = "|".join(
+ r" *" + re.escape(x)
+ for x in [
+ "# ===== redact-beg =====\n",
+ "# ===== redact-end =====\n",
+ "<!--- redact-beg -->\n",
+ "<!--- redact-end -->\n",
+ ]
)
- special_tokens = {ENDOFTEXT: 199999, ENDOFPROMPT: 200018}
- # This regex could be made more efficient. If I was the one working on this encoding, I would
- # have done a few other things differently too, e.g. I think you can allocate tokens more
- # efficiently across languages.
- pat_str = "|".join(
+
+ if re.search(pattern, text):
+ redacted_text = "".join(re.split(pattern, text)[::2])
+ if not dry_run:
+ path.write_text(redacted_text)
+ print(f"Redacted {path}")
```
This function is important because it defines how tiktoken Tutorial: OpenAI Token Encoding & Optimization implements the patterns covered in this chapter.
-### `tiktoken_ext/openai_public.py`
+### `scripts/redact.py`
-The `o200k_base` function in [`tiktoken_ext/openai_public.py`](https://github.com/openai/tiktoken/blob/HEAD/tiktoken_ext/openai_public.py) handles a key part of this chapter's functionality:
+The `redact` function in [`scripts/redact.py`](https://github.com/openai/tiktoken/blob/HEAD/scripts/redact.py) handles a key part of this chapter's functionality:
```py
-def o200k_base():
- mergeable_ranks = load_tiktoken_bpe(
- "https://openaipublic.blob.core.windows.net/encodings/o200k_base.tiktoken",
- expected_hash="446a9538cb6c348e3516120d7c08b09f57c36495e2acfffe59a5bf8b0cfb1a2d",
- )
- special_tokens = {ENDOFTEXT: 199999, ENDOFPROMPT: 200018}
- # This regex could be made more efficient. If I was the one working on this encoding, I would
- # have done a few other things differently too, e.g. I think you can allocate tokens more
- # efficiently across languages.
- pat_str = "|".join(
- [
- r"""[^\r\n\p{L}\p{N}]?[\p{Lu}\p{Lt}\p{Lm}\p{Lo}\p{M}]*[\p{Ll}\p{Lm}\p{Lo}\p{M}]+(?i:'s|'t|'re|'ve|'m|'ll|'d)?""",
- r"""[^\r\n\p{L}\p{N}]?[\p{Lu}\p{Lt}\p{Lm}\p{Lo}\p{M}]+[\p{Ll}\p{Lm}\p{Lo}\p{M}]*(?i:'s|'t|'re|'ve|'m|'ll|'d)?""",
- r"""\p{N}{1,3}""",
- r""" ?[^\s\p{L}\p{N}]+[\r\n/]*""",
- r"""\s*[\r\n]+""",
- r"""\s+(?!\S)""",
- r"""\s+""",
+def redact_file(path: Path, dry_run: bool) -> None:
+ if not path.exists() or path.is_dir():
+ return
+
+ text = path.read_text()
+ if not text:
+ return
+
+ first_line = text.splitlines()[0]
+ if "redact" in first_line:
+ if not dry_run:
+ path.unlink()
+ print(f"Deleted {path}")
+ return
+
+ pattern = "|".join(
+ r" *" + re.escape(x)
+ for x in [
+ "# ===== redact-beg =====\n",
+ "# ===== redact-end =====\n",
+ "<!--- redact-beg -->\n",
+ "<!--- redact-end -->\n",
]
)
- return {
- "name": "o200k_base",
- "pat_str": pat_str,
- "mergeable_ranks": mergeable_ranks,
- "special_tokens": special_tokens,
- }
-
-def o200k_harmony():
- base_enc = o200k_base()
+ if re.search(pattern, text):
+ redacted_text = "".join(re.split(pattern, text)[::2])
+ if not dry_run:
+ path.write_text(redacted_text)
+ print(f"Redacted {path}")
```
This function is important because it defines how tiktoken Tutorial: OpenAI Token Encoding & Optimization implements the patterns covered in this chapter.
-### `tiktoken_ext/openai_public.py`
+### `scripts/redact.py`
-The `o200k_harmony` function in [`tiktoken_ext/openai_public.py`](https://github.com/openai/tiktoken/blob/HEAD/tiktoken_ext/openai_public.py) handles a key part of this chapter's functionality:
+The `main` function in [`scripts/redact.py`](https://github.com/openai/tiktoken/blob/HEAD/scripts/redact.py) handles a key part of this chapter's functionality:
```py
-def o200k_harmony():
- base_enc = o200k_base()
- name = "o200k_harmony"
- pat_str = base_enc["pat_str"]
- mergeable_ranks = base_enc["mergeable_ranks"]
- special_tokens = {
- **base_enc["special_tokens"],
- "<|startoftext|>": 199998,
- "<|endoftext|>": 199999,
- "<|reserved_200000|>": 200000,
- "<|reserved_200001|>": 200001,
- "<|return|>": 200002,
- "<|constrain|>": 200003,
- "<|reserved_200004|>": 200004,
- "<|channel|>": 200005,
- "<|start|>": 200006,
- "<|end|>": 200007,
- "<|message|>": 200008,
- "<|reserved_200009|>": 200009,
- "<|reserved_200010|>": 200010,
- "<|reserved_200011|>": 200011,
- "<|call|>": 200012,
- } | {f"<|reserved_{i}|>": i for i in range(200013, 201088)}
- return {
- "name": name,
- "pat_str": pat_str,
- "mergeable_ranks": mergeable_ranks,
- "special_tokens": special_tokens,
- }
+def main() -> None:
+ parser = argparse.ArgumentParser()
+ parser.add_argument("--dry-run", type=lambda x: not x or x[0].lower() != "f", default=True)
+ args = parser.parse_args()
+ redact(args.dry_run)
+ if args.dry_run:
+ print("Dry run, use --dry-run=false to actually redact files")
+
+
+if __name__ == "__main__":
+ main()
```
@@ -273,11 +249,11 @@ This function is important because it defines how tiktoken Tutorial: OpenAI Toke
```mermaid
flowchart TD
- A[p50k_edit]
- B[cl100k_base]
- C[o200k_base]
- D[o200k_harmony]
- E[benchmark_batch]
+ A[benchmark_batch]
+ B[redact_file]
+ C[redact]
+ D[main]
+ E[download_artifacts]
A --> B
B --> C
C --> D
diff --git a/tutorials/tutorial-manifest.json b/tutorials/tutorial-manifest.json
index 249e41c9..3c4306c7 100644
--- a/tutorials/tutorial-manifest.json
+++ b/tutorials/tutorial-manifest.json
@@ -3,9 +3,9 @@
"docs_only": 0,
"index_only": 0,
"mixed": 0,
- "root_only": 201
+ "root_only": 203
},
- "tutorial_count": 201,
+ "tutorial_count": 203,
"tutorials": [
{
"chapter_numbers": [
@@ -331,6 +331,25 @@
"top_level_chapter_count": 8,
"total_numbered_chapter_count": 8
},
+ {
+ "chapter_numbers": [
+ "01",
+ "02",
+ "03",
+ "04",
+ "05",
+ "06",
+ "07",
+ "08"
+ ],
+ "docs_chapter_count": 0,
+ "has_index": true,
+ "name": "autoresearch-tutorial",
+ "path": "tutorials/autoresearch-tutorial",
+ "structure": "root_only",
+ "top_level_chapter_count": 8,
+ "total_numbered_chapter_count": 8
+ },
{
"chapter_numbers": [
"01",
@@ -1547,6 +1566,25 @@
"top_level_chapter_count": 8,
"total_numbered_chapter_count": 8
},
+ {
+ "chapter_numbers": [
+ "01",
+ "02",
+ "03",
+ "04",
+ "05",
+ "06",
+ "07",
+ "08"
+ ],
+ "docs_chapter_count": 0,
+ "has_index": true,
+ "name": "hermes-agent-tutorial",
+ "path": "tutorials/hermes-agent-tutorial",
+ "structure": "root_only",
+ "top_level_chapter_count": 8,
+ "total_numbered_chapter_count": 8
+ },
{
"chapter_numbers": [
"01",
diff --git a/tutorials/vercel-ai-tutorial/01-getting-started.md b/tutorials/vercel-ai-tutorial/01-getting-started.md
index 0cc78c75..8431b12f 100644
--- a/tutorials/vercel-ai-tutorial/01-getting-started.md
+++ b/tutorials/vercel-ai-tutorial/01-getting-started.md
@@ -5,6 +5,7 @@ parent: "Vercel AI Tutorial"
nav_order: 1
---
+
# Chapter 1: Getting Started with Vercel AI
Welcome to Vercel AI! If you've ever wanted to build AI-powered applications with TypeScript and React, you're in the right place. Vercel AI is the comprehensive toolkit created by the makers of Next.js for building modern AI applications with type safety, streaming responses, and seamless integration.
@@ -340,292 +341,53 @@ Now that you understand Vercel AI basics, let's explore text generation in depth
## Depth Expansion Playbook
-<!-- depth-expansion-v2 -->
-
-This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
-
-### Strategic Context
-
-- tutorial: **Vercel AI SDK Tutorial: Production TypeScript AI Apps and Agents**
-- tutorial slug: **vercel-ai-tutorial**
-- chapter focus: **Chapter 1: Getting Started with Vercel AI**
-- system context: **Vercel Ai Tutorial**
-- objective: move from surface-level usage to repeatable engineering operation
-
-### Architecture Decomposition
-
-1. Define the runtime boundary for `Chapter 1: Getting Started with Vercel AI`.
-2. Separate control-plane decisions from data-plane execution.
-3. Capture input contracts, transformation points, and output contracts.
-4. Trace state transitions across request lifecycle stages.
-5. Identify extension hooks and policy interception points.
-6. Map ownership boundaries for team and automation workflows.
-7. Specify rollback and recovery paths for unsafe changes.
-8. Track observability signals for correctness, latency, and cost.
-
-### Operator Decision Matrix
-
-| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
-|:--------------|:--------------|:------------------|:---------|
-| Runtime mode | managed defaults | explicit policy config | speed vs control |
-| State handling | local ephemeral | durable persisted state | simplicity vs auditability |
-| Tool integration | direct API use | mediated adapter layer | velocity vs governance |
-| Rollout method | manual change | staged + canary rollout | effort vs safety |
-| Incident response | best effort logs | runbooks + SLO alerts | cost vs reliability |
-
-### Failure Modes and Countermeasures
-
-| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
-|:-------------|:-------------|:-------------------|:---------------|
-| stale context | inconsistent outputs | missing refresh window | enforce context TTL and refresh hooks |
-| policy drift | unexpected execution | ad hoc overrides | centralize policy profiles |
-| auth mismatch | 401/403 bursts | credential sprawl | rotation schedule + scope minimization |
-| schema breakage | parser/validation errors | unmanaged upstream changes | contract tests per release |
-| retry storms | queue congestion | no backoff controls | jittered backoff + circuit breakers |
-| silent regressions | quality drop without alerts | weak baseline metrics | eval harness with thresholds |
-
-### Implementation Runbook
-
-1. Establish a reproducible baseline environment.
-2. Capture chapter-specific success criteria before changes.
-3. Implement minimal viable path with explicit interfaces.
-4. Add observability before expanding feature scope.
-5. Run deterministic tests for happy-path behavior.
-6. Inject failure scenarios for negative-path validation.
-7. Compare output quality against baseline snapshots.
-8. Promote through staged environments with rollback gates.
-9. Record operational lessons in release notes.
-
-### Quality Gate Checklist
-
-- [ ] chapter-level assumptions are explicit and testable
-- [ ] API/tool boundaries are documented with input/output examples
-- [ ] failure handling includes retry, timeout, and fallback policy
-- [ ] security controls include auth scopes and secret rotation plans
-- [ ] observability includes logs, metrics, traces, and alert thresholds
-- [ ] deployment guidance includes canary and rollback paths
-- [ ] docs include links to upstream sources and related tracks
-- [ ] post-release verification confirms expected behavior under load
-
-### Source Alignment
-
-- [AI SDK Repository](https://github.com/vercel/ai)
-- [AI SDK Releases](https://github.com/vercel/ai/releases)
-- [AI SDK Docs](https://ai-sdk.dev)
-
-### Cross-Tutorial Connection Map
-
-- [OpenAI Python SDK Tutorial](../openai-python-sdk-tutorial/)
-- [OpenAI Realtime Agents Tutorial](../openai-realtime-agents-tutorial/)
-- [Dyad Tutorial](../dyad-tutorial/)
-- [bolt.diy Tutorial](../bolt-diy-tutorial/)
-- [Chapter 1: Getting Started](01-getting-started.md)
-
-### Advanced Practice Exercises
-
-1. Build a minimal end-to-end implementation for `Chapter 1: Getting Started with Vercel AI`.
-2. Add instrumentation and measure baseline latency and error rate.
-3. Introduce one controlled failure and confirm graceful recovery.
-4. Add policy constraints and verify they are enforced consistently.
-5. Run a staged rollout and document rollback decision criteria.
-
-### Review Questions
-
-1. Which execution boundary matters most for this chapter and why?
-2. What signal detects regressions earliest in your environment?
-3. What tradeoff did you make between delivery speed and governance?
-4. How would you recover from the highest-impact failure mode?
-5. What must be automated before scaling to team-wide adoption?
-
-### Scenario Playbook 1: Chapter 1: Getting Started with Vercel AI
-
-- tutorial context: **Vercel AI SDK Tutorial: Production TypeScript AI Apps and Agents**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 2: Chapter 1: Getting Started with Vercel AI
-
-- tutorial context: **Vercel AI SDK Tutorial: Production TypeScript AI Apps and Agents**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 3: Chapter 1: Getting Started with Vercel AI
-
-- tutorial context: **Vercel AI SDK Tutorial: Production TypeScript AI Apps and Agents**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 4: Chapter 1: Getting Started with Vercel AI
-
-- tutorial context: **Vercel AI SDK Tutorial: Production TypeScript AI Apps and Agents**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 5: Chapter 1: Getting Started with Vercel AI
-
-- tutorial context: **Vercel AI SDK Tutorial: Production TypeScript AI Apps and Agents**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 6: Chapter 1: Getting Started with Vercel AI
-
-- tutorial context: **Vercel AI SDK Tutorial: Production TypeScript AI Apps and Agents**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 7: Chapter 1: Getting Started with Vercel AI
-
-- tutorial context: **Vercel AI SDK Tutorial: Production TypeScript AI Apps and Agents**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 8: Chapter 1: Getting Started with Vercel AI
-
-- tutorial context: **Vercel AI SDK Tutorial: Production TypeScript AI Apps and Agents**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 9: Chapter 1: Getting Started with Vercel AI
-
-- tutorial context: **Vercel AI SDK Tutorial: Production TypeScript AI Apps and Agents**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 10: Chapter 1: Getting Started with Vercel AI
-
-- tutorial context: **Vercel AI SDK Tutorial: Production TypeScript AI Apps and Agents**
-- trigger condition: environment parity drifts between staging and production
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: restore environment parity via immutable config promotion
-- verification target: retry volume stays bounded without feedback loops
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 11: Chapter 1: Getting Started with Vercel AI
-
-- tutorial context: **Vercel AI SDK Tutorial: Production TypeScript AI Apps and Agents**
-- trigger condition: access policy changes reduce successful execution rates
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: re-scope credentials and rotate leaked or stale keys
-- verification target: data integrity checks pass across write/read cycles
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 12: Chapter 1: Getting Started with Vercel AI
-
-- tutorial context: **Vercel AI SDK Tutorial: Production TypeScript AI Apps and Agents**
-- trigger condition: background jobs accumulate and exceed processing windows
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: activate degradation mode to preserve core user paths
-- verification target: audit logs capture all control-plane mutations
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-## What Problem Does This Solve?
-
-Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for `openai`, `className`, `error` so behavior stays predictable as complexity grows.
-
-In practical terms, this chapter helps you avoid three common failures:
-
-- coupling core logic too tightly to one implementation path
-- missing the handoff boundaries between setup, execution, and validation
-- shipping changes without clear rollback or observability strategy
-
-After working through this chapter, you should be able to reason about `Chapter 1: Getting Started with Vercel AI` as an operating subsystem inside **Vercel AI SDK Tutorial: Production TypeScript AI Apps and Agents**, with explicit contracts for inputs, state transitions, and outputs.
-
-Use the implementation notes around `message`, `text`, `messages` as your checklist when adapting these patterns to your own repository.
-
-## How it Works Under the Hood
-
-Under the hood, `Chapter 1: Getting Started with Vercel AI` usually follows a repeatable control path:
-
-1. **Context bootstrap**: initialize runtime config and prerequisites for `openai`.
-2. **Input normalization**: shape incoming data so `className` receives stable contracts.
-3. **Core execution**: run the main logic branch and propagate intermediate state through `error`.
-4. **Policy and safety checks**: enforce limits, auth scopes, and failure boundaries.
-5. **Output composition**: return canonical result payloads for downstream consumers.
-6. **Operational telemetry**: emit logs/metrics needed for debugging and performance tuning.
-
-When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
-
-## Source Walkthrough
-
-Use the following upstream sources to verify implementation details while reading this chapter:
-
-- [AI SDK Repository](https://github.com/vercel/ai)
- Why it matters: authoritative reference on `AI SDK Repository` (github.com).
-- [AI SDK Releases](https://github.com/vercel/ai/releases)
- Why it matters: authoritative reference on `AI SDK Releases` (github.com).
-- [AI SDK Docs](https://ai-sdk.dev)
- Why it matters: authoritative reference on `AI SDK Docs` (ai-sdk.dev).
-
-Suggested trace strategy:
-- search upstream code for `openai` and `className` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
-
-## Chapter Connections
-
-- [Tutorial Index](README.md)
-- [Next Chapter: Chapter 2: Text Generation](02-text-generation.md)
-- [Main Catalog](../../README.md#-tutorial-catalog)
-- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
+## Source Code Walkthrough
+
+### `packages/ai/package.json`
+
+The `for` interface in [`packages/ai/package.json`](https://github.com/vercel/ai/blob/HEAD/packages/ai/package.json) handles a key part of this chapter's functionality:
+
+```json
+ "name": "ai",
+ "version": "7.0.0-beta.64",
+ "description": "AI SDK by Vercel - build apps like ChatGPT, Claude, Gemini, and more with a single interface for any model using the Vercel AI Gateway or go direct to OpenAI, Anthropic, Google, or any other model provider.",
+ "license": "Apache-2.0",
+ "sideEffects": false,
+ "main": "./dist/index.js",
+ "module": "./dist/index.mjs",
+ "types": "./dist/index.d.ts",
+ "source": "./src/index.ts",
+ "files": [
+ "dist/**/*",
+ "docs/**/*",
+ "src",
+ "!src/**/*.test.ts",
+ "!src/**/*.test-d.ts",
+ "!src/**/__snapshots__",
+ "CHANGELOG.md",
+ "internal.d.ts",
+ "README.md",
+ "test.d.ts"
+ ],
+ "directories": {
+ "doc": "./docs"
+ },
+ "scripts": {
+ "build": "pnpm clean && tsup --tsconfig tsconfig.build.json",
+ "build:watch": "pnpm clean && tsup --watch --tsconfig tsconfig.build.json",
+ "clean": "del-cli dist docs *.tsbuildinfo",
+ "prepack": "cp -r ../../content/docs ./docs",
+ "postpack": "del-cli docs",
+ "type-check": "tsc --build",
+ "test": "pnpm test:node && pnpm test:edge",
+```
+
+This interface is important because it defines how Vercel AI SDK Tutorial: Production TypeScript AI Apps and Agents implements the patterns covered in this chapter.
+
+
+## How These Components Connect
+
+```mermaid
+flowchart TD
+ A[for]
+```
diff --git a/tutorials/vercel-ai-tutorial/02-text-generation.md b/tutorials/vercel-ai-tutorial/02-text-generation.md
index ff262cbe..3930b01d 100644
--- a/tutorials/vercel-ai-tutorial/02-text-generation.md
+++ b/tutorials/vercel-ai-tutorial/02-text-generation.md
@@ -5,6 +5,7 @@ parent: "Vercel AI Tutorial"
nav_order: 2
---
+
# Chapter 2: Text Generation
Welcome to **Chapter 2: Text Generation**. In this part of **Vercel AI SDK Tutorial: Production TypeScript AI Apps and Agents**, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
@@ -457,185 +458,24 @@ Ready to take your AI applications to the next level? In [Chapter 3: Streaming R
## Depth Expansion Playbook
-<!-- depth-expansion-v2 -->
-
-This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
-
-### Strategic Context
-
-- tutorial: **Vercel AI SDK Tutorial: Production TypeScript AI Apps and Agents**
-- tutorial slug: **vercel-ai-tutorial**
-- chapter focus: **Chapter 2: Text Generation**
-- system context: **Vercel Ai Tutorial**
-- objective: move from surface-level usage to repeatable engineering operation
-
-### Architecture Decomposition
-
-1. Define the runtime boundary for `Chapter 2: Text Generation`.
-2. Separate control-plane decisions from data-plane execution.
-3. Capture input contracts, transformation points, and output contracts.
-4. Trace state transitions across request lifecycle stages.
-5. Identify extension hooks and policy interception points.
-6. Map ownership boundaries for team and automation workflows.
-7. Specify rollback and recovery paths for unsafe changes.
-8. Track observability signals for correctness, latency, and cost.
-
-### Operator Decision Matrix
-
-| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
-|:--------------|:--------------|:------------------|:---------|
-| Runtime mode | managed defaults | explicit policy config | speed vs control |
-| State handling | local ephemeral | durable persisted state | simplicity vs auditability |
-| Tool integration | direct API use | mediated adapter layer | velocity vs governance |
-| Rollout method | manual change | staged + canary rollout | effort vs safety |
-| Incident response | best effort logs | runbooks + SLO alerts | cost vs reliability |
-
-### Failure Modes and Countermeasures
-
-| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
-|:-------------|:-------------|:-------------------|:---------------|
-| stale context | inconsistent outputs | missing refresh window | enforce context TTL and refresh hooks |
-| policy drift | unexpected execution | ad hoc overrides | centralize policy profiles |
-| auth mismatch | 401/403 bursts | credential sprawl | rotation schedule + scope minimization |
-| schema breakage | parser/validation errors | unmanaged upstream changes | contract tests per release |
-| retry storms | queue congestion | no backoff controls | jittered backoff + circuit breakers |
-| silent regressions | quality drop without alerts | weak baseline metrics | eval harness with thresholds |
-
-### Implementation Runbook
-
-1. Establish a reproducible baseline environment.
-2. Capture chapter-specific success criteria before changes.
-3. Implement minimal viable path with explicit interfaces.
-4. Add observability before expanding feature scope.
-5. Run deterministic tests for happy-path behavior.
-6. Inject failure scenarios for negative-path validation.
-7. Compare output quality against baseline snapshots.
-8. Promote through staged environments with rollback gates.
-9. Record operational lessons in release notes.
-
-### Quality Gate Checklist
-
-- [ ] chapter-level assumptions are explicit and testable
-- [ ] API/tool boundaries are documented with input/output examples
-- [ ] failure handling includes retry, timeout, and fallback policy
-- [ ] security controls include auth scopes and secret rotation plans
-- [ ] observability includes logs, metrics, traces, and alert thresholds
-- [ ] deployment guidance includes canary and rollback paths
-- [ ] docs include links to upstream sources and related tracks
-- [ ] post-release verification confirms expected behavior under load
-
-### Source Alignment
-
-- [AI SDK Repository](https://github.com/vercel/ai)
-- [AI SDK Releases](https://github.com/vercel/ai/releases)
-- [AI SDK Docs](https://ai-sdk.dev)
-
-### Cross-Tutorial Connection Map
-
-- [OpenAI Python SDK Tutorial](../openai-python-sdk-tutorial/)
-- [OpenAI Realtime Agents Tutorial](../openai-realtime-agents-tutorial/)
-- [Dyad Tutorial](../dyad-tutorial/)
-- [bolt.diy Tutorial](../bolt-diy-tutorial/)
-- [Chapter 1: Getting Started](01-getting-started.md)
-
-### Advanced Practice Exercises
-
-1. Build a minimal end-to-end implementation for `Chapter 2: Text Generation`.
-2. Add instrumentation and measure baseline latency and error rate.
-3. Introduce one controlled failure and confirm graceful recovery.
-4. Add policy constraints and verify they are enforced consistently.
-5. Run a staged rollout and document rollback decision criteria.
-
-### Review Questions
-
-1. Which execution boundary matters most for this chapter and why?
-2. What signal detects regressions earliest in your environment?
-3. What tradeoff did you make between delivery speed and governance?
-4. How would you recover from the highest-impact failure mode?
-5. What must be automated before scaling to team-wide adoption?
-
-### Scenario Playbook 1: Chapter 2: Text Generation
-
-- tutorial context: **Vercel AI SDK Tutorial: Production TypeScript AI Apps and Agents**
-- trigger condition: incoming request volume spikes after release
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: introduce adaptive concurrency limits and queue bounds
-- verification target: latency p95 and p99 stay within defined SLO windows
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 2: Chapter 2: Text Generation
-
-- tutorial context: **Vercel AI SDK Tutorial: Production TypeScript AI Apps and Agents**
-- trigger condition: tool dependency latency increases under concurrency
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: enable staged retries with jitter and circuit breaker fallback
-- verification target: error budget burn rate remains below escalation threshold
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-### Scenario Playbook 3: Chapter 2: Text Generation
-
-- tutorial context: **Vercel AI SDK Tutorial: Production TypeScript AI Apps and Agents**
-- trigger condition: schema updates introduce incompatible payloads
-- initial hypothesis: identify the smallest reproducible failure boundary
-- immediate action: protect user-facing stability before optimization work
-- engineering control: pin schema versions and add compatibility shims
-- verification target: throughput remains stable under target concurrency
-- rollback trigger: pre-defined quality gate fails for two consecutive checks
-- communication step: publish incident status with owner and ETA
-- learning capture: add postmortem and convert findings into automated tests
-
-## What Problem Does This Solve?
-
-Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for `text`, `prompt`, `temperature` so behavior stays predictable as complexity grows.
-
-In practical terms, this chapter helps you avoid three common failures:
-
-- coupling core logic too tightly to one implementation path
-- missing the handoff boundaries between setup, execution, and validation
-- shipping changes without clear rollback or observability strategy
-
-After working through this chapter, you should be able to reason about `Chapter 2: Text Generation` as an operating subsystem inside **Vercel AI SDK Tutorial: Production TypeScript AI Apps and Agents**, with explicit contracts for inputs, state transitions, and outputs.
-
-Use the implementation notes around `model`, `models`, `className` as your checklist when adapting these patterns to your own repository.
-
-## How it Works Under the Hood
-
-Under the hood, `Chapter 2: Text Generation` usually follows a repeatable control path:
+## Source Code Walkthrough
-1. **Context bootstrap**: initialize runtime config and prerequisites for `text`.
-2. **Input normalization**: shape incoming data so `prompt` receives stable contracts.
-3. **Core execution**: run the main logic branch and propagate intermediate state through `temperature`.
-4. **Policy and safety checks**: enforce limits, auth scopes, and failure boundaries.
-5. **Output composition**: return canonical result payloads for downstream consumers.
-6. **Operational telemetry**: emit logs/metrics needed for debugging and performance tuning.
+Use the following upstream sources to verify text generation implementation details while reading this chapter:
-When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
-
-## Source Walkthrough
-
-Use the following upstream sources to verify implementation details while reading this chapter:
-
-- [AI SDK Repository](https://github.com/vercel/ai)
- Why it matters: authoritative reference on `AI SDK Repository` (github.com).
-- [AI SDK Releases](https://github.com/vercel/ai/releases)
- Why it matters: authoritative reference on `AI SDK Releases` (github.com).
-- [AI SDK Docs](https://ai-sdk.dev)
- Why it matters: authoritative reference on `AI SDK Docs` (ai-sdk.dev).
+- [`packages/ai/src/generate-text/generate-text.ts`](https://github.com/vercel/ai/blob/HEAD/packages/ai/src/generate-text/generate-text.ts) — the `generateText` function implementation, the primary non-streaming text generation entry point that wraps model provider calls, tool execution, and result assembly.
+- [`packages/ai/src/generate-text/index.ts`](https://github.com/vercel/ai/blob/HEAD/packages/ai/src/generate-text/index.ts) — the package exports for the text generation surface, showing which types and functions are part of the public API.
Suggested trace strategy:
-- search upstream code for `text` and `prompt` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
-
-## Chapter Connections
-
-- [Tutorial Index](README.md)
-- [Previous Chapter: Chapter 1: Getting Started with Vercel AI](01-getting-started.md)
-- [Next Chapter: Chapter 3: Streaming Responses](03-streaming-responses.md)
-- [Main Catalog](../../README.md#-tutorial-catalog)
-- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
+- trace `generateText` to understand how the provider abstraction, prompt formatting, and tool loop are composed
+- review the `GenerateTextResult` type to understand all fields available after a generation call completes
+- check `packages/ai/src/core/` for the shared model call infrastructure used by both `generateText` and `streamText`
+
+## How These Components Connect
+
+```mermaid
+flowchart LR
+ A[generateText call] --> B[Provider abstraction layer]
+ B --> C[LLM API request]
+ C --> D[GenerateTextResult returned]
+ D --> E[text, usage, finishReason available]
+```
\ No newline at end of file
diff --git a/tutorials/vercel-ai-tutorial/03-streaming-responses.md b/tutorials/vercel-ai-tutorial/03-streaming-responses.md
index 7062c1c2..30c30563 100644
--- a/tutorials/vercel-ai-tutorial/03-streaming-responses.md
+++ b/tutorials/vercel-ai-tutorial/03-streaming-responses.md
@@ -5,6 +5,7 @@ parent: "Vercel AI Tutorial"
nav_order: 3
---
+
# Chapter 3: Streaming Responses
Welcome to the world of real-time AI! Streaming responses are what make modern AI applications feel alive and responsive. Instead of waiting for the complete response, users see text appear character by character, creating an engaging, interactive experience.
@@ -576,149 +577,24 @@ Ready for more advanced AI capabilities? In [Chapter 4: Function Calling](04-fun
## Depth Expansion Playbook
-<!-- depth-expansion-v2 -->
-
-This chapter is expanded to v1-style depth for production-grade learning and implementation quality.
-
-### Strategic Context
-
-- tutorial: **Vercel AI SDK Tutorial: Production TypeScript AI Apps and Agents**
-- tutorial slug: **vercel-ai-tutorial**
-- chapter focus: **Chapter 3: Streaming Responses**
-- system context: **Vercel Ai Tutorial**
-- objective: move from surface-level usage to repeatable engineering operation
-
-### Architecture Decomposition
-
-1. Define the runtime boundary for `Chapter 3: Streaming Responses`.
-2. Separate control-plane decisions from data-plane execution.
-3. Capture input contracts, transformation points, and output contracts.
-4. Trace state transitions across request lifecycle stages.
-5. Identify extension hooks and policy interception points.
-6. Map ownership boundaries for team and automation workflows.
-7. Specify rollback and recovery paths for unsafe changes.
-8. Track observability signals for correctness, latency, and cost.
-
-### Operator Decision Matrix
-
-| Decision Area | Low-Risk Path | High-Control Path | Tradeoff |
-|:--------------|:--------------|:------------------|:---------|
-| Runtime mode | managed defaults | explicit policy config | speed vs control |
-| State handling | local ephemeral | durable persisted state | simplicity vs auditability |
-| Tool integration | direct API use | mediated adapter layer | velocity vs governance |
-| Rollout method | manual change | staged + canary rollout | effort vs safety |
-| Incident response | best effort logs | runbooks + SLO alerts | cost vs reliability |
-
-### Failure Modes and Countermeasures
-
-| Failure Mode | Early Signal | Root Cause Pattern | Countermeasure |
-|:-------------|:-------------|:-------------------|:---------------|
-| stale context | inconsistent outputs | missing refresh window | enforce context TTL and refresh hooks |
-| policy drift | unexpected execution | ad hoc overrides | centralize policy profiles |
-| auth mismatch | 401/403 bursts | credential sprawl | rotation schedule + scope minimization |
-| schema breakage | parser/validation errors | unmanaged upstream changes | contract tests per release |
-| retry storms | queue congestion | no backoff controls | jittered backoff + circuit breakers |
-| silent regressions | quality drop without alerts | weak baseline metrics | eval harness with thresholds |
-
-### Implementation Runbook
-
-1. Establish a reproducible baseline environment.
-2. Capture chapter-specific success criteria before changes.
-3. Implement minimal viable path with explicit interfaces.
-4. Add observability before expanding feature scope.
-5. Run deterministic tests for happy-path behavior.
-6. Inject failure scenarios for negative-path validation.
-7. Compare output quality against baseline snapshots.
-8. Promote through staged environments with rollback gates.
-9. Record operational lessons in release notes.
-
-### Quality Gate Checklist
-
-- [ ] chapter-level assumptions are explicit and testable
-- [ ] API/tool boundaries are documented with input/output examples
-- [ ] failure handling includes retry, timeout, and fallback policy
-- [ ] security controls include auth scopes and secret rotation plans
-- [ ] observability includes logs, metrics, traces, and alert thresholds
-- [ ] deployment guidance includes canary and rollback paths
-- [ ] docs include links to upstream sources and related tracks
-- [ ] post-release verification confirms expected behavior under load
-
-### Source Alignment
-
-- [AI SDK Repository](https://github.com/vercel/ai)
-- [AI SDK Releases](https://github.com/vercel/ai/releases)
-- [AI SDK Docs](https://ai-sdk.dev)
-
-### Cross-Tutorial Connection Map
-
-- [OpenAI Python SDK Tutorial](../openai-python-sdk-tutorial/)
-- [OpenAI Realtime Agents Tutorial](../openai-realtime-agents-tutorial/)
-- [Dyad Tutorial](../dyad-tutorial/)
-- [bolt.diy Tutorial](../bolt-diy-tutorial/)
-- [Chapter 1: Getting Started](01-getting-started.md)
+## Source Code Walkthrough
-### Advanced Practice Exercises
+Use the following upstream sources to verify streaming response implementation details while reading this chapter:
-1. Build a minimal end-to-end implementation for `Chapter 3: Streaming Responses`.
-2. Add instrumentation and measure baseline latency and error rate.
-3. Introduce one controlled failure and confirm graceful recovery.
-4. Add policy constraints and verify they are enforced consistently.
-5. Run a staged rollout and document rollback decision criteria.
-
-### Review Questions
-
-1. Which execution boundary matters most for this chapter and why?
-2. What signal detects regressions earliest in your environment?
-3. What tradeoff did you make between delivery speed and governance?
-4. How would you recover from the highest-impact failure mode?
-5. What must be automated before scaling to team-wide adoption?
-
-## What Problem Does This Solve?
-
-Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for `className`, `messages`, `text` so behavior stays predictable as complexity grows.
-
-In practical terms, this chapter helps you avoid three common failures:
-
-- coupling core logic too tightly to one implementation path
-- missing the handoff boundaries between setup, execution, and validation
-- shipping changes without clear rollback or observability strategy
-
-After working through this chapter, you should be able to reason about `Chapter 3: Streaming Responses` as an operating subsystem inside **Vercel AI SDK Tutorial: Production TypeScript AI Apps and Agents**, with explicit contracts for inputs, state transitions, and outputs.
-
-Use the implementation notes around `stream`, `flex`, `gray` as your checklist when adapting these patterns to your own repository.
-
-## How it Works Under the Hood
-
-Under the hood, `Chapter 3: Streaming Responses` usually follows a repeatable control path:
-
-1. **Context bootstrap**: initialize runtime config and prerequisites for `className`.
-2. **Input normalization**: shape incoming data so `messages` receives stable contracts.
-3. **Core execution**: run the main logic branch and propagate intermediate state through `text`.
-4. **Policy and safety checks**: enforce limits, auth scopes, and failure boundaries.
-5. **Output composition**: return canonical result payloads for downstream consumers.
-6. **Operational telemetry**: emit logs/metrics needed for debugging and performance tuning.
-
-When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
-
-## Source Walkthrough
-
-Use the following upstream sources to verify implementation details while reading this chapter:
-
-- [AI SDK Repository](https://github.com/vercel/ai)
- Why it matters: authoritative reference on `AI SDK Repository` (github.com).
-- [AI SDK Releases](https://github.com/vercel/ai/releases)
- Why it matters: authoritative reference on `AI SDK Releases` (github.com).
-- [AI SDK Docs](https://ai-sdk.dev)
- Why it matters: authoritative reference on `AI SDK Docs` (ai-sdk.dev).
+- [`packages/ai/src/stream-text/stream-text.ts`](https://github.com/vercel/ai/blob/HEAD/packages/ai/src/stream-text/stream-text.ts) — the `streamText` function implementation, providing the streaming counterpart to `generateText` with text delta, tool call, and finish event streams.
+- [`packages/ai/src/ui/use-chat.ts`](https://github.com/vercel/ai/blob/HEAD/packages/ai/src/ui/use-chat.ts) — the `useChat` React hook that consumes the data stream protocol from `streamText` and exposes messages, input, and status state for UI integration.
Suggested trace strategy:
-- search upstream code for `className` and `messages` to map concrete implementation paths
-- compare docs claims against actual runtime/config code before reusing patterns in production
-
-## Chapter Connections
-
-- [Tutorial Index](README.md)
-- [Previous Chapter: Chapter 2: Text Generation](02-text-generation.md)
-- [Next Chapter: Chapter 4: Function Calling](04-function-calling.md)
-- [Main Catalog](../../README.md#-tutorial-catalog)
-- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
+- trace `streamText` to understand the `textStream`, `toolCallStream`, and `fullStream` properties returned
+- review how the data stream protocol format works by tracing the response body format from a Next.js route handler
+- check `useChat` to see how streaming chunks are parsed and accumulated into the messages state array
+
+## How These Components Connect
+
+```mermaid
+flowchart LR
+ A[streamText in API route] --> B[Data stream protocol response]
+ B --> C[useChat hook in React]
+ C --> D[messages state updated incrementally]
+ D --> E[UI renders streaming text]
+```
\ No newline at end of file
diff --git a/tutorials/vercel-ai-tutorial/04-function-calling.md b/tutorials/vercel-ai-tutorial/04-function-calling.md
index 66b367f1..6738c0eb 100644
--- a/tutorials/vercel-ai-tutorial/04-function-calling.md
+++ b/tutorials/vercel-ai-tutorial/04-function-calling.md
@@ -617,6 +617,18 @@ Under the hood, `Chapter 4: Function Calling` usually follows a repeatable contr
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## Architecture Flow
+
+```mermaid
+flowchart LR
+ A[User message] --> B[generateText with tools defined]
+ B --> C[Model decides to call tool]
+ C --> D[Tool function executed]
+ D --> E[Tool result added to context]
+ E --> B
+ B --> F[Final text response]
+```
+
## Source Walkthrough
Use the following upstream sources to verify implementation details while reading this chapter:
diff --git a/tutorials/vercel-ai-tutorial/05-structured-outputs.md b/tutorials/vercel-ai-tutorial/05-structured-outputs.md
index 828d2d9b..2e75a2e2 100644
--- a/tutorials/vercel-ai-tutorial/05-structured-outputs.md
+++ b/tutorials/vercel-ai-tutorial/05-structured-outputs.md
@@ -706,6 +706,16 @@ Under the hood, `Chapter 5: Structured Outputs` usually follows a repeatable con
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## Architecture Flow
+
+```mermaid
+flowchart LR
+ A[Prompt with schema] --> B[generateObject call]
+ B --> C[Model constrained by Zod schema]
+ C --> D[Validated structured object returned]
+ D --> E[Type-safe usage in application]
+```
+
## Source Walkthrough
Use the following upstream sources to verify implementation details while reading this chapter:
diff --git a/tutorials/vercel-ai-tutorial/06-react-integration.md b/tutorials/vercel-ai-tutorial/06-react-integration.md
index cdf07c41..75c57d6b 100644
--- a/tutorials/vercel-ai-tutorial/06-react-integration.md
+++ b/tutorials/vercel-ai-tutorial/06-react-integration.md
@@ -913,6 +913,18 @@ Under the hood, `Chapter 6: React Integration` usually follows a repeatable cont
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## Architecture Flow
+
+```mermaid
+flowchart LR
+ A[User input in React] --> B[useChat or useCompletion hook]
+ B --> C[POST to API route]
+ C --> D[streamText on server]
+ D --> E[Stream response to client]
+ E --> B
+ B --> F[messages state updated in UI]
+```
+
## Source Walkthrough
Use the following upstream sources to verify implementation details while reading this chapter:
diff --git a/tutorials/vercel-ai-tutorial/07-nextjs-applications.md b/tutorials/vercel-ai-tutorial/07-nextjs-applications.md
index 384f800f..306496b9 100644
--- a/tutorials/vercel-ai-tutorial/07-nextjs-applications.md
+++ b/tutorials/vercel-ai-tutorial/07-nextjs-applications.md
@@ -1034,6 +1034,16 @@ Under the hood, `Chapter 7: Next.js Applications` usually follows a repeatable c
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## Architecture Flow
+
+```mermaid
+flowchart LR
+ A[Next.js API route handler] --> B[streamText with provider]
+ B --> C[toDataStreamResponse sent to client]
+ C --> D[useChat hook in page component]
+ D --> E[Real-time UI updates]
+```
+
## Source Walkthrough
Use the following upstream sources to verify implementation details while reading this chapter:
diff --git a/tutorials/vercel-ai-tutorial/08-production-deployment.md b/tutorials/vercel-ai-tutorial/08-production-deployment.md
index f06a0a61..928893b5 100644
--- a/tutorials/vercel-ai-tutorial/08-production-deployment.md
+++ b/tutorials/vercel-ai-tutorial/08-production-deployment.md
@@ -924,6 +924,17 @@ Under the hood, `Chapter 8: Production Deployment` usually follows a repeatable
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## Architecture Flow
+
+```mermaid
+flowchart LR
+ A[AI SDK application] --> B[Provider configuration]
+ B --> C[Rate limiting and retry logic]
+ C --> D[Observability and logging]
+ D --> E[Deployed to Vercel or self-hosted]
+ E --> F[Production traffic handled]
+```
+
## Source Walkthrough
Use the following upstream sources to verify implementation details while reading this chapter:
diff --git a/tutorials/vibe-kanban-tutorial/01-getting-started.md b/tutorials/vibe-kanban-tutorial/01-getting-started.md
index 70cdd241..69e3695e 100644
--- a/tutorials/vibe-kanban-tutorial/01-getting-started.md
+++ b/tutorials/vibe-kanban-tutorial/01-getting-started.md
@@ -53,8 +53,6 @@ You now have Vibe Kanban up and ready for multi-agent task orchestration.
Next: [Chapter 2: Orchestration Architecture](02-orchestration-architecture.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `shared/remote-types.ts`
diff --git a/tutorials/vibe-kanban-tutorial/02-orchestration-architecture.md b/tutorials/vibe-kanban-tutorial/02-orchestration-architecture.md
index ce888d55..bf4ad0f7 100644
--- a/tutorials/vibe-kanban-tutorial/02-orchestration-architecture.md
+++ b/tutorials/vibe-kanban-tutorial/02-orchestration-architecture.md
@@ -44,184 +44,182 @@ You now understand how Vibe Kanban coordinates planning and execution across man
Next: [Chapter 3: Multi-Agent Execution Strategies](03-multi-agent-execution-strategies.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `scripts/setup-dev-environment.js`
+### `shared/types.ts`
-The `savePorts` function in [`scripts/setup-dev-environment.js`](https://github.com/BloopAI/vibe-kanban/blob/HEAD/scripts/setup-dev-environment.js) handles a key part of this chapter's functionality:
+The `InvitationStatus` interface in [`shared/types.ts`](https://github.com/BloopAI/vibe-kanban/blob/HEAD/shared/types.ts) handles a key part of this chapter's functionality:
-```js
- * Save ports to file
- */
-function savePorts(ports) {
- try {
- fs.writeFileSync(PORTS_FILE, JSON.stringify(ports, null, 2));
- } catch (error) {
- console.error("Failed to save ports:", error.message);
- throw error;
- }
-}
+```ts
+export enum MemberRole { ADMIN = "ADMIN", MEMBER = "MEMBER" }
-/**
- * Verify that saved ports are still available
- */
-async function verifyPorts(ports) {
- const frontendAvailable = await isPortAvailable(ports.frontend);
- const backendAvailable = await isPortAvailable(ports.backend);
- const previewProxyAvailable = await isPortAvailable(ports.preview_proxy);
+export enum InvitationStatus { PENDING = "PENDING", ACCEPTED = "ACCEPTED", DECLINED = "DECLINED", EXPIRED = "EXPIRED" }
- if (process.argv[2] === "get" && (!frontendAvailable || !backendAvailable || !previewProxyAvailable)) {
- console.log(
- `Port availability check failed: frontend:${ports.frontend}=${frontendAvailable}, backend:${ports.backend}=${backendAvailable}, preview_proxy:${ports.preview_proxy}=${previewProxyAvailable}`
- );
- }
+export type Organization = { id: string, name: string, slug: string, is_personal: boolean, issue_prefix: string, created_at: string, updated_at: string, };
- return frontendAvailable && backendAvailable && previewProxyAvailable;
-}
+export type OrganizationWithRole = { id: string, name: string, slug: string, is_personal: boolean, issue_prefix: string, created_at: string, updated_at: string, user_role: MemberRole, };
+
+export type ListOrganizationsResponse = { organizations: Array<OrganizationWithRole>, };
+
+export type GetOrganizationResponse = { organization: Organization, user_role: string, };
+
+export type CreateOrganizationRequest = { name: string, slug: string, };
+
+export type CreateOrganizationResponse = { organization: OrganizationWithRole, };
+
+export type UpdateOrganizationRequest = { name: string, };
+
+export type Invitation = { id: string, organization_id: string, invited_by_user_id: string | null, email: string, role: MemberRole, status: InvitationStatus, token: string, created_at: string, expires_at: string, };
+
+export type CreateInvitationRequest = { email: string, role: MemberRole, };
+
+export type CreateInvitationResponse = { invitation: Invitation, };
+
+export type ListInvitationsResponse = { invitations: Array<Invitation>, };
+
+export type GetInvitationResponse = { id: string, organization_slug: string, role: MemberRole, expires_at: string, };
+
+export type AcceptInvitationResponse = { organization_id: string, organization_slug: string, role: MemberRole, };
+
+export type RevokeInvitationRequest = { invitation_id: string, };
-/**
- * Allocate ports for development
- */
-async function allocatePorts() {
```
-This function is important because it defines how Vibe Kanban Tutorial: Multi-Agent Orchestration Board for Coding Workflows implements the patterns covered in this chapter.
+This interface is important because it defines how Vibe Kanban Tutorial: Multi-Agent Orchestration Board for Coding Workflows implements the patterns covered in this chapter.
-### `scripts/setup-dev-environment.js`
+### `shared/types.ts`
-The `verifyPorts` function in [`scripts/setup-dev-environment.js`](https://github.com/BloopAI/vibe-kanban/blob/HEAD/scripts/setup-dev-environment.js) handles a key part of this chapter's functionality:
+The `ThemeMode` interface in [`shared/types.ts`](https://github.com/BloopAI/vibe-kanban/blob/HEAD/shared/types.ts) handles a key part of this chapter's functionality:
-```js
- * Verify that saved ports are still available
- */
-async function verifyPorts(ports) {
- const frontendAvailable = await isPortAvailable(ports.frontend);
- const backendAvailable = await isPortAvailable(ports.backend);
- const previewProxyAvailable = await isPortAvailable(ports.preview_proxy);
+```ts
+export type SearchMode = "taskform" | "settings";
+
+export type Config = { config_version: string, theme: ThemeMode, executor_profile: ExecutorProfileId, disclaimer_acknowledged: boolean, onboarding_acknowledged: boolean, remote_onboarding_acknowledged: boolean, notifications: NotificationConfig, editor: EditorConfig, github: GitHubConfig, analytics_enabled: boolean, workspace_dir: string | null, last_app_version: string | null, show_release_notes: boolean, language: UiLanguage, git_branch_prefix: string, showcases: ShowcaseState, pr_auto_description_enabled: boolean, pr_auto_description_prompt: string | null, commit_reminder_enabled: boolean, commit_reminder_prompt: string | null, send_message_shortcut: SendMessageShortcut, relay_enabled: boolean, host_nickname: string | null, };
+
+export type NotificationConfig = { sound_enabled: boolean, push_enabled: boolean, sound_file: SoundFile, };
+
+export enum ThemeMode { LIGHT = "LIGHT", DARK = "DARK", SYSTEM = "SYSTEM" }
+
+export type EditorConfig = { editor_type: EditorType, custom_command: string | null, remote_ssh_host: string | null, remote_ssh_user: string | null, auto_install_extension: boolean, };
- if (process.argv[2] === "get" && (!frontendAvailable || !backendAvailable || !previewProxyAvailable)) {
- console.log(
- `Port availability check failed: frontend:${ports.frontend}=${frontendAvailable}, backend:${ports.backend}=${backendAvailable}, preview_proxy:${ports.preview_proxy}=${previewProxyAvailable}`
- );
- }
+export enum EditorType { VS_CODE = "VS_CODE", VS_CODE_INSIDERS = "VS_CODE_INSIDERS", CURSOR = "CURSOR", WINDSURF = "WINDSURF", INTELLI_J = "INTELLI_J", ZED = "ZED", XCODE = "XCODE", GOOGLE_ANTIGRAVITY = "GOOGLE_ANTIGRAVITY", CUSTOM = "CUSTOM" }
- return frontendAvailable && backendAvailable && previewProxyAvailable;
-}
+export type EditorOpenError = { "type": "executable_not_found", executable: string, editor_type: EditorType, } | { "type": "invalid_command", details: string, editor_type: EditorType, } | { "type": "launch_failed", executable: string, details: string, editor_type: EditorType, };
+export type GitHubConfig = { pat: string | null, oauth_token: string | null, username: string | null, primary_email: string | null, default_pr_base: string | null, };
+
+export enum SoundFile { ABSTRACT_SOUND1 = "ABSTRACT_SOUND1", ABSTRACT_SOUND2 = "ABSTRACT_SOUND2", ABSTRACT_SOUND3 = "ABSTRACT_SOUND3", ABSTRACT_SOUND4 = "ABSTRACT_SOUND4", COW_MOOING = "COW_MOOING", FAHHHHH = "FAHHHHH", PHONE_VIBRATION = "PHONE_VIBRATION", ROOSTER = "ROOSTER" }
+
+export type UiLanguage = "BROWSER" | "EN" | "FR" | "JA" | "ES" | "KO" | "ZH_HANS" | "ZH_HANT";
+
+export type ShowcaseState = { seen_features: Array<string>, };
+
+export type SendMessageShortcut = "ModifierEnter" | "Enter";
+
+export type GitBranch = { name: string, is_current: boolean, is_remote: boolean, last_commit_date: Date, };
+
+export type QueuedMessage = {
/**
- * Allocate ports for development
+ * The session this message is queued for
*/
-async function allocatePorts() {
- // If PORT env is set, use it for frontend and PORT+1 for backend
- if (process.env.PORT) {
- const frontendPort = parseInt(process.env.PORT, 10);
- const backendPort = frontendPort + 1;
- const previewProxyPort = backendPort + 1;
-
- const ports = {
- frontend: frontendPort,
- backend: backendPort,
- preview_proxy: previewProxyPort,
- timestamp: new Date().toISOString(),
- };
+session_id: string,
+/**
```
-This function is important because it defines how Vibe Kanban Tutorial: Multi-Agent Orchestration Board for Coding Workflows implements the patterns covered in this chapter.
+This interface is important because it defines how Vibe Kanban Tutorial: Multi-Agent Orchestration Board for Coding Workflows implements the patterns covered in this chapter.
-### `scripts/setup-dev-environment.js`
+### `shared/types.ts`
-The `allocatePorts` function in [`scripts/setup-dev-environment.js`](https://github.com/BloopAI/vibe-kanban/blob/HEAD/scripts/setup-dev-environment.js) handles a key part of this chapter's functionality:
+The `EditorType` interface in [`shared/types.ts`](https://github.com/BloopAI/vibe-kanban/blob/HEAD/shared/types.ts) handles a key part of this chapter's functionality:
+
+```ts
+export type GetMcpServerResponse = { mcp_config: McpConfig, config_path: string, };
+
+export type CheckEditorAvailabilityQuery = { editor_type: EditorType, };
+
+export type CheckEditorAvailabilityResponse = { available: boolean, };
+
+export type CheckAgentAvailabilityQuery = { executor: BaseCodingAgent, };
+
+export type AgentPresetOptionsQuery = { executor: BaseCodingAgent, variant: string | null, };
+
+export type CurrentUserResponse = { user_id: string, };
+
+export type StartSpake2EnrollmentRequest = { enrollment_code: string, client_message_b64: string, };
+
+export type FinishSpake2EnrollmentRequest = { enrollment_id: string, client_id: string, client_name: string, client_browser: string, client_os: string, client_device: string, public_key_b64: string, client_proof_b64: string, };
+
+export type StartSpake2EnrollmentResponse = { enrollment_id: string, server_message_b64: string, };
+
+export type FinishSpake2EnrollmentResponse = { signing_session_id: string, server_public_key_b64: string, server_proof_b64: string, };
+
+export type RelayPairedClient = { client_id: string, client_name: string, client_browser: string, client_os: string, client_device: string, };
+
+export type ListRelayPairedClientsResponse = { clients: Array<RelayPairedClient>, };
+
+export type RemoveRelayPairedClientResponse = { removed: boolean, };
+
+export type RefreshRelaySigningSessionRequest = { client_id: string, timestamp: bigint, nonce: string, signature_b64: string, };
+
+export type RefreshRelaySigningSessionResponse = { signing_session_id: string, };
+
+export type CreateFollowUpAttempt = { prompt: string, executor_config: ExecutorConfig, retry_process_id: string | null, force_when_dirty: boolean | null, perform_git_reset: boolean | null, };
-```js
- * Allocate ports for development
- */
-async function allocatePorts() {
- // If PORT env is set, use it for frontend and PORT+1 for backend
- if (process.env.PORT) {
- const frontendPort = parseInt(process.env.PORT, 10);
- const backendPort = frontendPort + 1;
- const previewProxyPort = backendPort + 1;
-
- const ports = {
- frontend: frontendPort,
- backend: backendPort,
- preview_proxy: previewProxyPort,
- timestamp: new Date().toISOString(),
- };
-
- if (process.argv[2] === "get") {
- console.log("Using PORT environment variable:");
- console.log(`Frontend: ${ports.frontend}`);
- console.log(`Backend: ${ports.backend}`);
- console.log(`Preview Proxy: ${ports.preview_proxy}`);
- }
-
- return ports;
- }
-
- // Try to load existing ports first
- const existingPorts = loadPorts();
-
- if (existingPorts) {
- // Verify existing ports are still available
- if (await verifyPorts(existingPorts)) {
```
-This function is important because it defines how Vibe Kanban Tutorial: Multi-Agent Orchestration Board for Coding Workflows implements the patterns covered in this chapter.
+This interface is important because it defines how Vibe Kanban Tutorial: Multi-Agent Orchestration Board for Coding Workflows implements the patterns covered in this chapter.
-### `scripts/setup-dev-environment.js`
+### `shared/types.ts`
-The `getPorts` function in [`scripts/setup-dev-environment.js`](https://github.com/BloopAI/vibe-kanban/blob/HEAD/scripts/setup-dev-environment.js) handles a key part of this chapter's functionality:
+The `SoundFile` interface in [`shared/types.ts`](https://github.com/BloopAI/vibe-kanban/blob/HEAD/shared/types.ts) handles a key part of this chapter's functionality:
-```js
- * Get ports (allocate if needed)
- */
-async function getPorts() {
- const ports = await allocatePorts();
- copyDevAssets();
- return ports;
-}
+```ts
+export type Config = { config_version: string, theme: ThemeMode, executor_profile: ExecutorProfileId, disclaimer_acknowledged: boolean, onboarding_acknowledged: boolean, remote_onboarding_acknowledged: boolean, notifications: NotificationConfig, editor: EditorConfig, github: GitHubConfig, analytics_enabled: boolean, workspace_dir: string | null, last_app_version: string | null, show_release_notes: boolean, language: UiLanguage, git_branch_prefix: string, showcases: ShowcaseState, pr_auto_description_enabled: boolean, pr_auto_description_prompt: string | null, commit_reminder_enabled: boolean, commit_reminder_prompt: string | null, send_message_shortcut: SendMessageShortcut, relay_enabled: boolean, host_nickname: string | null, };
+
+export type NotificationConfig = { sound_enabled: boolean, push_enabled: boolean, sound_file: SoundFile, };
+
+export enum ThemeMode { LIGHT = "LIGHT", DARK = "DARK", SYSTEM = "SYSTEM" }
+
+export type EditorConfig = { editor_type: EditorType, custom_command: string | null, remote_ssh_host: string | null, remote_ssh_user: string | null, auto_install_extension: boolean, };
+
+export enum EditorType { VS_CODE = "VS_CODE", VS_CODE_INSIDERS = "VS_CODE_INSIDERS", CURSOR = "CURSOR", WINDSURF = "WINDSURF", INTELLI_J = "INTELLI_J", ZED = "ZED", XCODE = "XCODE", GOOGLE_ANTIGRAVITY = "GOOGLE_ANTIGRAVITY", CUSTOM = "CUSTOM" }
+
+export type EditorOpenError = { "type": "executable_not_found", executable: string, editor_type: EditorType, } | { "type": "invalid_command", details: string, editor_type: EditorType, } | { "type": "launch_failed", executable: string, details: string, editor_type: EditorType, };
+export type GitHubConfig = { pat: string | null, oauth_token: string | null, username: string | null, primary_email: string | null, default_pr_base: string | null, };
+
+export enum SoundFile { ABSTRACT_SOUND1 = "ABSTRACT_SOUND1", ABSTRACT_SOUND2 = "ABSTRACT_SOUND2", ABSTRACT_SOUND3 = "ABSTRACT_SOUND3", ABSTRACT_SOUND4 = "ABSTRACT_SOUND4", COW_MOOING = "COW_MOOING", FAHHHHH = "FAHHHHH", PHONE_VIBRATION = "PHONE_VIBRATION", ROOSTER = "ROOSTER" }
+
+export type UiLanguage = "BROWSER" | "EN" | "FR" | "JA" | "ES" | "KO" | "ZH_HANS" | "ZH_HANT";
+
+export type ShowcaseState = { seen_features: Array<string>, };
+
+export type SendMessageShortcut = "ModifierEnter" | "Enter";
+
+export type GitBranch = { name: string, is_current: boolean, is_remote: boolean, last_commit_date: Date, };
+
+export type QueuedMessage = {
/**
- * Copy dev_assets_seed to dev_assets
+ * The session this message is queued for
*/
-function copyDevAssets() {
- try {
- if (!fs.existsSync(DEV_ASSETS)) {
- // Copy dev_assets_seed to dev_assets
- fs.cpSync(DEV_ASSETS_SEED, DEV_ASSETS, { recursive: true });
-
- if (process.argv[2] === "get") {
- console.log("Copied dev_assets_seed to dev_assets");
- }
- }
- } catch (error) {
- console.error("Failed to copy dev assets:", error.message);
- }
-}
-
+session_id: string,
/**
- * Clear saved ports
+ * The follow-up data (message + variant)
*/
-function clearPorts() {
- try {
- if (fs.existsSync(PORTS_FILE)) {
```
-This function is important because it defines how Vibe Kanban Tutorial: Multi-Agent Orchestration Board for Coding Workflows implements the patterns covered in this chapter.
+This interface is important because it defines how Vibe Kanban Tutorial: Multi-Agent Orchestration Board for Coding Workflows implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[savePorts]
- B[verifyPorts]
- C[allocatePorts]
- D[getPorts]
- E[copyDevAssets]
+ A[InvitationStatus]
+ B[ThemeMode]
+ C[EditorType]
+ D[SoundFile]
+ E[BaseCodingAgent]
A --> B
B --> C
C --> D
diff --git a/tutorials/vibe-kanban-tutorial/03-multi-agent-execution-strategies.md b/tutorials/vibe-kanban-tutorial/03-multi-agent-execution-strategies.md
index 673cd0ce..e7698667 100644
--- a/tutorials/vibe-kanban-tutorial/03-multi-agent-execution-strategies.md
+++ b/tutorials/vibe-kanban-tutorial/03-multi-agent-execution-strategies.md
@@ -45,92 +45,8 @@ You now can structure multi-agent execution for both speed and reliability.
Next: [Chapter 4: MCP and Configuration Control](04-mcp-and-configuration-control.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `scripts/generate-desktop-manifest.js`
-
-The `findBundleArtifact` function in [`scripts/generate-desktop-manifest.js`](https://github.com/BloopAI/vibe-kanban/blob/HEAD/scripts/generate-desktop-manifest.js) handles a key part of this chapter's functionality:
-
-```js
-
-// Find the main bundle artifact for a platform (skip .sig and installer-only files)
-function findBundleArtifact(dir) {
- if (!fs.existsSync(dir)) return null;
-
- const files = fs.readdirSync(dir);
-
- // Look for updater artifacts in priority order
- // macOS: .app.tar.gz, Linux: .AppImage.tar.gz, Windows: *-setup.exe
- const tarGz = files.find(
- (f) =>
- (f.endsWith('.app.tar.gz') || f.endsWith('.AppImage.tar.gz')) &&
- !f.endsWith('.sig')
- );
- if (tarGz) {
- const type = tarGz.endsWith('.app.tar.gz')
- ? 'app-tar-gz'
- : 'appimage-tar-gz';
- return { file: tarGz, type };
- }
-
- // Windows NSIS installer
- const nsis = files.find(
- (f) => f.endsWith('-setup.exe') && !f.endsWith('.sig')
- );
- if (nsis) {
- return { file: nsis, type: 'nsis-exe' };
- }
-
- return null;
-}
-
-```
-
-This function is important because it defines how Vibe Kanban Tutorial: Multi-Agent Orchestration Board for Coding Workflows implements the patterns covered in this chapter.
-
-### `scripts/generate-tauri-update-json.js`
-
-The `parseArgs` function in [`scripts/generate-tauri-update-json.js`](https://github.com/BloopAI/vibe-kanban/blob/HEAD/scripts/generate-tauri-update-json.js) handles a key part of this chapter's functionality:
-
-```js
-const path = require('path');
-
-function parseArgs() {
- const args = process.argv.slice(2);
- const parsed = {};
- for (let i = 0; i < args.length; i += 2) {
- const key = args[i].replace(/^--/, '');
- parsed[key] = args[i + 1];
- }
- return parsed;
-}
-
-function findArtifact(dir) {
- if (!fs.existsSync(dir)) return null;
-
- const files = fs.readdirSync(dir);
- // Look for .sig files to find the updater artifacts
- const sigFiles = files.filter(f => f.endsWith('.sig'));
-
- if (sigFiles.length === 0) return null;
-
- // Prefer .tar.gz (macOS/Linux) over .exe (Windows)
- // Tauri generates: .app.tar.gz + .sig on macOS, .AppImage.tar.gz + .sig on Linux, .exe + .sig on Windows
- const sigFile = sigFiles[0];
- const artifactFile = sigFile.replace(/\.sig$/, '');
-
- if (!files.includes(artifactFile)) {
- console.error(`Warning: Found ${sigFile} but missing ${artifactFile} in ${dir}`);
- return null;
- }
-
- return {
-```
-
-This function is important because it defines how Vibe Kanban Tutorial: Multi-Agent Orchestration Board for Coding Workflows implements the patterns covered in this chapter.
-
### `scripts/generate-tauri-update-json.js`
The `findArtifact` function in [`scripts/generate-tauri-update-json.js`](https://github.com/BloopAI/vibe-kanban/blob/HEAD/scripts/generate-tauri-update-json.js) handles a key part of this chapter's functionality:
@@ -172,57 +88,139 @@ const downloadBase = args['download-base'];
This function is important because it defines how Vibe Kanban Tutorial: Multi-Agent Orchestration Board for Coding Workflows implements the patterns covered in this chapter.
-### `shared/types.ts`
+### `scripts/setup-dev-environment.js`
-The `ScratchType` interface in [`shared/types.ts`](https://github.com/BloopAI/vibe-kanban/blob/HEAD/shared/types.ts) handles a key part of this chapter's functionality:
+The `isPortAvailable` function in [`scripts/setup-dev-environment.js`](https://github.com/BloopAI/vibe-kanban/blob/HEAD/scripts/setup-dev-environment.js) handles a key part of this chapter's functionality:
-```ts
-export type ScratchPayload = { "type": "DRAFT_TASK", "data": string } | { "type": "DRAFT_FOLLOW_UP", "data": DraftFollowUpData } | { "type": "DRAFT_WORKSPACE", "data": DraftWorkspaceData } | { "type": "DRAFT_ISSUE", "data": DraftIssueData } | { "type": "PREVIEW_SETTINGS", "data": PreviewSettingsData } | { "type": "WORKSPACE_NOTES", "data": WorkspaceNotesData } | { "type": "UI_PREFERENCES", "data": UiPreferencesData } | { "type": "PROJECT_REPO_DEFAULTS", "data": ProjectRepoDefaultsData };
+```js
+ * Check if a port is available
+ */
+function isPortAvailable(port) {
+ return new Promise((resolve) => {
+ const sock = net.createConnection({ port, host: "localhost" });
+ sock.on("connect", () => {
+ sock.destroy();
+ resolve(false);
+ });
+ sock.on("error", () => resolve(true));
+ });
+}
-export enum ScratchType { DRAFT_TASK = "DRAFT_TASK", DRAFT_FOLLOW_UP = "DRAFT_FOLLOW_UP", DRAFT_WORKSPACE = "DRAFT_WORKSPACE", DRAFT_ISSUE = "DRAFT_ISSUE", PREVIEW_SETTINGS = "PREVIEW_SETTINGS", WORKSPACE_NOTES = "WORKSPACE_NOTES", UI_PREFERENCES = "UI_PREFERENCES", PROJECT_REPO_DEFAULTS = "PROJECT_REPO_DEFAULTS" }
+/**
+ * Find a free port starting from a given port
+ */
+async function findFreePort(startPort = 3000) {
+ let port = startPort;
+ while (!(await isPortAvailable(port))) {
+ port++;
+ if (port > 65535) {
+ throw new Error("No available ports found");
+ }
+ }
+ return port;
+}
-export type Scratch = { id: string, payload: ScratchPayload, created_at: string, updated_at: string, };
+/**
+ * Load existing ports from file
+ */
+function loadPorts() {
+ try {
+```
-export type CreateScratch = { payload: ScratchPayload, };
+This function is important because it defines how Vibe Kanban Tutorial: Multi-Agent Orchestration Board for Coding Workflows implements the patterns covered in this chapter.
-export type UpdateScratch = { payload: ScratchPayload, };
+### `scripts/setup-dev-environment.js`
-export type Workspace = { id: string, task_id: string | null, container_ref: string | null, branch: string, setup_completed_at: string | null, created_at: string, updated_at: string, archived: boolean, pinned: boolean, name: string | null, worktree_deleted: boolean, };
+The `findFreePort` function in [`scripts/setup-dev-environment.js`](https://github.com/BloopAI/vibe-kanban/blob/HEAD/scripts/setup-dev-environment.js) handles a key part of this chapter's functionality:
-export type WorkspaceWithStatus = { is_running: boolean, is_errored: boolean, id: string, task_id: string | null, container_ref: string | null, branch: string, setup_completed_at: string | null, created_at: string, updated_at: string, archived: boolean, pinned: boolean, name: string | null, worktree_deleted: boolean, };
+```js
+ * Find a free port starting from a given port
+ */
+async function findFreePort(startPort = 3000) {
+ let port = startPort;
+ while (!(await isPortAvailable(port))) {
+ port++;
+ if (port > 65535) {
+ throw new Error("No available ports found");
+ }
+ }
+ return port;
+}
-export type Session = { id: string, workspace_id: string, name: string | null, executor: string | null, agent_working_dir: string | null, created_at: string, updated_at: string, };
+/**
+ * Load existing ports from file
+ */
+function loadPorts() {
+ try {
+ if (fs.existsSync(PORTS_FILE)) {
+ const data = fs.readFileSync(PORTS_FILE, "utf8");
+ return JSON.parse(data);
+ }
+ } catch (error) {
+ console.warn("Failed to load existing ports:", error.message);
+ }
+ return null;
+}
-export type ExecutionProcess = { id: string, session_id: string, run_reason: ExecutionProcessRunReason, executor_action: ExecutorAction, status: ExecutionProcessStatus, exit_code: bigint | null,
/**
- * dropped: true if this process is excluded from the current
- * history view (due to restore/trimming). Hidden from logs/timeline;
- * still listed in the Processes tab.
+ * Save ports to file
*/
-dropped: boolean, started_at: string, completed_at: string | null, created_at: string, updated_at: string, };
+function savePorts(ports) {
+```
-export enum ExecutionProcessStatus { running = "running", completed = "completed", failed = "failed", killed = "killed" }
+This function is important because it defines how Vibe Kanban Tutorial: Multi-Agent Orchestration Board for Coding Workflows implements the patterns covered in this chapter.
-export type ExecutionProcessRunReason = "setupscript" | "cleanupscript" | "archivescript" | "codingagent" | "devserver";
+### `scripts/setup-dev-environment.js`
-export type ExecutionProcessRepoState = { id: string, execution_process_id: string, repo_id: string, before_head_commit: string | null, after_head_commit: string | null, merge_commit: string | null, created_at: Date, updated_at: Date, };
+The `loadPorts` function in [`scripts/setup-dev-environment.js`](https://github.com/BloopAI/vibe-kanban/blob/HEAD/scripts/setup-dev-environment.js) handles a key part of this chapter's functionality:
-export type Merge = { "type": "direct" } & DirectMerge | { "type": "pr" } & PrMerge;
+```js
+ * Load existing ports from file
+ */
+function loadPorts() {
+ try {
+ if (fs.existsSync(PORTS_FILE)) {
+ const data = fs.readFileSync(PORTS_FILE, "utf8");
+ return JSON.parse(data);
+ }
+ } catch (error) {
+ console.warn("Failed to load existing ports:", error.message);
+ }
+ return null;
+}
+
+/**
+ * Save ports to file
+ */
+function savePorts(ports) {
+ try {
+ fs.writeFileSync(PORTS_FILE, JSON.stringify(ports, null, 2));
+ } catch (error) {
+ console.error("Failed to save ports:", error.message);
+ throw error;
+ }
+}
+/**
+ * Verify that saved ports are still available
+ */
+async function verifyPorts(ports) {
+ const frontendAvailable = await isPortAvailable(ports.frontend);
+ const backendAvailable = await isPortAvailable(ports.backend);
```
-This interface is important because it defines how Vibe Kanban Tutorial: Multi-Agent Orchestration Board for Coding Workflows implements the patterns covered in this chapter.
+This function is important because it defines how Vibe Kanban Tutorial: Multi-Agent Orchestration Board for Coding Workflows implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[findBundleArtifact]
- B[parseArgs]
- C[findArtifact]
- D[ScratchType]
- E[ExecutionProcessStatus]
+ A[findArtifact]
+ B[isPortAvailable]
+ C[findFreePort]
+ D[loadPorts]
+ E[savePorts]
A --> B
B --> C
C --> D
diff --git a/tutorials/vibe-kanban-tutorial/04-mcp-and-configuration-control.md b/tutorials/vibe-kanban-tutorial/04-mcp-and-configuration-control.md
index ee5ec692..387dbe26 100644
--- a/tutorials/vibe-kanban-tutorial/04-mcp-and-configuration-control.md
+++ b/tutorials/vibe-kanban-tutorial/04-mcp-and-configuration-control.md
@@ -46,184 +46,182 @@ You now have a practical model for MCP/runtime configuration governance in Vibe
Next: [Chapter 5: Review and Quality Gates](05-review-and-quality-gates.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `shared/types.ts`
-
-The `EditorType` interface in [`shared/types.ts`](https://github.com/BloopAI/vibe-kanban/blob/HEAD/shared/types.ts) handles a key part of this chapter's functionality:
-
-```ts
-export type GetMcpServerResponse = { mcp_config: McpConfig, config_path: string, };
-
-export type CheckEditorAvailabilityQuery = { editor_type: EditorType, };
-
-export type CheckEditorAvailabilityResponse = { available: boolean, };
-
-export type CheckAgentAvailabilityQuery = { executor: BaseCodingAgent, };
-
-export type AgentPresetOptionsQuery = { executor: BaseCodingAgent, variant: string | null, };
-
-export type CurrentUserResponse = { user_id: string, };
-
-export type StartSpake2EnrollmentRequest = { enrollment_code: string, client_message_b64: string, };
-
-export type FinishSpake2EnrollmentRequest = { enrollment_id: string, client_id: string, client_name: string, client_browser: string, client_os: string, client_device: string, public_key_b64: string, client_proof_b64: string, };
-
-export type StartSpake2EnrollmentResponse = { enrollment_id: string, server_message_b64: string, };
-
-export type FinishSpake2EnrollmentResponse = { signing_session_id: string, server_public_key_b64: string, server_proof_b64: string, };
-
-export type RelayPairedClient = { client_id: string, client_name: string, client_browser: string, client_os: string, client_device: string, };
-
-export type ListRelayPairedClientsResponse = { clients: Array<RelayPairedClient>, };
-
-export type RemoveRelayPairedClientResponse = { removed: boolean, };
-
-export type RefreshRelaySigningSessionRequest = { client_id: string, timestamp: bigint, nonce: string, signature_b64: string, };
-
-export type RefreshRelaySigningSessionResponse = { signing_session_id: string, };
-
-export type CreateFollowUpAttempt = { prompt: string, executor_config: ExecutorConfig, retry_process_id: string | null, force_when_dirty: boolean | null, perform_git_reset: boolean | null, };
-
-```
-
-This interface is important because it defines how Vibe Kanban Tutorial: Multi-Agent Orchestration Board for Coding Workflows implements the patterns covered in this chapter.
-
-### `shared/types.ts`
-
-The `SoundFile` interface in [`shared/types.ts`](https://github.com/BloopAI/vibe-kanban/blob/HEAD/shared/types.ts) handles a key part of this chapter's functionality:
-
-```ts
-export type Config = { config_version: string, theme: ThemeMode, executor_profile: ExecutorProfileId, disclaimer_acknowledged: boolean, onboarding_acknowledged: boolean, remote_onboarding_acknowledged: boolean, notifications: NotificationConfig, editor: EditorConfig, github: GitHubConfig, analytics_enabled: boolean, workspace_dir: string | null, last_app_version: string | null, show_release_notes: boolean, language: UiLanguage, git_branch_prefix: string, showcases: ShowcaseState, pr_auto_description_enabled: boolean, pr_auto_description_prompt: string | null, commit_reminder_enabled: boolean, commit_reminder_prompt: string | null, send_message_shortcut: SendMessageShortcut, relay_enabled: boolean, host_nickname: string | null, };
-
-export type NotificationConfig = { sound_enabled: boolean, push_enabled: boolean, sound_file: SoundFile, };
-
-export enum ThemeMode { LIGHT = "LIGHT", DARK = "DARK", SYSTEM = "SYSTEM" }
-
-export type EditorConfig = { editor_type: EditorType, custom_command: string | null, remote_ssh_host: string | null, remote_ssh_user: string | null, auto_install_extension: boolean, };
-
-export enum EditorType { VS_CODE = "VS_CODE", VS_CODE_INSIDERS = "VS_CODE_INSIDERS", CURSOR = "CURSOR", WINDSURF = "WINDSURF", INTELLI_J = "INTELLI_J", ZED = "ZED", XCODE = "XCODE", GOOGLE_ANTIGRAVITY = "GOOGLE_ANTIGRAVITY", CUSTOM = "CUSTOM" }
-
-export type EditorOpenError = { "type": "executable_not_found", executable: string, editor_type: EditorType, } | { "type": "invalid_command", details: string, editor_type: EditorType, } | { "type": "launch_failed", executable: string, details: string, editor_type: EditorType, };
-
-export type GitHubConfig = { pat: string | null, oauth_token: string | null, username: string | null, primary_email: string | null, default_pr_base: string | null, };
-
-export enum SoundFile { ABSTRACT_SOUND1 = "ABSTRACT_SOUND1", ABSTRACT_SOUND2 = "ABSTRACT_SOUND2", ABSTRACT_SOUND3 = "ABSTRACT_SOUND3", ABSTRACT_SOUND4 = "ABSTRACT_SOUND4", COW_MOOING = "COW_MOOING", FAHHHHH = "FAHHHHH", PHONE_VIBRATION = "PHONE_VIBRATION", ROOSTER = "ROOSTER" }
-
-export type UiLanguage = "BROWSER" | "EN" | "FR" | "JA" | "ES" | "KO" | "ZH_HANS" | "ZH_HANT";
-
-export type ShowcaseState = { seen_features: Array<string>, };
+### `scripts/setup-dev-environment.js`
-export type SendMessageShortcut = "ModifierEnter" | "Enter";
+The `copyDevAssets` function in [`scripts/setup-dev-environment.js`](https://github.com/BloopAI/vibe-kanban/blob/HEAD/scripts/setup-dev-environment.js) handles a key part of this chapter's functionality:
-export type GitBranch = { name: string, is_current: boolean, is_remote: boolean, last_commit_date: Date, };
+```js
+async function getPorts() {
+ const ports = await allocatePorts();
+ copyDevAssets();
+ return ports;
+}
-export type QueuedMessage = {
/**
- * The session this message is queued for
+ * Copy dev_assets_seed to dev_assets
*/
-session_id: string,
+function copyDevAssets() {
+ try {
+ if (!fs.existsSync(DEV_ASSETS)) {
+ // Copy dev_assets_seed to dev_assets
+ fs.cpSync(DEV_ASSETS_SEED, DEV_ASSETS, { recursive: true });
+
+ if (process.argv[2] === "get") {
+ console.log("Copied dev_assets_seed to dev_assets");
+ }
+ }
+ } catch (error) {
+ console.error("Failed to copy dev assets:", error.message);
+ }
+}
+
/**
- * The follow-up data (message + variant)
+ * Clear saved ports
*/
+function clearPorts() {
+ try {
+ if (fs.existsSync(PORTS_FILE)) {
+ fs.unlinkSync(PORTS_FILE);
+ console.log("Cleared saved dev ports");
```
-This interface is important because it defines how Vibe Kanban Tutorial: Multi-Agent Orchestration Board for Coding Workflows implements the patterns covered in this chapter.
+This function is important because it defines how Vibe Kanban Tutorial: Multi-Agent Orchestration Board for Coding Workflows implements the patterns covered in this chapter.
-### `shared/types.ts`
+### `scripts/setup-dev-environment.js`
-The `BaseCodingAgent` interface in [`shared/types.ts`](https://github.com/BloopAI/vibe-kanban/blob/HEAD/shared/types.ts) handles a key part of this chapter's functionality:
+The `clearPorts` function in [`scripts/setup-dev-environment.js`](https://github.com/BloopAI/vibe-kanban/blob/HEAD/scripts/setup-dev-environment.js) handles a key part of this chapter's functionality:
-```ts
- * Capabilities supported per executor (e.g., { "CLAUDE_CODE": ["SESSION_FORK"] })
+```js
+ * Clear saved ports
*/
-capabilities: { [key in string]?: Array<BaseAgentCapability> }, shared_api_base: string | null, preview_proxy_port: number | null, executors: { [key in BaseCodingAgent]?: ExecutorProfile }, };
-
-export type Environment = { os_type: string, os_version: string, os_architecture: string, bitness: string, };
-
-export type McpServerQuery = { executor: BaseCodingAgent, };
-
-export type UpdateMcpServersBody = { servers: { [key in string]?: JsonValue }, };
-
-export type GetMcpServerResponse = { mcp_config: McpConfig, config_path: string, };
-
-export type CheckEditorAvailabilityQuery = { editor_type: EditorType, };
-
-export type CheckEditorAvailabilityResponse = { available: boolean, };
-
-export type CheckAgentAvailabilityQuery = { executor: BaseCodingAgent, };
+function clearPorts() {
+ try {
+ if (fs.existsSync(PORTS_FILE)) {
+ fs.unlinkSync(PORTS_FILE);
+ console.log("Cleared saved dev ports");
+ } else {
+ console.log("No saved ports to clear");
+ }
+ } catch (error) {
+ console.error("Failed to clear ports:", error.message);
+ }
+}
+
+// CLI interface
+if (require.main === module) {
+ const command = process.argv[2];
+
+ switch (command) {
+ case "get":
+ getPorts()
+ .then((ports) => {
+ console.log(JSON.stringify(ports));
+ })
+ .catch(console.error);
+ break;
+
+ case "clear":
+ clearPorts();
+ break;
-export type AgentPresetOptionsQuery = { executor: BaseCodingAgent, variant: string | null, };
+```
-export type CurrentUserResponse = { user_id: string, };
+This function is important because it defines how Vibe Kanban Tutorial: Multi-Agent Orchestration Board for Coding Workflows implements the patterns covered in this chapter.
-export type StartSpake2EnrollmentRequest = { enrollment_code: string, client_message_b64: string, };
+### `scripts/setup-dev-environment.js`
-export type FinishSpake2EnrollmentRequest = { enrollment_id: string, client_id: string, client_name: string, client_browser: string, client_os: string, client_device: string, public_key_b64: string, client_proof_b64: string, };
+The `if` interface in [`scripts/setup-dev-environment.js`](https://github.com/BloopAI/vibe-kanban/blob/HEAD/scripts/setup-dev-environment.js) handles a key part of this chapter's functionality:
-export type StartSpake2EnrollmentResponse = { enrollment_id: string, server_message_b64: string, };
+```js
-export type FinishSpake2EnrollmentResponse = { signing_session_id: string, server_public_key_b64: string, server_proof_b64: string, };
+/**
+ * Check if a port is available
+ */
+function isPortAvailable(port) {
+ return new Promise((resolve) => {
+ const sock = net.createConnection({ port, host: "localhost" });
+ sock.on("connect", () => {
+ sock.destroy();
+ resolve(false);
+ });
+ sock.on("error", () => resolve(true));
+ });
+}
-export type RelayPairedClient = { client_id: string, client_name: string, client_browser: string, client_os: string, client_device: string, };
+/**
+ * Find a free port starting from a given port
+ */
+async function findFreePort(startPort = 3000) {
+ let port = startPort;
+ while (!(await isPortAvailable(port))) {
+ port++;
+ if (port > 65535) {
+ throw new Error("No available ports found");
+ }
+ }
+ return port;
+}
+/**
+ * Load existing ports from file
+ */
```
This interface is important because it defines how Vibe Kanban Tutorial: Multi-Agent Orchestration Board for Coding Workflows implements the patterns covered in this chapter.
-### `shared/types.ts`
-
-The `BaseAgentCapability` interface in [`shared/types.ts`](https://github.com/BloopAI/vibe-kanban/blob/HEAD/shared/types.ts) handles a key part of this chapter's functionality:
-
-```ts
- * Capabilities supported per executor (e.g., { "CLAUDE_CODE": ["SESSION_FORK"] })
- */
-capabilities: { [key in string]?: Array<BaseAgentCapability> }, shared_api_base: string | null, preview_proxy_port: number | null, executors: { [key in BaseCodingAgent]?: ExecutorProfile }, };
-
-export type Environment = { os_type: string, os_version: string, os_architecture: string, bitness: string, };
-
-export type McpServerQuery = { executor: BaseCodingAgent, };
-
-export type UpdateMcpServersBody = { servers: { [key in string]?: JsonValue }, };
-
-export type GetMcpServerResponse = { mcp_config: McpConfig, config_path: string, };
-
-export type CheckEditorAvailabilityQuery = { editor_type: EditorType, };
-
-export type CheckEditorAvailabilityResponse = { available: boolean, };
-
-export type CheckAgentAvailabilityQuery = { executor: BaseCodingAgent, };
-
-export type AgentPresetOptionsQuery = { executor: BaseCodingAgent, variant: string | null, };
-
-export type CurrentUserResponse = { user_id: string, };
-
-export type StartSpake2EnrollmentRequest = { enrollment_code: string, client_message_b64: string, };
-
-export type FinishSpake2EnrollmentRequest = { enrollment_id: string, client_id: string, client_name: string, client_browser: string, client_os: string, client_device: string, public_key_b64: string, client_proof_b64: string, };
-
-export type StartSpake2EnrollmentResponse = { enrollment_id: string, server_message_b64: string, };
-
-export type FinishSpake2EnrollmentResponse = { signing_session_id: string, server_public_key_b64: string, server_proof_b64: string, };
-
-export type RelayPairedClient = { client_id: string, client_name: string, client_browser: string, client_os: string, client_device: string, };
+### `scripts/generate-desktop-manifest.js`
+
+The `parseArgs` function in [`scripts/generate-desktop-manifest.js`](https://github.com/BloopAI/vibe-kanban/blob/HEAD/scripts/generate-desktop-manifest.js) handles a key part of this chapter's functionality:
+
+```js
+const crypto = require('crypto');
+
+function parseArgs() {
+ const args = process.argv.slice(2);
+ const parsed = {};
+ for (let i = 0; i < args.length; i += 2) {
+ const key = args[i].replace(/^--/, '');
+ parsed[key] = args[i + 1];
+ }
+ return parsed;
+}
+
+// Find the main bundle artifact for a platform (skip .sig and installer-only files)
+function findBundleArtifact(dir) {
+ if (!fs.existsSync(dir)) return null;
+
+ const files = fs.readdirSync(dir);
+
+ // Look for updater artifacts in priority order
+ // macOS: .app.tar.gz, Linux: .AppImage.tar.gz, Windows: *-setup.exe
+ const tarGz = files.find(
+ (f) =>
+ (f.endsWith('.app.tar.gz') || f.endsWith('.AppImage.tar.gz')) &&
+ !f.endsWith('.sig')
+ );
+ if (tarGz) {
+ const type = tarGz.endsWith('.app.tar.gz')
+ ? 'app-tar-gz'
+ : 'appimage-tar-gz';
+ return { file: tarGz, type };
+ }
```
-This interface is important because it defines how Vibe Kanban Tutorial: Multi-Agent Orchestration Board for Coding Workflows implements the patterns covered in this chapter.
+This function is important because it defines how Vibe Kanban Tutorial: Multi-Agent Orchestration Board for Coding Workflows implements the patterns covered in this chapter.
## How These Components Connect
```mermaid
flowchart TD
- A[EditorType]
- B[SoundFile]
- C[BaseCodingAgent]
- D[BaseAgentCapability]
- E[PermissionPolicy]
+ A[copyDevAssets]
+ B[clearPorts]
+ C[if]
+ D[parseArgs]
+ E[findBundleArtifact]
A --> B
B --> C
C --> D
diff --git a/tutorials/vibe-kanban-tutorial/05-review-and-quality-gates.md b/tutorials/vibe-kanban-tutorial/05-review-and-quality-gates.md
index 5a64e3c4..d14d34e6 100644
--- a/tutorials/vibe-kanban-tutorial/05-review-and-quality-gates.md
+++ b/tutorials/vibe-kanban-tutorial/05-review-and-quality-gates.md
@@ -45,170 +45,168 @@ You now have a high-throughput review model for multi-agent task output.
Next: [Chapter 6: Remote Access and Self-Hosting](06-remote-access-and-self-hosting.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `npx-cli/src/desktop.ts`
+### `npx-cli/src/cli.ts`
-The `readSentinel` function in [`npx-cli/src/desktop.ts`](https://github.com/BloopAI/vibe-kanban/blob/HEAD/npx-cli/src/desktop.ts) handles a key part of this chapter's functionality:
+The `cleanOldVersions` function in [`npx-cli/src/cli.ts`](https://github.com/BloopAI/vibe-kanban/blob/HEAD/npx-cli/src/cli.ts) handles a key part of this chapter's functionality:
```ts
-}
-function readSentinel(dir: string): SentinelMeta | null {
- const sentinelPath = path.join(dir, '.installed');
- if (!fs.existsSync(sentinelPath)) return null;
+// Remove old version directories from the binary cache
+function cleanOldVersions(): void {
try {
- return JSON.parse(
- fs.readFileSync(sentinelPath, 'utf-8')
- ) as SentinelMeta;
+ const entries = fs.readdirSync(CACHE_DIR, {
+ withFileTypes: true,
+ });
+ for (const entry of entries) {
+ if (entry.isDirectory() && entry.name !== BINARY_TAG) {
+ const oldDir = path.join(CACHE_DIR, entry.name);
+ fs.rmSync(oldDir, { recursive: true, force: true });
+ }
+ }
} catch {
- return null;
+ // Ignore cleanup errors — not critical
}
}
-// Try to copy the .app to a destination directory, returning the final path on success
-function tryCopyApp(
- srcAppPath: string,
- destDir: string
-): string | null {
- try {
- const appName = path.basename(srcAppPath);
- const destAppPath = path.join(destDir, appName);
-
- // Ensure destination directory exists
- fs.mkdirSync(destDir, { recursive: true });
+function showProgress(downloaded: number, total: number): void {
+ const percent = total ? Math.round((downloaded / total) * 100) : 0;
+ const mb = (downloaded / (1024 * 1024)).toFixed(1);
+ const totalMb = total ? (total / (1024 * 1024)).toFixed(1) : "?";
+ process.stderr.write(
+ `\r Downloading: ${mb}MB / ${totalMb}MB (${percent}%)`,
+ );
+}
- // Remove existing app at destination if present
- if (fs.existsSync(destAppPath)) {
- fs.rmSync(destAppPath, { recursive: true, force: true });
- }
+function buildMcpArgs(args: string[]): string[] {
+ return args.length > 0 ? args : ["--mode", "global"];
+}
- // Use cp -R for macOS .app bundles (preserves symlinks and metadata)
+async function extractAndRun(
```
This function is important because it defines how Vibe Kanban Tutorial: Multi-Agent Orchestration Board for Coding Workflows implements the patterns covered in this chapter.
-### `npx-cli/src/desktop.ts`
+### `npx-cli/src/cli.ts`
-The `tryCopyApp` function in [`npx-cli/src/desktop.ts`](https://github.com/BloopAI/vibe-kanban/blob/HEAD/npx-cli/src/desktop.ts) handles a key part of this chapter's functionality:
+The `showProgress` function in [`npx-cli/src/cli.ts`](https://github.com/BloopAI/vibe-kanban/blob/HEAD/npx-cli/src/cli.ts) handles a key part of this chapter's functionality:
```ts
+}
-// Try to copy the .app to a destination directory, returning the final path on success
-function tryCopyApp(
- srcAppPath: string,
- destDir: string
-): string | null {
- try {
- const appName = path.basename(srcAppPath);
- const destAppPath = path.join(destDir, appName);
-
- // Ensure destination directory exists
- fs.mkdirSync(destDir, { recursive: true });
-
- // Remove existing app at destination if present
- if (fs.existsSync(destAppPath)) {
- fs.rmSync(destAppPath, { recursive: true, force: true });
- }
-
- // Use cp -R for macOS .app bundles (preserves symlinks and metadata)
- execSync(`cp -R "${srcAppPath}" "${destAppPath}"`, {
- stdio: 'pipe',
- });
+function showProgress(downloaded: number, total: number): void {
+ const percent = total ? Math.round((downloaded / total) * 100) : 0;
+ const mb = (downloaded / (1024 * 1024)).toFixed(1);
+ const totalMb = total ? (total / (1024 * 1024)).toFixed(1) : "?";
+ process.stderr.write(
+ `\r Downloading: ${mb}MB / ${totalMb}MB (${percent}%)`,
+ );
+}
- return destAppPath;
- } catch {
- return null;
- }
+function buildMcpArgs(args: string[]): string[] {
+ return args.length > 0 ? args : ["--mode", "global"];
}
-// macOS: extract .app.tar.gz, copy to /Applications, remove quarantine, launch with `open`
-async function installAndLaunchMacOS(
- bundleInfo: DesktopBundleInfo
+async function extractAndRun(
+ baseName: string,
+ launch: (binPath: string) => void,
+): Promise<void> {
+ const binName = getBinaryName(baseName);
+ const binPath = path.join(versionCacheDir, binName);
+ const zipPath = path.join(versionCacheDir, `${baseName}.zip`);
+
+ // Clean old binary if exists
+ try {
+ if (fs.existsSync(binPath)) {
+ fs.unlinkSync(binPath);
+ }
+ } catch (err: unknown) {
+ if (process.env.VIBE_KANBAN_DEBUG) {
+ const msg = err instanceof Error ? err.message : String(err);
+ console.warn(`Warning: Could not delete existing binary: ${msg}`);
```
This function is important because it defines how Vibe Kanban Tutorial: Multi-Agent Orchestration Board for Coding Workflows implements the patterns covered in this chapter.
-### `npx-cli/src/desktop.ts`
+### `npx-cli/src/cli.ts`
-The `installAndLaunchMacOS` function in [`npx-cli/src/desktop.ts`](https://github.com/BloopAI/vibe-kanban/blob/HEAD/npx-cli/src/desktop.ts) handles a key part of this chapter's functionality:
+The `buildMcpArgs` function in [`npx-cli/src/cli.ts`](https://github.com/BloopAI/vibe-kanban/blob/HEAD/npx-cli/src/cli.ts) handles a key part of this chapter's functionality:
```ts
+}
-// macOS: extract .app.tar.gz, copy to /Applications, remove quarantine, launch with `open`
-async function installAndLaunchMacOS(
- bundleInfo: DesktopBundleInfo
-): Promise<number> {
- const { archivePath, dir } = bundleInfo;
-
- const sentinel = readSentinel(dir);
- if (sentinel?.appPath && fs.existsSync(sentinel.appPath)) {
- return launchMacOSApp(sentinel.appPath);
- }
-
- if (!archivePath || !fs.existsSync(archivePath)) {
- throw new Error('No archive to extract for macOS desktop app');
- }
+function buildMcpArgs(args: string[]): string[] {
+ return args.length > 0 ? args : ["--mode", "global"];
+}
- extractTarGz(archivePath, dir);
+async function extractAndRun(
+ baseName: string,
+ launch: (binPath: string) => void,
+): Promise<void> {
+ const binName = getBinaryName(baseName);
+ const binPath = path.join(versionCacheDir, binName);
+ const zipPath = path.join(versionCacheDir, `${baseName}.zip`);
- const appName = fs.readdirSync(dir).find((f) => f.endsWith('.app'));
- if (!appName) {
- throw new Error(
- `No .app bundle found in ${dir} after extraction`
- );
+ // Clean old binary if exists
+ try {
+ if (fs.existsSync(binPath)) {
+ fs.unlinkSync(binPath);
+ }
+ } catch (err: unknown) {
+ if (process.env.VIBE_KANBAN_DEBUG) {
+ const msg = err instanceof Error ? err.message : String(err);
+ console.warn(`Warning: Could not delete existing binary: ${msg}`);
+ }
}
- const extractedAppPath = path.join(dir, appName);
-
- // Try to install to /Applications, then ~/Applications, then fall back to cache dir
- const userApplications = path.join(os.homedir(), 'Applications');
- const finalAppPath =
- tryCopyApp(extractedAppPath, '/Applications') ??
- tryCopyApp(extractedAppPath, userApplications) ??
+ // Download if not cached
+ if (!fs.existsSync(zipPath)) {
+ console.error(`Downloading ${baseName}...`);
+ try {
+ await ensureBinary(platformDir, baseName, showProgress);
+ console.error(""); // newline after progress
```
This function is important because it defines how Vibe Kanban Tutorial: Multi-Agent Orchestration Board for Coding Workflows implements the patterns covered in this chapter.
-### `npx-cli/src/desktop.ts`
+### `npx-cli/src/cli.ts`
-The `launchMacOSApp` function in [`npx-cli/src/desktop.ts`](https://github.com/BloopAI/vibe-kanban/blob/HEAD/npx-cli/src/desktop.ts) handles a key part of this chapter's functionality:
+The `extractAndRun` function in [`npx-cli/src/cli.ts`](https://github.com/BloopAI/vibe-kanban/blob/HEAD/npx-cli/src/cli.ts) handles a key part of this chapter's functionality:
```ts
- const sentinel = readSentinel(dir);
- if (sentinel?.appPath && fs.existsSync(sentinel.appPath)) {
- return launchMacOSApp(sentinel.appPath);
- }
-
- if (!archivePath || !fs.existsSync(archivePath)) {
- throw new Error('No archive to extract for macOS desktop app');
- }
+}
- extractTarGz(archivePath, dir);
+async function extractAndRun(
+ baseName: string,
+ launch: (binPath: string) => void,
+): Promise<void> {
+ const binName = getBinaryName(baseName);
+ const binPath = path.join(versionCacheDir, binName);
+ const zipPath = path.join(versionCacheDir, `${baseName}.zip`);
- const appName = fs.readdirSync(dir).find((f) => f.endsWith('.app'));
- if (!appName) {
- throw new Error(
- `No .app bundle found in ${dir} after extraction`
- );
+ // Clean old binary if exists
+ try {
+ if (fs.existsSync(binPath)) {
+ fs.unlinkSync(binPath);
+ }
+ } catch (err: unknown) {
+ if (process.env.VIBE_KANBAN_DEBUG) {
+ const msg = err instanceof Error ? err.message : String(err);
+ console.warn(`Warning: Could not delete existing binary: ${msg}`);
+ }
}
- const extractedAppPath = path.join(dir, appName);
-
- // Try to install to /Applications, then ~/Applications, then fall back to cache dir
- const userApplications = path.join(os.homedir(), 'Applications');
- const finalAppPath =
- tryCopyApp(extractedAppPath, '/Applications') ??
- tryCopyApp(extractedAppPath, userApplications) ??
- extractedAppPath;
-
- // Clean up extracted copy if we successfully copied elsewhere
- if (finalAppPath !== extractedAppPath) {
+ // Download if not cached
+ if (!fs.existsSync(zipPath)) {
+ console.error(`Downloading ${baseName}...`);
try {
- fs.rmSync(extractedAppPath, { recursive: true, force: true });
- } catch {}
+ await ensureBinary(platformDir, baseName, showProgress);
+ console.error(""); // newline after progress
+ } catch (err: unknown) {
+ const msg = err instanceof Error ? err.message : String(err);
+ console.error(`\nDownload failed: ${msg}`);
+ process.exit(1);
```
This function is important because it defines how Vibe Kanban Tutorial: Multi-Agent Orchestration Board for Coding Workflows implements the patterns covered in this chapter.
@@ -218,11 +216,11 @@ This function is important because it defines how Vibe Kanban Tutorial: Multi-Ag
```mermaid
flowchart TD
- A[readSentinel]
- B[tryCopyApp]
- C[installAndLaunchMacOS]
- D[launchMacOSApp]
- E[installAndLaunchLinux]
+ A[cleanOldVersions]
+ B[showProgress]
+ C[buildMcpArgs]
+ D[extractAndRun]
+ E[checkForUpdates]
A --> B
B --> C
C --> D
diff --git a/tutorials/vibe-kanban-tutorial/06-remote-access-and-self-hosting.md b/tutorials/vibe-kanban-tutorial/06-remote-access-and-self-hosting.md
index 30373e2f..7510cdee 100644
--- a/tutorials/vibe-kanban-tutorial/06-remote-access-and-self-hosting.md
+++ b/tutorials/vibe-kanban-tutorial/06-remote-access-and-self-hosting.md
@@ -40,163 +40,168 @@ You now know how to run Vibe Kanban beyond a single local machine safely.
Next: [Chapter 7: Development and Source Build Workflow](07-development-and-source-build-workflow.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `npx-cli/src/desktop.ts`
+### `npx-cli/src/cli.ts`
-The `installAndLaunch` function in [`npx-cli/src/desktop.ts`](https://github.com/BloopAI/vibe-kanban/blob/HEAD/npx-cli/src/desktop.ts) handles a key part of this chapter's functionality:
+The `normalizeArgv` function in [`npx-cli/src/cli.ts`](https://github.com/BloopAI/vibe-kanban/blob/HEAD/npx-cli/src/cli.ts) handles a key part of this chapter's functionality:
```ts
+}
-// macOS: extract .app.tar.gz, copy to /Applications, remove quarantine, launch with `open`
-async function installAndLaunchMacOS(
- bundleInfo: DesktopBundleInfo
-): Promise<number> {
- const { archivePath, dir } = bundleInfo;
-
- const sentinel = readSentinel(dir);
- if (sentinel?.appPath && fs.existsSync(sentinel.appPath)) {
- return launchMacOSApp(sentinel.appPath);
- }
-
- if (!archivePath || !fs.existsSync(archivePath)) {
- throw new Error('No archive to extract for macOS desktop app');
+function normalizeArgv(argv: string[]): string[] {
+ const args = argv.slice(2);
+ const mcpFlagIndex = args.indexOf("--mcp");
+ if (mcpFlagIndex === -1) {
+ return argv;
}
- extractTarGz(archivePath, dir);
+ const normalizedArgs = [
+ ...args.slice(0, mcpFlagIndex),
+ "mcp",
+ ...args.slice(mcpFlagIndex + 1),
+ ];
- const appName = fs.readdirSync(dir).find((f) => f.endsWith('.app'));
- if (!appName) {
- throw new Error(
- `No .app bundle found in ${dir} after extraction`
- );
- }
+ return [...argv.slice(0, 2), ...normalizedArgs];
+}
- const extractedAppPath = path.join(dir, appName);
+function runOrExit(task: Promise<void>): void {
+ void task.catch((err: unknown) => {
+ const msg = err instanceof Error ? err.message : String(err);
+ console.error("Fatal error:", msg);
+ if (process.env.VIBE_KANBAN_DEBUG && err instanceof Error) {
+ console.error(err.stack);
+ }
+ process.exit(1);
+ });
+}
- // Try to install to /Applications, then ~/Applications, then fall back to cache dir
- const userApplications = path.join(os.homedir(), 'Applications');
- const finalAppPath =
- tryCopyApp(extractedAppPath, '/Applications') ??
- tryCopyApp(extractedAppPath, userApplications) ??
+async function main(): Promise<void> {
+ fs.mkdirSync(versionCacheDir, { recursive: true });
+ const cli = cac("vibe-kanban");
```
This function is important because it defines how Vibe Kanban Tutorial: Multi-Agent Orchestration Board for Coding Workflows implements the patterns covered in this chapter.
-### `npx-cli/src/desktop.ts`
+### `npx-cli/src/cli.ts`
-The `cleanOldDesktopVersions` function in [`npx-cli/src/desktop.ts`](https://github.com/BloopAI/vibe-kanban/blob/HEAD/npx-cli/src/desktop.ts) handles a key part of this chapter's functionality:
+The `runOrExit` function in [`npx-cli/src/cli.ts`](https://github.com/BloopAI/vibe-kanban/blob/HEAD/npx-cli/src/cli.ts) handles a key part of this chapter's functionality:
```ts
}
-export function cleanOldDesktopVersions(
- desktopBaseDir: string,
- currentTag: string
-): void {
- try {
- const entries = fs.readdirSync(desktopBaseDir, {
- withFileTypes: true,
- });
- for (const entry of entries) {
- if (entry.isDirectory() && entry.name !== currentTag) {
- const oldDir = path.join(desktopBaseDir, entry.name);
- try {
- fs.rmSync(oldDir, { recursive: true, force: true });
- } catch {
- // Ignore errors (e.g. EBUSY on Windows if app is running)
- }
- }
+function runOrExit(task: Promise<void>): void {
+ void task.catch((err: unknown) => {
+ const msg = err instanceof Error ? err.message : String(err);
+ console.error("Fatal error:", msg);
+ if (process.env.VIBE_KANBAN_DEBUG && err instanceof Error) {
+ console.error(err.stack);
}
- } catch {
- // Ignore cleanup errors
- }
+ process.exit(1);
+ });
}
+async function main(): Promise<void> {
+ fs.mkdirSync(versionCacheDir, { recursive: true });
+ const cli = cac("vibe-kanban");
+
+ cli
+ .command("[...args]", "Launch the local vibe-kanban app")
+ .option("--desktop", "Launch the desktop app instead of browser mode")
+ .allowUnknownOptions()
+ .action((_args: string[], options: RootOptions) => {
+ runOrExit(runMain(Boolean(options.desktop)));
+ });
+
+ cli
+ .command("review [...args]", "Run the review CLI")
+ .allowUnknownOptions()
+ .action((args: string[]) => {
+ runOrExit(runReview(args));
+ });
+
```
This function is important because it defines how Vibe Kanban Tutorial: Multi-Agent Orchestration Board for Coding Workflows implements the patterns covered in this chapter.
-### `npx-cli/src/desktop.ts`
+### `npx-cli/src/cli.ts`
-The `SentinelMeta` interface in [`npx-cli/src/desktop.ts`](https://github.com/BloopAI/vibe-kanban/blob/HEAD/npx-cli/src/desktop.ts) handles a key part of this chapter's functionality:
+The `main` function in [`npx-cli/src/cli.ts`](https://github.com/BloopAI/vibe-kanban/blob/HEAD/npx-cli/src/cli.ts) handles a key part of this chapter's functionality:
```ts
-type TauriPlatform = string | null;
-
-interface SentinelMeta {
- type: string;
- appPath: string;
}
-const PLATFORM_MAP: Record<string, string> = {
- 'macos-arm64': 'darwin-aarch64',
- 'macos-x64': 'darwin-x86_64',
- 'linux-x64': 'linux-x86_64',
- 'linux-arm64': 'linux-aarch64',
- 'windows-x64': 'windows-x86_64',
- 'windows-arm64': 'windows-aarch64',
-};
-
-// Map NPX-style platform names to Tauri-style platform names
-export function getTauriPlatform(
- npxPlatformDir: string
-): TauriPlatform {
- return PLATFORM_MAP[npxPlatformDir] || null;
-}
+async function main(): Promise<void> {
+ fs.mkdirSync(versionCacheDir, { recursive: true });
+ const cli = cac("vibe-kanban");
-// Extract .tar.gz using system tar (available on macOS, Linux, and Windows 10+)
-function extractTarGz(archivePath: string, destDir: string): void {
- execSync(`tar -xzf "${archivePath}" -C "${destDir}"`, {
- stdio: 'pipe',
- });
-}
+ cli
+ .command("[...args]", "Launch the local vibe-kanban app")
+ .option("--desktop", "Launch the desktop app instead of browser mode")
+ .allowUnknownOptions()
+ .action((_args: string[], options: RootOptions) => {
+ runOrExit(runMain(Boolean(options.desktop)));
+ });
-function writeSentinel(dir: string, meta: SentinelMeta): void {
- fs.writeFileSync(
-```
+ cli
+ .command("review [...args]", "Run the review CLI")
+ .allowUnknownOptions()
+ .action((args: string[]) => {
+ runOrExit(runReview(args));
+ });
-This interface is important because it defines how Vibe Kanban Tutorial: Multi-Agent Orchestration Board for Coding Workflows implements the patterns covered in this chapter.
+ cli
+ .command("mcp [...args]", "Run the MCP server")
+ .allowUnknownOptions()
+ .action((args: string[]) => {
+ runOrExit(runMcp(args));
+ });
-### `packages/local-web/tailwind.new.config.js`
+ cli.help();
+ cli.version(CLI_VERSION);
+ cli.parse(normalizeArgv(process.argv));
+}
+```
-The `getSize` function in [`packages/local-web/tailwind.new.config.js`](https://github.com/BloopAI/vibe-kanban/blob/HEAD/packages/local-web/tailwind.new.config.js) handles a key part of this chapter's functionality:
+This function is important because it defines how Vibe Kanban Tutorial: Multi-Agent Orchestration Board for Coding Workflows implements the patterns covered in this chapter.
-```js
-const chatMaxWidth = '48rem';
+### `npx-cli/src/download.ts`
-function getSize(sizeLabel, multiplier = 1) {
+The `downloadFile` function in [`npx-cli/src/download.ts`](https://github.com/BloopAI/vibe-kanban/blob/HEAD/npx-cli/src/download.ts) handles a key part of this chapter's functionality:
- return sizes[sizeLabel] * multiplier + "rem";
+```ts
}
-module.exports = {
- darkMode: ["class"],
- important: false,
- content: [
- './pages/**/*.{ts,tsx}',
- './components/**/*.{ts,tsx}',
- './app/**/*.{ts,tsx}',
- './src/**/*.{ts,tsx}',
- '../web-core/src/**/*.{ts,tsx}',
- '../remote-web/src/**/*.{ts,tsx}',
- '../ui/src/**/*.{ts,tsx}',
- "node_modules/@rjsf/shadcn/src/**/*.{js,ts,jsx,tsx,mdx}"
- ],
- safelist: [
- 'xl:hidden',
- 'xl:relative',
- 'xl:inset-auto',
- 'xl:z-auto',
- 'xl:h-full',
- 'xl:w-[800px]',
- 'xl:flex',
- 'xl:flex-1',
- 'xl:min-w-0',
- 'xl:overflow-y-auto',
- 'xl:opacity-100',
+function downloadFile(
+ url: string,
+ destPath: string,
+ expectedSha256: string | undefined,
+ onProgress?: ProgressCallback
+): Promise<string> {
+ const tempPath = destPath + '.tmp';
+ return new Promise((resolve, reject) => {
+ const file = fs.createWriteStream(tempPath);
+ const hash = crypto.createHash('sha256');
+
+ const cleanup = () => {
+ try {
+ fs.unlinkSync(tempPath);
+ } catch {}
+ };
+
+ https
+ .get(url, (res) => {
+ if (res.statusCode === 301 || res.statusCode === 302) {
+ file.close();
+ cleanup();
+ return downloadFile(
+ res.headers.location!,
+ destPath,
+ expectedSha256,
+ onProgress
+ )
+ .then(resolve)
+ .catch(reject);
```
This function is important because it defines how Vibe Kanban Tutorial: Multi-Agent Orchestration Board for Coding Workflows implements the patterns covered in this chapter.
@@ -206,11 +211,11 @@ This function is important because it defines how Vibe Kanban Tutorial: Multi-Ag
```mermaid
flowchart TD
- A[installAndLaunch]
- B[cleanOldDesktopVersions]
- C[SentinelMeta]
- D[getSize]
- E[downloadFile]
+ A[normalizeArgv]
+ B[runOrExit]
+ C[main]
+ D[downloadFile]
+ E[ensureBinary]
A --> B
B --> C
C --> D
diff --git a/tutorials/vibe-kanban-tutorial/07-development-and-source-build-workflow.md b/tutorials/vibe-kanban-tutorial/07-development-and-source-build-workflow.md
index 3a090125..6ef2910a 100644
--- a/tutorials/vibe-kanban-tutorial/07-development-and-source-build-workflow.md
+++ b/tutorials/vibe-kanban-tutorial/07-development-and-source-build-workflow.md
@@ -52,20 +52,13 @@ You now have a contributor-ready workflow for iterating on Vibe Kanban itself.
Next: [Chapter 8: Production Operations and Governance](08-production-operations-and-governance.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `npx-cli/src/download.ts`
-The `BinaryInfo` interface in [`npx-cli/src/download.ts`](https://github.com/BloopAI/vibe-kanban/blob/HEAD/npx-cli/src/download.ts) handles a key part of this chapter's functionality:
+The `BinaryManifest` interface in [`npx-cli/src/download.ts`](https://github.com/BloopAI/vibe-kanban/blob/HEAD/npx-cli/src/download.ts) handles a key part of this chapter's functionality:
```ts
- process.env.VIBE_KANBAN_LOCAL === '1';
-
-export interface BinaryInfo {
- sha256: string;
- size: number;
}
export interface BinaryManifest {
@@ -93,22 +86,22 @@ type ProgressCallback = (downloaded: number, total: number) => void;
function fetchJson<T>(url: string): Promise<T> {
return new Promise((resolve, reject) => {
+ https
+ .get(url, (res) => {
+ if (res.statusCode === 301 || res.statusCode === 302) {
+ return fetchJson<T>(res.headers.location!)
+ .then(resolve)
```
This interface is important because it defines how Vibe Kanban Tutorial: Multi-Agent Orchestration Board for Coding Workflows implements the patterns covered in this chapter.
### `npx-cli/src/download.ts`
-The `BinaryManifest` interface in [`npx-cli/src/download.ts`](https://github.com/BloopAI/vibe-kanban/blob/HEAD/npx-cli/src/download.ts) handles a key part of this chapter's functionality:
+The `DesktopPlatformInfo` interface in [`npx-cli/src/download.ts`](https://github.com/BloopAI/vibe-kanban/blob/HEAD/npx-cli/src/download.ts) handles a key part of this chapter's functionality:
```ts
}
-export interface BinaryManifest {
- latest?: string;
- platforms: Record<string, Record<string, BinaryInfo>>;
-}
-
export interface DesktopPlatformInfo {
file: string;
sha256: string;
@@ -134,23 +127,22 @@ function fetchJson<T>(url: string): Promise<T> {
if (res.statusCode === 301 || res.statusCode === 302) {
return fetchJson<T>(res.headers.location!)
.then(resolve)
+ .catch(reject);
+ }
+ if (res.statusCode !== 200) {
+ return reject(new Error(`HTTP ${res.statusCode} fetching ${url}`));
+ }
```
This interface is important because it defines how Vibe Kanban Tutorial: Multi-Agent Orchestration Board for Coding Workflows implements the patterns covered in this chapter.
### `npx-cli/src/download.ts`
-The `DesktopPlatformInfo` interface in [`npx-cli/src/download.ts`](https://github.com/BloopAI/vibe-kanban/blob/HEAD/npx-cli/src/download.ts) handles a key part of this chapter's functionality:
+The `DesktopManifest` interface in [`npx-cli/src/download.ts`](https://github.com/BloopAI/vibe-kanban/blob/HEAD/npx-cli/src/download.ts) handles a key part of this chapter's functionality:
```ts
}
-export interface DesktopPlatformInfo {
- file: string;
- sha256: string;
- type: string | null;
-}
-
export interface DesktopManifest {
platforms: Record<string, DesktopPlatformInfo>;
}
@@ -175,21 +167,23 @@ function fetchJson<T>(url: string): Promise<T> {
if (res.statusCode !== 200) {
return reject(new Error(`HTTP ${res.statusCode} fetching ${url}`));
}
+ let data = '';
+ res.on('data', (chunk: string) => (data += chunk));
+ res.on('end', () => {
+ try {
+ resolve(JSON.parse(data) as T);
+ } catch {
```
This interface is important because it defines how Vibe Kanban Tutorial: Multi-Agent Orchestration Board for Coding Workflows implements the patterns covered in this chapter.
### `npx-cli/src/download.ts`
-The `DesktopManifest` interface in [`npx-cli/src/download.ts`](https://github.com/BloopAI/vibe-kanban/blob/HEAD/npx-cli/src/download.ts) handles a key part of this chapter's functionality:
+The `DesktopBundleInfo` interface in [`npx-cli/src/download.ts`](https://github.com/BloopAI/vibe-kanban/blob/HEAD/npx-cli/src/download.ts) handles a key part of this chapter's functionality:
```ts
}
-export interface DesktopManifest {
- platforms: Record<string, DesktopPlatformInfo>;
-}
-
export interface DesktopBundleInfo {
archivePath: string | null;
dir: string;
@@ -216,6 +210,10 @@ function fetchJson<T>(url: string): Promise<T> {
try {
resolve(JSON.parse(data) as T);
} catch {
+ reject(new Error(`Failed to parse JSON from ${url}`));
+ }
+ });
+ })
```
This interface is important because it defines how Vibe Kanban Tutorial: Multi-Agent Orchestration Board for Coding Workflows implements the patterns covered in this chapter.
@@ -225,11 +223,11 @@ This interface is important because it defines how Vibe Kanban Tutorial: Multi-A
```mermaid
flowchart TD
- A[BinaryInfo]
- B[BinaryManifest]
- C[DesktopPlatformInfo]
- D[DesktopManifest]
- E[DesktopBundleInfo]
+ A[BinaryManifest]
+ B[DesktopPlatformInfo]
+ C[DesktopManifest]
+ D[DesktopBundleInfo]
+ E[getTauriPlatform]
A --> B
B --> C
C --> D
diff --git a/tutorials/vibe-kanban-tutorial/08-production-operations-and-governance.md b/tutorials/vibe-kanban-tutorial/08-production-operations-and-governance.md
index 5a3f16d3..f248435d 100644
--- a/tutorials/vibe-kanban-tutorial/08-production-operations-and-governance.md
+++ b/tutorials/vibe-kanban-tutorial/08-production-operations-and-governance.md
@@ -42,170 +42,168 @@ You now have a full operational runbook for managing coding-agent orchestration
Continue with the [Opcode Tutorial](../opcode-tutorial/) for GUI-native Claude Code workflows.
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `npx-cli/src/cli.ts`
+### `npx-cli/src/desktop.ts`
-The `cleanOldVersions` function in [`npx-cli/src/cli.ts`](https://github.com/BloopAI/vibe-kanban/blob/HEAD/npx-cli/src/cli.ts) handles a key part of this chapter's functionality:
+The `tryCopyApp` function in [`npx-cli/src/desktop.ts`](https://github.com/BloopAI/vibe-kanban/blob/HEAD/npx-cli/src/desktop.ts) handles a key part of this chapter's functionality:
```ts
-// Remove old version directories from the binary cache
-function cleanOldVersions(): void {
+// Try to copy the .app to a destination directory, returning the final path on success
+function tryCopyApp(
+ srcAppPath: string,
+ destDir: string
+): string | null {
try {
- const entries = fs.readdirSync(CACHE_DIR, {
- withFileTypes: true,
- });
- for (const entry of entries) {
- if (entry.isDirectory() && entry.name !== BINARY_TAG) {
- const oldDir = path.join(CACHE_DIR, entry.name);
- fs.rmSync(oldDir, { recursive: true, force: true });
- }
+ const appName = path.basename(srcAppPath);
+ const destAppPath = path.join(destDir, appName);
+
+ // Ensure destination directory exists
+ fs.mkdirSync(destDir, { recursive: true });
+
+ // Remove existing app at destination if present
+ if (fs.existsSync(destAppPath)) {
+ fs.rmSync(destAppPath, { recursive: true, force: true });
}
- } catch {
- // Ignore cleanup errors — not critical
- }
-}
-function showProgress(downloaded: number, total: number): void {
- const percent = total ? Math.round((downloaded / total) * 100) : 0;
- const mb = (downloaded / (1024 * 1024)).toFixed(1);
- const totalMb = total ? (total / (1024 * 1024)).toFixed(1) : "?";
- process.stderr.write(
- `\r Downloading: ${mb}MB / ${totalMb}MB (${percent}%)`,
- );
-}
+ // Use cp -R for macOS .app bundles (preserves symlinks and metadata)
+ execSync(`cp -R "${srcAppPath}" "${destAppPath}"`, {
+ stdio: 'pipe',
+ });
-function buildMcpArgs(args: string[]): string[] {
- return args.length > 0 ? args : ["--mode", "global"];
+ return destAppPath;
+ } catch {
+ return null;
+ }
}
-async function extractAndRun(
+// macOS: extract .app.tar.gz, copy to /Applications, remove quarantine, launch with `open`
+async function installAndLaunchMacOS(
+ bundleInfo: DesktopBundleInfo
```
This function is important because it defines how Vibe Kanban Tutorial: Multi-Agent Orchestration Board for Coding Workflows implements the patterns covered in this chapter.
-### `npx-cli/src/cli.ts`
+### `npx-cli/src/desktop.ts`
-The `showProgress` function in [`npx-cli/src/cli.ts`](https://github.com/BloopAI/vibe-kanban/blob/HEAD/npx-cli/src/cli.ts) handles a key part of this chapter's functionality:
+The `installAndLaunchMacOS` function in [`npx-cli/src/desktop.ts`](https://github.com/BloopAI/vibe-kanban/blob/HEAD/npx-cli/src/desktop.ts) handles a key part of this chapter's functionality:
```ts
-}
-function showProgress(downloaded: number, total: number): void {
- const percent = total ? Math.round((downloaded / total) * 100) : 0;
- const mb = (downloaded / (1024 * 1024)).toFixed(1);
- const totalMb = total ? (total / (1024 * 1024)).toFixed(1) : "?";
- process.stderr.write(
- `\r Downloading: ${mb}MB / ${totalMb}MB (${percent}%)`,
- );
-}
+// macOS: extract .app.tar.gz, copy to /Applications, remove quarantine, launch with `open`
+async function installAndLaunchMacOS(
+ bundleInfo: DesktopBundleInfo
+): Promise<number> {
+ const { archivePath, dir } = bundleInfo;
-function buildMcpArgs(args: string[]): string[] {
- return args.length > 0 ? args : ["--mode", "global"];
-}
+ const sentinel = readSentinel(dir);
+ if (sentinel?.appPath && fs.existsSync(sentinel.appPath)) {
+ return launchMacOSApp(sentinel.appPath);
+ }
+
+ if (!archivePath || !fs.existsSync(archivePath)) {
+ throw new Error('No archive to extract for macOS desktop app');
+ }
-async function extractAndRun(
- baseName: string,
- launch: (binPath: string) => void,
-): Promise<void> {
- const binName = getBinaryName(baseName);
- const binPath = path.join(versionCacheDir, binName);
- const zipPath = path.join(versionCacheDir, `${baseName}.zip`);
+ extractTarGz(archivePath, dir);
- // Clean old binary if exists
- try {
- if (fs.existsSync(binPath)) {
- fs.unlinkSync(binPath);
- }
- } catch (err: unknown) {
- if (process.env.VIBE_KANBAN_DEBUG) {
- const msg = err instanceof Error ? err.message : String(err);
- console.warn(`Warning: Could not delete existing binary: ${msg}`);
+ const appName = fs.readdirSync(dir).find((f) => f.endsWith('.app'));
+ if (!appName) {
+ throw new Error(
+ `No .app bundle found in ${dir} after extraction`
+ );
+ }
+
+ const extractedAppPath = path.join(dir, appName);
+
+ // Try to install to /Applications, then ~/Applications, then fall back to cache dir
+ const userApplications = path.join(os.homedir(), 'Applications');
+ const finalAppPath =
+ tryCopyApp(extractedAppPath, '/Applications') ??
+ tryCopyApp(extractedAppPath, userApplications) ??
```
This function is important because it defines how Vibe Kanban Tutorial: Multi-Agent Orchestration Board for Coding Workflows implements the patterns covered in this chapter.
-### `npx-cli/src/cli.ts`
+### `npx-cli/src/desktop.ts`
-The `buildMcpArgs` function in [`npx-cli/src/cli.ts`](https://github.com/BloopAI/vibe-kanban/blob/HEAD/npx-cli/src/cli.ts) handles a key part of this chapter's functionality:
+The `launchMacOSApp` function in [`npx-cli/src/desktop.ts`](https://github.com/BloopAI/vibe-kanban/blob/HEAD/npx-cli/src/desktop.ts) handles a key part of this chapter's functionality:
```ts
-}
+ const sentinel = readSentinel(dir);
+ if (sentinel?.appPath && fs.existsSync(sentinel.appPath)) {
+ return launchMacOSApp(sentinel.appPath);
+ }
-function buildMcpArgs(args: string[]): string[] {
- return args.length > 0 ? args : ["--mode", "global"];
-}
+ if (!archivePath || !fs.existsSync(archivePath)) {
+ throw new Error('No archive to extract for macOS desktop app');
+ }
-async function extractAndRun(
- baseName: string,
- launch: (binPath: string) => void,
-): Promise<void> {
- const binName = getBinaryName(baseName);
- const binPath = path.join(versionCacheDir, binName);
- const zipPath = path.join(versionCacheDir, `${baseName}.zip`);
+ extractTarGz(archivePath, dir);
- // Clean old binary if exists
- try {
- if (fs.existsSync(binPath)) {
- fs.unlinkSync(binPath);
- }
- } catch (err: unknown) {
- if (process.env.VIBE_KANBAN_DEBUG) {
- const msg = err instanceof Error ? err.message : String(err);
- console.warn(`Warning: Could not delete existing binary: ${msg}`);
- }
+ const appName = fs.readdirSync(dir).find((f) => f.endsWith('.app'));
+ if (!appName) {
+ throw new Error(
+ `No .app bundle found in ${dir} after extraction`
+ );
}
- // Download if not cached
- if (!fs.existsSync(zipPath)) {
- console.error(`Downloading ${baseName}...`);
+ const extractedAppPath = path.join(dir, appName);
+
+ // Try to install to /Applications, then ~/Applications, then fall back to cache dir
+ const userApplications = path.join(os.homedir(), 'Applications');
+ const finalAppPath =
+ tryCopyApp(extractedAppPath, '/Applications') ??
+ tryCopyApp(extractedAppPath, userApplications) ??
+ extractedAppPath;
+
+ // Clean up extracted copy if we successfully copied elsewhere
+ if (finalAppPath !== extractedAppPath) {
try {
- await ensureBinary(platformDir, baseName, showProgress);
- console.error(""); // newline after progress
+ fs.rmSync(extractedAppPath, { recursive: true, force: true });
+ } catch {}
```
This function is important because it defines how Vibe Kanban Tutorial: Multi-Agent Orchestration Board for Coding Workflows implements the patterns covered in this chapter.
-### `npx-cli/src/cli.ts`
+### `npx-cli/src/desktop.ts`
-The `extractAndRun` function in [`npx-cli/src/cli.ts`](https://github.com/BloopAI/vibe-kanban/blob/HEAD/npx-cli/src/cli.ts) handles a key part of this chapter's functionality:
+The `installAndLaunchLinux` function in [`npx-cli/src/desktop.ts`](https://github.com/BloopAI/vibe-kanban/blob/HEAD/npx-cli/src/desktop.ts) handles a key part of this chapter's functionality:
```ts
-}
-async function extractAndRun(
- baseName: string,
- launch: (binPath: string) => void,
-): Promise<void> {
- const binName = getBinaryName(baseName);
- const binPath = path.join(versionCacheDir, binName);
- const zipPath = path.join(versionCacheDir, `${baseName}.zip`);
+// Linux: extract AppImage.tar.gz, chmod +x, run
+async function installAndLaunchLinux(
+ bundleInfo: DesktopBundleInfo
+): Promise<number> {
+ const { archivePath, dir } = bundleInfo;
- // Clean old binary if exists
- try {
- if (fs.existsSync(binPath)) {
- fs.unlinkSync(binPath);
- }
- } catch (err: unknown) {
- if (process.env.VIBE_KANBAN_DEBUG) {
- const msg = err instanceof Error ? err.message : String(err);
- console.warn(`Warning: Could not delete existing binary: ${msg}`);
- }
+ const sentinel = readSentinel(dir);
+ if (sentinel?.appPath && fs.existsSync(sentinel.appPath)) {
+ return launchLinuxAppImage(sentinel.appPath);
}
- // Download if not cached
- if (!fs.existsSync(zipPath)) {
- console.error(`Downloading ${baseName}...`);
- try {
- await ensureBinary(platformDir, baseName, showProgress);
- console.error(""); // newline after progress
- } catch (err: unknown) {
- const msg = err instanceof Error ? err.message : String(err);
- console.error(`\nDownload failed: ${msg}`);
- process.exit(1);
+ if (!archivePath || !fs.existsSync(archivePath)) {
+ throw new Error('No archive to extract for Linux desktop app');
+ }
+
+ extractTarGz(archivePath, dir);
+
+ const appImage = fs
+ .readdirSync(dir)
+ .find((f) => f.endsWith('.AppImage'));
+ if (!appImage) {
+ throw new Error(`No .AppImage found in ${dir} after extraction`);
+ }
+
+ const appImagePath = path.join(dir, appImage);
+ fs.chmodSync(appImagePath, 0o755);
+
+ writeSentinel(dir, {
+ type: 'appimage-tar-gz',
+ appPath: appImagePath,
+ });
```
This function is important because it defines how Vibe Kanban Tutorial: Multi-Agent Orchestration Board for Coding Workflows implements the patterns covered in this chapter.
@@ -215,11 +213,11 @@ This function is important because it defines how Vibe Kanban Tutorial: Multi-Ag
```mermaid
flowchart TD
- A[cleanOldVersions]
- B[showProgress]
- C[buildMcpArgs]
- D[extractAndRun]
- E[checkForUpdates]
+ A[tryCopyApp]
+ B[installAndLaunchMacOS]
+ C[launchMacOSApp]
+ D[installAndLaunchLinux]
+ E[launchLinuxAppImage]
A --> B
B --> C
C --> D
diff --git a/tutorials/vibesdk-tutorial/01-getting-started-and-deployment-paths.md b/tutorials/vibesdk-tutorial/01-getting-started-and-deployment-paths.md
index 125cc280..3f655417 100644
--- a/tutorials/vibesdk-tutorial/01-getting-started-and-deployment-paths.md
+++ b/tutorials/vibesdk-tutorial/01-getting-started-and-deployment-paths.md
@@ -107,8 +107,6 @@ You now have a practical bootstrap playbook for VibeSDK and a clear path from lo
Next: [Chapter 2: System Architecture](02-system-architecture.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `worker-configuration.d.ts`
diff --git a/tutorials/vibesdk-tutorial/02-system-architecture.md b/tutorials/vibesdk-tutorial/02-system-architecture.md
index d2712674..12a2b717 100644
--- a/tutorials/vibesdk-tutorial/02-system-architecture.md
+++ b/tutorials/vibesdk-tutorial/02-system-architecture.md
@@ -96,8 +96,6 @@ You now have a clear system map for VibeSDK and can reason about where to implem
Next: [Chapter 3: AI Pipeline and Phase Engine](03-ai-pipeline-and-phase-engine.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `container/cli-tools.ts`
diff --git a/tutorials/vibesdk-tutorial/03-ai-pipeline-and-phase-engine.md b/tutorials/vibesdk-tutorial/03-ai-pipeline-and-phase-engine.md
index 58857934..10c464df 100644
--- a/tutorials/vibesdk-tutorial/03-ai-pipeline-and-phase-engine.md
+++ b/tutorials/vibesdk-tutorial/03-ai-pipeline-and-phase-engine.md
@@ -92,8 +92,6 @@ You now understand how VibeSDK decomposes app generation into controllable phase
Next: [Chapter 4: Sandbox and Preview Runtime](04-sandbox-and-preview-runtime.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `container/cli-tools.ts`
@@ -269,7 +267,7 @@ flowchart TD
B[handleProcessCommand]
C[handleErrorCommand]
D[handleLogCommand]
- E[ContentType]
+ E[StorageManager]
A --> B
B --> C
C --> D
diff --git a/tutorials/vibesdk-tutorial/04-sandbox-and-preview-runtime.md b/tutorials/vibesdk-tutorial/04-sandbox-and-preview-runtime.md
index a2b91e2d..5e51020f 100644
--- a/tutorials/vibesdk-tutorial/04-sandbox-and-preview-runtime.md
+++ b/tutorials/vibesdk-tutorial/04-sandbox-and-preview-runtime.md
@@ -87,170 +87,168 @@ You now have a runtime model for sandbox previews and a practical baseline for s
Next: [Chapter 5: Data Layer and Persistence](05-data-layer-and-persistence.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `debug-tools/ai_request_analyzer_v2.py`
-
-The `class` class in [`debug-tools/ai_request_analyzer_v2.py`](https://github.com/cloudflare/vibesdk/blob/HEAD/debug-tools/ai_request_analyzer_v2.py) handles a key part of this chapter's functionality:
-
-```py
-import sys
-import re
-from dataclasses import dataclass, field
-from typing import Dict, List, Any, Optional, Tuple, Union, TypedDict, Protocol
-from pathlib import Path
-import argparse
-from collections import defaultdict, Counter
-import math
-from enum import Enum
-from abc import ABC, abstractmethod
-
-
-class ContentType(Enum):
- """Enumeration for content types."""
- SOURCE_CODE = "source_code"
- JSON_DATA = "json_data"
- MARKDOWN_STRUCTURED = "markdown_structured"
- LARGE_TEXT = "large_text"
- METADATA = "metadata"
- PROSE = "prose"
-
-
-class ComponentName(Enum):
- """Enumeration for component names."""
- ROLE_SECTION = "role_section"
- GOAL_SECTION = "goal_section"
- CONTEXT_SECTION = "context_section"
- CLIENT_REQUEST = "client_request"
- BLUEPRINT = "blueprint"
- DEPENDENCIES = "dependencies"
- UI_GUIDELINES = "ui_guidelines"
- STRATEGY = "strategy"
+### `scripts/undeploy.ts`
+
+The `WranglerConfig` interface in [`scripts/undeploy.ts`](https://github.com/cloudflare/vibesdk/blob/HEAD/scripts/undeploy.ts) handles a key part of this chapter's functionality:
+
+```ts
+
+// Types for configuration
+interface WranglerConfig {
+ name: string;
+ dispatch_namespaces?: Array<{
+ binding: string;
+ namespace: string;
+ experimental_remote?: boolean;
+ }>;
+ r2_buckets?: Array<{
+ binding: string;
+ bucket_name: string;
+ experimental_remote?: boolean;
+ }>;
+ containers?: Array<{
+ class_name: string;
+ image: string;
+ max_instances: number;
+ }>;
+ d1_databases?: Array<{
+ binding: string;
+ database_name: string;
+ database_id: string;
+ migrations_dir?: string;
+ experimental_remote?: boolean;
+ }>;
+ kv_namespaces?: Array<{
+ binding: string;
+ id: string;
+ experimental_remote?: boolean;
+ }>;
+}
```
-This class is important because it defines how VibeSDK Tutorial: Build a Vibe-Coding Platform on Cloudflare implements the patterns covered in this chapter.
+This interface is important because it defines how VibeSDK Tutorial: Build a Vibe-Coding Platform on Cloudflare implements the patterns covered in this chapter.
-### `debug-tools/ai_request_analyzer_v2.py`
+### `debug-tools/state_analyzer.py`
-The `class` class in [`debug-tools/ai_request_analyzer_v2.py`](https://github.com/cloudflare/vibesdk/blob/HEAD/debug-tools/ai_request_analyzer_v2.py) handles a key part of this chapter's functionality:
+The `from` class in [`debug-tools/state_analyzer.py`](https://github.com/cloudflare/vibesdk/blob/HEAD/debug-tools/state_analyzer.py) handles a key part of this chapter's functionality:
```py
+State Analyzer for SimpleGeneratorAgent setState debugging
+
+This script parses error messages from setState failures and analyzes:
+1. Size of each state property when serialized
+2. Differences between old and new states
+3. Main contributors to state growth
+4. Detailed breakdown for debugging SQL storage issues
+
+Usage: python state_analyzer.py <error_file_path>
+"""
+
+import json
import sys
import re
-from dataclasses import dataclass, field
-from typing import Dict, List, Any, Optional, Tuple, Union, TypedDict, Protocol
-from pathlib import Path
-import argparse
-from collections import defaultdict, Counter
-import math
-from enum import Enum
-from abc import ABC, abstractmethod
-
-
-class ContentType(Enum):
- """Enumeration for content types."""
- SOURCE_CODE = "source_code"
- JSON_DATA = "json_data"
- MARKDOWN_STRUCTURED = "markdown_structured"
- LARGE_TEXT = "large_text"
- METADATA = "metadata"
- PROSE = "prose"
-
-
-class ComponentName(Enum):
- """Enumeration for component names."""
- ROLE_SECTION = "role_section"
- GOAL_SECTION = "goal_section"
- CONTEXT_SECTION = "context_section"
- CLIENT_REQUEST = "client_request"
- BLUEPRINT = "blueprint"
- DEPENDENCIES = "dependencies"
- UI_GUIDELINES = "ui_guidelines"
- STRATEGY = "strategy"
+import os
+from typing import Dict, Any, List, Tuple, Union
+from dataclasses import dataclass
+from collections import defaultdict
+import difflib
+
+
+@dataclass
+class PropertyAnalysis:
+ """Analysis results for a single property"""
+ name: str
+ old_size: int
+ new_size: int
+ old_serialized_length: int
+ new_serialized_length: int
+ growth_bytes: int
+ growth_chars: int
+ has_changed: bool
```
This class is important because it defines how VibeSDK Tutorial: Build a Vibe-Coding Platform on Cloudflare implements the patterns covered in this chapter.
-### `debug-tools/ai_request_analyzer_v2.py`
+### `debug-tools/state_analyzer.py`
-The `class` class in [`debug-tools/ai_request_analyzer_v2.py`](https://github.com/cloudflare/vibesdk/blob/HEAD/debug-tools/ai_request_analyzer_v2.py) handles a key part of this chapter's functionality:
+The `class` class in [`debug-tools/state_analyzer.py`](https://github.com/cloudflare/vibesdk/blob/HEAD/debug-tools/state_analyzer.py) handles a key part of this chapter's functionality:
```py
-import sys
-import re
-from dataclasses import dataclass, field
-from typing import Dict, List, Any, Optional, Tuple, Union, TypedDict, Protocol
-from pathlib import Path
-import argparse
-from collections import defaultdict, Counter
-import math
-from enum import Enum
-from abc import ABC, abstractmethod
-
-
-class ContentType(Enum):
- """Enumeration for content types."""
- SOURCE_CODE = "source_code"
- JSON_DATA = "json_data"
- MARKDOWN_STRUCTURED = "markdown_structured"
- LARGE_TEXT = "large_text"
- METADATA = "metadata"
- PROSE = "prose"
-
-
-class ComponentName(Enum):
- """Enumeration for component names."""
- ROLE_SECTION = "role_section"
- GOAL_SECTION = "goal_section"
- CONTEXT_SECTION = "context_section"
- CLIENT_REQUEST = "client_request"
- BLUEPRINT = "blueprint"
- DEPENDENCIES = "dependencies"
- UI_GUIDELINES = "ui_guidelines"
- STRATEGY = "strategy"
+import os
+from typing import Dict, Any, List, Tuple, Union
+from dataclasses import dataclass
+from collections import defaultdict
+import difflib
+
+
+@dataclass
+class PropertyAnalysis:
+ """Analysis results for a single property"""
+ name: str
+ old_size: int
+ new_size: int
+ old_serialized_length: int
+ new_serialized_length: int
+ growth_bytes: int
+ growth_chars: int
+ has_changed: bool
+ old_type: str
+ new_type: str
+
+
+@dataclass
+class StateAnalysis:
+ """Complete analysis of state comparison"""
+ total_old_size: int
+ total_new_size: int
+ total_old_serialized_length: int
+ total_new_serialized_length: int
+ total_growth_bytes: int
+ total_growth_chars: int
+ property_analyses: List[PropertyAnalysis]
```
This class is important because it defines how VibeSDK Tutorial: Build a Vibe-Coding Platform on Cloudflare implements the patterns covered in this chapter.
-### `debug-tools/ai_request_analyzer_v2.py`
+### `debug-tools/state_analyzer.py`
-The `BaseAnalyzer` class in [`debug-tools/ai_request_analyzer_v2.py`](https://github.com/cloudflare/vibesdk/blob/HEAD/debug-tools/ai_request_analyzer_v2.py) handles a key part of this chapter's functionality:
+The `class` class in [`debug-tools/state_analyzer.py`](https://github.com/cloudflare/vibesdk/blob/HEAD/debug-tools/state_analyzer.py) handles a key part of this chapter's functionality:
```py
-
-
-class BaseAnalyzer(ABC):
- """Abstract base class for analyzers to ensure consistent interface."""
-
- @abstractmethod
- def analyze(self, content: str) -> Any:
- """Analyze content and return results."""
- pass
-
-
-class SCOFParser(BaseAnalyzer):
- """Type-safe SCOF format parser."""
-
- SCOF_FILE_PATTERN = re.compile(
- r'# Creating new file: ([^\n]+)\n'
- r'# File Purpose: ([^\n]*(?:\n# [^\n]*)*)\n*'
- r'cat > [^\n]+ << \'EOF\'\n'
- r'(.*?)\n'
- r'EOF',
- re.DOTALL | re.MULTILINE
- )
-
- SCOF_DIFF_PATTERN = re.compile(
- r'# Applying diff to file: ([^\n]+)\n'
- r'# File Purpose: ([^\n]*(?:\n# [^\n]*)*)\n*'
- r'cat << \'EOF\' \| patch [^\n]+\n'
- r'(.*?)\n'
- r'EOF',
- re.DOTALL | re.MULTILINE
- )
-
+import os
+from typing import Dict, Any, List, Tuple, Union
+from dataclasses import dataclass
+from collections import defaultdict
+import difflib
+
+
+@dataclass
+class PropertyAnalysis:
+ """Analysis results for a single property"""
+ name: str
+ old_size: int
+ new_size: int
+ old_serialized_length: int
+ new_serialized_length: int
+ growth_bytes: int
+ growth_chars: int
+ has_changed: bool
+ old_type: str
+ new_type: str
+
+
+@dataclass
+class StateAnalysis:
+ """Complete analysis of state comparison"""
+ total_old_size: int
+ total_new_size: int
+ total_old_serialized_length: int
+ total_new_serialized_length: int
+ total_growth_bytes: int
+ total_growth_chars: int
+ property_analyses: List[PropertyAnalysis]
```
This class is important because it defines how VibeSDK Tutorial: Build a Vibe-Coding Platform on Cloudflare implements the patterns covered in this chapter.
@@ -260,11 +258,11 @@ This class is important because it defines how VibeSDK Tutorial: Build a Vibe-Co
```mermaid
flowchart TD
- A[class]
- B[class]
+ A[WranglerConfig]
+ B[from]
C[class]
- D[BaseAnalyzer]
- E[for]
+ D[class]
+ E[StateAnalyzer]
A --> B
B --> C
C --> D
diff --git a/tutorials/vibesdk-tutorial/05-data-layer-and-persistence.md b/tutorials/vibesdk-tutorial/05-data-layer-and-persistence.md
index eaf4fa28..d12bdeee 100644
--- a/tutorials/vibesdk-tutorial/05-data-layer-and-persistence.md
+++ b/tutorials/vibesdk-tutorial/05-data-layer-and-persistence.md
@@ -87,100 +87,95 @@ You now have a persistence model that supports reliable operations without overl
Next: [Chapter 6: API, SDK, and Integrations](06-api-sdk-and-integrations.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `debug-tools/ai_request_analyzer_v2.py`
-The `PhaseImplementationAnalyzer` class in [`debug-tools/ai_request_analyzer_v2.py`](https://github.com/cloudflare/vibesdk/blob/HEAD/debug-tools/ai_request_analyzer_v2.py) handles a key part of this chapter's functionality:
+The `Dependency` class in [`debug-tools/ai_request_analyzer_v2.py`](https://github.com/cloudflare/vibesdk/blob/HEAD/debug-tools/ai_request_analyzer_v2.py) handles a key part of this chapter's functionality:
```py
-
-class PhaseImplementationAnalyzer:
- """Main type-safe analyzer for Phase Implementation requests."""
+@dataclass(frozen=True)
+class Dependency:
+ """Type-safe representation of a package dependency."""
+ name: str
+ version: str
+ category: str # 'runtime', 'dev', 'peer'
- def __init__(self):
- self.scof_parser = SCOFParser()
- self.dependency_parser = DependencyParser()
- self.template_parser = TemplateParser()
-
- self.prompt_patterns = self._get_prompt_patterns()
+ def __post_init__(self):
+ """Validate dependency data."""
+ if not self.name or not self.version:
+ raise ValueError("Dependency name and version are required")
- def _get_prompt_patterns(self) -> Dict[ComponentName, Tuple[str, str]]:
- """Get prompt component patterns."""
- return {
- ComponentName.ROLE_SECTION: ('<ROLE>', '</ROLE>'),
- ComponentName.GOAL_SECTION: ('<GOAL>', '</GOAL>'),
- ComponentName.CONTEXT_SECTION: ('<CONTEXT>', '</CONTEXT>'),
- ComponentName.CLIENT_REQUEST: ('<CLIENT REQUEST>', '</CLIENT REQUEST>'),
- ComponentName.BLUEPRINT: ('<BLUEPRINT>', '</BLUEPRINT>'),
- # Use more specific pattern for DEPENDENCIES to avoid matching references
- ComponentName.DEPENDENCIES: ('<DEPENDENCIES>\n**Available Dependencies:**', '</DEPENDENCIES>'),
- ComponentName.STRATEGY: ('<PHASES GENERATION STRATEGY>', '</PHASES GENERATION STRATEGY>'),
- ComponentName.PROJECT_CONTEXT: ('<PROJECT CONTEXT>', '</PROJECT CONTEXT>'),
- ComponentName.COMPLETED_PHASES: ('<COMPLETED PHASES>', '</COMPLETED PHASES>'),
- ComponentName.CODEBASE: ('<CODEBASE>', '</CODEBASE>'),
- ComponentName.CURRENT_PHASE: ('<CURRENT_PHASE>', '</CURRENT_PHASE>'),
- ComponentName.INSTRUCTIONS: ('<INSTRUCTIONS & CODE QUALITY STANDARDS>', '</INSTRUCTIONS & CODE QUALITY STANDARDS>'),
- }
+ @property
+ def is_dev_dependency(self) -> bool:
+ """Check if this is a dev dependency."""
+ dev_indicators = ['@types/', 'eslint', 'typescript', 'vite', '@vitejs/', 'autoprefixer', 'postcss', 'globals']
+ return any(indicator in self.name for indicator in dev_indicators)
- def analyze_request(self, json_path: str) -> RequestAnalysis:
- """Analyze AI request with full type safety."""
+ @property
+ def size_estimate(self) -> int:
+ """Estimate package size contribution in chars."""
+ return len(f'"{self.name}":"{self.version}",')
+
+
+@dataclass(frozen=True)
+class PromptComponent:
+ """Type-safe representation of a prompt component."""
+ name: ComponentName
+ content: str
+ start_marker: str
+ end_marker: str
```
This class is important because it defines how VibeSDK Tutorial: Build a Vibe-Coding Platform on Cloudflare implements the patterns covered in this chapter.
### `debug-tools/ai_request_analyzer_v2.py`
-The `main` function in [`debug-tools/ai_request_analyzer_v2.py`](https://github.com/cloudflare/vibesdk/blob/HEAD/debug-tools/ai_request_analyzer_v2.py) handles a key part of this chapter's functionality:
+The `PromptComponent` class in [`debug-tools/ai_request_analyzer_v2.py`](https://github.com/cloudflare/vibesdk/blob/HEAD/debug-tools/ai_request_analyzer_v2.py) handles a key part of this chapter's functionality:
```py
-
-def main():
- """Main CLI entry point with proper error handling."""
- parser = argparse.ArgumentParser(
- description="Type-safe AI Gateway request analyzer for PhaseImplementation",
- formatter_class=argparse.RawDescriptionHelpFormatter,
- epilog="""
-Examples:
- python ai_request_analyzer_v2.py sample-request.json --detailed
- python ai_request_analyzer_v2.py sample-request.json --export analysis.json
- """
- )
+@dataclass(frozen=True)
+class PromptComponent:
+ """Type-safe representation of a prompt component."""
+ name: ComponentName
+ content: str
+ start_marker: str
+ end_marker: str
+ size_chars: int
+ content_type: ContentType
- parser.add_argument('request_file', help='Path to the JSON request file')
- parser.add_argument('--detailed', '-d', action='store_true',
- help='Print detailed analysis')
- parser.add_argument('--export', '-e', help='Export analysis to JSON file')
+ def __post_init__(self):
+ """Validate component data."""
+ if self.size_chars != len(self.content):
+ raise ValueError("Size mismatch in PromptComponent")
- args = parser.parse_args()
+ @property
+ def size_tokens_approx(self) -> int:
+ """Approximate token count."""
+ return math.ceil(self.size_chars / 4)
- # Validate input
- if not Path(args.request_file).exists():
- print(f"❌ Error: Request file not found: {args.request_file}")
- sys.exit(1)
-
- try:
- # Run analysis
- analyzer = PhaseImplementationAnalyzer()
- analysis = analyzer.analyze_request(args.request_file)
-
- # Print results
+ @property
+ def percentage_of_request(self) -> float:
+ """Percentage of total request (set externally)."""
+ return 0.0 # Will be calculated by analyzer
+
+
+@dataclass
+class MessageAnalysis:
+ """Type-safe analysis of a single message."""
+ role: str
+ content: str
```
-This function is important because it defines how VibeSDK Tutorial: Build a Vibe-Coding Platform on Cloudflare implements the patterns covered in this chapter.
+This class is important because it defines how VibeSDK Tutorial: Build a Vibe-Coding Platform on Cloudflare implements the patterns covered in this chapter.
### `debug-tools/ai_request_analyzer_v2.py`
-The `import` interface in [`debug-tools/ai_request_analyzer_v2.py`](https://github.com/cloudflare/vibesdk/blob/HEAD/debug-tools/ai_request_analyzer_v2.py) handles a key part of this chapter's functionality:
+The `class` class in [`debug-tools/ai_request_analyzer_v2.py`](https://github.com/cloudflare/vibesdk/blob/HEAD/debug-tools/ai_request_analyzer_v2.py) handles a key part of this chapter's functionality:
```py
-"""
-
-import json
import sys
import re
from dataclasses import dataclass, field
@@ -210,47 +205,50 @@ class ComponentName(Enum):
CONTEXT_SECTION = "context_section"
CLIENT_REQUEST = "client_request"
BLUEPRINT = "blueprint"
+ DEPENDENCIES = "dependencies"
+ UI_GUIDELINES = "ui_guidelines"
+ STRATEGY = "strategy"
```
-This interface is important because it defines how VibeSDK Tutorial: Build a Vibe-Coding Platform on Cloudflare implements the patterns covered in this chapter.
-
-### `container/storage.ts`
-
-The `StorageManager` class in [`container/storage.ts`](https://github.com/cloudflare/vibesdk/blob/HEAD/container/storage.ts) handles a key part of this chapter's functionality:
-
-```ts
- * Unified storage manager with shared database connections and optimized operations
- */
-export class StorageManager {
- private errorDb: Database;
- private logDb: Database;
- private errorStorage: ErrorStorage;
- private logStorage: LogStorage;
- private options: {
- error: Required<ErrorStoreOptions>;
- log: Required<LogStoreOptions>;
- };
-
- constructor(
- errorDbPath: string = getErrorDbPath(),
- logDbPath: string = getLogDbPath(),
- options: { error?: ErrorStoreOptions; log?: LogStoreOptions } = {}
- ) {
- this.options = {
- error: { ...DEFAULT_STORAGE_OPTIONS, ...options.error } as Required<ErrorStoreOptions>,
- log: { ...DEFAULT_LOG_STORE_OPTIONS, ...options.log } as Required<LogStoreOptions>
- };
-
- this.ensureDataDirectory(errorDbPath);
- if (errorDbPath !== logDbPath) {
- this.ensureDataDirectory(logDbPath);
- }
-
- this.errorDb = this.initializeDatabase(errorDbPath);
- this.logDb = errorDbPath === logDbPath ? this.errorDb : this.initializeDatabase(logDbPath);
-
- this.errorStorage = new ErrorStorage(this.errorDb, this.options.error);
- this.logStorage = new LogStorage(this.logDb, this.options.log);
+This class is important because it defines how VibeSDK Tutorial: Build a Vibe-Coding Platform on Cloudflare implements the patterns covered in this chapter.
+
+### `debug-tools/ai_request_analyzer_v2.py`
+
+The `class` class in [`debug-tools/ai_request_analyzer_v2.py`](https://github.com/cloudflare/vibesdk/blob/HEAD/debug-tools/ai_request_analyzer_v2.py) handles a key part of this chapter's functionality:
+
+```py
+import sys
+import re
+from dataclasses import dataclass, field
+from typing import Dict, List, Any, Optional, Tuple, Union, TypedDict, Protocol
+from pathlib import Path
+import argparse
+from collections import defaultdict, Counter
+import math
+from enum import Enum
+from abc import ABC, abstractmethod
+
+
+class ContentType(Enum):
+ """Enumeration for content types."""
+ SOURCE_CODE = "source_code"
+ JSON_DATA = "json_data"
+ MARKDOWN_STRUCTURED = "markdown_structured"
+ LARGE_TEXT = "large_text"
+ METADATA = "metadata"
+ PROSE = "prose"
+
+
+class ComponentName(Enum):
+ """Enumeration for component names."""
+ ROLE_SECTION = "role_section"
+ GOAL_SECTION = "goal_section"
+ CONTEXT_SECTION = "context_section"
+ CLIENT_REQUEST = "client_request"
+ BLUEPRINT = "blueprint"
+ DEPENDENCIES = "dependencies"
+ UI_GUIDELINES = "ui_guidelines"
+ STRATEGY = "strategy"
```
This class is important because it defines how VibeSDK Tutorial: Build a Vibe-Coding Platform on Cloudflare implements the patterns covered in this chapter.
@@ -260,11 +258,11 @@ This class is important because it defines how VibeSDK Tutorial: Build a Vibe-Co
```mermaid
flowchart TD
- A[PhaseImplementationAnalyzer]
- B[main]
- C[import]
- D[StorageManager]
- E[ErrorStorage]
+ A[Dependency]
+ B[PromptComponent]
+ C[class]
+ D[class]
+ E[class]
A --> B
B --> C
C --> D
diff --git a/tutorials/vibesdk-tutorial/06-api-sdk-and-integrations.md b/tutorials/vibesdk-tutorial/06-api-sdk-and-integrations.md
index 6ede32a1..1e1c2f14 100644
--- a/tutorials/vibesdk-tutorial/06-api-sdk-and-integrations.md
+++ b/tutorials/vibesdk-tutorial/06-api-sdk-and-integrations.md
@@ -92,170 +92,168 @@ You now have a practical integration model for embedding VibeSDK into programmat
Next: [Chapter 7: Security, Auth, and Governance](07-security-auth-and-governance.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `debug-tools/state_analyzer.py`
+### `debug-tools/ai_request_analyzer_v2.py`
-The `class` class in [`debug-tools/state_analyzer.py`](https://github.com/cloudflare/vibesdk/blob/HEAD/debug-tools/state_analyzer.py) handles a key part of this chapter's functionality:
+The `TemplateParser` class in [`debug-tools/ai_request_analyzer_v2.py`](https://github.com/cloudflare/vibesdk/blob/HEAD/debug-tools/ai_request_analyzer_v2.py) handles a key part of this chapter's functionality:
```py
-import os
-from typing import Dict, Any, List, Tuple, Union
-from dataclasses import dataclass
-from collections import defaultdict
-import difflib
-
-
-@dataclass
-class PropertyAnalysis:
- """Analysis results for a single property"""
- name: str
- old_size: int
- new_size: int
- old_serialized_length: int
- new_serialized_length: int
- growth_bytes: int
- growth_chars: int
- has_changed: bool
- old_type: str
- new_type: str
-
-
-@dataclass
-class StateAnalysis:
- """Complete analysis of state comparison"""
- total_old_size: int
- total_new_size: int
- total_old_serialized_length: int
- total_new_serialized_length: int
- total_growth_bytes: int
- total_growth_chars: int
- property_analyses: List[PropertyAnalysis]
+
+
+class TemplateParser(BaseAnalyzer):
+ """Type-safe template analysis parser."""
+
+ TEMPLATE_VAR_PATTERN = re.compile(r'\{\{(\w+)\}\}')
+ MARKDOWN_SECTION_PATTERN = re.compile(r'^#{2,6}\s+(.+)$', re.MULTILINE)
+
+ def analyze(self, content: str) -> TemplateAnalysis:
+ """Analyze template usage and efficiency."""
+ # Find template variables
+ template_vars = list(set(self.TEMPLATE_VAR_PATTERN.findall(content)))
+
+ # Count markdown sections
+ markdown_sections = len(self.MARKDOWN_SECTION_PATTERN.findall(content))
+
+ # Calculate overheads
+ substitution_overhead = len(template_vars) * 20 # Estimated overhead per variable
+ markdown_overhead = markdown_sections * 50 # Estimated overhead per section
+
+ # Detect unused sections (simplified heuristic)
+ unused_sections = []
+ if 'placeholder' in content.lower() or 'example' in content.lower():
+ unused_sections.append('example_content')
+
+ return TemplateAnalysis(
+ template_variables=template_vars,
+ substitution_overhead=substitution_overhead,
+ markdown_sections=markdown_sections,
+ markdown_overhead=markdown_overhead,
+ unused_sections=unused_sections,
+ total_template_size=len(content)
```
This class is important because it defines how VibeSDK Tutorial: Build a Vibe-Coding Platform on Cloudflare implements the patterns covered in this chapter.
-### `debug-tools/state_analyzer.py`
+### `debug-tools/ai_request_analyzer_v2.py`
-The `class` class in [`debug-tools/state_analyzer.py`](https://github.com/cloudflare/vibesdk/blob/HEAD/debug-tools/state_analyzer.py) handles a key part of this chapter's functionality:
+The `class` class in [`debug-tools/ai_request_analyzer_v2.py`](https://github.com/cloudflare/vibesdk/blob/HEAD/debug-tools/ai_request_analyzer_v2.py) handles a key part of this chapter's functionality:
```py
-import os
-from typing import Dict, Any, List, Tuple, Union
-from dataclasses import dataclass
-from collections import defaultdict
-import difflib
-
-
-@dataclass
-class PropertyAnalysis:
- """Analysis results for a single property"""
- name: str
- old_size: int
- new_size: int
- old_serialized_length: int
- new_serialized_length: int
- growth_bytes: int
- growth_chars: int
- has_changed: bool
- old_type: str
- new_type: str
-
-
-@dataclass
-class StateAnalysis:
- """Complete analysis of state comparison"""
- total_old_size: int
- total_new_size: int
- total_old_serialized_length: int
- total_new_serialized_length: int
- total_growth_bytes: int
- total_growth_chars: int
- property_analyses: List[PropertyAnalysis]
+import sys
+import re
+from dataclasses import dataclass, field
+from typing import Dict, List, Any, Optional, Tuple, Union, TypedDict, Protocol
+from pathlib import Path
+import argparse
+from collections import defaultdict, Counter
+import math
+from enum import Enum
+from abc import ABC, abstractmethod
+
+
+class ContentType(Enum):
+ """Enumeration for content types."""
+ SOURCE_CODE = "source_code"
+ JSON_DATA = "json_data"
+ MARKDOWN_STRUCTURED = "markdown_structured"
+ LARGE_TEXT = "large_text"
+ METADATA = "metadata"
+ PROSE = "prose"
+
+
+class ComponentName(Enum):
+ """Enumeration for component names."""
+ ROLE_SECTION = "role_section"
+ GOAL_SECTION = "goal_section"
+ CONTEXT_SECTION = "context_section"
+ CLIENT_REQUEST = "client_request"
+ BLUEPRINT = "blueprint"
+ DEPENDENCIES = "dependencies"
+ UI_GUIDELINES = "ui_guidelines"
+ STRATEGY = "strategy"
```
This class is important because it defines how VibeSDK Tutorial: Build a Vibe-Coding Platform on Cloudflare implements the patterns covered in this chapter.
-### `debug-tools/state_analyzer.py`
+### `debug-tools/ai_request_analyzer_v2.py`
-The `StateAnalyzer` class in [`debug-tools/state_analyzer.py`](https://github.com/cloudflare/vibesdk/blob/HEAD/debug-tools/state_analyzer.py) handles a key part of this chapter's functionality:
+The `class` class in [`debug-tools/ai_request_analyzer_v2.py`](https://github.com/cloudflare/vibesdk/blob/HEAD/debug-tools/ai_request_analyzer_v2.py) handles a key part of this chapter's functionality:
```py
-
-
-class StateAnalyzer:
- """Main analyzer class for state debugging"""
-
- def __init__(self):
- self.known_large_properties = {
- 'generatedFilesMap', 'templateDetails', 'conversationMessages',
- 'generatedPhases', 'blueprint', 'commandsHistory'
- }
-
- def extract_states_from_error(self, error_content: str) -> Tuple[Dict[str, Any], Dict[str, Any]]:
- """Extract original and new states from WebSocket error message"""
- print("🔍 Extracting states from WebSocket error message...")
-
- # First, try to parse as WebSocket JSON message
- websocket_message = None
- try:
- websocket_message = json.loads(error_content)
- print("✅ Successfully parsed WebSocket message")
- except json.JSONDecodeError:
- print("⚠️ Not a JSON WebSocket message, trying as plain text...")
-
- # Extract the error text
- if websocket_message and isinstance(websocket_message, dict):
- # Handle WebSocket message format: {"type": "error", "error": "..."}
- if 'error' in websocket_message:
- error_text = websocket_message['error']
- print(f"📄 Extracted error text from WebSocket message: {len(error_text):,} chars")
- else:
- # Maybe the whole message is the error text
- error_text = str(websocket_message)
+import sys
+import re
+from dataclasses import dataclass, field
+from typing import Dict, List, Any, Optional, Tuple, Union, TypedDict, Protocol
+from pathlib import Path
+import argparse
+from collections import defaultdict, Counter
+import math
+from enum import Enum
+from abc import ABC, abstractmethod
+
+
+class ContentType(Enum):
+ """Enumeration for content types."""
+ SOURCE_CODE = "source_code"
+ JSON_DATA = "json_data"
+ MARKDOWN_STRUCTURED = "markdown_structured"
+ LARGE_TEXT = "large_text"
+ METADATA = "metadata"
+ PROSE = "prose"
+
+
+class ComponentName(Enum):
+ """Enumeration for component names."""
+ ROLE_SECTION = "role_section"
+ GOAL_SECTION = "goal_section"
+ CONTEXT_SECTION = "context_section"
+ CLIENT_REQUEST = "client_request"
+ BLUEPRINT = "blueprint"
+ DEPENDENCIES = "dependencies"
+ UI_GUIDELINES = "ui_guidelines"
+ STRATEGY = "strategy"
```
This class is important because it defines how VibeSDK Tutorial: Build a Vibe-Coding Platform on Cloudflare implements the patterns covered in this chapter.
-### `debug-tools/state_analyzer.py`
+### `debug-tools/ai_request_analyzer_v2.py`
-The `for` class in [`debug-tools/state_analyzer.py`](https://github.com/cloudflare/vibesdk/blob/HEAD/debug-tools/state_analyzer.py) handles a key part of this chapter's functionality:
+The `PhaseImplementationAnalyzer` class in [`debug-tools/ai_request_analyzer_v2.py`](https://github.com/cloudflare/vibesdk/blob/HEAD/debug-tools/ai_request_analyzer_v2.py) handles a key part of this chapter's functionality:
```py
-#!/usr/bin/env python3
-"""
-State Analyzer for SimpleGeneratorAgent setState debugging
-This script parses error messages from setState failures and analyzes:
-1. Size of each state property when serialized
-2. Differences between old and new states
-3. Main contributors to state growth
-4. Detailed breakdown for debugging SQL storage issues
-Usage: python state_analyzer.py <error_file_path>
-"""
-
-import json
-import sys
-import re
-import os
-from typing import Dict, Any, List, Tuple, Union
-from dataclasses import dataclass
-from collections import defaultdict
-import difflib
-
-
-@dataclass
-class PropertyAnalysis:
- """Analysis results for a single property"""
- name: str
- old_size: int
- new_size: int
- old_serialized_length: int
- new_serialized_length: int
- growth_bytes: int
+class PhaseImplementationAnalyzer:
+ """Main type-safe analyzer for Phase Implementation requests."""
+
+ def __init__(self):
+ self.scof_parser = SCOFParser()
+ self.dependency_parser = DependencyParser()
+ self.template_parser = TemplateParser()
+
+ self.prompt_patterns = self._get_prompt_patterns()
+
+ def _get_prompt_patterns(self) -> Dict[ComponentName, Tuple[str, str]]:
+ """Get prompt component patterns."""
+ return {
+ ComponentName.ROLE_SECTION: ('<ROLE>', '</ROLE>'),
+ ComponentName.GOAL_SECTION: ('<GOAL>', '</GOAL>'),
+ ComponentName.CONTEXT_SECTION: ('<CONTEXT>', '</CONTEXT>'),
+ ComponentName.CLIENT_REQUEST: ('<CLIENT REQUEST>', '</CLIENT REQUEST>'),
+ ComponentName.BLUEPRINT: ('<BLUEPRINT>', '</BLUEPRINT>'),
+ # Use more specific pattern for DEPENDENCIES to avoid matching references
+ ComponentName.DEPENDENCIES: ('<DEPENDENCIES>\n**Available Dependencies:**', '</DEPENDENCIES>'),
+ ComponentName.STRATEGY: ('<PHASES GENERATION STRATEGY>', '</PHASES GENERATION STRATEGY>'),
+ ComponentName.PROJECT_CONTEXT: ('<PROJECT CONTEXT>', '</PROJECT CONTEXT>'),
+ ComponentName.COMPLETED_PHASES: ('<COMPLETED PHASES>', '</COMPLETED PHASES>'),
+ ComponentName.CODEBASE: ('<CODEBASE>', '</CODEBASE>'),
+ ComponentName.CURRENT_PHASE: ('<CURRENT_PHASE>', '</CURRENT_PHASE>'),
+ ComponentName.INSTRUCTIONS: ('<INSTRUCTIONS & CODE QUALITY STANDARDS>', '</INSTRUCTIONS & CODE QUALITY STANDARDS>'),
+ }
+
+ def analyze_request(self, json_path: str) -> RequestAnalysis:
+ """Analyze AI request with full type safety."""
```
This class is important because it defines how VibeSDK Tutorial: Build a Vibe-Coding Platform on Cloudflare implements the patterns covered in this chapter.
@@ -265,10 +263,10 @@ This class is important because it defines how VibeSDK Tutorial: Build a Vibe-Co
```mermaid
flowchart TD
- A[class]
+ A[TemplateParser]
B[class]
- C[StateAnalyzer]
- D[for]
+ C[class]
+ D[PhaseImplementationAnalyzer]
E[main]
A --> B
B --> C
diff --git a/tutorials/vibesdk-tutorial/07-security-auth-and-governance.md b/tutorials/vibesdk-tutorial/07-security-auth-and-governance.md
index 23778670..d998ca45 100644
--- a/tutorials/vibesdk-tutorial/07-security-auth-and-governance.md
+++ b/tutorials/vibesdk-tutorial/07-security-auth-and-governance.md
@@ -75,91 +75,89 @@ You now have a practical security and governance baseline for operating VibeSDK
Next: [Chapter 8: Production Operations and Scaling](08-production-operations-and-scaling.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `scripts/undeploy.ts`
-
-The `CloudflareUndeploymentManager` class in [`scripts/undeploy.ts`](https://github.com/cloudflare/vibesdk/blob/HEAD/scripts/undeploy.ts) handles a key part of this chapter's functionality:
-
-```ts
-}
-
-class CloudflareUndeploymentManager {
- private config: WranglerConfig;
- private forceMode: boolean = false;
- private allMode: boolean = false;
-
- constructor() {
- this.parseArguments();
- this.config = this.parseWranglerConfig();
- }
-
- /**
- * Parse command line arguments
- */
- private parseArguments(): void {
- const args = process.argv.slice(2);
- this.allMode = args.includes('all');
- this.forceMode = args.includes('--force');
-
- if (this.allMode && !this.forceMode) {
- console.warn('⚠️ Warning: "all" mode requires --force flag for safety');
- console.warn(' Usage: bun scripts/undeploy.ts all --force');
- process.exit(1);
- }
-
- console.log(`🚨 Undeployment Mode: ${this.allMode ? 'COMPLETE DESTRUCTION' : 'Standard Cleanup'}`);
- if (this.allMode) {
- console.log('⚠️ This will DELETE ALL RESOURCES including D1 database and dispatch namespace!');
- } else {
- console.log('ℹ️ This will preserve D1 database and dispatch namespace');
- }
+### `debug-tools/conversation_analyzer.py`
+
+The `ConversationAnalyzer` class in [`debug-tools/conversation_analyzer.py`](https://github.com/cloudflare/vibesdk/blob/HEAD/debug-tools/conversation_analyzer.py) handles a key part of this chapter's functionality:
+
+```py
+ recommendations: List[str]
+
+class ConversationAnalyzer:
+ def __init__(self):
+ self.size_thresholds = {
+ 'small': 1000, # 1KB
+ 'medium': 5000, # 5KB
+ 'large': 20000, # 20KB
+ 'huge': 100000 # 100KB
+ }
+
+ def analyze_conversation_messages(self, messages: List[Dict[str, Any]]) -> ConversationAnalysis:
+ """Analyze conversation messages for size and content"""
+ print(f"🔍 Analyzing {len(messages)} conversation messages...")
+
+ total_size = 0
+ message_types = Counter()
+ size_by_type = defaultdict(int)
+ largest_messages = []
+
+ for i, msg in enumerate(messages):
+ # Calculate message size
+ msg_size = len(json.dumps(msg, default=str))
+ total_size += msg_size
+
+ # Categorize by type/role
+ msg_type = msg.get('role', msg.get('type', 'unknown'))
+ message_types[msg_type] += 1
+ size_by_type[msg_type] += msg_size
+
+ # Track largest messages
+ msg_info = {
```
This class is important because it defines how VibeSDK Tutorial: Build a Vibe-Coding Platform on Cloudflare implements the patterns covered in this chapter.
-### `scripts/undeploy.ts`
-
-The `WranglerConfig` interface in [`scripts/undeploy.ts`](https://github.com/cloudflare/vibesdk/blob/HEAD/scripts/undeploy.ts) handles a key part of this chapter's functionality:
-
-```ts
-
-// Types for configuration
-interface WranglerConfig {
- name: string;
- dispatch_namespaces?: Array<{
- binding: string;
- namespace: string;
- experimental_remote?: boolean;
- }>;
- r2_buckets?: Array<{
- binding: string;
- bucket_name: string;
- experimental_remote?: boolean;
- }>;
- containers?: Array<{
- class_name: string;
- image: string;
- max_instances: number;
- }>;
- d1_databases?: Array<{
- binding: string;
- database_name: string;
- database_id: string;
- migrations_dir?: string;
- experimental_remote?: boolean;
- }>;
- kv_namespaces?: Array<{
- binding: string;
- id: string;
- experimental_remote?: boolean;
- }>;
-}
+### `debug-tools/conversation_analyzer.py`
+
+The `main` function in [`debug-tools/conversation_analyzer.py`](https://github.com/cloudflare/vibesdk/blob/HEAD/debug-tools/conversation_analyzer.py) handles a key part of this chapter's functionality:
+
+```py
+ return "\n".join(report)
+
+def main():
+ # Check if we have debug files from the main analyzer
+ conversation_file = "debug_output/conversationMessages_new.json"
+
+ if not os.path.exists(conversation_file):
+ print("❌ Conversation messages debug file not found!")
+ print(" Please run the main state analyzer first: python state_analyzer.py errorfile.json")
+ print(" This will generate the required debug files in debug_output/")
+ return
+
+ print("🚀 Starting conversation messages analysis...")
+ print(f"📁 Reading conversation data from: {conversation_file}")
+
+ try:
+ with open(conversation_file, 'r') as f:
+ messages = json.load(f)
+
+ print(f"📄 Loaded {len(messages)} conversation messages")
+
+ analyzer = ConversationAnalyzer()
+ analysis = analyzer.analyze_conversation_messages(messages)
+
+ # Generate report
+ report = analyzer.generate_report(analysis)
+
+ # Save report
+ report_file = "conversation_analysis_report.txt"
+ with open(report_file, 'w') as f:
+ f.write(report)
+
```
-This interface is important because it defines how VibeSDK Tutorial: Build a Vibe-Coding Platform on Cloudflare implements the patterns covered in this chapter.
+This function is important because it defines how VibeSDK Tutorial: Build a Vibe-Coding Platform on Cloudflare implements the patterns covered in this chapter.
### `container/types.ts`
@@ -248,8 +246,8 @@ This interface is important because it defines how VibeSDK Tutorial: Build a Vib
```mermaid
flowchart TD
- A[CloudflareUndeploymentManager]
- B[WranglerConfig]
+ A[ConversationAnalyzer]
+ B[main]
C[LogLine]
D[ProcessInfo]
E[MonitoringOptions]
diff --git a/tutorials/vibesdk-tutorial/08-production-operations-and-scaling.md b/tutorials/vibesdk-tutorial/08-production-operations-and-scaling.md
index d23a7077..ff33e233 100644
--- a/tutorials/vibesdk-tutorial/08-production-operations-and-scaling.md
+++ b/tutorials/vibesdk-tutorial/08-production-operations-and-scaling.md
@@ -89,8 +89,6 @@ You now have an operations blueprint for running VibeSDK as a production platfor
Next: return to the [VibeSDK Tutorial index](README.md).
-## Depth Expansion Playbook
-
## Source Code Walkthrough
### `container/types.ts`
diff --git a/tutorials/vllm-tutorial/01-getting-started.md b/tutorials/vllm-tutorial/01-getting-started.md
index 0081fd7d..4285738e 100644
--- a/tutorials/vllm-tutorial/01-getting-started.md
+++ b/tutorials/vllm-tutorial/01-getting-started.md
@@ -582,6 +582,16 @@ Under the hood, `Chapter 1: Getting Started with vLLM` usually follows a repeata
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## Architecture Flow
+
+```mermaid
+flowchart LR
+ A[pip install vllm] --> B[LLM model loaded]
+ B --> C[SamplingParams configured]
+ C --> D[llm.generate called]
+ D --> E[Completion tokens returned]
+```
+
## Source Walkthrough
Use the following upstream sources to verify implementation details while reading this chapter:
diff --git a/tutorials/vllm-tutorial/02-model-loading.md b/tutorials/vllm-tutorial/02-model-loading.md
index 269603a5..92c4680e 100644
--- a/tutorials/vllm-tutorial/02-model-loading.md
+++ b/tutorials/vllm-tutorial/02-model-loading.md
@@ -786,6 +786,16 @@ Under the hood, `Chapter 2: Model Loading and Management` usually follows a repe
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## Architecture Flow
+
+```mermaid
+flowchart LR
+ A[HuggingFace model ID or local path] --> B[vLLM model loader]
+ B --> C[Quantization applied if configured]
+ C --> D[Model weights in GPU VRAM]
+ D --> E[Ready for inference]
+```
+
## Source Walkthrough
Use the following upstream sources to verify implementation details while reading this chapter:
diff --git a/tutorials/vllm-tutorial/03-basic-inference.md b/tutorials/vllm-tutorial/03-basic-inference.md
index ca012985..dae77ad0 100644
--- a/tutorials/vllm-tutorial/03-basic-inference.md
+++ b/tutorials/vllm-tutorial/03-basic-inference.md
@@ -651,6 +651,16 @@ Under the hood, `Chapter 3: Basic Inference - Text Generation and Sampling` usua
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## Architecture Flow
+
+```mermaid
+flowchart LR
+ A[Input prompts list] --> B[Continuous batching scheduler]
+ B --> C[PagedAttention KV cache]
+ C --> D[Token sampling with SamplingParams]
+ D --> E[RequestOutput with completion text]
+```
+
## Source Walkthrough
Use the following upstream sources to verify implementation details while reading this chapter:
diff --git a/tutorials/vllm-tutorial/04-advanced-features.md b/tutorials/vllm-tutorial/04-advanced-features.md
index 4243fcc8..562a98bb 100644
--- a/tutorials/vllm-tutorial/04-advanced-features.md
+++ b/tutorials/vllm-tutorial/04-advanced-features.md
@@ -815,6 +815,17 @@ Under the hood, `Chapter 4: Advanced Features - Streaming, Tool Calling, and Mul
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## Architecture Flow
+
+```mermaid
+flowchart LR
+ A[Streaming request] --> B[AsyncLLMEngine]
+ B --> C[Token-by-token generation]
+ C --> D[Streamed to client]
+ E[Tool call request] --> B
+ F[Multi-modal image + text] --> B
+```
+
## Source Walkthrough
Use the following upstream sources to verify implementation details while reading this chapter:
diff --git a/tutorials/vllm-tutorial/05-performance-optimization.md b/tutorials/vllm-tutorial/05-performance-optimization.md
index d73b2ab5..7dc9daba 100644
--- a/tutorials/vllm-tutorial/05-performance-optimization.md
+++ b/tutorials/vllm-tutorial/05-performance-optimization.md
@@ -920,6 +920,17 @@ Under the hood, `Chapter 5: Performance Optimization - Maximizing Throughput and
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## Architecture Flow
+
+```mermaid
+flowchart LR
+ A[Incoming requests] --> B[Continuous batching]
+ B --> C[PagedAttention memory management]
+ C --> D[Quantized model weights]
+ D --> E[Optimized CUDA kernels]
+ E --> F[Maximum GPU utilization]
+```
+
## Source Walkthrough
Use the following upstream sources to verify implementation details while reading this chapter:
diff --git a/tutorials/vllm-tutorial/06-distributed-inference.md b/tutorials/vllm-tutorial/06-distributed-inference.md
index 965e6681..c69c48f7 100644
--- a/tutorials/vllm-tutorial/06-distributed-inference.md
+++ b/tutorials/vllm-tutorial/06-distributed-inference.md
@@ -979,6 +979,16 @@ Under the hood, `Chapter 6: Distributed Inference - Scaling Across GPUs and Node
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## Architecture Flow
+
+```mermaid
+flowchart LR
+ A[Large model too big for single GPU] --> B[Tensor parallelism across GPUs]
+ B --> C[Pipeline parallelism across nodes]
+ C --> D[Ray cluster coordination]
+ D --> E[Distributed token generation]
+```
+
## Source Walkthrough
Use the following upstream sources to verify implementation details while reading this chapter:
diff --git a/tutorials/vllm-tutorial/07-production-deployment.md b/tutorials/vllm-tutorial/07-production-deployment.md
index f68b179c..bc1d9194 100644
--- a/tutorials/vllm-tutorial/07-production-deployment.md
+++ b/tutorials/vllm-tutorial/07-production-deployment.md
@@ -1308,6 +1308,17 @@ Under the hood, `Chapter 7: Production Deployment - Serving vLLM at Scale` usual
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## Architecture Flow
+
+```mermaid
+flowchart LR
+ A[Client request] --> B[Load balancer]
+ B --> C[vLLM OpenAI-compatible API server]
+ C --> D[Model inference]
+ D --> E[Response returned]
+ C --> F[Prometheus metrics exposed]
+```
+
## Source Walkthrough
Use the following upstream sources to verify implementation details while reading this chapter:
diff --git a/tutorials/vllm-tutorial/08-monitoring-scaling.md b/tutorials/vllm-tutorial/08-monitoring-scaling.md
index d318a633..8c170749 100644
--- a/tutorials/vllm-tutorial/08-monitoring-scaling.md
+++ b/tutorials/vllm-tutorial/08-monitoring-scaling.md
@@ -1104,6 +1104,16 @@ Under the hood, `Chapter 8: Monitoring & Scaling - Production Operations at Scal
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
+## Architecture Flow
+
+```mermaid
+flowchart LR
+ A[vLLM server metrics endpoint] --> B[Prometheus scrape]
+ B --> C[Grafana dashboard]
+ C --> D[Latency and throughput visibility]
+ D --> E[Auto-scaling trigger if threshold exceeded]
+```
+
## Source Walkthrough
Use the following upstream sources to verify implementation details while reading this chapter:
diff --git a/tutorials/whisper-cpp-tutorial/01-getting-started.md b/tutorials/whisper-cpp-tutorial/01-getting-started.md
index 19815b9e..f66822ab 100644
--- a/tutorials/whisper-cpp-tutorial/01-getting-started.md
+++ b/tutorials/whisper-cpp-tutorial/01-getting-started.md
@@ -10,6 +10,16 @@ nav_order: 1
Welcome to Whisper.cpp! If you've ever wanted to add speech recognition capabilities to your applications, you're in the right place. Whisper.cpp brings the power of OpenAI's Whisper model to C/C++ applications with exceptional performance and minimal dependencies.
## What Problem Does Whisper.cpp Solve?
+```mermaid
+flowchart LR
+ A[Audio File] --> B[whisper_init_from_file]
+ B --> C[whisper_context]
+ C --> D[whisper_full]
+ D --> E[whisper_full_n_segments]
+ E --> F[Text Output]
+ G[Model File .bin] --> B
+```
+
Traditional speech recognition solutions often require:
- **Expensive cloud APIs** with usage costs and latency
diff --git a/tutorials/whisper-cpp-tutorial/02-audio-processing.md b/tutorials/whisper-cpp-tutorial/02-audio-processing.md
index cbd10c11..1f598bab 100644
--- a/tutorials/whisper-cpp-tutorial/02-audio-processing.md
+++ b/tutorials/whisper-cpp-tutorial/02-audio-processing.md
@@ -13,6 +13,15 @@ Welcome to **Chapter 2: Audio Processing Fundamentals**. In this part of **Whisp
Welcome back! Now that you have Whisper.cpp up and running, let's dive into the fascinating world of audio processing. Understanding how audio works is crucial for getting the best results from speech recognition systems. In this chapter, we'll explore the fundamentals of digital audio and how Whisper.cpp processes sound.
## What Makes Audio Processing Important?
+```mermaid
+flowchart LR
+ A[Raw Audio WAV/MP3] --> B[16kHz Resampling]
+ B --> C[Mono Channel]
+ C --> D[Float32 Normalization]
+ D --> E[Mel Spectrogram 80 bins]
+ E --> F[Whisper Encoder]
+```
+
Imagine trying to read a book where all the letters are jumbled together - that's what raw audio looks like to a computer! Audio processing transforms continuous sound waves into a format that machine learning models can understand and work with.
diff --git a/tutorials/whisper-cpp-tutorial/04-core-api.md b/tutorials/whisper-cpp-tutorial/04-core-api.md
index e0596e60..17a323b5 100644
--- a/tutorials/whisper-cpp-tutorial/04-core-api.md
+++ b/tutorials/whisper-cpp-tutorial/04-core-api.md
@@ -23,6 +23,18 @@ By the end of this chapter, you'll understand:
- Advanced API features and callbacks
## 🏗️ Core API Architecture
+```mermaid
+flowchart TD
+ A[whisper_init_from_file path] --> B[whisper_context]
+ B --> C[whisper_full ctx params pcm n_samples]
+ C --> D{Success?}
+ D -->|yes| E[whisper_full_n_segments ctx]
+ D -->|no| F[Error handling]
+ E --> G[whisper_full_get_segment_text ctx i]
+ G --> H[Text output]
+ B --> I[whisper_free ctx]
+```
+
### **Main Data Structures**
diff --git a/tutorials/windmill-tutorial/01-getting-started.md b/tutorials/windmill-tutorial/01-getting-started.md
index 4340d750..2f340d27 100644
--- a/tutorials/windmill-tutorial/01-getting-started.md
+++ b/tutorials/windmill-tutorial/01-getting-started.md
@@ -252,6 +252,17 @@ wmill push
The CLI enables git-based workflows: write scripts locally, version them in Git, and deploy via CI/CD.
+## Source Code Walkthrough
+
+### Windmill TypeScript worker — `backend/windmill-worker/src/worker.rs`
+
+Windmill's worker runtime is written in Rust. The [`backend/windmill-worker/src/worker.rs`](https://github.com/windmill-labs/windmill/blob/main/backend/windmill-worker/src/worker.rs) file shows how jobs are dequeued, dispatched to the correct language runtime (Deno for TypeScript, Python subprocess, etc.), and how results are returned. This is what runs every time you execute a script.
+
+### Auto-generated webhook — `backend/windmill-api/src/jobs.rs`
+
+Script webhook endpoints are generated automatically. [`backend/windmill-api/src/jobs.rs`](https://github.com/windmill-labs/windmill/blob/main/backend/windmill-api/src/jobs.rs) implements the `/api/w/{workspace}/jobs/run/p/{path}` route that the auto-generated webhook calls — showing exactly how script path maps to a REST endpoint.
+
+
## What Just Happened
In this chapter you:
diff --git a/tutorials/windmill-tutorial/02-architecture-and-runtimes.md b/tutorials/windmill-tutorial/02-architecture-and-runtimes.md
index 3e90c148..a0e7a1db 100644
--- a/tutorials/windmill-tutorial/02-architecture-and-runtimes.md
+++ b/tutorials/windmill-tutorial/02-architecture-and-runtimes.md
@@ -291,6 +291,17 @@ console.log(job.result); // the return value of your script
- **Throughput**: a single worker handles ~26 million jobs/month (Windmill benchmark)
- **Horizontal scaling**: add more workers to increase throughput linearly
+## Source Code Walkthrough
+
+### Worker dispatcher — `backend/windmill-worker/src/worker.rs`
+
+The central dispatch logic in [`backend/windmill-worker/src/worker.rs`](https://github.com/windmill-labs/windmill/blob/main/backend/windmill-worker/src/worker.rs) routes jobs to language-specific execution handlers. The match on `language` field shows exactly how TypeScript jobs go to the Deno runtime, Python to the Python subprocess executor, Go to the Go compiler, etc.
+
+### Job queue — `backend/windmill-queue/src/queues.rs`
+
+[`backend/windmill-queue/src/queues.rs`](https://github.com/windmill-labs/windmill/blob/main/backend/windmill-queue/src/queues.rs) implements the PostgreSQL-backed job queue: `push_job`, `pull_job`, and the polling loop that workers use to claim new work. This is the core of Windmill's distributed execution model.
+
+
## What You Learned
In this chapter you:
diff --git a/tutorials/windmill-tutorial/03-script-development.md b/tutorials/windmill-tutorial/03-script-development.md
index 4d72e49d..65d68255 100644
--- a/tutorials/windmill-tutorial/03-script-development.md
+++ b/tutorials/windmill-tutorial/03-script-development.md
@@ -464,6 +464,17 @@ export async function main() {
| `cache_ttl` | Cache results for N seconds |
| `concurrency_limit` | Max simultaneous executions |
+## Source Code Walkthrough
+
+### TypeScript Deno executor — `backend/windmill-worker/src/deno_executor.rs`
+
+[`backend/windmill-worker/src/deno_executor.rs`](https://github.com/windmill-labs/windmill/blob/main/backend/windmill-worker/src/deno_executor.rs) shows how TypeScript scripts are executed via Deno. It handles resource injection (making `Bun.env` available for secrets), import map generation for dependencies, and result capture from stdout.
+
+### Python executor — `backend/windmill-worker/src/python_executor.rs`
+
+[`backend/windmill-worker/src/python_executor.rs`](https://github.com/windmill-labs/windmill/blob/main/backend/windmill-worker/src/python_executor.rs) implements Python script execution: virtual environment creation, `requirements.txt` installation, and how Windmill injects `wmill` client for resources and variables.
+
+
## What You Learned
In this chapter you:
diff --git a/tutorials/windmill-tutorial/04-flow-builder-and-workflows.md b/tutorials/windmill-tutorial/04-flow-builder-and-workflows.md
index 82b61bb1..21e517df 100644
--- a/tutorials/windmill-tutorial/04-flow-builder-and-workflows.md
+++ b/tutorials/windmill-tutorial/04-flow-builder-and-workflows.md
@@ -412,6 +412,17 @@ When a flow fails:
3. Click a failed step to see the full error and logs
4. Use **Restart from step** to re-run from the failure point
+## Source Code Walkthrough
+
+### Flow execution — `backend/windmill-worker/src/flow_status_helpers.rs`
+
+[`backend/windmill-worker/src/flow_status_helpers.rs`](https://github.com/windmill-labs/windmill/blob/main/backend/windmill-worker/src/flow_status_helpers.rs) implements the DAG execution engine: step sequencing, branch evaluation, loop iteration, and suspend/resume for approval steps. This is where flow state transitions are managed.
+
+### Flow API — `backend/windmill-api/src/flows.rs`
+
+[`backend/windmill-api/src/flows.rs`](https://github.com/windmill-labs/windmill/blob/main/backend/windmill-api/src/flows.rs) handles flow CRUD operations and defines the JSON schema for flow modules (step, branchall, branchone, for-loop, flow). Reviewing this shows the data model behind the visual Flow Builder.
+
+
## What You Learned
In this chapter you:
diff --git a/tutorials/windmill-tutorial/05-app-builder-and-uis.md b/tutorials/windmill-tutorial/05-app-builder-and-uis.md
index 759e739d..93e5e461 100644
--- a/tutorials/windmill-tutorial/05-app-builder-and-uis.md
+++ b/tutorials/windmill-tutorial/05-app-builder-and-uis.md
@@ -399,6 +399,17 @@ Global CSS can be added in the app settings for consistent styling across all co
Published apps are accessible at: `http://localhost:8000/apps/get/f/apps/user_dashboard`
+## Source Code Walkthrough
+
+### App frontend — `frontend/src/lib/components/apps/`
+
+The App Builder UI components live in [`frontend/src/lib/components/apps/`](https://github.com/windmill-labs/windmill/tree/main/frontend/src/lib/components/apps). This directory contains the drag-and-drop canvas, individual component renderers (Button, Table, Chart, etc.), and the component configuration panels. The Svelte components show exactly how apps are serialized and rendered.
+
+### App runtime — `backend/windmill-api/src/apps.rs`
+
+[`backend/windmill-api/src/apps.rs`](https://github.com/windmill-labs/windmill/blob/main/backend/windmill-api/src/apps.rs) handles app publication, versioning, and the policy system that controls what script paths an app can call. This governs the permissions model for published internal tools.
+
+
## What You Learned
In this chapter you:
diff --git a/tutorials/windmill-tutorial/06-scheduling-and-triggers.md b/tutorials/windmill-tutorial/06-scheduling-and-triggers.md
index 0461d468..daa0e6cf 100644
--- a/tutorials/windmill-tutorial/06-scheduling-and-triggers.md
+++ b/tutorials/windmill-tutorial/06-scheduling-and-triggers.md
@@ -406,6 +406,17 @@ Navigate to **Runs** in the UI and filter by schedule path. Each run shows:
- Result or error
- Worker that executed the job
+## Source Code Walkthrough
+
+### Scheduler — `backend/windmill-worker/src/schedule.rs`
+
+[`backend/windmill-worker/src/schedule.rs`](https://github.com/windmill-labs/windmill/blob/main/backend/windmill-worker/src/schedule.rs) implements cron-based scheduling: cron expression parsing, next-run calculation, and job push on schedule tick. The schedule checker runs on a background thread and fires jobs when cron expressions match.
+
+### Webhook handler — `backend/windmill-api/src/jobs.rs`
+
+The webhook endpoint in [`backend/windmill-api/src/jobs.rs`](https://github.com/windmill-labs/windmill/blob/main/backend/windmill-api/src/jobs.rs) implements token-authenticated HTTP triggers for scripts and flows. The `run_script_by_path` handler shows how webhook payloads are validated and converted to job queue entries.
+
+
## What You Learned
In this chapter you:
diff --git a/tutorials/windmill-tutorial/07-variables-secrets-and-resources.md b/tutorials/windmill-tutorial/07-variables-secrets-and-resources.md
index 86712c7b..7f37c907 100644
--- a/tutorials/windmill-tutorial/07-variables-secrets-and-resources.md
+++ b/tutorials/windmill-tutorial/07-variables-secrets-and-resources.md
@@ -429,6 +429,17 @@ export async function main(
}
```
+## Source Code Walkthrough
+
+### Variables and secrets — `backend/windmill-api/src/variables.rs`
+
+[`backend/windmill-api/src/variables.rs`](https://github.com/windmill-labs/windmill/blob/main/backend/windmill-api/src/variables.rs) implements the Variables API: creation, encryption for secrets (AES-256-GCM via the `magic_crypt` crate), workspace scoping, and the permission model that prevents unauthorized reads. This is where secret encryption happens.
+
+### Resource types — `backend/windmill-api/src/resources.rs`
+
+[`backend/windmill-api/src/resources.rs`](https://github.com/windmill-labs/windmill/blob/main/backend/windmill-api/src/resources.rs) implements typed resources: JSON Schema validation for resource values, OAuth token refresh logic for OAuth resource types, and the `r/` path prefix that scripts use to reference resources in their type signatures.
+
+
## What You Learned
In this chapter you:
diff --git a/tutorials/windmill-tutorial/08-self-hosting-and-production.md b/tutorials/windmill-tutorial/08-self-hosting-and-production.md
index 87690679..a187fe11 100644
--- a/tutorials/windmill-tutorial/08-self-hosting-and-production.md
+++ b/tutorials/windmill-tutorial/08-self-hosting-and-production.md
@@ -580,6 +580,17 @@ helm upgrade windmill windmill/windmill \
--set windmill.image.tag=latest
```
+## Source Code Walkthrough
+
+### Docker Compose — `docker-compose.yml`
+
+The official [`docker-compose.yml`](https://github.com/windmill-labs/windmill/blob/main/docker-compose.yml) at the repo root is the recommended production deployment template. It defines the server, worker(s), PostgreSQL, and Caddy reverse proxy services — all the components described in this chapter's self-hosting section.
+
+### Worker scaling — `backend/windmill-worker/src/worker.rs`
+
+The worker process entry point in [`backend/windmill-worker/src/worker.rs`](https://github.com/windmill-labs/windmill/blob/main/backend/windmill-worker/src/worker.rs) reads `NUM_WORKERS`, `WORKER_TAGS`, and concurrency settings from environment variables. Worker pools (native, gpu, etc.) are configured by setting `WORKER_TAGS` to specific tag sets — the horizontal scaling model described in this chapter.
+
+
## What You Learned
In this chapter you:
diff --git a/tutorials/wshobson-agents-tutorial/01-getting-started.md b/tutorials/wshobson-agents-tutorial/01-getting-started.md
index 3c19dea4..f63b9350 100644
--- a/tutorials/wshobson-agents-tutorial/01-getting-started.md
+++ b/tutorials/wshobson-agents-tutorial/01-getting-started.md
@@ -57,98 +57,24 @@ You now have a working baseline installation and first command surface.
Next: [Chapter 2: Marketplace Architecture and Plugin Structure](02-marketplace-architecture-and-plugin-structure.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `tools/yt-design-extractor.py`
-
-The `extract_video_id` function in [`tools/yt-design-extractor.py`](https://github.com/wshobson/agents/blob/HEAD/tools/yt-design-extractor.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def extract_video_id(url: str) -> str:
- """Pull the 11-char video ID out of any common YouTube URL format."""
- patterns = [
- r"(?:v=|/v/|youtu\.be/)([a-zA-Z0-9_-]{11})",
- r"(?:embed/)([a-zA-Z0-9_-]{11})",
- r"(?:shorts/)([a-zA-Z0-9_-]{11})",
- ]
- for pat in patterns:
- m = re.search(pat, url)
- if m:
- return m.group(1)
- # Maybe the user passed a bare ID
- if re.match(r"^[a-zA-Z0-9_-]{11}$", url):
- return url
- sys.exit(f"Could not extract video ID from: {url}")
-
-
-def get_video_metadata(url: str) -> dict:
- """Use yt-dlp to pull title, description, chapters, duration, etc."""
- cmd = [
- "yt-dlp",
- "--dump-json",
- "--no-download",
- "--no-playlist",
- url,
- ]
- print("[*] Fetching video metadata …")
- try:
- result = subprocess.run(cmd, capture_output=True, text=True, timeout=120)
- except subprocess.TimeoutExpired:
-```
+> **Note:** `wshobson/agents` is a collection of Claude Code plugin definitions (YAML/Markdown), not a traditional compiled library. The "source code" is the plugin manifest and prompt files themselves. The relevant files for this chapter are the plugin installation interface and marketplace metadata.
-This function is important because it defines how Wshobson Agents Tutorial: Pluginized Multi-Agent Workflows for Claude Code implements the patterns covered in this chapter.
-
-### `tools/yt-design-extractor.py`
-
-The `get_video_metadata` function in [`tools/yt-design-extractor.py`](https://github.com/wshobson/agents/blob/HEAD/tools/yt-design-extractor.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def get_video_metadata(url: str) -> dict:
- """Use yt-dlp to pull title, description, chapters, duration, etc."""
- cmd = [
- "yt-dlp",
- "--dump-json",
- "--no-download",
- "--no-playlist",
- url,
- ]
- print("[*] Fetching video metadata …")
- try:
- result = subprocess.run(cmd, capture_output=True, text=True, timeout=120)
- except subprocess.TimeoutExpired:
- sys.exit("yt-dlp metadata fetch timed out after 120s.")
- if result.returncode != 0:
- sys.exit(f"yt-dlp metadata failed:\n{result.stderr}")
- try:
- return json.loads(result.stdout)
- except json.JSONDecodeError as e:
- sys.exit(
- f"yt-dlp returned invalid JSON: {e}\nFirst 200 chars: {result.stdout[:200]}"
- )
-
-
-def get_transcript(video_id: str) -> list[dict] | None:
- """Grab the transcript via youtube-transcript-api. Returns list of
- {text, start, duration} dicts, or None if unavailable."""
- try:
- from youtube_transcript_api import YouTubeTranscriptApi
- from youtube_transcript_api._errors import (
-```
+### `.claude-plugin/marketplace.json`
+
+The marketplace metadata file at [`/.claude-plugin/marketplace.json`](https://github.com/wshobson/agents/blob/main/.claude-plugin/marketplace.json) defines the plugin catalog that `/plugin marketplace add wshobson/agents` installs. It lists available plugins, their categories, and discovery metadata — this is the entry point for the Getting Started workflow.
-This function is important because it defines how Wshobson Agents Tutorial: Pluginized Multi-Agent Workflows for Claude Code implements the patterns covered in this chapter.
+### `README.md` Quick Start section
+The [Quick Start section of the README](https://github.com/wshobson/agents/blob/main/README.md#quick-start) documents the exact `/plugin` commands used in this chapter and explains the intended first-session operating pattern.
## How These Components Connect
```mermaid
flowchart TD
- A[extract_video_id]
- B[get_video_metadata]
- A --> B
+ A[marketplace.json] -->|defines| B[plugin catalog]
+ B -->|/plugin marketplace add| C[Claude Code plugin install]
+ C -->|/plugin install python-development| D[plugin activated]
+ D --> E[slash commands available]
```
diff --git a/tutorials/wshobson-agents-tutorial/02-marketplace-architecture-and-plugin-structure.md b/tutorials/wshobson-agents-tutorial/02-marketplace-architecture-and-plugin-structure.md
index a8b6562c..fd3d44c4 100644
--- a/tutorials/wshobson-agents-tutorial/02-marketplace-architecture-and-plugin-structure.md
+++ b/tutorials/wshobson-agents-tutorial/02-marketplace-architecture-and-plugin-structure.md
@@ -58,98 +58,27 @@ You now understand the composable architecture that powers the ecosystem.
Next: [Chapter 3: Installation and Plugin Selection Strategy](03-installation-and-plugin-selection-strategy.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `tools/yt-design-extractor.py`
-
-The `get_transcript` function in [`tools/yt-design-extractor.py`](https://github.com/wshobson/agents/blob/HEAD/tools/yt-design-extractor.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def get_transcript(video_id: str) -> list[dict] | None:
- """Grab the transcript via youtube-transcript-api. Returns list of
- {text, start, duration} dicts, or None if unavailable."""
- try:
- from youtube_transcript_api import YouTubeTranscriptApi
- from youtube_transcript_api._errors import (
- TranscriptsDisabled,
- NoTranscriptFound,
- VideoUnavailable,
- )
- except ImportError:
- print("[!] youtube-transcript-api not installed. Skipping transcript.")
- return None
-
- try:
- print("[*] Fetching transcript …")
- ytt_api = YouTubeTranscriptApi()
- transcript = ytt_api.fetch(video_id)
- entries = []
- for snippet in transcript:
- entries.append(
- {
- "text": snippet.text,
- "start": snippet.start,
- "duration": snippet.duration,
- }
- )
- return entries
- except (TranscriptsDisabled, NoTranscriptFound, VideoUnavailable) as e:
- print(f"[!] Transcript unavailable ({e}). Will proceed without it.")
-```
+> **Note:** `wshobson/agents` is a collection of Claude Code plugin definitions (YAML/Markdown prompt files), not a traditional compiled library. The architecture is expressed through directory structure and file conventions rather than executable code.
-This function is important because it defines how Wshobson Agents Tutorial: Pluginized Multi-Agent Workflows for Claude Code implements the patterns covered in this chapter.
-
-### `tools/yt-design-extractor.py`
-
-The `download_video` function in [`tools/yt-design-extractor.py`](https://github.com/wshobson/agents/blob/HEAD/tools/yt-design-extractor.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def download_video(url: str, out_dir: Path) -> Path:
- """Download video, preferring 720p or lower. Falls back to best available."""
- out_template = str(out_dir / "video.%(ext)s")
- cmd = [
- "yt-dlp",
- "-f",
- "bestvideo[height<=720]+bestaudio/best[height<=720]/best",
- "--merge-output-format",
- "mp4",
- "-o",
- out_template,
- "--no-playlist",
- url,
- ]
- print("[*] Downloading video (720p preferred) …")
- try:
- result = subprocess.run(cmd, capture_output=True, text=True, timeout=600)
- except subprocess.TimeoutExpired:
- sys.exit(
- "Video download timed out after 10 minutes. "
- "The video may be too large or your connection too slow."
- )
- if result.returncode != 0:
- sys.exit(f"yt-dlp download failed:\n{result.stderr}")
-
- # Find the downloaded file
- for f in out_dir.iterdir():
- if f.name.startswith("video.") and f.suffix in (".mp4", ".mkv", ".webm"):
- return f
- sys.exit("Download succeeded but could not locate video file.")
-```
+### `docs/architecture.md`
+
+The [architecture guide](https://github.com/wshobson/agents/blob/main/docs/architecture.md) explains the composable plugin design: how `plugins/<name>/agents/`, `plugins/<name>/commands/`, and `plugins/<name>/skills/` directories implement the single-responsibility principle described in this chapter.
-This function is important because it defines how Wshobson Agents Tutorial: Pluginized Multi-Agent Workflows for Claude Code implements the patterns covered in this chapter.
+### `.claude-plugin/marketplace.json`
+The [marketplace manifest](https://github.com/wshobson/agents/blob/main/.claude-plugin/marketplace.json) is the structural root of the plugin catalog — it maps plugin names to their directory paths, categories, and descriptions, making the composability model concrete.
## How These Components Connect
```mermaid
flowchart TD
- A[get_transcript]
- B[download_video]
- A --> B
+ A[marketplace.json] -->|catalog metadata| B[Plugin Discovery]
+ B -->|points to| C[plugins/name/agents/]
+ B -->|points to| D[plugins/name/commands/]
+ B -->|points to| E[plugins/name/skills/]
+ C --> F[specialist agent prompt files]
+ D --> G[slash command definitions]
+ E --> H[progressive-disclosure skill packs]
```
diff --git a/tutorials/wshobson-agents-tutorial/03-installation-and-plugin-selection-strategy.md b/tutorials/wshobson-agents-tutorial/03-installation-and-plugin-selection-strategy.md
index afb10e54..18c15de8 100644
--- a/tutorials/wshobson-agents-tutorial/03-installation-and-plugin-selection-strategy.md
+++ b/tutorials/wshobson-agents-tutorial/03-installation-and-plugin-selection-strategy.md
@@ -67,98 +67,27 @@ You now have a practical method for controlled plugin adoption.
Next: [Chapter 4: Commands, Natural Language, and Workflow Orchestration](04-commands-natural-language-and-workflow-orchestration.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `tools/yt-design-extractor.py`
-
-The `extract_frames_interval` function in [`tools/yt-design-extractor.py`](https://github.com/wshobson/agents/blob/HEAD/tools/yt-design-extractor.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def extract_frames_interval(
- video_path: Path, out_dir: Path, interval: int = 30
-) -> list[Path]:
- """Extract one frame every `interval` seconds."""
- frames_dir = out_dir / "frames"
- frames_dir.mkdir(exist_ok=True)
- pattern = str(frames_dir / "frame_%04d.png")
- cmd = [
- "ffmpeg",
- "-i",
- str(video_path),
- "-vf",
- f"fps=1/{interval}",
- "-q:v",
- "2",
- pattern,
- "-y",
- ]
- print(f"[*] Extracting frames every {interval}s …")
- try:
- result = subprocess.run(cmd, capture_output=True, text=True, timeout=600)
- except subprocess.TimeoutExpired:
- sys.exit("Frame extraction timed out after 10 minutes.")
- if result.returncode != 0:
- print(f"[!] ffmpeg frame extraction failed (exit code {result.returncode}):")
- print(f" {result.stderr[:500]}")
- return []
- frames = sorted(frames_dir.glob("frame_*.png"))
- if not frames:
- print(
-```
+> **Note:** `wshobson/agents` stores all behavior in plugin definition files (Markdown/YAML), not compiled source code. Plugin selection strategy is encoded in the catalog and documentation rather than executable functions.
-This function is important because it defines how Wshobson Agents Tutorial: Pluginized Multi-Agent Workflows for Claude Code implements the patterns covered in this chapter.
-
-### `tools/yt-design-extractor.py`
-
-The `extract_frames_scene` function in [`tools/yt-design-extractor.py`](https://github.com/wshobson/agents/blob/HEAD/tools/yt-design-extractor.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def extract_frames_scene(
- video_path: Path, out_dir: Path, threshold: float = 0.3
-) -> list[Path]:
- """Use ffmpeg scene-change detection to grab visually distinct frames."""
- frames_dir = out_dir / "frames_scene"
- frames_dir.mkdir(exist_ok=True)
- pattern = str(frames_dir / "scene_%04d.png")
- cmd = [
- "ffmpeg",
- "-i",
- str(video_path),
- "-vf",
- f"select='gt(scene,{threshold})',showinfo",
- "-vsync",
- "vfr",
- "-q:v",
- "2",
- pattern,
- "-y",
- ]
- print(f"[*] Extracting scene-change frames (threshold={threshold}) …")
- try:
- result = subprocess.run(cmd, capture_output=True, text=True, timeout=600)
- except subprocess.TimeoutExpired:
- sys.exit("Scene-change frame extraction timed out after 10 minutes.")
- if result.returncode != 0:
- print(f"[!] ffmpeg scene detection failed (exit code {result.returncode}):")
- print(f" {result.stderr[:500]}")
- return []
- frames = sorted(frames_dir.glob("scene_*.png"))
-```
+### `docs/plugins.md`
+
+The [plugin catalog documentation](https://github.com/wshobson/agents/blob/main/docs/plugins.md) is the primary reference for this chapter. It lists all available plugins by category (Backend, Frontend, Cloud, Security, etc.) and explains which workflows each plugin supports — the direct basis for the portfolio profiles described in this chapter.
-This function is important because it defines how Wshobson Agents Tutorial: Pluginized Multi-Agent Workflows for Claude Code implements the patterns covered in this chapter.
+### `docs/usage.md`
+The [usage guide](https://github.com/wshobson/agents/blob/main/docs/usage.md) explains the phased installation approach: start minimal, add plugins when workflow gaps emerge. This documents the anti-patterns around over-installation that this chapter covers.
## How These Components Connect
```mermaid
flowchart TD
- A[extract_frames_interval]
- B[extract_frames_scene]
- A --> B
+ A[docs/plugins.md] -->|catalog by category| B[Plugin Selection]
+ B -->|solo engineer profile| C[backend + frontend + review plugins]
+ B -->|platform team profile| D[cloud + kubernetes + cicd plugins]
+ B -->|data/LLM team profile| E[llm + data-engineering + mlops plugins]
+ C --> F[controlled installation]
+ D --> F
+ E --> F
```
diff --git a/tutorials/wshobson-agents-tutorial/04-commands-natural-language-and-workflow-orchestration.md b/tutorials/wshobson-agents-tutorial/04-commands-natural-language-and-workflow-orchestration.md
index dcb9901b..aa59200c 100644
--- a/tutorials/wshobson-agents-tutorial/04-commands-natural-language-and-workflow-orchestration.md
+++ b/tutorials/wshobson-agents-tutorial/04-commands-natural-language-and-workflow-orchestration.md
@@ -63,98 +63,28 @@ You now have a balanced command/NL operating model for reliable multi-agent work
Next: [Chapter 5: Agents, Skills, and Model Tier Strategy](05-agents-skills-and-model-tier-strategy.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `tools/yt-design-extractor.py`
-
-The `ocr_frame_tesseract` function in [`tools/yt-design-extractor.py`](https://github.com/wshobson/agents/blob/HEAD/tools/yt-design-extractor.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def ocr_frame_tesseract(frame_path: Path) -> str:
- """Extract text from a frame using Tesseract OCR. Converts to grayscale first."""
- if not TESSERACT_AVAILABLE:
- return ""
- try:
- img = Image.open(frame_path)
- if img.mode != "L":
- img = img.convert("L")
- text = pytesseract.image_to_string(img, config="--psm 6")
- return text.strip()
- except Exception as e:
- print(f"[!] OCR failed for {frame_path}: {e}")
- return ""
-
-
-def ocr_frame_easyocr(frame_path: Path, reader) -> str:
- """Extract text from a frame using EasyOCR (better for stylized text)."""
- try:
- results = reader.readtext(str(frame_path), detail=0)
- return "\n".join(results).strip()
- except Exception as e:
- print(f"[!] OCR failed for {frame_path}: {e}")
- return ""
-
-
-def run_ocr_on_frames(
- frames: list[Path], ocr_engine: str = "tesseract", workers: int = 4
-) -> dict[Path, str]:
- """Run OCR on frames. Tesseract runs in parallel; EasyOCR sequentially.
- Returns {frame_path: text}."""
-```
+> **Note:** `wshobson/agents` is a prompt-file collection. Command invocation patterns are defined in the plugin command files, not in compiled source. The relevant references for this chapter are the command definition files and usage documentation.
-This function is important because it defines how Wshobson Agents Tutorial: Pluginized Multi-Agent Workflows for Claude Code implements the patterns covered in this chapter.
+### `docs/usage.md` — Command patterns
-### `tools/yt-design-extractor.py`
-
-The `ocr_frame_easyocr` function in [`tools/yt-design-extractor.py`](https://github.com/wshobson/agents/blob/HEAD/tools/yt-design-extractor.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def ocr_frame_easyocr(frame_path: Path, reader) -> str:
- """Extract text from a frame using EasyOCR (better for stylized text)."""
- try:
- results = reader.readtext(str(frame_path), detail=0)
- return "\n".join(results).strip()
- except Exception as e:
- print(f"[!] OCR failed for {frame_path}: {e}")
- return ""
-
-
-def run_ocr_on_frames(
- frames: list[Path], ocr_engine: str = "tesseract", workers: int = 4
-) -> dict[Path, str]:
- """Run OCR on frames. Tesseract runs in parallel; EasyOCR sequentially.
- Returns {frame_path: text}."""
- if not frames:
- return {}
-
- results = {}
-
- if ocr_engine == "easyocr":
- if not EASYOCR_AVAILABLE:
- sys.exit(
- "EasyOCR was explicitly requested but is not installed.\n"
- " Install: pip install torch torchvision --index-url "
- "https://download.pytorch.org/whl/cpu && pip install easyocr\n"
- " Or use: --ocr-engine tesseract"
- )
- else:
- print("[*] Initializing EasyOCR (this may take a moment) …")
-```
+The [usage guide](https://github.com/wshobson/agents/blob/main/docs/usage.md) documents both the slash-command invocation pattern (e.g. `/full-stack-orchestration:full-stack-feature`) and the natural-language fallback approach. It also covers the hybrid workflow pattern (command scaffold + NL refinement) described in this chapter.
-This function is important because it defines how Wshobson Agents Tutorial: Pluginized Multi-Agent Workflows for Claude Code implements the patterns covered in this chapter.
+### `plugins/` command files
+Individual command behavior is defined in files like [`plugins/full-stack-orchestration/commands/`](https://github.com/wshobson/agents/tree/main/plugins) — each command file specifies its arguments, default behaviors, and expected outputs, making the invocation contract explicit.
## How These Components Connect
```mermaid
flowchart TD
- A[ocr_frame_tesseract]
- B[ocr_frame_easyocr]
- A --> B
+ A[User Intent] -->|explicit args| B[Slash Command invocation]
+ A -->|open-ended task| C[Natural Language prompt]
+ B -->|predictable path| D[Command definition file]
+ C -->|agent reasoning| E[Dynamic agent selection]
+ D --> F[Deterministic output]
+ E --> G[Flexible output]
+ F --> H[Review command / quality gate]
+ G --> H
```
diff --git a/tutorials/wshobson-agents-tutorial/05-agents-skills-and-model-tier-strategy.md b/tutorials/wshobson-agents-tutorial/05-agents-skills-and-model-tier-strategy.md
index d47eb6a6..d53f479c 100644
--- a/tutorials/wshobson-agents-tutorial/05-agents-skills-and-model-tier-strategy.md
+++ b/tutorials/wshobson-agents-tutorial/05-agents-skills-and-model-tier-strategy.md
@@ -55,98 +55,27 @@ You now understand how to combine specialists, skills, and model strategy for be
Next: [Chapter 6: Multi-Agent Team Patterns and Production Workflows](06-multi-agent-team-patterns-and-production-workflows.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `tools/yt-design-extractor.py`
-
-The `run_ocr_on_frames` function in [`tools/yt-design-extractor.py`](https://github.com/wshobson/agents/blob/HEAD/tools/yt-design-extractor.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def run_ocr_on_frames(
- frames: list[Path], ocr_engine: str = "tesseract", workers: int = 4
-) -> dict[Path, str]:
- """Run OCR on frames. Tesseract runs in parallel; EasyOCR sequentially.
- Returns {frame_path: text}."""
- if not frames:
- return {}
-
- results = {}
-
- if ocr_engine == "easyocr":
- if not EASYOCR_AVAILABLE:
- sys.exit(
- "EasyOCR was explicitly requested but is not installed.\n"
- " Install: pip install torch torchvision --index-url "
- "https://download.pytorch.org/whl/cpu && pip install easyocr\n"
- " Or use: --ocr-engine tesseract"
- )
- else:
- print("[*] Initializing EasyOCR (this may take a moment) …")
- reader = easyocr.Reader(["en"], gpu=False, verbose=False)
-
- if ocr_engine == "tesseract" and not TESSERACT_AVAILABLE:
- print("[!] Tesseract/pytesseract not installed, skipping OCR")
- return {}
-
- print(f"[*] Running OCR on {len(frames)} frames ({ocr_engine}) …")
-
- if ocr_engine == "easyocr":
- # EasyOCR doesn't parallelize well, run sequentially
-```
-
-This function is important because it defines how Wshobson Agents Tutorial: Pluginized Multi-Agent Workflows for Claude Code implements the patterns covered in this chapter.
-
-### `tools/yt-design-extractor.py`
-
-The `extract_color_palette` function in [`tools/yt-design-extractor.py`](https://github.com/wshobson/agents/blob/HEAD/tools/yt-design-extractor.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def extract_color_palette(frame_path: Path, color_count: int = 6) -> list[tuple]:
- """Extract dominant colors from a frame. Returns list of RGB tuples."""
- if not COLORTHIEF_AVAILABLE:
- return []
- try:
- ct = ColorThief(str(frame_path))
- palette = ct.get_palette(color_count=color_count, quality=5)
- return palette
- except Exception as e:
- print(f"[!] Color extraction failed for {frame_path}: {e}")
- return []
+> **Note:** `wshobson/agents` defines agent behavior through prompt files and documentation, not compiled code. Specialist agent personas, skill packs, and model tier guidance all live in Markdown files within the plugin directories.
+### `docs/agents.md`
-def rgb_to_hex(rgb: tuple) -> str:
- """Convert RGB tuple to hex color string."""
- return "#{:02x}{:02x}{:02x}".format(*rgb)
-
-
-def analyze_color_palettes(frames: list[Path], sample_size: int = 10) -> dict:
- """Analyze color palettes across sampled frames."""
- if not COLORTHIEF_AVAILABLE:
- return {}
- if not frames:
- return {}
-
- # Sample frames evenly across the video
- step = max(1, len(frames) // sample_size)
- sampled = frames[::step][:sample_size]
-
- print(f"[*] Extracting color palettes from {len(sampled)} frames …")
-```
+The [agent reference](https://github.com/wshobson/agents/blob/main/docs/agents.md) catalogs all available specialist agents (backend-architect, security-auditor, performance-engineer, etc.) and explains their roles. This is the primary source for the agent-category coverage and specialization concepts in this chapter.
-This function is important because it defines how Wshobson Agents Tutorial: Pluginized Multi-Agent Workflows for Claude Code implements the patterns covered in this chapter.
+### `docs/agent-skills.md`
+The [agent skills guide](https://github.com/wshobson/agents/blob/main/docs/agent-skills.md) documents how skill packs activate progressive-disclosure domain knowledge on demand — the mechanism this chapter covers for narrowing context to high-value specializations without token bloat.
## How These Components Connect
```mermaid
flowchart TD
- A[run_ocr_on_frames]
- B[extract_color_palette]
- A --> B
+ A[docs/agents.md] -->|specialist personas| B[Agent Assignment]
+ C[docs/agent-skills.md] -->|skill activation| D[Domain Knowledge Injection]
+ B --> E[Task Execution]
+ D --> E
+ E -->|high-criticality| F[strongest model tier]
+ E -->|implementation task| G[balanced model tier]
+ E -->|deterministic ops| H[cost-efficient model tier]
```
diff --git a/tutorials/wshobson-agents-tutorial/06-multi-agent-team-patterns-and-production-workflows.md b/tutorials/wshobson-agents-tutorial/06-multi-agent-team-patterns-and-production-workflows.md
index eb50e091..20c3b9d6 100644
--- a/tutorials/wshobson-agents-tutorial/06-multi-agent-team-patterns-and-production-workflows.md
+++ b/tutorials/wshobson-agents-tutorial/06-multi-agent-team-patterns-and-production-workflows.md
@@ -59,98 +59,27 @@ You now have concrete patterns for reliable multi-agent collaboration.
Next: [Chapter 7: Governance, Safety, and Operational Best Practices](07-governance-safety-and-operational-best-practices.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `tools/yt-design-extractor.py`
-
-The `rgb_to_hex` function in [`tools/yt-design-extractor.py`](https://github.com/wshobson/agents/blob/HEAD/tools/yt-design-extractor.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def rgb_to_hex(rgb: tuple) -> str:
- """Convert RGB tuple to hex color string."""
- return "#{:02x}{:02x}{:02x}".format(*rgb)
-
-
-def analyze_color_palettes(frames: list[Path], sample_size: int = 10) -> dict:
- """Analyze color palettes across sampled frames."""
- if not COLORTHIEF_AVAILABLE:
- return {}
- if not frames:
- return {}
-
- # Sample frames evenly across the video
- step = max(1, len(frames) // sample_size)
- sampled = frames[::step][:sample_size]
-
- print(f"[*] Extracting color palettes from {len(sampled)} frames …")
-
- all_colors = []
- for frame in sampled:
- palette = extract_color_palette(frame)
- all_colors.extend(palette)
-
- if not all_colors:
- return {}
-
- # Find most common colors (rounded to reduce similar colors)
- def round_color(rgb, bucket_size=32):
- return tuple((c // bucket_size) * bucket_size for c in rgb)
-
-```
-
-This function is important because it defines how Wshobson Agents Tutorial: Pluginized Multi-Agent Workflows for Claude Code implements the patterns covered in this chapter.
-
-### `tools/yt-design-extractor.py`
-
-The `analyze_color_palettes` function in [`tools/yt-design-extractor.py`](https://github.com/wshobson/agents/blob/HEAD/tools/yt-design-extractor.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def analyze_color_palettes(frames: list[Path], sample_size: int = 10) -> dict:
- """Analyze color palettes across sampled frames."""
- if not COLORTHIEF_AVAILABLE:
- return {}
- if not frames:
- return {}
+> **Note:** `wshobson/agents` expresses multi-agent team patterns through plugin compositions and documentation, not executable source code. The `plugins/agent-teams` directory and usage guide document the orchestration patterns covered here.
- # Sample frames evenly across the video
- step = max(1, len(frames) // sample_size)
- sampled = frames[::step][:sample_size]
+### `plugins/agent-teams/`
- print(f"[*] Extracting color palettes from {len(sampled)} frames …")
-
- all_colors = []
- for frame in sampled:
- palette = extract_color_palette(frame)
- all_colors.extend(palette)
-
- if not all_colors:
- return {}
-
- # Find most common colors (rounded to reduce similar colors)
- def round_color(rgb, bucket_size=32):
- return tuple((c // bucket_size) * bucket_size for c in rgb)
-
- rounded = [round_color(c) for c in all_colors]
- most_common = Counter(rounded).most_common(12)
-
- return {
- "dominant_colors": [rgb_to_hex(c) for c, _ in most_common[:6]],
-```
+The [`plugins/agent-teams/` directory](https://github.com/wshobson/agents/tree/main/plugins/agent-teams) contains the agent-teams plugin definition. This plugin is specifically designed for coordinated multi-agent workflows — it defines team compositions, handoff patterns, and the orchestration commands referenced in this chapter's Full-Stack Feature Flow and Team Review Flow patterns.
-This function is important because it defines how Wshobson Agents Tutorial: Pluginized Multi-Agent Workflows for Claude Code implements the patterns covered in this chapter.
+### `docs/usage.md` — Multi-agent workflow examples
+The [multi-agent workflow examples section](https://github.com/wshobson/agents/blob/main/docs/usage.md#multi-agent-workflow-examples) in the usage guide documents concrete orchestration sequences for feature development, review, and incident response — the three patterns this chapter covers.
## How These Components Connect
```mermaid
flowchart TD
- A[rgb_to_hex]
- B[analyze_color_palettes]
- A --> B
+ A[plugins/agent-teams/] -->|team compositions| B[Multi-Agent Orchestration]
+ B -->|full-stack feature| C[architecture → implementation → security → deploy]
+ B -->|team review| D[split concerns → aggregate → prioritize]
+ B -->|incident response| E[triage → fix → regression guard]
+ C --> F[Production guardrail: explicit scope + final review]
+ D --> F
+ E --> F
```
diff --git a/tutorials/wshobson-agents-tutorial/07-governance-safety-and-operational-best-practices.md b/tutorials/wshobson-agents-tutorial/07-governance-safety-and-operational-best-practices.md
index b53b0471..5f565214 100644
--- a/tutorials/wshobson-agents-tutorial/07-governance-safety-and-operational-best-practices.md
+++ b/tutorials/wshobson-agents-tutorial/07-governance-safety-and-operational-best-practices.md
@@ -53,98 +53,27 @@ You now have a governance model for scaling plugin-based agent operations.
Next: [Chapter 8: Contribution Workflow and Plugin Authoring Patterns](08-contribution-workflow-and-plugin-authoring-patterns.md)
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `tools/yt-design-extractor.py`
-
-The `fmt_timestamp` function in [`tools/yt-design-extractor.py`](https://github.com/wshobson/agents/blob/HEAD/tools/yt-design-extractor.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def fmt_timestamp(seconds: float) -> str:
- m, s = divmod(int(seconds), 60)
- h, m = divmod(m, 60)
- if h:
- return f"{h}:{m:02d}:{s:02d}"
- return f"{m}:{s:02d}"
+> **Note:** `wshobson/agents` governance patterns are expressed through documentation conventions and contributing guidelines, not executable source code. The relevant sources for this chapter are the contributing guide and plugin design principles docs.
+### `.github/CONTRIBUTING.md`
-def group_transcript(entries: list[dict], chunk_seconds: int = 60) -> list[dict]:
- """Merge transcript snippets into chunks of at least `chunk_seconds` duration."""
- if not entries:
- return []
- groups = []
- current = {"start": entries[0]["start"], "text": ""}
- for e in entries:
- if e["start"] - current["start"] >= chunk_seconds and current["text"]:
- groups.append(current)
- current = {"start": e["start"], "text": ""}
- current["text"] += " " + e["text"]
- if current["text"]:
- groups.append(current)
- for g in groups:
- g["text"] = g["text"].strip()
- return groups
-
-
-def build_markdown(
- meta: dict,
- transcript: list[dict] | None,
- interval_frames: list[Path],
-```
-
-This function is important because it defines how Wshobson Agents Tutorial: Pluginized Multi-Agent Workflows for Claude Code implements the patterns covered in this chapter.
-
-### `tools/yt-design-extractor.py`
-
-The `group_transcript` function in [`tools/yt-design-extractor.py`](https://github.com/wshobson/agents/blob/HEAD/tools/yt-design-extractor.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def group_transcript(entries: list[dict], chunk_seconds: int = 60) -> list[dict]:
- """Merge transcript snippets into chunks of at least `chunk_seconds` duration."""
- if not entries:
- return []
- groups = []
- current = {"start": entries[0]["start"], "text": ""}
- for e in entries:
- if e["start"] - current["start"] >= chunk_seconds and current["text"]:
- groups.append(current)
- current = {"start": e["start"], "text": ""}
- current["text"] += " " + e["text"]
- if current["text"]:
- groups.append(current)
- for g in groups:
- g["text"] = g["text"].strip()
- return groups
-
-
-def build_markdown(
- meta: dict,
- transcript: list[dict] | None,
- interval_frames: list[Path],
- scene_frames: list[Path],
- out_dir: Path,
- interval: int,
- ocr_results: Optional[dict[Path, str]] = None,
- color_analysis: Optional[dict] = None,
-) -> Path:
- """Assemble the final reference markdown document."""
- title = meta.get("title", "Untitled Video")
-```
+The [contributing guidelines](https://github.com/wshobson/agents/blob/main/.github/CONTRIBUTING.md) document the change-management process for plugin additions — the organizational equivalent of the approved-plugin-list and review checkpoint patterns described in this chapter.
-This function is important because it defines how Wshobson Agents Tutorial: Pluginized Multi-Agent Workflows for Claude Code implements the patterns covered in this chapter.
+### `docs/plugins.md` — Plugin design principles
+The [plugin design principles section](https://github.com/wshobson/agents/blob/main/docs/plugins.md#plugin-design-principles) specifies the single-responsibility requirement, overlap prevention, and explicit naming conventions that form the governance baseline. Following these principles prevents the plugin drift and command-surface sprawl this chapter guards against.
## How These Components Connect
```mermaid
flowchart TD
- A[fmt_timestamp]
- B[group_transcript]
- A --> B
+ A[.github/CONTRIBUTING.md] -->|change management| B[Plugin Addition Review]
+ C[docs/plugins.md design principles] -->|single-responsibility| D[Plugin Quality Gate]
+ B --> E[Approved Plugin List]
+ D --> E
+ E -->|enforce| F[Security scanning on prod-bound changes]
+ E -->|enforce| G[Explicit commands in sensitive workflows]
+ E -->|enforce| H[Periodic plugin pruning]
```
diff --git a/tutorials/wshobson-agents-tutorial/08-contribution-workflow-and-plugin-authoring-patterns.md b/tutorials/wshobson-agents-tutorial/08-contribution-workflow-and-plugin-authoring-patterns.md
index 6e51287c..11009d85 100644
--- a/tutorials/wshobson-agents-tutorial/08-contribution-workflow-and-plugin-authoring-patterns.md
+++ b/tutorials/wshobson-agents-tutorial/08-contribution-workflow-and-plugin-authoring-patterns.md
@@ -58,98 +58,27 @@ Next steps:
- codify command templates for repeatable workflows
- contribute one focused plugin or documentation improvement
-## Depth Expansion Playbook
-
## Source Code Walkthrough
-### `tools/yt-design-extractor.py`
-
-The `build_markdown` function in [`tools/yt-design-extractor.py`](https://github.com/wshobson/agents/blob/HEAD/tools/yt-design-extractor.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def build_markdown(
- meta: dict,
- transcript: list[dict] | None,
- interval_frames: list[Path],
- scene_frames: list[Path],
- out_dir: Path,
- interval: int,
- ocr_results: Optional[dict[Path, str]] = None,
- color_analysis: Optional[dict] = None,
-) -> Path:
- """Assemble the final reference markdown document."""
- title = meta.get("title", "Untitled Video")
- channel = meta.get("channel", meta.get("uploader", "Unknown"))
- duration = meta.get("duration", 0)
- description = meta.get("description", "")
- chapters = meta.get("chapters") or []
- video_url = meta.get("webpage_url", "")
- tags = meta.get("tags") or []
-
- ocr_results = ocr_results or {}
- color_analysis = color_analysis or {}
-
- lines: list[str] = []
-
- # --- Header ---
- lines.append(f"# {title}\n")
- lines.append(f"> **Source:** [{channel}]({video_url}) ")
- lines.append(f"> **Duration:** {fmt_timestamp(duration)} ")
- lines.append(f"> **Extracted:** {datetime.now().strftime('%Y-%m-%d %H:%M')} ")
- if tags:
-```
+> **Note:** `wshobson/agents` contribution process centers on authoring plugin definition files (Markdown/YAML), not compiled code. The contribution workflow and quality gates are defined in the contributing guide and architecture documentation.
-This function is important because it defines how Wshobson Agents Tutorial: Pluginized Multi-Agent Workflows for Claude Code implements the patterns covered in this chapter.
-
-### `tools/yt-design-extractor.py`
-
-The `main` function in [`tools/yt-design-extractor.py`](https://github.com/wshobson/agents/blob/HEAD/tools/yt-design-extractor.py) handles a key part of this chapter's functionality:
-
-```py
-
-
-def main():
- parser = argparse.ArgumentParser(
- description="Extract design concepts from a YouTube video into a "
- "structured markdown reference document.",
- formatter_class=argparse.RawDescriptionHelpFormatter,
- epilog=textwrap.dedent("""\
- Examples:
- %(prog)s "https://youtu.be/eVnQFWGDEdY"
- %(prog)s "https://youtu.be/eVnQFWGDEdY" --full
- %(prog)s "https://youtu.be/eVnQFWGDEdY" --interval 15 --scene-detect --ocr
- %(prog)s "https://youtu.be/eVnQFWGDEdY" --ocr --ocr-engine easyocr --colors
- %(prog)s "https://youtu.be/eVnQFWGDEdY" -o ./my-output
- """),
- )
- parser.add_argument("url", help="YouTube video URL or ID")
- parser.add_argument(
- "-o",
- "--output-dir",
- help="Output directory (default: ./yt-extract-<video_id>)",
- )
- parser.add_argument(
- "--interval",
- type=int,
- default=30,
- help="Seconds between keyframe captures (default: 30)",
- )
- parser.add_argument(
- "--scene-detect",
- action="store_true",
- help="Also extract frames on scene changes (good for visual-heavy videos)",
-```
+### `.github/CONTRIBUTING.md`
+
+The [CONTRIBUTING.md](https://github.com/wshobson/agents/blob/main/.github/CONTRIBUTING.md) defines the end-to-end contribution flow: issue → feature branch → focused changes → updated docs → PR with rationale. This file is the authoritative reference for the Contribution Flow section of this chapter.
-This function is important because it defines how Wshobson Agents Tutorial: Pluginized Multi-Agent Workflows for Claude Code implements the patterns covered in this chapter.
+### `docs/architecture.md`
+The [architecture guide](https://github.com/wshobson/agents/blob/main/docs/architecture.md) specifies the plugin authoring heuristics this chapter covers: single plugin purpose, explicit naming, minimal overlap, and required usage examples. Reviewing this file before authoring a plugin prevents the most common quality pitfalls.
## How These Components Connect
```mermaid
flowchart TD
- A[build_markdown]
- B[main]
- A --> B
+ A[Identify issue or gap] --> B[Feature branch]
+ B -->|author new plugin| C[plugins/name/agents/ + commands/ + skills/]
+ C -->|follow| D[docs/architecture.md design principles]
+ D -->|single responsibility| E[Plugin quality check]
+ E -->|update docs| F[docs/plugins.md catalog entry]
+ F -->|PR with rationale| G[Review against .github/CONTRIBUTING.md]
+ G --> H[Merge]
```